From 7dd1237cf3c7293cebd04417a2ad4bba4c5ab4fe Mon Sep 17 00:00:00 2001 From: Yiran Date: Tue, 10 Dec 2024 18:41:27 +0800 Subject: [PATCH] docs: publish v0.11 (#1370) --- .../version-0.11.json | 190 + .../datanode/data-persistence-indexing.md | 86 + .../datanode/metric-engine.md | 41 + .../contributor-guide/datanode/overview.md | 27 + .../datanode/python-scripts.md | 29 + .../datanode/query-engine.md | 46 + .../datanode/storage-engine.md | 61 + .../contributor-guide/datanode/wal.md | 25 + .../contributor-guide/flownode/arrangement.md | 17 + .../contributor-guide/flownode/dataflow.md | 17 + .../contributor-guide/flownode/overview.md | 20 + .../frontend/distributed-querying.md | 39 + .../contributor-guide/frontend/overview.md | 18 + .../frontend/table-sharding.md | 52 + .../contributor-guide/getting-started.md | 69 + .../how-to/how-to-trace-greptimedb.md | 79 + .../how-to/how-to-use-tokio-console.md | 33 + .../how-to/how-to-write-sdk.md | 72 + .../contributor-guide/metasrv/admin-api.md | 297 + .../contributor-guide/metasrv/overview.md | 161 + .../contributor-guide/metasrv/selector.md | 46 + .../contributor-guide/overview.md | 49 + .../tests/integration-test.md | 13 + .../contributor-guide/tests/overview.md | 6 + .../contributor-guide/tests/sqlness-test.md | 49 + .../contributor-guide/tests/unit-test.md | 27 + .../clients/otlp-logs-integration.md | 22 + .../clients/otlp-metrics-integration.md | 18 + .../clients/vector-integration.md | 16 + .../migrate/_migrate-from-prometheus.md | 30 + .../migrate/migrate-from-influxdb.md | 257 + .../tutorials/monitor-host-metrics/go-demo.md | 58 + .../monitor-host-metrics/influxdb-demo.md | 57 + .../monitor-host-metrics/java-demo.md | 66 + .../monitor-host-metrics/mysql-demo.md | 67 + .../monitor-host-metrics/node-js-demo.md | 57 + .../monitor-host-metrics/overview.md | 4 + .../monitor-host-metrics/prometheus-demo.md | 62 + .../monitor-host-metrics/python-demo.md | 65 + ...olution-based-on-active-active-failover.md | 68 + .../disaster-recovery/overview.md | 11 + .../enterprise/autopilot/region-balancer.md | 38 + .../enterprise/deployments/audit-logging.md | 80 + .../enterprise/deployments/authentication.md | 82 + .../version-0.11/enterprise/overview.md | 29 + .../enterprise/release-notes/release-24_11.md | 54 + .../version-0.11/faq-and-others/faq.md | 214 + .../version-0.11/faq-and-others/overview.md | 3 + .../installation/greptimedb-cluster.md | 54 + .../installation/greptimedb-dashboard.md | 16 + .../installation/greptimedb-standalone.md | 132 + .../getting-started/installation/overview.md | 32 + .../version-0.11/getting-started/overview.md | 6 + .../getting-started/quick-start.md | 380 ++ .../getting-started/create-service.md | 0 .../greptimecloud/getting-started/go.md | 4 + .../greptimecloud/getting-started/influxdb.md | 4 + .../greptimecloud/getting-started/java.md | 4 + .../greptimecloud/getting-started/mysql.md | 4 + .../greptimecloud/getting-started/node.md | 4 + .../greptimecloud/getting-started/overview.md | 0 .../getting-started/prometheus.md | 4 + .../greptimecloud/getting-started/python.md | 4 + .../greptimecloud/getting-started/vector.md | 12 +- .../getting-started/visualize-data.md | 0 .../greptimecloud/integrations/alloy.md | 4 + .../greptimecloud/integrations/dbeaver.md | 4 + .../greptimecloud/integrations/grafana.md | 4 + .../greptimecloud/integrations/influxdb.md | 4 + .../greptimecloud/integrations/kafka.md | 4 + .../greptimecloud/integrations/metabase.md | 4 + .../greptimecloud/integrations/mindsdb.md | 4 + .../greptimecloud/integrations/mysql.md | 4 + .../greptimecloud/integrations/otlp.md | 4 + .../greptimecloud/integrations/postgresql.md | 19 + .../greptimecloud/integrations/prometheus.md | 4 + .../integrations/sdk-libraries/go.md | 4 + .../integrations/sdk-libraries/java.md | 4 + .../greptimecloud/integrations/streamlit.md | 4 + .../greptimecloud/integrations/superset.md | 4 + .../greptimecloud/integrations/vector.md | 5 + .../migrate-from-influxdb.md | 4 + .../migrate-from-prometheus.md | 4 + .../greptimecloud/overview.md | 0 .../tutorials/monitor-host-metrics/go.md | 4 + .../monitor-host-metrics/influxdb.md | 4 + .../tutorials/monitor-host-metrics/java.md | 4 + .../tutorials/monitor-host-metrics/mysql.md | 4 + .../tutorials/monitor-host-metrics/node-js.md | 4 + .../monitor-host-metrics/prometheus.md | 4 + .../tutorials/monitor-host-metrics/python.md | 4 + .../monitor-host-metrics/visualize-data.md | 0 .../greptimecloud/usage-&-billing/billing.md | 4 + .../usage-&-billing/dedicated.md | 4 + .../greptimecloud/usage-&-billing/hobby.md | 4 + .../greptimecloud/usage-&-billing/overview.md | 0 .../usage-&-billing/request-capacity-unit.md | 4 + .../usage-&-billing/serverless.md | 4 + .../shared-storage-capacity.md | 0 .../version-0.11/index.md | 39 + .../reference/about-greptimedb-version.md | 33 + .../version-0.11/reference/command-lines.md | 204 + .../version-0.11/reference/gtctl.md | 245 + .../version-0.11/reference/http-endpoints.md | 193 + .../version-0.11/reference/sql-tools.md | 289 + .../version-0.11/reference/sql/admin.md | 32 + .../version-0.11/reference/sql/alter.md | 183 + .../version-0.11/reference/sql/case.md | 93 + .../version-0.11/reference/sql/cast.md | 34 + .../reference/sql/compatibility.md | 24 + .../version-0.11/reference/sql/copy.md | 176 + .../version-0.11/reference/sql/create.md | 437 ++ .../version-0.11/reference/sql/data-types.md | 377 ++ .../version-0.11/reference/sql/delete.md | 29 + .../reference/sql/describe_table.md | 43 + .../version-0.11/reference/sql/distinct.md | 22 + .../version-0.11/reference/sql/drop.md | 93 + .../version-0.11/reference/sql/explain.md | 57 + .../reference/sql/functions/df-functions.md | 5036 +++++++++++++++++ .../reference/sql/functions/geo.md | 443 ++ .../reference/sql/functions/json.md | 124 + .../reference/sql/functions/overview.md | 236 + .../reference/sql/functions/vector.md | 106 + .../version-0.11/reference/sql/group_by.md | 72 + .../sql/information-schema/build-info.md | 31 + .../sql/information-schema/character-sets.md | 30 + .../sql/information-schema/cluster-info.md | 76 + .../collation-character-set-applicability.md | 28 + .../sql/information-schema/collations.md | 32 + .../sql/information-schema/columns.md | 180 + .../sql/information-schema/engines.md | 50 + .../reference/sql/information-schema/flows.md | 39 + .../information-schema/key-column-usage.md | 87 + .../sql/information-schema/overview.md | 61 + .../sql/information-schema/partitions.md | 163 + .../sql/information-schema/procedure-info.md | 36 + .../sql/information-schema/region-peers.md | 43 + .../information-schema/region-statistics.md | 66 + .../sql/information-schema/runtime-metrics.md | 57 + .../sql/information-schema/schemata.md | 51 + .../information-schema/table-constraints.md | 59 + .../sql/information-schema/tables.md | 113 + .../reference/sql/information-schema/views.md | 41 + .../version-0.11/reference/sql/insert.md | 133 + .../version-0.11/reference/sql/join.md | 39 + .../version-0.11/reference/sql/limit.md | 85 + .../version-0.11/reference/sql/order_by.md | 77 + .../version-0.11/reference/sql/overview.md | 28 + .../version-0.11/reference/sql/range.md | 602 ++ .../version-0.11/reference/sql/select.md | 127 + .../version-0.11/reference/sql/show.md | 385 ++ .../version-0.11/reference/sql/tql.md | 122 + .../version-0.11/reference/sql/truncate.md | 15 + .../version-0.11/reference/sql/where.md | 57 + .../version-0.11/reference/sql/with.md | 88 + .../version-0.11/reference/telemetry.md | 52 + .../administration/capacity-plan.md | 70 + .../back-up-&-restore-data.md | 157 + ...oss-region-deployment-in-single-cluster.md | 124 + .../dr-solution-for-standalone.md | 1 + .../disaster-recovery/overview.md | 146 + .../manage-data/basic-table-operations.md | 358 ++ .../administration/manage-data/compaction.md | 147 + .../administration/manage-data/overview.md | 14 + .../manage-data/region-failover.md | 85 + .../manage-data/region-migration.md | 81 + .../manage-data/table-sharding.md | 193 + .../monitoring/export-metrics.md | 161 + .../administration/monitoring/overview.md | 12 + .../administration/monitoring/tracing.md | 115 + .../user-guide/administration/overview.md | 18 + .../administration/performance-tuning-tips.md | 187 + .../remote-wal/cluster-deployment.md | 236 + .../administration/remote-wal/quick-start.md | 169 + .../user-guide/administration/runtime-info.md | 29 + .../user-guide/administration/upgrade.md | 183 + .../user-guide/concepts/architecture.md | 17 + .../user-guide/concepts/data-model.md | 84 + .../concepts/features-that-you-concern.md | 73 + .../user-guide/concepts/key-concepts.md | 50 + .../user-guide/concepts/overview.md | 21 + .../user-guide/concepts/storage-location.md | 44 + .../user-guide/concepts/why-greptimedb.md | 97 + .../continuous-aggregation/expression.md | 27 + .../continuous-aggregation/manage-flow.md | 220 + .../continuous-aggregation/overview.md | 151 + .../continuous-aggregation/usecase-example.md | 265 + .../deployments/authentication/overview.md | 12 + .../deployments/authentication/static.md | 27 + .../user-guide/deployments/configuration.md | 815 +++ .../deploy-on-kubernetes/getting-started.md | 555 ++ .../greptimedb-operator-management.md | 228 + .../deploy-on-kubernetes/overview.md | 19 + .../user-guide/deployments/overview.md | 34 + .../user-guide/deployments/run-on-android.md | 107 + .../user-guide/ingest-data/for-iot/emqx.md | 5 + .../ingest-data/for-iot/grpc-sdks/go.md | 262 + .../ingest-data/for-iot/grpc-sdks/java.md | 368 ++ .../ingest-data/for-iot/grpc-sdks/overview.md | 11 + .../ingest-data/for-iot/grpc-sdks/template.md | 103 + .../for-iot/influxdb-line-protocol.md | 205 + .../ingest-data/for-iot/opentsdb.md | 60 + .../ingest-data/for-iot/overview.md | 19 + .../user-guide/ingest-data/for-iot/sql.md | 118 + .../influxdb-line-protocol.md | 4 + .../ingest-data/for-observerbility/loki.md | 126 + .../for-observerbility/opentelemetry.md | 190 + .../for-observerbility/overview.md | 15 + .../for-observerbility/prometheus.md | 154 + .../ingest-data/for-observerbility/vector.md | 60 + .../user-guide/ingest-data/overview.md | 25 + .../user-guide/integrations/dbeaver.md | 26 + .../user-guide/integrations/emqx.md | 4 + .../user-guide/integrations/grafana.md | 134 + .../user-guide/integrations/metabase.md | 29 + .../user-guide/integrations/overview.md | 11 + .../user-guide/integrations/prometheus.md | 15 + .../user-guide/integrations/superset.md | 55 + .../user-guide/integrations/vector.md | 3 + .../user-guide/logs/manage-pipelines.md | 296 + .../version-0.11/user-guide/logs/overview.md | 7 + .../user-guide/logs/pipeline-config.md | 598 ++ .../user-guide/logs/query-logs.md | 144 + .../user-guide/logs/quick-start.md | 270 + .../user-guide/logs/write-logs.md | 112 + .../user-guide/manage-data/overview.md | 332 ++ .../migrate-from-influxdb.md | 194 + .../migrate-from-mysql.md | 87 + .../migrate-from-postgresql.md | 111 + .../migrate-from-prometheus.md | 29 + .../version-0.11/user-guide/overview.md | 73 + .../version-0.11/user-guide/protocols/grpc.md | 5 + .../version-0.11/user-guide/protocols/http.md | 552 ++ .../protocols/influxdb-line-protocol.md | 36 + .../user-guide/protocols/mysql.md | 77 + .../user-guide/protocols/opentelemetry.md | 4 + .../user-guide/protocols/opentsdb.md | 3 + .../user-guide/protocols/overview.md | 9 + .../user-guide/protocols/postgresql.md | 160 + .../user-guide/python-scripts/api.md | 93 + .../user-guide/python-scripts/data-types.md | 185 + .../python-scripts/define-function.md | 270 + .../python-scripts/getting-started.md | 193 + .../user-guide/python-scripts/overview.md | 31 + .../user-guide/python-scripts/query-data.md | 117 + .../user-guide/python-scripts/write-data.md | 38 + .../version-0.11/user-guide/query-data/cte.md | 167 + .../user-guide/query-data/overview.md | 26 + .../user-guide/query-data/promql.md | 248 + .../query-data/query-external-data.md | 123 + .../version-0.11/user-guide/query-data/sql.md | 465 ++ .../user-guide/query-data/view.md | 148 + .../version-0.11/user-guide/timezone.md | 48 + .../user-guide/vectors/vector-type.md | 98 + variables/variables-0.11.ts | 7 + variables/variables-nightly.ts | 2 +- versioned_docs/version-0.10/index.md | 2 - .../datanode/data-persistence-indexing.md | 83 + .../datanode/metric-engine.md | 43 + .../contributor-guide/datanode/overview.md | 33 + .../datanode/python-scripts.md | 34 + .../datanode/query-engine.md | 65 + .../datanode/storage-engine.md | 64 + .../contributor-guide/datanode/wal.md | 35 + .../contributor-guide/flownode/arrangement.md | 19 + .../contributor-guide/flownode/dataflow.md | 16 + .../contributor-guide/flownode/overview.md | 21 + .../frontend/distributed-querying.md | 32 + .../contributor-guide/frontend/overview.md | 25 + .../frontend/table-sharding.md | 54 + .../contributor-guide/getting-started.md | 69 + .../how-to/how-to-trace-greptimedb.md | 79 + .../how-to/how-to-use-tokio-console.md | 34 + .../how-to/how-to-write-sdk.md | 76 + .../contributor-guide/metasrv/admin-api.md | 297 + .../contributor-guide/metasrv/overview.md | 160 + .../contributor-guide/metasrv/selector.md | 46 + .../contributor-guide/overview.md | 70 + .../tests/integration-test.md | 12 + .../contributor-guide/tests/overview.md | 7 + .../contributor-guide/tests/sqlness-test.md | 60 + .../contributor-guide/tests/unit-test.md | 31 + .../clients/otlp-logs-integration.md | 22 + .../clients/otlp-metrics-integration.md | 18 + .../clients/vector-integration.md | 19 + .../migrate/_migrate-from-prometheus.md | 31 + .../migrate/migrate-from-influxdb.md | 257 + .../tutorials/monitor-host-metrics/go-demo.md | 58 + .../monitor-host-metrics/influxdb-demo.md | 57 + .../monitor-host-metrics/java-demo.md | 65 + .../monitor-host-metrics/mysql-demo.md | 69 + .../monitor-host-metrics/node-js-demo.md | 57 + .../monitor-host-metrics/overview.md | 6 + .../monitor-host-metrics/prometheus-demo.md | 62 + .../monitor-host-metrics/python-demo.md | 65 + ...olution-based-on-active-active-failover.md | 58 + .../disaster-recovery/overview.md | 13 + .../enterprise/autopilot/region-balancer.md | 38 + .../enterprise/deployments/audit-logging.md | 90 + .../enterprise/deployments/authentication.md | 88 + .../version-0.11/enterprise/overview.md | 30 + .../enterprise/release-notes/release-24_11.md | 59 + .../version-0.11/faq-and-others/faq.md | 219 + .../version-0.11/faq-and-others/overview.md | 3 + .../installation/greptimedb-cluster.md | 53 + .../installation/greptimedb-dashboard.md | 16 + .../installation/greptimedb-standalone.md | 131 + .../getting-started/installation/overview.md | 30 + .../version-0.11/getting-started/overview.md | 6 + .../getting-started/quick-start.md | 387 ++ .../getting-started/create-service.md | 0 .../greptimecloud/getting-started/go.md | 4 + .../greptimecloud/getting-started/influxdb.md | 4 + .../greptimecloud/getting-started/java.md | 4 + .../greptimecloud/getting-started/mysql.md | 4 + .../greptimecloud/getting-started/node.md | 4 + .../greptimecloud/getting-started/overview.md | 0 .../getting-started/prometheus.md | 4 + .../greptimecloud/getting-started/python.md | 4 + .../greptimecloud/getting-started/vector.md | 12 +- .../getting-started/visualize-data.md | 0 .../greptimecloud/greptimeai/langchain.md | 0 .../greptimecloud/greptimeai/openai.md | 0 .../greptimecloud/integrations/alloy.md | 4 + .../greptimecloud/integrations/dbeaver.md | 4 + .../greptimecloud/integrations/emqx.md | 4 + .../greptimecloud/integrations/grafana.md | 4 + .../greptimecloud/integrations/influxdb.md | 4 + .../greptimecloud/integrations/kafka.md | 4 + .../greptimecloud/integrations/metabase.md | 4 + .../greptimecloud/integrations/mindsdb.md | 4 + .../greptimecloud/integrations/mysql.md | 4 + .../greptimecloud/integrations/otlp.md | 4 + .../greptimecloud/integrations/postgresql.md | 19 + .../greptimecloud/integrations/prometheus.md | 4 + .../integrations/sdk-libraries/go.md | 4 + .../integrations/sdk-libraries/java.md | 4 + .../greptimecloud/integrations/streamlit.md | 4 + .../greptimecloud/integrations/superset.md | 4 + .../greptimecloud/integrations/vector.md | 5 + .../migrate-from-influxdb.md | 4 + .../migrate-from-prometheus.md | 4 + .../greptimecloud/overview.md | 4 + .../tutorials/monitor-host-metrics/go.md | 4 + .../monitor-host-metrics/influxdb.md | 4 + .../tutorials/monitor-host-metrics/java.md | 4 + .../tutorials/monitor-host-metrics/mysql.md | 4 + .../tutorials/monitor-host-metrics/node-js.md | 4 + .../monitor-host-metrics/prometheus.md | 4 + .../tutorials/monitor-host-metrics/python.md | 0 .../monitor-host-metrics/visualize-data.md | 0 .../greptimecloud/usage-&-billing/billing.md | 4 + .../usage-&-billing/dedicated.md | 4 + .../greptimecloud/usage-&-billing/hobby.md | 4 + .../greptimecloud/usage-&-billing/overview.md | 4 + .../usage-&-billing/request-capacity-unit.md | 4 + .../usage-&-billing/serverless.md | 4 + .../shared-storage-capacity.md | 0 versioned_docs/version-0.11/index.md | 42 + .../reference/about-greptimedb-version.md | 30 + .../version-0.11/reference/command-lines.md | 205 + .../version-0.11/reference/gtctl.md | 245 + .../version-0.11/reference/http-endpoints.md | 193 + .../version-0.11/reference/sql-tools.md | 289 + .../version-0.11/reference/sql/admin.md | 33 + .../version-0.11/reference/sql/alter.md | 180 + .../version-0.11/reference/sql/case.md | 95 + .../version-0.11/reference/sql/cast.md | 34 + .../reference/sql/compatibility.md | 24 + .../version-0.11/reference/sql/copy.md | 182 + .../version-0.11/reference/sql/create.md | 432 ++ .../version-0.11/reference/sql/data-types.md | 376 ++ .../version-0.11/reference/sql/delete.md | 29 + .../reference/sql/describe_table.md | 44 + .../version-0.11/reference/sql/distinct.md | 25 + .../version-0.11/reference/sql/drop.md | 96 + .../version-0.11/reference/sql/explain.md | 59 + .../reference/sql/functions/df-functions.md | 5036 +++++++++++++++++ .../reference/sql/functions/geo.md | 455 ++ .../reference/sql/functions/json.md | 124 + .../reference/sql/functions/overview.md | 244 + .../reference/sql/functions/vector.md | 114 + .../version-0.11/reference/sql/group_by.md | 73 + .../sql/information-schema/build-info.md | 32 + .../sql/information-schema/character-sets.md | 30 + .../sql/information-schema/cluster-info.md | 75 + .../collation-character-set-applicability.md | 28 + .../sql/information-schema/collations.md | 32 + .../sql/information-schema/columns.md | 178 + .../sql/information-schema/engines.md | 49 + .../reference/sql/information-schema/flows.md | 39 + .../information-schema/key-column-usage.md | 87 + .../sql/information-schema/overview.md | 63 + .../sql/information-schema/partitions.md | 163 + .../sql/information-schema/procedure-info.md | 36 + .../sql/information-schema/region-peers.md | 43 + .../information-schema/region-statistics.md | 68 + .../sql/information-schema/runtime-metrics.md | 58 + .../sql/information-schema/schemata.md | 51 + .../information-schema/table-constraints.md | 59 + .../sql/information-schema/tables.md | 110 + .../reference/sql/information-schema/views.md | 41 + .../version-0.11/reference/sql/insert.md | 142 + .../version-0.11/reference/sql/join.md | 39 + .../version-0.11/reference/sql/limit.md | 88 + .../version-0.11/reference/sql/order_by.md | 79 + .../version-0.11/reference/sql/overview.md | 28 + .../version-0.11/reference/sql/range.md | 611 ++ .../version-0.11/reference/sql/select.md | 137 + .../version-0.11/reference/sql/show.md | 384 ++ .../version-0.11/reference/sql/tql.md | 122 + .../version-0.11/reference/sql/truncate.md | 16 + .../version-0.11/reference/sql/where.md | 59 + .../version-0.11/reference/sql/with.md | 88 + .../version-0.11/reference/telemetry.md | 52 + .../administration/capacity-plan.md | 71 + .../back-up-&-restore-data.md | 150 + ...oss-region-deployment-in-single-cluster.md | 125 + .../dr-solution-for-standalone.md | 1 + .../disaster-recovery/overview.md | 129 + .../manage-data/basic-table-operations.md | 363 ++ .../administration/manage-data/compaction.md | 148 + .../administration/manage-data/overview.md | 14 + .../manage-data/region-failover.md | 85 + .../manage-data/region-migration.md | 83 + .../manage-data/table-sharding.md | 188 + .../monitoring/export-metrics.md | 162 + .../administration/monitoring/overview.md | 12 + .../administration/monitoring/tracing.md | 115 + .../user-guide/administration/overview.md | 18 + .../administration/performance-tuning-tips.md | 187 + .../remote-wal/cluster-deployment.md | 233 + .../administration/remote-wal/quick-start.md | 172 + .../user-guide/administration/runtime-info.md | 30 + .../user-guide/administration/upgrade.md | 181 + .../user-guide/concepts/architecture.md | 29 + .../user-guide/concepts/data-model.md | 102 + .../concepts/features-that-you-concern.md | 72 + .../user-guide/concepts/key-concepts.md | 55 + .../user-guide/concepts/overview.md | 21 + .../user-guide/concepts/storage-location.md | 44 + .../user-guide/concepts/why-greptimedb.md | 93 + .../continuous-aggregation/expression.md | 27 + .../continuous-aggregation/manage-flow.md | 236 + .../continuous-aggregation/overview.md | 150 + .../continuous-aggregation/usecase-example.md | 258 + .../deployments/authentication/overview.md | 14 + .../deployments/authentication/static.md | 25 + .../user-guide/deployments/configuration.md | 846 +++ .../deploy-on-kubernetes/getting-started.md | 499 ++ .../greptimedb-operator-management.md | 224 + .../deploy-on-kubernetes/overview.md | 20 + .../user-guide/deployments/overview.md | 32 + .../user-guide/deployments/run-on-android.md | 103 + .../user-guide/ingest-data/for-iot/emqx.md | 9 + .../ingest-data/for-iot/grpc-sdks/go.md | 285 + .../ingest-data/for-iot/grpc-sdks/java.md | 377 ++ .../ingest-data/for-iot/grpc-sdks/overview.md | 10 + .../ingest-data/for-iot/grpc-sdks/template.md | 104 + .../for-iot/influxdb-line-protocol.md | 206 + .../ingest-data/for-iot/opentsdb.md | 60 + .../ingest-data/for-iot/overview.md | 20 + .../user-guide/ingest-data/for-iot/sql.md | 120 + .../influxdb-line-protocol.md | 4 + .../ingest-data/for-observerbility/loki.md | 127 + .../for-observerbility/opentelemetry.md | 190 + .../for-observerbility/overview.md | 15 + .../for-observerbility/prometheus.md | 163 + .../ingest-data/for-observerbility/vector.md | 58 + .../user-guide/ingest-data/overview.md | 25 + .../user-guide/integrations/dbeaver.md | 25 + .../user-guide/integrations/emqx.md | 4 + .../user-guide/integrations/grafana.md | 134 + .../user-guide/integrations/metabase.md | 32 + .../user-guide/integrations/overview.md | 15 + .../user-guide/integrations/prometheus.md | 17 + .../user-guide/integrations/superset.md | 57 + .../user-guide/integrations/vector.md | 3 + .../user-guide/logs/manage-pipelines.md | 299 + .../version-0.11/user-guide/logs/overview.md | 11 + .../user-guide/logs/pipeline-config.md | 579 ++ .../user-guide/logs/query-logs.md | 144 + .../user-guide/logs/quick-start.md | 278 + .../user-guide/logs/write-logs.md | 111 + .../user-guide/manage-data/overview.md | 336 ++ .../migrate-from-influxdb.md | 191 + .../migrate-from-mysql.md | 100 + .../migrate-from-postgresql.md | 132 + .../migrate-from-prometheus.md | 30 + .../version-0.11/user-guide/overview.md | 74 + .../version-0.11/user-guide/protocols/grpc.md | 9 + .../version-0.11/user-guide/protocols/http.md | 526 ++ .../protocols/influxdb-line-protocol.md | 37 + .../user-guide/protocols/mysql.md | 81 + .../user-guide/protocols/opentelemetry.md | 4 + .../user-guide/protocols/opentsdb.md | 3 + .../user-guide/protocols/overview.md | 9 + .../user-guide/protocols/postgresql.md | 164 + .../user-guide/python-scripts/api.md | 93 + .../user-guide/python-scripts/data-types.md | 184 + .../python-scripts/define-function.md | 267 + .../python-scripts/getting-started.md | 191 + .../user-guide/python-scripts/overview.md | 29 + .../user-guide/python-scripts/query-data.md | 117 + .../user-guide/python-scripts/write-data.md | 39 + .../version-0.11/user-guide/query-data/cte.md | 167 + .../user-guide/query-data/overview.md | 26 + .../user-guide/query-data/promql.md | 250 + .../query-data/query-external-data.md | 123 + .../version-0.11/user-guide/query-data/sql.md | 486 ++ .../user-guide/query-data/view.md | 146 + .../version-0.11/user-guide/timezone.md | 49 + .../user-guide/vectors/vector-type.md | 98 + versioned_sidebars/version-0.10-sidebars.json | 90 - versioned_sidebars/version-0.11-sidebars.json | 545 ++ versions.json | 1 + 516 files changed, 56789 insertions(+), 99 deletions(-) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11.json create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/data-persistence-indexing.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/metric-engine.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/python-scripts.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/query-engine.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/storage-engine.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/wal.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/arrangement.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/dataflow.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/distributed-querying.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/table-sharding.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/getting-started.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-trace-greptimedb.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-use-tokio-console.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-write-sdk.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/admin-api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/selector.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/integration-test.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/sqlness-test.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/unit-test.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/otlp-logs-integration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/otlp-metrics-integration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/vector-integration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/migrate/_migrate-from-prometheus.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/migrate/migrate-from-influxdb.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/go-demo.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/influxdb-demo.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/java-demo.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/mysql-demo.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/node-js-demo.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/prometheus-demo.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/python-demo.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/administration/disaster-recovery/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/autopilot/region-balancer.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/deployments/audit-logging.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/deployments/authentication.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/release-notes/release-24_11.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/faq-and-others/faq.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/faq-and-others/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-cluster.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-dashboard.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-standalone.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/quick-start.md rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/create-service.md (100%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/go.md (83%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/influxdb.md (85%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/java.md (84%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/mysql.md (86%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/node.md (83%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/overview.md (100%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/prometheus.md (86%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/python.md (85%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/vector.md (66%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/visualize-data.md (100%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/alloy.md (84%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/dbeaver.md (87%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/grafana.md (92%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/influxdb.md (88%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/kafka.md (90%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/metabase.md (80%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/mindsdb.md (84%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/mysql.md (87%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/otlp.md (91%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/postgresql.md (70%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/prometheus.md (89%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/sdk-libraries/go.md (82%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/sdk-libraries/java.md (83%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/streamlit.md (84%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/superset.md (77%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/integrations/vector.md (89%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md (96%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md (81%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/overview.md (100%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/go.md (82%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/influxdb.md (81%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/java.md (82%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/mysql.md (82%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/node-js.md (82%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/prometheus.md (82%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/python.md (82%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md (100%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/billing.md (92%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/dedicated.md (92%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/hobby.md (91%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/overview.md (100%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/request-capacity-unit.md (97%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/serverless.md (93%) rename i18n/zh/docusaurus-plugin-content-docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/shared-storage-capacity.md (100%) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/index.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/about-greptimedb-version.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/command-lines.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/gtctl.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/http-endpoints.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql-tools.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/admin.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/alter.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/case.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/cast.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/compatibility.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/copy.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/create.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/data-types.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/delete.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/describe_table.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/distinct.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/drop.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/explain.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/df-functions.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/geo.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/json.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/vector.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/group_by.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/build-info.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/character-sets.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/cluster-info.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/collation-character-set-applicability.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/collations.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/columns.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/engines.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/flows.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/key-column-usage.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/partitions.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/procedure-info.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/region-peers.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/region-statistics.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/runtime-metrics.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/schemata.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/table-constraints.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/tables.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/views.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/insert.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/join.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/limit.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/order_by.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/range.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/select.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/show.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/tql.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/truncate.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/where.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/with.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/telemetry.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/capacity-plan.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/back-up-&-restore-data.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-for-standalone.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/basic-table-operations.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/compaction.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/region-failover.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/region-migration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/table-sharding.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/export-metrics.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/tracing.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/performance-tuning-tips.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/remote-wal/cluster-deployment.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/remote-wal/quick-start.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/runtime-info.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/upgrade.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/architecture.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/data-model.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/features-that-you-concern.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/key-concepts.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/storage-location.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/why-greptimedb.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/expression.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/manage-flow.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/usecase-example.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/authentication/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/authentication/static.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/configuration.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/getting-started.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/run-on-android.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/emqx.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/go.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/java.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/template.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/influxdb-line-protocol.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/opentsdb.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/sql.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/influxdb-line-protocol.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/loki.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/opentelemetry.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/prometheus.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/vector.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/dbeaver.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/emqx.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/grafana.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/metabase.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/prometheus.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/superset.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/vector.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/manage-pipelines.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/pipeline-config.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/query-logs.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/quick-start.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/write-logs.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/manage-data/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-mysql.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-postgresql.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-prometheus.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/grpc.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/http.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/influxdb-line-protocol.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/mysql.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/opentelemetry.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/opentsdb.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/postgresql.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/data-types.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/define-function.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/getting-started.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/query-data.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/write-data.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/cte.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/overview.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/promql.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/query-external-data.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/sql.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/view.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/timezone.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/vectors/vector-type.md create mode 100644 variables/variables-0.11.ts create mode 100644 versioned_docs/version-0.11/contributor-guide/datanode/data-persistence-indexing.md create mode 100644 versioned_docs/version-0.11/contributor-guide/datanode/metric-engine.md create mode 100644 versioned_docs/version-0.11/contributor-guide/datanode/overview.md create mode 100644 versioned_docs/version-0.11/contributor-guide/datanode/python-scripts.md create mode 100644 versioned_docs/version-0.11/contributor-guide/datanode/query-engine.md create mode 100644 versioned_docs/version-0.11/contributor-guide/datanode/storage-engine.md create mode 100644 versioned_docs/version-0.11/contributor-guide/datanode/wal.md create mode 100644 versioned_docs/version-0.11/contributor-guide/flownode/arrangement.md create mode 100644 versioned_docs/version-0.11/contributor-guide/flownode/dataflow.md create mode 100644 versioned_docs/version-0.11/contributor-guide/flownode/overview.md create mode 100644 versioned_docs/version-0.11/contributor-guide/frontend/distributed-querying.md create mode 100644 versioned_docs/version-0.11/contributor-guide/frontend/overview.md create mode 100644 versioned_docs/version-0.11/contributor-guide/frontend/table-sharding.md create mode 100644 versioned_docs/version-0.11/contributor-guide/getting-started.md create mode 100644 versioned_docs/version-0.11/contributor-guide/how-to/how-to-trace-greptimedb.md create mode 100644 versioned_docs/version-0.11/contributor-guide/how-to/how-to-use-tokio-console.md create mode 100644 versioned_docs/version-0.11/contributor-guide/how-to/how-to-write-sdk.md create mode 100644 versioned_docs/version-0.11/contributor-guide/metasrv/admin-api.md create mode 100644 versioned_docs/version-0.11/contributor-guide/metasrv/overview.md create mode 100644 versioned_docs/version-0.11/contributor-guide/metasrv/selector.md create mode 100644 versioned_docs/version-0.11/contributor-guide/overview.md create mode 100644 versioned_docs/version-0.11/contributor-guide/tests/integration-test.md create mode 100644 versioned_docs/version-0.11/contributor-guide/tests/overview.md create mode 100644 versioned_docs/version-0.11/contributor-guide/tests/sqlness-test.md create mode 100644 versioned_docs/version-0.11/contributor-guide/tests/unit-test.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/clients/otlp-logs-integration.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/clients/otlp-metrics-integration.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/clients/vector-integration.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/migrate/_migrate-from-prometheus.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/migrate/migrate-from-influxdb.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/go-demo.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/influxdb-demo.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/java-demo.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/mysql-demo.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/node-js-demo.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/overview.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/prometheus-demo.md create mode 100644 versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/python-demo.md create mode 100644 versioned_docs/version-0.11/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md create mode 100644 versioned_docs/version-0.11/enterprise/administration/disaster-recovery/overview.md create mode 100644 versioned_docs/version-0.11/enterprise/autopilot/region-balancer.md create mode 100644 versioned_docs/version-0.11/enterprise/deployments/audit-logging.md create mode 100644 versioned_docs/version-0.11/enterprise/deployments/authentication.md create mode 100644 versioned_docs/version-0.11/enterprise/overview.md create mode 100644 versioned_docs/version-0.11/enterprise/release-notes/release-24_11.md create mode 100644 versioned_docs/version-0.11/faq-and-others/faq.md create mode 100644 versioned_docs/version-0.11/faq-and-others/overview.md create mode 100644 versioned_docs/version-0.11/getting-started/installation/greptimedb-cluster.md create mode 100644 versioned_docs/version-0.11/getting-started/installation/greptimedb-dashboard.md create mode 100644 versioned_docs/version-0.11/getting-started/installation/greptimedb-standalone.md create mode 100644 versioned_docs/version-0.11/getting-started/installation/overview.md create mode 100644 versioned_docs/version-0.11/getting-started/overview.md create mode 100644 versioned_docs/version-0.11/getting-started/quick-start.md rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/create-service.md (100%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/go.md (84%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/influxdb.md (84%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/java.md (86%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/mysql.md (84%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/node.md (84%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/overview.md (100%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/prometheus.md (88%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/python.md (86%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/vector.md (69%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/getting-started/visualize-data.md (100%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/greptimeai/langchain.md (100%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/greptimeai/openai.md (100%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/alloy.md (88%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/dbeaver.md (90%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/emqx.md (89%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/grafana.md (93%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/influxdb.md (91%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/kafka.md (92%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/metabase.md (79%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/mindsdb.md (86%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/mysql.md (88%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/otlp.md (93%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/postgresql.md (70%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/prometheus.md (91%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/sdk-libraries/go.md (86%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/sdk-libraries/java.md (87%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/streamlit.md (82%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/superset.md (76%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/integrations/vector.md (86%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md (96%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md (82%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/overview.md (61%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/go.md (82%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/influxdb.md (81%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/java.md (82%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/mysql.md (82%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/node-js.md (82%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/prometheus.md (82%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/python.md (100%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md (100%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/billing.md (90%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/dedicated.md (89%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/hobby.md (87%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/overview.md (58%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/request-capacity-unit.md (97%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/serverless.md (92%) rename versioned_docs/{version-0.10 => version-0.11}/greptimecloud/usage-&-billing/shared-storage-capacity.md (100%) create mode 100644 versioned_docs/version-0.11/index.md create mode 100644 versioned_docs/version-0.11/reference/about-greptimedb-version.md create mode 100644 versioned_docs/version-0.11/reference/command-lines.md create mode 100644 versioned_docs/version-0.11/reference/gtctl.md create mode 100644 versioned_docs/version-0.11/reference/http-endpoints.md create mode 100644 versioned_docs/version-0.11/reference/sql-tools.md create mode 100644 versioned_docs/version-0.11/reference/sql/admin.md create mode 100644 versioned_docs/version-0.11/reference/sql/alter.md create mode 100644 versioned_docs/version-0.11/reference/sql/case.md create mode 100644 versioned_docs/version-0.11/reference/sql/cast.md create mode 100644 versioned_docs/version-0.11/reference/sql/compatibility.md create mode 100644 versioned_docs/version-0.11/reference/sql/copy.md create mode 100644 versioned_docs/version-0.11/reference/sql/create.md create mode 100644 versioned_docs/version-0.11/reference/sql/data-types.md create mode 100644 versioned_docs/version-0.11/reference/sql/delete.md create mode 100644 versioned_docs/version-0.11/reference/sql/describe_table.md create mode 100644 versioned_docs/version-0.11/reference/sql/distinct.md create mode 100644 versioned_docs/version-0.11/reference/sql/drop.md create mode 100644 versioned_docs/version-0.11/reference/sql/explain.md create mode 100644 versioned_docs/version-0.11/reference/sql/functions/df-functions.md create mode 100644 versioned_docs/version-0.11/reference/sql/functions/geo.md create mode 100644 versioned_docs/version-0.11/reference/sql/functions/json.md create mode 100644 versioned_docs/version-0.11/reference/sql/functions/overview.md create mode 100644 versioned_docs/version-0.11/reference/sql/functions/vector.md create mode 100644 versioned_docs/version-0.11/reference/sql/group_by.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/build-info.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/character-sets.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/cluster-info.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/collation-character-set-applicability.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/collations.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/columns.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/engines.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/flows.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/key-column-usage.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/overview.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/partitions.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/procedure-info.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/region-peers.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/region-statistics.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/runtime-metrics.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/schemata.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/table-constraints.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/tables.md create mode 100644 versioned_docs/version-0.11/reference/sql/information-schema/views.md create mode 100644 versioned_docs/version-0.11/reference/sql/insert.md create mode 100644 versioned_docs/version-0.11/reference/sql/join.md create mode 100644 versioned_docs/version-0.11/reference/sql/limit.md create mode 100644 versioned_docs/version-0.11/reference/sql/order_by.md create mode 100644 versioned_docs/version-0.11/reference/sql/overview.md create mode 100644 versioned_docs/version-0.11/reference/sql/range.md create mode 100644 versioned_docs/version-0.11/reference/sql/select.md create mode 100644 versioned_docs/version-0.11/reference/sql/show.md create mode 100644 versioned_docs/version-0.11/reference/sql/tql.md create mode 100644 versioned_docs/version-0.11/reference/sql/truncate.md create mode 100644 versioned_docs/version-0.11/reference/sql/where.md create mode 100644 versioned_docs/version-0.11/reference/sql/with.md create mode 100644 versioned_docs/version-0.11/reference/telemetry.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/capacity-plan.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/disaster-recovery/back-up-&-restore-data.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-for-standalone.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/disaster-recovery/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/manage-data/basic-table-operations.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/manage-data/compaction.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/manage-data/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/manage-data/region-failover.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/manage-data/region-migration.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/manage-data/table-sharding.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/monitoring/export-metrics.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/monitoring/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/monitoring/tracing.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/performance-tuning-tips.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/remote-wal/cluster-deployment.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/remote-wal/quick-start.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/runtime-info.md create mode 100644 versioned_docs/version-0.11/user-guide/administration/upgrade.md create mode 100644 versioned_docs/version-0.11/user-guide/concepts/architecture.md create mode 100644 versioned_docs/version-0.11/user-guide/concepts/data-model.md create mode 100644 versioned_docs/version-0.11/user-guide/concepts/features-that-you-concern.md create mode 100644 versioned_docs/version-0.11/user-guide/concepts/key-concepts.md create mode 100644 versioned_docs/version-0.11/user-guide/concepts/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/concepts/storage-location.md create mode 100644 versioned_docs/version-0.11/user-guide/concepts/why-greptimedb.md create mode 100644 versioned_docs/version-0.11/user-guide/continuous-aggregation/expression.md create mode 100644 versioned_docs/version-0.11/user-guide/continuous-aggregation/manage-flow.md create mode 100644 versioned_docs/version-0.11/user-guide/continuous-aggregation/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/continuous-aggregation/usecase-example.md create mode 100644 versioned_docs/version-0.11/user-guide/deployments/authentication/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/deployments/authentication/static.md create mode 100644 versioned_docs/version-0.11/user-guide/deployments/configuration.md create mode 100644 versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/getting-started.md create mode 100644 versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management.md create mode 100644 versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/deployments/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/deployments/run-on-android.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/emqx.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/go.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/java.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/template.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/influxdb-line-protocol.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/opentsdb.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-iot/sql.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/influxdb-line-protocol.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/loki.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/opentelemetry.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/prometheus.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/vector.md create mode 100644 versioned_docs/version-0.11/user-guide/ingest-data/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/integrations/dbeaver.md create mode 100644 versioned_docs/version-0.11/user-guide/integrations/emqx.md create mode 100644 versioned_docs/version-0.11/user-guide/integrations/grafana.md create mode 100644 versioned_docs/version-0.11/user-guide/integrations/metabase.md create mode 100644 versioned_docs/version-0.11/user-guide/integrations/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/integrations/prometheus.md create mode 100644 versioned_docs/version-0.11/user-guide/integrations/superset.md create mode 100644 versioned_docs/version-0.11/user-guide/integrations/vector.md create mode 100644 versioned_docs/version-0.11/user-guide/logs/manage-pipelines.md create mode 100644 versioned_docs/version-0.11/user-guide/logs/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/logs/pipeline-config.md create mode 100644 versioned_docs/version-0.11/user-guide/logs/query-logs.md create mode 100644 versioned_docs/version-0.11/user-guide/logs/quick-start.md create mode 100644 versioned_docs/version-0.11/user-guide/logs/write-logs.md create mode 100644 versioned_docs/version-0.11/user-guide/manage-data/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md create mode 100644 versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-mysql.md create mode 100644 versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-postgresql.md create mode 100644 versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-prometheus.md create mode 100644 versioned_docs/version-0.11/user-guide/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/protocols/grpc.md create mode 100644 versioned_docs/version-0.11/user-guide/protocols/http.md create mode 100644 versioned_docs/version-0.11/user-guide/protocols/influxdb-line-protocol.md create mode 100644 versioned_docs/version-0.11/user-guide/protocols/mysql.md create mode 100644 versioned_docs/version-0.11/user-guide/protocols/opentelemetry.md create mode 100644 versioned_docs/version-0.11/user-guide/protocols/opentsdb.md create mode 100644 versioned_docs/version-0.11/user-guide/protocols/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/protocols/postgresql.md create mode 100644 versioned_docs/version-0.11/user-guide/python-scripts/api.md create mode 100644 versioned_docs/version-0.11/user-guide/python-scripts/data-types.md create mode 100644 versioned_docs/version-0.11/user-guide/python-scripts/define-function.md create mode 100644 versioned_docs/version-0.11/user-guide/python-scripts/getting-started.md create mode 100644 versioned_docs/version-0.11/user-guide/python-scripts/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/python-scripts/query-data.md create mode 100644 versioned_docs/version-0.11/user-guide/python-scripts/write-data.md create mode 100644 versioned_docs/version-0.11/user-guide/query-data/cte.md create mode 100644 versioned_docs/version-0.11/user-guide/query-data/overview.md create mode 100644 versioned_docs/version-0.11/user-guide/query-data/promql.md create mode 100644 versioned_docs/version-0.11/user-guide/query-data/query-external-data.md create mode 100644 versioned_docs/version-0.11/user-guide/query-data/sql.md create mode 100644 versioned_docs/version-0.11/user-guide/query-data/view.md create mode 100644 versioned_docs/version-0.11/user-guide/timezone.md create mode 100644 versioned_docs/version-0.11/user-guide/vectors/vector-type.md create mode 100644 versioned_sidebars/version-0.11-sidebars.json diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11.json b/i18n/zh/docusaurus-plugin-content-docs/version-0.11.json new file mode 100644 index 000000000..056c19ee9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11.json @@ -0,0 +1,190 @@ +{ + "sidebar.docs.category.Getting Started": { + "message": "立即开始", + "description": "The label for category Getting Started in sidebar docs" + }, + "sidebar.docs.category.Installation": { + "message": "安装", + "description": "The label for category Installation in sidebar docs" + }, + "sidebar.docs.category.User Guide": { + "message": "用户指南", + "description": "The label for category User Guide in sidebar docs" + }, + "sidebar.docs.category.Concepts": { + "message": "概念", + "description": "The label for category Concepts in sidebar docs" + }, + "sidebar.docs.category.Migrate to GreptimeDB": { + "message": "迁移到 GreptimeDB", + "description": "The label for category Migrate to GreptimeDB in sidebar docs" + }, + "sidebar.docs.category.Write Data": { + "message": "写入数据", + "description": "The label for category Write Data in sidebar docs" + }, + "sidebar.docs.category.Query Data": { + "message": "读取数据", + "description": "The label for category Query Data in sidebar docs" + }, + "sidebar.docs.category.Continuous Aggregation": { + "message": "持续聚合", + "description": "The label for category Continuous Aggregation in sidebar docs" + }, + "sidebar.docs.category.Logs": { + "message": "日志", + "description": "The label for category Logs in sidebar docs" + }, + "sidebar.docs.category.Client Libraries": { + "message": "客户端库", + "description": "The label for category Client Libraries in sidebar docs" + }, + "sidebar.docs.category.Administration": { + "message": "管理", + "description": "The label for category Operations in sidebar docs" + }, + "sidebar.docs.category.Authentication": { + "message": "鉴权", + "description": "The label for category Authentication in sidebar docs" + }, + "sidebar.docs.category.Deployments": { + "message": "部署", + "description": "The label for category Deployments in sidebar docs" + }, + "sidebar.docs.category.Deploy on Kubernetes": { + "message": "部署到 Kubernetes", + "description": "The label for category Deploy on Kubernetes in sidebar docs" + }, + "sidebar.docs.category.Manage GreptimeDB Operator": { + "message": "管理 GreptimeDB Operator", + "description": "The label for category Deploy on Kubernetes in sidebar docs" + }, + "sidebar.docs.category.Disaster Recovery": { + "message": "灾难恢复", + "description": "The label for category Disaster Recovery in sidebar docs" + }, + "sidebar.docs.category.Remote WAL": { + "message": "Remote WAL", + "description": "The label for category Remote WAL in sidebar docs" + }, + "sidebar.docs.category.GreptimeCloud": { + "message": "GreptimeCloud", + "description": "The label for category GreptimeCloud in sidebar docs" + }, + "sidebar.docs.category.Integrations": { + "message": "集成", + "description": "The label for category Integrations in sidebar docs" + }, + "sidebar.docs.category.Prometheus": { + "message": "Prometheus", + "description": "The label for category Prometheus in sidebar docs" + }, + "sidebar.docs.category.SDK Libraries": { + "message": "SDK Libraries", + "description": "The label for category SDK Libraries in sidebar docs" + }, + "sidebar.docs.category.Migrate to GreptimeCloud": { + "message": "迁移到 GreptimeCloud", + "description": "The label for category Migrate to GreptimeCloud in sidebar docs" + }, + "sidebar.docs.category.Usage & Billing": { + "message": "用量及费用", + "description": "The label for category Usage & Billing in sidebar docs" + }, + "sidebar.docs.category.Tutorials": { + "message": "教程", + "description": "The label for category Tutorials in sidebar docs" + }, + "sidebar.docs.category.Monitor Host Metrics": { + "message": "监控 Host Metrics", + "description": "The label for category Monitor Host Metrics in sidebar docs" + }, + "sidebar.docs.category.GreptimeDB Enterprise": { + "message": "GreptimeDB 企业版", + "description": "The label for category GreptimeDB Enterprise in sidebar docs" + }, + "sidebar.docs.category.Reference": { + "message": "Reference", + "description": "The label for category Reference in sidebar docs" + }, + "sidebar.docs.category.SQL": { + "message": "SQL", + "description": "The label for category SQL in sidebar docs" + }, + "sidebar.docs.category.Functions": { + "message": "Functions", + "description": "The label for category Functions in sidebar docs" + }, + "sidebar.docs.category.Information Schema": { + "message": "Information Schema", + "description": "The label for category Information Schema in sidebar docs" + }, + "sidebar.docs.category.Contributor Guide": { + "message": "贡献者指南", + "description": "The label for category Contributor Guide in sidebar docs" + }, + "sidebar.docs.category.Frontend": { + "message": "Frontend", + "description": "The label for category Frontend in sidebar docs" + }, + "sidebar.docs.category.Datanode": { + "message": "Datanode", + "description": "The label for category Datanode in sidebar docs" + }, + "sidebar.docs.category.Metasrv": { + "message": "Metasrv", + "description": "The label for category Metasrv in sidebar docs" + }, + "sidebar.docs.category.Flownode": { + "message": "Flownode", + "description": "The label for category Flownode in sidebar docs" + }, + "sidebar.docs.category.Tests": { + "message": "测试", + "description": "The label for category Tests in sidebar docs" + }, + "sidebar.docs.category.How To": { + "message": "指南", + "description": "The label for category How To in sidebar docs" + }, + "sidebar.docs.category.FAQ and Others": { + "message": "常见问题及其他", + "description": "The label for category FAQ and Others in sidebar docs" + }, + "sidebar.docs.link.Release Notes": { + "message": "Release Notes", + "description": "The label for link Release Notes in sidebar docs, linking to /release-notes" + }, + "sidebar.docs.category.Ingest Data": { + "message": "写入数据", + "description": "The label for category Ingest Data in sidebar docs" + }, + "sidebar.docs.category.For Observerbility": { + "message": "可观测场景", + "description": "The label for category For Observerbility in sidebar docs" + }, + "sidebar.docs.category.For IoT": { + "message": "物联网（IoT）场景", + "description": "The label for category For IoT in sidebar docs" + }, + "sidebar.docs.category.gRPC SDKs": { + "message": "gRPC SDKs", + "description": "The label for category gRPC SDKs in sidebar docs" + }, + "sidebar.docs.category.Manage Data": { + "message": "管理数据", + "description": "The label for category Manage Data in sidebar docs" + }, + "sidebar.docs.category.Protocols": { + "message": "协议", + "description": "The label for category Manage Data in sidebar docs" + }, + "sidebar.docs.category.Monitoring": { + "message": "监控", + "description": "The label for category Monitoring in sidebar docs" + }, + "sidebar.docs.category.Vector Storage": { + "message": "向量存储", + "description": "The label for category Vector Storage in sidebar docs" + } +} diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/data-persistence-indexing.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/data-persistence-indexing.md new file mode 100644 index 000000000..cd80076f1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/data-persistence-indexing.md @@ -0,0 +1,86 @@ +--- +description: 介绍了 GreptimeDB 的数据持久化和索引机制，包括 SST 文件格式、数据持久化过程和倒排索引的实现。 +--- + +# 数据持久化与索引 + +与所有类似 LSMT 的存储引擎一样，MemTables 中的数据被持久化到耐久性存储，例如本地磁盘文件系统或对象存储服务。GreptimeDB 采用 [Apache Parquet][1] 作为其持久文件格式。 + +## SST 文件格式 + +Parquet 是一种提供快速数据查询的开源列式存储格式，已经被许多项目采用，例如 Delta Lake。 + +Parquet 具有层次结构，类似于“行组-列-数据页”。Parquet 文件中的数据被水平分区为行组（row group），在其中相同列的所有值一起存储以形成数据页（data pages）。数据页是最小的存储单元。这种结构极大地提高了性能。 + +首先，数据按列聚集，这使得文件扫描更加高效，特别是当查询只涉及少数列时，这在分析系统中非常常见。 + +其次，相同列的数据往往是同质的（比如具备近似的值），这有助于在采用字典和 Run-Length Encoding（RLE）等技术进行压缩。 + +![Parquet file format](/parquet-file-format.png) + +## 数据持久化 + +GreptimeDB 提供了 `storage.flush.global_write_buffer_size` 的配置项来设置全局的 Memtable 大小阈值。当数据库所有 MemTable 中的数据量之和达到阈值时将自动触发持久化操作，将 MemTable 的数据 flush 到 SST 文件中。 + + +## SST 文件中的索引数据 + +Apache Parquet 文件格式在列块和数据页的头部提供了内置的统计信息，用于剪枝和跳过。 + +![Column chunk header](/column-chunk-header.png) + +例如，在上述 Parquet 文件中，如果你想要过滤 `name` 等于 `Emily` 的行，你可以轻松跳过行组 0，因为 `name` 字段的最大值是 `Charlie`。这些统计信息减少了 IO 操作。 + + +## 索引文件 + +对于每个 SST 文件，GreptimeDB 不但维护 SST 文件内部索引，还会单独生成一个文件用于存储针对该 SST 文件的索引结构。 + +索引文件采用 [Puffin][3] 格式，这种格式具有较大的灵活性，能够存储更多的元数据，并支持更多的索引结构。 + +![Puffin](/puffin.png) + +目前，倒排索引是 GreptimeDB 第一个支持的单独索引结构，以 Blob 的形式存储在索引文件中。 + + +## 倒排索引 + +在 v0.7 版本中，GreptimeDB 引入了倒排索引（Inverted Index）来加速查询。 + +倒排索引是一种常见的用于全文搜索的索引结构，它将文档中的每个单词映射到包含该单词的文档列表，GreptimeDB 把这项源自于搜索引擎的技术应用到了时间序列数据库中。 + +搜索引擎和时间序列数据库虽然运行在不同的领域，但是应用的倒排索引技术背后的原理是相似的。这种相似性需要一些概念上的调整： +1. 单词：在 GreptimeDB 中，指时间线的列值。 +2. 文档：在 GreptimeDB 中，指包含多个时间线的数据段。 + +倒排索引的引入，使得 GreptimeDB 可以跳过不符合查询条件的数据段，从而提高扫描效率。 + +![Inverted index searching](/inverted-index-searching.png) + +例如，上述查询使用倒排索引来定位数据段，数据段满足条件：`job` 等于 `apiserver`，`handler` 符合正则匹配 `.*users` 及 `status` 符合正则匹配 `4..`，然后扫描这些数据段以产生满足所有条件的最终结果，从而显着减少 IO 操作的次数。 + +### 倒排索引格式 + +![Inverted index format](/inverted-index-format.png) + +GreptimeDB 按列构建倒排索引，每个倒排索引包含一个 FST 和多个 Bitmap。 + +FST（Finite State Transducer）允许 GreptimeDB 以紧凑的格式存储列值到 Bitmap 位置的映射，并且提供了优秀的搜索性能和支持复杂搜索（例如正则表达式匹配）；Bitmap 则维护了数据段 ID 列表，每个位表示一个数据段。 + + +### 索引数据段 + +GreptimeDB 把一个 SST 文件分割成多个索引数据段，每个数据段包含相同行数的数据。这种分段的目的是通过只扫描符合查询条件的数据段来优化查询性能。 + +例如，当数据段的行数为 1024，如果查询条件应用倒排索引后，得到的数据段列表为 `[0, 2]`，那么只需扫描 SST 文件中的第 0 和第 2 个数据段（即第 0 行到第 1023 行和第 2048 行到第 3071 行）即可。 + +数据段的行数由引擎选项 `index.inverted_index.segment_row_count` 控制，默认为 `1024`。较小的值意味着更精确的索引，往往会得到更好的查询性能，但会增加索引存储成本。通过调整该选项，可以在存储成本和查询性能之间进行权衡。 + + +## 统一数据访问层：OpenDAL + +GreptimeDB使用 [OpenDAL][2] 提供统一的数据访问层，因此，存储引擎无需与不同的存储 API 交互，数据可以无缝迁移到基于云的存储，如 AWS S3。 + +[1]: https://parquet.apache.org +[2]: https://github.com/datafuselabs/opendal +[3]: https://iceberg.apache.org/puffin-spec diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/metric-engine.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/metric-engine.md new file mode 100644 index 000000000..9721077cc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/metric-engine.md @@ -0,0 +1,41 @@ +--- +description: 介绍了 Metric 引擎的概念、架构及设计，重点描述了逻辑表与物理表的区别和批量 DDL 操作的实现。 +--- + +# Metric 引擎 + +## 概述 + +`Metric` 引擎是 GreptimeDB 的一个组件，属于存储引擎的一种实现，主要针对可观测 metrics 等存在大量小表的场景。 + +它的主要特点是利用合成的物理宽表来存储大量的小表数据，实现相同列复用和元数据复用等效果，从而达到减少小表的存储开销以及提高列式压缩效率等目标。表这一概念在 `Metric` 引擎下变得更更加轻量。 + +## 概念 + +`Metric` 引擎引入了两个新的概念，分别是逻辑表与物理表。从用户视角看，逻辑表与普通表完全一样。从存储视角看，物理 Region 就是一个普通的 Region。 + +### 逻辑表 +逻辑表，即用户定义的表。与普通的表都完全一样，逻辑表的定义包括表的名称、列的定义、索引的定义等。用户的查询、写入等操作都是基于逻辑表进行的。用户在使用过程中不需要关心逻辑表和普通表的区别。 + +从实现层面来说，逻辑表是一个虚拟的表，它并不直接读写物理的数据，而是通过将读写请求映射成对应物理表的请求来实现数据的存储与查询。 + +### 物理表 +物理表是真实存储数据的表，它拥有若干个由分区规则定义的物理 Region。 + +## 架构及设计 + +`Metric` 引擎的主要设计架构如下： + +![Arch](/metric-engine-arch.png) + +在目前版本的实现中，`Metric` 引擎复用了 `Mito` 引擎来实现物理数据的存储及查询能力，并在此之上同时提供物理表与逻辑表的访问能力。 + +在分区方面，逻辑表拥有与物理表完全一致的分区规则及 Region 分布。这是非常自然的，因为逻辑表的数据直接存储在物理表中，所以分区规则也是一致的。 + +在路由元数据方面，逻辑表的路由地址为逻辑地址，即该逻辑表所对应的物理表是什么，而后通过该物理表进行二次路由取得真正的物理地址。这一间接路由方式能够显著减少 `Metric` 引擎的 Region 发生迁移调度时所需要修改的元数据数量。 + +在操作方面，`Metric` 引擎仅对物理表的操作进行了有限的支持以防止误操作，例如通过禁止写入物理表、删除物理表等操作防止影响用户逻辑表的数据。总体上可以认为物理表是对用户只读的。 + +为了提升对大量表同时进行 DDL（Data Definition Language，数据操作语言）操作时性能，如 Prometheus Remote Write 冷启动时大量 metrics 带来的自动建表请求，以及前面提到的迁移物理 Region 时大量路由表的修改请求等，`Metric` 引擎引入了一些批量 DDL 操作。这些批量 DDL 操作能够将大量的 DDL 操作合并成一个请求，从而减少了元数据的查询及修改次数，提升了性能。 + +除了物理表的物理数据 Region 之外，`Metric` 引擎还额外为每一个物理数据 Region 创建了一个物理的元数据 Region，用于存储 `Metric` 引擎自身为了维护映射等状态所需要的一些元数据。这些元数据包括逻辑表与物理表的映射关系，逻辑列与物理列的映射关系等等。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/overview.md new file mode 100644 index 000000000..13e284550 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/overview.md @@ -0,0 +1,27 @@ +--- +description: 介绍了 Datanode 的主要职责和组件，包括 gRPC 服务、HTTP 服务、Heartbeat Task 和 Region Manager。 +--- + +# Datanode + +## Introduction + +`Datanode` 主要的职责是为 GreptimeDB 存储数据，我们知道在 GreptimeDB 中一个 `table` 可以有一个或者多个 `Region`, +而 `Datanode` 的职责便是管理这些 `Region` 的读写。`Datanode` 不感知 `table`，可以认为它是一个 `region server`。 +所以 `Frontend` 和 `Metasrv` 按照 `Region` 粒度来操作 `Datanode`。 + +![Datanode](/datanode.png) + +## Components + +一个 datanode 包含了 region server 所需的全部组件。这里列出了比较重要的部分： + +- 一个 gRPC 服务来提供对 `Region` 数据的读写，`Frontend` 便是使用这个服务来从 `Datanode` 读写数据。 +- 一个 HTTP 服务，可以通过它来获得当前节点的 metrics、 配置信息等 +- `Heartbeat Task` 用来向 `Metasrv` 发送心跳，心跳在 GreptimeDB 的分布式架构中发挥着至关重要的作用， + 是分布式协调和调度的基础通信通道，心跳的上行消息中包含了重要信息比如 `Region` 的负载，如果 `Metasrv` 做出了调度 + 决定（比如 Region 转移），它会通过心跳的下行消息发送指令到 `Datanode` +- `Datanode` 不包含物理规划器（Physical planner）、优化器（optimizer）等组件（这些被放置在 `Frontend` 中），用户对 + 一个或多个 `Table` 的查询请求会在 `Frontend` 中被转换为 `Region` 的查询请求，`Datanode` 负责处理这些 `Region` 查询请求 +- 一个 `Region Manager` 用来管理 `Datanode` 上的所有 `Region`s +- GreptimeDB 支持可插拔的多引擎架构，目前已有的 engine 包括 `File Engine` 和 `Mito Engine` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/python-scripts.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/python-scripts.md new file mode 100644 index 000000000..103092531 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/python-scripts.md @@ -0,0 +1,29 @@ +--- +description: 介绍了在 GreptimeDB 中使用 Python 脚本进行数据分析的两种后端实现：CPython 和嵌入式 RustPython 解释器。 +--- + +# Python 脚本 + +## 简介 + +Python 脚本是分析本地数据库中的数据的便捷方式， +通过将脚本直接在数据库内运行而不是从数据库拉取数据的方式，可以节省大量的数据传输时间。 +下图描述了 Python 脚本的工作原理。 +`RecordBatch`（基本上是表中的一列，带有类型和元数据）可以来自数据库中的任何地方， +而返回的 `RecordBatch` 可以用 Python 语法注释以指示其元数据，例如类型或空。 +脚本将尽其所能将返回的对象转换为 `RecordBatch`，无论它是 Python 列表、从参数计算出的 `RecordBatch` 还是常量（它被扩展到与输入参数相同的长度）。 + +![Python Coprocessor](/python-coprocessor.png) + +## 两种可选的后端 + +### CPython 后端 + +该后端由 [PyO3](https://pyo3.rs/v0.18.1/) 提供支持，可以使用您最喜欢的 Python 库（如 NumPy、Pandas 等），并允许 Conda 管理您的 Python 环境。 + +但是使用它也涉及一些复杂性。您必须设置正确的 Python 共享库，这可能有点棘手。一般来说，您只需要安装 `python-dev` 包。但是，如果您使用 Homebrew 在 macOS 上安装 Python，则必须创建一个适当的软链接到 `Library/Frameworks/Python.framework`。有关使用 PyO3 crate 与不同 Python 版本的详细说明，请参见 [这里](https://pyo3.rs/v0.18.1/building_and_distribution#configuring-the-python-version) + +### 嵌入式 RustPython 解释器 + +可以运行脚本的实验性 [python 解释器](https://github.com/RustPython/RustPython)，它支持 Python 3.10 语法。您可以使用所有的 Python 语法，更多信息请参见 [Python 脚本的用户指南](/user-guide/python-scripts/overview.md). + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/query-engine.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/query-engine.md new file mode 100644 index 000000000..b8916e226 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/query-engine.md @@ -0,0 +1,46 @@ +--- +description: 介绍了 GreptimeDB 的查询引擎架构，基于 Apache DataFusion 构建，涵盖逻辑计划、物理计划、优化和执行过程。 +--- + +# Query Engine + +## 介绍 + +GreptimeDB 的查询引擎是基于[Apache DataFusion][1]（属于[Apache Arrow][2]的子项目）构建的，它是一个用 Rust 编写的出色的查询引擎。它提供了一整套功能齐全的组件，从逻辑计划、物理计划到执行运行时。下面将解释每个组件如何被整合在一起，以及在执行过程中它们的位置。 + +![Execution Procedure](/execution-procedure.png) + +入口点是逻辑计划，它被用作查询或执行逻辑等的通用中间表示。逻辑计划的两个主要来源是：1. 用户查询，例如通过 SQL 解析器和规划器的 SQL；2. Frontend 的分布式查询，这将在下一节中详细解释。 + +接下来是物理计划，或称执行计划。与包含所有逻辑计划变体（除特殊扩展计划节点外）的大型枚举的逻辑计划不同，物理计划实际上是一个定义了在执行过程中调用的一组方法的特性。所有数据处理逻辑都包装在实现该特性的相应结构中。它们是对数据执行的实际操作，如聚合器 `MIN` 或 `AVG` ，以及表扫描 `SELECT ... FROM`。 + +优化阶段通过转换逻辑计划和物理计划来提高执行性能，现在全部基于规则。它也被称为“基于规则的优化”。一些规则是 DataFusion 原生的，其他一些是在 GreptimeDB 中自定义的。在未来，我们计划添加更多规则，并利用数据统计进行基于成本的优化 (CBO)。 + +最后一个阶段"执行"是一个动词，代表从存储读取数据、进行计算并生成预期结果的过程。虽然它比之前提到的概念更抽象，但你可以简单地将它想象为执行一个 Rust 异步函数，并且它确实是一个异步流。 + +当你想知道 SQL 是如何通过逻辑计划或物理计划中表示时，`EXPLAIN [VERBOSE] ` 是非常有用的。 + +## 数据表示 + +GreptimeDB 使用 [Apache Arrow][2]作为内存中的数据表示格式。它是面向列的，以跨平台格式，也包含许多高性能的基础操作。这些特性使得在许多不同的环境中共享数据和实现计算逻辑变得容易。 + +## 索引 + +在时序数据中，有两个重要的维度：时间戳和标签列（或者类似于关系数据库中的主键）。GreptimeDB 将数据分组到时间桶中，因此能在非常低的成本下定位和提取预期时间范围内的数据。GreptimeDB 中主要使用的持久文件格式 [Apache Parquet][3] 提供了多级索引和过滤器，使得在查询过程中很容易修剪数据。在未来，我们将更多地利用这个特性，并开发我们的分离索引来处理更复杂的用例。 + +## 拓展性 + + + +在 GreptimeDB 中扩展操作非常简单。你可以像 [这样][5] 实现你的算子。 + +## 分布式查询 + +参考 [Distributed Querying][6]. + +[1]: https://github.com/apache/arrow-datafusion +[2]: https://arrow.apache.org/ +[3]: https://parquet.apache.org +[4]: python-scripts.md +[5]: https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-write-aggregate-function.md +[6]: ../frontend/distributed-querying.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/storage-engine.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/storage-engine.md new file mode 100644 index 000000000..616c1f4d2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/storage-engine.md @@ -0,0 +1,61 @@ +--- +description: 详细介绍了 GreptimeDB 的存储引擎架构、数据模型和 region 的概念，重点描述了 Mito 存储引擎的优化和组件。 +--- + +# 存储引擎 + +## 概述 + +`存储引擎` 负责存储数据库的数据。Mito 是我们默认使用的存储引擎，基于 [LSMT][1]（Log-structured Merge-tree）。我们针对处理时间序列数据的场景做了很多优化，因此 mito 这个存储引擎并不适用于通用用途。 + +## 架构 +下图展示了存储引擎的架构和处理数据的流程。 + +![Architecture](/storage-engine-arch.png) + +该架构与传统的 LSMT 引擎相同： + +- [WAL][2] + - 为尚未刷盘的数据提供高持久性保证。 + - 基于 `LogStore` API 实现，不关心底层存储介质。 + - WAL 的日志记录可以存储在本地磁盘上，也可以存储在实现了 `LogStore` API 的分布式日志服务中。 +- Memtable + - 数据首先写入 `active memtable`，又称 `mutable memtable`。 + - 当 `mutable memtable` 已满时，它将变为只读的 `immutable memtable`。 +- SST + - SST 的全名为有序字符串表（`Sorted String Table`）。 + - `immutable memtable` 刷到持久存储后形成一个SST文件。 +- Compactor + - `Compactor` 通过 compaction 操作将小的 SST 合并为大的 SST。 + - 默认使用 [TWCS][3] 策略进行合并 +- Manifest + - `Manifest` 存储引擎的元数据，例如 SST 的元数据。 +- Cache + - 加速查询操作。 + +[1]: https://en.wikipedia.org/wiki/Log-structured_merge-tree +[2]: https://en.wikipedia.org/wiki/Write-ahead_logging +[3]: https://cassandra.apache.org/doc/latest/cassandra/operating/compaction/twcs.html + +## 数据模型 + +存储引擎提供的数据模型介于 `key-value` 模型和表模型之间 + +```txt +tag-1, ..., tag-m, timestamp -> field-1, ..., field-n +``` + +每一行数据包含多个 tag 列，一个 timestamp 列和多个 field 列 +- `0 ~ m` 个 tag 列 + - tag 列是可空的 + - 在建表时通过 `PRIMARY KEY` 指定 +- 必须包含一个 timestamp 列 + - timestamp 列非空 + - 在建表时通过 `TIME INDEX` 指定 +- `0 ~ n` 个 field 列 + - field 列是可空的 +- 数据按照 tag 列和 timestamp 列有序存储 + +## Region + +数据在存储引擎中以 `region` 的形式存储，`region` 是引擎中的一个逻辑隔离存储单元。`region` 中的行必须具有相同的 `schema`（模式），该 `schema` 定义了 `region` 中的 tag 列，timestamp 列和 field 列。数据库中表的数据存储在一到多个 `region` 中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/wal.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/wal.md new file mode 100644 index 000000000..f2df12b5f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/datanode/wal.md @@ -0,0 +1,25 @@ +--- +description: 介绍了 GreptimeDB 的预写日志（WAL）机制，包括其命名空间、同步/异步刷盘策略和在数据节点重启时的重放功能。 +--- + +# 预写日志 + +## 介绍 + +我们的存储引擎受到了日志结构合并树（Log-structured Merge Tree，LSMT）的启发。对数据的变更操作直接应用于 MemTable 而不是持久化到磁盘上的数据页，这显著提高了性能，但也带来了持久化相关的问题，特别是在 Datanode 意外崩溃时。与所有类似LSMT 的存储引擎一样，GreptimeDB 使用预写日志（Write-Ahead Log，WAL）来确保数据被可靠地持久化，并且保证崩溃时的数据完整性。 + +预写日志是一个仅提供追加写的文件组。所有的 INSERT、UPDATE 和 DELETE 操作都被转换为操作日志，然后追加到 WAL。一旦操作日志被持久化到底层文件，该操作才可以进一步应用到 MemTable。 + +当数据节点重新启动时，WAL 中的操作条目将被重放，以重建正确的 MemTable 状态。 + +![WAL in Datanode](/wal.png) + +## 命名空间 + +WAL 的命名空间用于区分来自不同 region 的条目。追加和读取操作必须提供一个命名空间。目前，region ID 被用作命名空间，因为每个 region 都有一个在数据节点重新启动时需要重构的 MemTable。 + +## 同步/异步刷盘 + +默认情况下，WAL 的追加写是异步的，这意味着写入方不会等待操作日志被刷入到磁盘并持久化。这个默认设置提供了更高的性能，但在服务器意外关闭时可能会丢失数据。另一方面，同步刷新提供了更高的可靠性，但其代价是性能更低。 + +在 v0.4 版本中，新的 region worker 架构可以使用批处理来减轻同步刷盘的开销。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/arrangement.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/arrangement.md new file mode 100644 index 000000000..4fc53bf91 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/arrangement.md @@ -0,0 +1,17 @@ +--- +description: 描述了 Arrangement 在数据流进程中的状态存储功能，包括键值对存储、查询和删除操作的实现。 +--- + +# Arrangement + +Arrangement 存储数据流进程中的状态，存储 flow 的更新流（stream）以供进一步查询和更新。 + +Arrangement 本质上存储的是带有时间戳的键值对。 +在内部，Arrangement 接收类似 `((Key Row, Value Row), timestamp, diff)` 的 tuple，并将其存储在内存中。 +你可以使用 `get(now: Timestamp, key: Row)` 查询某个时间的键值对。 +Arrangement 假定早于某个时间（也称为 Low Watermark）的所有内容都已被写入到 sink 表中，不会为其保留历史记录。 + +:::tip 注意 +Arrangement 允许通过将传入 tuple 的 `diff` 设置为 -1 来删除键。 +此外，如果已将行数据添加到 Arrangement 并且使用不同的值插入相同的键，则原始值将被新值覆盖。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/dataflow.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/dataflow.md new file mode 100644 index 000000000..c519038c4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/dataflow.md @@ -0,0 +1,17 @@ +--- +description: 解释了 Dataflow 模块的核心计算功能，包括 SQL 查询转换、内部执行计划、数据流的触发运行和支持的操作。 +--- + +# 数据流 + +Dataflow 模块（参见 `flow::compute` 模块）是 `flow` 的核心计算模块。 +它接收 SQL 查询并将其转换为 `flow` 的内部执行计划。 +然后，该执行计划被转化为实际的数据流，而数据流本质上是一个由带有输入和输出端口的函数组成的有向无环图（DAG）。 +数据流会在需要时被触发运行。 + +目前该数据流只支持 `map`和 `reduce` 操作，未来将添加对 `join` 等操作的支持。 + +在内部，数据流使用 `tuple(row, time, diff)` 以行格式处理数据。 +这里 `row` 表示实际传递的数据，可能包含多个 `value` 对象。 +`time` 是系统时间，用于跟踪数据流的进度，`diff` 通常表示行的插入或删除（+1 或 -1）。 +因此，`tuple` 表示给定系统时间的 `row` 的插入/删除操作。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/overview.md new file mode 100644 index 000000000..c19968757 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/flownode/overview.md @@ -0,0 +1,20 @@ +--- +description: 介绍了 Flownode 的基本概念、组件和当前版本的支持情况，包括 FlownodeManager、FlowWorker 和 Flow 的功能。 +--- + +# 概述 + +## 简介 + +`Flownode` 为数据库提供了一种简单的流处理（称为 `flow`）能力。 +`Flownode` 管理 `flow`，这些 `flow` 是从 `source` 接收数据并将数据发送到 `sink` 的任务。 + +在当前版本中，`Flownode` 仅在单机模式中支持，未来将支持分布式模式。 + +## 组件 + +`Flownode` 包含了 flow 流式处理的所有组件，以下是关键部分： + +- `FlownodeManager`：用于接收从 `Frontend` 转发的插入数据并将结果发送回 flow 的 sink 表。 +- 一定数量的 `FlowWorker` 实例，每个实例在单独的线程中运行。当前在单机模式中只有一个 flow worker，但这可能会在未来发生变化。 +- `Flow` 是一个主动从 `source` 接收数据并将数据发送到 `sink` 的任务。由 `FlownodeManager` 管理并由 `FlowWorker` 运行。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/distributed-querying.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/distributed-querying.md new file mode 100644 index 000000000..8a17eae72 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/distributed-querying.md @@ -0,0 +1,39 @@ +--- +description: 介绍 GreptimeDB 中的分布式查询方法，包括查询的拆分和合并过程，以及 TableScan 节点的作用。 +--- + +# 分布式查询 + +我们知道在 GreptimeDB 中数据是如何分布的（参见“[表分片][1]”），那么如何查询呢？在 GreptimeDB 中，分布式查询非常简单。简单来说，我们只需将查询拆分为子查询，每个子查询负责查询表数据的一个部分，然后将所有结果合并为最终结果。这是一种典型的“拆分-合并”方法。具体来说，让我们从查询到达 `frontend` 开始。 + +当查询到达 `frontend` 时，它首先被解析为 SQL 抽象语法树（AST）。我们遍历 AST，并从中生成逻辑计划。顾名思义，逻辑计划只是如何“逻辑地”执行查询的“提示”，它不能被直接运行，因此我们进一步从中生成可执行的物理计划。物理计划是一种类似树形的数据结构，每个节点实际上表示查询的执行方法。一旦我们从上到下运行物理计划树，结果数据将从叶子到根流动，被合并或计算。最终，我们在根节点的输出处得到了查询的结果。 + +到目前为止，这只是一个典型的 “volcano” 查询执行模型，你可以在几乎每个 SQL 数据库中看到这种模型。那么“分布式”是在哪里发生的呢？这全部发生在一个名为 “TableScan” 的物理计划节点中。TableScan 是物理计划树中的一个叶子节点，它负责扫描表的数据（就像它的名称所暗示的）。当 `frontend` 即将扫描表时，它首先需要根据每个 `region` 的数据范围将表扫描拆分为较小的扫描。 + +[1]: ./table-sharding.md + +表的所有 `region` 都有它们存储数据的范围。以下表为例： + +```sql +CREATE TABLE my_table ( + a INT, + others STRING, +) +PARTITION ON COLUMNS (a) ( + n < 10, + n >= 10 AND n < 20, + n >= 20 +) +``` + +`my_table` 表创建时被设定了 3 个分区。在 GreptimeDB 的当前实现中，将为该表创建 3 个 `region`（分区与 `region` 的比例为 1:1）。这 3 个区域将分别包含以下范围："[-∞, 10)", "[10, 20)" 和 "[20, +∞)"。例如，如果提供了值 "42"，我们将搜索这些范围，并找到包含该值的相应的 `region`（在此示例中为第 3 个 `region`）。 + +对于查询，我们使用“过滤器”来查找 `region`。 "过滤器"是 "WHERE" 子句中的条件。例如，查询 `SELECT * FROM my_table WHERE a < 10 AND b > 10`，其“过滤器”为 “a < 10 AND b > 10”。然后我们检查这些范围，找出包含满足过滤器条件的值的所有 `region`。 + +> 如果某个查询没有任何过滤器，则将其视为全表扫描。 + +找到所需的区域后，我们只需在其中组装子扫描。通过这种方式，我们将查询拆分为子查询，每个子查询都获取表数据的一部分。子查询在 `datanode` 中执行，并在 `frontend` 中等待完成。它们的结果将合并为表扫描请求的最终返回。 + +下面这张图片总结了分布式查询执行的过程： + +![Distributed Querying](/distributed-querying.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/overview.md new file mode 100644 index 000000000..3081e48de --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/overview.md @@ -0,0 +1,18 @@ +# 概述 + +`Frontend` 执行客户端的请求，也处理云服务中的一些特定任务，例如租户管理、鉴权认证、流量控制等。 + +`Frontend` 暴露了多个接口以支持用多种协议读写数据。您可以参考 [客户端协议][1] 了解更多细节。 + +下图是 GreptimeDB 在云上的一个典型的部署。`Frontend` 实例组成了一个集群处理来自客户端的请求： + +![frontend](/frontend.png) + +## 查看更多 + +- [表分片][2] +- [分布式查询][3] + +[1]: /user-guide/protocols/overview.md +[2]: ./table-sharding.md +[3]: ./distributed-querying.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/table-sharding.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/table-sharding.md new file mode 100644 index 000000000..8e545a09b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/frontend/table-sharding.md @@ -0,0 +1,52 @@ +--- +description: 介绍 GreptimeDB 中表数据的分片方法，包括分区和 Region 的定义及其关系。 +--- + +# 表分片 + +对于任何分布式数据库来说，数据的分片都是必不可少的。本文将描述 GreptimeDB 中的表数据如何进行分片。 + +## 分区 + +有关创建分区表的语法，请参阅用户指南中的[表分片](/user-guide/administration/manage-data/table-sharding.md)部分。 + +## Region + +在创建分区后，表中的数据被逻辑上分割。你可能会问："在 GreptimeDB 中，被逻辑上分区的数据是如何存储的？" 答案是保存在 `Region` 当中。 + +每个 `Region` 对应一个分区，并保存分区的数据。所有的 `Region` 分布在各个 `Datanode` 之中。我们的 `Metasrv` 会根据 `Datanode` +的状态在它们之间自动移动 `Region`。此外，`Metasrv` 还可以根据数据量或访问模式拆分或合并 `Region`。 + +分区和Region的关系参见下图： + +```text + ┌───────┐ + │ │ + │ Table │ + │ │ + └───┬───┘ + │ + Range [Start, end) │ Horizontally Split Data + ┌──────────────────┼──────────────────┐ + │ │ │ + │ │ │ + ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ + │ │ │ │ │ │ + │ Partition │ │ Partition │ │ Partition │ + │ │ │ │ │ │ + │ P0 │ │ P1 │ │ Px │ + └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ + │ │ │ + │ │ │ +┌───────┼──────────────────┼───────┐ │ Partition 和 Region 是一一对应的 +│ │ │ │ │ +│ ┌─────▼─────┐ ┌─────▼─────┐ │ ┌─────▼─────┐ +│ │ │ │ │ │ │ │ +│ │ Region │ │ Region │ │ │ Region │ +│ │ │ │ │ │ │ │ +│ │ R0 │ │ R1 │ │ │ Ry │ +│ └───────────┘ └───────────┘ │ └───────────┘ +│ │ +└──────────────────────────────────┘ + 可以放在同一个 Datanode 之中 +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/getting-started.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/getting-started.md new file mode 100644 index 000000000..9eb0b59f0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/getting-started.md @@ -0,0 +1,69 @@ +--- +description: 介绍如何在本地环境中从源代码编译和运行 GreptimeDB，包括系统要求和依赖项。 +--- + +# 立即开始 + +本页面介绍如何在本地环境中从源代码运行 GreptimeDB。 + +## 先决条件 + +### 系统和架构 + +目前，GreptimeDB 支持 Linux（amd64 和 arm64）、macOS（amd64 和 Apple Silicone）和 Windows。 + +### 构建依赖项 + +- [Git](https://git-scm.com/book/en/v2/Getting-Started-The-Command-Line)（可选） +- C/C++ 工具链：提供编译和链接的基本工具。在 Ubuntu 上，这可用作 `build-essential`。在其他平台上，也有类似的命令。 +- Rust（[指南][1]） + - 编译源代码 +- Protobuf（[指南][2]） + - 编译 proto 文件 + - 请注意，版本需要 >= 3.15。你可以使用 `protoc --version` 检查它。 +- 机器：建议内存在16GB以上 或者 使用[mold](https://github.com/rui314/mold)工具以降低链接时的内存使用。 + +[1]: +[2]: + +## 编译和运行 + +只需几个命令即可使用以 Standalone 模式启动 GreptimeDB 实例: + +```shell +git clone https://github.com/GreptimeTeam/greptimedb.git +cd greptimedb +cargo run -- standalone start +``` + +接下来，你可以选择与 GreptimeDB 交互的协议。 + +如果你只想构建服务器而不运行它： + +```shell +cargo build # --release +``` + +根据构建的模式（是否传递了 `--release` 选项），构建后的文件可以在 `$REPO/target/debug` 或 `$REPO/target/release` 目录下找到。 + +## 单元测试 + +GreptimeDB 经过了充分的测试，整个单元测试套件都随源代码一起提供。要测试它们，请使用 [nextest](https://nexte.st/index.html)。 + +要使用 cargo 安装 nextest，请运行： + +```shell +cargo install cargo-nextest --locked +``` + +或者，你可以查看他们的[文档](https://nexte.st/docs/installation/pre-built-binaries/)以了解其他安装方式。 + +安装好 nextest 后，你可以使用以下命令运行测试套件： + +```shell +cargo nextest run +``` + +## Docker + +我们还通过 Docker 提供预构建二进制文件，可以在 [Docker Hub 上获取](https://hub.docker.com/r/greptime/greptimedb)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-trace-greptimedb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-trace-greptimedb.md new file mode 100644 index 000000000..6234137b7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-trace-greptimedb.md @@ -0,0 +1,79 @@ +--- +description: 介绍如何在 GreptimeDB 中使用 Rust 的 tracing 框架进行代码埋点，包括在 RPC 中定义和传递 tracing 上下文的方法。 +--- + +# How to trace GreptimeDB + +GreptimeDB 使用 Rust 的 [tracing](https://docs.rs/tracing/latest/tracing/) 框架进行代码埋点，tracing 的具体原理和使用方法参见 tracing 的官方文档。 + +通过将 `trace_id` 等信息在整个分布式数据链路上透传，使得我们能够记录整个分布式链路的函数调用链，知道每个被追踪函数的调用时间等相关信息，从而对整个系统进行诊断。 + +## 在 RPC 中定义 tracing 上下文 + +因为 tracing 框架并没有原生支持分布式追踪，我们需要手动将 `trace_id` 等信息在 RPC 消息中传递，从而正确的识别函数的调用关系。我们使用基于 [w3c 的标准](https://www.w3.org/TR/trace-context/#traceparent-header-field-values) 将相关信息编码为 `tracing_context` ，将消息附在 RPC 的 header 中。主要定义在： + +- `frontend` 与 `datanode` 交互：`tracing_context` 定义在 [`RegionRequestHeader`](https://github.com/GreptimeTeam/greptime-proto/blob/main/proto/greptime/v1/region/server.proto) 中 +- `frontend` 与 `metasrv` 交互：`tracing_context` 定义在 [`RequestHeader`](https://github.com/GreptimeTeam/greptime-proto/blob/main/proto/greptime/v1/meta/common.proto) 中 +- Client 与 `frontend` 交互：`tracing_context` 定义在 [`RequestHeader`](https://github.com/GreptimeTeam/greptime-proto/blob/main/proto/greptime/v1/common.proto) 中 + +## 在 RPC 调用中传递 tracing 上下文 + +我们构建了一个 `TracingContext` 结构体，封装了与 tracing 上下文有关的操作。[相关代码](https://github.com/GreptimeTeam/greptimedb/blob/main/src/common/telemetry/src/tracing_context.rs) + +GreptimeDB 在使用 `TracingContext::from_current_span()` 获取当前 tracing 上下文，使用 `to_w3c()` 方法将 tracing 上下文编码为符合 w3c 的格式，并将其附在 RPC 消息中，从而使 tracing 上下文正确的在分布式组件之中传递。 + +下面的例子说明了如何获取当前 tracing 上下文，并在构造 RPC 消息时正确传递参数，从而使 tracing 上下文正确的在分布式组件之中传递。 + + +```rust +let request = RegionRequest { + header: Some(RegionRequestHeader { + tracing_context: TracingContext::from_current_span().to_w3c(), + ..Default::default() + }), + body: Some(region_request::Body::Alter(request)), +}; +``` + +在 RPC 消息的接收方，需要将 tracing 上下文正确解码，并且使用该上下文构建第一个 `span` 对函数调用进行追踪。比如下面的代码就将接收到的 RPC 消息中的 `tracing_context` 使用 `TracingContext::from_w3c` 方法正确解码。并使用 `attach` 方法将新建的 `info_span!("RegionServer::handle_read")`  附上了上下文消息，从而能够跨分布式组件对调用进行追踪。 + +```rust +... +let tracing_context = request + .header + .as_ref() + .map(|h| TracingContext::from_w3c(&h.tracing_context)) + .unwrap_or_default(); +let result = self + .handle_read(request) + .trace(tracing_context.attach(info_span!("RegionServer::handle_read"))) + .await?; +... +``` + +## 使用 `tracing::instrument` 对监测代码进行埋点 + +我们使用 tracing 提供的 `instrument` 宏对代码进行埋点，只要将 `instrument` 宏标记在需要进行埋点的函数即可。 `instrument` 宏会每次将函数调用的参数以 `Debug` 的形式打印到 span 中。对于没有实现 `Debug` trait 的参数，或者结构体过大、参数过多，最后导致 span 过大，希望避免这些情况就需要使用 `skip_all`，跳过所有的参数打印。 + +```rust +#[tracing::instrument(skip_all)] +async fn instrument_function(....) { + ... +} +``` + +## 跨越 runtime 的代码埋点 + +Rust 的 tracing 库会自动处理埋点函数间的嵌套关系，但如果某个函数的调用跨越 runtime 的话，tracing 不能自动对这类调用进行追踪，我们需要手动跨越 runtime 去传递上下文。 + +```rust +let tracing_context = TracingContext::from_current_span(); +let handle = runtime.spawn(async move { + handler + .handle(query) + .trace(tracing_context.attach(info_span!("xxxxx"))) + ... +}); +``` + +比如上面这段代码需要跨越 runtime 去进行 tracing，我们先通过 `TracingContext::from_current_span()` 获取当前 tracing 上下文，通过在另外一个 runtime 里新建一个 span，并将 span 附着在当前上下文中，我们就完成了跨越 runtime 的代码埋点，正确追踪到了调用链。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-use-tokio-console.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-use-tokio-console.md new file mode 100644 index 000000000..304a53ba3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-use-tokio-console.md @@ -0,0 +1,33 @@ +--- +description: 介绍如何在 GreptimeDB 中启用 tokio-console，包括构建和启动时的配置方法。 +--- + +# 如何在 GreptimeDB 中启用 tokio-console + +本文介绍了如何在 GreptimeDB 中启用 [tokio-console](https://github.com/tokio-rs/console)。 + +首先，在构建 GreptimeDB 时带上 feature `cmd/tokio-console`。同时 `tokio_unstable` cfg 也必须开启： + +```bash +RUSTFLAGS="--cfg tokio_unstable" cargo build -F cmd/tokio-console +``` + +启动 GreptimeDB，可设置 tokio console 绑定的地址，配置是 `--tokio-console-addr`。`tokio_unstable` 的 cfg 也需要同时开启。例如： + +```bash +RUSTFLAGS="--cfg tokio_unstable" greptime --tokio-console-addr="127.0.0.1:6669" standalone start +``` + +这样就可以使用 `tokio-console` 命令去连接 GreptimeDB 的 tokio console 服务了： + +```bash +tokio-console [TARGET_ADDR] +``` + +"`TARGET_ADDR`" 默认是 "\"。 + +:::tip Note + +`tokio-console` 命令的安装方法参见 [tokio-console](https://github.com/tokio-rs/console)。 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-write-sdk.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-write-sdk.md new file mode 100644 index 000000000..dc4f5f35b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/how-to/how-to-write-sdk.md @@ -0,0 +1,72 @@ +--- +description: 介绍如何为 GreptimeDB 开发一个 gRPC SDK，包括 GreptimeDatabase 服务的定义、GreptimeRequest 和 GreptimeResponse 的结构。 +--- + +# 如何为 GreptimeDB 开发一个 gRPC SDK + +GreptimeDB 的 gRPC SDK 只需要处理写请求即可。读请求是标准 SQL 或 PromQL ，可以由任何 JDBC 客户端或 Prometheus +客户端处理。这也是为什么所有的 GreptimeDB SDK 都命名为 "`greptimedb-ingester-`"。请确保你的 GreptimeDB SDK +遵循相同的命名约定。 + +## `GreptimeDatabase` 服务 + +GreptimeDB 自定义了一个 gRPC 服务：`GreptimeDatabase` +。你只需要实现这个服务即可。你可以在[这里](https://github.com/GreptimeTeam/greptime-proto/blob/main/proto/greptime/v1/database.proto) +找到它的 Protobuf 定义。 + +`GreptimeDatabase` 有 2 个 RPC 方法： + +```protobuf +service GreptimeDatabase { + rpc Handle(GreptimeRequest) returns (GreptimeResponse); + + rpc HandleRequests(stream GreptimeRequest) returns (GreptimeResponse); +} +``` + +`Handle` 方法是一个 unary 调用：当 GreptimeDB 服务接收到一个 `GreptimeRequest` 请求后，它立刻处理该请求并返回一个相应的 +`GreptimeResponse`。 + +`HandleRequests` 方法则是一个 "[Client Streaming RPC][3]" 方式的调用。 +它可以接受一个连续的 `GreptimeRequest` 请求流，持续地发给 GreptimeDB 服务。 +GreptimeDB 服务会在收到流中的每个请求时立刻进行处理，并最终（流结束时）返回一个总结性的 `GreptimeResponse`。 +通过 `HandleRequests`，我们可以获得一个非常高的请求吞吐量。 + +### `GreptimeRequest` + +`GreptimeRequest` 是一个 Protobuf 消息，定义如下： + +```protobuf +message GreptimeRequest { + RequestHeader header = 1; + oneof request { + InsertRequests inserts = 2; + QueryRequest query = 3; + DdlRequest ddl = 4; + DeleteRequests deletes = 5; + RowInsertRequests row_inserts = 6; + RowDeleteRequests row_deletes = 7; + } +} +``` + +`RequestHeader` 是必需，它包含了一些上下文，鉴权和其他信息。"oneof" 的字段包含了发往 GreptimeDB 服务的请求。 + +注意我们有两种类型的插入请求，一种是以 "列" 的形式（`InsertRequests`），另一种是以 "行" 的形式（`RowInsertRequests` +）。通常我们建议使用 "行" 的形式，因为它对于表的插入更自然，更容易使用。但是，如果需要一次插入大量列，或者有大量的 "null" +值需要插入，那么最好使用 "列" 的形式。 + +### `GreptimeResponse` + +`GreptimeResponse` 是一个 Protobuf 消息，定义如下： + +```protobuf +message GreptimeResponse { + ResponseHeader header = 1; + oneof response {AffectedRows affected_rows = 2;} +} +``` + +`ResponseHeader` 包含了返回值的状态码，以及错误信息（如果有的话）。"oneof" 的字段目前只有 "affected rows"。 + +GreptimeDB 现在有很多 SDK，你可以参考[这里](https://github.com/GreptimeTeam?q=ingester&type=all&language=&sort=)获取一些示例。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/admin-api.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/admin-api.md new file mode 100644 index 000000000..c0c09a839 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/admin-api.md @@ -0,0 +1,297 @@ +--- +description: 介绍 Metasrv 的 Admin API，包括健康检查、leader 查询和心跳检测等功能。 +--- + +# Admin API + +Admin 提供了一种简单的方法来查看集群信息，包括 metasrv 健康检测、metasrv leader 查询、数据库元数据查询和数据节点心跳检测。 + +Admin API 是一个 HTTP 服务，提供一组可以通过 HTTP 请求调用的 RESTful API。Admin API 简单、用户友好且安全。 +可用的 API： + +- /health +- /leader +- /heartbeat +- /maintenance + +所有这些 API 都在父资源 `/admin` 下。 + +在以下部分中，我们假设你的 metasrv 实例运行在本地主机的 3002 端口。 + +## /health HTTP 端点 + +`/health` 端点接受 GET HTTP 请求，你可以使用此端点检查你的 metasrv 实例的健康状况。 + +### 定义 + +```bash +curl -X GET http://localhost:3002/admin/health +``` + +### 示例 + +#### 请求 + +```bash +curl -X GET http://localhost:3002/admin/health +``` + +#### 响应 + +```json +OK +``` + +## /leader HTTP 端点 + +`/leader` 端点接受 GET HTTP 请求，你可以使用此端点查询你的 metasrv 实例的 leader 地址。 + +### 定义 + +```bash +curl -X GET http://localhost:3002/admin/leader +``` + +### 示例 + +#### 请求 + +```bash +curl -X GET http://localhost:3002/admin/leader +``` + +#### 响应 + +```json +127.0.0.1:3002 +``` + +## /heartbeat HTTP 端点 + +`/heartbeat` 端点接受 GET HTTP 请求，你可以使用此端点查询所有数据节点的心跳。 + +你还可以查询指定 `addr` 的数据节点的心跳数据，但在路径中指定 `addr` 是可选的。 + +### 定义 + +```bash +curl -X GET http://localhost:3002/admin/heartbeat +``` + +| 查询字符串参数 | 类型 | 可选/必选 | 定义 | +|:---------------|:-------|:----------|:--------------------| +| addr | String | 可选 | 数据节点的地址。 | + +### 示例 + +#### 请求 + +```bash +curl -X GET 'http://localhost:3002/admin/heartbeat?addr=127.0.0.1:4100' +``` + +#### 响应 + +```json +[ + [{ + "timestamp_millis": 1677049348651, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049344048, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049343624, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049339036, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049338609, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049334019, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049333592, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049329002, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049328573, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049323986, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }] +] +``` + +## /maintenance HTTP 端点 + +当处于维护状态时，metasrv 将忽略检测到的区域故障。这在数据节点计划短时间不可用时非常有用，例如数据节点的滚动升级时。 + +### GET + +`/maintenance` 端点接受 GET HTTP 请求，你可以使用此端点查询你的 metasrv 实例的维护状态。 + +```bash +curl -X GET http://localhost:3002/admin/maintenance +``` + +#### 请求 + +```bash +curl -X GET http://localhost:3002/admin/maintenance +``` + +#### 响应 + +```text +Maintenance mode is disabled +``` + +### PUT + +`/maintenance` 端点接受 PUT HTTP 请求，你可以切换你的 metasrv 实例的维护状态。 + +```bash +curl -X PUT http://localhost:3002/admin/maintenance +``` + +| 查询字符串参数 | 类型 | 可选/必选 | 定义 | +|:---------------|:-------|:----------|:--------------------| +| enable | String | 必选 | 'true' 或 'false' | + +#### 请求 + +```bash +curl -X PUT http://localhost:3002/admin/maintenance?enable=true +``` + +#### 响应 + +```text +Maintenance mode enabled +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/overview.md new file mode 100644 index 000000000..bae3b2038 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/overview.md @@ -0,0 +1,161 @@ +--- +description: 介绍 Metasrv 的功能、架构和与前端的交互方式。 +--- + +# 概述 + +![meta](/meta.png) + +## Metasrv 包含什么 + +- 存储元数据（Catalog, Schema, Table, Region 等） +- 请求路由器。它告诉前端在哪里写入和读取数据。 +- 数据节点的负载均衡，决定谁应该处理新的表创建请求，更准确地说，它做出资源分配决策。 +- 选举与高可用性，GreptimeDB 设计为 Leader-Follower 架构，只有 leader 节点可以写入，而 follower 节点可以读取，follower 节点的数量通常 >= 1，当 leader 不可用时，follower 节点需要能够快速切换为 leader。 +- 统计数据收集（通过每个节点上的心跳报告），如 CPU、负载、节点上的表数量、平均/峰值数据读写大小等，可用作分布式调度的基础。 + +## 前端如何与 Metasrv 交互 + +首先，请求路由器中的路由表结构如下（注意这只是逻辑结构，实际存储结构可能不同，例如端点可能有字典压缩）。 + +```txt + table_A + table_name + table_schema // 用于物理计划 + regions + region_1 + mutate_endpoint + select_endpoint_1, select_endpoint_2 + region_2 + mutate_endpoint + select_endpoint_1, select_endpoint_2, select_endpoint_3 + region_xxx + table_B + ... +``` + +### 创建表 + +1. 前端发送 `CREATE TABLE` 请求到 Metasrv。 +2. 根据请求中包含的分区规则规划 Region 数量。 +3. 检查数据节点可用资源的全局视图（通过心跳收集）并为每个 Region 分配一个节点。 +4. 前端创建表并在成功创建后将 `Schema` 存储到 Metasrv。 + +### `Insert` + +1. 前端从 Metasrv 获取指定表的路由。注意，最小的路由单元是表的路由（多个 Region），即包含该表所有 Region 的地址。 +2. 最佳实践是前端首先从本地缓存中获取路由并将请求转发到数据节点。如果路由不再有效，则数据节点有义务返回 `Invalid Route` 错误，前端重新从 Metasrv 获取最新数据并更新其缓存。路由信息不经常变化，因此，前端使用惰性策略维护缓存是足够的。 +3. 前端处理可能包含多个表和多个 Region 的一批写入，因此前端需要根据“路由表”拆分用户请求。 + +### `Select` + +1. 与 `Insert` 类似，前端首先从本地缓存中获取路由表。 +2. 与 `Insert` 不同，对于 `Select`，前端需要从路由表中提取只读节点（follower），然后根据优先级将请求分发到 leader 或 follower 节点。 +3. 前端的分布式查询引擎根据路由信息分发多个子查询任务并聚合查询结果。 + +## Metasrv 架构 + +![metasrv-architecture](/metasrv-architecture.png) + +## 分布式共识 + +如你所见，Metasrv 依赖于分布式共识，因为： + +1. 首先，Metasrv 必须选举一个 leader ，数据节点只向 leader 发送心跳，我们只使用单个 Metasrv 节点接收心跳，这使得基于全局信息进行一些计算或调度变得容易且快速。至于数据节点如何连接到 leader ，这由 MetaClient 决定（使用重定向，心跳请求变为 gRPC 流，使用重定向比转发更不容易出错），这对数据节点是透明的。 +2. 其次，Metasrv 必须为数据节点提供选举 API，以选举“写入”和“只读”节点，并帮助数据节点实现高可用性。 +3. 最后，`Metadata`、`Schema` 和其他数据必须在 Metasrv 上可靠且一致地存储。因此，基于共识的算法是存储它们的理想方法。 + +对于 Metasrv 的第一个版本，我们选择 Etcd 作为共识算法组件（Metasrv 设计时考虑适应不同的实现，甚至创建一个新的轮子），原因如下： + +1. Etcd 提供了我们需要的 API，例如 `Watch`、`Election`、`KV` 等。 +2. 我们只执行两个分布式共识任务：选举（使用 `Watch` 机制）和存储（少量元数据），这两者都不需要我们定制自己的状态机，也不需要基于 raft 定制自己的状态机；少量数据也不需要多 raft 组支持。 +3. Metasrv 的初始版本使用 Etcd，使我们能够专注于 Metasrv 的功能，而不需要在分布式共识算法上花费太多精力，这提高了系统设计（避免与共识算法耦合）并有助于初期的快速开发，同时通过良好的架构设计，未来可以轻松接入优秀的共识算法实现。 + +## 心跳管理 + +数据节点与 Metasrv 之间的主要通信方式是心跳请求/响应流，我们希望这是唯一的通信方式。这个想法受到 [TiKV PD](https://github.com/tikv/pd) 设计的启发，我们在 [RheaKV](https://github.com/sofastack/sofa-jraft/tree/master/jraft-rheakv/rheakv-pd) 中有实际经验。请求发送其状态，而 Metasrv 通过心跳响应发送不同的调度指令。 + +心跳可能携带以下数据，但这不是最终设计，我们仍在讨论和探索究竟应该收集哪些数据。 + +``` +service Heartbeat { + // 心跳，心跳可能有很多内容，例如： + // 1. 要注册到 Metasrv 并可被其他节点发现的元数据。 + // 2. 一些性能指标，例如负载、CPU 使用率等。 + // 3. 正在执行的计算任务数量。 + rpc Heartbeat(stream HeartbeatRequest) returns (stream HeartbeatResponse) {} +} + +message HeartbeatRequest { + RequestHeader header = 1; + + // 自身节点 + Peer peer = 2; + // leader 节点 + bool is_leader = 3; + // 实际报告时间间隔 + TimeInterval report_interval = 4; + // 节点状态 + NodeStat node_stat = 5; + // 此节点中的 Region 状态 + repeated RegionStat region_stats = 6; + // follower 节点和状态，在 follower 节点上为空 + repeated ReplicaStat replica_stats = 7; +} + +message NodeStat { + // 此期间的读取容量单位 + uint64 rcus = 1; + // 此期间的写入容量单位 + uint64 wcus = 2; + // 此节点中的表数量 + uint64 table_num = 3; + // 此节点中的 Region 数量 + uint64 region_num = 4; + + double cpu_usage = 5; + double load = 6; + // 节点中的读取磁盘 I/O + double read_io_rate = 7; + // 节点中的写入磁盘 I/O + double write_io_rate = 8; + + // 其他 + map attrs = 100; +} + +message RegionStat { + uint64 region_id = 1; + TableName table_name = 2; + // 此期间的读取容量单位 + uint64 rcus = 3; + // 此期间的写入容量单位 + uint64 wcus = 4; + // 近似 Region 大小 + uint64 approximate_size = 5; + // 近似行数 + uint64 approximate_rows = 6; + + // 其他 + map attrs = 100; +} + +message ReplicaStat { + Peer peer = 1; + bool in_sync = 2; + bool is_learner = 3; +} +``` + +## Central Nervous System (CNS) + +我们要构建一个算法系统，该系统依赖于每个节点的实时和历史心跳数据，应该做出一些更智能的调度决策并将其发送到 Metasrv 的 Autoadmin 单元，该单元分发调度决策，由数据节点本身或更可能由 PaaS 平台执行。 + +## 工作负载抽象 + +工作负载抽象的级别决定了 Metasrv 生成的调度策略（如资源分配）的效率和质量。 + +DynamoDB 定义了 RCUs 和 WCUs（读取容量单位/写入容量单位），解释说 RCU 是一个 4KB 数据的读取请求，WCU 是一个 1KB 数据的写入请求。当使用 RCU 和 WCU 描述工作负载时，更容易实现性能可测量性并获得更有信息量的资源预分配，因为我们可以将不同的硬件能力抽象为 RCU 和 WCU 的组合。 + +然而，GreptimeDB 面临比 DynamoDB 更复杂的情况，特别是 RCU 不适合描述需要大量计算的 GreptimeDB 读取工作负载。我们正在努力解决这个问题。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/selector.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/selector.md new file mode 100644 index 000000000..a11b9a8d0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/metasrv/selector.md @@ -0,0 +1,46 @@ +--- +description: 介绍 Metasrv 中的 Selector，包括其类型和配置方法。 +--- + +# Selector + +## 介绍 + +什么是 `Selector`？顾名思义，它允许用户从给定的 `namespace` 和 `context` 中选择 `Item`s。有一个相关的 `trait`，也叫做 `Selector`，其定义可以在[这里][0]找到。 + +[0]: https://github.com/GreptimeTeam/greptimedb/blob/main/src/meta-srv/src/selector.rs + +在 `Metasrv` 中存在一个特定的场景。当 `Frontend` 向 `Metasrv` 发送建表请求时，`Metasrv` 会创建一个路由表（表的创建细节不在这里赘述）。在创建路由表时，`Metasrv` 需要选择适当的 `Datanode`s，这时候就需要用到 `Selector`。 + +## Selector 类型 + +`Metasrv` 目前提供以下几种类型的 `Selectors`: + +### LeasebasedSelector + +`LeasebasedSelector` 从所有可用的（也就是在租约期间内）`Datanode` 中随机选择，其特点是简单和快速。 + +### LoadBasedSelector + +`LoadBasedSelector` 按照负载来选择，负载值则由每个 `Datanode` 上的 region 数量决定，较少的 region 表示较低的负载，`LoadBasedSelector` 优先选择低负载的 `Datanode`。 + +### RoundRobinSelector [默认选项] +`RoundRobinSelector` 以轮询的方式选择 `Datanode`。在大多数情况下，这是默认的且推荐的选项。如果你不确定选择哪个，通常它就是正确的选择。 + +## 配置 + +您可以在启动 `Metasrv` 服务时通过名称配置 `Selector`。 + +- LeasebasedSelector: `lease_based` 或 `LeaseBased` +- LoadBasedSelector: `load_based` 或 `LoadBased` +- RoundRobinSelector: `round_robin` 或 `RoundRobin` + +例如： + +```shell +cargo run -- metasrv start --selector round_robin +``` + +```shell +cargo run -- metasrv start --selector RoundRobin +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/overview.md new file mode 100644 index 000000000..fe0e34376 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/overview.md @@ -0,0 +1,49 @@ +--- +description: 介绍 GreptimeDB 的架构、关键概念和工作原理，包括各组件的交互方式和数据处理流程。 +--- + +# 概述 + +## 架构 + +`GreptimeDB` 由以下关键组件组成： + +- `Frontend`：通过多种协议提供读写服务，并将请求转发到 `Datanode`。 +- `Datanode`：负责数据的持久化存储，例如存储到本地磁盘、S3 和 Azure Blob Storage 等。 +- `Metasrv` 元数据存储和分布式调度：协调 `Frontend` 和 `Datanode` 之间的操作。 + +![Architecture](/architecture-3.png) + +## 概念 + +为了更好地理解 `GreptimeDB`，需要介绍一些概念： + +- `table` 是 `GreptimeDB` 中存储用户数据的地方，有表结构和有序的主键。`table` 通过其分区键被分割成称为 `region`。 +- `region` 是表中的一个连续段，在某些关系型数据库中被视为分区。`region` 可以在多个 `datanode` 上复制，其中任何一个副本都可以支持读请求，但只有一个副本支持写请求。 +- `datanode` 存储并为 `frontend` 提供 `region` 服务。一个 `datanode` 可以服务多个 `region`，一个 `region` 可以由多个 `datanode` 服务。 +- `metasrv` 服务器存储集群的元数据，例如表、`datanode`、每个表的 `region` 等。它还协调 `frontend` 和 `datanode`。 +- `frontend` 有一个 catalog 实现，它从 `metasrv` 中获取元数据，告诉相应的组件哪个 `table` 的 `region` 由哪个 `datanode` 提供服务。 +- `frontend` 是一个无状态服务，用于接收客户端的请求。它作为 proxy 根据 catalog 中的信息将读取和写入请求转发到相应的 `datanode`。 +- 一个 `table` 的时间线(time-series)由其主键标识。因为 `GreptimeDB` 是一个时间序列数据库，所以每个 `table` 必须有一个时间戳列。`table` 中的数据将按其主键和时间戳排序，但顺序的实际实现方式比较特殊，可能会在将来发生变化。 + +## 工作原理 + +![Interactions between components](/how-it-works.png) + +在深入了解每个组件之前，让我们先从高层次上了解一下 GreptimeDB 的工作原理。 + +- 用户可以通过各种协议与数据库交互，例如使用 `InfluxDB line Protocol` 插入数据，然后使用 SQL 或 PromQL 查询数据。`frontend` 是用户或客户端连接和操作数据库的组件，因此在其后面隐藏了 `datanode` 和 `metasrv`。 +- 假设用户向 `frontend` 实例发送了 HTTP 请求来插入数据。当 `frontend` 接收到请求时，它会使用相应的协议解析器解析请求正文，并从 `metasrv` 的 catalog 中找到要写入的表。 +- `frontend` 依靠推拉结合的策略缓存来自 `metasrv` 的元数据，因此它知道应将请求发送到哪个 `datanode`，或者更准确地说，应该发送到哪个 `region`。如果请求的内容需要存储在不同的 `region` 中，则请求可能会被拆分并发送到多个 `region`。 +- 当 `datanode` 接收到请求时，它将数据写入 `region` 中，然后将响应发送回 `frontend`。写入 `region` 也意味着将数据写入底层的存储引擎中，该引擎最终将数据放置在持久化存储中。 +- 当 `frontend` 从目标 `datanode`s 接收到所有响应时，就会将结果返回给用户。 + +有关每个组件的更多详细信息，请参阅以下指南： + +- [frontend][1] +- [datanode][2] +- [metasrv][3] + +[1]: frontend/overview.md +[2]: datanode/overview.md +[3]: metasrv/overview.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/integration-test.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/integration-test.md new file mode 100644 index 000000000..1e3b6cf4d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/integration-test.md @@ -0,0 +1,13 @@ +--- +description: 介绍 GreptimeDB 的集成测试，包括测试范围和如何运行这些测试。 +--- + +# 集成测试 + +## 介绍 + +集成测试使用 Rust 测试工具（`#[test]`）编写，与单元测试不同，它们被单独放置在 +[这里](https://github.com/GreptimeTeam/greptimedb/tree/main/tests-integration)。 +它涵盖了涉及多个组件的场景，其中一个典型案例是与 HTTP/gRPC 相关的功能。你可以查看 +其[文档](https://github.com/GreptimeTeam/greptimedb/blob/main/tests-integration/README.md)以获取更多信息。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/overview.md new file mode 100644 index 000000000..1366187cb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/overview.md @@ -0,0 +1,6 @@ +# 测试 + +## 介绍 + +我们的团队进行了大量测试，以确保 GreptimeDB 的行为。本章将介绍几种用于测试 GreptimeDB 的重要方法，以及如何使用它们。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/sqlness-test.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/sqlness-test.md new file mode 100644 index 000000000..4007a7509 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/sqlness-test.md @@ -0,0 +1,49 @@ +--- +description: 介绍 GreptimeDB 的 Sqlness 测试，包括测试文件类型、组织测试案例和运行测试的方法。 +--- + +# Sqlness 测试 + +## 介绍 + +SQL 是 `GreptimeDB` 的一个重要用户接口。我们为它提供了一个单独的测试套件（名为 `sqlness`）。 + +## Sqlness 手册 + +### 测试文件 + +Sqlness 有三种类型的文件 + +- `.sql`：测试输入，仅包含 SQL +- `.result`：预期的测试输出，包含 SQL 和其结果 +- `.output`：不同的输出，包含 SQL 和其结果 + +`.result` 和 `.output` 都是输出（执行结果）文件。区别在于 `.result` 是标准（预期）输出，而 `.output` 是错误输出。因此，如果生成了 `.output` 文件，意味着测试结果不同，测试失败。你应该检查变更日志来解决问题。 + +你只需要在 `.sql` 文件中编写测试 SQL，然后运行测试。第一次运行时会生成 `.output` 文件，因为没有 `.result` 文件进行比较。如果你确认 `.output` 文件中的内容是正确的，可以将其重命名为 `.result`，这意味着它是预期输出。 + +任何时候都应该只有两种文件类型，`.sql` 和 `.result` —— 否则，存在 `.output` 文件意味着测试失败。这就是为什么我们不应该在 `.gitignore` 中忽略 `.output` 文件类型，而是跟踪它并确保它不存在。 + +### 组织测试案例 + +输入案例的根目录是 `tests/cases`。它包含几个子目录，代表不同的测试模式。例如，`standalone/` 包含所有在 `greptimedb standalone start` 模式下运行的测试。 + +在第一级子目录下（例如 `cases/standalone`），你可以随意组织你的测试案例。Sqlness 会递归地遍历每个文件并运行它们。 + +## 运行测试 + +与其他测试不同，这个测试工具是以二进制目标形式存在的。你可以用以下命令运行它 + +```shell +cargo run --bin sqlness-runner +``` + +它会自动完成以下步骤：编译 `GreptimeDB`，启动它，抓取测试并将其发送到服务器，然后收集和比较结果。你只需要检查是否有新的 `.output` 文件。如果没有，恭喜你，测试通过了 🥳！ + +### 运行特定测试 + +```shell +cargo sqlness -t your_test +``` + +如果你指定了第二个参数，则只会执行名称中包含指定字符串的测试案例。Sqlness 还支持基于环境的过滤。过滤器接受正则表达式字符串，并会检查格式为 `env:case` 的案例名称。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/unit-test.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/unit-test.md new file mode 100644 index 000000000..0dfaf776d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/contributor-guide/tests/unit-test.md @@ -0,0 +1,27 @@ +--- +description: 介绍 GreptimeDB 的单元测试，包括如何编写、运行和检查测试覆盖率。 +--- + +# 单元测试 + +## 介绍 + +单元测试嵌入在代码库中，通常放置在被测试逻辑的旁边。它们使用 Rust 的 `#[test]` 属性编写，并可以使用 `cargo nextest run` 运行。 + +GreptimeDB 代码库不支持默认的 `cargo` 测试运行器。推荐使用 [`nextest`](https://nexte.st/)。你可以通过以下命令安装它： + +```shell +cargo install cargo-nextest --locked +``` + +然后运行测试（这里 `--workspace` 不是必须的） + +```shell +cargo nextest run +``` + +注意，如果你的 Rust 是通过 `rustup` 安装的，请确保使用 `cargo` 安装 `nextest`，而不是像 `homebrew` 这样的包管理器，否则会弄乱你的本地环境。 + +## 覆盖率 + +我们的持续集成（CI）作业有一个“覆盖率检查”步骤。它会报告有多少代码被单元测试覆盖。请在你的补丁中添加必要的单元测试。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/otlp-logs-integration.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/otlp-logs-integration.md new file mode 100644 index 000000000..58f9b233c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/otlp-logs-integration.md @@ -0,0 +1,22 @@ +GreptimeDB 是一个可观测性后端，能够通过 [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) 协议原生地消费 OpenTelemetry 日志。 + +#### API + +要通过 OpenTelemetry SDK 库将 OpenTelemetry 日志发送到 GreptimeDB，请使用以下信息： + +* **URL:** `https:///v1/otlp/v1/logs` +* **Headers:** + * `X-Greptime-DB-Name`: `` + * `Authorization`: `Basic` 认证，这是一个 Base64 编码的 `:` 字符串。更多信息，请参考 [鉴权](https://docs.greptime.cn/user-guide/deployments/authentication/static/) 和 [HTTP API](https://docs.greptime.cn/user-guide/protocols/http#authentication)。 + * `X-Greptime-Log-Table-Name`: ``（可选）- 存储日志的表名。如果未提供，默认表名为 `opentelemetry_logs`。 + * `X-Greptime-Log-Extract-Keys`: ``（可选）- 从属性中提取对应 key 的值到表的顶级字段。key 应以逗号（`,`）分隔。例如，`key1,key2,key3` 将从属性中提取 `key1`、`key2` 和 `key3`，并将它们提升到日志的顶层，设置为标签。如果提取的字段类型是数组、浮点数或对象，将返回错误。如果提供了 pipeline name，此设置将被忽略。 + * `X-Greptime-Log-Pipeline-Name`: ``（可选）- 处理日志的 pipeline 名称。如果未提供，将使用 `X-Greptime-Log-Extract-Keys` 来处理日志。 + * `X-Greptime-Log-Pipeline-Version`: ``（可选）- 处理日志的 pipeline 的版本。如果未提供，将使用 pipeline 的最新版本。 + +请求使用二进制 protobuf 编码负载，因此您需要使用支持 `HTTP/protobuf` 的包。 + +:::tip 提示 +包名可能会根据 OpenTelemetry 的更新而变化，因此我们建议您参考官方 OpenTelemetry 文档以获取最新信息。 +::: + +有关 OpenTelemetry SDK 的更多信息，请参考您首选编程语言的官方文档。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/otlp-metrics-integration.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/otlp-metrics-integration.md new file mode 100644 index 000000000..6e3cd7b71 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/otlp-metrics-integration.md @@ -0,0 +1,18 @@ +GreptimeDB 通过原生支持 [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) 协议，可以作为后端存储服务来接收 OpenTelemetry 指标数据。 + +### API + +使用下面的信息通过 Opentelemetry SDK 库发送 Metrics 到 GreptimeDB： + +* URL: `https:///v1/otlp/v1/metrics` +* Headers: + * `X-Greptime-DB-Name`: `` +* `Authorization`: `Basic` 认证，是 `:` 的 Base64 编码字符串。更多信息请参考 [鉴权](https://docs.greptime.cn/user-guide/deployments/authentication/static/) 和 [HTTP API](https://docs.greptime.cn/user-guide/protocols/http#authentication)。 + +请求中使用 binary protobuf 编码 payload，因此你需要使用支持 `HTTP/protobuf` 的包。例如，在 Node.js 中，可以使用 [`exporter-trace-otlp-proto`](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-proto)；在 Go 中，可以使用 [`go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp`](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp)；在 Java 中，可以使用 [`io.opentelemetry:opentelemetry-exporter-otlp`](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-exporter-otlp)；在 Python 中，可以使用 [`opentelemetry-exporter-otlp-proto-http`](https://pypi.org/project/opentelemetry-exporter-otlp-proto-http/)。 + +:::tip 注意 +包名可能会根据 OpenTelemetry 的发展发生变化，因此建议你参考 OpenTelemetry 官方文档以获取最新信息。 +::: + +请参考 Opentelementry 的官方文档获取它所支持的编程语言的更多信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/vector-integration.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/vector-integration.md new file mode 100644 index 000000000..498bff093 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/clients/vector-integration.md @@ -0,0 +1,16 @@ +Vector 是高性能的可观测数据管道。 +它原生支持 GreptimeDB 指标数据接收端。 +通过 Vector，你可以从各种来源接收指标数据，包括 Prometheus、OpenTelemetry、StatsD 等。 +GreptimeDB 可以作为 Vector 的 Sink 组件来接收指标数据。 + + + +启动 Vector: + +``` +vector -c sample.toml +``` + +请前往 [Vector GreptimeDB Configuration](https://vector.dev/docs/reference/sinks/greptimedb/) 查看更多配置项。 + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/migrate/_migrate-from-prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/migrate/_migrate-from-prometheus.md new file mode 100644 index 000000000..bd989340b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/migrate/_migrate-from-prometheus.md @@ -0,0 +1,30 @@ +GreptimeDB 可以用来存储 [Prometheus](https://prometheus.io/) 的时间序列数据。 +此外，GreptimeDB 通过其 HTTP API 支持 Prometheus 查询语言。 +这可以使你轻松将 Prometheus 的 long-term storage 切换到 GreptimeDB。 + +## 数据模型的区别 + +要了解 Prometheus 和 GreptimeDB 数据模型之间的差异，请参阅 Ingest Data 文档中的[数据模型](/user-guide/ingest-data/for-observerbility/prometheus.md#data-model)部分。 + +## Prometheus Remote Write + + + +## Prometheus HTTP API 与 PromQL + +GreptimeDB 通过其 HTTP API 支持 Prometheus 查询语言 (PromQL)。 + + +## 使用 Grafana 可视化数据 + +对于习惯使用 Grafana 可视化 Prometheus 数据的开发人员，你可以继续使用相同的 Grafana 仪表板来可视化存储在 GreptimeDB 中的数据。 + + +## 参考阅读 + +请参考以下博客文章查看 GreptimeDB 与 Prometheus 的集成教程及用户故事： + +- [如何配置 GreptimeDB 作为 Prometheus 的长期存储](https://greptime.com/blogs/2024-08-09-prometheus-backend-tutorial) +- [Scale Prometheus： K8s 部署 GreptimeDB 集群作为 Prometheus 长期存储](https://greptime.com/blogs/2024-10-07-scale-prometheus) +- [「用户故事」从 Thanos 到 GreptimeDB，我们实现了 Prometheus 高效长期存储](https://greptime.com/blogs/2024-10-16-thanos-migration-to-greptimedb) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/migrate/migrate-from-influxdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/migrate/migrate-from-influxdb.md new file mode 100644 index 000000000..cd7a3a5e3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/migrate/migrate-from-influxdb.md @@ -0,0 +1,257 @@ +本文档将帮助你了解 GreptimeDB 和 InfluxDB 的数据模型之间的区别，并指导你完成迁移过程。 + +## 数据模型的区别 + +要了解 InfluxDB 和 GreptimeDB 的数据模型之间的差异，请参考写入数据文档中的[数据模型](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md#数据模型)。 + +## 数据库连接信息 + +在写入或查询数据之前，需要了解 InfluxDB 和 GreptimeDB 之间的数据库连接信息的差异。 + +- **Token**：InfluxDB API 中的 token 用于身份验证，与 GreptimeDB 身份验证相同。 + 当使用 InfluxDB 的客户端库或 HTTP API 与 GreptimeDB 交互时，你可以使用 `` 作为 token。 +- **Organization**：GreptimeDB 中没有组织。 +- **Bucket**：在 InfluxDB 中，bucket 是时间序列数据的容器，与 GreptimeDB 中的数据库名称相同。 + + + +## 写入数据 + +GreptimeDB 兼容 InfluxDB 的行协议格式，包括 v1 和 v2。 +这意味着你可以轻松地从 InfluxDB 迁移到 GreptimeDB。 + +### HTTP API + +你可以使用以下 HTTP API 请求将 measurement 写入 GreptimeDB： + + + +### Telegraf + +GreptimeDB 支持 InfluxDB 行协议也意味着 GreptimeDB 与 Telegraf 兼容。 +要配置 Telegraf，只需将 GreptimeDB 的 URL 添加到 Telegraf 配置中： + + + +### 客户端库 + +使用 InfluxDB 客户端库写入数据到 GreptimeDB 非常直接且简单。 +你只需在客户端配置中包含 URL 和身份验证信息。 + +例如： + + + +除了上述语言之外，GreptimeDB 还支持其他 InfluxDB 支持的客户端库。 +你可以通过参考上面提供的连接信息代码片段，使用你喜欢的语言编写代码。 + +## 查询数据 + +GreptimeDB 不支持 Flux 和 InfluxQL，而是使用 SQL 和 PromQL。 + +SQL 是一种通用的用于管理和操作关系数据库的语言。 +具有灵活的数据检索、操作和分析功能， +减少了已经熟悉 SQL 的用户的学习曲线。 + +PromQL（Prometheus 查询语言）允许用户实时选择和聚合时间序列数据， +表达式的结果可以显示为图形，也可以在 Prometheus 的表达式浏览器中以表格数据的形式查看， +或通过 [HTTP API](/user-guide/query-data/promql.md#prometheus-http-api) 传递给外部系统。 + +假设你要查询过去 24 小时内记录的 `monitor` 表中的最大 CPU。 +在 InfluxQL 中，查询如下： + +```sql [InfluxQL] +SELECT + MAX("cpu") +FROM + "monitor" +WHERE + time > now() - 24h +GROUP BY + time(1h) +``` + +此 InfluxQL 查询计算 `monitor` 表中 `cpu`字段的最大值， +其中时间大于当前时间减去 24 小时，结果以一小时为间隔进行分组。 + +该查询在 Flux 中的表达如下： + +```flux [Flux] +from(bucket: "public") + |> range(start: -24h) + |> filter(fn: (r) => r._measurement == "monitor") + |> aggregateWindow(every: 1h, fn: max) +``` + +在 GreptimeDB SQL 中，类似的查询为： + +```sql [SQL] +SELECT + ts, + host, + AVG(cpu) RANGE '1h' as mean_cpu +FROM + monitor +WHERE + ts > NOW() - INTERVAL '24 hours' +ALIGN '1h' TO NOW +ORDER BY ts DESC; +``` + +在该 SQL 查询中， +`RANGE` 子句确定了 AVG(cpu) 聚合函数的时间窗口， +而 `ALIGN` 子句设置了时间序列数据的对齐时间。 +有关按时间窗口分组的更多详细信息，请参考[按时间窗口聚合数据](/user-guide/query-data/sql.md#按时间窗口聚合数据)文档。 + +在 PromQL 中，类似的查询为： + +```promql +avg_over_time(monitor[1h]) +``` + +要查询最后 24 小时的时间序列数据， +你需要执行此 PromQL 并使用 HTTP API 的 `start` 和 `end` 参数定义时间范围。 +有关 PromQL 的更多信息，请参考 [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) 文档。 + +## 可视化数据 + + + +## 迁移数据 + +你可以通过以下步骤实现从 InfluxDB 到 GreptimeDB 的数据无缝迁移： + +![Double write to GreptimeDB and InfluxDB](/migrate-influxdb-to-greptimedb.drawio.svg) + +1. 同时将数据写入 GreptimeDB 和 InfluxDB，以避免迁移过程中的数据丢失。 +2. 从 InfluxDB 导出所有历史数据，并将数据导入 GreptimeDB。 +3. 停止向 InfluxDB 写入数据，并移除 InfluxDB 服务器。 + +### 双写 GreptimeDB 和 InfluxDB + +将数据双写 GreptimeDB 和 InfluxDB 是迁移过程中防止数据丢失的有效策略。 +当使用 InfluxDB 的[客户端库](#client-libraries)时，你可以建立两个客户端实例，一个用于 GreptimeDB，另一个用于 InfluxDB。 +有关如何使用 InfluxDB 行协议将数据写入 GreptimeDB 的操作，请参考[写入数据](#write-data)部分。 + +如果无需保留所有历史数据， +你可以双写一段时间以积累所需的最新数据， +然后停止向 InfluxDB 写入数据并仅使用 GreptimeDB。 +如果需要完整迁移所有历史数据，请按照接下来的步骤操作。 + +### 从 InfluxDB v1 服务器导出数据 + +创建一个临时目录来存储 InfluxDB 的导出数据。 + +```shell +mkdir -p /path/to/export +``` + +使用 InfluxDB 的 [`influx_inspect export` 命令](https://docs.influxdata.com/influxdb/v1/tools/influx_inspect/#export) 导出数据。 + +```shell +influx_inspect export \ + -database \ + -end \ + -lponly \ + -datadir /var/lib/influxdb/data \ + -waldir /var/lib/influxdb/wal \ + -out /path/to/export/data +``` + +- `-database` 指定要导出的数据库。 +- `-end` 指定要导出的数据的结束时间。 +必须是[RFC3339 格式](https://datatracker.ietf.org/doc/html/rfc3339)，例如 `2024-01-01T00:00:00Z`。 +你可以使用同时写入 GreptimeDB 和 InfluxDB 时的时间戳作为结束时间。 +- `-lponly` 指定只导出行协议数据。 +- `-datadir` 指定数据目录的路径，请见[InfluxDB 数据设置](https://docs.influxdata.com/influxdb/v1/administration/config/#data-settings)中的配置。 +- `-waldir` 指定 WAL 目录的路径，请见[InfluxDB 数据设置](https://docs.influxdata.com/influxdb/v1/administration/config/#data-settings)中的配置。 +- `-out` 指定输出目录。 + +导出的 InfluxDB 行协议数据类似如下： + +```txt +disk,device=disk1s5s1,fstype=apfs,host=bogon,mode=ro,path=/ inodes_used=356810i 1714363350000000000 +diskio,host=bogon,name=disk0 iops_in_progress=0i 1714363350000000000 +disk,device=disk1s6,fstype=apfs,host=bogon,mode=rw,path=/System/Volumes/Update inodes_used_percent=0.0002391237988702021 1714363350000000000 +... +``` + +### 从 InfluxDB v2 服务器导出数据 + +创建一个临时目录来存储 InfluxDB 的导出数据。 + +```shell +mkdir -p /path/to/export +``` + +使用 InfluxDB 的 [`influx inspect export-lp` 命令](https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/export-lp/) 导出数据。 + +```shell +influxd inspect export-lp \ + --bucket-id \ + --engine-path /var/lib/influxdb2/engine/ \ + --end \ + --output-path /path/to/export/data +``` + +- `--bucket-id` 指定要导出的 bucket ID。 +- `--engine-path` 指定引擎目录的路径，请见[InfluxDB 数据设置](https://docs.influxdata.com/influxdb/v2.0/reference/config-options/#engine-path)中的配置。 +- `--end` 指定要导出的数据的结束时间。 +必须是[RFC3339 格式](https://datatracker.ietf.org/doc/html/rfc3339)，例如 `2024-01-01T00:00:00Z`。 +你可以使用同时写入 GreptimeDB 和 InfluxDB 时的时间戳作为结束时间。 +- `--output-path` 指定输出目录。 + +命令行的执行结果类似如下： + +```json +{"level":"info","ts":1714377321.4795408,"caller":"export_lp/export_lp.go:219","msg":"exporting TSM files","tsm_dir":"/var/lib/influxdb2/engine/data/307013e61d514f3c","file_count":1} +{"level":"info","ts":1714377321.4940555,"caller":"export_lp/export_lp.go:315","msg":"exporting WAL files","wal_dir":"/var/lib/influxdb2/engine/wal/307013e61d514f3c","file_count":1} +{"level":"info","ts":1714377321.4941633,"caller":"export_lp/export_lp.go:204","msg":"export complete"} +``` + +导出的 InfluxDB 行协议数据类似如下： + +```txt +cpu,cpu=cpu-total,host=bogon usage_idle=80.4448912910468 1714376180000000000 +cpu,cpu=cpu-total,host=bogon usage_idle=78.50167052182304 1714376190000000000 +cpu,cpu=cpu-total,host=bogon usage_iowait=0 1714375700000000000 +cpu,cpu=cpu-total,host=bogon usage_iowait=0 1714375710000000000 +... +``` + +### 导入数据到 GreptimeDB + +在将数据导入 GreptimeDB 之前，如果数据文件过大，建议将数据文件拆分为多个片段： + +```shell +split -l 100000 -d -a 10 data data. +# -l [line_count] 创建长度为 line_count 行的拆分文件。 +# -d 使用数字后缀而不是字母后缀。 +# -a [suffix_length] 使用 suffix_length 个字母来形成文件名的后缀。 +``` + +你可以使用 HTTP API 导入数据，如[写入数据](#写入数据)部分所述。 +下方提供的脚本将帮助你从文件中读取数据并将其导入 GreptimeDB。 + +假设你的当前位置是存储数据文件的目录： + +```shell +. +├── data.0000000000 +├── data.0000000001 +├── data.0000000002 +... +``` + +将 GreptimeDB 的连接信息设置到环境变量中： + +```shell +export GREPTIME_USERNAME= +export GREPTIME_PASSWORD= +export GREPTIME_HOST= +export GREPTIME_DB= +``` + +将数据导入到 GreptimeDB： + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/go-demo.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/go-demo.md new file mode 100644 index 000000000..eef904911 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/go-demo.md @@ -0,0 +1,58 @@ +在本节中，我们将创建一个快速开始的 Demo，并展示收集 host 指标并发送到 GreptimeDB 的核心代码。该 Demo 基于[OTLP/HTTP](https://opentelemetry.io/)。你可以在 [GitHub](https://github.com/GreptimeCloudStarters/quick-start-go) 上获取整个 Demo 以作参考。 + +首先，创建一个名为 `quick-start-go` 的新目录来托管我们的项目，然后在根目录中运行命令 `go mod init quick-start` 生成一个`go.mod`文件，该文件在 Go 中用于做包管理。 + +接下来，创建一个名为 `app.go` 的新文件并安装所需的 OpenTelemetry 依赖： + +```shell +go get go.opentelemetry.io/otel@v1.16.0 \ + go.opentelemetry.io/contrib/instrumentation/host@v0.42.0 \ + go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp@v0.39.0 +``` + +安装所需的包后，在 `app.go` 中编写代码创建一个 metric exporter 对象，将 metrics 发送到 GreptimeDB。 +请参考 [GreptimeDB](/user-guide/protocols/opentelemetry.md) 或 [GreptimeCloud](/greptimecloud/integrations/otlp.md) 中的 OTLP 集成文档获取 exporter 的相关配置。 + +```go +auth := base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("%s:%s", *username, *password))) +exporter, err := otlpmetrichttp.New( + context.Background(), + otlpmetrichttp.WithEndpoint(*dbHost), + otlpmetrichttp.WithURLPath("/v1/otlp/v1/metrics"), + otlpmetrichttp.WithHeaders(map[string]string{ + "x-greptime-db-name": *db, + "Authorization": "Basic " + auth, + }), + otlpmetrichttp.WithTimeout(time.Second*5), +) + +if err != nil { + panic(err) +} + +reader := metric.NewPeriodicReader(exporter, metric.WithInterval(time.Second*2)) +``` + +将 exporter 附加到 MeterProvider 并开始收集 host metrics： + +```go +res := resource.NewWithAttributes( + semconv.SchemaURL, + semconv.ServiceName("quick-start-go"), +) + +meterProvider := metric.NewMeterProvider( + metric.WithResource(res), + metric.WithReader(reader), +) + +log.Print("Sending metrics...") +err = appHost.Start(appHost.WithMeterProvider(meterProvider)) +if err != nil { + log.Fatal(err) +} +``` + +请参考 [OpenTelemetry 文档](https://opentelemetry.io/docs/instrumentation/go/) 获取有关代码的更多详细信息。 + +恭喜你完成了 Demo 的核心部分！现在可以按照 [GitHub 库](https://github.com/GreptimeCloudStarters/quick-start-go)中 `README.md` 文件中的说明运行完整的 Demo。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/influxdb-demo.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/influxdb-demo.md new file mode 100644 index 000000000..aaada18b8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/influxdb-demo.md @@ -0,0 +1,57 @@ +我们将编写一个 Bash 脚本，并展示收集 host metrics 并将其发送到 GreptimeDB 的核心代码。您可以在 [GitHub](https://github.com/GreptimeCloudStarters/quick-start-influxdb-line-protocol) 上查看完整的 Demo。 + +首先，创建一个名为 `quick-start-influxdb` 的新目录来托管我们的项目，然后创建一个名为 `quick-start.sh` 的新文件并使其可执行： + +```bash +touch quick-start.sh +chmod +x quick-start.sh +``` + +在脚本中收集 CPU 和内存指标，并将数据格式化为 InfluxDB line protocol 格式： + +```bash +#!/bin/bash + +generate_data() +{ + unameOut="$(uname -s)" + case "${unameOut}" in + Linux*) + user_cpu_util=$(top -bn1 | grep "Cpu(s)" | awk '{print $2 + $4}') + sys_cpu_util=$(top -bn1 | grep "Cpu(s)" | awk '{print $6}') + idle_cpu_util=$(top -bn1 | grep "Cpu(s)" | awk -F "," '{print $4}' | awk -F " " '{print $1}') + mem_util=$(free | grep Mem | awk '{print $3}') + ;; + Darwin*) + user_cpu_util=$(top -l 1 | awk '/^CPU usage: / { print substr($3, 1, length($3)-1) }') + sys_cpu_util=$(top -l 1 | awk '/^CPU usage: / { print substr($5, 1, length($5)-1) }') + idle_cpu_util=$(top -l 1 | awk '/^CPU usage: / { print substr($7, 1, length($7)-1) }') + mem_util=$(top -l 1 | awk '/^PhysMem:/ { print substr($6, 1, length($6)-1) }') + ;; + *) + user_cpu_util=$(shuf -i 10-15 -n 1) + sys_cpu_util=$(shuf -i 5-10 -n 1) + idle_cpu_util=$(shuf -i 70-80 -n 1) + mem_util=$(shuf -i 50-60 -n 1) + esac + now=$(($(date +%s)*1000000000)) + cat <` to any timeseries scraped from this config. + - job_name: 'node' + static_configs: + - targets: ['node_exporter:9100'] + +remote_write: + - url: https:///v1/prometheus/write?db= + basic_auth: + username: + password: +``` + +通过上面的配置文件，Prometheus 从 node exporter 中抓取指标并将其发送到 GreptimeDB。有关 ``, ``, `` 和 `` 的信息，请参考 [GreptimeDB](/user-guide/integrations/prometheus.md) 或 [GreptimeCloud](/greptimecloud/integrations/prometheus.md) 中的 Prometheus 文档。 + +最后启动 Docker 容器： + +```bash +docker-compose up +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/python-demo.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/python-demo.md new file mode 100644 index 000000000..1a0ba4b44 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/python-demo.md @@ -0,0 +1,65 @@ +### 准备 + +- [Python 3.10+](https://www.python.org) + +### 示例 Demo + +在本节中，我们将创建一个快速开始的 Demo，并展示收集 host 指标并发送到 GreptimeDB 的核心代码。该 Demo 基于[OTLP/HTTP](https://opentelemetry.io/)。你可以在 [GitHub](https://github.com/GreptimeCloudStarters/quick-start-python) 上获取整个 Demo 以作参考。 + +首先，创建一个名为 `quick-start-python` 的新目录来托管我们的项目，然后创建文件 `requirements.txt` 并添加以下内容： + +```txt +opentelemetry-api==1.19.0 +opentelemetry-exporter-otlp-proto-common==1.19.0 +opentelemetry-exporter-otlp-proto-http==1.19.0 +opentelemetry-instrumentation==0.40b0 +opentelemetry-instrumentation-system-metrics==0.40b0 +opentelemetry-proto==1.19.0 +opentelemetry-sdk==1.19.0 +``` + +安装依赖： + +```bash +pip install -r requirements.txt +``` + +安装所需的包后，创建名为 `main.py` 的新文件并编写代码创建一个 metric exporter 对象，将 metrics 发送到 GreptimeDB。 +请参考 [GreptimeDB](/user-guide/protocols/opentelemetry.md) 或 [GreptimeCloud](/greptimecloud/integrations/otlp.md) 中的 OTLP 集成文档获取 exporter 的相关配置。 + +```python +from opentelemetry import metrics +from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor +from opentelemetry.sdk.resources import SERVICE_NAME, Resource +from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter + +auth = f"{username}:{password}" +b64_auth = base64.b64encode(auth.encode()).decode("ascii") +endpoint = f"https://{host}/v1/otlp/v1/metrics" +exporter = OTLPMetricExporter( + endpoint=endpoint, + headers={"Authorization": f"Basic {b64_auth}", "x-greptime-db-name": db}, + timeout=5) +``` + +将 exporter 附加到 MeterProvider 并开始收集 host metrics： + +```python +metric_reader = PeriodicExportingMetricReader(exporter, 5000) +provider = MeterProvider(resource=resource, metric_readers=[metric_reader]) + +# Sets the global default meter provider +metrics.set_meter_provider(provider) +configuration = { + "system.memory.usage": ["used", "free", "cached"], + "system.cpu.time": ["idle", "user", "system", "irq"], + "process.runtime.memory": ["rss", "vms"], + "process.runtime.cpu.time": ["user", "system"], +} +SystemMetricsInstrumentor(config=configuration).instrument() + +``` + +请参考 [OpenTelemetry 文档](https://opentelemetry.io/docs/instrumentation/python/getting-started/) 获取有关代码的更多详细信息。 + +恭喜你完成了 Demo 的核心部分！现在可以按照 [GitHub 库](https://github.com/GreptimeCloudStarters/quick-start-python)中 `README.md` 文件中的说明运行完整的 Demo。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md new file mode 100644 index 000000000..cb980144c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md @@ -0,0 +1,68 @@ +--- +description: 介绍 GreptimeDB 中基于双活互备的灾难恢复解决方案，包括不同读写模式的 RPO 和 RTO 目标，以及故障转移的处理方法。 +--- + +# 基于双活互备的 DR 解决方案 + +## RPO + +在 GreptimeDB 的“双活互备”架构中，有两个节点，分别独立部署了 GreptimeDB 服务。这两个节点都可以提供客户端执行读写的能力。然而，为了达到 +RTO 和 RPO 的目标，我们需要对两节点进行一些配置。首先我们介绍一下在“双活互备”架构中读写的模式。 + +对于读操作： + +- `SingleRead`：读操作只在一个节点上执行，结果直接返回给客户端。 +- `DualRead`：读操作在两个节点上都执行，结果将会合并去重后返回给客户端。 + +下图展示了这两种读操作模式的区别： + +![disaster-recovery-read-mode](/disaster-recovery-read-mode.png) + +对于写操作： + +- `SyncWrite`：写操作在两个节点上都执行，只有在两个节点都写成功后才会返回给客户端（成功）。 +- `AsyncWrite`：写操作仍然在两个节点上执行，但是在发起节点写成功后就会返回给客户端。另一个节点会异步地从发起节点接收写操作的复制。 + +下图展示了这两种写操作模式的区别： + +![disaster-recovery-write-mode](/disaster-recovery-write-mode.png) + +所以读写操作有四种组合，它们的 RPO 如下： + +| RPO | `SingleRead` | `DualRead` | +|--------------|--------------|------------| +| `SyncWrite` | 0 | 0 | +| `AsyncWrite` | 两节点之间的网络延迟 | 0 | + +在 `SyncWrite` 模式下，由于两个节点之间的写操作是同步的，所以 RPO 总是 0，无论读操作是什么模式。然而，`SyncWrite` +要求两个节点同时正常运行以处理写操作。如果你的工作负载是读多写少，并且可以容忍一段系统不可用的时间来恢复两个节点的健康状态，我们建议使用 `SyncWrite + SingleRead` +组合。 + +另一个可以达到 0 RPO 的组合是 `AsyncWrite + DualRead`。这是上面所说的相反情况，适用于写多读少的工作负载，两节点可用性的限制要求可以降低。 + +最后一个组合是 `AsyncWrite + SingleRead`。这是对两节点可用性最宽松的要求。如果两个节点之间的网络状况良好，并且节点可以被可靠地托管，例如，两个节点托管在一个 +AZ（可用区，或“数据中心”）内的虚拟机系统中，你可能更倾向这种组合。当然，只要记住 RPO 不是 0。 + +## RTO + +为了保持我们的双活互备架构的最低需求，我们没有要求第三个节点或第三个服务来处理 GreptimeDB 的故障转移。一般来说，有几种方法可以处理故障转移： + +- 通过一个 LoadBalancer。如果你可以额外腾出另一个节点来部署一个 LoadBalancer + 如 [Nginx](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/)，或者你有其他 LoadBalance + 服务，我们推荐这种方式。 + DR-LoadBalancer +- 通过客户端 SDK 的故障转移机制。例如，如果你使用 MySQL Connector/j，你可以通过在连接 URL + 中设置多个主机和端口来配置故障转移（参见其[文档](https://dev.mysql.com/doc/connector-j/en/connector-j-config-failover.html) + ）。PostgreSQL 的驱动程序[也有相同的机制](https://jdbc.postgresql.org/documentation/use/#connection-fail-over) + 。这是处理故障转移最简单的方法，但并不是每个客户端 SDK 都支持这种故障转移机制。 + DR-SDK +- 内部的 endpoint 更新机制。如果你可以检测到节点的故障，那么就可以在你的代码中更新 GreptimeDB 的 endpoint。 + +:::tip NOTE +请参考 "[解决方案比较](/user-guide/administration/disaster-recovery/overview.md#解决方案比较)" 来比较不同灾难恢复解决方案的 RPO 和 RTO。 +::: + +## 总结 + +在 GreptimeDB 的“双活互备”架构中，你可以选择不同的读写模式组合来实现你的 RPO 目标。至于 RTO，我们依赖外部机制来处理故障转移。一个 +LoadBalancer 是最适合的。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/administration/disaster-recovery/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/administration/disaster-recovery/overview.md new file mode 100644 index 000000000..0f56d79fe --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/administration/disaster-recovery/overview.md @@ -0,0 +1,11 @@ +--- +description: 概述 GreptimeDB Enterprise 中的灾难恢复解决方案，特别是基于双活互备的 DR 解决方案，并提供相关链接以获取更多信息。 +--- + +# 概述 + +作为分布式数据库，GreptimeDB 提供了不同的灾难恢复（DR）解决方案。 + +请参考 GreptimeDB OSS 文档中的[灾难恢复概述](/user-guide/administration/disaster-recovery/overview.md)了解 Greptime 提供的所有灾难恢复解决方案。本章节仅介绍在 GreptimeDB Enterprise 中提供的解决方案。 + +- [基于双活互备的 DR 解决方案](./dr-solution-based-on-active-active-failover.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/autopilot/region-balancer.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/autopilot/region-balancer.md new file mode 100644 index 000000000..c7813e250 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/autopilot/region-balancer.md @@ -0,0 +1,38 @@ +--- +description: 介绍 Region Balancer 插件，通过配置窗口大小和负载阈值来均衡 Datanode 上的 Region 写入负载，避免频繁迁移。 +--- + +# Region Balancer + +该插件用于均衡 Datanode 上的 Region 写入负载，通过指定的窗口大小和负载阈值来避免频繁的 Region 迁移。 + +```toml +[[plugins]] +[plugins.region_balancer] + +max_window = "45s" + +window_stability_threshold = 2 + +min_load_threshold = "10MB" + +tick_interval = "45s" +``` + +## 配置项说明 + +- `max_window`: string + - **说明**: 滑动窗口的时间跨度，用于计算区域负载的短期平均值。窗口期内的负载变化会被平滑，减轻短期突增对负载均衡的影响。 + - **单位**: 时间（支持格式：`"45s"` 表示 45 秒）。 + - **建议**: 根据集群负载波动情况配置，较大的窗口会使负载均衡响应更平稳。 +- `window_stability_threshold`: integer + - **说明**: 连续多少个窗口必须满足触发条件后，才会进行迁移操作。该阈值用于防止频繁的平衡操作，只在持续不均衡的情况下进行 Region 迁移。 + - **建议**: 较大的值会延迟再平衡的触发，适用于负载波动较大的系统；值为 2 表示需要至少两个连续窗口符合条件。 +- `min_load_threshold`: string + - **说明**: 触发 Region 迁移的最小写负载阈值（每秒字节数）。当节点的负载低于该值时，将不会触发迁移。 + - **单位**: 字节（例如，`"10MB"` 表示 10 MiB）。 + - **建议**: 设置为合理的最小值，防止小负载情况触发迁移。值可以根据系统实际流量进行调整。 +- `tick_interval`: string + - **说明**: 平衡器的运行间隔时间，控制负载均衡任务的触发频率。 + - **单位**: 时间（例如，"45s" 表示 45 秒）。 + - **建议**: 根据系统的响应速度和负载变化频率设置。较短的间隔可以更快响应负载变化，但可能增加系统开销。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/deployments/audit-logging.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/deployments/audit-logging.md new file mode 100644 index 000000000..bb2e24b81 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/deployments/audit-logging.md @@ -0,0 +1,80 @@ +--- +description: 介绍 GreptimeDB 中的审计日志功能，包括审计日志的格式、配置方法及注意事项，帮助用户监控数据库操作并确保合规性。 +--- + +# 审计日志 + +数据库的审计日志记录了对数据库执行的操作。审计日志有助于监控用户活动，检测可疑操作，并确保组织内外的合规性。本文档提供了 +GreptimeDB 中审计日志的概述以及如何配置它。 + +## 概述 + +一条在 GreptimeDB 上执行的语句（SQL 或 PromQL）会被记录在审计日志中（当然，前提是已经将其配置为需要被审计）。以下是审计日志中的一条示例记录： + +```json +{ + "time": "2024-11-05T06:13:19.903713Z", + "user": "greptime_user", + "source": "Mysql", + "class": "Ddl", + "command": "Create", + "object_type": "Database", + "object_names": [ + "audit_test" + ], + "statement": "CREATE DATABASE audit_test" +} +``` + +正如您所见，一条审计日志的记录被格式化为 JSON 字符串。它包含以下字段： + +- `time`: 语句执行的时间。格式为带有 UTC 时区的 ISO 8601 日期和时间的字符串。 +- `user`: 发送该请求的用户。 +- `source`: 请求的来源，也即用于连接到 GreptimeDB 的协议。 +- `class`: 语句的类别，如 "Read"、"Write" 或 "DDL" 等。 +- `command`: 语句的命令，如 "Select"、"Insert" 或 "Create" 等。 +- `object_type`: 语句操作的对象的类型，如 "Database"、"Table" 或 "Flow" 等。 +- `object_names`: 语句操作的对象的名称。 +- `statement`: 语句本身。 + +## 配置 + +审计日志作为 GreptimeDB 的插件提供。要启用并配置它，请将以下 TOML 添加到 GreptimeDB 配置文件中： + +```toml +[[plugins]] +# 将审计日志插件添加到 GreptimeDB 中。 +[plugins.audit_log] +# 是否启用审计日志，默认为 true。 +enable = true +# 存储审计日志文件的目录。默认为 "/tmp" 中的一个目录。 +dir = "/tmp/greptimedb/logs/" +# 允许审计的语句的来源。此选项作为过滤器：如果语句不来自这些配置的来源之一，则不会记录在审计日志中。 +# 多个来源用逗号（","）分隔。 +# 所有可配置的来源是 "Http"、"Mysql" 和 "Postgres"。 +# 一个特殊的 "all"（默认值）表示所有来源。 +sources = "all" +# 允许审计的语句的类别。此选项作为过滤器：如果语句的类别不匹配这些配置的值之一，则不会记录在审计日志中。 +# 多个类别用逗号（","）分隔。 +# 所有可配置的类别是 "Read"、"Write"、"Admin"、"DDL" 和 "Misc"。 +# 一个特殊的 "all" 表示所有类别。默认值为 "DDL" 和 "Admin"。 +classes = "ddl,admin" +# 允许审计的语句的命令。此选项作为过滤器：如果语句的命令不匹配这些配置的值之一，则不会记录在审计日志中。 +# 多个命令用逗号（","）分隔。 +# 所有可配置的命令是 "Promql"、"Select"、"Copy"、"Insert"、"Delete"、"Create"、"Alter"、"Truncate"、"Drop"、"Admin" 和 "Misc"。 +# 一个特殊的 "all"（默认值）表示所有命令。 +commands = "all" +# 允许审计的对象类型。此选项作为过滤器：如果语句的目标对象不匹配这些配置的值之一，则不会记录在审计日志中。 +# 多个对象类型用逗号（","）分隔。 +# 所有可配置的对象类型是 "Database"、"Table"、"View"、"Flow"、"Index" 和 "Misc"。 +# 一个特殊的 "all"（默认值）表示所有对象类型。 +object_types = "all" +# 保留的审计日志文件的最大数量。默认为 30。 +# 审计日志每天生成一个新的。 +max_log_files = 30 +``` + +## 注意 + +如果没有正确配置的话，审计日志可能会非常庞大。例如，在业务繁忙的 GreptimeDB 中，将 "`all`" 设置给所有的 `sources`，`classes`， +`commands` 和 `object_types` 会记录在 GreptimeDB 上执行的所有语句，导致一个非常大的审计日志文件。这可能会轻易地耗尽磁盘空间。因此，强烈建议合理地配置审计日志插件以避免这种情况。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/deployments/authentication.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/deployments/authentication.md new file mode 100644 index 000000000..9f30e0a6c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/deployments/authentication.md @@ -0,0 +1,82 @@ +--- +description: 介绍 GreptimeDB Enterprise 中的 LDAP 鉴权功能，包括 simple bind 和 search bind 两种模式的配置示例及使用方法。 +--- + +# LDAP 鉴权 + +除了 GreptimeDB OSS 中内置的 [Static User Provider](/user-guide/deployments/authentication/static.md)， +GreptimeDB Enterprise 还提供了连接到外部 LDAP 服务器进行身份验证的功能。 + +## 配置 + +与 [PostgreSQL 中的 LDAP 机制相似](https://www.postgresql.org/docs/current/auth-ldap.html)， 在 GreptimeDB 中，LDAP 鉴权也分为两种模式："simple bind" 和 "search bind"。 + +在 "simple bind" 模式下，GreptimeDB 会构造一个格式为 `{prefix}{username}{suffix}` 的 "DN"(distinguished name) +，并使用客户端传来的密码向 LDAP 服务发起”绑定 (bind)“。绑定的结果就是鉴权的结果。一个典型配置是，`prefix` 参数指定 `cn=`， +`suffix` 用于指定 DN 的其余部分。`username` 将会被替换为客户端发来的用户名。 + +以下一个 LDAP user provider "simple bind" 模式的配置文件示例： + +```toml +# LDAP 服务地址。 +server = "127.0.0.1" +# LDAP 服务端口。 +port = 636 +# 设置为 "ldap" 以使用 LDAP scheme，"ldaps" 以使用 LDAPS。 +# GreptimeDB 和 LDAP 服务之间的连接一开始时是未加密的。连接建立后升级到 TLS。这是 LDAPv3 的 "StartTLS" 标准。 +scheme = "ldaps" + +# LDAP 鉴权模式。`bind = "simple"` 和 `bind = "search"` 只能选择其一。 +[auth_mode] +# 以下配置仅在 simple bind 模式下使用： +bind = "simple" +# 当进行 simple bind 鉴权时，用于构造绑定 DN 的前缀。 +prefix = "cn=" +# 当进行 simple bind 鉴权时，用于构造绑定 DN 的后缀。 +suffix = ",dc=example,dc=com" +``` + +在 "search bind" 模式中，GreptimeDB 首先会使用配置文件中设置的固定用户名和密码（`bind_dn` 和 `bind_passwd`）尝试绑定到 LDAP +目录。然后 GreptimeDB 会在 LDAP 目录中搜索尝试登录到数据库的用户。搜索将在 `base_dn` 下的子树中进行，由 `search_filter` +过滤，并尝试对 `search_attribute` 中指定的属性进行精确匹配。一旦在搜索中找到用户，GreptimeDB +会以此用户重新绑定到目录，使用客户端指定的密码，以验证登录是否正确。这种方法允许用户对象在 LDAP 目录中的位置更加灵活，但会导致向 +LDAP 服务器发出两个额外的请求。 + +以下 toml 片段展示了 GreptimeDB LDAP user provider "search bind" 模式的配置文件示例。在上面的 "simple bind" 模式配置文件中显示的 +`server`、`port` 和 `scheme` 的公共部分被省略了： + +```toml +[auth_mode] +# 以下配置仅在 search bind 模式下使用： +bind = "search" +# 进行 search bind 鉴权时，开始搜索用户的根 DN。 +base_dn = "ou=people,dc=example,dc=com" +# 进行 search bind 鉴权时，首先进行绑定的用户 DN。 +bind_dn = "cn=admin,dc=example,dc=com" +# 进行 search bind 鉴权时，首先进行绑定的用户密码。 +bind_passwd = "secret" +# 进行 search bind 鉴权时，用于匹配的用户属性。 +# 如果未指定属性，则将使用 uid 属性。 +search_attribute = "cn" +# 进行 search bind 鉴权时，使用的搜索过滤器。 +# "$username" 将被替换为客户端传来的用户名。 +# 这允许比 search_attribute 更灵活的用户搜索。 +search_filter = "(cn=$username)" +``` + +## 在 GreptimeDB 中使用 LDAP User Provider + +要使用 LDAP User Provider，首先参照上文配置你的 LDAP 鉴权模式，然后在启动 GreptimeDB 时使用 `--user-provider` 参数，将其设置为 +`ldap_user_provider:`。例如，如果你有一个配置文件是 `/home/greptimedb/ldap.toml`，你可以使用以下命令启动一个 +standalone GreptimeDB： + +```shell +greptime standalone start --user-provider=ldap_user_provider:/home/greptimedb/ldap.toml +``` + +现在你就可以使用你的 LDAP 用户账户创建一个连接到 GreptimeDB 了。 + +:::tip 注意 +如果你使用 MySQL CLI 连接到配置了 LDAP User Provider 的 GreptimeDB，你需要在 MySQL CLI 中指定 +`--enable-cleartext-plugin`。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/overview.md new file mode 100644 index 000000000..1043b4492 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/overview.md @@ -0,0 +1,29 @@ +--- +description: GreptimeDB Enterprise 是为企业设计的时序数据库解决方案，提供了 BYOC、全托管云、边云一体等部署方式，并包含高级功能如双活互备的 DR 解决方案、LDAP 身份验证和审计日志。 +--- + +# 概述 + +GreptimeDB Enterprise 是专为满足企业特定需求而设计的强大时序数据库解决方案。 +除了开源版 GreptimeDB 中提供的所有功能外， +Enterprise 版还提供更多增强功能，帮助企业优化数据效率并显著降低成本，使企业能够使用时序数据做出更智能、更快速的决策。 + +解决方案包括： + +- **将数据库部署在你的云中 - Bring Your Own Cloud（BYOC**: 利用你自己的云基础设施来托管 GreptimeDB，提供广泛的定制和灵活性以满足你的业务需求。此服务包括对你的云资源的全面管理和强大的安全措施，以保护你的基础设施。 +- **全托管的独立云**: Greptime 团队提供完全托管的专用云环境，确保最佳性能、增强的安全性和卓越的可靠性，以满足你的企业需求。 +- **[边云一体解决方案](https://greptime.com/product/carcloud)**: 用于管理从边缘设备到云的时序数据，实现整个基础设施的实时分析和洞察的全面解决方案。 +- 针对物联网 (IoT)、可观测等行业的特定解决方案。 + +本章节概述了 GreptimeDB Enterprise 中可用的高级功能。有关获取试用或购买，请[联系我们](https://greptime.cn/contactus)。 + +## 功能 + +- [基于双活互备的 DR 解决方案](./administration/disaster-recovery/overview.md)：通过高级灾难恢复解决方案确保服务不中断和数据保护。 +- [LDAP 身份验证](./deployments/authentication.md)：使用基于 LDAP 的身份验证进行访问管理，确保系统安全。 +- [审计日志](./deployments/audit-logging.md): 用详细的审计日志追踪并记录用户的行为。 +- 更多功能文档即将推出！ + +## 发布说明 + +- [24.11](./release-notes/release-24_11.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/release-notes/release-24_11.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/release-notes/release-24_11.md new file mode 100644 index 000000000..04c59d097 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/enterprise/release-notes/release-24_11.md @@ -0,0 +1,54 @@ +--- +description: GreptimeDB 企业版 24.11 版本介绍了 Region Rebalance、管理控制台、LDAP User Provider、审计日志等新特性，并基于开源版 v0.10 引入了多项改进。 +--- + +# Release 24.11 + +我们很高兴向大家介绍 GreptimeDB 企业版的 24.11 版本。 + +## 特性亮点 + +### Region Rebalance + +为了增强 GreptimeDB 的弹性，Region Rebalance 功能允许在数据节点之间灵活地重新分配 +Region，无论是否由手动或动态触发。 + +这一前瞻性的措施带来了多个关键优势，包括均衡工作负载、优化资源利用，并确保在计划 +维护期间无缝运行。 + +### GreptimeDB 企业版管理控制台 + +我们带来了首个版本的 GreptimeDB 企业版管理控制台的用户界面。 + +此版本提供了一系列功能，包括： + +- 慢查询分析与调试 +- 详细的集群拓扑信息 +- 实时查看集群指标和日志 + +### LDAP User Provider + +将您自己的 LDAP 用户数据库与 GreptimeDB 企业版进行连接。我们实现了灵活的配置选项 +支持，无论是简单的还是复杂的认证机制。 + +### 审计日志 + +提供日志以跟踪数据库中的查询操作，并记录以下信息： + +- 查询类型：读取、写入、DDL 或其他 +- 命令：SELECT、INSERT 等 +- 对象类型：操作的目标对象，例如表、数据库等 + +### GreptimeDB 开源版特性 + +本版本基于 GreptimeDB 开源版 v0.10。开源基础引入了一些新功能： + +- 向量数据类型支持用于相似性搜索 +- 二级索引更新：用户现在可以在任何列上创建二级索引 +- 添加了表选项以更新 TTL、压缩参数和全文索引设置 +- JSON 数据类型和函数的支持 +- Loki Remote Write 的早期支持 +- 更多地理空间的通用函数（UDF）包括空间关系与测量、S2索引等。 + +请参阅[这里](https://docs.greptime.com/release-notes/release-0-10-0)以获取完整的 +变更日志。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/faq-and-others/faq.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/faq-and-others/faq.md new file mode 100644 index 000000000..de3d5e00a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/faq-and-others/faq.md @@ -0,0 +1,214 @@ +# 常见问题 + +### What would be the use cases for a time-series database? + +Common use cases for time-series database include but are not limited to the following four scenarios: + +1. Monitor applications and infrastructure +2. Store and access IoT data +3. Process self-driving vehicle data +4. Understand financial trends + +### TSDB features that you concern + +Please refer to [features that you concern](/user-guide/concepts/features-that-you-concern.md). + + +### How is the performance of GreptimeDB when used for non-time-series DB tables? + +GreptimeDB supports SQL and can deal with non-time-series data, especially efficient for high concurrent and throughput data writing. However, we develop GreptimeDB for a specific domain (time-series scenarios), and it doesn't support transactions and can't delete data efficiently. + +### Does GreptimeDB have a Go driver? + +Yes, you can find our Go SDK here: https://github.com/GreptimeTeam/greptimedb-ingester-go. + +Currently, we support MySQL protocol, you can check it out on the [user guide](/user-guide/protocols/mysql.md). + +HTTP API is also available, please see [this article](/user-guide/protocols/http.md) for more information. + +### Can GreptimeDB be used as a Rust alternative to Prometheus in the observable area? + +GreptimeDB has initially implemented native support for PromQL, with compatibility in GreptimeDB v0.7 surpassing 80%, making it comparable to VictoriaMetrics. + +### Is GreptimeDB compatible with Grafana? + +Yes, It's compatible with Grafana. + +GreptimeDB has an official Grafana plugin: [greptimedb-grafana-datasource](https://github.com/GreptimeTeam/greptimedb-grafana-datasource/) + +GreptimeDB also supports MySQL and PostgreSQL protocol, so you can use [MySQL or PG grafana +plugin](https://grafana.com/docs/grafana/latest/datasources/mysql/) to config GreptimeDB as a datasource. Then you can use SQL to query the data. + +Also, we are implementing PromQL natively which is frequently used with Grafana. + +### How does this compare to Loki? Is there a crate with Rust bindings available, preferably as tracing or logging subscriber? + +GreptimeDB has primarily focused on metrics, but will soon offer log storage and full-text search capabilities for logs. These features are expected to be available in version 0.9, which is anticipated to be released in early July. + +### When will GreptimeDB release its first GA version? + +The current version has not yet reached General Availability version standards. In line with our Greptime 2024 Roadmap, we plan to achieve a production-level version with the update to v1.0 in August. More details: https://github.com/GreptimeTeam/greptimedb/issues/3412. + +### Are there any plans/works done for the official UI for GreptimeDB so that it would be possible to check cluster status, list of tables, statistics etc？ + +Yes, we open sourced the dashboard for users to query and visualize their data. +Please check out our initial version on [GitHub Repo](https://github.com/GreptimeTeam/dashboard). + +### Does GreptimeDB support schemaless? + +Yes, GreptimeDB is a schemaless database without need for creating tables in advance. The table and columns will be created automatically when writing data with protocol gRPC, InfluxDB, OpentsDB, Prometheus remote write. + +For more information, refer to [this document](/user-guide/administration/manage-data/basic-table-operations.md#create-table). + +### How do you measure the passing rate of PromQL compatibility tests? Is there any testing framework？ + +There’s [an issue](https://github.com/GreptimeTeam/greptimedb/issues/1042) to track the PromQL compatibility tests passing rate. It's based on Prometheus's compliance test. + +### Where’s the name “Greptime” coming from? + +Because `grep` is the most useful command line tool on \*nix platform to search data, and time means time series. So Greptime is to help everybody to search/find value in time series data. + +### Is there any good first issue that can help beginners get started quickly? + +Yes, beginners can filter issues with ["good first issue"](https://github.com/GreptimeTeam/greptimedb/issues?q=label%3A%22good+first+issue%22) label. Additionally, more good first issues will be released on a rolling basis, so stay tuned! + +### Does GreptimeDB support dumping table-level data to S3? + +You can use the [`COPY TO` command](/reference/sql/copy.md#s3) to dump table-level data to S3. + +### Can [Nightingale](https://n9e.github.io) now be directly integrated with GreptimeDB? How is its compatibility? + +Currently, GreptimeDB's compatibility efforts are primarily focused on the implementation of native PromQL. Going forward, we will continue to enhance compatibility with MetricQL's extended syntax. + +### If I delete the database, can I use the `DROP DATABASE` command? + +Yes, the `DROP DATABASE` command has been implemented in version 0.8. You can refer to the official documentation for usage: [`Drop Database`](https://docs.greptime.com/reference/sql/drop#drop). + +### Are there any retention policy? + +We have implemented table level Time-To-Live (TTL) in [this PR](https://github.com/GreptimeTeam/greptimedb/pull/1052). You can refer to the TTL option of the table build statement [here](/user-guide/concepts/features-that-you-concern.md#can-i-set-ttl-or-retention-policy-for-different-tables-or-measurements). + +And since 0.8, GreptimeDB already supports database level `TTL` too, read the [CREATE DATABASE](/reference/sql/create.md#create-database). + +### What are the main differences between Greptime and another time-series database built on DataFusion like InfluxDB? + +At GreptimeDB, we share some technical similarities with InfluxDB, both using Datafusion, Arrow, Parquet, and built on object storage. However, we differ in several key aspects: + +- Open-Source Strategy: Unlike InfluxDB, which only open-sources its standalone version, our entire distributed cluster version is open-source. Our architecture can even run on edge Android systems. +- Distributed Architecture: Our architecture is more aligned with HBase's Region/RegionServer design. Our Write-Ahead Log (WAL) uses Kafka, and we're exploring a quorum-based implementation in the future. +- Workload and Services: We focus on a hybrid workload combining time series and analytics. This integration aims to enhance resource efficiency and real-time performance for users. We also offer [GreptimeCloud](https://greptime.com/product/cloud), a commercial cloud service. +- Storage Engine Design: Our pluggable storage engine is versatile. For scenarios with many small data tables, like in Prometheus, we have a dedicated Metrics storage engine. +- Query Language Support: We support PromQL for observability and SQL for data analysis, and incorporate Python for complex data processing. InfluxDB, on the other hand, uses InfluxQL and SQL. + +We're a young, rapidly evolving project and always looking to improve. For more details, visit [our Blog](https://greptime.com/blogs/) and [Contributor Guide](https://docs.greptime.com/contributor-guide/overview). We welcome your interest and contributions! + +### As a first-timer looking to contribute to GreptimeDB, where can I find a comprehensive guide to get started? + +Welcome! Please refer to our [contribution guide](https://github.com/GreptimeTeam/greptimedb/blob/main/CONTRIBUTING.md). For those new to GreptimeDB, we have a selected collection of [good first issues](https://github.com/GreptimeTeam/greptimedb/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+first+issue%22). Feel free to reach us in Slack channel anytime! + +### Can GreptimeDB be used for a large-scale internal metrics collection system similar to Fb's Gorilla or Google's Monarch, with a preference for in-memory data and high availability? Are there plans for asynchronous WAL or optional disk storage, and how is data replication handled without WAL? + +GreptimeDB supports asynchronous WAL and is developing a per-table WAL toggle for more control. A tiered storage approach, starting with in-memory caching, is also in development. For data replication, data flushed to remote stores like S3 is replicated independently of WAL. The details for tiered storage are tracked in issue [db#2516](https://github.com/GreptimeTeam/greptimedb/issues/2516). A remote WAL implementation based on Apache Kafka ensures the durability of unflushed data in cluster mode. + +### Does GreptimeDB have a way to handle absolute counters that can reset, like InfluxDB's non-negative differential? How do aggregations work with these counters, and is PromQL preferred over SQL for them? Also, is there a plan to integrate PromQL functions into SQL, similar to InfluxDB v3? + +GreptimeDB, like Prometheus, handles counters effectively. Functions like` reset()`, `rate()`, or `delta()` in GreptimeDB are designed to automatically detect and adjust for counter resets. While it's not recommended to use the `deriv()` function on a counter since it's meant for gauges, you can apply `rate()` to your counter and then use `deriv()`. PromQL is indeed more suitable for operations involving counters, given its origin in Prometheus. However, we are exploring the integration of PromQL functions into SQL for greater flexibility. If you're interested in implementing functions into GreptimeDB, we have documentation available which you can check out: [Greptime Documentation](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-write-aggregate-function.md). + +### What are the feature differences between the open-source version and the cloud version of GreptimeDB? + +Thank you for asking, here are some key points: + +- **Foundational Features**: The foundational features, including the ingestion protocol, SQL capabilities, and storage functions, are largely identical between the two versions. However, GreptimeCloud offers advanced SQL functions and additional features. +- **Fully Managed Service**: GreptimeCloud is a fully managed service that supports multi-tenancy, data encryption, and security audits for compliance, which are not available in the open-source version. +- **Enhanced Dashboard**: Another significant advantage of GreptimeCloud is its superior dashboard, which is more user-friendly and includes a unique Prometheus workbench. This workbench facilitates online editing of Prometheus dashboards and alert rules, as well as GitOps integration. +- **Specialized Solutions**: GreptimeCloud introduces specialized solutions like GreptimeAI, which leverages DBaaS technology. We are also expanding our offerings to include more innovative solutions, such as those for IoT. + +As mentioned, the cloud version offers more ready-to-use features to help you get started quickly. The core features are almost identical, especially on our dedicated plan. + +### What should I do if the region becomes `DOWNGRADED` and the tables on that node become read-only after the datanode restarts? Is there a way to automatically reactivate it? + +According to your configuration, the failover in metasrv, which may mark the region as `DOWNGRADED`, is disabled. Another procedure that may mark a region as `DOWNGRADED` is the region migration procedure. Please try running the region migration procedure and provide feedback for further assistance. + +### Is there a guide or suggestions for compiling GreptimeDB into a standalone binary with only the necessary modules and features for an embedded environment? + +We have prebuilt binaries for Android ARM64 platforms, which have been successfully used in some enterprise projects. However, these binaries are not available for bare metal devices, as some fundamental components of GreptimeDB require a standard library. + +### Is there a built-in SQL command like 'compaction table t1' that can be used for manual compaction? + +Of course, please use the `compact_table` function: + +```sql +-- Schedule a compaction for table test -- +ADMIN compact_table("test"); +``` + +There are many [administration functions](/reference/sql/admin.md#admin-functions) for database management. + +### Can GreptimeDB be used to store logs? + +- The current columnar storage structure can be used to store logs. For example, by setting a column's type to string (non-primary key), logs can be stored. Logs can be written and queried using the supported protocols, and the data can be stored in object storage (OSS/S3) with distributed scalability. + +- If logs can be parsed into structured dimensions, they can also be stored as tags (primary key). These tags can then be used for dimensional queries. + +- However, there are still a few key features missing. Firstly, full-text indexing (currently, LIKE queries can be used as a substitute). Secondly, specific syntax or SQL functions for log queries. Lastly, support for some unique log ingestion protocols. These features are under active development and are expected to be supported in version 0.9, anticipated for release in early July. However, it may not be a simple replacement for Elasticsearch (ES) since its query syntax needs further exploration. Currently, SQL is the primary query language. + +### How is the query performance for non-primary key fields? Can inverted indexes be set? Will the storage cost be lower compared to Elasticsearch? + +Currently, non-primary key fields (or non-tag fields) do not have default inverted indexes, and we have not yet provided a `CREATE INDEX` syntax. Inverted index support will be released in an upcoming iteration along with full-text indexing. Without indexes, queries rely on MPP brute-force scanning. Although there is some parallel processing, the efficiency may not be optimal. + +As for storage costs, they will certainly be lower. You can use containers and object storage directly without relying on disks, using small local disks for buffering/caching to speed up performance. GreptimeDB employs a tiered storage architecture. For more details, please refer to our documentation on architecture and storage location. + +### Is the Log-Structured Merge-Tree engine similar to Kafka's engine model? + +From a technical storage perspective, they are similar. However, the actual data formats differ: GreptimeDB reads and writes Parquet format, while Kafka uses its own RecordBatch format. To analyze time-series data temporarily stored in Kafka, it needs to be written into GreptimeDB first. + +You can replace Kafka with EMQX, which is also a message queue. Here is a reference example: [EMQX Data Integration with GreptimeDB](https://www.emqx.com/en). The process of writing data from Kafka to GreptimeDB is quite similar. + +As mentioned, to analyze the data, it must be written into GreptimeDB first. Consume Kafka messages and write them into GreptimeDB using the provided protocols. If analyzing data directly in Kafka is necessary, you might consider the KSQL project: [KSQL GitHub Repository](https://github.com/confluentinc/ksql). However, our past attempts with KSQL encountered several issues. + +We are also working on releasing a Kafka consumer component that will automate the consumption and writing process. + +### Are there limitations on the number of tables or columns in GreptimeDB? Does having many columns affect read and write performance? + +Generally, there are no strict limitations. With a few hundred tables, as long as there aren't many primary key columns, the impact on write performance is minimal (measured by the number of points written per second, not rows). + +Similarly, for reads, if queries only involve a subset of columns, the memory and computational load will not be significantly high. + +### Can tables be dynamically partitioned by day based on timestamps, or is this unnecessary because the timestamp field already has an index? + +GreptimeDB's data is distributed in timestamp order, so there is no need to additionally shard/partition by timestamp. It is recommended to shard by primary key instead. + +### How many servers are generally needed to set up a reliable GreptimeDB cluster, and how should Frontend, Datanode, and Metasrv be deployed? Should each node run all three services regardless of the number of nodes? + +A minimum of 3 nodes is required, with each node running the 3 services: metasrv, frontend, and datanode. However, the exact number of nodes depends on the scale of data being handled. + +It is not necessary to deploy all three services on each node. A small-sized cluster can be set up with 3 nodes dedicated to metasrv. Frontend and datanode can be deployed on equal nodes, with one container running two processes. + +For more general advice for deployment, please read [Capacity Plan](/user-guide/administration/capacity-plan.md). + +### Does GreptimeDB support inverted indexes, and does it use Tantivy? + +Since v0.7, GreptimeDB supports inverted indexes which are designed by ourselves, read the [Contributor Guide](/contributor-guide/datanode/data-persistence-indexing.md#inverted-index) for more information. + +We plan to integrate Tantivy into the upcoming 0.9 release for full-text search functionality, although we are not currently using it. + +### In v0.8, does the Flow Engine (pre-computation) feature support PromQL syntax for calculations? + +This is a good suggestion. Currently, the Flow Engine does not support PromQL syntax for calculations. We will evaluate this, as it seems theoretically feasible. + +### Will Metasrv support storage backends like MySQL or PostgreSQL? + +We have developed an abstraction layer for Metasrv, but it does not yet support RDBMS backends. Support for MySQL and PostgreSQL is planned. For further suggestions, please open an issue on our GitHub repository. + +### What is the best way to downsample interface traffic rates (maximum rate within every hour) from multiple NICs(network interface controller) across thousands of computers every 30 seconds, so that the data can be kept for many years? + +Using a flow table is the appropriate tool for this task. A simple flow task should suffice. The output of a flow task is stored in a normal table, allowing it to be kept indefinitely. + +### Why is there a performance drop in query response times after upgrading or restarting? + +Currently, GreptimeDB only builds indexes for persistent data. Therefore, query performance might improve after flushing buffered input data. The in-memory page cache for persistent files also needs to be warmed up by queries after restarting the instance. + +- Persistence Mechanism: Data is flushed periodically or when the buffered data size reaches a threshold. +- Cache Warm-up: Query performance improves as the in-memory page cache warms up. + +These mechanisms help stabilize and improve query performance after an upgrade. \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/faq-and-others/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/faq-and-others/overview.md new file mode 100644 index 000000000..abbc87d98 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/faq-and-others/overview.md @@ -0,0 +1,3 @@ +# 概述 + +In this section, we present the [most frequently asked questions](./faq.md) and some additional information. diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-cluster.md new file mode 100644 index 000000000..4feccc545 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-cluster.md @@ -0,0 +1,54 @@ +--- +description: 介绍如何在 Kubernetes 和 Docker Compose 中部署 GreptimeDB 集群，以支持水平扩展。 +--- + +# GreptimeDB 分布式集群 + +GreptimeDB 可以运行于 [cluster](/contributor-guide/overview.md) 模式以支持水平扩展。 + +## 在 Kubernetes 中部署 GreptimeDB 集群 + +对于生产环境，我们建议在 Kubernetes 中部署 GreptimeDB 集群。请参考 [在 Kubernetes 上部署](/user-guide/deployments/deploy-on-kubernetes/overview.md)。 + +## 使用 Docker Compose + +:::tip 注意 +虽然 Docker Compose 是运行 GreptimeDB 集群的便捷方法，但仅适用于开发和测试目的。 + +对于生产环境或基准测试，我们建议使用 Kubernetes。 +::: + +### 前置条件 + +使用 Docker Compose 是运行 GreptimeDB 集群的最简单方法。开始之前，请确保已经安装了 Docker。 + +### 步骤 1: 下载 Docker Compose 的 YAML 文件 + +``` +wget https://raw.githubusercontent.com/GreptimeTeam/greptimedb/VAR::greptimedbVersion/docker/docker-compose/cluster-with-etcd.yaml +``` + +### 步骤 2: 启动集群 + +``` +GREPTIMEDB_VERSION=VAR::greptimedbVersion \ +GREPTIMEDB_REGISTRY=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ +ETCD_REGISTRY=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + docker compose -f ./cluster-with-etcd.yaml up +``` + +如果集群成功启动，它将监听 4000-4003 端口。你可以通过参考 [快速开始](../quick-start.md#连接到-greptimedb) 访问集群。 + +### 清理 + +你可以使用以下命令停止集群： + +``` +docker compose -f ./cluster-with-etcd.yaml down +``` + +默认情况下，数据将被存储在 `/tmp/greptimedb-cluster-docker-compose`。如果你想清理数据，也可删除该目录。 + +## 下一步 + +学习如何使用 GreptimeDB：[快速开始](../quick-start.md#连接到-greptimedb)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-dashboard.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-dashboard.md new file mode 100644 index 000000000..bbd199732 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-dashboard.md @@ -0,0 +1,16 @@ +--- +description: 介绍 GreptimeDB 控制台的功能和使用方法，包括数据可视化和多种查询语言的支持。 +--- + +# GreptimeDB 控制台 + +数据可视化在时间序列数据分析时发挥着关键作用。为了帮助用户充分利用 GreptimeDB 的各种功能，GreptimeDB 提供了一个简单的[控制台](https://github.com/GreptimeTeam/dashboard)。 + +自 GreptimeDB v0.2.0 版本以来，控制台已经默认嵌入到 GreptimeDB 的 binary 文件中。在启动 [GreptimeDB 单机版](greptimedb-standalone.md)或[分布式集群](greptimedb-cluster.md)后，可以通过 URL `http://localhost:4000/dashboard` 访问控制台。控制台支持多种查询语言，包括 [SQL 查询](/user-guide/query-data/sql.md)和 [PromQL 查询](/user-guide/query-data/promql.md)。 + +我们提供不同种类的图表，可以根据不同的场景进行选择。当用户有足够的数据时，图表的内容将更加丰富。 + +![line](/dashboard-line.png) +![scatter](/dashboard-scatter.png) + +我们将持续开发和迭代这个开源项目，并计划将时间序列数据应用于监测、分析和其他相关领域的扩展。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-standalone.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-standalone.md new file mode 100644 index 000000000..e6e217fef --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/greptimedb-standalone.md @@ -0,0 +1,132 @@ +--- +description: 介绍如何在单机模式下安装和运行 GreptimeDB，包括使用二进制文件、Docker 和 Windows 的安装方法。 +--- + +# GreptimeDB 单机模式 + +## 安装 + +我们先通过最简单的配置来开始。有关 GreptimeDB 中可用的所有配置选项的详细列表，请参考[配置文档](/user-guide/deployments/configuration.md)。 + +### 二进制 + +你可以在[下载页面](https://greptime.cn/download)通过发布的最新稳定版本尝试使用 GreptimeDB。 + +### Linux 或 macOS + +如果你使用的是 Linux 或 macOS，可以通过以下命令下载 `greptime` binary 的最新版本： + +```shell +curl -fsSL \ + https://raw.githubusercontent.com/greptimeteam/greptimedb/main/scripts/install.sh | sh -s VAR::greptimedbVersion +``` + +下载完成后，binary 文件 `greptime` 将存储在当前的目录中。 + +你可以在单机模式下运行 GreptimeDB： + +```shell +./greptime standalone start +``` + +### Windows + +若您的 Windows 系统已开启 WSL([Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/about))，您可以直接打开一个最新的 Ubuntu 接着如上所示运行 GreptimeDB ！ + +否则请到我们的[官网](https://greptime.com/resources)下载并解压最新的 GreptimeDB for Windows 安装包。 + +在单机模式下运行 GreptimeDB，您可以在 GreptimeDB 二进制所在的文件夹下打开一个终端（比如 Powershell ），执行： + +```shell +.\greptime standalone start +``` + +### Docker + +请确保已经安装了 [Docker](https://www.docker.com/)。如果还没有安装，可以参考 Docker 官方的[文档](https://www.docker.com/get-started/)进行安装。 + +```shell +docker run -p 127.0.0.1:4000-4003:4000-4003 \ + -v "$(pwd)/greptimedb:/tmp/greptimedb" \ + --name greptime --rm \ + greptime-registry.cn-hangzhou.cr.aliyuncs.com/greptime/greptimedb:VAR::greptimedbVersion standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 +``` + +:::tip 注意事项 +为了防止不小心退出 Docker 容器，你可能想以 “detached” 模式运行它：在 `docker run` 命令中添加 `-d` 参数即可。 +::: + +数据将会存储在当前目录下的 `greptimedb/` 目录中。 + +如果你想要使用另一个版本的 GreptimeDB 镜像，可以从我们的 [GreptimeDB Dockerhub](https://hub.docker.com/r/greptime/greptimedb) 下载。 + +:::tip 注意事项 + +如果正在使用小于 [v23.0](https://docs.docker.com/engine/release-notes/23.0/) 的 Docker 版本，由于旧版本的 Docker Engine 中存在 [bug](https://github.com/moby/moby/pull/42681)，所以当你尝试运行上面的命令时，可能会遇到权限不足的问题。 + +你可以: + +1. 设置 `--security-opt seccomp=unconfined`： + + ```shell + docker run --security-opt seccomp=unconfined -p 4000-4003:4000-4003 \ + -v "$(pwd)/greptimedb:/tmp/greptimedb" \ + --name greptime --rm \ + greptime-registry.cn-hangzhou.cr.aliyuncs.com/greptime/greptimedb:VAR::greptimedbVersion standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 + ``` + +2. 将 Docker 版本升级到 v23.0.0 或更高; +::: + +## 绑定地址 + +GreptimeDB 默认绑定地址为 `127.0.0.1`。如果你需要能够接收来自所有地址的连接，可以通过以下参数启动。 + +:::danger 危险操作 + +如果运行 GreptimeDB 的计算机直接向互联网暴露服务，那么绑定 `0.0.0.0` 会十分危险，因为这将数据库实例暴露给互联网上的所有人。 + + + + + +```shell +./greptime standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 +``` + + + + + +```shell +docker run -p 0.0.0.0:4000-4003:4000-4003 \ + -v "$(pwd)/greptimedb:/tmp/greptimedb" \ + --name greptime --rm \ + greptime-registry.cn-hangzhou.cr.aliyuncs.com/greptime/greptimedb:VAR::greptimedbVersion standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 +``` + + + + + +你也可以参考[配置 GreptimeDB](/user-guide/deployments/configuration.md)文档在配置文件中修改绑定的地址。 + +## 下一步 + +学习如何使用 GreptimeDB：[快速开始](../quick-start.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/overview.md new file mode 100644 index 000000000..5981d170f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/installation/overview.md @@ -0,0 +1,32 @@ +--- +description: 介绍如何安装 GreptimeDB 以及启动后检查数据库健康状态的方法。 +--- + +# 概述 + +## 安装 + +根据以下说明安装 GreptimeDB： + +- [GreptimeDB 单机模式](greptimedb-standalone.md) +- [GreptimeDB 分布式集群](greptimedb-cluster.md) + +## 检查数据库健康状态 + +启动 GreptimeDB 后，你可以检查其状态以确保其正常运行。 + +```shell + +curl http://localhost:4000/health + +``` + +如果 GreptimeDB 实例正常运行，你将看到下面的响应： + +```json +{} +``` + +## 下一步 + +- [快速入门](/getting-started/quick-start.md)：使用 MySQL 或 PostgreSQL 客户端在 GreptimeDB 中写入和查询数据。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/overview.md new file mode 100644 index 000000000..5a8f5232f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/overview.md @@ -0,0 +1,6 @@ +# 概述 + +立即开始使用 GreptimeDB！ + +- [安装](./installation/overview.md)：安装 GreptimeDB 单机模式或分布式集群。 +- [快速开始](./quick-start.md)：使用你熟悉的协议或语言快速上手 GreptimeDB。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/quick-start.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/quick-start.md new file mode 100644 index 000000000..e833a8e29 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/getting-started/quick-start.md @@ -0,0 +1,380 @@ +--- +description: 介绍如何快速开始使用 GreptimeDB，包括连接数据库、创建表、写入数据、查询数据等核心功能。 +--- + +# 快速开始 + +在继续阅读之前，请确保你已经[安装了 GreptimeDB](./installation/overview.md)。 + +本指南通过引导你创建一个 metric 表和一个 log 表来介绍 GreptimeDB 的核心功能。 + +## 连接到 GreptimeDB + +GreptimeDB 支持[多种协议](/user-guide/protocols/overview.md)与数据库进行交互。 +在本快速入门文档中，我们使用 SQL 作为实例。 + +如果你的 GreptimeDB 实例运行在 `127.0.0.1` 中， +并且使用 MySQL 客户端默认端口 `4002` 或 PostgreSQL 客户端默认端口 `4003`， +你可以使用以下命令连接到数据库。 + +GreptimeDB 默认不开启[鉴权认证](/user-guide/deployments/authentication/overview.md)。 +在本章节中你可以在连接数据库时不提供用户名密码。 + +```shell +mysql -h 127.0.0.1 -P 4002 +``` + +或者 + +```shell +psql -h 127.0.0.1 -p 4003 -d public +``` + +## 创建表 + +假设你有一个名为 `grpc_latencies` 的表，用于存储的 gRPC 延迟。表 schema 如下： + +```sql +CREATE TABLE grpc_latencies ( + ts TIMESTAMP TIME INDEX, + host STRING, + method_name STRING, + latency DOUBLE, + PRIMARY KEY (host, method_name) +) with('append_mode'='true'); +``` + +- `ts`：收集指标时的时间戳，时间索引列。 +- `host`：主机名，tag 列。 +- `method_name`：RPC 请求方法的名称，tag 列。 +- `latency`：RPC 请求的延迟。 + +此外，还有一个名为 `app_logs` 的表用于存储日志： + +```sql +CREATE TABLE app_logs ( + ts TIMESTAMP TIME INDEX, + host STRING, + api_path STRING FULLTEXT, + log_level STRING, + log STRING FULLTEXT, + PRIMARY KEY (host, log_level) +) with('append_mode'='true'); +``` + +- `ts`：日志条目的时间戳，时间索引列。 +- `host`：主机名，tag 列。 +- `api_path`：API 路径，使用 `FULLTEXT` 进行索引以加速搜索。 +- `log_level`：日志级别，tag 列。 +- `log`：日志消息，使用 `FULLTEXT` 进行索引以加速搜索。 + +## 写入数据 + +让我们插入一些模拟数据来模拟收集的指标和错误日志。 + +假设有两个服务器 `host1` 和 `host2` 记录着 gRPC 延迟。 +从 `2024-07-11 20:00:10` 开始，`host1` 的延迟显著增加。 + +下图显示了 `host1` 的不稳定延迟。 + +unstable latencies + +使用以下 SQL 语句插入模拟数据。 + +在 `2024-07-11 20:00:10` 之前，主机正常运行： + +```sql +INSERT INTO grpc_latencies (ts, host, method_name, latency) VALUES + ('2024-07-11 20:00:06', 'host1', 'GetUser', 103.0), + ('2024-07-11 20:00:06', 'host2', 'GetUser', 113.0), + ('2024-07-11 20:00:07', 'host1', 'GetUser', 103.5), + ('2024-07-11 20:00:07', 'host2', 'GetUser', 107.0), + ('2024-07-11 20:00:08', 'host1', 'GetUser', 104.0), + ('2024-07-11 20:00:08', 'host2', 'GetUser', 96.0), + ('2024-07-11 20:00:09', 'host1', 'GetUser', 104.5), + ('2024-07-11 20:00:09', 'host2', 'GetUser', 114.0); +``` + +在 `2024-07-11 20:00:10` 之后，`host1` 的延迟变得不稳定： + +```sql + +INSERT INTO grpc_latencies (ts, host, method_name, latency) VALUES + ('2024-07-11 20:00:10', 'host1', 'GetUser', 150.0), + ('2024-07-11 20:00:10', 'host2', 'GetUser', 110.0), + ('2024-07-11 20:00:11', 'host1', 'GetUser', 200.0), + ('2024-07-11 20:00:11', 'host2', 'GetUser', 102.0), + ('2024-07-11 20:00:12', 'host1', 'GetUser', 1000.0), + ('2024-07-11 20:00:12', 'host2', 'GetUser', 108.0), + ('2024-07-11 20:00:13', 'host1', 'GetUser', 80.0), + ('2024-07-11 20:00:13', 'host2', 'GetUser', 111.0), + ('2024-07-11 20:00:14', 'host1', 'GetUser', 4200.0), + ('2024-07-11 20:00:14', 'host2', 'GetUser', 95.0), + ('2024-07-11 20:00:15', 'host1', 'GetUser', 90.0), + ('2024-07-11 20:00:15', 'host2', 'GetUser', 115.0), + ('2024-07-11 20:00:16', 'host1', 'GetUser', 3000.0), + ('2024-07-11 20:00:16', 'host2', 'GetUser', 95.0), + ('2024-07-11 20:00:17', 'host1', 'GetUser', 320.0), + ('2024-07-11 20:00:17', 'host2', 'GetUser', 115.0), + ('2024-07-11 20:00:18', 'host1', 'GetUser', 3500.0), + ('2024-07-11 20:00:18', 'host2', 'GetUser', 95.0), + ('2024-07-11 20:00:19', 'host1', 'GetUser', 100.0), + ('2024-07-11 20:00:19', 'host2', 'GetUser', 115.0), + ('2024-07-11 20:00:20', 'host1', 'GetUser', 2500.0), + ('2024-07-11 20:00:20', 'host2', 'GetUser', 95.0); +``` + +当 `host1` 的 gRPC 请求的延迟遇到问题时，收集了一些错误日志。 + +```sql +INSERT INTO app_logs (ts, host, api_path, log_level, log) VALUES + ('2024-07-11 20:00:10', 'host1', '/api/v1/resource', 'ERROR', 'Connection timeout'), + ('2024-07-11 20:00:10', 'host1', '/api/v1/billings', 'ERROR', 'Connection timeout'), + ('2024-07-11 20:00:11', 'host1', '/api/v1/resource', 'ERROR', 'Database unavailable'), + ('2024-07-11 20:00:11', 'host1', '/api/v1/billings', 'ERROR', 'Database unavailable'), + ('2024-07-11 20:00:12', 'host1', '/api/v1/resource', 'ERROR', 'Service overload'), + ('2024-07-11 20:00:12', 'host1', '/api/v1/billings', 'ERROR', 'Service overload'), + ('2024-07-11 20:00:13', 'host1', '/api/v1/resource', 'ERROR', 'Connection reset'), + ('2024-07-11 20:00:13', 'host1', '/api/v1/billings', 'ERROR', 'Connection reset'), + ('2024-07-11 20:00:14', 'host1', '/api/v1/resource', 'ERROR', 'Timeout'), + ('2024-07-11 20:00:14', 'host1', '/api/v1/billings', 'ERROR', 'Timeout'), + ('2024-07-11 20:00:15', 'host1', '/api/v1/resource', 'ERROR', 'Disk full'), + ('2024-07-11 20:00:15', 'host1', '/api/v1/billings', 'ERROR', 'Disk full'), + ('2024-07-11 20:00:16', 'host1', '/api/v1/resource', 'ERROR', 'Network issue'), + ('2024-07-11 20:00:16', 'host1', '/api/v1/billings', 'ERROR', 'Network issue'); +``` + +## 查询数据 + +### 根据 tag 和时间索引进行过滤 + +你可以使用 WHERE 子句来过滤数据。例如，要查询 `2024-07-11 20:00:15` 之后 `host1` 的延迟： + +```sql +SELECT * + FROM grpc_latencies + WHERE host = 'host1' AND ts > '2024-07-11 20:00:15'; +``` + +```sql ++---------------------+-------+-------------+---------+ +| ts | host | method_name | latency | ++---------------------+-------+-------------+---------+ +| 2024-07-11 20:00:16 | host1 | GetUser | 3000 | +| 2024-07-11 20:00:17 | host1 | GetUser | 320 | +| 2024-07-11 20:00:18 | host1 | GetUser | 3500 | +| 2024-07-11 20:00:19 | host1 | GetUser | 100 | +| 2024-07-11 20:00:20 | host1 | GetUser | 2500 | ++---------------------+-------+-------------+---------+ +5 rows in set (0.14 sec) +``` + +你还可以在过滤数据时使用函数。例如，你可以使用 `approx_percentile_cont` 函数按主机分组计算延迟的第 95 百分位数： + +```sql +SELECT + approx_percentile_cont(latency, 0.95) AS p95_latency, + host +FROM grpc_latencies +WHERE ts >= '2024-07-11 20:00:10' +GROUP BY host; +``` + +```sql ++-------------------+-------+ +| p95_latency | host | ++-------------------+-------+ +| 4164.999999999999 | host1 | +| 115 | host2 | ++-------------------+-------+ +2 rows in set (0.11 sec) +``` + +### Range query + +你可以使用 [range query](/reference/sql/range.md#range-query)来实时监控延迟。例如，按 5 秒窗口计算请求的 p95 延迟： + +```sql +SELECT + ts, + host, + approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency +FROM + grpc_latencies +ALIGN '5s' FILL PREV; +``` + +```sql ++---------------------+-------+-------------+ +| ts | host | p95_latency | ++---------------------+-------+-------------+ +| 2024-07-11 20:00:05 | host2 | 114 | +| 2024-07-11 20:00:10 | host2 | 111 | +| 2024-07-11 20:00:15 | host2 | 115 | +| 2024-07-11 20:00:20 | host2 | 95 | +| 2024-07-11 20:00:05 | host1 | 104.5 | +| 2024-07-11 20:00:10 | host1 | 4200 | +| 2024-07-11 20:00:15 | host1 | 3500 | +| 2024-07-11 20:00:20 | host1 | 2500 | ++---------------------+-------+-------------+ +8 rows in set (0.06 sec) +``` + +### 全文搜索 + +你可以使用 `matches` 函数来搜索具有 `FULLTEXT` 索引的列。例如，搜索包含错误信息 `timeout` 的日志： + +```sql +SELECT + ts, + api_path, + log +FROM + app_logs +WHERE + matches(log, 'timeout'); +``` + +```sql ++---------------------+------------------+--------------------+ +| ts | api_path | log | ++---------------------+------------------+--------------------+ +| 2024-07-11 20:00:10 | /api/v1/billings | Connection timeout | +| 2024-07-11 20:00:10 | /api/v1/resource | Connection timeout | ++---------------------+------------------+--------------------+ +2 rows in set (0.01 sec) +``` + +### 指标和日志的关联查询 + +通过组合两个表的数据，你可以快速地确定故障时间和相应的日志。以下 SQL 查询使用 `JOIN` 操作关联指标和日志： + +```sql +WITH + metrics AS ( + SELECT + ts, + host, + approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency + FROM + grpc_latencies + ALIGN '5s' FILL PREV + ), + logs AS ( + SELECT + ts, + host, + count(log) RANGE '5s' AS num_errors, + FROM + app_logs + WHERE + log_level = 'ERROR' + ALIGN '5s' +) +--- 关联 metric 和日志 --- +SELECT + metrics.ts, + p95_latency, + coalesce(num_errors, 0) as num_errors, + metrics.host +FROM + metrics + LEFT JOIN logs ON metrics.host = logs.host + AND metrics.ts = logs.ts +ORDER BY + metrics.ts; +``` + + +```sql ++---------------------+-------------+------------+-------+ +| ts | p95_latency | num_errors | host | ++---------------------+-------------+------------+-------+ +| 2024-07-11 20:00:05 | 114 | 0 | host2 | +| 2024-07-11 20:00:05 | 104.5 | 0 | host1 | +| 2024-07-11 20:00:10 | 4200 | 10 | host1 | +| 2024-07-11 20:00:10 | 111 | 0 | host2 | +| 2024-07-11 20:00:15 | 115 | 0 | host2 | +| 2024-07-11 20:00:15 | 3500 | 4 | host1 | +| 2024-07-11 20:00:20 | 110 | 0 | host2 | +| 2024-07-11 20:00:20 | 2500 | 0 | host1 | ++---------------------+-------------+------------+-------+ +8 rows in set (0.02 sec) +``` + + + +## GreptimeDB 控制台 + +GreptimeDB 提供了一个[仪表板](./installation/greptimedb-dashboard.md)用于数据探索和管理。 + +### 数据探索 + +按照[安装部分](./installation/overview.md)中的说明启动 GreptimeDB 后，你可以通过 HTTP 地址 `http://localhost:4000/dashboard` 访问控制台。 + +点击 `+` 按钮添加一个新的查询，在命令文本中编写你的 SQL 命令，然后点击 `Run All`。 +下方的 SQL 会查询 `grpc_latencies` 表中的所有数据。 + +```sql +SELECT * FROM grpc_latencies; +``` + +然后点击结果面板中的 `Chart` 按钮来可视化数据。 + +![select gRPC latencies](/select-grpc-latencies.png) + +### 使用 InfluxDB Line Protocol 导入数据 + +除了 SQL，GreptimeDB 还支持多种协议，其中最常用之一是 InfluxDB Line Protocol。 +在仪表板中点击 `Ingest` 图标，你可以以 InfluxDB Line Protocol 格式上传数据。 + +例如，将以下数据粘贴到输入框中： + +```txt +grpc_metrics,host=host1,method_name=GetUser latency=100,code=0 1720728021000000000 +grpc_metrics,host=host2,method_name=GetUser latency=110,code=1 1720728021000000000 +``` + +然后点击 `Write` 按钮来导入数据到 `grpc_metrics` 表。如果改表不存在，将会自动创建该表。 + +## 下一步 + +你现在已经体验了 GreptimeDB 的核心功能。 +要进一步探索和利用 GreptimeDB： + +- [使用 Grafana 可视化数据](/user-guide/integrations/grafana.md) +- [探索更多 GreptimeDB 的 Demo](https://github.com/GreptimeTeam/demo-scene/) +- [阅读用户指南文档以了解更多关于 GreptimeDB 的详细信息](/user-guide/overview.md) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/create-service.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/create-service.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/create-service.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/create-service.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/go.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/go.md similarity index 83% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/go.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/go.md index 31c94c176..8b9d87b0a 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/go.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/go.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Go 收集系统指标数据并将其发送到 GreptimeCloud，包括安装命令和示例代码。 +--- + # Go ## 创建服务 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/influxdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/influxdb.md similarity index 85% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/influxdb.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/influxdb.md index 96bcdb20a..0cb5c84c4 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/influxdb.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/influxdb.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何通过 InfluxDB line protocol 收集系统指标数据并将其发送到 GreptimeCloud。 +--- + # InfluxDB Line Protocol ## 创建服务 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/java.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/java.md similarity index 84% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/java.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/java.md index 8cb0b18fd..17c2c9d17 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/java.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/java.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Java 收集 JVM 运行时指标数据并将其发送到 GreptimeCloud，包括下载命令和示例代码。 +--- + # Java ## 创建服务 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/mysql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/mysql.md similarity index 86% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/mysql.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/mysql.md index d4fd73503..04ed9fcb7 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/mysql.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/mysql.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何通过 MySQL 收集系统指标数据并将其发送到 GreptimeCloud。 +--- + # MySQL ## 创建服务 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/node.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/node.md similarity index 83% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/node.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/node.md index dcdba8ffb..fe9b902fd 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/node.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/node.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Node.js 收集系统指标数据并将其发送到 GreptimeCloud，包括安装命令和示例代码。 +--- + # Node.js ## 创建服务 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/overview.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/overview.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/overview.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/prometheus.md similarity index 86% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/prometheus.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/prometheus.md index ebc8e9d59..0a9a6e680 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/prometheus.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/prometheus.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Prometheus 收集系统指标数据并将其发送到 GreptimeCloud，包括配置文件示例和 Docker 启动命令。 +--- + # Prometheus ## 创建服务 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/python.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/python.md similarity index 85% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/python.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/python.md index 4c142269f..0af680034 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/python.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/python.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Python 收集系统指标数据并将其发送到 GreptimeCloud，包括安装命令和示例代码。 +--- + # Python ## 创建服务 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/vector.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/vector.md similarity index 66% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/vector.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/vector.md index cc2192f90..c86b65a71 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/vector.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/vector.md @@ -1,7 +1,11 @@ +--- +description: 介绍如何使用 Vector 收集系统指标数据并将其发送到 GreptimeCloud，包括配置文件示例和启动命令。 +--- + # Vector ## 创建服务 -import Includecreateservice from './create-service.md' +import Includecreateservice from './create-service.md' @@ -17,10 +21,12 @@ scrape_interval_secs = 30 [sinks.cloud] inputs = ["in"] type = "greptimedb" -endpoint = ":4001" +endpoint = ":5001" dbname = "" username = "" password = "" +tls = {} +new_naming = true ``` 然后使用配置文件启动 Vector： @@ -30,6 +36,6 @@ vector --config vector.toml ``` ## 数据可视化 -import Includevisualizedata from './visualize-data.md' +import Includevisualizedata from './visualize-data.md' diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/visualize-data.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/visualize-data.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/getting-started/visualize-data.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/getting-started/visualize-data.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/alloy.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/alloy.md similarity index 84% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/alloy.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/alloy.md index 60378c188..09e56b99d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/alloy.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/alloy.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何将 GreptimeCloud 配置为 Grafana Alloy 的数据目的地，并提供了 Prometheus Remote Write 和 OpenTelemetry 的配置示例。 +--- + # Alloy [Grafana Alloy](https://grafana.com/docs/alloy/latest/) 是可观测数据采集器，同时兼容 OpenTelemetry 。 GreptimeDB 可被配置 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/dbeaver.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/dbeaver.md similarity index 87% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/dbeaver.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/dbeaver.md index 038d8f553..f3a5e2c29 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/dbeaver.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/dbeaver.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 DBeaver 通过 MySQL Driver 连接到 GreptimeCloud，并提供了连接信息和配置步骤。 +--- + # DBeaver [DBeaver](https://dbeaver.io/) 是一个免费、开源且跨平台的数据库工具，支持所有流行的数据库。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/grafana.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/grafana.md similarity index 92% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/grafana.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/grafana.md index 9f17ecc66..6a526c8b4 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/grafana.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/grafana.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何将 GreptimeCloud 配置为 Grafana 数据源，并提供了使用 GreptimeCloud、Prometheus 和 MySQL 数据源的配置示例。 +--- + # Grafana GreptimeDB 服务可以配置为 [Grafana 数据源](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/influxdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/influxdb.md similarity index 88% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/influxdb.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/influxdb.md index cd6559270..a368dfaf3 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/influxdb.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/influxdb.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 InfluxDB Line Protocol 连接到 GreptimeCloud，并提供了 Telegraf 和 Java 客户端的配置示例。 +--- + # InfluxDB Line Protocol GreptimeCloud 提供了 [Influxdb line protocol](https://docs.influxdata.com/influxdb/cloud/reference/syntax/line-protocol/) 的 http 接口。该接口和认证与 [InfluxDB write protocol 1.x](https://docs.influxdata.com/influxdb/v1.8/guides/write_data/#write-data-using-the-influxdb-api) 兼容。更多信息请参考 GreptimeDB 的 [InfluxDB 客户端](https://docs.greptime.cn/nightly/user-guide/protocols/influxdb-line-protocol)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/kafka.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/kafka.md similarity index 90% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/kafka.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/kafka.md index b286181cb..2e009d834 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/kafka.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/kafka.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Kafka 将数据传输到 GreptimeCloud，并提供了日志和指标数据的配置示例。 +--- + # Kafka 如果您正在使用 Kafka 或兼容 Kafka 的消息队列来传输可观测性数据，可以直接将数据写入到 GreptimeDB 中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/metabase.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/metabase.md similarity index 80% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/metabase.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/metabase.md index 46b8ecfce..10e41e55f 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/metabase.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/metabase.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何将 GreptimeCloud 添加到 Metabase 作为数据源，并提供了连接信息。 +--- + # Metabase [Metabase](https://github.com/metabase/metabase) 是一个用 Clojure 编写的开源 BI diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/mindsdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/mindsdb.md similarity index 84% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/mindsdb.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/mindsdb.md index 2949e43da..7b38f784a 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/mindsdb.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/mindsdb.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 MindsDB 将 GreptimeCloud 实例集成到机器学习平台，并提供了配置示例。 +--- + # MindsDB [MindsDB](https://mindsdb.com/) 是一个开源的机器学习平台，使开发人员能够轻松地将 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/mysql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/mysql.md similarity index 87% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/mysql.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/mysql.md index 193d65d0a..6423aa906 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/mysql.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/mysql.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何通过 MySQL 协议连接到 GreptimeCloud，并提供了连接信息和使用 MySQL、MariaDB CLI 及 JDBC 客户端的示例。 +--- + # MySQL GreptimeCloud 可以通过 MySQL 协议访问，兼容大多数标准客户端和驱动程序，其连接使用 TLS 加密。有关更多信息，请参阅 GreptimeDB 的 [MySQL 客户端](https://docs.greptime.cn/nightly/user-guide/protocols/mysql)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/otlp.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/otlp.md similarity index 91% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/otlp.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/otlp.md index dabf3aec9..bfa1d2dac 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/otlp.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/otlp.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何通过 OpenTelemetry Protocol (OTLP) 将指标数据发送到 GreptimeCloud，包括使用 OpenTelemetry API/SDK 和 OpenTelemetry Collector 的配置示例。 +--- + # OpenTelemetry Protocol (OTLP) 你可以通过 [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) 协议原生消费 OpenTelemetry 指标。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/postgresql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/postgresql.md similarity index 70% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/postgresql.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/postgresql.md index 2d8c0927d..0d03204ac 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/postgresql.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/postgresql.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 PostgreSQL 协议连接到 GreptimeCloud，包括连接信息、使用 psql 工具和连接字符串示例。 +--- + # PostgreSQL GreptimeCloud 支持用 PostgreSQL v3 协议访问 GreptimeDB。大多数标准客户端和驱动程序在协议级别上兼容，且连接使用TLS加密。 @@ -41,3 +45,18 @@ jdbc:postgresql://:4003/?user=&password=&ssl=t ``` postgresql://:@:4003/ ``` + +## Postgres 外部表 + +将 GreptimeCloud 实例配置外 Postgres 外部数据源。注意依据你的配置修改下方的服务 +器名和用户名 。 + +```sql +CREATE SERVER greptimedb +FOREIGN DATA WRAPPER postgres_fdw +OPTIONS (host '', dbname '', port '4003'); + +CREATE USER MAPPING FOR postgres +SERVER greptimedb +OPTIONS (user '', password ''); +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/prometheus.md similarity index 89% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/prometheus.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/prometheus.md index 64cb5c838..af63d0434 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/prometheus.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/prometheus.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何将 GreptimeCloud 用作 Prometheus 的存储和查询替代品，包括配置 Remote Write 和使用 Prometheus HTTP API 与 PromQL。 +--- + # Prometheus GreptimeCloud 与 GreptimeDB 完全兼容 Prometheus。这意味着你可以无缝地将 GreptimeCloud 用作 Prometheus 存储和查询的替代品。有关更多信息，请参阅 GreptimeDB 用户指南中的 [Prometheus 文档](https://docs.greptime.cn/user-guide/clients/prometheus)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/sdk-libraries/go.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/sdk-libraries/go.md similarity index 82% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/sdk-libraries/go.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/sdk-libraries/go.md index 720d689ac..745e8824f 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/sdk-libraries/go.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/sdk-libraries/go.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 GreptimeDB Go SDK 通过 gRPC 协议连接到 GreptimeCloud，并提供了连接信息和示例代码。 +--- + # Go SDK GreptimeDB Go SDK 使用 gRPC 与数据库通信， diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/sdk-libraries/java.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/sdk-libraries/java.md similarity index 83% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/sdk-libraries/java.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/sdk-libraries/java.md index 380ab24ec..54d852268 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/sdk-libraries/java.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/sdk-libraries/java.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 GreptimeDB Java SDK 通过 gRPC 协议连接到 GreptimeCloud，并提供了连接信息和示例代码。 +--- + # Java SDK GreptimeDB Java ingester 库使用 gRPC 协议写入数据， diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/streamlit.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/streamlit.md similarity index 84% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/streamlit.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/streamlit.md index 1862d7192..401d567d6 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/streamlit.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/streamlit.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Streamlit 连接 GreptimeCloud 并执行 SQL 查询，展示数据应用的构建示例。 +--- + # Streamlit Streamlit 是一套快速构建数据应用的 Python 框架，目前他也支持构建基于 GreptimeDB diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/superset.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/superset.md similarity index 77% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/superset.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/superset.md index 5d97651db..7dcf74449 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/superset.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/superset.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何在 Apache Superset 中将 GreptimeCloud 作为数据源，包括连接信息和 URL 格式。 +--- + # Superset [Apache Superset](https://superset.apache.org) 是开源的 BI 工具，用 Python 编写。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/vector.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/vector.md similarity index 89% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/vector.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/vector.md index ac8d66412..feb0aeb5e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/integrations/vector.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/integrations/vector.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Vector 将指标数据发送到 GreptimeCloud，包括配置示例和启动 Vector 的步骤。 +--- + # Vector Vector 是高性能的可观测数据管道。 @@ -23,6 +27,7 @@ dbname = "" username = "" password = "" tls = {} +new_naming = true ## logs [sources.logs_in] diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md similarity index 96% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md index a812a8af9..f54ae207f 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何从 InfluxDB 迁移到 GreptimeCloud，包括获取数据库连接信息、通过 HTTP API 和 Telegraf 写入数据、使用客户端库写入数据以及数据可视化。 +--- + import DocTemplate from '../../db-cloud-shared/migrate/migrate-from-influxdb.md' # 从 InfluxDB 迁移 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md similarity index 81% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md index 9e8459724..eefb8de90 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何从 Prometheus 迁移到 GreptimeCloud，包括配置 Remote Write、使用 PromQL 查询数据以及在 Grafana 中添加数据源。 +--- + import DocTemplate from '../../db-cloud-shared/migrate/_migrate-from-prometheus.md' # 从 Prometheus 迁移 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/overview.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/overview.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/overview.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/go.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/go.md similarity index 82% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/go.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/go.md index f977661dc..9e22fa2bd 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/go.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/go.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Go 监控主机指标，包括创建服务、写入数据和数据可视化。 +--- + # Go import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/influxdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/influxdb.md similarity index 81% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/influxdb.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/influxdb.md index 7b3152366..1937262fc 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/influxdb.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/influxdb.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 InfluxDB Line Protocol 监控主机指标，包括创建服务、写入数据和数据可视化。 +--- + # InfluxDB Line Protocol import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/java.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/java.md similarity index 82% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/java.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/java.md index 938aef2f4..4d58ae710 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/java.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/java.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Java 监控主机指标，包括创建服务、写入数据和数据可视化。 +--- + # Java import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/mysql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/mysql.md similarity index 82% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/mysql.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/mysql.md index bb482ce37..739c91aff 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/mysql.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/mysql.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 MySQL 监控主机指标，包括创建服务、写入数据和数据可视化。 +--- + # MySQL import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/node-js.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/node-js.md similarity index 82% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/node-js.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/node-js.md index 524affea9..68bbc6301 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/node-js.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/node-js.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Node.js 监控主机指标，包括创建服务、写入数据和数据可视化。 +--- + # Node.js import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/prometheus.md similarity index 82% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/prometheus.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/prometheus.md index 814818f46..b19ec9936 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/prometheus.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/prometheus.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Prometheus 监控主机指标，包括创建服务、写入数据和数据可视化。 +--- + # Prometheus import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/python.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/python.md similarity index 82% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/python.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/python.md index 5c0d7a496..a235c84c2 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/python.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/python.md @@ -1,3 +1,7 @@ +--- +description: 介绍如何使用 Python 监控主机指标，包括创建服务、写入数据和数据可视化。 +--- + # Python import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/billing.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/billing.md similarity index 92% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/billing.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/billing.md index ab5255769..01fdb9c25 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/billing.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/billing.md @@ -1,3 +1,7 @@ +--- +description: 介绍 GreptimeCloud 的账单生成、用量跟踪和费用计算方法。 +--- + # 账单 ## 发票 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/dedicated.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/dedicated.md similarity index 92% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/dedicated.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/dedicated.md index 88ad45459..d9dd167aa 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/dedicated.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/dedicated.md @@ -1,3 +1,7 @@ +--- +description: 介绍 Dedicated 计划的特点、配置方法和费用计算公式。 +--- + # Dedicated 计划 Dedicated 计划允许你购买专用的 CPU 和存储来托管 GreptimeDB。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/hobby.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/hobby.md similarity index 91% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/hobby.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/hobby.md index 42eb6d86b..c2fa2feb2 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/hobby.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/hobby.md @@ -1,3 +1,7 @@ +--- +description: 介绍 GreptimeCloud 的免费 Hobby 计划及其限制。 +--- + # Hobby 计划 ## 简介 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/overview.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/overview.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/overview.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/request-capacity-unit.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/request-capacity-unit.md similarity index 97% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/request-capacity-unit.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/request-capacity-unit.md index 3f5225104..f076373ac 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/request-capacity-unit.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/request-capacity-unit.md @@ -1,3 +1,7 @@ +--- +description: 详细介绍 GreptimeCloud 的请求容量单位算法，包括 WCU 和 RCU 的计算方法和优化建议。 +--- + # 请求容量单位 本文档将介绍 GreptimeCloud 的请求容量单位算法。你可以前往 [GreptimeCloud 控制台](https://console.greptime.cloud/) 监控服务的使用情况。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/serverless.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/serverless.md similarity index 93% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/serverless.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/serverless.md index d5dabebf7..b71acabc7 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/serverless.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/serverless.md @@ -1,3 +1,7 @@ +--- +description: 介绍 Serverless 计划的特点、配置方法和费用计算公式。 +--- + # Serverless 计划 Serverless 计划允许你根据需求购买请求容量，并提供 SRE 团队支持。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/shared-storage-capacity.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/shared-storage-capacity.md similarity index 100% rename from i18n/zh/docusaurus-plugin-content-docs/version-0.10/greptimecloud/usage-&-billing/shared-storage-capacity.md rename to i18n/zh/docusaurus-plugin-content-docs/version-0.11/greptimecloud/usage-&-billing/shared-storage-capacity.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/index.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/index.md new file mode 100644 index 000000000..d75a4aa53 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/index.md @@ -0,0 +1,39 @@ +--- +description: 介绍了 GreptimeDB 的核心功能和特点，并提供了相关文档的链接，帮助用户快速上手和深入了解。 +--- + +# 简介 + +

+ GreptimeDB Logo +

+ +GreptimeDB 是开源的统一时序数据库，能同时处理**指标**（Metrics）、**日志**（Logs）、**事件**（Events）和**追踪**（Traces）。从云到端，GreptimeDB 能从任意规模的时序数据中获取实时数据洞察。 + +GreptimeDB 经由 [GreptimeCloud](https://greptime.cn/product/cloud) 提供云服务。 +GreptimeCloud 是一个完全托管的时序数据库服务，具有无服务器的可扩展性、与生态系统的无缝集成和 Prometheus 兼容性。 + +我们的核心开发人员多年深耕于建立时序数据平台。基于他们的丰富经验，GreptimeDB 应运而生，并为用户提供： + +- 统一的时序数据处理；GreptimeDB 将所有时序数据统一抽象成带有时间戳和上下文的事件，从而统一了指标、日志和事件的存储和分析。同时，GreptimeDB 支持使用 SQL 和 PromQL 进行分析，以及通过持续聚合能力来实现流处理。 +- 为处理时序数据而优化的列式布局；经过压缩、整理，并存储在各种存储后端，尤其是可以节省 50 倍成本效率的云对象存储。 +- 完全开源的分布式集群架构，利用云原生弹性计算资源的强大功能。 +- 从边缘节点的单机部署到云端强大、高可用的分布式集群的无缝扩展，为开发人员和管理员提供透明的体验。 +- 灵活的索引功能和分布式、并行处理查询引擎，解决高基数的问题。 +- 适配广泛采用的数据库协议和 API，包括 MySQL、PostgreSQL 和 Prometheus 远程存储等。 +- Schemaless 写入，自动为数据创建表格。 + +在开始上手之前，请阅读以下文档，其包含了设置说明、基本概念、架构设计和教程： + +- [立即开始][1]: 为刚接触 GreptimeDB 的用户提供指引，包括如何安装与数据库操作。 +- [用户指南][2]: 应用程序开发人员可以使用 GreptimeDB 或建立自定义集成。 +- [贡献者指南][3]: 有兴趣了解更多技术细节并想成为 GreptimeDB 的贡献者的开发者请阅读此文档。 + + +[1]: ./getting-started/overview.md +[2]: ./user-guide/overview.md +[3]: ./contributor-guide/overview.md + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/about-greptimedb-version.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/about-greptimedb-version.md new file mode 100644 index 000000000..52affc4e2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/about-greptimedb-version.md @@ -0,0 +1,33 @@ +--- +description: 介绍 GreptimeDB 版本号的语义化版本控制方案，包括主版本号、次版本号和修订号的定义和影响。 +--- + +# 关于 GreptimeDB 版本号 + +GreptimeDB 遵循 [语义化版本控制](https://semver.org/) 方案： + +1.2.3 其中： +- 1 是主版本号 +- 2 是次版本号 +- 3 是修订号 + +## 主版本号(1) + +主版本号表示软件生命周期中的一个重要里程碑，通常引入广泛的变化。 +- 特点：包括主要的架构更新、重大新功能或系统大修。 +- 影响：通常不向后兼容，用户或开发人员需要进行调整。 +- 示例：主要的 API 重新设计、基础架构的重大变化或引入新的核心模块。 + +## 次版本号(2) + +次版本号侧重于功能增强和小改进，旨在完善现有系统。 +- 特点：添加新功能、小更新或界面改进。 +- 影响：虽然它在同一主版本内努力保持向后兼容，但偶尔也可能会出现小的破坏性更改。 +- 示例：引入可选功能、更新用户界面或扩展配置选项并对现有行为进行轻微调整。 + +## 修订号(3) + +修订号用于修补或小幅改进，解决特定问题。 +- 特点：专注于错误修复、安全更新或性能优化。 +- 影响：不引入新功能或改变系统的整体行为。 +- 示例：修复已知错误、解决安全漏洞或提高系统稳定性。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/command-lines.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/command-lines.md new file mode 100644 index 000000000..a9de7c73d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/command-lines.md @@ -0,0 +1,204 @@ +--- +description: 介绍 Greptime 命令行工具的安装、使用方法，包括全局选项、各子命令选项、配置示例、升级 GreptimeDB 版本等内容。 +--- + +# Greptime 命令行工具 + +`greptime` 命令行工具可以启动、停止、或传递配置项给 GreptimeDB。 + +## 安装命令行工具 + +Greptime 命令行工具与 GreptimeDB 二进制文件捆绑在一起。 +在[安装 GreptimeDB](/getting-started/installation/overview.md)之后， +你可以在 GreptimeDB 的当前目录中执行 `./greptime` 命令。 + +为了方便起见，如果你希望使用 `greptime` 而不是 `./greptime` 来运行命令， +可以将命令行工具的二进制文件移动到系统的 `bin` 目录，或者将二进制文件的路径添加到 `PATH` 环境变量中。 + +## 选项 + +`help` 命令列出了 `greptime` 所有可用的命令和选项。 + +```sh +$ greptime help +Usage: greptime [OPTIONS] + +Commands: + datanode Start datanode service + frontend Start frontend service + metasrv Start metasrv service + standalone Run greptimedb as a standalone service + cli Execute the cli tools for greptimedb + help Print this message or the help of the given subcommand(s) + +Options: + --log-dir + --log-level + -h, --help Print help + -V, --version Print version +``` + +- `--log-dir=[dir]` specify logs directory, `/tmp/greptimedb/logs` by default. +- `--log-level=[info | debug | error | warn | trace]` specify the log level, `info` by default. + +### 全局选项 + +- `-h`/`--help`: 打印命令行帮助信息 +- `-V`/`--version`: 打印 GreptimeDB 版本信息 +- `--log-dir `: 指定日志路径 +- `--log-level `: 指定日志级别，如 `info`、`debug` 等。 + +### datanode 子命令选项 + +通过执行下列命令来获取 `datanode` 子命令的帮助菜单： + +``` +greptime datanode start --help +``` + +- `-c`/`--config-file`: 指定 datanode 启动的配置文件 +- `--data-home`: 数据库存储 home 目录 +- `--env-prefix `: 配置的环境变量前缀，默认为 `GREPTIMEDB_DATANODE`; +- `--http-addr `: HTTP 服务地址 +- `--http-timeout `: HTTP 超时设置，单位秒 +- `--metasrv-addrs `: Metasrv 服务器列表，用逗号或者空格隔开 +- `--node-id `: 节点 ID +- `--rpc-addr `: gRPC 服务地址 +- `--rpc-hostname `: 节点 hostname +- `--wal-dir `: WAL 日志目录; + +所有的地址类选项都是 `ip:port` 形式的字符串。 + +### metasrv 子命令选项 + +通过执行下列命令来获取 `metasrv` 子命令的帮助菜单： + +``` +greptime metasrv start --help +``` + +- `-c`/`--config-file`: 指定 `metasrv` 启动配置文件 +- `--enable-region-failover`: 是否启动 region 自动容灾，默认为 `false` 不启用。 +- `--env-prefix `: 配置的环境变量前缀，默认为`GREPTIMEDB_METASRV`; +- `--bind-addr `:服务监听地址，默认为 `127.0.0.1:3002`. +- `--http-addr `: HTTP 服务器地址 +- `--http-timeout `: HTTP 超时设置，单位秒 +- `--selector `: 参考 [selector 类型](/contributor-guide/metasrv/selector.md#selector-type); +- `--server-addr `: 提供给 frontend 和 datanode 的外部通讯服务器地址 +- `--store-addrs `: 逗号或空格分隔的键值存储服务器（默认为 etcd）地址，用于存储元数据； +- `--use-memory-store`: 是否使用内存存储替代 etcd，仅用于测试 + +### frontend 子命令选项 + +通过执行下列命令来获取 `frontend` 子命令的帮助菜单： + +``` +greptime frontend start --help +``` + +- `-c`/`--config-file`: 指定 `frontend` 启动配置文件 +- `--disable-dashboard`: 是否禁用 dashboard，默认为 `false`。 +- `--env-prefix `: 配置的环境变量前缀，默认为`GREPTIMEDB_FRONTEND`; +- `--rpc-addr `: gRPC 服务地址 +- `--http-addr `: HTTP 服务器地址 +- `--http-timeout `: HTTP 超时设置，单位秒 +- `--influxdb-enable`: 是否启用 `influxdb` HTTP 接口，默认为 true。 +- `--metasrv-addrs `: Metasrv 地址列表，用逗号或者空格隔开 +- `--mysql-addr `: MySQL 服务地址 +- `--postgres-addr `: Postgres 服务地址 +- `--tls-cert-path `: TLS 公钥文件地址 +- `--tls-key-path `: TLS 私钥文件地址 +- `--tls-mode `: TLS 模式 +- `--user-provider `: 参考 [鉴权](/user-guide/deployments/authentication/overview.md); + + +### Flownode 子命令选项 + +通过执行下列命令来获取 `flownode` 子命令的帮助菜单： + +``` +greptime flownode start --help +``` + +- `--node-id `: Flownode的ID +- `--rpc-addr `: gRPC服务器的绑定地址 +- `--rpc-hostname `: gRPC服务器的主机名 +- `--metasrv-addrs ...`: Metasrv地址列表 +- `-c, --config-file `: Flownode的配置文件 +- `--env-prefix `: 环境变量的前缀，默认为 `GREPTIMEDB_FLOWNODE` + +### standalone 子命令选项 + +通过执行下列命令来获取 `standalone` 子命令的帮助菜单： + +``` +greptime standalone start --help +``` + +- `-c`/`--config-file`: 指定 `standalone` 启动配置文件 +- `--env-prefix `: 配置的环境变量前缀，默认为`GREPTIMEDB_STANDALONE`; +- `--http-addr `: HTTP 服务器地址 +- `--influxdb-enable`: 是否启用 `influxdb` HTTP 接口，默认为 true。 +- `--mysql-addr `: MySQL 服务地址 +- `--postgres-addr `: Postgres 服务地址 +- `--rpc-addr `: gRPC 服务地址 + +## 配置示例 + +### 启动服务时使用相关配置 + +使用自定义配置以 standalone 模式启动 GreptimeDB： + +```sh +greptime --log-dir=/tmp/greptimedb/logs --log-level=info standalone start -c config/standalone.example.toml +``` + +`standalone.example.toml` 配置文件来自 `[GreptimeDB](https://github.com/GreptimeTeam/greptimedb/)` 仓库的 `config` 目录。您可以在那里找到更多示例配置文件。使用 `-c` 选项可以指定配置文件，有关更多信息，更多信息请查看[配置](../user-guide/deployments/configuration.md)。 + +为了以分布式模式启动 GreptimeDB，您需要分别启动每个组件。以下命令显示了如何使用自定义配置或命令行参数启动每个组件： + +使用自定义配置启动 metasrv： + +```sh +greptime metasrv start -c config/metasrv.example.toml +``` + +使用自定义配置启动 datanode： + +```sh +greptime datanode start -c config/datanode.example.toml +``` + +使用命令行参数启动 datanode，指定 gRPC 服务地址、MySQL 服务地址、metasrv 地址和该 datanode 的 ID： + +```sh +greptime datanode start --rpc-addr=0.0.0.0:4001 --mysql-addr=0.0.0.0:4002 --metasrv-addrs=0.0.0.0:3002 --node-id=1 +``` + +使用自定义配置启动 frontend： + +```sh +greptime frontend start -c config/frontend.example.toml +``` + +使用命令行参数启动 frontend，指定 metasrv 的地址： + +```sh +greptime frontend start --metasrv-addrs=0.0.0.0:3002 +``` + +使用自定义配置启动 flownode + +```sh +greptime flownode start -c config/flownode.example.toml +``` + +使用命令行参数启动 flownode，指定 metasrv 和 frontend 的地址： + +```sh +greptime flownode start --node-id=0 --rpc-addr=127.0.0.1:6800 --metasrv-addrs=127.0.0.1:3002; +``` + +### 升级 GreptimeDB 版本 + +请参考具体的[升级步骤](/user-guide/administration/upgrade.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/gtctl.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/gtctl.md new file mode 100644 index 000000000..bdc854a05 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/gtctl.md @@ -0,0 +1,245 @@ +--- +description: 介绍 gtctl 工具的安装、使用方法，包括一键安装、通过 Homebrew 安装、从源代码构建、启用自动补全、快速入门、部署等内容。 +--- + +# gtctl + +[gtctl][1]，g-t-control，是一个用于管理 GreptimeDB 集群的命令行工具。gtctl 是集成了 GreptimeDB 集群的多种操作的多合一 binary。 + +## 安装 + +### 一键安装 + +使用以下命令下载二进制文件： + +```bash +curl -fsSL https://raw.githubusercontent.com/greptimeteam/gtctl/develop/hack/install.sh | sh +``` + +下载完成后，gtctl 将位于当前目录中。 + +你还可以从 AWS 中国区 S3 存储桶安装 gtctl： + +```bash +curl -fsSL https://downloads.greptime.cn/releases/scripts/gtctl/install.sh | sh -s -- -s aws +``` + +### 通过 Homebrew 安装 + +在 macOS 上，可以通过 Homebrew 安装 gtctl： + +```bash +brew tap greptimeteam/greptime +brew install gtctl +``` + +### 从源代码构建 + +如果已经安装了 [Go][2]，可以在该项目下运行 `make` 命令来构建 gtctl： + +```bash +make gtctl +``` + +构建完成后，gtctl 将生成在 `./bin/` 目录下。如果想要安装 gtctl，可以运行 `install` 命令： + +```bash +# 构建的 gtctl 将安装在 /usr/local/bin 目录下 +make install + +# 构建的 gtctl 将安装在自定义路径下 +make install INSTALL_DIR= +``` + +## 启用 gtctl 自动补全（可选） + +gtctl 支持多种不同的 shell 自动补全。 + +### Bash + +在 Bash 中，可以使用命令 `gtctl completion bash` 生成 gtctl 的自动补全脚本。将补全脚本引入到你的 shell 中可以启用 gtctl 的自动补全功能。 + +```bash +echo 'source <(gtctl completion bash)' >> ~/.bashrc +``` + +### Zsh + +在 Zsh 中，可以使用命令 `gtctl completion zsh` 生成 gtctl 的自动补全脚本。将补全脚本引入到你的 shell 中可以启用 gtctl 的自动补全功能。 + +```bash +mkdir -p $ZSH/completions && gtctl completion zsh > $ZSH/completions/_gtctl +``` + +### Fish + +在 Fish 中，可以使用命令 `gtctl completion fish` 生成 gtctl 的自动补全脚本。将补全脚本引入到你的 shell 中可以启用 gtctl 的自动补全功能。 + +```bash +gtctl completion fish | source +``` + +## 快速入门 + +体验 GreptimeDB 集群的**最快**方法是使用 playground： + +```bash +gtctl playground +``` + +`playground` 命令将在你的环境中以**裸机**模式部署最小的 GreptimeDB 集群。 + +## 部署 + +gtctl 支持两种部署模式：Kubernetes 和裸机模式（Bare-Metal）。 + +### Kubernetes + +#### 先决条件 + +* 需要 Kubernetes 版本 1.18 或更高。 + + 你可以使用 [kind][3] 创建自己的 Kubernetes 集群： + + ```bash + kind create cluster + ``` + +#### 创建 + +创建自己的 GreptimeDB 集群和 etcd 集群： + +```bash +gtctl cluster create mycluster -n default +``` + +如果你想使用存储在中国区的 artifacts（charts 和镜像），你可以启用 `--use-greptime-cn-artifacts`： + +```bash +gtctl cluster create mycluster -n default --use-greptime-cn-artifacts +``` + +创建完成后，整个 GreptimeDB 集群将在 default 命名空间中启动： + +```bash +# 获取集群。 +gtctl cluster get mycluster -n default + +# 列出所有集群。 +gtctl cluster list +``` + +所有在 [charts][4] 中提供的用于 cluster、etcd 和 operator 的值都是可配置的，你可以使用 `--set` 进行配置。gtctl 还提供了一些常用的配置选项，你可以使用 `gtctl cluster create --help` 来查看它们。 + +```bash +# 将 cluster datanode 副本数配置为 5 +gtctl cluster create mycluster --set cluster.datanode.replicas=5 + +# 两种配置 etcd 存储大小为 15Gi 的方式 +gtctl cluster create mycluster --set etcd.storage.volumeSize=15Gi +gtctl cluster create mycluster --etcd-storage-size 15Gi +``` + +#### 预运行 + +在集群创建过程中，gtctl 提供了 `--dry-run` 选项。如果用户使用 `--dry-run` 执行命令，gtctl 将输出清单的内容而不应用它们： + +```bash +gtctl cluster create mycluster -n default --dry-run +``` + +#### 连接 + +你可以使用 kubectl 的 `port-forward` 命令将前端请求转发到本地： + +```bash +kubectl port-forward svc/mycluster-frontend 4002:4002 > connections.out & +``` + +使用 gtctl 的 `connect` 命令或你的 `mysql` 客户端连接到集群： + +```bash +gtctl cluster connect mycluster -p mysql + +mysql -h 127.0.0.1 -P 4002 +``` + +#### 扩缩容（实验性） + +你可以使用以下命令来扩展（或缩小）集群的规模： + +```bash +# 将 datanode 扩展到 3 个副本。 +gtctl cluster scale -n -c datanode --replicas 3 + +# 将 frontend 扩展到 5 个副本。 +gtctl cluster scale -n -c frontend --replicas 5 +``` + +#### 删除 + +如果你想删除集群，可以执行以下操作： + +```bash +# 删除集群。 +gtctl cluster delete mycluster -n default + +# 删除集群，包括 etcd 集群。 +gtctl cluster delete mycluster -n default --tear-down-etcd +``` + +### 裸机模式（Bare-Metal） + +#### 创建 + +你可以使用以下简单命令在裸机环境中部署 GreptimeDB 集群： + +```bash +gtctl cluster create mycluster --bare-metal +``` + +它会在 `${HOME}/.gtctl` 中创建所有必要的元信息。 + +如果你想进行更多的配置，可以使用 yaml 格式的配置文件： + +```bash +gtctl cluster create mycluster --bare-metal --config +``` + +你可以参考 [`examples/bare-metal`][5] 中提供的示例配置文件 `cluster.yaml` 和 `cluster-with-local-artifacts.yaml`。 + +#### 删除 + +由于裸机模式下的集群在前台运行，任何 `SIGINT` 和 `SIGTERM` 信号都会删除集群。例如，在键盘上按下 `Ctrl+C` 后集群将被删除。 + +删除操作还会删除位于 `${HOME}/.gtctl` 中的一个集群的元信息。如果启用了 `--retain-logs`（默认启用），集群的日志将保留。 + +## 开发 + +Makefile 提供了许多有用的工具，你可以简单地运行 `make help` 来获取更多信息： + +* 编译项目 + + ```bash + make + ``` + + 然后 gtctl 会生成在 `./bin/` 目录下。 + +* 运行单元测试 + + ```bash + make test + ``` + +* 运行端到端测试 + + ```bash + make e2e + ``` + +[1]: +[2]: +[3]: +[4]: +[5]: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/http-endpoints.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/http-endpoints.md new file mode 100644 index 000000000..6d7d7ddb2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/http-endpoints.md @@ -0,0 +1,193 @@ +# HTTP API 端点列表 + +以下是 GreptimeDB 中各种 HTTP 路径及其用法的完整列表： + +## 管理 API + +未版本化的端点（不在 `/v1` 下）。用于健康检查、状态、指标等管理用途。 + +### 健康检查 + +- **路径**: `/health` +- **方法**: `GET`, `POST` +- **描述**: 提供一个健康检查端点以验证服务器是否正在运行。 +- **用法**: 访问此端点以检查服务器的健康状态。 + +### 状态 + +- **路径**: `/status` +- **方法**: `GET` +- **描述**: 检索服务器的当前状态。 +- **用法**: 使用此端点获取服务器状态信息。 + +### 指标 + +- **路径**: `/metrics` +- **方法**: `GET` +- **描述**: 暴露 Prometheus 指标以进行监控。 +- **用法**: Prometheus 可以抓取此端点以收集指标数据。 + +### 配置 + +- **路径**: `/config` +- **方法**: `GET` +- **描述**: 检索服务器的配置选项。 +- **用法**: 访问此端点以获取配置详细信息。 + +### 仪表盘 + +- **路径**: `/dashboard` +- **方法**: `GET`, `POST` +- **描述**: 提供对服务器仪表盘界面的访问。 +- **用法**: 访问这些端点以与基于 Web 的仪表盘进行交互。 + +此仪表盘与 GreptimeDB 服务器一起打包，并提供一个用户友好的界面与服务器进行交互。构建 GreptimeDB 时需要启用相应的编译标志。仪表盘的原始源代码在 https://github.com/GreptimeTeam/dashboard。 + +### 日志级别 + +- **路径**: `/debug/log_level` +- **方法**: `POST` +- **描述**: 动态调整服务器的日志级别。 +- **用法**: 发送日志级别更改请求到此端点。 + +有关更多信息，请参阅[如何文档](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-change-log-level-on-the-fly.md)。 + +### 性能分析工具 + +- **基础路径**: `/debug/prof/` +- **端点**: + - `cpu` + - `mem` +- **方法**: `POST` 用于分析数据库节点。 +- **描述**: 运行时 CPU 或内存使用情况分析。 +- **用法**: + - 有关 CPU 分析的详细指南，请参阅 [CPU 分析](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-profile-cpu.md)。 + - 有关内存分析的详细指南，请参阅 [内存分析](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-profile-memory.md)。 + +## 查询端点 + +用于向 GreptimeDB 发送查询的各种查询 API。 + +### SQL API + +- **路径**: `/v1/sql` +- **方法**: `GET`, `POST` +- **描述**: 执行 SQL 查询。 +- **用法**: 在请求体中发送 SQL 语句。 + +有关 SQL API 的更多信息，请参阅用户指南中的 [HTTP API 文档](/user-guide/protocols/http.md#post-sql-statements)。 + +### PromQL API + +- **路径**: `/v1/promql` +- **方法**: `GET`, `POST` +- **描述**: 执行 PromQL 查询以获取 Prometheus 兼容的指标，并以 GreptimeDB 的 JSON 格式返回数据。 +- **用法**: 在请求体中发送 PromQL 语句。 + +有关 PromQL API 的更多信息，请参阅 [PromQL 文档](/user-guide/query-data/promql.md)。 + +## 协议端点 + +与 GreptimeDB 兼容的各种协议的端点。如 InfluxDB、Prometheus、OpenTelemetry 等。 + +### InfluxDB 兼容性 + +- **路径**: + - `/v1/influxdb/write` + - `/v1/influxdb/api/v2/write` + - `/v1/influxdb/ping` + - `/v1/influxdb/health` +- **方法**: + - `POST` 用于写入端点。 + - `GET` 用于 ping 和健康检查端点。 +- **描述**: 提供与 InfluxDB 兼容的数据写入和健康检查端点。 +- **用法**: + - 使用 InfluxDB 行协议写入数据。 + - 使用 ping 和健康检查端点检查服务器状态。 + +有关 InfluxDB 协议的详细文档，请参阅[这里](/user-guide/protocols/influxdb-line-protocol.md)。 + +### Prometheus 远程写入/读取 + +- **路径**: + - `/v1/prometheus/write` + - `/v1/prometheus/read` +- **方法**: `POST` +- **描述**: 支持 Prometheus 远程写入和读取 API。 +- **用法**: + - 使用 Prometheus 远程写入协议发送指标数据。 + - 使用 Prometheus 远程读取协议读取指标数据。 + +### Prometheus HTTP API + +- **基础路径**: `/v1/prometheus/api/v1` +- **端点**: + - `/format_query` + - `/status/buildinfo` + - `/query` + - `/query_range` + - `/labels` + - `/series` + - `/parse_query` + - `/label/{label_name}/values` +- **方法**: `GET`, `POST` +- **描述**: 提供 Prometheus HTTP API 端点以查询和检索指标数据。 +- **用法**: 使用这些端点以标准 Prometheus HTTP API 进行指标交互。 + +有关 Prometheus HTTP API 的更多信息，请参阅原始 Prometheus 文档 [Prometheus HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/)。 + +### OpenTelemetry 协议 (OTLP) + +- **路径**: + - `/v1/otlp/v1/metrics` + - `/v1/otlp/v1/traces` + - `/v1/otlp/v1/logs` +- **方法**: `POST` +- **描述**: 支持 OpenTelemetry 协议以写入 Metrics、Traces 和 Logs。 +- **用法**: 将 OpenTelemetry 格式的数据发送到这些端点。 + +### Loki 兼容性 + +- **路径**: `/v1/loki/api/v1/push` +- **方法**: `POST` +- **描述**: 以兼容 Loki 的 API 写入日志。 +- **用法**: 将日志数据以 Loki 的格式发送到此端点。 + +### OpenTSDB 协议 + +- **路径**: `/v1/opentsdb/api/put` +- **方法**: `POST` +- **描述**: 支持使用 OpenTSDB 协议写入数据。 +- **用法**: 使用 OpenTSDB 的 JSON 格式写入时间序列数据。 + +## 日志写入端点 + +- **路径**: + - `/v1/events/logs` + - `/v1/events/pipelines/{pipeline_name}` + - `/v1/events/pipelines/dryrun` +- **方法**: + - `POST` 写入日志和添加 Pipeline。 + - `DELETE` 用于删除 Pipeline。 +- **描述**: 提供日志写入和 Pipeline 管理的端点。 +- **用法**: + - 通过 `/logs` 端点写入日志。 + - 使用 `/pipelines` 端点管理日志 Pipeline。 + +有关日志写入和 Pipeline 管理的更多信息，请参阅[日志概述](/user-guide/logs/overview.md)。 + +## 脚本端点 + +### 脚本管理 + +- **路径**: `/v1/scripts` +- **方法**: `POST` +- **描述**: 管理服务器上的脚本。 +- **用法**: 提交脚本以执行或管理。 + +### 运行脚本 + +- **路径**: `/v1/run-script` +- **方法**: `POST` +- **描述**: 在服务器上执行脚本。 +- **用法**: 发送要执行的脚本内容。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql-tools.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql-tools.md new file mode 100644 index 000000000..24c430efd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql-tools.md @@ -0,0 +1,289 @@ +--- +description: 介绍如何使用 SQL 工具与 GreptimeDB 交互，包括推荐的查询库、安装方法、连接数据库、使用 Raw SQL 查询数据等内容。 +--- + +# SQL 工具 + +GreptimeDB 使用 SQL 作为主要查询语言，并支持许多流行的 SQL 工具。 +本文档指导你如何使用 SQL 工具与 GreptimeDB 交互。 + +## 编程语言 Driver + +推荐使用成熟的 SQL driver 来查询数据。 + +### 推荐的查询库 + + + + Java 数据库连接（JDBC）是 JavaSoft 规范的标准应用程序编程接口（API），它允许 Java 程序访问数据库管理系统。 + + 许多数据库协议，如 MySQL 或 PostgreSQL，都已经基于 JDBC API 实现了自己的驱动程序。 + 由于 GreptimeDB [支持多种协议](/user-guide/protocols/overview.md)，这里我们使用 MySQL 协议作为示例来演示如何使用 JDBC。 + 如果你希望使用其他协议，只需要将 MySQL driver 换为相应的 driver。 + + + 推荐使用 [GORM](https://gorm.io/) 库来查询数据。 + + + +### 安装 + + + + 如果你使用的是 [Maven](https://maven.apache.org/)，请将以下内容添加到 `pom.xml` 的依赖项列表中： + + ```xml + + mysql + mysql-connector-java + 8.0.33 + + ``` + + + + 使用下方的命令安装 GORM： + + ```shell + go get -u gorm.io/gorm + ``` + + 以 MySQL 为例安装 driver： + + ```shell + go get -u gorm.io/driver/mysql + ``` + + 将库引入到代码中： + + ```go + import ( + "gorm.io/gorm" + "gorm.io/driver/mysql" + ) + ``` + + + +### Connect to database + +下面以 MySQL 为例演示如何连接到 GreptimeDB。 + + + + ```java + public static Connection getConnection() throws IOException, ClassNotFoundException, SQLException { + Properties prop = new Properties(); + prop.load(QueryJDBC.class.getResourceAsStream("/db-connection.properties")); + + String dbName = (String) prop.get("db.database-driver"); + String dbConnUrl = (String) prop.get("db.url"); + String dbUserName = (String) prop.get("db.username"); + String dbPassword = (String) prop.get("db.password"); + + Class.forName(dbName); + Connection dbConn = DriverManager.getConnection(dbConnUrl, dbUserName, dbPassword); + + return Objects.requireNonNull(dbConn, "Failed to make connection!"); + } + ``` + + 你需要一个 properties 文件来存储数据库连接信息，将其放在 Resources 目录中并命名为 `db-connection.properties`。文件内容如下： + + ```txt + # DataSource + db.database-driver=com.mysql.cj.jdbc.Driver + db.url=jdbc:mysql://localhost:4002/public + db.username= + db.password= + ``` + + 或者你可以从[这里](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/ingester-example/src/main/resources/db-connection.properties)获取文件。 + + + ```go + type Mysql struct { + Host string + Port string + User string + Password string + Database string + + DB *gorm.DB + } + + m := &Mysql{ + Host: "127.0.0.1", + Port: "4002", // default port for MySQL + User: "username", + Password: "password", + Database: "public", + } + + dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local", + m.Host, m.Port, m.Database) + dsn = fmt.Sprintf("%s:%s@%s", m.User, m.Password, dsn) + db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{}) + if err != nil { + // error handling + } + m.DB = db + ``` + + + +#### 时区 + + + + 通过设置 URL 参数来设置 JDBC 时区: + + ```txt + jdbc:mysql://127.0.0.1:4002?connectionTimeZone=Asia/Shanghai&forceConnectionTimeZoneToSession=true + ``` + * `connectionTimeZone={LOCAL|SERVER|user-defined-time-zone}` 配置连接时区。 + * `forceConnectionTimeZoneToSession=true` 使 session `time_zone` 变量被设置为 `connectionTimeZone` 指定的值。 + + + 在 DSN 中设置时区。例如，将时区设置为 `Asia/Shanghai`: + + ```go + dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local&time_zone=%27Asia%2FShanghai%27", + m.Host, m.Port, m.Database) + ``` + + 更多信息请参考 [MySQL Driver 文档](https://github.com/go-sql-driver/mysql?tab=readme-ov-file#system-variables)。 + + + +### Raw SQL + +推荐使用 Raw SQL 来体验 GreptimeDB 的全部功能。 +下面的例子展示了如何使用 Raw SQL 查询数据： + + + + ```java + try (Connection conn = getConnection()) { + Statement statement = conn.createStatement(); + + // DESC table; + ResultSet rs = statement.executeQuery("DESC cpu_metric"); + LOG.info("Column | Type | Key | Null | Default | Semantic Type "); + while (rs.next()) { + LOG.info("{} | {} | {} | {} | {} | {}", + rs.getString(1), + rs.getString(2), + rs.getString(3), + rs.getString(4), + rs.getString(5), + rs.getString(6)); + } + + // SELECT COUNT(*) FROM cpu_metric; + rs = statement.executeQuery("SELECT COUNT(*) FROM cpu_metric"); + while (rs.next()) { + LOG.info("Count: {}", rs.getInt(1)); + } + + // SELECT * FROM cpu_metric ORDER BY ts DESC LIMIT 5; + rs = statement.executeQuery("SELECT * FROM cpu_metric ORDER BY ts DESC LIMIT 5"); + LOG.info("host | ts | cpu_user | cpu_sys"); + while (rs.next()) { + LOG.info("{} | {} | {} | {}", + rs.getString("host"), + rs.getTimestamp("ts"), + rs.getDouble("cpu_user"), + rs.getDouble("cpu_sys")); + } + } + ``` + + 请参考[此处](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/ingester-example/src/main/java/io/greptime/QueryJDBC.java)获取直接可执行的代码。 + + + The following code declares a GORM object model: + + ```go + type CpuMetric struct { + Host string `gorm:"column:host;primaryKey"` + Ts time.Time `gorm:"column:ts;primaryKey"` + CpuUser float64 `gorm:"column:cpu_user"` + CpuSys float64 `gorm:"column:cpu_sys"` + } + ``` + + 如果你正在使用[高层级 API](/user-guide/ingest-data/for-iot/grpc-sdks/go.md#高层级-api) 来插入数据，你可以在模型中同时声明 GORM 和 GreptimeDB Tag。 + + ```go + type CpuMetric struct { + Host string `gorm:"column:host;primaryKey" greptime:"tag;column:host;type:string"` + Ts time.Time `gorm:"column:ts;primaryKey" greptime:"timestamp;column:ts;type:timestamp;precision:millisecond"` + CpuUser float64 `gorm:"column:cpu_user" greptime:"field;column:cpu_user;type:float64"` + CpuSys float64 `gorm:"column:cpu_sys" greptime:"field;column:cpu_sys;type:float64"` + } + ``` + + 声明表名： + + ```go + func (CpuMetric) TableName() string { + return "cpu_metric" + } + ``` + + 使用 Raw SQL 查询数据： + + ```go + var cpuMetric CpuMetric + db.Raw("SELECT * FROM cpu_metric LIMIT 10").Scan(&result) + ``` + + + +### 查询库参考 + +有关如何使用查询库的更多信息，请参考相应库的文档： + + + + - [JDBC 在线教程](https://docs.oracle.com/javase/tutorial/jdbc/basics/index.html) + + + - [GORM](https://gorm.io/docs/index.html) + + + +## 命令行工具 + +### MySQL + +你可以使用 `mysql` 命令行工具连接到 GreptimeDB。 +请参考 [MySQL 协议](/user-guide/protocols/mysql.md) 文档获取连接信息。 + +连接到服务器后，你可以使用所有 [GreptimeDB SQL 命令](/reference/sql/overview.md)与数据库交互。 + +### PostgreSQL + +你可以使用 `psql` 命令行工具连接到 GreptimeDB。 +请参考 [PostgreSQL 协议](/user-guide/protocols/postgresql.md) 文档获取连接信息。 + +连接到服务器后，你可以使用所有 [GreptimeDB SQL 命令](/reference/sql/overview.md)与数据库交互。 + +## GreptimeDB 控制台 + +你可以在 [Greptime 控制台](/getting-started/installation/greptimedb-dashboard.md)中运行 SQL 并可视化数据。 + +## GUI 工具 + +### DBeaver + +请参考 [DBeaver 集成指南](/user-guide/integrations/dbeaver.md)。 + + + +## HTTP API + +你可以将 POST SQL 到 GreptimeDB HTTP API 以查询数据。 +请参考 [HTTP API](/user-guide/protocols/http.md) 文档获取更多信息。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/admin.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/admin.md new file mode 100644 index 000000000..663b86c1d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/admin.md @@ -0,0 +1,32 @@ +--- +description: ADMIN 语句用于运行管理函数来管理数据库和数据。 +--- + +# ADMIN + +`ADMIN` 语句用于运行管理函数： + +```sql +ADMIN function(arg1, arg2, ...) +``` + +## 管理函数 + +GreptimeDB 提供了一些管理函数来管理数据库和数据： + +* `flush_table(table_name)` 根据表名将表的 Memtable 刷新到 SST 文件中。 +* `flush_region(region_id)` 根据 Region ID 将 Region 的 Memtable 刷新到 SST 文件中。通过 [PARTITIONS](./information-schema/partitions.md) 表查找 Region ID。 +* `compact_table(table_name, [type], [options])` 为表启动一个 compaction 任务，详细信息请阅读 [compaction](/user-guide/administration/manage-data/compaction.md#严格窗口压缩策略swcs和手动压缩)。 +* `compact_region(region_id)` 为 Region 启动一个 compaction 任务。 +* `migrate_region(region_id, from_peer, to_peer, [timeout])` 在 Datanode 之间迁移 Region，请阅读 [Region Migration](/user-guide/administration/manage-data/region-migration.md)。 +* `procedure_state(procedure_id)` 根据 ID 查询 Procedure 状态。 +* `flush_flow(flow_name)` 将 Flow 的输出刷新到目标接收表。 + +例如： +```sql +-- 刷新表 test -- +admin flush_table("test"); + +-- 为表 test 启动 compaction 任务 -- +admin compact_table("test"); +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/alter.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/alter.md new file mode 100644 index 000000000..928befe3e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/alter.md @@ -0,0 +1,183 @@ +--- +description: ALTER 用于修改数据库的设置、表的设置或表的元数据。 +--- + +# ALTER + +`ALTER` 可以用来修改数据库的设置，表的设置或表的元数据，包括： + +* 修改数据库选项 +* 添加/删除/修改列 +* 重命名表 +* 修改表选项 + +## ALTER DATABASE + + +`ALTER DATABASE` 语句可以用来修改数据库的选项。 + +### 语法 + +```sql +ALTER TABLE [db.]table + [ADD COLUMN name type [options] + | DROP COLUMN name + | MODIFY COLUMN name type + | MODIFY COLUMN name SET FULLTEXT [WITH ] + | RENAME name + | SET = [, ...] + | UNSET [, ...] + ] +``` + +当前支持修改以下数据库选项： +- `ttl`: 数据库中数据的默认保留时间。 + +### 示例 + +#### 修改数据库中数据的默认保留时间 + +修改数据库中数据的默认保留时间为 1 天： + +```sql +ALTER DATABASE db SET 'ttl'='1d'; +``` + +取消数据库中数据的默认保留时间设置： + +```sql +ALTER DATABASE db UNSET 'ttl'; +``` + +## ALTER TABLE + +## 语法 + +```sql +ALTER TABLE [db.]table + [ADD COLUMN name type [options] + | DROP COLUMN name + | MODIFY COLUMN name type + | MODIFY COLUMN name SET FULLTEXT [WITH ] + | RENAME name + | SET = [, ...] + ] +``` + +### 示例 + +#### 增加列 + +在表中增加新列： + +```sql +ALTER TABLE monitor ADD COLUMN load_15 double; +``` + +列的定义和 [CREATE](./create.md) 中的定义方式一样。 + +我们可以设置新列的位置。比如放在第一位： + +```sql +ALTER TABLE monitor ADD COLUMN load_15 double FIRST; +``` + +或者放在某个已有列之后： + +```sql +ALTER TABLE monitor ADD COLUMN load_15 double AFTER memory; +``` + +增加一个带默认值的 Tag 列（加入 Primary key 约束）： +```sql +ALTER TABLE monitor ADD COLUMN app STRING DEFAULT 'shop' PRIMARY KEY; +``` + + +#### 移除列 + +从表中移除列： + +```sql +ALTER TABLE monitor DROP COLUMN load_15; +``` + +后续的所有查询立刻不能获取到被移除的列。 + +#### 修改列类型 + +修改列的数据类型 + +```sql +ALTER TABLE monitor MODIFY COLUMN load_15 STRING; +``` + +被修改的的列不能是 tag 列（primary key）或 time index 列，同时该列必须允许空值 `NULL` 存在来保证数据能够安全地进行转换（转换失败时返回 `NULL`）。 + +#### 修改表的参数 + +`ALTER TABLE` 语句也可以用来更改表的选项。 +当前支持修改以下表选项： +- `ttl`: 表数据的保留时间。 +- `compaction.twcs.time_window`: TWCS compaction 策略的时间窗口。 +- `compaction.twcs.max_output_file_size`: TWCS compaction 策略的最大允许输出文件大小。 +- `compaction.twcs.max_active_window_runs`: TWCS compaction 策略的活跃窗口中最多允许的有序组数量。 +- `compaction.twcs.max_inactive_window_runs`: TWCS compaction 策略的非活跃窗口中最多允许的有序组数量。 +- `compaction.twcs.max_active_window_files`: TWCS compaction 策略的活跃窗口中最多允许的文件数量。 +- `compaction.twcs.max_inactive_window_files`: TWCS compaction 策略的非活跃窗口中最多允许的文件数量。 + + +```sql +ALTER TABLE monitor SET 'ttl'='1d'; + +ALTER TABLE monitor SET 'compaction.twcs.time_window'='2h'; + +ALTER TABLE monitor SET 'compaction.twcs.max_output_file_size'='500MB'; + +ALTER TABLE monitor SET 'compaction.twcs.max_inactive_window_files'='2'; + +ALTER TABLE monitor SET 'compaction.twcs.max_active_window_files'='2'; + +ALTER TABLE monitor SET 'compaction.twcs.max_active_window_runs'='6'; + +ALTER TABLE monitor SET 'compaction.twcs.max_inactive_window_runs'='6'; +``` + +#### 移除设置过的表参数 + +```sql +ALTER TABLE monitor UNSET 'ttl'; +``` + +#### 修改列全文索引选项 + +启用列的全文索引： + +```sql +ALTER TABLE monitor MODIFY COLUMN load_15 SET FULLTEXT WITH (analyzer = 'Chinese', case_sensitive = 'false'); +``` + +在启用列的全文索引时，可以使用 `FULLTEXT WITH` 可以指定以下选项： + +- `analyzer`：设置全文索引的分析器语言，支持 `English` 和 `Chinese`。默认为 `English`。 +- `case_sensitive`：设置全文索引是否区分大小写，支持 `true` 和 `false`。默认为 `false`。 + +与 `CREATE TABLE` 一样，可以不带 `WITH` 选项，全部使用默认值。 + +#### 关闭列的全文索引 + +```sql +ALTER TABLE monitor MODIFY COLUMN load_15 UNSET FULLTEXT; +``` + +修改列的全文索引选项时，列的数据类型必须是字符串类型。 + +当列的全文索引未开启过时，可以启用全文索引，并设置 `analyzer` 和 `case_sensitive` 选项；当列的全文索引选项已经启用时，可以关闭全文索引，**但不能修改选项**。 + +#### 重命名表 + +```sql +ALTER TABLE monitor RENAME monitor_new; +``` + +该命令只是重命名表，不会修改表中的数据。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/case.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/case.md new file mode 100644 index 000000000..b20f6a9b8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/case.md @@ -0,0 +1,93 @@ +--- +description: CASE 语句允许在查询中执行条件逻辑，根据条件返回特定值。 +--- + +# CASE + +CASE 语句类似于编程语言中的 IF-THEN-ELSE 结构，允许你在查询中执行条件逻辑， +它使你能够根据条件返回特定值，从而使数据检索和操作更加动态。 + +## 语法 + +```sql +CASE + WHEN condition1 THEN result1 + WHEN condition2 THEN result2 + ... + ELSE result +END +``` + +- `condition1`，`condition2`，...：表达式的判断条件。 +- `result1`，`result2`，...：满足相应条件时要返回的值。 +- `result`：当没有条件满足时要返回的值（可选）。 + +## 示例 + +`CASE` 语句可以在各种子句中使用，例如 `SELECT`，`WHERE`，`ORDER BY` 和 `GROUP BY`。 + +### 在 `SELECT` 中使用 `CASE` + +在 `SELECT` 子句中，你可以使用 `CASE` 语句根据条件创建新列。 +请参阅查询数据指南中的[示例](/user-guide/query-data/sql.md#case)。 + +你还可以将 `CASE` 与 `SUM` 等函数一起使用，以有条件地聚合数据。 +例如，你可以计算状态码为 200 和 404 的日志总数： + +```sql +SELECT + SUM(CASE WHEN status_code = '200' THEN 1 ELSE 0 END) AS status_200_count, + SUM(CASE WHEN status_code = '404' THEN 1 ELSE 0 END) AS status_404_count +FROM nginx_logs; +``` + +### 在 `WHERE` 中使用 `CASE` + +在 `WHERE` 子句中，你可以根据条件过滤行。 +例如，以下查询根据 `ts` 条件从 `monitor` 表中检索数据： + +```sql +SELECT * +FROM monitor +WHERE host = CASE + WHEN ts > '2023-12-13 02:05:46' THEN '127.0.0.1' + ELSE '127.0.0.2' + END; +``` + +### 在 `GROUP BY` 中使用 `CASE` + +`CASE` 语句可以在 `GROUP BY` 子句中使用，以根据特定条件对数据进行分类。 +例如，以下查询按 `host` 列分组，并将 `cpu` 列分类为三类：'high'，'medium' 和 'low'： + +```sql +SELECT + host, + COUNT(*) AS count, + CASE + WHEN cpu > 0.5 THEN 'high' + WHEN cpu > 0.3 THEN 'medium' + ELSE 'low' + END AS cpu_status +FROM monitor +GROUP BY + host, cpu_status; +``` + +### 在 `ORDER BY` 中使用 `CASE` + +根据 GreptimeDB 的[数据模型](/user-guide/concepts/data-model.md)， +`Tag` 列拥有索引，可以在 `ORDER BY` 子句中使用以提高查询性能。 +假如 `nginx_logs` 表中的 `status_code` 和 `http_method` 列是存储字符串值的 `Tag` 列， +你可以利用 `CASE` 语句根据这些列对数据进行排序，如下所示： + +```sql +SELECT * +FROM nginx_logs +ORDER BY + CASE + WHEN status_code IS NOT NULL THEN status_code + ELSE http_method + END; +``` + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/cast.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/cast.md new file mode 100644 index 000000000..7785a02bd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/cast.md @@ -0,0 +1,34 @@ +--- +description: CAST 用于将一个数据类型的表达式转换为另一个数据类型。 +--- + +# CAST + +`CAST` 用于将一个数据类型的表达式转换为另一个数据类型。 + +## Syntax + +```sql +CAST (expression AS data_type) +``` + +## 参数 + +- expression: 需要类型转换的表达式。 +- data_type: 需要被转换为的数据类型。 + +# 示例 + +将字符串转换为 `INT` 类型： + + ```sql + SELECT CAST('123' AS INT) ; + ``` + +```sql ++-------------+ +| Utf8("123") | ++-------------+ +| 123 | ++-------------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/compatibility.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/compatibility.md new file mode 100644 index 000000000..9c64866eb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/compatibility.md @@ -0,0 +1,24 @@ +--- +description: GreptimeDB 支持的 SQL 是 ANSI SQL 的子集，并且拥有一些特有的扩展。 +--- + +# ANSI Compatibility + +GreptimeDB 支持的 SQL 是 ANSI SQL 的子集，并且拥有一些特有的扩展。一些主要的不兼容和扩展描述如下： + +1. 建表 + * 支持特有的 `TIME INDEX` 约束，详细请参考[数据模型](/user-guide/concepts/data-model.md)和 [CREATE](./create.md) 建表语法一节。 + * 目前仅支持 `PRIMARY KEY` 约束，不支持其他类型的约束，也不支持外键。 + * GreptimeDB 是原生的分布式数据库，因此分布式表的建表语句支持分区规则，也请参考[CREATE](./create.md) 建表语法一节。 +2. 插入新数据： 与 ANSI SQL 语法一致，但是强制要求提供 `TIME INDEX` 列值（或默认值）。 +3. 更新：不支持 `UPDATE` 语法，但是在 `INSERT` 的时候，如果主键和 `TIME INDEX` 对应的列值一样，那么后续插入的行将覆盖以前写入的行，从而变相实现更新。 + * 从 0.8 开始， GreptimeDB 支持 [append 模式](/reference/sql/create.md#创建-Append-Only-表)，创建时指定`append_mode = "true"` 选项的表将保留重复的数据行。 + * GreptimeDB 支持 [merge 模式](/reference/sql/create.md#create-an-append-only-table)，该模式使用 `merge_mode="last_non_null"` 选项创建表，允许部分更新字段。 +4. 查询：查询语法兼容 ANSI SQL，存在部分功能差异和缺失 + * 从 v0.9.0 开始支持[视图](/user-guide/query-data/view.md)。 + * TQL 语法扩展：TQL 子命令支持在 SQL 中执行 PromQL，详细请参考 [TQL](./tql.md) 一节。 + * [Range Query](/reference/sql/range.md#range-query) 支持按照指定窗口来查询和聚合时序数据。 +5. 删除数据：语法与 ANSI SQL 基本一致。 +6. 他项： + * 标识符，如表名，列名等，约束与 ANSI SQL 类似，大小写敏感，遇到特殊字符或者大写需要用双引号括起来。 + * GreptimeDB 针对不同方言做了优化，比如用 MySQL 客户端或者 PostgreSQL 客户端连接到数据库时， 允许使用特定 SQL 方言的标识符规则，比如在 MySQL 中可以用反引号 `` ` ``，而在 PostgreSQL 中还是标准的双引号 `"`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/copy.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/copy.md new file mode 100644 index 000000000..8527c3079 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/copy.md @@ -0,0 +1,176 @@ +--- +description: COPY 语句用于导入和导出表或数据库的数据。 +--- + +# COPY + +## COPY TABLE +### COPY TO + +`COPY TO` 被用来将表的内容导出到文件中，其语法如下： + +```sql +COPY tbl TO '/xxx/xxx/output.parquet' WITH (FORMAT = 'parquet'); +``` + +命令以 `COPY` 关键字开始，后面跟着要导出数据的表名（本例中为 `tbl`）。 +`TO` 指定导出数据的文件路径和名称（本例中为 `/xxx/xxx/output.parquet`）。 + +#### `WITH` 选项 + +`WITH` 可以添加一些选项，比如文件的 `FORMAT` 用来指定导出文件的格式。本例中的格式为 Parquet，它是一种用于大数据处理的列式存储格式。Parquet 为大数据分析高效地压缩和编码列式数据。 + +| 选项 | 描述 | 是否必需 | +|---|---|---| +| `FORMAT` | 目标文件格式，例如 JSON, CSV, Parquet | **是** | +| `START_TIME`/`END_TIME`| 需要导出数据的时间范围，时间范围为左闭右开 | 可选 | + +#### `CONNECTION` 选项 + +`COPY TO` 支持导出数据到云存储上，比如 S3。详情请参考 [连接 S3](#连接-s3)。 + + +### COPY FROM + +`COPY FROM` 被用来将文件中的数据导入到表中，其语法如下： + +```sql +COPY [.] +FROM { '/[]' } +[ [ WITH ] + ( + [ FORMAT = { 'CSV' | 'JSON' | 'PARQUET' | 'ORC' } ] + [ PATTERN = '' ] + ) +] +[LIMIT NUM] +``` + +命令以 `COPY` 关键字开始，后面跟着要导入数据的表名。 + +#### `WITH` 选项 + +`FORMAT` 指定导入文件的格式，本例中为 Parquet。 + +选项 `PATTERN` 允许使用通配符（如 *）指定匹配某种模式的多个输入文件。例如，你可以使用以下语法导入目录（必须是绝对路径）"/path/to/folder" 中文件名包含 `parquet` 的所有文件： + +```sql +COPY tbl FROM '/path/to/folder/' WITH (FORMAT = 'parquet', PATTERN = '.*parquet.*'); +``` + +例如，如果你只有一个文件需要导入，可以使用下方的语法： + +```sql +COPY tbl FROM '/path/to/folder/xxx.parquet' WITH (FORMAT = 'parquet'); +``` + +| 选项 | 描述 | 是否必需 | +|---|---|---| +| `FORMAT` | 目标文件格式，例如 JSON, CSV, Parquet, ORC | **是** | +| `PATTERN` | 使用正则匹配文件，例如 `*_today.parquet` | 可选 | + +#### Connection 选项 + +`COPY FROM` 同样支持从云存储上导入数据，比如 S3。详情请参考 [连接 S3](#连接-s3)。 + +#### LIMIT 选项 + +可以通过 `LIMIT` 手动限制一次插入的最大行数。 + +### 连接 S3 + +你可以从 S3 导入/导出数据 + +```sql +-- COPY FROM +COPY tbl FROM '' WITH (FORMAT = 'parquet') CONNECTION(REGION = 'us-west-2'); + +-- COPY TO +COPY tbl TO '' WITH (FORMAT = 'parquet') CONNECTION(REGION = 'us-west-2'); +``` + +#### URL + +注意：你应该使用 `S3://bucket/key-name` 指定文件。下方的例子展示了正确的格式： + +``` +S3://my-bucket/data.parquet +``` + +另一种方式是使用 Virtual-hosted–style（`ENABLE_VIRTUAL_HOST_STYLE` 需要设置成 `true`），例如： + +``` +https://bucket-name.s3.region-code.amazonaws.com/key-name +``` + +:::tip NOTE +可以在 S3 控制台上点击 `Copy S3 URI` 或者 `COPY URL` 直接获取对应的 URL/HTTP 前缀或者完整路径。 +::: + +#### 选项 + +你可以设置这些 **CONNECTION** 选项： + +| 选项 | 描述 | 是否必需 | +|---|---|---| +| `REGION` | AWS region 名称，例如 `us-west-2` | **是** | +| `ENDPOINT` | The bucket endpoint，例如 `s3.us-west-2.amazonaws.com` | 可选 | +| `ACCESS_KEY_ID` | 用于连接 AWS S3 兼容的对象存储的访问密钥 ID | 可选 | +| `SECRET_ACCESS_KEY` | 用于连接 AWS S3 兼容的对象存储的秘密访问密钥 | 可选 | +| `ENABLE_VIRTUAL_HOST_STYLE` | 如果你使用 virtual hosting 的方式来定位 bucket，将该选项设置为 "true" | 可选 | +| `SESSION_TOKEN` | 用于连接 AWS S3 服务的临时凭证。 | 可选 | + +## COPY DATABASE + +`COPY` 语句除可以导入/导出表之外，也可以导入/导出指定的数据库，其语法如下： + +```sql +COPY DATABASE + [TO | FROM] '' + WITH ( + FORMAT = { 'CSV' | 'JSON' | 'PARQUET' } + START_TIME = "", + END_TIME = "" + ) + [CONNECTION( + REGION = "", + ENDPOINT = "", + ACCESS_KEY_ID = "", + SECRET_ACCESS_KEY = "", + ENABLE_VIRTUAL_HOST_STYLE = "[true | false]", + )] +``` + +| 选项 | 描述 | 是否必需 | +|---|---|---| +| `FORMAT` | 目标文件格式，例如 JSON, CSV, Parquet | **是** | +| `START_TIME`/`END_TIME`| 需要导出数据的时间范围，时间范围为左闭右开 | 可选 | + +> - 当导入/导出表时，`` 参数必须以 `/` 结尾； +> - COPY DATABASE 同样可以通过 `CONNECTION` 参数将数据导入/导出的路径指向 S3 等对象存储 + + +### 示例 + +```sql +-- 将 public 数据库中所有数据导出到 /tmp/export/ 目录下 +COPY DATABASE public TO '/tmp/export/' WITH (FORMAT='parquet'); + +-- 将 public 数据库中时间范围在 2022-04-11 08:00:00到2022-04-11 09:00:00 之间的数据导出到 /tmp/export/ 目录下 +COPY DATABASE public TO '/tmp/export/' WITH (FORMAT='parquet', START_TIME='2022-04-11 08:00:00', END_TIME='2022-04-11 09:00:00'); + +-- 从 /tmp/export/ 目录恢复 public 数据库的数据 +COPY DATABASE public FROM '/tmp/export/' WITH (FORMAT='parquet'); +``` + +## Windows 平台上的路径 + +请注意，在 Windows 平台上执行 `COPY`/`COPY DATABASE` 语句时，请使用 `/` 代替 `` 中的 `\`，如 `C:/some_dir/output.parquet`。 + +```sql +-- 下列语句将会报错 +COPY tbl TO 'C:\xxx\xxx\output.parquet' WITH (FORMAT = 'parquet'); + +-- 下列语句能够正常执行 +COPY tbl TO 'C:/xxx/xxx/output.parquet' WITH (FORMAT = 'parquet'); +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/create.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/create.md new file mode 100644 index 000000000..9558af4f0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/create.md @@ -0,0 +1,437 @@ +--- +description: CREATE 用于创建新的数据库或表，支持指定列、主键、时间索引、存储引擎和其他选项。 +--- + +# CREATE + +`CREATE` 用于创建新的数据库或者表。 + +## CREATE DATABASE + +### Syntax + +创建新数据库： + +```sql +CREATE DATABASE [IF NOT EXISTS] db_name [WITH ] +``` + +如果 `db_name` 数据库已经存在，`CREATE` 语句的行为如下： + +- 不会创建新的数据库。 +- 当 `IF NOT EXISTS` 子句被指定时，不会返回错误。 +- 否则，返回错误。 + +数据库也可以通过使用 `WITH` 关键字配置与 `CREATE TABLE` 语句类似的选项。[表选项](#表选项) 中提供的所有选项也可以在此处使用（一个例外是数据库的 TTL 不能为 `instant`）。在创建表时，如果未提供相应的表选项，将使用在数据库级别配置的选项或者默认值。 + +### 示例 + +创建名为 `test` 的数据库： + +```sql +CREATE DATABASE test; +``` + +```sql +Query OK, 1 row affected (0.05 sec) +``` + +使用 `IF NOT EXISTS` 再次创建： + +```sql +CREATE DATABASE IF NOT EXISTS test; +``` + +创建一个具有 7 天 `TTL`（数据存活时间）的数据库，也就是该数据库中的所有表如果没有单独设置 TTL 选项，都将继承此选项值。 + +```sql +CREATE DATABASE test WITH (ttl='7d'); +``` + + +## CREATE TABLE + +### Syntax + +在 `db` 或当前数据库中创建新表： + +```sql +CREATE TABLE [IF NOT EXISTS] [db.]table_name +( + column1 type1 [NULL | NOT NULL] [DEFAULT expr1] [TIME INDEX] [PRIMARY KEY] [FULLTEXT | FULLTEXT WITH options] [COMMENT comment1], + column2 type2 [NULL | NOT NULL] [DEFAULT expr2] [TIME INDEX] [PRIMARY KEY] [FULLTEXT | FULLTEXT WITH options] [COMMENT comment2], + ... + [TIME INDEX (column)], + [PRIMARY KEY(column1, column2, ...)], + [INVERTED INDEX(column1, column2, ...)] +) ENGINE = engine WITH([TTL | storage | ...] = expr, ...) +[ + PARTITION ON COLUMNS(column1, column2, ...) ( + , + ... + ) +] +``` + +表 schema 由 `ENGINE` 之前的括号指定，表 schema 是列的定义和表的约束。 +列定义包括列名称和数据类型，以及可选的 `NULL`、`NOT NULL`、`DEFAULT` 等。 + +### 表约束 + +表约束包括以下内容： + +- `TIME INDEX` 指定时间索引列，每个表只能有一个时间索引列。它表示 GreptimeDB 的 [数据模型](/user-guide/concepts/data-model.md) 中的 `Timestamp` 类型。 +- `PRIMARY KEY` 指定表的主键列，它表示 GreptimeDB 的 [数据模型](/user-guide/concepts/data-model.md) 中的 `Tag` 类型。它不能包含时间索引列，但是它总是隐式地将时间索引列添加到键的末尾。 +- 其他列是 GreptimeDB 的 [数据模型](/user-guide/concepts/data-model.md) 中的 `Field` 类型。 + +:::tip 注意 +`CREATE` 语句中指定的 `PRIMARY KEY` **不是** 传统关系数据库中的主键。 +实际上，传统关系数据库中的 `PRIMARY KEY` 相当于 GreptimeDB 中的 `PRIMARY KEY` 和 `TIME INDEX` 的组合。 +换句话说，`PRIMARY KEY` 和 `TIME INDEX` 一起构成了 GreptimeDB 中行的唯一标识符。 +::: + +如果表已经存在且创建表时指定了 `IF NOT EXISTS`，`CREATE` 语句不会返回错误；否则返回错误。 + +#### 倒排索引 + +`INVERTED INDEX` 指定表的[倒排索引](/contributor-guide/datanode/data-persistence-indexing.md#倒排索引)列。倒排索引列可以是任何列。对于每一个指定的列，GreptimeDB 会创建倒排索引以加速查询。 + +- 如果没有指定 `INVERTED INDEX`，则为 `PRIMARY KEY` 中的列创建倒排索引。 +- 如果指定了 `INVERTED INDEX`，则仅为 `INVERTED INDEX` 中的列创建倒排索引。特别的，当指定为 `INVECTED INDEX()`，代表不会为任何列创建倒排索引。 + +### 表选项 + +用户可以使用 `WITH` 添加表选项。有效的选项包括以下内容： + +| 选项 | 描述 | 值 | +| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ttl` | 表数据的存储时间 | 一个时间范围字符串，例如 `'60m'`, `'1h'` 代表 1 小时， `'14d'` 代表 14 天等。支持的时间单位有：`s` / `m` / `h` / `d`| +| `storage` | 自定义表的存储引擎，存储引擎提供商的名字 | 字符串，类似 `S3`、`Gcs` 等。 必须在 `[[storage.providers]]` 列表里配置, 参考 [configuration](/user-guide/deployments/configuration.md#存储引擎提供商)。 | +| `compaction.type` | Compaction 策略 | 字符串值. 只支持 `twcs`。你可以阅读这篇[文章](https://cassandra.apache.org/doc/latest/cassandra/managing/operating/compaction/twcs.html)来了解 `twcs` compaction 策略 | +| `compaction.twcs.max_active_window_files` | 当前活跃时间窗口内的最大文件数 | 字符串值，如 '8'。只在 `compaction.type` 为 `twcs` 时可用 | +| `compaction.twcs.max_inactive_window_files` | 非活跃时间窗口内的最大文件数 | 字符串值，如 '1'。只在 `compaction.type` 为 `twcs` 时可用 | +| `compaction.twcs.time_window` | Compaction 时间窗口 | 字符串值，如 '1d' 表示 1 天。该表会根据时间戳将数据分区到不同的时间窗口中。只在 `compaction.type` 为 `twcs` 时可用 | +| `memtable.type` | memtable 的类型 | 字符串值，支持 `time_series`，`partition_tree` | +| `append_mode` | 该表是否时 append-only 的 | 字符串值。默认值为 'false'，根据 'merge_mode' 按主键和时间戳删除重复行。设置为 'true' 可以开启 append 模式和创建 append-only 表，保留所有重复的行 | +| `merge_mode` | 合并重复行的策略 | 字符串值。只有当 `append_mode` 为 'false' 时可用。默认值为 `last_row`，保留相同主键和时间戳的最后一行。设置为 `last_non_null` 则保留相同主键和时间戳的最后一个非空字段。 | +| `comment` | 表级注释 | 字符串值. | + +#### 创建指定 TTL 的表 +例如，创建一个存储数据 TTL(Time-To-Live) 为七天的表： + +```sql +CREATE TABLE IF NOT EXISTS temperatures( + ts TIMESTAMP TIME INDEX, + temperature DOUBLE DEFAULT 10, +) with(ttl='7d'); +``` +`ttl` 值是一个字符串，支持以下类型的值： + +- 一个时间范围字符串，如 `1hour 12min 5s`，时间范围对象是时间段的连接。每个时间段由一个整数和一个后缀组成。支持的后缀有： + - `nsec`, `ns` – 纳秒（nanoseconds） + - `usec`, `us` – 微秒（microseconds） + - `msec`, `ms` – 毫秒（milliseconds） + - `seconds`, `second`, `sec`, `s` - 秒 + - `minutes`, `minute`, `min`, `m` - 分钟 + - `hours`, `hour`, `hr`, `h` - 小时 + - `days`, `day`, `d` - 天 + - `weeks`, `week`, `w` - 周 + - `months`, `month`, `M` – 月，定义为 30.44 天 + - `years`, `year`, `y` – 年，定义为 365.25 天 +- `forever`, `NULL`, `0s` （或任何长度为 0 的时间范围，如 `0d`）或空字符串 `''`，表示数据永远不会被删除。 +- `instant`, 注意数据库的 TTL 不能设置为 `instant`。`instant` 表示数据在插入时立即删除，如果你想将输入发送到流任务而不保存它，可以使用 `instant`，请参阅[流管理文档](/user-guide/continuous-aggregation/manage-flow.md#manage-flows)了解更多细节。 +- 未设置，可以使用 `ALTER TABLE UNSET 'ttl'` 来取消表的 `ttl` 设置，这样表将继承数据库的 `ttl` 策略（如果有的话）。 + +如果一张表有自己的 TTL 策略，那么它将使用该 TTL 策略。否则，数据库的 TTL 策略将被应用到表上。 + +比如说，如果表的 TTL 设置为 `forever`，那么无论数据库的 TTL 是什么，数据都不会被删除。但是如果你取消表的 TTL 设置： +```sql +ALTER TABLE UNSET 'ttl'; +``` +那么数据库的 TTL 将会被应用到表上。 + +请注意表和数据库的默认 TTL 策略都是未设置，也就是没有设置 TTL，代表着数据永远不会删除。 + +#### 创建自定义存储的表 +或者创建一个表单独将数据存储在 Google Cloud Storage 服务上： + +```sql +CREATE TABLE IF NOT EXISTS temperatures( + ts TIMESTAMP TIME INDEX, + temperature DOUBLE DEFAULT 10, +) with(ttl='7d', storage="Gcs"); +``` + +#### 创建自定义 compaction 参数的表 +创建带自定义 twcs compaction 参数的表。这个表会尝试根据数据的时间戳将数据按 1 天的时间窗口分区。 +- 它会在最新时间窗口内的文件超过 8 个时合并该窗口的文件 +- 它会将非最新窗口内的文件合并为一个文件 + +```sql +CREATE TABLE IF NOT EXISTS temperatures( + ts TIMESTAMP TIME INDEX, + temperature DOUBLE DEFAULT 10, +) +with( + 'compaction.type'='twcs', + 'compaction.twcs.time_window'='1d', + 'compaction.twcs.max_active_window_files'='8', + 'compaction.twcs.max_inactive_window_files'='1', +); +``` + +#### 创建 Append-Only 表 +创建一个 append-only 表来关闭去重 +```sql +CREATE TABLE IF NOT EXISTS temperatures( + ts TIMESTAMP TIME INDEX, + temperature DOUBLE DEFAULT 10, +) with('append_mode'='true'); +``` + +#### 创建带有 merge 模式的表 + +创建一个带有 `last_row` merge 模式的表，这是默认的 merge 模式。 + +```sql +create table if not exists metrics( + host string, + ts timestamp, + cpu double, + memory double, + TIME INDEX (ts), + PRIMARY KEY(host) +) +with('merge_mode'='last_row'); +``` + +在 `last_row` 模式下，表会通过保留最新的行来合并具有相同主键和时间戳的行。 + +```sql +INSERT INTO metrics VALUES ('host1', 0, 0, NULL), ('host2', 1, NULL, 1); +INSERT INTO metrics VALUES ('host1', 0, NULL, 10), ('host2', 1, 11, NULL); + +SELECT * from metrics ORDER BY host, ts; + ++-------+-------------------------+------+--------+ +| host | ts | cpu | memory | ++-------+-------------------------+------+--------+ +| host1 | 1970-01-01T00:00:00 | | 10.0 | +| host2 | 1970-01-01T00:00:00.001 | 11.0 | | ++-------+-------------------------+------+--------+ +``` + + +创建带有 `last_non_null` merge 模式的表。 + +```sql +create table if not exists metrics( + host string, + ts timestamp, + cpu double, + memory double, + TIME INDEX (ts), + PRIMARY KEY(host) +) +with('merge_mode'='last_non_null'); +``` + +在 `last_non_null` 模式下，表会通过保留每个字段的最新值来合并具有相同主键和时间戳的行。 + +```sql +INSERT INTO metrics VALUES ('host1', 0, 0, NULL), ('host2', 1, NULL, 1); +INSERT INTO metrics VALUES ('host1', 0, NULL, 10), ('host2', 1, 11, NULL); + +SELECT * from metrics ORDER BY host, ts; + ++-------+-------------------------+------+--------+ +| host | ts | cpu | memory | ++-------+-------------------------+------+--------+ +| host1 | 1970-01-01T00:00:00 | 0.0 | 10.0 | +| host2 | 1970-01-01T00:00:00.001 | 11.0 | 1.0 | ++-------+-------------------------+------+--------+ +``` + +### 列选项 + +GreptimeDB 支持以下列选项： + +| 选项 | 描述 | +| ----------------- | --------------------------------------------- | +| NULL | 列值可以为 `null` | +| NOT NULL | 列值不能为 `null` | +| DEFAULT `expr` | 该列的默认值是 `expr`，其类型必须是该列的类型 | +| COMMENT `comment` | 列注释，必须为字符串类型 | +| FULLTEXT | 创建全文索引，可以加速全文搜索操作。仅适用于字符串类型列 | + +表约束 `TIME INDEX` 和 `PRIMARY KEY` 也可以通过列选项设置，但是它们只能在列定义中指定一次，在多个列选项中指定 `PRIMARY KEY` 会报错： + +```sql +CREATE TABLE system_metrics ( + host STRING PRIMARY KEY, + idc STRING PRIMARY KEY, + cpu_util DOUBLE, + memory_util DOUBLE, + disk_util DOUBLE, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP(), + TIME INDEX(ts) +); +``` + +会得到报错： + +```sql + Illegal primary keys definition: not allowed to inline multiple primary keys in columns options +``` + +正确的做法是使用 `PRIMARY KEY()` 来指定多个列作为主键： + +```sql +CREATE TABLE system_metrics ( + host STRING, + idc STRING, + cpu_util DOUBLE, + memory_util DOUBLE, + disk_util DOUBLE, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + PRIMARY KEY(host, idc), +); +``` + +```sql +Query OK, 0 rows affected (0.01 sec) +``` + +#### `FULLTEXT` 列选项 + +`FULLTEXT` 用于创建全文索引，加速全文搜索操作。该选项只能应用于字符串类型的列。 + +使用 `FULLTEXT WITH` 可以指定以下选项： + +- `analyzer`：设置全文索引的分析器语言，支持 `English` 和 `Chinese`。 +- `case_sensitive`：设置全文索引是否区分大小写，支持 `true` 和 `false`。 + +如果不带 `WITH` 选项，`FULLTEXT` 将使用默认值： + +- `analyzer`：默认 `English` +- `case_sensitive`：默认 `false` + +例如，要创建一个带有全文索引的表，配置 `log` 列为全文索引，并指定分析器为 `Chinese` 且不区分大小写： + +```sql +CREATE TABLE IF NOT EXISTS logs( + host STRING PRIMARY KEY, + log STRING FULLTEXT WITH(analyzer = 'Chinese', case_sensitive = 'false'), + ts TIMESTAMP TIME INDEX +); +``` + +更多关于全文索引和全文搜索的使用，请参阅 [日志查询文档](/user-guide/logs/query-logs.md)。 + +### Region 分区规则 + +请参考 [分区](/contributor-guide/frontend/table-sharding.md#partition) 章节. + +## CREATE EXTERNAL TABLE + +### Syntax + +在 `db` 或当前数据库中创建新的文件外部表： + +```sql +CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name +[ + ( + column1 type1 [NULL | NOT NULL] [DEFAULT expr1] [TIME INDEX] [PRIMARY KEY] [COMMENT comment1], + column2 type2 [NULL | NOT NULL] [DEFAULT expr2] [TIME INDEX] [PRIMARY KEY] [COMMENT comment2], + ... + [TIME INDEX (column)], + [PRIMARY KEY(column1, column2, ...)] + ) +] WITH ( + LOCATION = url, + FORMAT = { 'CSV' | 'JSON' | 'PARQUET' | 'ORC' } + [,PATTERN = regex_pattern ] + [,REGION = region ] + [,ENDPOINT = uri ] + [,ACCESS_KEY_ID = key_id ] + [,SECRET_ACCESS_KEY = access_key ] + [,ENABLE_VIRTUAL HOST_STYLE = { TRUE | FALSE }] + [,SESSION_TOKEN = token ] + ... +) +``` + +### 表选项 + +| 选项 | 描述 | 是否必需 | +| ---------- | ------------------------------------------------------------------ | -------- | +| `LOCATION` | 外部表的位置，例如 `s3://[]`, `//[]` | **是** | +| `FORMAT` | 目标文件的格式，例如 JSON，CSV，Parquet, ORC | **是** | +| `PATTERN` | 使用正则来匹配文件，例如 `*_today.parquet` | 可选 | + +#### S3 + +| 选项 | 描述 | 是否必需 | +| --------------------------- | --------------------------------------------------------------- | -------- | +| `REGION` | AWS region 名称，例如 us-east-1 | **是** | +| `ENDPOINT` | The bucket endpoint | 可选 | +| `ACCESS_KEY_ID` | 用于连接 AWS S3 兼容对象存储的访问密钥 ID | 可选 | +| `SECRET_ACCESS_KEY` | 用于连接 AWS S3 兼容对象存储的秘密访问密钥 | 可选 | +| `ENABLE_VIRTUAL HOST_STYLE` | 如果你想要使用 virtual hosting 来定位 bucket，将其设置为 `true` | 可选 | +| `SESSION_TOKEN` | 用于连接 AWS S3 服务的临时凭证 | 可选 | + +### 时间索引列 + +在利用 `CREATE EXTERNAL TABLE` 语句创建外部表时，要求使用 `TIME INDEX` 约束来指定一个时间索引列。 + +### 示例 + +你可以在创建外部表时不带有列定义，列定义将会被自动推断： + +```sql +CREATE EXTERNAL TABLE IF NOT EXISTS city WITH (location='/var/data/city.csv',format='csv'); +``` + +在这个例子中，我们没有明确定义表的列，为满足外边表必须指定**时间索引列**的要求，`CREATE EXTERNAL TABLE` 语句会依据下述规则推断出时间索引列： + +1. 如果可以从文件元数据中推断出时间索引列，那么就用该列作为时间索引列。 +2. 如果存在名为 `greptime_timestamp` 的列（该列的类型必须为 `TIMESTAMP`，否则将抛出错误），那么就用该列作为时间索引列。 +3. 否则，将自动创建名为 `greptime_timestamp` 的列作为时间索引列，并添加 `DEFAULT '1970-01-01 00:00:00+0000'` 约束。 + +或者带有列定义： + +```sql +CREATE EXTERNAL TABLE city ( + host string, + ts timestamp, + cpu float64 default 0, + memory float64, + TIME INDEX (ts), + PRIMARY KEY(host) +) WITH (location='/var/data/city.csv', format='csv'); +``` + +在这个例子中，我们明确定义了 `ts` 列作为时间索引列。如果在文件中没有适合的时间索引列，你也可以创建一个占位符列，并添加 `DEFAULT expr` 约束。 + +## 创建 Flow + +```sql +CREATE [OR REPLACE] FLOW [ IF NOT EXISTS ] +SINK TO +[ EXPIRE AFTER ] +[ COMMENT '' ] +AS +; +``` + +用于创建或更新 Flow 任务，请阅读[Flow 管理文档](/user-guide/continuous-aggregation/manage-flow.md#创建-flow)。 + +## 创建 View + +```sql +CREATE [OR REPLACE] VIEW [ IF NOT EXISTS ] +AS select_statement +``` + +用于创建或更新视图，请阅读[视图用户指南](/user-guide/query-data/view.md#视图)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/data-types.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/data-types.md new file mode 100644 index 000000000..10df05f76 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/data-types.md @@ -0,0 +1,377 @@ +--- +description: SQL 数据类型定义了列可以存储的数据类型，包括字符串、二进制、数值、日期和时间、布尔和 JSON 类型。 +--- + +# 数据类型 + +SQL 数据类型定义了列可以存储的数据类型。当您运行 `DESC TABLE` 命令时，你可以看到每列的数据类型。 + +## 字符串和二进制数据类型 + +| 类型名称 | 描述 | 大小 | +|-----------|-------------|------| +| `String` | UTF-8 编码的字符串。最多可容纳 2,147,483,647 字节的数据 | 字符串的长度 | +| `Binary` | 变长二进制值。最多可容纳 2,147,483,647 字节的数据 | 数据的长度 + 2 字节 | + +`String` 和 `Binary` 的最大容量取决于它们的编码方式以及存储引擎如何处理它们。例如，`String` 值被编码为 UTF-8，如果所有字符的长度为 3 个字节，该字段最多可以存储 715,827,882 个字符。对于 `Binary` 类型，它们最多可以存储 2,147,483,647 字节。 + +## 数值数据类型 + +| 类型名称 | 描述 | 大小 | +|-----------|-------------|------| +| `Int8` | -128 ~ 127 | 1 字节 | +| `Int16` | -32768 ~ 32767 | 2 字节 | +| `Int32` | -2147483648 ~ 2147483647 | 4 字节 | +| `Int64` | -9223372036854775808 ~ 9223372036854775807 | 8 字节 | +| `UInt8` | 0 ~ 255 | 1 字节 | +| `UInt16` | 0 ~ 65535 | 2 字节 | +| `UInt32` | 0 ~ 4294967295 | 4 字节 | +| `UInt64` | 0 ~ 18446744073709551615 | 8 字节 | +| `Float32` | 32 位 IEEE 754 浮点数 | 4 字节 | +| `Float64` | 双精度 IEEE 754 浮点数 | 8 字节 | + +## Decimal 类型 + +GreptimeDB 支持 `decimal` 类型，这是一种定点类型，表示为 `decimal(precision, scale)`，其中 `precision` 是总位数，`scale` 是小数部分的位数。例如，`123.45` 的总位数为 5，小数位数为 2。 + +- `precision` 可以在 [1, 38] 范围内。 +- `scale` 可以在 [0, precision] 范围内。 + +如果未指定总位数和比例，则默认的十进制数是 `decimal(38, 10)`。 + +```sql +CREATE TABLE decimals( + d DECIMAL(3, 2), + ts TIMESTAMP TIME INDEX, +); + +INSERT INTO decimals VALUES ('0.1',1000), ('0.2',2000); + +SELECT * FROM decimals; +``` + +```sql ++------+---------------------+ +| d | ts | ++------+---------------------+ +| 0.10 | 1970-01-01T00:00:01 | +| 0.20 | 1970-01-01T00:00:02 | ++------+---------------------+ +``` + +## 日期和时间类型 + +| 类型名称 | 描述 | 大小 | +|-----------|-------------|------| +| `TimestampSecond` | 64 位时间戳值，精度为秒，范围：`[-262144-01-01 00:00:00, +262143-12-31 23:59:59]` | 8 字节 | +| `TimestampMillisecond` | 64 位时间戳值，毫秒精度，范围：`[-262144-01-01 00:00:00.000, +262143-12-31 23:59:59.999]` | 8 字节 | +| `TimestampMicroSecond` | 64 位时间戳值，微秒精度，范围：`[-262144-01-01 00:00:00.000000, +262143-12-31 23:59:59.999999]` | 8 字节 | +| `TimestampNanosecond` | 64 位时间戳值，纳秒精度，范围： `[1677-09-21 00:12:43.145225, 2262-04-11 23:47:16.854775807]` | 8 字节 | +| `Interval`| 时间间隔 | 对于 `YearMonth`, 使用4字节，对于 `DayTime`, 使用8字节，对于 `MonthDayNano`, 使用16字节 | + +:::tip 注意 +使用 MySQL/PostgreSQL 协议写入时间戳字符串字面量时，值的范围限制为 '0001-01-01 00:00:00' 到 '9999-12-31 23:59:59'。 +::: + +### Interval 类型详解 + +`Interval` 类型用于需要跟踪和操作时间间隔的场景。它的编写语法如下： + +``` +QUANTITY UNIT [QUANTITY UNIT...] +``` + +* `QUANTITY`：是一个数字（可能有符号）， +* `UNIT`：时间单位，可以是 `microsecond`（微秒）、`millisecond`（毫秒）、`second`（秒）、`minute`（分钟）、`hour`（小时）、`day`（天）、`week`（周）、`month`（月）、`year`（年）、`decade`（十年）、`century`（世纪）或这些单位的缩写或复数形式； + +不同的时间单位将会被计算合并，每个单位的符号决定它是增加还是减少总间隔。例如，“1 年 -2 个月”导致净间隔为 10 个月。 +遗憾的是，GreptimeDB 暂时还不支持以 [ISO 8601 时间间隔](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals)格式编写间隔，例如 `P3Y3M700DT133H17M36.789S` 等。但它支持以这种格式输出。 + +让我们来看一些例子： + +```sql +SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::INTERVAL; +``` + +```sql ++---------------------------------------------------------------------+ +| Utf8("2 years 15 months 100 weeks 99 hours 123456789 milliseconds") | ++---------------------------------------------------------------------+ +| P3Y3M700DT133H17M36.789S | ++---------------------------------------------------------------------+ +``` + +55 分钟前： + +```sql +SELECT '-1 hour 5 minute'::INTERVAL; +``` + +```sql ++--------------------------+ +| Utf8("-1 hour 5 minute") | ++--------------------------+ +| P0Y0M0DT0H-55M0S | ++--------------------------+ +``` + +1 小时 5 分钟前： + +```sql +SELECT '-1 hour -5 minute'::INTERVAL; +``` + +```sql ++---------------------------+ +| Utf8("-1 hour -5 minute") | ++---------------------------+ +| P0Y0M0DT-1H-5M0S | ++---------------------------+ +``` + +当然，你可以通过算术运算来操作时间间隔。 +获取 5 分钟前的时间： + +```sql +SELECT now() - INTERVAL '5 minute'; +``` + +```sql ++----------------------------------------------+ +| now() - IntervalMonthDayNano("300000000000") | ++----------------------------------------------+ +| 2024-06-24 21:24:05.012306 | ++----------------------------------------------+ +``` + +注意到你也可以用 `INTERVAL 'literal'` 的方式来输入 interval 类型。`'-1 hour -5 minute'::INTERVAL` 这样的方式其实是一个`CAST` 函数调用。 + +GreptimeDB 还支持类似 `3y2mon4h` 这样不包含空格的简写形式： + +```sql +SELECT INTERVAL '3y2mon4h'; +SELECT '3y2mon4h'::INTERVAL; +``` + +``` ++---------------------------------------------------------+ +| IntervalMonthDayNano("3010670175542044842954670112768") | ++---------------------------------------------------------+ +| P3Y2M0DT4H0M0S | ++---------------------------------------------------------+ ++---------------------------------------------------------+ +| IntervalMonthDayNano("3010670175542044842954670112768") | ++---------------------------------------------------------+ +| P3Y2M0DT4H0M0S | ++---------------------------------------------------------+ +``` + +同样也支持符号数： + +```sql +SELECT INTERVAL '-1h5m'; +SELECT '-1h5m'::INTERVAL; +``` + +``` ++----------------------------------------------+ +| IntervalMonthDayNano("18446740773709551616") | ++----------------------------------------------+ +| P0Y0M0DT0H-55M0S | ++----------------------------------------------+ ++----------------------------------------------+ +| IntervalMonthDayNano("18446740773709551616") | ++----------------------------------------------+ +| P0Y0M0DT0H-55M0S | ++----------------------------------------------+ +``` + +支持的缩写包括： + +| 缩写 | 全称 | +|-------|---------------| +| y | years | +| mon | months | +| w | weeks | +| d | days | +| h | hours | +| m | minutes | +| s | seconds | +| millis| milliseconds | +| ms | milliseconds | +| us | microseconds | +| ns | nanoseconds | + +## JSON 类型 +GreptimeDB 支持 JSON 类型，允许用户存储和查询 JSON 格式的数据。JSON 类型非常灵活，可以存储各种形式的结构化或非结构化数据，适合日志记录、分析和半结构化数据存储等场景。 + +```sql +CREATE TABLE json_data( + my_json JSON, + ts TIMESTAMP TIME INDEX +); + +INSERT INTO json_data VALUES ('{"key1": "value1", "key2": 10}', 1000), + ('{"name": "GreptimeDB", "open_source": true}', 2000); + +SELECT * FROM json_data; +``` + +输出: + +``` ++------------------------------------------+---------------------+ +| my_json | ts | ++------------------------------------------+---------------------+ +| {"key1":"value1","key2":10} | 1970-01-01 00:00:01 | +| {"name":"GreptimeDB","open_source":true} | 1970-01-01 00:00:02 | ++------------------------------------------+---------------------+ +``` + +### 查询 JSON 数据 + +您可以直接查询 JSON 数据，也可以使用 GreptimeDB 提供的 [JSON 函数](./functions/overview.md#json-functions) 提取特定字段。以下是一个示例： + +```sql +SELECT json_get_string(my_json, '$.name') as name FROM json_data; +``` + +输出: + +``` ++---------------------------------------------------+ +| name | ++---------------------------------------------------+ +| NULL | +| GreptimeDB | ++---------------------------------------------------+ +``` + + +## 布尔类型 + +| 类型名称 | 描述 | 大小 | +|-----------|-------------|------| +| `Boolean` | 布尔值 | 1 字节 | + +在 SQL 语句中使用 `TRUE` 或 `FALSE` 表示布尔值。例如： + +```sql +CREATE TABLE bools( + b BOOLEAN, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, +); +``` + +```sql +INSERT INTO bools(b) VALUES (TRUE), (FALSE); +``` + +## 与 MySQL 和 PostgreSQL 兼容的数据类型 + +### 类型别名 + +对于从 MySQL 或 PostgreSQL 迁移到 GreptimeDB 的用户，GreptimeDB 支持以下类型别名。 + +| 数据类型 | 别名 | +| ---------------------- | --------------------------------------------------------------- | +| `String` | `Text`, `TinyText`, `MediumText`, `LongText`, `Varchar`, `Char` | +| `Binary` | `Varbinary` | +| `Int8` | `TinyInt` | +| `Int16` | `SmallInt` | +| `Int32` | `Int` | +| `Int64` | `BigInt` | +| `UInt8` | `UnsignedInt` | +| `UInt16` | `UnsignedTinyInt` | +| `UInt32` | `UnsignedSmallInt` | +| `UInt64` | `UnsignedBigInt` | +| `Float32` | `Float` | +| `Float64` | `Double` | +| `TimestampSecond` | `Timestamp_s`, `Timestamp_sec`, `Timestamp(0)` | +| `TimestampMillisecond` | `Timestamp`, `Timestamp_ms` , `Timestamp(3)` | +| `TimestampMicroSecond` | `Timestamp_us`, `Timestamp(6)` | +| `TimestampNanosecond` | `Timestamp_ns`, `Timestamp(9)` | + +在创建表时也可以使用这些别名类型。 +例如，使用 `Varchar` 代替 `String`，使用 `Double` 代替 `Float64`，使用 `Timestamp(0)` 代替 `TimestampSecond`。 + +```sql +CREATE TABLE alias_types ( + s TEXT, + i Double, + ts0 Timestamp(0) DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + PRIMARY KEY(s) +); +``` + +### 日期和时间类型 + +除了在 GreptimeDB 中用作默认时间类型的 `Timestamp` 类型之外 +GreptimeDB 还支持与 MySQL 和 PostgreSQL 兼容的 `Date` 和 `DateTime` 类型。 + +| 类型名称 | 描述 | 大小 | +|-----------|-------------|------| +|`Date` |32 位日期值，表示自 UNIX Epoch 以来的天数 | 4 字节 | +|`DateTime` |64 位日期时间值，表示自 UNIX Epoch 以来的毫秒数| 8 字节 | + +## 示例 + +### 创建表 + +```sql +CREATE TABLE data_types ( + s STRING, + vbi BINARY, + b BOOLEAN, + tint INT8, + sint INT16, + i INT32, + bint INT64, + utint UINT8, + usint UINT16, + ui UINT32, + ubint UINT64, + f FLOAT32, + d FLOAT64, + dm DECIMAL(3, 2), + dt DATE, + dtt DATETIME, + ts0 TIMESTAMPSECOND, + ts3 TIMESTAMPMILLISECOND, + ts6 TIMESTAMPMICROSECOND, + ts9 TIMESTAMPNANOSECOND DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + PRIMARY KEY(s)); +``` + +### 描述表结构 + +```sh +DESC TABLE data_types; +``` + +```sql ++--------+----------------------+------+------+---------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------+----------------------+------+------+---------------------+---------------+ +| s | String | PRI | YES | | TAG | +| vbi | Binary | | YES | | FIELD | +| b | Boolean | | YES | | FIELD | +| tint | Int8 | | YES | | FIELD | +| sint | Int16 | | YES | | FIELD | +| i | Int32 | | YES | | FIELD | +| bint | Int64 | | YES | | FIELD | +| utint | UInt8 | | YES | | FIELD | +| usint | UInt16 | | YES | | FIELD | +| ui | UInt32 | | YES | | FIELD | +| ubint | UInt64 | | YES | | FIELD | +| f | Float32 | | YES | | FIELD | +| d | Float64 | | YES | | FIELD | +| dm | Decimal(3, 2) | | YES | | FIELD | +| dt | Date | | YES | | FIELD | +| dtt | DateTime | | YES | | FIELD | +| ts0 | TimestampSecond | | YES | | FIELD | +| ts3 | TimestampMillisecond | | YES | | FIELD | +| ts6 | TimestampMicrosecond | | YES | | FIELD | +| ts9 | TimestampNanosecond | PRI | NO | current_timestamp() | TIMESTAMP | ++--------+----------------------+------+------+---------------------+---------------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/delete.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/delete.md new file mode 100644 index 000000000..ee4c35007 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/delete.md @@ -0,0 +1,29 @@ +--- +description: DELETE 用于从表中删除行数据，满足条件的行会立刻被标记，后续查询无法获取这些行数据。 +--- + +# DELETE + +`DELETE` 用于从表中删除行数据。 + +## Syntax + +```sql +DELETE FROM [db.]table WHERE expr +``` + +上述命令从表 `[db.]table` 中删除满足 `expr` 的行。被删除的行会立刻被标记，后续的查询立刻不能获取到这些行数据。 + +## 示例 + +例如，有一个带有主键 `host` 的表： + +```sql +CREATE TABLE monitor ( host STRING, ts TIMESTAMP, cpu DOUBLE DEFAULT 0, memory DOUBLE, TIME INDEX (ts), PRIMARY KEY(host)) ; +``` + +删除 host 为 `host1` 以及时间戳为 `1655276557000` 的行： + +```sql +DELETE FROM monitor WHERE host = 'host1' and ts = 1655276557000; +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/describe_table.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/describe_table.md new file mode 100644 index 000000000..144ed6207 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/describe_table.md @@ -0,0 +1,43 @@ +--- +description: DESCRIBE TABLE 用于描述数据库中表的结构，包括列名、类型、主键、是否为空、默认值和语义类型。 +--- + +# DESCRIBE TABLE + +`DESCRIBE [TABLE] [db.]table` 描述了 `db` 或当前使用的数据库中的表结构。 + +## 示例 + +描述表 `monitor`: + +```sql +DESCRIBE TABLE monitor; +``` + +或者 + +```sql +DESCRIBE monitor; +``` + +```sql +```sql ++--------+----------------------+------+------+---------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------+----------------------+------+------+---------------------+---------------+ +| host | String | PRI | YES | | TAG | +| ts | TimestampMillisecond | PRI | NO | current_timestamp() | TIMESTAMP | +| cpu | Float64 | | YES | 0 | FIELD | +| memory | Float64 | | YES | | FIELD | ++--------+----------------------+------+------+---------------------+---------------+ +4 rows in set (0.00 sec) +``` + +结果中展示相应的表结构： + +* `Column`: 列名 +* `Type`: 列类型 +* `Key`: `PRI` 表示该列在 `PRIMARY KEY` 约束里。 +* `Null`: `YES` 表示可以为空，否则为 `NO` +* `Default`: 列的默认值 +* `Semantic Type`：该列的语义类型，对应数据模型中的 `TAG`、`FIELD` 或 `TIMESTAMP`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/distinct.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/distinct.md new file mode 100644 index 000000000..6b7d1e850 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/distinct.md @@ -0,0 +1,22 @@ +--- +description: SELECT DISTINCT 用于从一组数据中选择唯一值，可以与过滤条件结合使用。 +--- + +# DISTINCT + +`SELECT DISTINCT` 用于从一组数据中选择唯一值，从查询的输出中返回唯一值，其基本语法如下： + +```sql +SELECT DISTINCT idc +FROM system_metrics; +``` + +`SELECT DISTINCT` 可以与 filter 结合使用： + +```sql +SELECT DISTINCT idc, host +FROM system_metrics +WHERE host != 'host2'; +``` + +`SELECT DISTINCT` 是 GreptimeDB SQL 中一个简单但功能强大的命令，它允许用户将数据压缩成唯一值的综合。它可以用于一个或多个列，使其在数据分析和报告中非常灵活。使用 `SELECT DISTINCT` 是获取表中存储的数据类型概述的好方法。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/drop.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/drop.md new file mode 100644 index 000000000..aace111ba --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/drop.md @@ -0,0 +1,93 @@ +--- +description: DROP 用于删除数据库、表、流或视图，操作不可撤销，需谨慎使用。 +--- + +# DROP + +## DROP DATABASE + +`DROP DATABASE` 用于删除数据库，它删除数据库的目录项并删除包含数据的目录。 + +:::danger 危险操作 + +`DROP DATABASE` 无法撤消。请谨慎使用！ + +::: + +### 语法 + +```sql +DROP DATABASE [ IF EXISTS ] db_name +``` + +- `IF EXISTS`: 如果数据库不存在，则不抛出错误。 +- `db_name`: 要删除的数据库的名称。 + +### 示例 + +删除名为 `test` 的数据库： + +```sql +DROP DATABASE test; +``` + +## DROP TABLE + +`DROP TABLE` 从数据库中删除表，它将删除该表的表定义和所有表数据、索引、规则和约束。 + +:::danger 危险操作 + +`DROP TABLE` 无法撤消。请谨慎使用！ + +::: + +### 语法 + +```sql +DROP TABLE [ IF EXISTS ] table_name +``` + +- `IF EXISTS`: 如果表不存在，则不抛出错误。 +- `table_name`: 要删除的表的名称。 + +### 示例 + +删除 `monitor` 表： + +```sql +DROP TABLE monitor; +``` + +## 删除 Flow + +```sql +DROP FLOW [ IF EXISTS ] flow_name; +``` + +- `IF EXISTS`: 如果流不存在，则不抛出错误。 +- `flow_name`: 要删除的流的名称。 + +```sql +DROP FLOW IF EXISTS test_flow; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +## 删除 View + +```sql +DROP VIEW [ IF EXISTS ] view_name; +``` + +- `IF EXISTS`: 如果视图不存在，则不抛出错误。 +- `view_name`: 要删除的视图的名称。 + +```sql +DROP VIEW IF EXISTS test_view; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/explain.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/explain.md new file mode 100644 index 000000000..357edb592 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/explain.md @@ -0,0 +1,57 @@ +--- +description: EXPLAIN 用于提供语句的执行计划，ANALYZE 子句将执行语句并测量每个计划节点的时间和输出行数。 +--- + +# EXPLAIN + +`EXPLAIN` 用于提供语句的执行计划。 + +## Syntax + +```sql +EXPLAIN [ANALYZE] SELECT ... +``` + +`ANALYZE` 子句将执行语句并测量每个计划节点花费的时间以及输出的总行数等。 + +## 示例 + +```sql +EXPLAIN SELECT * FROM monitor where host='host1'; +``` + +```sql +| plan_type | plan +| logical_plan | Projection: monitor.host, monitor.ts, monitor.cpu, monitor.memory + Filter: monitor.host = Utf8("host1") + TableScan: monitor projection=[host, ts, cpu, memory], partial_filters=[monitor.host = Utf8("host1")] | +| physical_plan | ProjectionExec: expr=[host@0 as host, ts@1 as ts, cpu@2 as cpu, memory@3 as memory] + CoalesceBatchesExec: target_batch_size=4096 + FilterExec: host@0 = host1 + RepartitionExec: partitioning=RoundRobinBatch(10) + ExecutionPlan(PlaceHolder) +``` + +`plan_type` 列指示了是 `logical_plan` 还是 `physical_plan`，`plan` 列详细说明了执行计划。 + +使用 `ANALYZE` 解释执行计划： + +```sql +EXPLAIN ANALYZE SELECT * FROM monitor where host='host1'; +``` + +```sql +| plan_type | plan +| Plan with Metrics | CoalescePartitionsExec, metrics=[output_rows=1, elapsed_compute=79.167µs, spill_count=0, spilled_bytes=0, mem_used=0] + ProjectionExec: expr=[host@0 as host, ts@1 as ts, cpu@2 as cpu, memory@3 as memory], metrics=[output_rows=1, elapsed_compute=17.176µs, spill_count=0, spilled_bytes=0, mem_used=0] + CoalesceBatchesExec: target_batch_size=4096, metrics=[output_rows=1, elapsed_compute=14.248µs, spill_count=0, spilled_bytes=0, mem_used=0] + CoalesceBatchesExec: target_batch_size=4096, metrics=[output_rows=1, elapsed_compute=17.21µs, spill_count=0, spilled_bytes=0, mem_used=0] + FilterExec: host@0 = host1, metrics=[output_rows=1, elapsed_compute=541.801µs, spill_count=0, spilled_bytes=0, mem_used=0] + CoalesceBatchesExec: target_batch_size=4096, metrics=[output_rows=3, elapsed_compute=43.004µs, spill_count=0, spilled_bytes=0, mem_used=0] + RepartitionExec: partitioning=RoundRobinBatch(10), metrics=[fetch_time=5.832958ms, repart_time=10ns, send_time=2.467µs] + RepartitionExec: partitioning=RoundRobinBatch(10), metrics=[fetch_time=386.585µs, repart_time=1ns, send_time=7.833µs] + ExecutionPlan(PlaceHolder), metrics=[] + +``` + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/df-functions.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/df-functions.md new file mode 100644 index 000000000..f590d01f2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/df-functions.md @@ -0,0 +1,5036 @@ +--- +description: 介绍了 Apache DataFusion 项目中的函数，包括标量函数和窗口函数的定义、使用方法和相关的 SQL 查询示例。 +--- + +# DataFusion Functions + +This page is generated from the Apache DataFusion project's documents: + * [DataFusion Scalar Functions](https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/scalar_functions.md) + * [DataFusion Scalar Functions (NEW)](https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/scalar_functions_new.md) + * [DataFusion Aggregate Functions](https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/aggregate_functions.md) + * [DataFusion Window Functions](https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/window_functions.md) + + + +## Scalar Functions + +Scalar functions operate on a single row at a time and return a single value. + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. +Please see the [Scalar Functions (new)](#scalar-functions-new) page for +the rest of the documentation. + +### Math Functions + +- [abs](#abs) +- [acos](#acos) +- [acosh](#acosh) +- [asin](#asin) +- [asinh](#asinh) +- [atan](#atan) +- [atanh](#atanh) +- [atan2](#atan2) +- [cbrt](#cbrt) +- [ceil](#ceil) +- [cos](#cos) +- [cosh](#cosh) +- [degrees](#degrees) +- [exp](#exp) +- [factorial](#factorial) +- [floor](#floor) +- [gcd](#gcd) +- [isnan](#isnan) +- [iszero](#iszero) +- [lcm](#lcm) +- [ln](#ln) +- [log10](#log10) +- [log2](#log2) +- [nanvl](#nanvl) +- [pi](#pi) +- [power](#power) +- [pow](#pow) +- [radians](#radians) +- [random](#random) +- [round](#round) +- [signum](#signum) +- [sin](#sin) +- [sinh](#sinh) +- [sqrt](#sqrt) +- [tan](#tan) +- [tanh](#tanh) +- [trunc](#trunc) + +##### `abs` + +Returns the absolute value of a number. + +``` +abs(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `acos` + +Returns the arc cosine or inverse cosine of a number. + +``` +acos(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `acosh` + +Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. + +``` +acosh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `asin` + +Returns the arc sine or inverse sine of a number. + +``` +asin(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `asinh` + +Returns the area hyperbolic sine or inverse hyperbolic sine of a number. + +``` +asinh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `atan` + +Returns the arc tangent or inverse tangent of a number. + +``` +atan(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `atanh` + +Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. + +``` +atanh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `atan2` + +Returns the arc tangent or inverse tangent of `expression_y / expression_x`. + +``` +atan2(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `cbrt` + +Returns the cube root of a number. + +``` +cbrt(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `ceil` + +Returns the nearest integer greater than or equal to a number. + +``` +ceil(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `cos` + +Returns the cosine of a number. + +``` +cos(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `cosh` + +Returns the hyperbolic cosine of a number. + +``` +cosh(numeric_expression) +``` + +##### `degrees` + +Converts radians to degrees. + +``` +degrees(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `exp` + +Returns the base-e exponential of a number. + +``` +exp(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to use as the exponent. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `factorial` + +Factorial. Returns 1 if value is less than 2. + +``` +factorial(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `floor` + +Returns the nearest integer less than or equal to a number. + +``` +floor(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `gcd` + +Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero. + +``` +gcd(expression_x, expression_y) +``` + +###### Arguments + +- **expression_x**: First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `isnan` + +Returns true if a given number is +NaN or -NaN otherwise returns false. + +``` +isnan(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `iszero` + +Returns true if a given number is +0.0 or -0.0 otherwise returns false. + +``` +iszero(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `lcm` + +Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero. + +``` +lcm(expression_x, expression_y) +``` + +###### Arguments + +- **expression_x**: First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `ln` + +Returns the natural logarithm of a number. + +``` +ln(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `log10` + +Returns the base-10 logarithm of a number. + +``` +log10(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `log2` + +Returns the base-2 logarithm of a number. + +``` +log2(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `nanvl` + +Returns the first argument if it's not _NaN_. +Returns the second argument otherwise. + +``` +nanvl(expression_x, expression_y) +``` + +###### Arguments + +- **expression_x**: Numeric expression to return if it's not _NaN_. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Numeric expression to return if the first expression is _NaN_. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `pi` + +Returns an approximate value of π. + +``` +pi() +``` + +##### `power` + +Returns a base expression raised to the power of an exponent. + +``` +power(base, exponent) +``` + +###### Arguments + +- **base**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **exponent**: Exponent numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +###### Aliases + +- pow + +##### `pow` + +_Alias of [power](#power)._ + +##### `radians` + +Converts degrees to radians. + +``` +radians(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `random` + +Returns a random float value in the range [0, 1). +The random seed is unique to each row. + +``` +random() +``` + +##### `round` + +Rounds a number to the nearest integer. + +``` +round(numeric_expression[, decimal_places]) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **decimal_places**: Optional. The number of decimal places to round to. + Defaults to 0. + +##### `signum` + +Returns the sign of a number. +Negative numbers return `-1`. +Zero and positive numbers return `1`. + +``` +signum(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `sin` + +Returns the sine of a number. + +``` +sin(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `sinh` + +Returns the hyperbolic sine of a number. + +``` +sinh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `sqrt` + +Returns the square root of a number. + +``` +sqrt(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `tan` + +Returns the tangent of a number. + +``` +tan(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `tanh` + +Returns the hyperbolic tangent of a number. + +``` +tanh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `trunc` + +Truncates a number to a whole number or truncated to the specified decimal places. + +``` +trunc(numeric_expression[, decimal_places]) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +- **decimal_places**: Optional. The number of decimal places to + truncate to. Defaults to 0 (truncate to a whole number). If + `decimal_places` is a positive integer, truncates digits to the + right of the decimal point. If `decimal_places` is a negative + integer, replaces digits to the left of the decimal point with `0`. + +### Conditional Functions + +See the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) + +### String Functions + +See the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) + +##### `position` + +Returns the position of `substr` in `origstr` (counting from 1). If `substr` does +not appear in `origstr`, return 0. + +``` +position(substr in origstr) +``` + +###### Arguments + +- **substr**: The pattern string. +- **origstr**: The model string. + +### Time and Date Functions + +- [now](#now) +- [current_date](#current-date) +- [current_time](#current-time) +- [date_bin](#date-bin) +- [date_trunc](#date-trunc) +- [datetrunc](#datetrunc) +- [date_part](#date-part) +- [datepart](#datepart) +- [extract](#extract) +- [today](#today) +- [make_date](#make-date) +- [to_char](#to-char) +- [to_local_time](#to-local-time) +- [to_timestamp](#to-timestamp) +- [to_timestamp_millis](#to-timestamp-millis) +- [to_timestamp_micros](#to-timestamp-micros) +- [to_timestamp_seconds](#to-timestamp-seconds) +- [to_timestamp_nanos](#to-timestamp-nanos) +- [from_unixtime](#from-unixtime) +- [to_unixtime](#to-unixtime) + +##### `now` + +Returns the current UTC timestamp. + +The `now()` return value is determined at query time and will return the same timestamp, +no matter when in the query plan the function executes. + +``` +now() +``` + +##### `current_date` + +Returns the current UTC date. + +The `current_date()` return value is determined at query time and will return the same date, +no matter when in the query plan the function executes. + +``` +current_date() +``` + +###### Aliases + +- today + +##### `today` + +_Alias of [current_date](#current-date)._ + +##### `current_time` + +Returns the current UTC time. + +The `current_time()` return value is determined at query time and will return the same time, +no matter when in the query plan the function executes. + +``` +current_time() +``` + +##### `date_bin` + +Calculates time intervals and returns the start of the interval nearest to the specified timestamp. +Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" +and applying an aggregate or selector function to each window. + +For example, if you "bin" or "window" data into 15 minute intervals, an input +timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 +minute bin it is in: `2023-01-01T18:15:00Z`. + +``` +date_bin(interval, expression, origin-timestamp) +``` + +###### Arguments + +- **interval**: Bin interval. +- **expression**: Time expression to operate on. + Can be a constant, column, or function. +- **origin-timestamp**: Optional. Starting point used to determine bin boundaries. If not specified + defaults `1970-01-01T00:00:00Z` (the UNIX epoch in UTC). + +The following intervals are supported: + +- nanoseconds +- microseconds +- milliseconds +- seconds +- minutes +- hours +- days +- weeks +- months +- years +- century + +##### `date_trunc` + +Truncates a timestamp value to a specified precision. + +``` +date_trunc(precision, expression) +``` + +###### Arguments + +- **precision**: Time precision to truncate to. + The following precisions are supported: + + - year / YEAR + - quarter / QUARTER + - month / MONTH + - week / WEEK + - day / DAY + - hour / HOUR + - minute / MINUTE + - second / SECOND + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +###### Aliases + +- datetrunc + +##### `datetrunc` + +_Alias of [date_trunc](#date-trunc)._ + +##### `date_part` + +Returns the specified part of the date as an integer. + +``` +date_part(part, expression) +``` + +###### Arguments + +- **part**: Part of the date to return. + The following date parts are supported: + + - year + - quarter _(emits value in inclusive range [1, 4] based on which quartile of the year the date is in)_ + - month + - week _(week of the year)_ + - day _(day of the month)_ + - hour + - minute + - second + - millisecond + - microsecond + - nanosecond + - dow _(day of the week)_ + - doy _(day of the year)_ + - epoch _(seconds since Unix epoch)_ + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +###### Aliases + +- datepart + +##### `datepart` + +_Alias of [date_part](#date-part)._ + +##### `extract` + +Returns a sub-field from a time value as an integer. + +``` +extract(field FROM source) +``` + +Equivalent to calling `date_part('field', source)`. For example, these are equivalent: + +```sql +extract(day FROM '2024-04-13'::date) +date_part('day', '2024-04-13'::date) +``` + +See [date_part](#date-part). + +##### `make_date` + +Make a date from year/month/day component parts. + +``` +make_date(year, month, day) +``` + +###### Arguments + +- **year**: Year to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **month**: Month to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **day**: Day to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. + +###### Example + +``` +> select make_date(2023, 1, 31); ++-------------------------------------------+ +| make_date(Int64(2023),Int64(1),Int64(31)) | ++-------------------------------------------+ +| 2023-01-31 | ++-------------------------------------------+ +> select make_date('2023', '01', '31'); ++-----------------------------------------------+ +| make_date(Utf8("2023"),Utf8("01"),Utf8("31")) | ++-----------------------------------------------+ +| 2023-01-31 | ++-----------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/make_date.rs) + +##### `to_char` + +Returns a string representation of a date, time, timestamp or duration based +on a [Chrono format]. Unlike the PostgreSQL equivalent of this function +numerical formatting is not supported. + +``` +to_char(expression, format) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function that results in a + date, time, timestamp or duration. +- **format**: A [Chrono format] string to use to convert the expression. + +###### Example + +``` +> select to_char('2023-03-01'::date, '%d-%m-%Y'); ++----------------------------------------------+ +| to_char(Utf8("2023-03-01"),Utf8("%d-%m-%Y")) | ++----------------------------------------------+ +| 01-03-2023 | ++----------------------------------------------+ +``` + +Additional examples can be found [here] + +[here]: https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_char.rs + +###### Aliases + +- date_format + +##### `to_local_time` + +Converts a timestamp with a timezone to a timestamp without a timezone (with no offset or +timezone information). This function handles daylight saving time changes. + +``` +to_local_time(expression) +``` + +###### Arguments + +- **expression**: Time expression to operate on. Can be a constant, column, or function. + +###### Example + +``` +> SELECT to_local_time('2024-04-01T00:00:20Z'::timestamp); ++---------------------------------------------+ +| to_local_time(Utf8("2024-04-01T00:00:20Z")) | ++---------------------------------------------+ +| 2024-04-01T00:00:20 | ++---------------------------------------------+ + +> SELECT to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels'); ++---------------------------------------------+ +| to_local_time(Utf8("2024-04-01T00:00:20Z")) | ++---------------------------------------------+ +| 2024-04-01T00:00:20 | ++---------------------------------------------+ + +> SELECT + time, + arrow_typeof(time) as type, + to_local_time(time) as to_local_time, + arrow_typeof(to_local_time(time)) as to_local_time_type +FROM ( + SELECT '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' AS time +); ++---------------------------+------------------------------------------------+---------------------+-----------------------------+ +| time | type | to_local_time | to_local_time_type | ++---------------------------+------------------------------------------------+---------------------+-----------------------------+ +| 2024-04-01T00:00:20+02:00 | Timestamp(Nanosecond, Some("Europe/Brussels")) | 2024-04-01T00:00:20 | Timestamp(Nanosecond, None) | ++---------------------------+------------------------------------------------+---------------------+-----------------------------+ + +## combine `to_local_time()` with `date_bin()` to bin on boundaries in the timezone rather +## than UTC boundaries + +> SELECT date_bin(interval '1 day', to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels')) AS date_bin; ++---------------------+ +| date_bin | ++---------------------+ +| 2024-04-01T00:00:00 | ++---------------------+ + +> SELECT date_bin(interval '1 day', to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels')) AT TIME ZONE 'Europe/Brussels' AS date_bin_with_timezone; ++---------------------------+ +| date_bin_with_timezone | ++---------------------------+ +| 2024-04-01T00:00:00+02:00 | ++---------------------------+ +``` + +##### `to_timestamp` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00Z`). +Supports strings, integer, unsigned integer, and double types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats] are provided. +Integers, unsigned integers, and doubles are interpreted as seconds since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding timestamp. + +Note: `to_timestamp` returns `Timestamp(Nanosecond)`. The supported range for integer input is between `-9223372037` and `9223372036`. +Supported range for string input is between `1677-09-21T00:12:44.0` and `2262-04-11T23:47:16.0`. Please use `to_timestamp_seconds` +for the input outside of supported bounds. + +``` +to_timestamp(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +[chrono format]: https://docs.rs/chrono/latest/chrono/format/strftime/index.html + +###### Example + +``` +> select to_timestamp('2023-01-31T09:26:56.123456789-05:00'); ++-----------------------------------------------------------+ +| to_timestamp(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++-----------------------------------------------------------+ +| 2023-01-31T14:26:56.123456789 | ++-----------------------------------------------------------+ +> select to_timestamp('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++--------------------------------------------------------------------------------------------------------+ +| to_timestamp(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++--------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00.123456789 | ++--------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `to_timestamp_millis` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`). +Supports strings, integer, and unsigned integer types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format]s are provided. +Integers and unsigned integers are interpreted as milliseconds since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding timestamp. + +``` +to_timestamp_millis(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_timestamp_millis('2023-01-31T09:26:56.123456789-05:00'); ++------------------------------------------------------------------+ +| to_timestamp_millis(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++------------------------------------------------------------------+ +| 2023-01-31T14:26:56.123 | ++------------------------------------------------------------------+ +> select to_timestamp_millis('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++---------------------------------------------------------------------------------------------------------------+ +| to_timestamp_millis(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++---------------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00.123 | ++---------------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `to_timestamp_micros` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000Z`). +Supports strings, integer, and unsigned integer types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format]s are provided. +Integers and unsigned integers are interpreted as microseconds since the unix epoch (`1970-01-01T00:00:00Z`) +Returns the corresponding timestamp. + +``` +to_timestamp_micros(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_timestamp_micros('2023-01-31T09:26:56.123456789-05:00'); ++------------------------------------------------------------------+ +| to_timestamp_micros(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++------------------------------------------------------------------+ +| 2023-01-31T14:26:56.123456 | ++------------------------------------------------------------------+ +> select to_timestamp_micros('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++---------------------------------------------------------------------------------------------------------------+ +| to_timestamp_micros(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++---------------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00.123456 | ++---------------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `to_timestamp_nanos` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000000Z`). +Supports strings, integer, and unsigned integer types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format]s are provided. +Integers and unsigned integers are interpreted as nanoseconds since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding timestamp. + +``` +to_timestamp_nanos(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_timestamp_nanos('2023-01-31T09:26:56.123456789-05:00'); ++-----------------------------------------------------------------+ +| to_timestamp_nanos(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++-----------------------------------------------------------------+ +| 2023-01-31T14:26:56.123456789 | ++-----------------------------------------------------------------+ +> select to_timestamp_nanos('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++--------------------------------------------------------------------------------------------------------------+ +| to_timestamp_nanos(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++--------------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00.123456789 | ++---------------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `to_timestamp_seconds` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`). +Supports strings, integer, and unsigned integer types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format]s are provided. +Integers and unsigned integers are interpreted as seconds since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding timestamp. + +``` +to_timestamp_seconds(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_timestamp_seconds('2023-01-31T09:26:56.123456789-05:00'); ++-------------------------------------------------------------------+ +| to_timestamp_seconds(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++-------------------------------------------------------------------+ +| 2023-01-31T14:26:56 | ++-------------------------------------------------------------------+ +> select to_timestamp_seconds('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++----------------------------------------------------------------------------------------------------------------+ +| to_timestamp_seconds(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++----------------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00 | ++----------------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `from_unixtime` + +Converts an integer to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). +Integers and unsigned integers are interpreted as nanoseconds since the unix epoch (`1970-01-01T00:00:00Z`) +return the corresponding timestamp. + +``` +from_unixtime(expression) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `to_unixtime` + +Converts a value to seconds since the unix epoch (`1970-01-01T00:00:00Z`). +Supports strings, dates, timestamps and double types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats] are provided. + +``` +to_unixtime(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_unixtime('2020-09-08T12:00:00+00:00'); ++------------------------------------------------+ +| to_unixtime(Utf8("2020-09-08T12:00:00+00:00")) | ++------------------------------------------------+ +| 1599566400 | ++------------------------------------------------+ +> select to_unixtime('01-14-2023 01:01:30+05:30', '%q', '%d-%m-%Y %H/%M/%S', '%+', '%m-%d-%Y %H:%M:%S%#z'); ++-----------------------------------------------------------------------------------------------------------------------------+ +| to_unixtime(Utf8("01-14-2023 01:01:30+05:30"),Utf8("%q"),Utf8("%d-%m-%Y %H/%M/%S"),Utf8("%+"),Utf8("%m-%d-%Y %H:%M:%S%#z")) | ++-----------------------------------------------------------------------------------------------------------------------------+ +| 1673638290 | ++-----------------------------------------------------------------------------------------------------------------------------+ +``` + +### Array Functions + +- [array_any_value](#array-any-value) +- [array_append](#array-append) +- [array_sort](#array-sort) +- [array_cat](#array-cat) +- [array_concat](#array-concat) +- [array_contains](#array-contains) +- [array_dims](#array-dims) +- [array_distance](#array-distance) +- [array_distinct](#array-distinct) +- [array_has](#array-has) +- [array_has_all](#array-has-all) +- [array_has_any](#array-has-any) +- [array_element](#array-element) +- [array_empty](#array-empty) +- [array_except](#array-except) +- [array_extract](#array-extract) +- [array_fill](#array-fill) +- [array_indexof](#array-indexof) +- [array_intersect](#array-intersect) +- [array_join](#array-join) +- [array_length](#array-length) +- [array_ndims](#array-ndims) +- [array_prepend](#array-prepend) +- [array_pop_front](#array-pop-front) +- [array_pop_back](#array-pop-back) +- [array_position](#array-position) +- [array_positions](#array-positions) +- [array_push_back](#array-push-back) +- [array_push_front](#array-push-front) +- [array_repeat](#array-repeat) +- [array_resize](#array-resize) +- [array_remove](#array-remove) +- [array_remove_n](#array-remove-n) +- [array_remove_all](#array-remove-all) +- [array_replace](#array-replace) +- [array_replace_n](#array-replace-n) +- [array_replace_all](#array-replace-all) +- [array_reverse](#array-reverse) +- [array_slice](#array-slice) +- [array_to_string](#array-to-string) +- [array_union](#array-union) +- [cardinality](#cardinality) +- [empty](#empty) +- [flatten](#flatten) +- [generate_series](#generate-series) +- [list_any_value](#list-any-value) +- [list_append](#list-append) +- [list_sort](#list-sort) +- [list_cat](#list-cat) +- [list_concat](#list-concat) +- [list_dims](#list-dims) +- [list_distance](#list-distance) +- [list_distinct](#list-distinct) +- [list_element](#list-element) +- [list_except](#list-except) +- [list_extract](#list-extract) +- [list_has](#list-has) +- [list_has_all](#list-has-all) +- [list_has_any](#list-has-any) +- [list_indexof](#list-indexof) +- [list_intersect](#list-intersect) +- [list_join](#list-join) +- [list_length](#list-length) +- [list_ndims](#list-ndims) +- [list_prepend](#list-prepend) +- [list_pop_back](#list-pop-back) +- [list_pop_front](#list-pop-front) +- [list_position](#list-position) +- [list_positions](#list-positions) +- [list_push_back](#list-push-back) +- [list_push_front](#list-push-front) +- [list_repeat](#list-repeat) +- [list_resize](#list-resize) +- [list_remove](#list-remove) +- [list_remove_n](#list-remove-n) +- [list_remove_all](#list-remove-all) +- [list_replace](#list-replace) +- [list_replace_n](#list-replace-n) +- [list_replace_all](#list-replace-all) +- [list_slice](#list-slice) +- [list_to_string](#list-to-string) +- [list_union](#list-union) +- [make_array](#make-array) +- [make_list](#make-list) +- [string_to_array](#string-to-array) +- [string_to_list](#string-to-list) +- [trim_array](#trim-array) +- [unnest](#unnest) +- [range](#range) + +##### `array_any_value` + +Returns the first non-null element in the array. + +``` +array_any_value(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_any_value([NULL, 1, 2, 3]); ++--------------------------------------------------------------+ +| array_any_value(List([NULL,1,2,3])) | ++--------------------------------------------------------------+ +| 1 | ++--------------------------------------------------------------+ +``` + +##### `array_append` + +Appends an element to the end of an array. + +``` +array_append(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to append to the array. + +###### Example + +``` +> select array_append([1, 2, 3], 4); ++--------------------------------------+ +| array_append(List([1,2,3]),Int64(4)) | ++--------------------------------------+ +| [1, 2, 3, 4] | ++--------------------------------------+ +``` + +###### Aliases + +- array_push_back +- list_append +- list_push_back + +##### `array_sort` + +Sort array. + +``` +array_sort(array, desc, nulls_first) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **desc**: Whether to sort in descending order(`ASC` or `DESC`). +- **nulls_first**: Whether to sort nulls first(`NULLS FIRST` or `NULLS LAST`). + +###### Example + +``` +> select array_sort([3, 1, 2]); ++-----------------------------+ +| array_sort(List([3,1,2])) | ++-----------------------------+ +| [1, 2, 3] | ++-----------------------------+ +``` + +###### Aliases + +- list_sort + +##### `array_resize` + +Resizes the list to contain size elements. Initializes new elements with value or empty if value is not set. + +``` +array_resize(array, size, value) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **size**: New size of given array. +- **value**: Defines new elements' value or empty if value is not set. + +###### Example + +``` +> select array_resize([1, 2, 3], 5, 0); ++-------------------------------------+ +| array_resize(List([1,2,3],5,0)) | ++-------------------------------------+ +| [1, 2, 3, 0, 0] | ++-------------------------------------+ +``` + +###### Aliases + +- list_resize + +##### `array_cat` + +_Alias of [array_concat](#array-concat)._ + +##### `array_concat` + +Concatenates arrays. + +``` +array_concat(array[, ..., array_n]) +``` + +###### Arguments + +- **array**: Array expression to concatenate. + Can be a constant, column, or function, and any combination of array operators. +- **array_n**: Subsequent array column or literal array to concatenate. + +###### Example + +``` +> select array_concat([1, 2], [3, 4], [5, 6]); ++---------------------------------------------------+ +| array_concat(List([1,2]),List([3,4]),List([5,6])) | ++---------------------------------------------------+ +| [1, 2, 3, 4, 5, 6] | ++---------------------------------------------------+ +``` + +###### Aliases + +- array_cat +- list_cat +- list_concat + +##### `array_contains` + +_Alias of [array_has](#array-has)._ + +##### `array_has` + +Returns true if the array contains the element + +``` +array_has(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Scalar or Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Aliases + +- list_has + +##### `array_has_all` + +Returns true if all elements of sub-array exist in array + +``` +array_has_all(array, sub-array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **sub-array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Aliases + +- list_has_all + +##### `array_has_any` + +Returns true if any elements exist in both arrays + +``` +array_has_any(array, sub-array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **sub-array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Aliases + +- list_has_any + +##### `array_dims` + +Returns an array of the array's dimensions. + +``` +array_dims(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_dims([[1, 2, 3], [4, 5, 6]]); ++---------------------------------+ +| array_dims(List([1,2,3,4,5,6])) | ++---------------------------------+ +| [2, 3] | ++---------------------------------+ +``` + +###### Aliases + +- list_dims + +##### `array_distance` + +Returns the Euclidean distance between two input arrays of equal length. + +``` +array_distance(array1, array2) +``` + +###### Arguments + +- **array1**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_distance([1, 2], [1, 4]); ++------------------------------------+ +| array_distance(List([1,2], [1,4])) | ++------------------------------------+ +| 2.0 | ++------------------------------------+ +``` + +###### Aliases + +- list_distance + +##### `array_distinct` + +Returns distinct values from the array after removing duplicates. + +``` +array_distinct(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_distinct([1, 3, 2, 3, 1, 2, 4]); ++---------------------------------+ +| array_distinct(List([1,2,3,4])) | ++---------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------+ +``` + +###### Aliases + +- list_distinct + +##### `array_element` + +Extracts the element with the index n from the array. + +``` +array_element(array, index) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **index**: Index to extract the element from the array. + +###### Example + +``` +> select array_element([1, 2, 3, 4], 3); ++-----------------------------------------+ +| array_element(List([1,2,3,4]),Int64(3)) | ++-----------------------------------------+ +| 3 | ++-----------------------------------------+ +``` + +###### Aliases + +- array_extract +- list_element +- list_extract + +##### `array_extract` + +_Alias of [array_element](#array-element)._ + +##### `array_fill` + +Returns an array filled with copies of the given value. + +DEPRECATED: use `array_repeat` instead! + +``` +array_fill(element, array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to copy to the array. + +##### `flatten` + +Converts an array of arrays to a flat array + +- Applies to any depth of nested arrays +- Does not change arrays that are already flat + +The flattened array contains all the elements from all source arrays. + +###### Arguments + +- **array**: Array expression + Can be a constant, column, or function, and any combination of array operators. + +``` +flatten(array) +``` + +##### `array_indexof` + +_Alias of [array_position](#array-position)._ + +##### `array_intersect` + +Returns an array of elements in the intersection of array1 and array2. + +``` +array_intersect(array1, array2) +``` + +###### Arguments + +- **array1**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [3, 4] | ++----------------------------------------------------+ +> select array_intersect([1, 2, 3, 4], [5, 6, 7, 8]); ++----------------------------------------------------+ +| array_intersect([1, 2, 3, 4], [5, 6, 7, 8]); | ++----------------------------------------------------+ +| [] | ++----------------------------------------------------+ +``` + +--- + +###### Aliases + +- list_intersect + +##### `array_join` + +_Alias of [array_to_string](#array-to-string)._ + +##### `array_length` + +Returns the length of the array dimension. + +``` +array_length(array, dimension) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **dimension**: Array dimension. + +###### Example + +``` +> select array_length([1, 2, 3, 4, 5]); ++---------------------------------+ +| array_length(List([1,2,3,4,5])) | ++---------------------------------+ +| 5 | ++---------------------------------+ +``` + +###### Aliases + +- list_length + +##### `array_ndims` + +Returns the number of dimensions of the array. + +``` +array_ndims(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_ndims([[1, 2, 3], [4, 5, 6]]); ++----------------------------------+ +| array_ndims(List([1,2,3,4,5,6])) | ++----------------------------------+ +| 2 | ++----------------------------------+ +``` + +###### Aliases + +- list_ndims + +##### `array_prepend` + +Prepends an element to the beginning of an array. + +``` +array_prepend(element, array) +``` + +###### Arguments + +- **element**: Element to prepend to the array. +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_prepend(1, [2, 3, 4]); ++---------------------------------------+ +| array_prepend(Int64(1),List([2,3,4])) | ++---------------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------------+ +``` + +###### Aliases + +- array_push_front +- list_prepend +- list_push_front + +##### `array_pop_front` + +Returns the array without the first element. + +``` +array_pop_front(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_pop_front([1, 2, 3]); ++-------------------------------+ +| array_pop_front(List([1,2,3])) | ++-------------------------------+ +| [2, 3] | ++-------------------------------+ +``` + +###### Aliases + +- list_pop_front + +##### `array_pop_back` + +Returns the array without the last element. + +``` +array_pop_back(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_pop_back([1, 2, 3]); ++-------------------------------+ +| array_pop_back(List([1,2,3])) | ++-------------------------------+ +| [1, 2] | ++-------------------------------+ +``` + +###### Aliases + +- list_pop_back + +##### `array_position` + +Returns the position of the first occurrence of the specified element in the array. + +``` +array_position(array, element) +array_position(array, element, index) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to search for position in the array. +- **index**: Index at which to start searching. + +###### Example + +``` +> select array_position([1, 2, 2, 3, 1, 4], 2); ++----------------------------------------------+ +| array_position(List([1,2,2,3,1,4]),Int64(2)) | ++----------------------------------------------+ +| 2 | ++----------------------------------------------+ +``` + +###### Aliases + +- array_indexof +- list_indexof +- list_position + +##### `array_positions` + +Searches for an element in the array, returns all occurrences. + +``` +array_positions(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to search for positions in the array. + +###### Example + +``` +> select array_positions([1, 2, 2, 3, 1, 4], 2); ++-----------------------------------------------+ +| array_positions(List([1,2,2,3,1,4]),Int64(2)) | ++-----------------------------------------------+ +| [2, 3] | ++-----------------------------------------------+ +``` + +###### Aliases + +- list_positions + +##### `array_push_back` + +_Alias of [array_append](#array-append)._ + +##### `array_push_front` + +_Alias of [array_prepend](#array-prepend)._ + +##### `array_repeat` + +Returns an array containing element `count` times. + +``` +array_repeat(element, count) +``` + +###### Arguments + +- **element**: Element expression. + Can be a constant, column, or function, and any combination of array operators. +- **count**: Value of how many times to repeat the element. + +###### Example + +``` +> select array_repeat(1, 3); ++---------------------------------+ +| array_repeat(Int64(1),Int64(3)) | ++---------------------------------+ +| [1, 1, 1] | ++---------------------------------+ +``` + +``` +> select array_repeat([1, 2], 2); ++------------------------------------+ +| array_repeat(List([1,2]),Int64(2)) | ++------------------------------------+ +| [[1, 2], [1, 2]] | ++------------------------------------+ +``` + +###### Aliases + +- list_repeat + +##### `array_remove` + +Removes the first element from the array equal to the given value. + +``` +array_remove(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. + +###### Example + +``` +> select array_remove([1, 2, 2, 3, 2, 1, 4], 2); ++----------------------------------------------+ +| array_remove(List([1,2,2,3,2,1,4]),Int64(2)) | ++----------------------------------------------+ +| [1, 2, 3, 2, 1, 4] | ++----------------------------------------------+ +``` + +###### Aliases + +- list_remove + +##### `array_remove_n` + +Removes the first `max` elements from the array equal to the given value. + +``` +array_remove_n(array, element, max) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. +- **max**: Number of first occurrences to remove. + +###### Example + +``` +> select array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2); ++---------------------------------------------------------+ +| array_remove_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(2)) | ++---------------------------------------------------------+ +| [1, 3, 2, 1, 4] | ++---------------------------------------------------------+ +``` + +###### Aliases + +- list_remove_n + +##### `array_remove_all` + +Removes all elements from the array equal to the given value. + +``` +array_remove_all(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. + +###### Example + +``` +> select array_remove_all([1, 2, 2, 3, 2, 1, 4], 2); ++--------------------------------------------------+ +| array_remove_all(List([1,2,2,3,2,1,4]),Int64(2)) | ++--------------------------------------------------+ +| [1, 3, 1, 4] | ++--------------------------------------------------+ +``` + +###### Aliases + +- list_remove_all + +##### `array_replace` + +Replaces the first occurrence of the specified element with another specified element. + +``` +array_replace(array, from, to) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. + +###### Example + +``` +> select array_replace([1, 2, 2, 3, 2, 1, 4], 2, 5); ++--------------------------------------------------------+ +| array_replace(List([1,2,2,3,2,1,4]),Int64(2),Int64(5)) | ++--------------------------------------------------------+ +| [1, 5, 2, 3, 2, 1, 4] | ++--------------------------------------------------------+ +``` + +###### Aliases + +- list_replace + +##### `array_replace_n` + +Replaces the first `max` occurrences of the specified element with another specified element. + +``` +array_replace_n(array, from, to, max) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. +- **max**: Number of first occurrences to replace. + +###### Example + +``` +> select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2); ++-------------------------------------------------------------------+ +| array_replace_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(5),Int64(2)) | ++-------------------------------------------------------------------+ +| [1, 5, 5, 3, 2, 1, 4] | ++-------------------------------------------------------------------+ +``` + +###### Aliases + +- list_replace_n + +##### `array_replace_all` + +Replaces all occurrences of the specified element with another specified element. + +``` +array_replace_all(array, from, to) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. + +###### Example + +``` +> select array_replace_all([1, 2, 2, 3, 2, 1, 4], 2, 5); ++------------------------------------------------------------+ +| array_replace_all(List([1,2,2,3,2,1,4]),Int64(2),Int64(5)) | ++------------------------------------------------------------+ +| [1, 5, 5, 3, 5, 1, 4] | ++------------------------------------------------------------+ +``` + +###### Aliases + +- list_replace_all + +##### `array_reverse` + +Returns the array with the order of the elements reversed. + +``` +array_reverse(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_reverse([1, 2, 3, 4]); ++------------------------------------------------------------+ +| array_reverse(List([1, 2, 3, 4])) | ++------------------------------------------------------------+ +| [4, 3, 2, 1] | ++------------------------------------------------------------+ +``` + +###### Aliases + +- list_reverse + +##### `array_slice` + +Returns a slice of the array based on 1-indexed start and end positions. + +``` +array_slice(array, begin, end) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **begin**: Index of the first element. + If negative, it counts backward from the end of the array. +- **end**: Index of the last element. + If negative, it counts backward from the end of the array. +- **stride**: Stride of the array slice. The default is 1. + +###### Example + +``` +> select array_slice([1, 2, 3, 4, 5, 6, 7, 8], 3, 6); ++--------------------------------------------------------+ +| array_slice(List([1,2,3,4,5,6,7,8]),Int64(3),Int64(6)) | ++--------------------------------------------------------+ +| [3, 4, 5, 6] | ++--------------------------------------------------------+ +``` + +###### Aliases + +- list_slice + +##### `array_to_string` + +Converts each element to its text representation. + +``` +array_to_string(array, delimiter) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **delimiter**: Array element separator. + +###### Example + +``` +> select array_to_string([[1, 2, 3, 4], [5, 6, 7, 8]], ','); ++----------------------------------------------------+ +| array_to_string(List([1,2,3,4,5,6,7,8]),Utf8(",")) | ++----------------------------------------------------+ +| 1,2,3,4,5,6,7,8 | ++----------------------------------------------------+ +``` + +###### Aliases + +- array_join +- list_join +- list_to_string + +##### `array_union` + +Returns an array of elements that are present in both arrays (all elements from both arrays) with out duplicates. + +``` +array_union(array1, array2) +``` + +###### Arguments + +- **array1**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_union([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_union([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [1, 2, 3, 4, 5, 6] | ++----------------------------------------------------+ +> select array_union([1, 2, 3, 4], [5, 6, 7, 8]); ++----------------------------------------------------+ +| array_union([1, 2, 3, 4], [5, 6, 7, 8]); | ++----------------------------------------------------+ +| [1, 2, 3, 4, 5, 6, 7, 8] | ++----------------------------------------------------+ +``` + +--- + +###### Aliases + +- list_union + +##### `array_except` + +Returns an array of the elements that appear in the first array but not in the second. + +``` +array_except(array1, array2) +``` + +###### Arguments + +- **array1**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_except([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_except([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [1, 2] | ++----------------------------------------------------+ +> select array_except([1, 2, 3, 4], [3, 4, 5, 6]); ++----------------------------------------------------+ +| array_except([1, 2, 3, 4], [3, 4, 5, 6]); | ++----------------------------------------------------+ +| [1, 2] | ++----------------------------------------------------+ +``` + +--- + +###### Aliases + +- list_except + +##### `cardinality` + +Returns the total number of elements in the array. + +``` +cardinality(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]); ++--------------------------------------+ +| cardinality(List([1,2,3,4,5,6,7,8])) | ++--------------------------------------+ +| 8 | ++--------------------------------------+ +``` + +##### `empty` + +Returns 1 for an empty array or 0 for a non-empty array. + +``` +empty(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select empty([1]); ++------------------+ +| empty(List([1])) | ++------------------+ +| 0 | ++------------------+ +``` + +###### Aliases + +- array_empty, +- list_empty + +##### `generate_series` + +Similar to the range function, but it includes the upper bound. + +``` +generate_series(start, stop, step) +``` + +###### Arguments + +- **start**: start of the series. Ints, timestamps, dates or string types that can be coerced to Date32 are supported. +- **end**: end of the series (included). Type must be the same as start. +- **step**: increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges. + +###### Example + +``` +> select generate_series(1,3); ++------------------------------------+ +| generate_series(Int64(1),Int64(3)) | ++------------------------------------+ +| [1, 2, 3] | ++------------------------------------+ +``` + +##### `list_any_value` + +_Alias of [array_any_value](#array-any-value)._ + +##### `list_append` + +_Alias of [array_append](#array-append)._ + +##### `list_cat` + +_Alias of [array_concat](#array-concat)._ + +##### `list_concat` + +_Alias of [array_concat](#array-concat)._ + +##### `list_dims` + +_Alias of [array_dims](#array-dims)._ + +##### `list_distance` + +_Alias of [array_distance](#array-distance)._ + +##### `list_distinct` + +_Alias of [array_distinct](#array-distinct)._ + +##### `list_element` + +_Alias of [array_element](#array-element)._ + +##### `list_empty` + +_Alias of [empty](#empty)._ + +##### `list_except` + +_Alias of [array_element](#array-except)._ + +##### `list_extract` + +_Alias of [array_element](#array-element)._ + +##### `list_has` + +_Alias of [array_has](#array-has)._ + +##### `list_has_all` + +_Alias of [array_has_all](#array-has-all)._ + +##### `list_has_any` + +_Alias of [array_has_any](#array-has-any)._ + +##### `list_indexof` + +_Alias of [array_position](#array-position)._ + +##### `list_intersect` + +_Alias of [array_position](#array-intersect)._ + +##### `list_join` + +_Alias of [array_to_string](#array-to-string)._ + +##### `list_length` + +_Alias of [array_length](#array-length)._ + +##### `list_ndims` + +_Alias of [array_ndims](#array-ndims)._ + +##### `list_prepend` + +_Alias of [array_prepend](#array-prepend)._ + +##### `list_pop_back` + +_Alias of [array_pop_back](#array-pop-back)._ + +##### `list_pop_front` + +_Alias of [array_pop_front](#array-pop-front)._ + +##### `list_position` + +_Alias of [array_position](#array-position)._ + +##### `list_positions` + +_Alias of [array_positions](#array-positions)._ + +##### `list_push_back` + +_Alias of [array_append](#array-append)._ + +##### `list_push_front` + +_Alias of [array_prepend](#array-prepend)._ + +##### `list_repeat` + +_Alias of [array_repeat](#array-repeat)._ + +##### `list_resize` + +_Alias of [array_resize](#array-resize)._ + +##### `list_remove` + +_Alias of [array_remove](#array-remove)._ + +##### `list_remove_n` + +_Alias of [array_remove_n](#array-remove-n)._ + +##### `list_remove_all` + +_Alias of [array_remove_all](#array-remove-all)._ + +##### `list_replace` + +_Alias of [array_replace](#array-replace)._ + +##### `list_replace_n` + +_Alias of [array_replace_n](#array-replace-n)._ + +##### `list_replace_all` + +_Alias of [array_replace_all](#array-replace-all)._ + +##### `list_reverse` + +_Alias of [array_reverse](#array-reverse)._ + +##### `list_slice` + +_Alias of [array_slice](#array-slice)._ + +##### `list_sort` + +_Alias of [array_sort](#array-sort)._ + +##### `list_to_string` + +_Alias of [array_to_string](#array-to-string)._ + +##### `list_union` + +_Alias of [array_union](#array-union)._ + +##### `make_array` + +Returns an Arrow array using the specified input expressions. + +``` +make_array(expression1[, ..., expression_n]) +``` + +##### `array_empty` + +_Alias of [empty](#empty)._ + +###### Arguments + +- **expression_n**: Expression to include in the output array. + Can be a constant, column, or function, and any combination of arithmetic or + string operators. + +###### Example + +``` +> select make_array(1, 2, 3, 4, 5); ++----------------------------------------------------------+ +| make_array(Int64(1),Int64(2),Int64(3),Int64(4),Int64(5)) | ++----------------------------------------------------------+ +| [1, 2, 3, 4, 5] | ++----------------------------------------------------------+ +``` + +###### Aliases + +- make_list + +##### `make_list` + +_Alias of [make_array](#make-array)._ + +##### `string_to_array` + +Splits a string in to an array of substrings based on a delimiter. Any substrings matching the optional `null_str` argument are replaced with NULL. +`SELECT string_to_array('abc##def', '##')` or `SELECT string_to_array('abc def', ' ', 'def')` + +``` +starts_with(str, delimiter[, null_str]) +``` + +###### Arguments + +- **str**: String expression to split. +- **delimiter**: Delimiter string to split on. +- **null_str**: Substring values to be replaced with `NULL` + +###### Aliases + +- string_to_list + +##### `string_to_list` + +_Alias of [string_to_array](#string-to-array)._ + +##### `trim_array` + +Removes the last n elements from the array. + +DEPRECATED: use `array_slice` instead! + +``` +trim_array(array, n) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **n**: Element to trim the array. + +##### `unnest` + +Transforms an array into rows. + +###### Arguments + +- **array**: Array expression to unnest. + Can be a constant, column, or function, and any combination of array operators. + +###### Examples + +``` +> select unnest(make_array(1, 2, 3, 4, 5)); ++------------------------------------------------------------------+ +| unnest(make_array(Int64(1),Int64(2),Int64(3),Int64(4),Int64(5))) | ++------------------------------------------------------------------+ +| 1 | +| 2 | +| 3 | +| 4 | +| 5 | ++------------------------------------------------------------------+ +``` + +``` +> select unnest(range(0, 10)); ++-----------------------------------+ +| unnest(range(Int64(0),Int64(10))) | ++-----------------------------------+ +| 0 | +| 1 | +| 2 | +| 3 | +| 4 | +| 5 | +| 6 | +| 7 | +| 8 | +| 9 | ++-----------------------------------+ +``` + +##### `range` + +Returns an Arrow array between start and stop with step. `SELECT range(2, 10, 3) -> [2, 5, 8]` or `SELECT range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH);` + +The range start..end contains all values with `start <= x < end`. It is empty if `start >= end`. + +Step can not be 0 (then the range will be nonsense.). + +Note that when the required range is a number, it accepts (stop), (start, stop), and (start, stop, step) as parameters, but when the required range is a date or timestamp, it must be 3 non-NULL parameters. +For example, + +``` +SELECT range(3); +SELECT range(1,5); +SELECT range(1,5,1); +``` + +are allowed in number ranges + +but in date and timestamp ranges, only + +``` +SELECT range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH); +SELECT range(TIMESTAMP '1992-09-01', TIMESTAMP '1993-03-01', INTERVAL '1' MONTH); +``` + +is allowed, and + +``` +SELECT range(DATE '1992-09-01', DATE '1993-03-01', NULL); +SELECT range(NULL, DATE '1993-03-01', INTERVAL '1' MONTH); +SELECT range(DATE '1992-09-01', NULL, INTERVAL '1' MONTH); +``` + +are not allowed + +###### Arguments + +- **start**: start of the range. Ints, timestamps, dates or string types that can be coerced to Date32 are supported. +- **end**: end of the range (not included). Type must be the same as start. +- **step**: increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges. + +###### Aliases + +- generate_series + +### Struct Functions + +- [unnest](#unnest-struct) + +For more struct functions see the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) + +##### `unnest (struct)` + +Unwraps struct fields into columns. + +###### Arguments + +- **struct**: Object expression to unnest. + Can be a constant, column, or function, and any combination of object operators. + +###### Examples + +``` +> select * from foo; ++---------------------+ +| column1 | ++---------------------+ +| {a: 5, b: a string} | ++---------------------+ + +> select unnest(column1) from foo; ++-----------------------+-----------------------+ +| unnest(foo.column1).a | unnest(foo.column1).b | ++-----------------------+-----------------------+ +| 5 | a string | ++-----------------------+-----------------------+ +``` + +### Map Functions + +- [map](#map) +- [make_map](#make-map) +- [map_extract](#map-extract) +- [map_keys](#map-keys) +- [map_values](#map-values) + +##### `map` + +Returns an Arrow map with the specified key-value pairs. + +``` +map(key, value) +map(key: value) +``` + +###### Arguments + +- **key**: Expression to be used for key. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. +- **value**: Expression to be used for value. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. + +###### Example + +``` +SELECT MAP(['POST', 'HEAD', 'PATCH'], [41, 33, null]); +---- +{POST: 41, HEAD: 33, PATCH: } + +SELECT MAP([[1,2], [3,4]], ['a', 'b']); +---- +{[1, 2]: a, [3, 4]: b} + +SELECT MAP { 'a': 1, 'b': 2 }; +---- +{a: 1, b: 2} +``` + +##### `make_map` + +Returns an Arrow map with the specified key-value pairs. + +``` +make_map(key_1, value_1, ..., key_n, value_n) +``` + +###### Arguments + +- **key_n**: Expression to be used for key. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. +- **value_n**: Expression to be used for value. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. + +###### Example + +``` +SELECT MAKE_MAP('POST', 41, 'HEAD', 33, 'PATCH', null); +---- +{POST: 41, HEAD: 33, PATCH: } +``` + +##### `map_extract` + +Return a list containing the value for a given key or an empty list if the key is not contained in the map. + +``` +map_extract(map, key) +``` + +###### Arguments + +- `map`: Map expression. + Can be a constant, column, or function, and any combination of map operators. +- `key`: Key to extract from the map. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. + +###### Example + +``` +SELECT map_extract(MAP {'a': 1, 'b': NULL, 'c': 3}, 'a'); +---- +[1] +``` + +###### Aliases + +- element_at + +##### `map_keys` + +Return a list of all keys in the map. + +``` +map_keys(map) +``` + +###### Arguments + +- `map`: Map expression. + Can be a constant, column, or function, and any combination of map operators. + +###### Example + +``` +SELECT map_keys(MAP {'a': 1, 'b': NULL, 'c': 3}); +---- +[a, b, c] + +select map_keys(map([100, 5], [42,43])); +---- +[100, 5] +``` + +##### `map_values` + +Return a list of all values in the map. + +``` +map_values(map) +``` + +###### Arguments + +- `map`: Map expression. + Can be a constant, column, or function, and any combination of map operators. + +###### Example + +``` +SELECT map_values(MAP {'a': 1, 'b': NULL, 'c': 3}); +---- +[1, , 3] + +select map_values(map([100, 5], [42,43])); +---- +[42, 43] +``` + +### Other Functions + +See the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) + + + + +## Scalar Functions (NEW) + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. +Please see the [Scalar Functions (old)](#aggregate-functions) page for +the rest of the documentation. + +### Math Functions + +- [log](#log) + +##### `log` + +Returns the base-x logarithm of a number. Can either provide a specified base, or if omitted then takes the base-10 of a number. + +``` +log(base, numeric_expression) +log(numeric_expression) +``` + +###### Arguments + +- **base**: Base numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### Conditional Functions + +- [coalesce](#coalesce) +- [ifnull](#ifnull) +- [nullif](#nullif) +- [nvl](#nvl) +- [nvl2](#nvl2) + +##### `coalesce` + +Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. This function is often used to substitute a default value for _null_ values. + +``` +coalesce(expression1[, ..., expression_n]) +``` + +###### Arguments + +- **expression1, expression_n**: Expression to use if previous expressions are _null_. Can be a constant, column, or function, and any combination of arithmetic operators. Pass as many expression arguments as necessary. + +###### Example + +```sql +> select coalesce(null, null, 'datafusion'); ++----------------------------------------+ +| coalesce(NULL,NULL,Utf8("datafusion")) | ++----------------------------------------+ +| datafusion | ++----------------------------------------+ +``` + +##### `ifnull` + +_Alias of [nvl](#nvl)._ + +##### `nullif` + +Returns _null_ if _expression1_ equals _expression2_; otherwise it returns _expression1_. +This can be used to perform the inverse operation of [`coalesce`](#coalesce). + +``` +nullif(expression1, expression2) +``` + +###### Arguments + +- **expression1**: Expression to compare and return if equal to expression2. Can be a constant, column, or function, and any combination of operators. +- **expression2**: Expression to compare to expression1. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select nullif('datafusion', 'data'); ++-----------------------------------------+ +| nullif(Utf8("datafusion"),Utf8("data")) | ++-----------------------------------------+ +| datafusion | ++-----------------------------------------+ +> select nullif('datafusion', 'datafusion'); ++-----------------------------------------------+ +| nullif(Utf8("datafusion"),Utf8("datafusion")) | ++-----------------------------------------------+ +| | ++-----------------------------------------------+ +``` + +##### `nvl` + +Returns _expression2_ if _expression1_ is NULL otherwise it returns _expression1_. + +``` +nvl(expression1, expression2) +``` + +###### Arguments + +- **expression1**: Expression to return if not null. Can be a constant, column, or function, and any combination of operators. +- **expression2**: Expression to return if expr1 is null. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select nvl(null, 'a'); ++---------------------+ +| nvl(NULL,Utf8("a")) | ++---------------------+ +| a | ++---------------------+\ +> select nvl('b', 'a'); ++--------------------------+ +| nvl(Utf8("b"),Utf8("a")) | ++--------------------------+ +| b | ++--------------------------+ +``` + +###### Aliases + +- ifnull + +##### `nvl2` + +Returns _expression2_ if _expression1_ is not NULL; otherwise it returns _expression3_. + +``` +nvl2(expression1, expression2, expression3) +``` + +###### Arguments + +- **expression1**: Expression to test for null. Can be a constant, column, or function, and any combination of operators. +- **expression2**: Expression to return if expr1 is not null. Can be a constant, column, or function, and any combination of operators. +- **expression3**: Expression to return if expr1 is null. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select nvl2(null, 'a', 'b'); ++--------------------------------+ +| nvl2(NULL,Utf8("a"),Utf8("b")) | ++--------------------------------+ +| b | ++--------------------------------+ +> select nvl2('data', 'a', 'b'); ++----------------------------------------+ +| nvl2(Utf8("data"),Utf8("a"),Utf8("b")) | ++----------------------------------------+ +| a | ++----------------------------------------+ +``` + +### String Functions + +- [ascii](#ascii) +- [bit_length](#bit-length) +- [btrim](#btrim) +- [char_length](#char-length) +- [character_length](#character-length) +- [chr](#chr) +- [concat](#concat) +- [concat_ws](#concat-ws) +- [contains](#contains) +- [ends_with](#ends-with) +- [find_in_set](#find-in-set) +- [initcap](#initcap) +- [instr](#instr) +- [left](#left) +- [length](#length) +- [levenshtein](#levenshtein) +- [lower](#lower) +- [lpad](#lpad) +- [ltrim](#ltrim) +- [octet_length](#octet-length) +- [position](#position) +- [repeat](#repeat) +- [replace](#replace) +- [reverse](#reverse) +- [right](#right) +- [rpad](#rpad) +- [rtrim](#rtrim) +- [split_part](#split-part) +- [starts_with](#starts-with) +- [strpos](#strpos) +- [substr](#substr) +- [substr_index](#substr-index) +- [substring](#substring) +- [substring_index](#substring-index) +- [to_hex](#to-hex) +- [translate](#translate) +- [trim](#trim) +- [upper](#upper) +- [uuid](#uuid) + +##### `ascii` + +Returns the Unicode character code of the first character in a string. + +``` +ascii(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select ascii('abc'); ++--------------------+ +| ascii(Utf8("abc")) | ++--------------------+ +| 97 | ++--------------------+ +> select ascii('🚀'); ++-------------------+ +| ascii(Utf8("🚀")) | ++-------------------+ +| 128640 | ++-------------------+ +``` + +**Related functions**: + +- [chr](#chr) + +##### `bit_length` + +Returns the bit length of a string. + +``` +bit_length(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select bit_length('datafusion'); ++--------------------------------+ +| bit_length(Utf8("datafusion")) | ++--------------------------------+ +| 80 | ++--------------------------------+ +``` + +**Related functions**: + +- [length](#length) +- [octet_length](#octet-length) + +##### `btrim` + +Trims the specified trim string from the start and end of a string. If no trim string is provided, all whitespace is removed from the start and end of the input string. + +``` +btrim(str[, trim_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **trim_str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. _Default is whitespace characters._ + +###### Example + +```sql +> select btrim('__datafusion____', '_'); ++-------------------------------------------+ +| btrim(Utf8("__datafusion____"),Utf8("_")) | ++-------------------------------------------+ +| datafusion | ++-------------------------------------------+ +``` + +###### Aliases + +- trim + +**Related functions**: + +- [ltrim](#ltrim) +- [rtrim](#rtrim) + +##### `char_length` + +_Alias of [character_length](#character-length)._ + +##### `character_length` + +Returns the number of characters in a string. + +``` +character_length(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select character_length('Ångström'); ++------------------------------------+ +| character_length(Utf8("Ångström")) | ++------------------------------------+ +| 8 | ++------------------------------------+ +``` + +###### Aliases + +- length +- char_length + +**Related functions**: + +- [bit_length](#bit-length) +- [octet_length](#octet-length) + +##### `chr` + +Returns the character with the specified ASCII or Unicode code value. + +``` +chr(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select chr(128640); ++--------------------+ +| chr(Int64(128640)) | ++--------------------+ +| 🚀 | ++--------------------+ +``` + +**Related functions**: + +- [ascii](#ascii) + +##### `concat` + +Concatenates multiple strings together. + +``` +concat(str[, ..., str_n]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **str_n**: Subsequent string expressions to concatenate. + +###### Example + +```sql +> select concat('data', 'f', 'us', 'ion'); ++-------------------------------------------------------+ +| concat(Utf8("data"),Utf8("f"),Utf8("us"),Utf8("ion")) | ++-------------------------------------------------------+ +| datafusion | ++-------------------------------------------------------+ +``` + +**Related functions**: + +- [concat_ws](#concat-ws) + +##### `concat_ws` + +Concatenates multiple strings together with a specified separator. + +``` +concat_ws(separator, str[, ..., str_n]) +``` + +###### Arguments + +- **separator**: Separator to insert between concatenated strings. +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **str_n**: Subsequent string expressions to concatenate. expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select concat_ws('_', 'data', 'fusion'); ++--------------------------------------------------+ +| concat_ws(Utf8("_"),Utf8("data"),Utf8("fusion")) | ++--------------------------------------------------+ +| data_fusion | ++--------------------------------------------------+ +``` + +**Related functions**: + +- [concat](#concat) + +##### `contains` + +Return true if search_str is found within string (case-sensitive). + +``` +contains(str, search_str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **search_str**: The string to search for in str. + +###### Example + +```sql +> select contains('the quick brown fox', 'row'); ++---------------------------------------------------+ +| contains(Utf8("the quick brown fox"),Utf8("row")) | ++---------------------------------------------------+ +| true | ++---------------------------------------------------+ +``` + +##### `ends_with` + +Tests if a string ends with a substring. + +``` +ends_with(str, substr) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring to test for. + +###### Example + +```sql +> select ends_with('datafusion', 'soin'); ++--------------------------------------------+ +| ends_with(Utf8("datafusion"),Utf8("soin")) | ++--------------------------------------------+ +| false | ++--------------------------------------------+ +> select ends_with('datafusion', 'sion'); ++--------------------------------------------+ +| ends_with(Utf8("datafusion"),Utf8("sion")) | ++--------------------------------------------+ +| true | ++--------------------------------------------+ +``` + +##### `find_in_set` + +Returns a value in the range of 1 to N if the string str is in the string list strlist consisting of N substrings. + +``` +find_in_set(str, strlist) +``` + +###### Arguments + +- **str**: String expression to find in strlist. +- **strlist**: A string list is a string composed of substrings separated by , characters. + +###### Example + +```sql +> select find_in_set('b', 'a,b,c,d'); ++----------------------------------------+ +| find_in_set(Utf8("b"),Utf8("a,b,c,d")) | ++----------------------------------------+ +| 2 | ++----------------------------------------+ +``` + +##### `initcap` + +Capitalizes the first character in each word in the input string. Words are delimited by non-alphanumeric characters. + +``` +initcap(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select initcap('apache datafusion'); ++------------------------------------+ +| initcap(Utf8("apache datafusion")) | ++------------------------------------+ +| Apache Datafusion | ++------------------------------------+ +``` + +**Related functions**: + +- [lower](#lower) +- [upper](#upper) + +##### `instr` + +_Alias of [strpos](#strpos)._ + +##### `left` + +Returns a specified number of characters from the left side of a string. + +``` +left(str, n) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: Number of characters to return. + +###### Example + +```sql +> select left('datafusion', 4); ++-----------------------------------+ +| left(Utf8("datafusion"),Int64(4)) | ++-----------------------------------+ +| data | ++-----------------------------------+ +``` + +**Related functions**: + +- [right](#right) + +##### `length` + +_Alias of [character_length](#character-length)._ + +##### `levenshtein` + +Returns the [`Levenshtein distance`](https://en.wikipedia.org/wiki/Levenshtein_distance) between the two given strings. + +``` +levenshtein(str1, str2) +``` + +###### Arguments + +- **str1**: String expression to compute Levenshtein distance with str2. +- **str2**: String expression to compute Levenshtein distance with str1. + +###### Example + +```sql +> select levenshtein('kitten', 'sitting'); ++---------------------------------------------+ +| levenshtein(Utf8("kitten"),Utf8("sitting")) | ++---------------------------------------------+ +| 3 | ++---------------------------------------------+ +``` + +##### `lower` + +Converts a string to lower-case. + +``` +lower(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select lower('Ångström'); ++-------------------------+ +| lower(Utf8("Ångström")) | ++-------------------------+ +| ångström | ++-------------------------+ +``` + +**Related functions**: + +- [initcap](#initcap) +- [upper](#upper) + +##### `lpad` + +Pads the left side of a string with another string to a specified string length. + +``` +lpad(str, n[, padding_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: String length to pad to. +- **padding_str**: Optional string expression to pad with. Can be a constant, column, or function, and any combination of string operators. _Default is a space._ + +###### Example + +```sql +> select lpad('Dolly', 10, 'hello'); ++---------------------------------------------+ +| lpad(Utf8("Dolly"),Int64(10),Utf8("hello")) | ++---------------------------------------------+ +| helloDolly | ++---------------------------------------------+ +``` + +**Related functions**: + +- [rpad](#rpad) + +##### `ltrim` + +Trims the specified trim string from the beginning of a string. If no trim string is provided, all whitespace is removed from the start of the input string. + +``` +ltrim(str[, trim_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **trim_str**: String expression to trim from the beginning of the input string. Can be a constant, column, or function, and any combination of arithmetic operators. _Default is whitespace characters._ + +###### Example + +```sql +> select ltrim(' datafusion '); ++-------------------------------+ +| ltrim(Utf8(" datafusion ")) | ++-------------------------------+ +| datafusion | ++-------------------------------+ +> select ltrim('___datafusion___', '_'); ++-------------------------------------------+ +| ltrim(Utf8("___datafusion___"),Utf8("_")) | ++-------------------------------------------+ +| datafusion___ | ++-------------------------------------------+ +``` + +**Related functions**: + +- [btrim](#btrim) +- [rtrim](#rtrim) + +##### `octet_length` + +Returns the length of a string in bytes. + +``` +octet_length(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select octet_length('Ångström'); ++--------------------------------+ +| octet_length(Utf8("Ångström")) | ++--------------------------------+ +| 10 | ++--------------------------------+ +``` + +**Related functions**: + +- [bit_length](#bit-length) +- [length](#length) + +##### `position` + +_Alias of [strpos](#strpos)._ + +##### `repeat` + +Returns a string with an input string repeated a specified number. + +``` +repeat(str, n) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: Number of times to repeat the input string. + +###### Example + +```sql +> select repeat('data', 3); ++-------------------------------+ +| repeat(Utf8("data"),Int64(3)) | ++-------------------------------+ +| datadatadata | ++-------------------------------+ +``` + +##### `replace` + +Replaces all occurrences of a specified substring in a string with a new substring. + +``` +replace(str, substr, replacement) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring expression to replace in the input string. Substring expression expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **replacement**: Replacement substring expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select replace('ABabbaBA', 'ab', 'cd'); ++-------------------------------------------------+ +| replace(Utf8("ABabbaBA"),Utf8("ab"),Utf8("cd")) | ++-------------------------------------------------+ +| ABcdbaBA | ++-------------------------------------------------+ +``` + +##### `reverse` + +Reverses the character order of a string. + +``` +reverse(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select reverse('datafusion'); ++-----------------------------+ +| reverse(Utf8("datafusion")) | ++-----------------------------+ +| noisufatad | ++-----------------------------+ +``` + +##### `right` + +Returns a specified number of characters from the right side of a string. + +``` +right(str, n) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: Number of characters to return + +###### Example + +```sql +> select right('datafusion', 6); ++------------------------------------+ +| right(Utf8("datafusion"),Int64(6)) | ++------------------------------------+ +| fusion | ++------------------------------------+ +``` + +**Related functions**: + +- [left](#left) + +##### `rpad` + +Pads the right side of a string with another string to a specified string length. + +``` +rpad(str, n[, padding_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: String length to pad to. +- **padding_str**: String expression to pad with. Can be a constant, column, or function, and any combination of string operators. _Default is a space._ + +###### Example + +```sql +> select rpad('datafusion', 20, '_-'); ++-----------------------------------------------+ +| rpad(Utf8("datafusion"),Int64(20),Utf8("_-")) | ++-----------------------------------------------+ +| datafusion_-_-_-_-_- | ++-----------------------------------------------+ +``` + +**Related functions**: + +- [lpad](#lpad) + +##### `rtrim` + +Trims the specified trim string from the end of a string. If no trim string is provided, all whitespace is removed from the end of the input string. + +``` +rtrim(str[, trim_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **trim_str**: String expression to trim from the end of the input string. Can be a constant, column, or function, and any combination of arithmetic operators. _Default is whitespace characters._ + +###### Example + +```sql +> select rtrim(' datafusion '); ++-------------------------------+ +| rtrim(Utf8(" datafusion ")) | ++-------------------------------+ +| datafusion | ++-------------------------------+ +> select rtrim('___datafusion___', '_'); ++-------------------------------------------+ +| rtrim(Utf8("___datafusion___"),Utf8("_")) | ++-------------------------------------------+ +| ___datafusion | ++-------------------------------------------+ +``` + +**Related functions**: + +- [btrim](#btrim) +- [ltrim](#ltrim) + +##### `split_part` + +Splits a string based on a specified delimiter and returns the substring in the specified position. + +``` +split_part(str, delimiter, pos) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **delimiter**: String or character to split on. +- **pos**: Position of the part to return. + +###### Example + +```sql +> select split_part('1.2.3.4.5', '.', 3); ++--------------------------------------------------+ +| split_part(Utf8("1.2.3.4.5"),Utf8("."),Int64(3)) | ++--------------------------------------------------+ +| 3 | ++--------------------------------------------------+ +``` + +##### `starts_with` + +Tests if a string starts with a substring. + +``` +starts_with(str, substr) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring to test for. + +###### Example + +```sql +> select starts_with('datafusion','data'); ++----------------------------------------------+ +| starts_with(Utf8("datafusion"),Utf8("data")) | ++----------------------------------------------+ +| true | ++----------------------------------------------+ +``` + +##### `strpos` + +Returns the starting position of a specified substring in a string. Positions begin at 1. If the substring does not exist in the string, the function returns 0. + +``` +strpos(str, substr) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring expression to search for. + +###### Example + +```sql +> select strpos('datafusion', 'fus'); ++----------------------------------------+ +| strpos(Utf8("datafusion"),Utf8("fus")) | ++----------------------------------------+ +| 5 | ++----------------------------------------+ +``` + +###### Aliases + +- instr +- position + +##### `substr` + +Extracts a substring of a specified number of characters from a specific starting position in a string. + +``` +substr(str, start_pos[, length]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **start_pos**: Character position to start the substring at. The first character in the string has a position of 1. +- **length**: Number of characters to extract. If not specified, returns the rest of the string after the start position. + +###### Example + +```sql +> select substr('datafusion', 5, 3); ++----------------------------------------------+ +| substr(Utf8("datafusion"),Int64(5),Int64(3)) | ++----------------------------------------------+ +| fus | ++----------------------------------------------+ +``` + +###### Aliases + +- substring + +##### `substr_index` + +Returns the substring from str before count occurrences of the delimiter delim. +If count is positive, everything to the left of the final delimiter (counting from the left) is returned. +If count is negative, everything to the right of the final delimiter (counting from the right) is returned. + +``` +substr_index(str, delim, count) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **delim**: The string to find in str to split str. +- **count**: The number of times to search for the delimiter. Can be either a positive or negative number. + +###### Example + +```sql +> select substr_index('www.apache.org', '.', 1); ++---------------------------------------------------------+ +| substr_index(Utf8("www.apache.org"),Utf8("."),Int64(1)) | ++---------------------------------------------------------+ +| www | ++---------------------------------------------------------+ +> select substr_index('www.apache.org', '.', -1); ++----------------------------------------------------------+ +| substr_index(Utf8("www.apache.org"),Utf8("."),Int64(-1)) | ++----------------------------------------------------------+ +| org | ++----------------------------------------------------------+ +``` + +###### Aliases + +- substring_index + +##### `substring` + +_Alias of [substr](#substr)._ + +##### `substring_index` + +_Alias of [substr_index](#substr-index)._ + +##### `to_hex` + +Converts an integer to a hexadecimal string. + +``` +to_hex(int) +``` + +###### Arguments + +- **int**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select to_hex(12345689); ++-------------------------+ +| to_hex(Int64(12345689)) | ++-------------------------+ +| bc6159 | ++-------------------------+ +``` + +##### `translate` + +Translates characters in a string to specified translation characters. + +``` +translate(str, chars, translation) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **chars**: Characters to translate. +- **translation**: Translation characters. Translation characters replace only characters at the same position in the **chars** string. + +###### Example + +```sql +> select translate('twice', 'wic', 'her'); ++--------------------------------------------------+ +| translate(Utf8("twice"),Utf8("wic"),Utf8("her")) | ++--------------------------------------------------+ +| there | ++--------------------------------------------------+ +``` + +##### `trim` + +_Alias of [btrim](#btrim)._ + +##### `upper` + +Converts a string to upper-case. + +``` +upper(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select upper('dataFusion'); ++---------------------------+ +| upper(Utf8("dataFusion")) | ++---------------------------+ +| DATAFUSION | ++---------------------------+ +``` + +**Related functions**: + +- [initcap](#initcap) +- [lower](#lower) + +##### `uuid` + +Returns [`UUID v4`]() string value which is unique per row. + +``` +uuid() +``` + +###### Example + +```sql +> select uuid(); ++--------------------------------------+ +| uuid() | ++--------------------------------------+ +| 6ec17ef8-1934-41cc-8d59-d0c8f9eea1f0 | ++--------------------------------------+ +``` + +### Binary String Functions + +- [decode](#decode) +- [encode](#encode) + +##### `decode` + +Decode binary data from textual representation in string. + +``` +decode(expression, format) +``` + +###### Arguments + +- **expression**: Expression containing encoded string data +- **format**: Same arguments as [encode](#encode) + +**Related functions**: + +- [encode](#encode) + +##### `encode` + +Encode binary data into a textual representation. + +``` +encode(expression, format) +``` + +###### Arguments + +- **expression**: Expression containing string or binary data +- **format**: Supported formats are: `base64`, `hex` + +**Related functions**: + +- [decode](#decode) + +### Regular Expression Functions + +Apache DataFusion uses a [PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions) +regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax) +(minus support for several features including look-around and backreferences). +The following regular expression functions are supported: + +- [regexp_like](#regexp-like) +- [regexp_match](#regexp-match) +- [regexp_replace](#regexp-replace) + +##### `regexp_like` + +Returns true if a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has at least one match in a string, false otherwise. + +``` +regexp_like(str, regexp[, flags]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **regexp**: Regular expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: + - **i**: case-insensitive: letters match both upper and lower case + - **m**: multi-line mode: ^ and $ match begin/end of line + - **s**: allow . to match \n + - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used + - **U**: swap the meaning of x* and x*? + +###### Example + +```sql +select regexp_like('Köln', '[a-zA-Z]ö[a-zA-Z]{2}'); ++--------------------------------------------------------+ +| regexp_like(Utf8("Köln"),Utf8("[a-zA-Z]ö[a-zA-Z]{2}")) | ++--------------------------------------------------------+ +| true | ++--------------------------------------------------------+ +SELECT regexp_like('aBc', '(b|d)', 'i'); ++--------------------------------------------------+ +| regexp_like(Utf8("aBc"),Utf8("(b|d)"),Utf8("i")) | ++--------------------------------------------------+ +| true | ++--------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) + +##### `regexp_match` + +Returns a list of [regular expression](https://docs.rs/regex/latest/regex/#syntax) matches in a string. + +``` +regexp_match(str, regexp[, flags]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **regexp**: Regular expression to match against. + Can be a constant, column, or function. +- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: + - **i**: case-insensitive: letters match both upper and lower case + - **m**: multi-line mode: ^ and $ match begin/end of line + - **s**: allow . to match \n + - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used + - **U**: swap the meaning of x* and x*? + +###### Example + +```sql + > select regexp_match('Köln', '[a-zA-Z]ö[a-zA-Z]{2}'); + +---------------------------------------------------------+ + | regexp_match(Utf8("Köln"),Utf8("[a-zA-Z]ö[a-zA-Z]{2}")) | + +---------------------------------------------------------+ + | [Köln] | + +---------------------------------------------------------+ + SELECT regexp_match('aBc', '(b|d)', 'i'); + +---------------------------------------------------+ + | regexp_match(Utf8("aBc"),Utf8("(b|d)"),Utf8("i")) | + +---------------------------------------------------+ + | [B] | + +---------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) + +##### `regexp_replace` + +Replaces substrings in a string that match a [regular expression](https://docs.rs/regex/latest/regex/#syntax). + +``` +regexp_replace(str, regexp, replacement[, flags]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **regexp**: Regular expression to match against. + Can be a constant, column, or function. +- **replacement**: Replacement string expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: +- **g**: (global) Search globally and don't return after the first match +- **i**: case-insensitive: letters match both upper and lower case +- **m**: multi-line mode: ^ and $ match begin/end of line +- **s**: allow . to match \n +- **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used +- **U**: swap the meaning of x* and x*? + +###### Example + +```sql +> select regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g'); ++------------------------------------------------------------------------+ +| regexp_replace(Utf8("foobarbaz"),Utf8("b(..)"),Utf8("X\1Y"),Utf8("g")) | ++------------------------------------------------------------------------+ +| fooXarYXazY | ++------------------------------------------------------------------------+ +SELECT regexp_replace('aBc', '(b|d)', 'Ab\\1a', 'i'); ++-------------------------------------------------------------------+ +| regexp_replace(Utf8("aBc"),Utf8("(b|d)"),Utf8("Ab\1a"),Utf8("i")) | ++-------------------------------------------------------------------+ +| aAbBac | ++-------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) + +### Time and Date Functions + +- [to_date](#to-date) + +##### `to_date` + +Converts a value to a date (`YYYY-MM-DD`). +Supports strings, integer and double types as input. +Strings are parsed as YYYY-MM-DD (e.g. '2023-07-20') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. +Integers and doubles are interpreted as days since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding date. + +Note: `to_date` returns Date32, which represents its values as the number of days since unix epoch(`1970-01-01`) stored as signed 32 bit value. The largest supported date value is `9999-12-31`. + +``` +to_date('2017-05-31', '%Y-%m-%d') +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **format_n**: Optional [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +```sql +> select to_date('2023-01-31'); ++-----------------------------+ +| to_date(Utf8("2023-01-31")) | ++-----------------------------+ +| 2023-01-31 | ++-----------------------------+ +> select to_date('2023/01/31', '%Y-%m-%d', '%Y/%m/%d'); ++---------------------------------------------------------------+ +| to_date(Utf8("2023/01/31"),Utf8("%Y-%m-%d"),Utf8("%Y/%m/%d")) | ++---------------------------------------------------------------+ +| 2023-01-31 | ++---------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs) + +### Struct Functions + +- [named_struct](#named-struct) +- [row](#row) +- [struct](#struct) + +##### `named_struct` + +Returns an Arrow struct using the specified name and input expressions pairs. + +``` +named_struct(expression1_name, expression1_input[, ..., expression_n_name, expression_n_input]) +``` + +###### Arguments + +- **expression_n_name**: Name of the column field. Must be a constant string. +- **expression_n_input**: Expression to include in the output struct. Can be a constant, column, or function, and any combination of arithmetic or string operators. + +###### Example + +For example, this query converts two columns `a` and `b` to a single column with +a struct type of fields `field_a` and `field_b`: + +```sql +> select * from t; ++---+---+ +| a | b | ++---+---+ +| 1 | 2 | +| 3 | 4 | ++---+---+ +> select named_struct('field_a', a, 'field_b', b) from t; ++-------------------------------------------------------+ +| named_struct(Utf8("field_a"),t.a,Utf8("field_b"),t.b) | ++-------------------------------------------------------+ +| {field_a: 1, field_b: 2} | +| {field_a: 3, field_b: 4} | ++-------------------------------------------------------+ +``` + +##### `row` + +_Alias of [struct](#struct)._ + +##### `struct` + +Returns an Arrow struct using the specified input expressions optionally named. +Fields in the returned struct use the optional name or the `cN` naming convention. +For example: `c0`, `c1`, `c2`, etc. + +``` +struct(expression1[, ..., expression_n]) +``` + +###### Arguments + +- **expression1, expression_n**: Expression to include in the output struct. Can be a constant, column, or function, any combination of arithmetic or string operators. + +###### Example + +For example, this query converts two columns `a` and `b` to a single column with +a struct type of fields `field_a` and `c1`: + +```sql +> select * from t; ++---+---+ +| a | b | ++---+---+ +| 1 | 2 | +| 3 | 4 | ++---+---+ + +-- use default names `c0`, `c1` +> select struct(a, b) from t; ++-----------------+ +| struct(t.a,t.b) | ++-----------------+ +| {c0: 1, c1: 2} | +| {c0: 3, c1: 4} | ++-----------------+ + +-- name the first field `field_a` +select struct(a as field_a, b) from t; ++--------------------------------------------------+ +| named_struct(Utf8("field_a"),t.a,Utf8("c1"),t.b) | ++--------------------------------------------------+ +| {field_a: 1, c1: 2} | +| {field_a: 3, c1: 4} | ++--------------------------------------------------+ +``` + +###### Aliases + +- row + +### Hashing Functions + +- [digest](#digest) +- [md5](#md5) +- [sha224](#sha224) +- [sha256](#sha256) +- [sha384](#sha384) +- [sha512](#sha512) + +##### `digest` + +Computes the binary hash of an expression using the specified algorithm. + +``` +digest(expression, algorithm) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **algorithm**: String expression specifying algorithm to use. Must be one of: +- md5 +- sha224 +- sha256 +- sha384 +- sha512 +- blake2s +- blake2b +- blake3 + +###### Example + +```sql +> select digest('foo', 'sha256'); ++------------------------------------------+ +| digest(Utf8("foo"), Utf8("sha256")) | ++------------------------------------------+ +| | ++------------------------------------------+ +``` + +##### `md5` + +Computes an MD5 128-bit checksum for a string expression. + +``` +md5(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select md5('foo'); ++-------------------------------------+ +| md5(Utf8("foo")) | ++-------------------------------------+ +| | ++-------------------------------------+ +``` + +##### `sha224` + +Computes the SHA-224 hash of a binary string. + +``` +sha224(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select sha224('foo'); ++------------------------------------------+ +| sha224(Utf8("foo")) | ++------------------------------------------+ +| | ++------------------------------------------+ +``` + +##### `sha256` + +Computes the SHA-256 hash of a binary string. + +``` +sha256(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select sha256('foo'); ++--------------------------------------+ +| sha256(Utf8("foo")) | ++--------------------------------------+ +| | ++--------------------------------------+ +``` + +##### `sha384` + +Computes the SHA-384 hash of a binary string. + +``` +sha384(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select sha384('foo'); ++-----------------------------------------+ +| sha384(Utf8("foo")) | ++-----------------------------------------+ +| | ++-----------------------------------------+ +``` + +##### `sha512` + +Computes the SHA-512 hash of a binary string. + +``` +sha512(expression) +``` + +###### Arguments + +- **expression**: String + +###### Example + +```sql +> select sha512('foo'); ++-------------------------------------------+ +| sha512(Utf8("foo")) | ++-------------------------------------------+ +| | ++-------------------------------------------+ +``` + +### Other Functions + +- [arrow_cast](#arrow-cast) +- [arrow_typeof](#arrow-typeof) +- [get_field](#get-field) +- [version](#version) + +##### `arrow_cast` + +Casts a value to a specific Arrow data type. + +``` +arrow_cast(expression, datatype) +``` + +###### Arguments + +- **expression**: Expression to cast. The expression can be a constant, column, or function, and any combination of operators. +- **datatype**: [Arrow data type](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html) name to cast to, as a string. The format is the same as that returned by [`arrow_typeof`] + +###### Example + +```sql +> select arrow_cast(-5, 'Int8') as a, + arrow_cast('foo', 'Dictionary(Int32, Utf8)') as b, + arrow_cast('bar', 'LargeUtf8') as c, + arrow_cast('2023-01-02T12:53:02', 'Timestamp(Microsecond, Some("+08:00"))') as d + ; ++----+-----+-----+---------------------------+ +| a | b | c | d | ++----+-----+-----+---------------------------+ +| -5 | foo | bar | 2023-01-02T12:53:02+08:00 | ++----+-----+-----+---------------------------+ +``` + +##### `arrow_typeof` + +Returns the name of the underlying [Arrow data type](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html) of the expression. + +``` +arrow_typeof(expression) +``` + +###### Arguments + +- **expression**: Expression to evaluate. The expression can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select arrow_typeof('foo'), arrow_typeof(1); ++---------------------------+------------------------+ +| arrow_typeof(Utf8("foo")) | arrow_typeof(Int64(1)) | ++---------------------------+------------------------+ +| Utf8 | Int64 | ++---------------------------+------------------------+ +``` + +##### `get_field` + +Returns a field within a map or a struct with the given key. +Note: most users invoke `get_field` indirectly via field access +syntax such as `my_struct_col['field_name']` which results in a call to +`get_field(my_struct_col, 'field_name')`. + +``` +get_field(expression1, expression2) +``` + +###### Arguments + +- **expression1**: The map or struct to retrieve a field for. +- **expression2**: The field name in the map or struct to retrieve data for. Must evaluate to a string. + +###### Example + +```sql +> create table t (idx varchar, v varchar) as values ('data','fusion'), ('apache', 'arrow'); +> select struct(idx, v) from t as c; ++-------------------------+ +| struct(c.idx,c.v) | ++-------------------------+ +| {c0: data, c1: fusion} | +| {c0: apache, c1: arrow} | ++-------------------------+ +> select get_field((select struct(idx, v) from t), 'c0'); ++-----------------------+ +| struct(t.idx,t.v)[c0] | ++-----------------------+ +| data | +| apache | ++-----------------------+ +> select get_field((select struct(idx, v) from t), 'c1'); ++-----------------------+ +| struct(t.idx,t.v)[c1] | ++-----------------------+ +| fusion | +| arrow | ++-----------------------+ +``` + +##### `version` + +Returns the version of DataFusion. + +``` +version() +``` + +###### Example + +```sql +> select version(); ++--------------------------------------------+ +| version() | ++--------------------------------------------+ +| Apache DataFusion 42.0.0, aarch64 on macos | ++--------------------------------------------+ +``` + + +## Aggregate Functions + +Aggregate functions operate on a set of values to compute a single result. + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. +Please see the [Aggregate Functions (new)](#aggregate-functions-new) page for +the rest of the documentation. + +[automatically created from the codebase]: https://github.com/apache/datafusion/issues/12740 + +### Statistical + +- [covar](#covar) +- [regr_avgx](#regr-avgx) +- [regr_avgy](#regr-avgy) +- [regr_count](#regr-count) +- [regr_intercept](#regr-intercept) +- [regr_r2](#regr-r2) +- [regr_slope](#regr-slope) +- [regr_sxx](#regr-sxx) +- [regr_syy](#regr-syy) +- [regr_sxy](#regr-sxy) + +##### `covar` + +Returns the covariance of a set of number pairs. + +``` +covar(expression1, expression2) +``` + +###### Arguments + +- **expression1**: First expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression2**: Second expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_slope` + +Returns the slope of the linear regression line for non-null pairs in aggregate columns. +Given input column Y and X: regr_slope(Y, X) returns the slope (k in Y = k\*X + b) using minimal RSS fitting. + +``` +regr_slope(expression1, expression2) +``` + +###### Arguments + +- **expression_y**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_avgx` + +Computes the average of the independent variable (input) `expression_x` for the non-null paired data points. + +``` +regr_avgx(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_avgy` + +Computes the average of the dependent variable (output) `expression_y` for the non-null paired data points. + +``` +regr_avgy(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_count` + +Counts the number of non-null paired data points. + +``` +regr_count(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_intercept` + +Computes the y-intercept of the linear regression line. For the equation \(y = kx + b\), this function returns `b`. + +``` +regr_intercept(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_r2` + +Computes the square of the correlation coefficient between the independent and dependent variables. + +``` +regr_r2(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_sxx` + +Computes the sum of squares of the independent variable. + +``` +regr_sxx(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_syy` + +Computes the sum of squares of the dependent variable. + +``` +regr_syy(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_sxy` + +Computes the sum of products of paired data points. + +``` +regr_sxy(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + + +## Window Functions + +A _window function_ performs a calculation across a set of table rows that are somehow related to the current row. + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. +Please see the [Window Functions (new)](#window-functions-new) page for +the rest of the documentation. + +[automatically created from the codebase]: https://github.com/apache/datafusion/issues/12740 + +Window functions are comparable to the type of calculation that can be done with an aggregate function. However, window functions do not cause rows to become grouped into a single output row like non-window aggregate calls would. Instead, the rows retain their separate identities. Behind the scenes, the window function is able to access more than just the current row of the query result + +Here is an example that shows how to compare each employee's salary with the average salary in his or her department: + +```sql +SELECT depname, empno, salary, avg(salary) OVER (PARTITION BY depname) FROM empsalary; + ++-----------+-------+--------+-------------------+ +| depname | empno | salary | avg | ++-----------+-------+--------+-------------------+ +| personnel | 2 | 3900 | 3700.0 | +| personnel | 5 | 3500 | 3700.0 | +| develop | 8 | 6000 | 5020.0 | +| develop | 10 | 5200 | 5020.0 | +| develop | 11 | 5200 | 5020.0 | +| develop | 9 | 4500 | 5020.0 | +| develop | 7 | 4200 | 5020.0 | +| sales | 1 | 5000 | 4866.666666666667 | +| sales | 4 | 4800 | 4866.666666666667 | +| sales | 3 | 4800 | 4866.666666666667 | ++-----------+-------+--------+-------------------+ +``` + +A window function call always contains an OVER clause directly following the window function's name and argument(s). This is what syntactically distinguishes it from a normal function or non-window aggregate. The OVER clause determines exactly how the rows of the query are split up for processing by the window function. The PARTITION BY clause within OVER divides the rows into groups, or partitions, that share the same values of the PARTITION BY expression(s). For each row, the window function is computed across the rows that fall into the same partition as the current row. The previous example showed how to count the average of a column per partition. + +You can also control the order in which rows are processed by window functions using ORDER BY within OVER. (The window ORDER BY does not even have to match the order in which the rows are output.) Here is an example: + +```sql +SELECT depname, empno, salary, + rank() OVER (PARTITION BY depname ORDER BY salary DESC) +FROM empsalary; + ++-----------+-------+--------+--------+ +| depname | empno | salary | rank | ++-----------+-------+--------+--------+ +| personnel | 2 | 3900 | 1 | +| develop | 8 | 6000 | 1 | +| develop | 10 | 5200 | 2 | +| develop | 11 | 5200 | 2 | +| develop | 9 | 4500 | 4 | +| develop | 7 | 4200 | 5 | +| sales | 1 | 5000 | 1 | +| sales | 4 | 4800 | 2 | +| personnel | 5 | 3500 | 2 | +| sales | 3 | 4800 | 2 | ++-----------+-------+--------+--------+ +``` + +There is another important concept associated with window functions: for each row, there is a set of rows within its partition called its window frame. Some window functions act only on the rows of the window frame, rather than of the whole partition. Here is an example of using window frames in queries: + +```sql +SELECT depname, empno, salary, + avg(salary) OVER(ORDER BY salary ASC ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING) AS avg, + min(salary) OVER(ORDER BY empno ASC ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS cum_min +FROM empsalary +ORDER BY empno ASC; + ++-----------+-------+--------+--------------------+---------+ +| depname | empno | salary | avg | cum_min | ++-----------+-------+--------+--------------------+---------+ +| sales | 1 | 5000 | 5000.0 | 5000 | +| personnel | 2 | 3900 | 3866.6666666666665 | 3900 | +| sales | 3 | 4800 | 4700.0 | 3900 | +| sales | 4 | 4800 | 4866.666666666667 | 3900 | +| personnel | 5 | 3500 | 3700.0 | 3500 | +| develop | 7 | 4200 | 4200.0 | 3500 | +| develop | 8 | 6000 | 5600.0 | 3500 | +| develop | 9 | 4500 | 4500.0 | 3500 | +| develop | 10 | 5200 | 5133.333333333333 | 3500 | +| develop | 11 | 5200 | 5466.666666666667 | 3500 | ++-----------+-------+--------+--------------------+---------+ +``` + +When a query involves multiple window functions, it is possible to write out each one with a separate OVER clause, but this is duplicative and error-prone if the same windowing behavior is wanted for several functions. Instead, each windowing behavior can be named in a WINDOW clause and then referenced in OVER. For example: + +```sql +SELECT sum(salary) OVER w, avg(salary) OVER w +FROM empsalary +WINDOW w AS (PARTITION BY depname ORDER BY salary DESC); +``` + +### Syntax + +The syntax for the OVER-clause is + +``` +function([expr]) + OVER( + [PARTITION BY expr[, …]] + [ORDER BY expr [ ASC | DESC ][, …]] + [ frame_clause ] + ) +``` + +where **frame_clause** is one of: + +``` + { RANGE | ROWS | GROUPS } frame_start + { RANGE | ROWS | GROUPS } BETWEEN frame_start AND frame_end +``` + +and **frame_start** and **frame_end** can be one of + +```sql +UNBOUNDED PRECEDING +offset PRECEDING +CURRENT ROW +offset FOLLOWING +UNBOUNDED FOLLOWING +``` + +where **offset** is an non-negative integer. + +RANGE and GROUPS modes require an ORDER BY clause (with RANGE the ORDER BY must specify exactly one column). + +### Aggregate functions + +All [aggregate functions](#aggregate-functions) can be used as window functions. + +### Ranking functions + +- [rank](#rank) +- [dense_rank](#dense-rank) +- [ntile](#ntile) + +##### `rank` + +Rank of the current row with gaps; same as row_number of its first peer. + +```sql +rank() +``` + +##### `dense_rank` + +Rank of the current row without gaps; this function counts peer groups. + +```sql +dense_rank() +``` + +##### `ntile` + +Integer ranging from 1 to the argument value, dividing the partition as equally as possible. + +```sql +ntile(expression) +``` + +###### Arguments + +- **expression**: An integer describing the number groups the partition should be split into + +### Analytical functions + +- [cume_dist](#cume-dist) +- [percent_rank](#percent-rank) +- [lag](#lag) +- [lead](#lead) +- [first_value](#first-value) +- [last_value](#last-value) +- [nth_value](#nth-value) + +##### `cume_dist` + +Relative rank of the current row: (number of rows preceding or peer with current row) / (total rows). + +```sql +cume_dist() +``` + +##### `percent_rank` + +Relative rank of the current row: (rank - 1) / (total rows - 1). + +```sql +percent_rank() +``` + +##### `lag` + +Returns value evaluated at the row that is offset rows before the current row within the partition; if there is no such row, instead return default (which must be of the same type as value). Both offset and default are evaluated with respect to the current row. If omitted, offset defaults to 1 and default to null. + +```sql +lag(expression, offset, default) +``` + +###### Arguments + +- **expression**: Expression to operate on +- **offset**: Integer. Specifies how many rows back the value of _expression_ should be retrieved. Defaults to 1. +- **default**: The default value if the offset is not within the partition. Must be of the same type as _expression_. + +##### `lead` + +Returns value evaluated at the row that is offset rows after the current row within the partition; if there is no such row, instead return default (which must be of the same type as value). Both offset and default are evaluated with respect to the current row. If omitted, offset defaults to 1 and default to null. + +```sql +lead(expression, offset, default) +``` + +###### Arguments + +- **expression**: Expression to operate on +- **offset**: Integer. Specifies how many rows forward the value of _expression_ should be retrieved. Defaults to 1. +- **default**: The default value if the offset is not within the partition. Must be of the same type as _expression_. + +##### `first_value` + +Returns value evaluated at the row that is the first row of the window frame. + +```sql +first_value(expression) +``` + +###### Arguments + +- **expression**: Expression to operate on + +##### `last_value` + +Returns value evaluated at the row that is the last row of the window frame. + +```sql +last_value(expression) +``` + +###### Arguments + +- **expression**: Expression to operate on + +##### `nth_value` + +Returns value evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row. + +```sql +nth_value(expression, n) +``` + +###### Arguments + +- **expression**: The name the column of which nth value to retrieve +- **n**: Integer. Specifies the _n_ in nth diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/geo.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/geo.md new file mode 100644 index 000000000..f5ff87a7d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/geo.md @@ -0,0 +1,443 @@ +--- +description: 列出了 GreptimeDB 中的所有地理空间相关函数，包括函数的定义、使用方法和相关的 SQL 查询示例。 +--- + +import TOCInline from '@theme/TOCInline'; + +# 地理函数 + +这个页面列出了 GreptimeDB 中的所有地理空间相关函数。当您启用了 +`common-function/geo` 特性（默认为开启状态）时，这些函数才会生效。 + + + +## Geo 数据类型函数 + +地理相关数据类型转换。 + +### `wkt_point_from_latlng` + +将纬度、经度转换成 WKT 点。 + +```sql +SELECT wkt_point_from_latlng(37.76938, -122.3889) AS point; +``` + +## Geohash + +了解 [更多关于 geohash 编码](https://en.wikipedia.org/wiki/Geohash)。 + +### `geohash` + +从纬度、经度和分辨率获取 geohash 编码的字符串。 + +```sql +SELECT geohash(37.76938, -122.3889, 11); +``` + +### `geohash_neighbours` + +给定坐标和分辨率获取所有 geohash 邻接点。 + +请注意，此函数返回一个字符串数组，并且仅在我们的HTTP查询API和Postgres通道上生效。 + +```sql +SELECT geohash_neighbours(37.76938, -122.3889, 11); +``` + +## H3 + +H3 地理坐标编码算法。[了解更多](https://h3geo.org/)。 + +### `h3_latlng_to_cell` + +将坐标（纬度，经度）编码为指定分辨率下的 h3 索引，并返回该单元格的 UInt64 表示。 + +```sql +SELECT h3_latlng_to_cell(37.76938, -122.3889, 1); +``` + +### `h3_latlng_to_cell_string` + +类似于 `h3_latlng_to_cell` ，但返回字符串编码格式。 + +```sql +h3_latlng_to_cell_string(37.76938, -122.3889, 1); +``` + +### `h3_cell_to_string` + +将单元格索引（UInt64）转换为其字符串表示形式。 + +```sql +SELECT h3_cell_to_string(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_string_to_cell` + +将十六进制编码的单元 ID 转换为其 UInt64 形式。 + +```sql +h3_string_to_cell(h3_latlng_to_cell_string(37.76938, -122.3889, 8::UInt64)); +``` + +### `h3_cell_center_latlng` + +返回单元中心的纬度和经度。 + +请注意，此函数返回一个浮点数数组，并且仅在我们的 HTTP 查询 API 和 Postgres 通道上有效。 + +```sql +SELECT h3_cell_center_latlng(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_cell_resolution` + +给定单元格的返回分辨率。 + +```sql +SELECT h3_cell_resolution(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_cell_base` + +返回给定单元的 Base 单元。 + +```sql +SELECT h3_cell_base(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_cell_is_pentagon` + +如果单元格是五边形，则返回 true。 + +```sql +SELECT h3_cell_is_pentagon(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_cell_parent` + +返回给定分辨率下单元的父单元。 + +```sql +h3_cell_parent(h3_latlng_to_cell(37.76938, -122.3889, 8), 6); +``` + +### `h3_cell_to_children` + +根据给定的分辨率返回子单元格。 + +请注意，此函数返回一个 UInt64 数组，并且仅在我们的 HTTP 查询 API 和 Postgres 通道上生效。 + +```sql +h3_cell_to_children(h3_latlng_to_cell(37.76938, -122.3889, 8), 10); +``` + +### `h3_cell_to_children_size` + +根据给定的分辨率，返回单元格中的子单元数量。 + + +```sql +h3_cell_to_children_size(h3_latlng_to_cell(37.76938, -122.3889, 8), 10); +``` + +### `h3_cell_to_child_pos` + +根据给定分辨率，返回单元在其父单元的位置。位置是单元在所有子单元中的索引。 + +```sql +h3_cell_to_child_pos(h3_latlng_to_cell(37.76938, -122.3889, 8), 6) +``` + +### `h3_child_pos_to_cell` + +在给定分辨率下，返回父单元中给定位置的单元。 + +参数： + +- 位置 +- 单元索引 +- 分辨率 + +```sql +h3_child_pos_to_cell(25, h3_latlng_to_cell(37.76938, -122.3889, 8), 11); +``` + +### `h3_cells_contains` + +测试输入的单元集合是否包含指定的单元，或其父单元。 + +参数： + +- 单元集合： 可以是 int64/uint64/string 数组, 或逗号分割的字符串单元 ID +- 单元索引 + +```sql +SELECT + h3_cells_contains('86283470fffffff,862834777ffffff, 862834757ffffff, 86283471fffffff, 862834707ffffff', '8b283470d112fff') AS R00, + h3_cells_contains(['86283470fffffff', '862834777ffffff', '862834757ffffff', '86283471fffffff', '862834707ffffff'], '8b283470d112fff') AS R11, + h3_cells_contains([604189641255419903, 604189643000250367, 604189642463379455, 604189641523855359, 604189641121202175], 604189641792290815) AS R21; +``` + +### `h3_grid_disk` + +返回给定单元格的 k 个距离对应的单元格。 + +请注意，此函数返回一个 UInt64 数组，并且仅能在我们的 HTTP 查询 API 和 Postgres 通道上工作。 + +```sql +h3_grid_disk(h3_latlng_to_cell(37.76938, -122.3889, 8), 3); +``` + +### `h3_grid_disk_distances` + +返回给定单元格范围内所有距离为 *k* 的单元格。 + +请注意，此函数返回一个 UInt64 数组，并且仅适用于我们的 HTTP 查询 API 和 Postgres 通道。 + +```sql +h3_grid_disk_distance(h3_latlng_to_cell(37.76938, -122.3889, 8), 3); +``` + +### `h3_grid_distance` + +返回两单元的距离。 + +```sql +SELECT + h3_grid_distance(cell1, cell2) AS distance, +FROM + ( + SELECT + h3_latlng_to_cell(37.76938, -122.3889, 8) AS cell1, + h3_latlng_to_cell(39.634, -104.999, 8) AS cell2 + ); +``` + +### `h3_grid_path_cells` + +此函数可在两个单元格之间返回路径单元格。请注意，如果两个单元格相距很远，该函数可能会失败。 + +```sql +SELECT + h3_grid_path_cells(cell1, cell2) AS path_cells, +FROM + ( + SELECT + h3_latlng_to_cell(37.76938, -122.3889, 8) AS cell1, + h3_latlng_to_cell(39.634, -104.999, 8) AS cell2 + ); +``` + +### `h3_distance_sphere_km` + +返回两个单元中心的大圆距离，单位：千米 + +```sql +SELECT + round(h3_distance_sphere_km(cell1, cell2), 5) AS sphere_distance +FROM + ( + SELECT + h3_string_to_cell('86283082fffffff') AS cell1, + h3_string_to_cell('86283470fffffff') AS cell2 + ); + +``` + +### `h3_distance_degree` + +返回两个单元中心的欧式距离，单位：度 + +```sql +SELECT + round(h3_distance_degree(cell1, cell2), 14) AS euclidean_distance +FROM + ( + SELECT + h3_string_to_cell('86283082fffffff') AS cell1, + h3_string_to_cell('86283470fffffff') AS cell2 + ); +``` + +## S2 + +了解[更多关于 S2 编码的信息](http://s2geometry.io/). + +### `s2_latlng_to_cell` + +给定坐标对应的 s2 单元索引。 + +```sql +SELECT s2_latlng_to_cell(37.76938, -122.3889); +``` + +### `s2_cell_to_token` + +给定单元格的字符串表示形式。 + +```sql +SELECT s2_cell_to_token(s2_latlng_to_cell(37.76938, -122.3889)); +``` + +### `s2_cell_level` + +返回给定单元格的级别。 + +```sql +SELECT s2_cell_level(s2_latlng_to_cell(37.76938, -122.3889)); +``` + +### `s2_cell_parent` + +返回给定单元格位于特定级别的父单元。 + +```sql +SELECT s2_cell_parent(s2_latlng_to_cell(37.76938, -122.3889), 3); +``` + +## 编码 + +### `json_encode_path` + +将纬度、经度按时间戳排序并编码为一个 JSON 数组。 + +参数： + +- 纬度 +- 经度 +- 时间戳 + +返回一个字符串类型的JSON数组。请注意，结果坐标中的顺序为 [经度, 纬度]，以符合 GeoJSON 规范。 + +```sql +SELECT json_encode_path(lat, lon, ts); +``` + +示例输出： + +```json +[[-122.3888,37.77001],[-122.3839,37.76928],[-122.3889,37.76938],[-122.382,37.7693]] +``` + +## 空间关系 + +### `st_contains` + +测试两个空间对象是否为包含关系。 + +参数：WKT 编码的地理对象。 + +```sql +SELECT + st_contains(polygon1, p1), + st_contains(polygon2, p1), +FROM + ( + SELECT + wkt_point_from_latlng(37.383287, -122.01325) AS p1, + 'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2, + ); + +``` + +### `st_within` + +测试两个空间对象是否为被包含关系。 + +参数：WKT 编码的地理对象。 + +```sql +SELECT + st_within(p1, polygon1), + st_within(p1, polygon2), + ROM + ( + SELECT + wkt_point_from_latlng(37.383287, -122.01325) AS p1, + 'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2, + ); + +``` + + +### `st_intersects` + +测试两个空间对象是否为重叠关系。 + +参数：WKT 编码的地理对象。 + +```sql +SELECT + st_intersects(polygon1, polygon2), + st_intersects(polygon1, polygon3), +FROM + ( + SELECT + 'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2, + 'POLYGON ((-122.089628 37.450332, -122.20535 37.378342, -122.093062 37.36088, -122.044301 37.372886, -122.089628 37.450332))' AS polygon3, + ); + +``` + + +## Spatial Measurement + +### `st_distance` + +返回两个对象的在 WGS84 坐标系下的欧式距离，单位：度。 + +参数：WKT 编码的地理对象。 + +```sql +SELECT + st_distance(p1, p2) AS euclidean_dist, + st_distance(p1, polygon1) AS euclidean_dist_pp, +FROM + ( + SELECT + wkt_point_from_latlng(37.76938, -122.3889) AS p1, + wkt_point_from_latlng(38.5216, -121.4247) AS p2, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon1, + ); +``` + +### `st_distance_sphere_m` + +返回两点的大圆距离，单位：米。 + +参数：WKT 编码的地理对象。 + +```sql +SELECT + st_distance_sphere_m(p1, p2) AS sphere_dist_m, +FROM + ( + SELECT + wkt_point_from_latlng(37.76938, -122.3889) AS p1, + wkt_point_from_latlng(38.5216, -121.4247) AS p2, + ); + +``` + +### `st_area` + +返回地理对象的面积。 + +参数：WKT 编码的地理对象。 + +```sql +SELECT + st_area(p1) as area_point, + st_area(polygon1) as area_polygon, +FROM + ( + SELECT + wkt_point_from_latlng(37.76938, -122.3889) AS p1, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon1, + ); +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/json.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/json.md new file mode 100644 index 000000000..2eea60ce3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/json.md @@ -0,0 +1,124 @@ +--- +description: 列出了 GreptimeDB 中的所有 JSON 函数，包括函数的定义、使用方法和相关的 SQL 查询示例。 +--- + +# JSON 函数 + +本页面列出了 GreptimeDB 中所有 JSON 类型相关的函数。 + + +## 转换 + +JSON 类型与其他类型的值之间的转换。 + +* `parse_json(string)` 尝试将字符串解析为 JSON 类型。非法的 JSON 字符串将返回错误。 +* `json_to_string(json)` 将 JSON 类型的值转换为字符串。 + +```sql +SELECT json_to_string(parse_json('{"a": 1, "b": 2}')); + ++----------------------------------------------------------+ +| json_to_string(parse_json(Utf8("{\"a\": 1, \"b\": 2}"))) | ++----------------------------------------------------------+ +| {"a":1,"b":2} | ++----------------------------------------------------------+ +``` + +## 提取 + +通过给定的路径和给定的数据类型，从 JSON 中提取值。 + +* `json_get_bool(json, path)` 按照路径 `path` 从 JSON 中获取布尔值。 +* `json_get_int(json, path)` 按照路径 `path` 从 JSON 中获取整数值。布尔值将被转换为整数。 +* `json_get_float(json, path)` 按照路径 `path` 从 JSON 中获取浮点数值。布尔值、整数值将被转换为浮点数。 +* `json_get_string(json, path)` 按照路径 `path` 从 JSON 中获取字符串。所有类型的 JSON 值都将被转换为字符串，包括数组、对象和 null。 + +`path` 是一个用于从 JSON 值中选择和提取元素的字符串。`path` 中支持的操作符有： + +| 操作符 | 描述 | 示例 | +|--------------------------|--------------------------------------------------------------|--------------------| +| `$` | 根元素 | `$` | +| `@` | 过滤表达式中的当前元素 | `$.event?(@ == 1)` | +| `.*` | 选择对象中的所有元素 | `$.*` | +| `.` | 选择对象中匹配名称的元素 | `$.event` | +| `:` | `.` 的别名 | `$:event` | +| `[""]` | `.` 的别名 | `$["event"]` | +| `[*]` | 选择数组中的所有元素 | `$[*]` | +| `[, ..]` | 选择数组中基于0的第 `n` 个元素 | `$[1, 2]` | +| `[last - , ..]` | 选择数组中最后一个元素之前的第 `n` 个元素 | `$[0, last - 1]` | +| `[ to , ..]` | 选择数组中某个范围内的所有元素 | `$[1 to last - 2]` | +| `?()` | 选择所有匹配过滤表达式的元素 | `$?(@.price < 10)` | + +如果 `path` 是无效的，函数将返回 `NULL`。 + +```sql +SELECT json_get_int(parse_json('{"a": {"c": 3}, "b": 2}'), 'a.c'); + ++-----------------------------------------------------------------------+ +| json_get_int(parse_json(Utf8("{"a": {"c": 3}, "b": 2}")),Utf8("a.c")) | ++-----------------------------------------------------------------------+ +| 3 | ++-----------------------------------------------------------------------+ +``` + +## 验证 + +检查 JSON 值的类型。 + +* `json_is_null(json)` 检查 JSON 中的值是否为 `NULL`。 +* `json_is_bool(json)` 检查 JSON 中的值是否为布尔值。 +* `json_is_int(json)` 检查 JSON 中的值是否为整数。 +* `json_is_float(json)` 检查 JSON 中的值是否为浮点数。 +* `json_is_string(json)` 检查 JSON 中的值是否为字符串。 +* `json_is_array(json)` 检查 JSON 中的值是否为数组。 +* `json_is_object(json)` 检查 JSON 中的值是否为对象。 + +```sql +SELECT json_is_array(parse_json('[1, 2, 3]')); + ++----------------------------------------------+ +| json_is_array(parse_json(Utf8("[1, 2, 3]"))) | ++----------------------------------------------+ +| 1 | ++----------------------------------------------+ + +SELECT json_is_object(parse_json('1')); + ++---------------------------------------+ +| json_is_object(parse_json(Utf8("1"))) | ++---------------------------------------+ +| 0 | ++---------------------------------------+ +``` + +* `json_path_exists(json, path)` 检查 JSON 中是否存在指定的路径。 + +如果 `path` 是无效的，函数将返回错误。 + +如果 `path` 或 `json` 是 `NULL`，函数将返回 `NULL`。 + +```sql +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'a'); + ++------------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("a")) | ++------------------------------------------------------------------+ +| 1 | ++------------------------------------------------------------------+ + +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'c.d'); + ++--------------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("c.d")) | ++--------------------------------------------------------------------+ +| 0 | ++--------------------------------------------------------------------+ + +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), NULL); + ++-------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),NULL) | ++-------------------------------------------------------------+ +| NULL | ++-------------------------------------------------------------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/overview.md new file mode 100644 index 000000000..42060282c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/overview.md @@ -0,0 +1,236 @@ +--- +description: 提供了 GreptimeDB 中函数的概述，包括函数的分类、定义和使用方法。 +--- + +import TOCInline from '@theme/TOCInline'; + +# 概述 + + + + + +## Datafusion 函数 + +由于 GreptimeDB 的查询引擎是基于 Apache Arrow DataFusion 构建的，GreptimeDB 继承了 DataFusion 中所有内置的函数。这些函数包括： + +* **聚合函数**: 如 `COUNT`、`SUM`、`MIN`、`MAX` 等。详细列表请参阅 [聚合函数](./df-functions.md#aggregate-functions) +* **标量函数**: 如 `ABS`、`COS`、`FLOOR` 等。详细列表请参阅 [标量函数](./df-functions.md#scalar-functions) +* **窗口函数**: 对相关的一组行记录执行计算。详细列表请参阅 [窗口函数](./df-functions.md#window-functions) + +要查看所有 DataFusion 函数，请参阅 [DataFusion 函数](./df-functions)。 + +### `arrow_cast` + +`arrow_cast` 函数来自 DataFusion 的 [`arrow_cast`](./df-functions.md#arrow-cast)。其用法如下： + +```sql +arrow_cast(expression, datatype) +``` + +其中 `datatype` 可以是此 [列表](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) 中的任何有效 Arrow 数据类型。四种时间戳类型是： + +- Timestamp(Second, None) +- Timestamp(Millisecond, None) +- Timestamp(Microsecond, None) +- Timestamp(Nanosecond, None) + +（注意 `None` 表示时间戳不考虑时区） + +## GreptimeDB 函数 + +### 字符串函数 + +DataFusion [字符串函数](./df-functions.md#string-functions)。GreptimeDB 提供： +* `matches(expression, pattern)` 用于全文检索。 + +阅读[查询日志](/user-guide/logs/query-logs.md)文档获取更多详情。 + +### 数学函数 + +DataFusion [数学函数](./df-functions.md#math-functions)。GreptimeDB 额外提供： +* `clamp(value, lower, upper)` 将给定值限制在上下界之间： +```sql +SELECT CLAMP(10, 0, 1); + ++------------------------------------+ +| clamp(Int64(10),Int64(0),Int64(1)) | ++------------------------------------+ +| 1 | ++------------------------------------+ +``` + +```sql +SELECT CLAMP(0.5, 0, 1); + ++---------------------------------------+ +| clamp(Float64(0.5),Int64(0),Int64(1)) | ++---------------------------------------+ +| 0.5 | ++---------------------------------------+ +``` + +* `mod(x, y)` 获取一个数除以另一个数的余数： +```sql +SELECT mod(18, 4); + ++-------------------------+ +| mod(Int64(18),Int64(4)) | ++-------------------------+ +| 2 | ++-------------------------+ +``` + +* `pow(x, y)` 获取一个数的幂值： +```sql +SELECT pow(2, 10); + ++-------------------------+ +| pow(Int64(2),Int64(10)) | ++-------------------------+ +| 1024 | ++-------------------------+ +``` + +### 日期和时间函数 + +DataFusion [时间和日期函数](./df-functions.md#time-and-date-functions)。GreptimeDB 额外提供： + +* `date_add(expression, interval)` 向 Timestamp、Date 或 DateTime 添加一个间隔值： + +```sql +SELECT date_add('2023-12-06'::DATE, '3 month 5 day'); +``` + +``` ++----------------------------------------------------+ +| date_add(Utf8("2023-12-06"),Utf8("3 month 5 day")) | ++----------------------------------------------------+ +| 2024-03-11 | ++----------------------------------------------------+ +``` + +* `date_sub(expression, interval)` 从 Timestamp、Date 或 DateTime 减去一个间隔值： + +```sql +SELECT date_sub('2023-12-06 07:39:46.222'::TIMESTAMP_MS, INTERVAL '5 day'); +``` + +``` ++-----------------------------------------------------------------------------------------------------------------------------------------+ +| date_sub(arrow_cast(Utf8("2023-12-06 07:39:46.222"),Utf8("Timestamp(Millisecond, None)")),IntervalMonthDayNano("92233720368547758080")) | ++-----------------------------------------------------------------------------------------------------------------------------------------+ +| 2023-12-01 07:39:46.222000 | ++-----------------------------------------------------------------------------------------------------------------------------------------+ +``` + +* `date_format(expression, fmt)` 将 Timestamp、Date 或 DateTime格式化： + +```sql +SELECT date_format('2023-12-06 07:39:46.222'::TIMESTAMP, '%Y-%m-%d %H:%M:%S:%3f'); +``` + +``` ++-----------------------------------------------------------------------------------------------------------------------------+ +| date_format(arrow_cast(Utf8("2023-12-06 07:39:46.222"),Utf8("Timestamp(Millisecond, None)")),Utf8("%Y-%m-%d %H:%M:%S:%3f")) | ++-----------------------------------------------------------------------------------------------------------------------------+ +| 2023-12-06 07:39:46:222 | ++-----------------------------------------------------------------------------------------------------------------------------+ +``` + +支持的格式化符号请参阅 [chrono::format::strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) 模块。 + +* `to_unixtime(expression)` 将表达式转换为 Unix 时间戳（秒）。参数可以是整数（毫秒 Unix 时间戳）、Timestamp、Date、DateTime 或字符串类型。如果参数是字符串类型，函数将首先尝试将其转换为 DateTime、Timestamp 或 Date。 + +```sql +select to_unixtime('2023-03-01T06:35:02Z'); +``` + +``` ++-------------------------------------------+ +| to_unixtime(Utf8("2023-03-01T06:35:02Z")) | ++-------------------------------------------+ +| 1677652502 | ++-------------------------------------------+ +``` + +```sql +select to_unixtime('2023-03-01'::date); +``` + +``` ++---------------------------------+ +| to_unixtime(Utf8("2023-03-01")) | ++---------------------------------+ +| 1677628800 | ++---------------------------------+ +``` + +* `timezone()` 查询当前会话时区： + +```sql +select timezone(); +``` + +``` ++------------+ +| timezone() | ++------------+ +| UTC | ++------------+ +``` + +### 系统函数 + +* `isnull(expression)` 检查表达式是否为 `NULL`： +```sql + SELECT isnull(1); + + +------------------+ +| isnull(Int64(1)) | ++------------------+ +| 0 | ++------------------+ +``` + +```sql +SELECT isnull(NULL); + ++--------------+ +| isnull(NULL) | ++--------------+ +| 1 | ++--------------+ +``` + +* `build()` 查询 GreptimeDB 构建信息。 +* `version()` 查询 GreptimeDB 版本信息。 +* `database()` 查询当前会话数据库： + +```sql +select database(); + ++------------+ +| database() | ++------------+ +| public | ++------------+ +``` + +### 管理函数 + +GreptimeDB 提供了 `ADMIN` 语句来执行管理函数，请阅读 [ADMIN](/reference/sql/admin.md) 文档。 + +### JSON 函数 + +[了解 GreptimeDB 中 JSON 相关的函数](./json.md)。 + +### 地理函数 + +[了解 GreptimeDB 中轨迹、地理编码相关的地理函数](./geo.md)。 + +### 向量函数 + +[了解 GreptimeDB 中向量相关的函数](./vector.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/vector.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/vector.md new file mode 100644 index 000000000..10c6b7a93 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/functions/vector.md @@ -0,0 +1,106 @@ +--- +description: 列出了 GreptimeDB 中的所有向量函数，包括函数的定义、使用方法和相关的 SQL 查询示例。 +--- + +# 向量函数 + +本页面列出了 GreptimeDB 中所有支持的向量相关函数。向量函数主要用于处理向量运算，比如距离计算、相似度度量等。 + +## 距离计算 + +GreptimeDB 提供了以下常用的距离计算函数： + +* `vec_l2sq_distance(vec1, vec2)`：计算两个向量之间的 L2 距离的平方。 +* `vec_cos_distance(vec1, vec2)`：计算两个向量之间的余弦距离。 +* `vec_dot_product(vec1, vec2)`：计算两个向量之间的点积。 + +这些函数接受向量值作为参数。你可以通过 `parse_vec` 函数将字符串转变为向量值，例如 `parse_vec('[1.0, 2.0, 3.0]')`。同时，字符串格式的向量（例如 `[1.0, 2.0, 3.0]`）也可以直接使用，它们会被自动转换。无论采用哪种方式，向量的维度必须保持一致。 + +### `vec_l2sq_distance` + +计算两个向量之间的平方欧几里得距离（L2 距离的平方）。L2 距离是几何空间中两个点之间的直线距离，此函数返回其平方值以提高计算效率。 + +示例： + +```sql +SELECT vec_l2sq_distance(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')); +``` + +或者 + +```sql +SELECT vec_l2sq_distance('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]'); +``` + +说明： +* 参数为两个维度一致的向量。 +* 返回值类型为 `Float32` 标量。 + +### `vec_cos_distance` + +计算两个向量之间的余弦距离。余弦距离是两个向量之间的夹角余弦值，用于衡量向量之间的相似度。 + +示例： + +```sql +SELECT vec_cos_distance(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')); +``` + +或者 + +```sql +SELECT vec_cos_distance('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]'); +``` + +说明： +* 参数为两个维度一致的向量。 +* 返回值类型为 `Float32` 标量。 + +### `vec_dot_product` + +计算两个向量之间的点积。点积是两个向量对应元素的乘积之和，常用于度量两个向量的相似性或用于机器学习的线性变换中。 + +示例： + +```sql +SELECT vec_dot_product(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')); +``` + +或者 + +```sql +SELECT vec_dot_product('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]'); +``` + +说明： +* 参数为两个维度一致的向量。 +* 返回值类型为 `Float32` 标量。 + +## 转换函数 + +在处理数据库中的向量数据时，GreptimeDB 提供了方便的函数，用于在字符串和向量值之间进行转换。 + +### `parse_vec` + +将字符串转换为向量值。字符串必须以方括号 `[]` 包围，并且包含 `Float32` 类型的元素，元素之间用逗号分隔。 + +示例： + +```sql +CREATE TABLE vectors ( + ts TIMESTAMP, + vec_col VECTOR(3) +); + +INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:01', parse_vec('[1.0, 2.0, 3.0]')); +``` + +### `vec_to_string` + +将向量值转换为字符串。转换后的字符串格式为 `[, , ...]`。 + +示例： + +```sql +SELECT vec_to_string(vec_col) FROM vectors; +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/group_by.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/group_by.md new file mode 100644 index 000000000..971e3d8fb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/group_by.md @@ -0,0 +1,72 @@ +--- +description: GROUP BY 语句用于对具有相同值的行进行分组，通常与聚合函数一起使用。 +--- + +# GROUP BY + +SQL 中的 `GROUP BY` 语句用于对具有一个或多个列中的相同值的行进行分组。 +该子句通常与聚合函数（如 `COUNT`、`SUM`、`AVG` 等）一起使用，以生成汇总报表。 + +## Syntax + +`GROUP BY` 的基本语法如下： + +```sql +SELECT column1, column2, ..., aggregate_function(column_name) +FROM table_name +GROUP BY column1, column2, ...; +``` + +`GROUP BY` 语句根据子句中指定的列对结果集进行分组。 +聚合函数应用于具有相同值的组。 + +## 示例 + +假设有如下名为 `system_metrics` 的表： + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` + +### 根据 Tags 聚合 + +要获取每个 `idc` 中的 memory_util 平均值，可以使用以下 SQL： + +```sql +SELECT idc, AVG(memory_util) +FROM system_metrics +GROUP BY idc; +``` + +结果如下： + +```sql ++-------+---------------------------------+ +| idc | AVG(system_metrics.memory_util) | ++-------+---------------------------------+ +| idc_b | 66.7 | +| idc_c | 66.8 | +| idc_e | 66.7 | +| idc_a | 40.3 | ++-------+---------------------------------+ +``` + +### 根据 Time Interval 聚合 + +要获取 memory_util 的日均值，SQL 如下： + +```sql +SELECT date_trunc('day', ts) as dt, avg(memory_util) +FROM system_metrics +GROUP BY dt +``` + +请参考 [date_trunc](./functions/overview.md#date_trunc) 获取更多信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/build-info.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/build-info.md new file mode 100644 index 000000000..7e9723803 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/build-info.md @@ -0,0 +1,31 @@ +--- +description: 提供了 GreptimeDB 构建信息的相关内容，包括版本信息、构建时间和相关的 SQL 查询示例。 +--- + +# BUILD_INFO + +`BUILD_INFO` 表提供了系统的构建信息： + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM BUILD_INFO; +``` + +结果如下： + +```sql ++------------+------------------------------------------+------------------+-----------+-------------+ +| git_branch | git_commit | git_commit_short | git_clean | pkg_version | ++------------+------------------------------------------+------------------+-----------+-------------+ +| | c595a56ac89bef78b19a76aa60d8c6bcac7354a5 | c595a56a | true | 0.9.0 | ++------------+------------------------------------------+------------------+-----------+-------------+ +``` + +结果中的列： + +* `branch`：构建的 git 分支名称。 +* `git_commit`：提交构建的 `commit`。 +* `git_commit_short`：提交构建的 `commit` 缩写。 +* `git_clean`：如果构建源目录包含了所有提交的更改，则为 `true`。 +* `pkg_version`：GreptimeDB 版本。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/character-sets.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/character-sets.md new file mode 100644 index 000000000..c3a8696fa --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/character-sets.md @@ -0,0 +1,30 @@ +--- +description: 介绍了 GreptimeDB 中的字符集，包括字符集的定义、使用方法和相关的 SQL 查询示例。 +--- + +# CHARACTER_SETS + +`CHARACTER_SETS` 提供了 GreptimeDB 支持的可用字符集。 + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM CHARACTER_SETS; +``` + +结果如下： + +```sql ++--------------------+----------------------+---------------+--------+ +| character_set_name | default_collate_name | description | maxlen | ++--------------------+----------------------+---------------+--------+ +| utf8 | utf8_bin | UTF-8 Unicode | 4 | ++--------------------+----------------------+---------------+--------+ +``` + +结果中的列： + +* `character_set_name`：字符集的名称。 +* `default_collate_name`：字符集的默认排序规则名称。 +* `description`：字符集的描述。 +* `MAXLEN`：存储一个字符所需的最大字节数。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/cluster-info.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/cluster-info.md new file mode 100644 index 000000000..c3053c975 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/cluster-info.md @@ -0,0 +1,76 @@ +--- +description: 提供了 GreptimeDB 集群信息的相关内容，包括集群状态、节点信息和相关的 SQL 查询示例。 +--- + +# CLUSTER_INFO + +`CLUSTER_INFO` 表提供了集群的节点拓扑信息。 + + +```sql +USE INFORMATION_SCHEMA; + +DESC TABLE CLUSTER_INFO; +``` + +输出如下： + +```sql ++-------------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-------------+----------------------+------+------+---------+---------------+ +| peer_id | Int64 | | NO | | FIELD | +| peer_type | String | | NO | | FIELD | +| peer_addr | String | | YES | | FIELD | +| version | String | | NO | | FIELD | +| git_commit | String | | NO | | FIELD | +| start_time | TimestampMillisecond | | YES | | FIELD | +| uptime | String | | YES | | FIELD | +| active_time | String | | YES | | FIELD | ++-------------+----------------------+------+------+---------+---------------+ +``` + + +每个列的含义： + +* `peer_id`: 节点的服务器 ID。对于 standalone 来讲，该字段总是为 `0`，对于集群模式下的 frontend 该字段总为 `-1`。因为在这两种情况下，该字段没有实际含义。 +* `peer_type`: 节点类型, 分布式集群里可能是 `METASRV`、`FRONTEND` 或者 `DATANODE`。单机模式显示为 `STANDALONE`。 +* `peer_addr`: 节点的 gRPC 服务地址。对于单机部署，该字段总为空。 +* `version`: 节点的版本号，形如 `0.7.2` 的字符串。 +* `git_commit`: 节点编译的 git 版本号。 +* `start_time`: 节点的启动时间。 +* `uptime`: 节点的持续运行时间，形如 `24h 10m 59s 150ms` 的字符串。 +* `active_time`: 距离节点上一次活跃（也就是发送心跳请求）过去的时间，形如 `24h 10m 59s 150ms` 的字符串。单机模式下该字段总为空。 + + +尝试查询下这张表： + +```sql +SELECT * FROM CLUSTER_INFO; +``` + +一个单机模式的样例输出： + +```sql ++---------+------------+-----------+---------+------------+-------------------------+--------+-------------+ +| peer_id | peer_type | peer_addr | version | git_commit | start_time | uptime | active_time | ++---------+------------+-----------+---------+------------+-------------------------+--------+-------------+ +| 0 | STANDALONE | | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:02.074 | 18ms | | ++---------+------------+-----------+---------+------------+-------------------------+--------+-------------+ +``` + +另一个输出来自一个分布式集群，它有三个 Datanode、一个 Frontend 和一个 Metasrv： + +```sql ++---------+-----------+----------------+---------+------------+-------------------------+----------+-------------+ +| peer_id | peer_type | peer_addr | version | git_commit | start_time | uptime | active_time | ++---------+-----------+----------------+---------+------------+-------------------------+----------+-------------+ +| 1 | DATANODE | 127.0.0.1:4101 | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:04.791 | 4s 478ms | 1s 467ms | +| 2 | DATANODE | 127.0.0.1:4102 | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:06.098 | 3s 171ms | 162ms | +| 3 | DATANODE | 127.0.0.1:4103 | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:07.425 | 1s 844ms | 1s 839ms | +| -1 | FRONTEND | 127.0.0.1:4001 | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:08.815 | 454ms | 47ms | +| 0 | METASRV | 127.0.0.1:3002 | unknown | unknown | | | | ++---------+-----------+----------------+---------+------------+-------------------------+----------+-------------+ +``` + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/collation-character-set-applicability.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/collation-character-set-applicability.md new file mode 100644 index 000000000..00c060f8c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/collation-character-set-applicability.md @@ -0,0 +1,28 @@ +--- +description: 介绍了 GreptimeDB 中排序规则与字符集的适用性，包括如何在 SQL 查询中使用这些规则和字符集。 +--- + +# COLLATION_CHARACTER_SET_APPLICABILITY + +`COLLATION_CHARACTER_SET_APPLICABILITY` 表示了每个排序规则适用的字符集。 + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM COLLATION_CHARACTER_SET_APPLICABILITY; +``` + +结果如下： + +```sql ++----------------+--------------------+ +| collation_name | character_set_name | ++----------------+--------------------+ +| utf8_bin | utf8 | ++----------------+--------------------+ +``` + +结果中的列： + +* `collation_name`：排序规则名称。 +* `character_set_name`：与排序规则关联的字符集名称。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/collations.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/collations.md new file mode 100644 index 000000000..6fe1e8f23 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/collations.md @@ -0,0 +1,32 @@ +--- +description: 介绍了 GreptimeDB 中字符集的排序规则，包括排序规则的定义、使用方法和相关的 SQL 查询示例。 +--- + +# COLLATIONS + +`COLLATIONS` 提供了每个字符集的排序规则信息。 + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM COLLATIONS; +``` + +结果如下： + +```sql ++----------------+--------------------+------+------------+-------------+---------+ +| collation_name | character_set_name | id | is_default | is_compiled | sortlen | ++----------------+--------------------+------+------------+-------------+---------+ +| utf8_bin | utf8 | 1 | Yes | Yes | 1 | ++----------------+--------------------+------+------------+-------------+---------+ +``` + +表中有这些列： + +* `collation_name`：排序规则名称。 +* `character_set_name`：字符集名称。 +* `id`：排序规则 ID。 +* `is_default`：是否为字符集的默认排序规则。 +* `is_compiled`：字符集是否已编译到系统中。 +* `sortlen`：以字符集表示的字符串排序所需的最小内存量。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/columns.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/columns.md new file mode 100644 index 000000000..b54f22a12 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/columns.md @@ -0,0 +1,180 @@ +--- +description: COLUMNS 表提供关于表中每列的详细信息。 +--- + +# COLUMNS + +`COLUMNS` 提供了关于表中每列的详细信息。 + +```sql +USE INFORMATION_SCHEMA; +DESC COLUMNS; +``` + +结果如下： + +```sql ++--------------------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------------+--------+------+------+---------+---------------+ +| table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| column_name | String | | NO | | FIELD | +| ordinal_position | Int64 | | NO | | FIELD | +| character_maximum_length | Int64 | | YES | | FIELD | +| character_octet_length | Int64 | | YES | | FIELD | +| numeric_precision | Int64 | | YES | | FIELD | +| numeric_scale | Int64 | | YES | | FIELD | +| datetime_precision | Int64 | | YES | | FIELD | +| character_set_name | String | | YES | | FIELD | +| collation_name | String | | YES | | FIELD | +| column_key | String | | NO | | FIELD | +| extra | String | | NO | | FIELD | +| privileges | String | | NO | | FIELD | +| generation_expression | String | | NO | | FIELD | +| greptime_data_type | String | | NO | | FIELD | +| data_type | String | | NO | | FIELD | +| semantic_type | String | | NO | | FIELD | +| column_default | String | | YES | | FIELD | +| is_nullable | String | | NO | | FIELD | +| column_type | String | | NO | | FIELD | +| column_comment | String | | YES | | FIELD | +| srs_id | Int64 | | YES | | FIELD | ++--------------------------+--------+------+------+---------+---------------+ +24 rows in set (0.00 sec) +``` + +创建表 `public.t1` 并查询其在 `COLUMNS` 中的信息： + +```sql +CREATE TABLE public.t1 (h STRING, v FLOAT64, ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, PRIMARY KEY(h)); +SELECT * FROM COLUMNS WHERE table_schema='public' AND TABLE_NAME='t1'\G +``` + +结果如下： + +```sql +*************************** 1. row *************************** + table_catalog: greptime + table_schema: public + table_name: t1 + column_name: h + ordinal_position: 1 +character_maximum_length: 2147483647 + character_octet_length: 2147483647 + numeric_precision: NULL + numeric_scale: NULL + datetime_precision: NULL + character_set_name: utf8 + collation_name: utf8_bin + column_key: PRI + extra: + privileges: select,insert + generation_expression: + greptime_data_type: String + data_type: string + semantic_type: TAG + column_default: NULL + is_nullable: Yes + column_type: string + column_comment: NULL + srs_id: NULL +*************************** 2. row *************************** + table_catalog: greptime + table_schema: public + table_name: t1 + column_name: v + ordinal_position: 2 +character_maximum_length: NULL + character_octet_length: NULL + numeric_precision: 22 + numeric_scale: NULL + datetime_precision: NULL + character_set_name: NULL + collation_name: NULL + column_key: + extra: + privileges: select,insert + generation_expression: + greptime_data_type: Float64 + data_type: double + semantic_type: FIELD + column_default: NULL + is_nullable: Yes + column_type: double + column_comment: NULL + srs_id: NULL +*************************** 3. row *************************** + table_catalog: greptime + table_schema: public + table_name: t1 + column_name: ts + ordinal_position: 3 +character_maximum_length: NULL + character_octet_length: NULL + numeric_precision: NULL + numeric_scale: NULL + datetime_precision: 3 + character_set_name: NULL + collation_name: NULL + column_key: TIME INDEX + extra: + privileges: select,insert + generation_expression: + greptime_data_type: TimestampMillisecond + data_type: timestamp(3) + semantic_type: TIMESTAMP + column_default: current_timestamp() + is_nullable: No + column_type: timestamp(3) + column_comment: NULL + srs_id: NULL +3 rows in set (0.03 sec) +``` + +`COLUMNS` 表中列的描述如下： + +- `table_catalog`：列所属的目录的名称。在 OSS 项目中该值始终为 `greptime`。 +- `table_schema`：包含列的表所属的数据库的名称。 +- `table_name`：包含列的表的名称。 +- `column_name`：列的名称。 +- `ordinal_position`：列在表中的位置。 +- `character_maximum_length`：对于字符串列，以字符为单位的最大长度。 +- `character_octet_length`：对于字符串列，以字节为单位的最大长度。 +- `numeric_precision`：对于数值数据类型，列的精度。 +- `numeric_scale`：对于数值数据类型，列的标度。 +- `datetime_precision`：对于日期时间数据类型，列的小数秒精度。 +- `character_set_name`：字符串列的字符集的名称。 +- `collation_name`：字符串列的排序规则的名称。 +- `column_key`：列的键类型。可以是以下之一：`PRI`、`TIME INDEX` 或空字符串。 +- `extra`：关于列的附加信息。 +- `privileges`：当前用户对该列的权限。 +- `generation_expression`：对于生成的列，此值显示用于计算列值的表达式。对于非生成的列，该值为空。 +- `greptime_data_type`：列的 GreptimeDB [数据类型](/reference/sql/data-types.md)。 +- `data_type`：列中的数据类型。 +- `semantic_type`：列的类型。可以是以下之一：`TAG`、`FIELD` 或 `TIMESTAMP`。 +- `column_default`：列的默认值。如果默认值被明确设定为 `NULL`，或者列定义中不包含 `default` 子句，则该值为 `NULL`。 +- `is_nullable`：列是否可为空。如果列可以存储空值，则该值为 `YES`；否则，为 `NO`。 +- `column_type`：列的数据类型。与 `DATA_TYPE` 列相同。 +- `column_comment`：列定义中包含的注释。 +- `srs_id`：列的空间参考系统（SRS）的 ID。 + +相应的 `SHOW` 语句如下： + +```sql +SHOW COLUMNS FROM t1 FROM public; +``` + +结果如下： + +```sql ++-------+--------------+------+------------+---------------------+-------+----------------------+ +| Field | Type | Null | Key | Default | Extra | Greptime_type | ++-------+--------------+------+------------+---------------------+-------+----------------------+ +| h | string | Yes | PRI | NULL | | String | +| ts | timestamp(3) | No | TIME INDEX | current_timestamp() | | TimestampMillisecond | +| v | double | Yes | | NULL | | Float64 | ++-------+--------------+------+------------+---------------------+-------+----------------------+ +3 rows in set (0.01 sec) +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/engines.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/engines.md new file mode 100644 index 000000000..53bef8d3c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/engines.md @@ -0,0 +1,50 @@ +--- +description: ENGINES 表提供关于存储引擎的信息，检查 GreptimeDB 是否支持某个存储引擎或查看默认的存储引擎。 +--- + +# ENGINES + +`ENGINES`表提供了关于存储引擎的信息。当你需要检查 GreptimeDB 是否支持某个存储引擎或者查看默认的存储引擎时，该表非常有用。 + +`ENGINES`表包含以下列： + +* `engine`：存储引擎名称。 +* `support`：存储引擎的支持级别： + +|值|含义| +| --- | --- | +| `YES` | 支持且在使用中 | +| `DEFAULT` | 支持且在使用中，且是默认的存储引擎 | +| `NO` | 不支持 | +| `DISABLED` | 支持但已被禁用 | + + +* `comment`：存储引擎的简要描述。 +* `transactions`：存储引擎是否支持事务。 +* `xa`：存储引擎是否支持 XA 事务。 +* `savepoints`：存储引擎是否支持保存点。 + +例如： + +```sql +SELECT * from INFORMATION_SCHEMA.ENGINES\G +``` + +结果如下： + +```sql +*************************** 1. row *************************** + engine: mito + support: DEFAULT + comment: Storage engine for time-series data +transactions: NO + xa: NO + savepoints: NO +*************************** 2. row *************************** + engine: metric + support: YES + comment: Storage engine for observability scenarios, which is adept at handling a large number of small tables, making it particularly suitable for cloud-native monitoring +transactions: NO + xa: NO + savepoints: NO +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/flows.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/flows.md new file mode 100644 index 000000000..3651e9872 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/flows.md @@ -0,0 +1,39 @@ +--- +description: FLOWS 表提供 Flow 任务的相关信息。 +--- + +# FLOWS +`Flows` 表提供了 Flow 任务的相关信息。 + +```sql +DESC TABLE INFORMATION_SCHEMA.FLOWS; +``` + +```sql + Column | Type | Key | Null | Default | Semantic Type +------------------+--------+-----+------+---------+--------------- + flow_name | String | | NO | | FIELD + flow_id | UInt32 | | NO | | FIELD + table_catalog | String | | NO | | FIELD + flow_definition | String | | NO | | FIELD + comment | String | | YES | | FIELD + expire_after | Int64 | | YES | | FIELD + source_table_ids | String | | YES | | FIELD + sink_table_name | String | | NO | | FIELD + flownode_ids | String | | YES | | FIELD + options | String | | YES | | FIELD +(10 rows) +``` + +表中的列： + +* `flow_name`: Flow 任务的名称。 +* `flow_id`: Flow 任务的 id。 +* `table_catalog`: 该 Flow 所属的目录，命名为 `table_catalog` 以保持与 `INFORMATION_SCHEMA` 标准一致。 +* `flow_definition`: Flow 任务的定义，是用于创建 Flow 任务的 SQL 语句。 +* `comment`: Flow 任务的注释。 +* `expire_after`: Flow 任务的过期时间。 +* `source_table_ids`: Flow 任务的源表 id。 +* `sink_table_name`: Flow 任务的目标表名称。 +* `flownode_ids`: Flow 任务使用的 flownode id。 +* `options`: Flow 任务的其他额外选项。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/key-column-usage.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/key-column-usage.md new file mode 100644 index 000000000..18f6912cd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/key-column-usage.md @@ -0,0 +1,87 @@ +--- +description: KEY_COLUMN_USAGE 表描述列的键约束，例如时间索引键的约束。 +--- + +# KEY_COLUMN_USAGE + +`KEY_COLUMN_USAGE` 表描述列的键约束，例如时间索引键的约束。 + +```sql +USE INFORMATION_SCHEMA; +DESC KEY_COLUMN_USAGE; +``` + +结果如下： + +```sql ++-------------------------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-------------------------------+--------+------+------+---------+---------------+ +| constraint_catalog | String | | NO | | FIELD | +| constraint_schema | String | | NO | | FIELD | +| constraint_name | String | | NO | | FIELD | +| table_catalog | String | | NO | | FIELD | +| real_table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| column_name | String | | NO | | FIELD | +| ordinal_position | UInt32 | | NO | | FIELD | +| position_in_unique_constraint | UInt32 | | YES | | FIELD | +| referenced_table_schema | String | | YES | | FIELD | +| referenced_table_name | String | | YES | | FIELD | +| referenced_column_name | String | | YES | | FIELD | ++-------------------------------+--------+------+------+---------+---------------+ +``` + +```sql +SELECT * FROM key_column_usage WHERE table_schema='public' and table_name='monitor'\G +``` + +```sql +*************************** 1. row *************************** + constraint_catalog: def + constraint_schema: public + constraint_name: TIME INDEX + table_catalog: def + real_table_catalog: greptime + table_schema: public + table_name: monitor + column_name: ts + ordinal_position: 1 +position_in_unique_constraint: NULL + referenced_table_schema: NULL + referenced_table_name: NULL + referenced_column_name: NULL +*************************** 2. row *************************** + constraint_catalog: def + constraint_schema: public + constraint_name: PRIMARY + table_catalog: def + real_table_catalog: greptime + table_schema: public + table_name: monitor + column_name: host + ordinal_position: 1 +position_in_unique_constraint: NULL + referenced_table_schema: NULL + referenced_table_name: NULL + referenced_column_name: NULL +2 rows in set (0.02 sec) +``` + +`KEY_COLUMN_USAGE` 表中列的描述如下： + +- `constraint_catalog`：约束所属的目录名称。该值始终为 `def`。 +- `constraint_schema`：约束所属的数据库名称。 +- `constraint_name`：约束的名称。 +- `table_catalog`：表所属目录的名称。该值始终为 `def`。 +- `real_table_catalog`：表所属目录的真实名称。该值始终为 `greptime`。 +- `table_schema`：表所属的数据库名称。 +- `table_name`：具有约束的表的名称。 +- `column_name`：具有约束的列的名称。 +- `ordinal_position`：列在约束中的位置，而不是在表中的位置。位置编号从 `1` 开始。 +- `position_in_unique_constraint`：唯一约束和主键约束为空。对于外键约束，此列是引用表键的位置。 +- `referenced_table_schema`：约束引用的数据库名称。目前在 GreptimeDB 中，除外键约束外，所有约束中此列的值均为 `NULL`。 +- `referenced_table_name`：约束引用的表名称。目前在 GreptimeDB 中，除外键约束外，所有约束中此列的值均为 `NULL`。 +- `referenced_column_name`：约束引用的列名称。目前在 GreptimeDB 中，除外键约束外，所有约束中此列的值均为 `NULL`。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/overview.md new file mode 100644 index 000000000..c64e92df6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/overview.md @@ -0,0 +1,61 @@ +--- +description: INFORMATION_SCHEMA 提供对系统元数据的访问，例如数据库或表的名称、列的数据类型等。 +--- + +# 概述 + +`INFORMATION_SCHEMA` 提供了对系统元数据的访问，例如数据库或表的名称、列的数据类型等。GreptimeDB 还提供了一些自定义的 `INFORMATION_SCHEMA` 表，用于查询有关 GreptimeDB 系统本身、集群信息和运行时指标等元数据。很多 `INFORMATION_SCHEMA` 表都有对应的 `SHOW` 命令，查询 `INFORMATION_SCHEMA` 的好处是可以在表之间进行连接。 + +`INFORMATION_SCHEMA` 依然有很多工作要做，请跟踪 `INFORMATION_SCHEMA` 的 [issue](https://github.com/GreptimeTeam/greptimedb/issues/2931)。 + +## MySQL 兼容性 + +|表名|描述| +| --- | --- | +| [`CHARACTER_SETS`](./character-sets.md) | 提供了可用字符集的信息。 | +| `CHECK_CONSTRAINTS`| 未实现。返回零行。 | +| [`COLLATIONS`](./collations.md) | 提供了服务器支持的排序规则列表。 | +| [`COLLATION_CHARACTER_SET_APPLICABILITY`](./collation-character-set-applicability.md) | 解释了哪些排序规则适用于哪些字符集。 | +| [`COLUMNS`](./columns.md) | 提供了所有表的列列表。 | +| `COLUMN_PRIVILEGES` | 未实现。返回零行。 | +| `COLUMN_STATISTICS` | 不支持。 | +| [`ENGINES`](./engines.md) | 提供了支持的存储引擎列表。 | +| `EVENTS` | 未实现。返回零行。 | +| `FILES` | 未实现。返回零行。 | +| `GLOBAL_STATUS` | 未实现。返回零行。 | +| `GLOBAL_VARIABLES` | 不支持。 | +| [`KEY_COLUMN_USAGE`](./key-column-usage.md) | 描述了列的关键约束，例如主键和时间索引约束。 | +| `OPTIMIZER_TRACE` | 未实现。返回零行。 | +| `PARAMETERS` | 未实现。返回零行。 | +| [`PARTITIONS`](./partitions.md) | 提供了表分区的列表。 | +| `PLUGINS` | 不支持。| +| `PROCESSLIST` | 不支持。 | +| `PROFILING` | 未实现。返回零行。 | +| `REFERENTIAL_CONSTRAINTS` | 未实现。返回零行。 | +| `ROUTINES` | 未实现。返回零行。 | +| [`SCHEMATA`](./schemata.md) | 提供了类似于 `SHOW DATABASES` 的信息。 | +| `SCHEMA_PRIVILEGES` | 未实现。返回零行。 | +| `SESSION_STATUS` | 未实现。返回零行。 | +| `SESSION_VARIABLES` | 不支持。 | +| `STATISTICS` | 不支持。 | +| [`TABLES`](./tables.md) | 提供了当前用户可见的表列表。类似于 `SHOW TABLES`。 | +| `TABLESPACES` | 不支持。 | +| `TABLE_PRIVILEGES` | 未实现。返回零行。 | +| `TRIGGERS` | 未实现。返回零行。 | +| `USER_ATTRIBUTES` | 不支持。 | +| `USER_PRIVILEGES` | 不支持。| +| `VARIABLES_INFO` | 不支持。 | +| [`VIEWS`](./views.md)| 提供了当前用户可见的视图（View）列表及相关信息。 | +| [`TABLE_CONSTRAINTS`](./table-constraints.md) | 提供了主键、唯一索引和外键的信息。 | + +## GreptimeDB 提供的表 + +|表名|描述| +| --- | --- | +| [`BUILD_INFO`](./build-info.md) | 提供了系统构建的信息。 | +| [`REGION_PEERS`](./region-peers.md) | 提供了表的 Region 存储的详细信息。 | +| [`REGION_STATISTICS`](./region-statistics.md) | 提供 Region 的详细统计信息，例如行数等。 | +| [`RUNTIME_METRICS`](./runtime-metrics.md)| 提供了系统运行时指标。| +| [`CLUSTER_INFO`](./cluster-info.md)| 提供了集群的节点拓扑信息。| +| [`FLOWS`](./flows.md) | 提供 Flow 相关信息。| +| [`PROCEDURE_INFO`](./procedure-info.md) | 提供 Procedure 相关信息。| diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/partitions.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/partitions.md new file mode 100644 index 000000000..f3e1c9926 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/partitions.md @@ -0,0 +1,163 @@ +--- +description: PARTITIONS 表提供关于分区表的信息。 +--- + +# PARTITIONS + +`PARTITIONS` 表提供了关于分区表的信息。 + +```sql +USE INFORMATION_SCHEMA; +DESC PARTITIONS; +``` + +结果如下： + +```sql ++-------------------------------+----------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-------------------------------+----------+------+------+---------+---------------+ +| table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| partition_name | String | | NO | | FIELD | +| subpartition_name | String | | YES | | FIELD | +| partition_ordinal_position | Int64 | | YES | | FIELD | +| subpartition_ordinal_position | Int64 | | YES | | FIELD | +| partition_method | String | | YES | | FIELD | +| subpartition_method | String | | YES | | FIELD | +| partition_expression | String | | YES | | FIELD | +| subpartition_expression | String | | YES | | FIELD | +| partition_description | String | | YES | | FIELD | +| table_rows | Int64 | | YES | | FIELD | +| avg_row_length | Int64 | | YES | | FIELD | +| data_length | Int64 | | YES | | FIELD | +| max_data_length | Int64 | | YES | | FIELD | +| index_length | Int64 | | YES | | FIELD | +| data_free | Int64 | | YES | | FIELD | +| create_time | DateTime | | YES | | FIELD | +| update_time | DateTime | | YES | | FIELD | +| check_time | DateTime | | YES | | FIELD | +| checksum | Int64 | | YES | | FIELD | +| partition_comment | String | | YES | | FIELD | +| nodegroup | String | | YES | | FIELD | +| tablespace_name | String | | YES | | FIELD | +| greptime_partition_id | UInt64 | | YES | | FIELD | ++-------------------------------+----------+------+------+---------+---------------+ +26 rows in set (0.01 sec) +``` + +主要列包括： +* `table_catalog`：表所属目录的名称。该值始终为 `def`。 +* `table_schema`：表所属的 schema（数据库）的名称。 +* `table_name`：包含分区（region）的表的名称。 +* `partition_name`：分区（region）的名称。 +* `partition_ordinal_position`：所有分区按照定义的顺序进行索引，1 是分配给第一个分区的编号。 +* `partition_method`：该值始终为 `RANGE`，GreptimeDB 仅支持范围分区。 +* `partition_expression`：该分区的表达式。 +* `create_time`：分区创建的时间。 +* `greptime_partition_id`：GreptimeDB 扩展字段，也就是 Region Id。 + +创建一张分区表并查询： + +```sql +CREATE TABLE public.test_p ( + a INT PRIMARY KEY, + b STRING, + ts TIMESTAMP TIME INDEX, +) +PARTITION ON COLUMNS (a) ( + a < 10, + a >= 10 AND a < 20, + a >= 20 +); + +--- 查询表的分区信息--- +SELECT * FROM PARTITIONS WHERE table_schema='public' AND table_name='test_p'\G +``` + +示例输出如下： + +```sql +*************************** 1. row *************************** + table_catalog: greptime + table_schema: public + table_name: test_p + partition_name: p0 + subpartition_name: NULL + partition_ordinal_position: 1 +subpartition_ordinal_position: NULL + partition_method: RANGE + subpartition_method: NULL + partition_expression: (a) VALUES LESS THAN (PartitionExpr { lhs: Column("a"), op: Lt, rhs: Value(Int32(10)) }) + subpartition_expression: NULL + partition_description: NULL + table_rows: NULL + avg_row_length: NULL + data_length: NULL + max_data_length: NULL + index_length: NULL + data_free: NULL + create_time: 2024-04-01 10:49:49.468000 + update_time: NULL + check_time: NULL + checksum: NULL + partition_comment: NULL + nodegroup: NULL + tablespace_name: NULL + greptime_partition_id: 4453881085952 +*************************** 2. row *************************** + table_catalog: greptime + table_schema: public + table_name: test_p + partition_name: p1 + subpartition_name: NULL + partition_ordinal_position: 2 +subpartition_ordinal_position: NULL + partition_method: RANGE + subpartition_method: NULL + partition_expression: (a) VALUES LESS THAN (PartitionExpr { lhs: Column("a"), op: GtEq, rhs: Value(Int32(20)) }) + subpartition_expression: NULL + partition_description: NULL + table_rows: NULL + avg_row_length: NULL + data_length: NULL + max_data_length: NULL + index_length: NULL + data_free: NULL + create_time: 2024-04-01 10:49:49.468000 + update_time: NULL + check_time: NULL + checksum: NULL + partition_comment: NULL + nodegroup: NULL + tablespace_name: NULL + greptime_partition_id: 4453881085954 +*************************** 3. row *************************** + table_catalog: greptime + table_schema: public + table_name: test_p + partition_name: p2 + subpartition_name: NULL + partition_ordinal_position: 3 +subpartition_ordinal_position: NULL + partition_method: RANGE + subpartition_method: NULL + partition_expression: (a) VALUES LESS THAN (PartitionExpr { lhs: Expr(PartitionExpr { lhs: Column("a"), op: Gt, rhs: Value(Int32(10)) }), op: And, rhs: Expr(PartitionExpr { lhs: Column("a"), op: Lt, rhs: Value(Int32(20)) }) }) + subpartition_expression: NULL + partition_description: NULL + table_rows: NULL + avg_row_length: NULL + data_length: NULL + max_data_length: NULL + index_length: NULL + data_free: NULL + create_time: 2024-04-01 10:49:49.468000 + update_time: NULL + check_time: NULL + checksum: NULL + partition_comment: NULL + nodegroup: NULL + tablespace_name: NULL + greptime_partition_id: 4453881085953 +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/procedure-info.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/procedure-info.md new file mode 100644 index 000000000..2a44de145 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/procedure-info.md @@ -0,0 +1,36 @@ +--- +description: PROCEDURE_INFO 表提供各种 Procedure 的详细信息。 +--- + +# PROCEDURE_INFO + +`PROCEDURE_INFO` 表提供了各种 Procedure 的详细信息。 +:::tip NOTE +该表在 [GreptimeCloud](https://greptime.cloud/) 中不可用。 +::: + +```sql +DESC TABLE INFORMATION_SCHEMA.PROCEDURE_INFO; +``` + +```sql ++----------------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++----------------+----------------------+------+------+---------+---------------+ +| procedure_id | String | | NO | | FIELD | +| procedure_type | String | | NO | | FIELD | +| start_time | TimestampMillisecond | | YES | | FIELD | +| end_time | TimestampMillisecond | | YES | | FIELD | +| status | String | | NO | | FIELD | +| lock_keys | String | | YES | | FIELD | ++----------------+----------------------+------+------+---------+---------------+ +``` + +`PROCEDURE_INFO` 表中的字段描述如下： + +- `procedure_id`: Procedure 的 ID。 +- `procedure_type`: Procedure 的类型。 +- `start_time`: Procedure 开始的时间戳。 +- `end_time`: Procedure 结束的时间戳。 +- `status`: Procedure 当前的状态。 +- `lock_keys`: Procedure 锁定的键。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/region-peers.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/region-peers.md new file mode 100644 index 000000000..4f4b7aa6f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/region-peers.md @@ -0,0 +1,43 @@ +--- +description: REGION_PEERS 表显示 GreptimeDB 中单个 Region 节点的详细信息，例如它是 learner 还是 leader。 +--- + +# REGION_PEERS + +`REGION_PEERS` 表显示了 GreptimeDB 中单个 Region 节点的详细信息，例如它是 learner 还是 leader。 + +:::tip 注意 +该表在 [GreptimeCloud](https://greptime.cloud/) 中不可用。 +::: + +```sql +USE INFORMATION_SCHEMA; +DESC REGION_PEERS; +``` + +结果如下： + +```sql ++--------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------+--------+------+------+---------+---------------+ +| region_id | UInt64 | | NO | | FIELD | +| peer_id | UInt64 | | YES | | FIELD | +| peer_addr | String | | YES | | FIELD | +| is_leader | String | | YES | | FIELD | +| status | String | | YES | | FIELD | +| down_seconds | Int64 | | YES | | FIELD | ++--------------+--------+------+------+---------+---------------+ +6 rows in set (0.00 sec) +``` + +`REGION_PEERS` 表中的字段描述如下： + +- `region_id`：Region 的 ID。 +- `peer_id`：Region peer 的 ID。 +- `peer_addr`：peer 的地址。 +- `is_leader`：peer 是否为 leader。 +- `status`：peer 的状态，`ALIVE` 或 `DOWNGRADED`。 + - `ALIVE`：peer 在线。 + - `DOWNGRADED`：Region peer 不可用（例如，已崩溃、网络断开），或者计划将 Region peer 迁移到另一个 peer。 +- `down_seconds`：离线时长，单位为秒。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/region-statistics.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/region-statistics.md new file mode 100644 index 000000000..fbdb86ae6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/region-statistics.md @@ -0,0 +1,66 @@ +--- +description: REGION_STATISTICS 表提供关于某个 Region 统计信息的详细数据，包括总行数、磁盘大小等。 +--- + +# REGION_STATISTICS + +`REGION_STATISTICS` 表提供了关于某个 Region 统计信息的详细数据，包括总行数、磁盘大小等。这些统计信息都是近似值。 + +:::tip NOTE +此表在 [GreptimeCloud](https://greptime.cloud/) 中不可用。 +::: + +```sql +USE INFORMATION_SCHEMA; +DESC REGION_STATISTICS; +``` + +输出如下： + +```sql ++---------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++---------------+--------+------+------+---------+---------------+ +| region_id | UInt64 | | NO | | FIELD | +| table_id | UInt32 | | NO | | FIELD | +| region_number | UInt32 | | NO | | FIELD | +| region_rows | UInt64 | | YES | | FIELD | +| disk_size | UInt64 | | YES | | FIELD | +| memtable_size | UInt64 | | YES | | FIELD | +| manifest_size | UInt64 | | YES | | FIELD | +| sst_size | UInt64 | | YES | | FIELD | +| index_size | UInt64 | | YES | | FIELD | +| engine | String | | YES | | FIELD | +| region_role | String | | YES | | FIELD | ++---------------+--------+------+------+---------+---------------+ +``` + +`REGION_STATISTICS` 表中的字段描述如下： + +- `region_id`: Region 的 ID。 +- `table_id`: 表的 ID。 +- `region_number`: Region 在表中的编号。 +- `region_rows`: Region 中的记录行数。 +- `disk_size`: Region 中数据文件的总大小，包括数据、索引及元信息等。 +- `memtable_size`: Region 中内存 memtables 的总大小。 +- `manifest_size`: Region 中元信息 manifest 文件的总大小。 +- `sst_size`: Region 中 SST 文件的总大小。 +- `index_size`: Region 中索引文件的总大小。 +- `engine`: Region 的引擎类型，可以是 `mito` 或 `metric`。 +- `region_role`: Region 的角色，可以是 `Leader` 或 `Follower`。 + +获取某张表的 Region 统计信息如下： + +```sql +SELECT r.* FROM REGION_STATISTICS r LEFT JOIN TABLES t on r.table_id = t.table_id \ +WHERE t.table_name = 'system_metrics'; +``` + +输出： +```sql ++---------------+----------+---------------+-------------+-----------+---------------+---------------+----------+------------+--------+-------------+ +| region_id | table_id | region_number | region_rows | disk_size | memtable_size | manifest_size | sst_size | index_size | engine | region_role | ++---------------+----------+---------------+-------------+-----------+---------------+---------------+----------+------------+--------+-------------+ +| 4398046511104 | 1024 | 0 | 8 | 4922 | 0 | 1338 | 3249 | 335 | mito | Leader | ++---------------+----------+---------------+-------------+-----------+---------------+---------------+----------+------------+--------+-------------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/runtime-metrics.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/runtime-metrics.md new file mode 100644 index 000000000..fb7e526e0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/runtime-metrics.md @@ -0,0 +1,57 @@ +--- +description: RUNTIME_METRICS 表提供系统运行时指标，包括集群中 `/metrics` HTTP 端点输出的所有指标。 +--- + +# RUNTIME_METRICS + +`RUNTIME_METRICS`表提供系统运行时指标。它包括集群中`/metrics` HTTP端点输出的所有指标。 + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM RUNTIME_METRICS; +``` + +结果如下： + +```sql ++------------------------------------------------------+------------------------+--------------------------------------------------------+---------+-----------+----------------------------+ +| metric_name | value | labels | node | node_type | timestamp | ++------------------------------------------------------+------------------------+--------------------------------------------------------+---------+-----------+----------------------------+ +| greptime_app_version | 1 | short_version=0.7.1, version=greptimedb-main-92a8e86 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_catalog_catalog_count | 1 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_catalog_schema_count | 2 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.005 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.01 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.025 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.05 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.1 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.25 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.5 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=1 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=2.5 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=5 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=10 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=+Inf | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_sum | 0.000290333 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_count | 1 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_counter | 1 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.005 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.01 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.025 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.05 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.1 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.25 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.5 | unknown | unknown | 2024-03-27 22:43:12.898000 | + +... +``` + +结果中的列： + +* `metric_name`：指标名称。 +* `value`：指标值。 +* `labels`：指标标签和值，用`,`分隔。 +* `node:` 指标来自哪个节点 +* `node_type`：节点类型，如`datanode`、`frontend`等。 +* `timestamp`：指标时间戳 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/schemata.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/schemata.md new file mode 100644 index 000000000..3f05b826e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/schemata.md @@ -0,0 +1,51 @@ +--- +description: SCHEMATA 表提供数据库的相关信息及其字段描述。 +--- + +# SCHEMATA + +`SCHEMATA` 表提供数据库的相关信息。表数据等同于 `SHOW DATABASES` 语句的结果。 + +```sql +USE INFORMATION_SCHEMA; +DESC SCHEMATA; +``` + +结果如下： + +```sql ++----------------------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++----------------------------+--------+------+------+---------+---------------+ +| catalog_name | String | | NO | | FIELD | +| schema_name | String | | NO | | FIELD | +| default_character_set_name | String | | NO | | FIELD | +| default_collation_name | String | | NO | | FIELD | +| sql_path | String | | YES | | FIELD | +| options | String | | YES | | FIELD | ++----------------------------+--------+------+------+---------+---------------+ +``` + +```sql +SELECT * FROM SCHEMATA; +``` + +```sql ++--------------+--------------------+----------------------------+------------------------+----------+-------------+ +| catalog_name | schema_name | default_character_set_name | default_collation_name | sql_path | options | ++--------------+--------------------+----------------------------+------------------------+----------+-------------+ +| greptime | greptime_private | utf8 | utf8_bin | NULL | | +| greptime | information_schema | utf8 | utf8_bin | NULL | | +| greptime | public | utf8 | utf8_bin | NULL | | +| greptime | test | utf8 | utf8_bin | NULL | ttl='7days' | ++--------------+--------------------+----------------------------+------------------------+----------+-------------+ +``` + +`SCHEMATA` 表中的字段描述如下： + +- `catalog_name`：数据库所属的目录。 +- `schema_name`：数据库的名称。 +- `default_character_set_name`：数据库的默认字符集。 +- `default_collation_name`：数据库的默认排序规则。 +- `sql_path`：该项的值始终为 `NULL`。 +- `options`: GreptimeDB 扩展字段，数据库的配置参数。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/table-constraints.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/table-constraints.md new file mode 100644 index 000000000..93325cba2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/table-constraints.md @@ -0,0 +1,59 @@ +--- +description: TABLE_CONSTRAINTS 表描述了哪些表具有约束及相关信息。 +--- + +# TABLE_CONSTRAINTS + +`TABLE_CONSTRAINTS` 表描述了哪些表具有约束（constraint）以及相关信息。 + +```sql +DESC INFORMATION_SCHEMA.table_constraints; +``` + +```sql ++--------------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+--------+------+------+---------+---------------+ +| constraint_catalog | String | | NO | | FIELD | +| constraint_schema | String | | NO | | FIELD | +| constraint_name | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| constraint_type | String | | NO | | FIELD | +| enforced | String | | NO | | FIELD | ++--------------------+--------+------+------+---------+---------------+ +``` + +表中的列： + +* `CONSTRAINT_CATALOG`: 约束所属 catalog 的名称。此值始终为 `def`。 +* `CONSTRAINT_SCHEMA`: 约束所属数据库的名称。 +* `CONSTRAINT_NAME`: 约束的名称，可以是 `TIME INDEX` 或 `PRIMARY`。 +* `TABLE_NAME`: 表的名称。 +* `CONSTRAINT_TYPE`: 约束的类型。值可以是 `TIME INDEX` 或 `PRIMARY KEY`。`TIME INDEX` 和 `PRIMARY KEY` 信息类似于 `SHOW INDEX` 语句的执行结果。 +* `enforced`: 不支持 `CHECK` 约束，此值始终为 `YES`。 + +```sql +select * from INFORMATION_SCHEMA.table_constraints WHERE table_name = 'monitor'\G; +``` + +输出结果： + +```sql +*************************** 1. row *************************** +constraint_catalog: def + constraint_schema: public + constraint_name: TIME INDEX + table_schema: public + table_name: monitor + constraint_type: TIME INDEX + enforced: YES +*************************** 2. row *************************** +constraint_catalog: def + constraint_schema: public + constraint_name: PRIMARY + table_schema: public + table_name: monitor + constraint_type: PRIMARY KEY + enforced: YES +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/tables.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/tables.md new file mode 100644 index 000000000..65edfb1ff --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/tables.md @@ -0,0 +1,113 @@ +--- +description: TABLES 表提供数据库中表的信息及其字段描述。 +--- + +# TABLES + +`TABLES` 表提供数据库中表的信息： + +```sql +USE INFORMATION_SCHEMA; +DESC TABLES; +``` + +结果如下： + +```sql ++------------------+----------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++------------------+----------+------+------+---------+---------------+ +| table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| table_type | String | | NO | | FIELD | +| table_id | UInt32 | | YES | | FIELD | +| data_length | UInt64 | | YES | | FIELD | +| max_data_length | UInt64 | | YES | | FIELD | +| index_length | UInt64 | | YES | | FIELD | +| max_index_length | UInt64 | | YES | | FIELD | +| avg_row_length | UInt64 | | YES | | FIELD | +| engine | String | | YES | | FIELD | +| version | UInt64 | | YES | | FIELD | +| row_format | String | | YES | | FIELD | +| table_rows | UInt64 | | YES | | FIELD | +| data_free | UInt64 | | YES | | FIELD | +| auto_increment | UInt64 | | YES | | FIELD | +| create_time | DateTime | | YES | | FIELD | +| update_time | DateTime | | YES | | FIELD | +| check_time | DateTime | | YES | | FIELD | +| table_collation | String | | YES | | FIELD | +| checksum | UInt64 | | YES | | FIELD | +| create_options | String | | YES | | FIELD | +| table_comment | String | | YES | | FIELD | +| temporary | String | | YES | | FIELD | ++------------------+----------+------+------+---------+---------------+ +``` + +```sql +SELECT * FROM tables WHERE table_schema='public' AND table_name='monitor'\G +``` + +```sql +*************************** 1. row *************************** + table_catalog: greptime + table_schema: public + table_name: monitor + table_type: BASE TABLE + table_id: 1054 + data_length: 0 + max_data_length: 0 + index_length: 0 +max_index_length: 0 + avg_row_length: 0 + engine: mito + version: 11 + row_format: Fixed + table_rows: 0 + data_free: 0 + auto_increment: 0 + create_time: 2024-07-24 22:06:18.085000 + update_time: NULL + check_time: NULL + table_collation: NULL + checksum: 0 + create_options: + table_comment: NULL + temporary: N +1 row in set (0.01 sec) +``` + + +下方的语句是等价的： + +```sql +SELECT table_name FROM INFORMATION_SCHEMA.TABLES + WHERE table_schema = '' + [AND table_name LIKE 'monitor'] + +SHOW TABLES + FROM db_name + [LIKE 'monitor'] +``` + +`TABLES` 表的字段描述如下： + +- `table_catalog`：表所属的目录。该值始终为 `greptime`。 +- `table_schema`：表所属的数据库。 +- `table_name`：表的名称。 +- `table_type`：表的类型。 + - `BASE TABLE`：基础表 + - `TEMPORARY`：临时结果集 + - `VIEW`：视图表 +- `table_id`：表 ID。 +- `data_length`: 表中 SST 文件的总长度（以字节为单位），近似值。 +- `index_length`: 表中索引文件的总长度（以字节为单位），近似值。 +- `table_rows`: 表中总的记录行数，近似值。 +- `avg_row_length`: 表中记录的平均大小（以字节为单位），近似值。 +- `engine`：该表使用的存储引擎。 +- `version`: 版本。固定值为 `11`。 +- `create_time`: 表创建的时间戳。 +- `table_comment`: 表的注释。 +- 其他列如 `table_rows`， `row_format` 等不支持，仅用于兼容 MySQL。GreptimeDB 未来可能会支持其中的一些列。 + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/views.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/views.md new file mode 100644 index 000000000..586847d47 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/information-schema/views.md @@ -0,0 +1,41 @@ +--- +description: VIEWS 表提供当前用户可见的视图列表及其字段描述。 +--- + +# VIEWS + +`VIEWS` 表提供了当前用户可见的视图（View）列表。 + +```sql +DESC TABLE INFORMATION_SCHEMA.VIEWS; +``` + +```sql ++----------------------+---------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++----------------------+---------+------+------+---------+---------------+ +| table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| view_definition | String | | NO | | FIELD | +| check_option | String | | YES | | FIELD | +| is_updatable | Boolean | | YES | | FIELD | +| definer | String | | YES | | FIELD | +| security_type | String | | YES | | FIELD | +| character_set_client | String | | YES | | FIELD | +| collation_connection | String | | YES | | FIELD | ++----------------------+---------+------+------+---------+---------------+ +``` + +表中的列： + +* `table_catalog`: 视图所属 catalog 的名称。 +* `table_schema`: 视图所属数据库的名称。 +* `table_name`: 视图名称。 +* `view_definition`: 视图的定义，即创建视图时的 `SELECT` 语句。 +* `check_option`: 不支持，始终为 `NULL`。 +* `is_updatable`: 视图是否可以进行 `UPDATE/INSERT/DELETE` 操作，始终为 `NO`。 +* `definer`: 创建视图的用户的名称。 +* `security_type`: 不支持，始终为 `NULL`。 +* `character_set_client`: 创建视图时 `character_set_client` 会话变量的值，始终为 `utf8`。 +* `collation_connection`: 创建视图时 `collation_connection` 会话变量的值，始终为 `utf8_bin`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/insert.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/insert.md new file mode 100644 index 000000000..2c3996d25 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/insert.md @@ -0,0 +1,133 @@ +--- +description: INSERT 用于将一条或多条记录插入到 GreptimeDB 中的表中，支持指定列名和使用默认值。 +--- + +# INSERT + +`INSERT` 用于将一条或多条记录插入到 GreptimeDB 中的表中。 + +## `INSERT INTO` Statement + +### Syntax + +`INSERT INTO` 语法如下： + +```sql +INSERT INTO table_name (column1, column2, column3, ...) +VALUES (value1, value2, value3, ...); +``` + +在上述语法中，`table_name` 是要插入数据的表名，`column1`、`column2`、`column3` 等是表中的列名。 +如果你想要插入数据到指定的列中，可以在 `INSERT INTO` 语句中指定列名。 +如果你不指定列名，数据将会插入到表中的所有列中。 + +`VALUES` 关键字后面跟着的是一个值列表，这个值列表的顺序必须和 `INSERT INTO` 语句中的列顺序一致。 + +VALUES 值支持以下数据类型： + +- `DEFAULT` 关键字指定该列的默认值。 +这在你不想在插入记录时显式指定某些列的值时非常有用。 +它允许使用表 schema 中定义的列默认值来替代需要显示指定的值。 +如果该列没有定义默认值，将会使用数据库的默认值（通常是 NULL）。 +- 使用十六进制字面值插入二进制字面值。 +- 使用 `{Value}::{Type}` 语法将特殊的数值 `Infinity`、`-Infinity` 和 `NaN` 转换为指定的数值类型。 + +### 示例 + +#### 插入数据 + +使用 `INSERT INTO` 语句将一条记录插入到名为 `system_metrics` 的表中： + +```sql +INSERT INTO system_metrics (host, idc, cpu_util, memory_util, disk_util, ts) +VALUES + ("host1", "idc_b", 50.0, 66.7, 40.6, 1667446797462); +``` + +上述语句将一条记录插入到 `system_metrics` 表中，该记录的 host 为 "host1"，idc 为 "idc_b"，cpu_util 为 50.0，memory_util 为 66.7， + +你还可以使用 `INSERT INTO` 语句一次向表中插入多条记录，例如向 `system_metrics` 表中插入多条记录： + +```sql +INSERT INTO system_metrics (host, idc, cpu_util, memory_util, disk_util, ts) +VALUES + ("host1", "idc_a", 11.8, 10.3, 10.3, 1667446797460), + ("host2", "idc_a", 80.1, 70.3, 90.0, 1667446797461), + ("host1", "idc_c", 50.1, 66.8, 40.8, 1667446797463); +``` + +此语句将三条记录插入到 `system_metrics` 表中，每列都有指定的值。 + +#### 使用默认值插入数据 + +下面的 SQL 语句使用 `DEFAULT` 关键字为 `cpu_util` 列插入默认值： + +```sql +INSERT INTO system_metrics (host, idc, cpu_util, memory_util, disk_util, ts) +VALUES ("host1", "idc_a", DEFAULT, 10.3, 10.3, 1667446797460); +``` + +#### 插入二进制数据 + +当我们想要插入二进制数据时，其列的数据类型为 `blob` 或 `bytea`： + +```sql +CREATE TABLE test(b BLOB, ts TIMESTAMP TIME INDEX); +``` + +推荐使用预编译语句，例如 JDBC： + +```java + PreparedStatement pstmt = conn.prepareStatement("insert into test values(?,?)"); + pstmt.setBytes(1, "hello".getBytes()); + pstmt.setInt(2, 1687867163); + pstmt.addBatch(); + ...... + pstmt.executeBatch(); +``` + +如果我们想要插入字面值的二进制数据，可以使用十六进制字面值： + +```sql +INSERT INTO test VALUES(X'9fad5e9eefdfb449', 1687867163); +-- or -- +INSERT INTO test VALUES(0x9fad5e9eefdfb449', 1687867163); +``` + +#### 插入特殊数字值 + +使用 `{Value}::{Type}` 将特殊的数值 `Infinity`、`-Infinity` 和 `NaN` 转换为指定的数值类型： + +```sql +INSERT INTO system_metrics (host, idc, cpu_util, memory_util, disk_util, ts) +VALUES ("host1", "idc_a", 66.6, 'NaN'::double, 'Infinity'::double, 1667446797460); +``` + +## `INSERT INTO SELECT` Statement + +`INSERT INTO SELECT` 语句用于将一张表中的数据复制到另一张表中。 + +### Syntax + +`INSERT INTO SELECT` 的语法如下： + +```sql +INSERT INTO table2 (column1, column2, ...) +SELECT column1, column2, ... +FROM table1; +``` + +在上述语法中，`table1` 是你想要从中复制数据的源表，`table2` 是你想要将数据插入的目标表。 +`table1` 和 `table2` 需要有用于复制数据的拥有同样名称和数据类型的列。 +`SELECT` 语句从源表中选择要插入的列。 +如果在`INSERT INTO`语句中没有指定列名，那么数据将被插入到目标表的所有列中。 + +当你想要从一个表中复制数据到另一个表时，`INSERT INTO SELECT` 语句非常有用。例如归档或备份数据时，比起备份整个数据库并恢复，这种方式更加高效。 + +### 示例 + +```sql +INSERT INTO system_metrics2 (host, idc, cpu_util, memory_util, disk_util, ts) +SELECT host, idc, cpu_util, memory_util, disk_util, ts +FROM system_metrics; +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/join.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/join.md new file mode 100644 index 000000000..7d543122c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/join.md @@ -0,0 +1,39 @@ +--- +description: JOIN 用于组合两个或多个表中基于相关列的行，支持 INNER JOIN、LEFT JOIN、RIGHT JOIN 和 FULL OUTER JOIN。 +--- + +# JOIN + +`JOIN` 用于组合两个或多个表中基于相关列的行。 +它允许你从多个表中提取数据，并将其呈现为单个结果集。 + +JOIN 语法有以下类型： + +- INNER JOIN：仅返回两个表中具有匹配值的行。 +- LEFT JOIN：返回左表中的所有行和右表中的匹配行。 +- RIGHT JOIN：返回右表中的所有行和左表中的匹配行。 +- FULL OUTER JOIN：返回两个表中的所有行。 + +## 示例 + +下面是使用 JOIN 子句的一些示例： + +```sql +-- Select all rows from the system_metrics table and idc_info table where the idc_id matches +SELECT a.* +FROM system_metrics a +JOIN idc_info b +ON a.idc = b.idc_id; + +-- Select all rows from the idc_info table and system_metrics table where the idc_id matches, and include null values for idc_info without any matching system_metrics +SELECT a.* +FROM idc_info a +LEFT JOIN system_metrics b +ON a.idc_id = b.idc; + +-- Select all rows from the system_metrics table and idc_info table where the idc_id matches, and include null values for idc_info without any matching system_metrics +SELECT b.* +FROM system_metrics a +RIGHT JOIN idc_info b +ON a.idc = b.idc_id; +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/limit.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/limit.md new file mode 100644 index 000000000..2a1f7931c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/limit.md @@ -0,0 +1,85 @@ +--- +description: 介绍了 `LIMIT` 子句的用法，通过示例展示了如何限制查询返回的行数。 +--- + +# LIMIT + +`LIMIT` 用于限制查询返回的行数。当处理大数据集时该子句特别有用，因为它通过减少需要处理的数据量来提高查询性能。 + +## Syntax + +`LIMIT` 的基本语法如下： + +```sql +SELECT column1, column2, ... +FROM table_name +LIMIT number_of_rows; +``` + +`number_of_rows` 参数用于指定要返回的最大行数。如果该参数的值为负数，则不返回任何行。 + +## 示例 + +假如我们有一个名为 `system_metrics` 的表： + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` + +使用 `LIMIT` 获取 `memory_util` 列中的前 3 个值： + +```sql +SELECT host, idc, memory_util +FROM system_metrics +ORDER BY memory_util DESC +LIMIT 3; +``` + +结果为： + +```sql ++-------+-------+-------------+ +| host | idc | memory_util | ++-------+-------+-------------+ +| host2 | idc_a | 70.3 | +| host1 | idc_c | 66.8 | +| host1 | idc_b | 66.7 | ++-------+-------+-------------+ +``` + +`LIMIT n, m` 允许在跳过前 n 行后从结果中选择 m 行，等价于`LIMIT m OFFSET n` 语法。 + +```sql +SELECT host, idc, memory_util +FROM system_metrics +ORDER BY memory_util DESC +LIMIT 2 OFFSET 1; +``` + +或 + +```sql +SELECT host, idc, memory_util +FROM system_metrics +ORDER BY memory_util DESC +LIMIT 1, 2; +``` + +结果如下： + +```sql ++-------+-------+-------------+ +| host | idc | memory_util | ++-------+-------+-------------+ +| host1 | idc_c | 66.8 | +| host1 | idc_b | 66.7 | ++-------+-------+-------------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/order_by.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/order_by.md new file mode 100644 index 000000000..75b498a33 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/order_by.md @@ -0,0 +1,77 @@ +--- +description: 介绍了 `ORDER BY` 语法的基本用法，通过示例展示了如何对数据进行升序或降序排序。 +--- + +# ORDER BY + +`ORDER BY` 语法用于根据 `SELECT` 语句中的一个或多个列对数据进行升序或降序排序。 + +# Syntax + +`ORDER BY` 的基本语法如下： + +```sql +SELECT column1, column2, ... +FROM table_name +ORDER BY column1 [ASC | DESC], column2 [ASC | DESC], ...; +``` + +`ORDER BY` 可以用于一个或多个列。ASC 关键字用于升序排序（默认），DESC 关键字用于降序排序。 + +# 示例 + +假如我们有一个名为 `system_metrics` 的表： + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` + +要根据 `memory_util` 列对数据进行升序排序，可以使用以下 SQL 语句： + +```sql +SELECT * FROM system_metrics +ORDER BY memory_util ASC; +``` + +结果为： + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` + +要根据 `disk_util` 列对数据进行降序排序，可以使用以下 SQL 语句： + +```sql +SELECT * FROM system_metrics +ORDER BY disk_util DESC; +``` + +结果为： + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/overview.md new file mode 100644 index 000000000..8d5fa9fc7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/overview.md @@ -0,0 +1,28 @@ +# 概述 + +* [数据类型](./data-types) +* [INSERT](./insert.md) +* [CAST](./cast.md) +* [COPY](./copy.md) +* [DROP](./drop.md) +* [SELECT](./select.md) +* [DISTINCT](./distinct.md) +* [WHERE](./where.md) +* [ORDER BY](./order_by.md) +* [GROUP BY](./group_by.md) +* [LIMIT](./limit.md) +* [JOIN](./join.md) +* [RANGE](./range.md) +* [DELETE](./delete.md) +* [SHOW](./show.md) +* [TQL](./tql.md) +* [TRUNCATE](./truncate.md) +* [CREATE](./create.md) +* [DESCRIBE TABLE](./describe_table.md) +* [WITH](./with.md) +* [ALTER](./alter.md) +* [EXPLAIN](./explain.md) +* [Functions](./functions/overview.md) +* [ADMIN](./admin.md) +* [ANSI Compatibility](./compatibility.md) +* [INFORMATION_SCHEMA](./information-schema/overview.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/range.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/range.md new file mode 100644 index 000000000..0ecccc745 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/range.md @@ -0,0 +1,602 @@ +--- +description: 介绍了 Range 查询的语法和用法，包括 `FILL`、`TO` 和 `BY` 选项的详细说明和示例。 +--- + +# RANGE QUERY + +查询并聚合一个给定长度的时间范围的数据是时序数据常见的一种查询模式，例如 `PromQL` 中的 `Range selector`。而 GreptimeDB 在 SQL 中支持了 Range 查询，用于将时序数据汇总为时间块，并在时间块上进行数据的聚合。Range 查询作为 `SELECT` 语句的一部分，可与 SQL 灵活结合，从而在 SQL 中提供更强大的时序数据查询能力。 + +## Syntax + +Range query 使用 `Time Index` 列作为聚合的时间线。 +一个合法的 Range 查询语法结构如下所示： + +```sql +SELECT + AGGR_FUNCTION(column1, column2,..) RANGE INTERVAL [FILL FILL_OPTION], + ... +FROM table_name + [ WHERE ] +ALIGN INTERVAL [ TO TO_OPTION ] [BY (columna, columnb,..)] [FILL FILL_OPTION] + [ ORDER BY ] +[ LIMIT ]; + +INTERVAL := TIME_INTERVAL | ( INTERVAL expr ) +``` + +- 关键字 `ALIGN`，必选字段，后接参数 `INTERVAL` ，`ALIGN` 指明了 Range 查询的步长。 + - 子关键字 `TO` ，可选字段，指定 Range 查询对齐到的时间点，合法的 `TO_OPTION` 参数见[TO Option](#to-option) 。 + - 子关键字 `BY` ，可选字段，后接参数 `(columna, columnb,..)` ，描述了聚合键。详情请见[BY OPTION](#by-option)。 +- 参数 `INTERVAL` ，主要用于给出一段时间长度，有两种参数形式： + - 基于 `PromQL Time Durations` 格式的字符串（例如：`3h`、`1h30m`）。访问 [Prometheus 文档](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations) 获取该格式更详细的说明。 + - `Interval` 类型，使用 `Interval` 类型需要携带括号,（例如：`(INTERVAL '1 year 3 hours 20 minutes')`）。访问 [Interval](./data-types.md#interval-type) 获取该格式更详细的说明。 +- `AGGR_FUNCTION(column1, column2,..) RANGE INTERVAL [FILL FILL_OPTION]` 称为一个 Range 表达式。 + - `AGGR_FUNCTION(column1, column2,..)` 是一个聚合函数，代表需要聚合的表达式。 + - 关键字 `RANGE`，必选字段，后接参数 `INTERVAL` 指定了每次数据聚合的时间范围， + - 关键字 `FILL`，可选字段，详情请见 [`FILL` Option](#fill-option)。 + - Range 表达式可与其他运算结合，实现更复杂的查询。具体见[嵌套使用 Range 表达式](#嵌套使用-range-表达式) 。 +- 关键字 `FILL`，可以跟在一个 Range 表达式后，详情请见[FILL Option](#fill-option) 。 + + +## `FILL` 选项 + +`FILL` 选项指定了在某个聚合的时间片上没有数据，或者聚合字段的值为空时的数据填充方法。 + +它可以跟在一个 Range 表达式后，作为这个 Range 表达式的数据填充方法；也可以放在 `ALIGN` 后面作为所有未指定 `FILL` 选项的 Range 表达式的填充方法。 + +例如，在下面的 SQL 代码中， +`max(val) RANGE '10s'` 范围表达式使用 `FILL` 选项 `LINEAR`，而 `min(val) RANGE '10s'` 没有指定 `FILL` 选项，它将使用在 `ALIGN`关键字之后指定的选项`PREV`。 + +```sql +SELECT + ts, + host, + min(val) RANGE '10s', + max(val) RANGE '10s' FILL LINEAR +FROM host_cpu +ALIGN '5s' BY (host) FILL PREV; +``` +`FILL` 有以下几种选项： + +| FILL | 描述 | +| :------: | :------------------------------------------------------------------------------------------------------------: | +| `NULL` | 直接使用 `NULL` 填充 | +| `PREV` | 使用前一个点的数据填充 | +| `LINEAR` | 使用线性插值法填充数据，如果一个整数类型使用 `LINEAR` 填充，则该列的变量类型会在计算的时候被隐式转换为浮点类型 | +| `X` | 填充一个常量，该常量的数据类型必须和 Range 表达式的变量类型一致 | + +以下面这张表为例 + +```sql ++---------------------+-------+------+ +| ts | host | val | ++---------------------+-------+------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+------+ +``` + +不同 `FILL` 选项的结果如下： + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FROM host ALIGN '5s'; + ++---------------------+-------+------------------------+ +| ts | host | MIN(host.val) RANGE 5s | ++---------------------+-------+------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+------------------------+ + +``` + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FILL NULL FROM host ALIGN '5s'; + ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 5s FILL NULL | ++---------------------+-------+----------------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:05 | host1 | NULL | +| 1970-01-01 00:00:10 | host1 | NULL | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:05 | host2 | NULL | +| 1970-01-01 00:00:10 | host2 | NULL | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+----------------------------------+ + +``` + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FILL PREV FROM host ALIGN '5s'; + ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 5s FILL PREV | ++---------------------+-------+----------------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:05 | host1 | 0 | +| 1970-01-01 00:00:10 | host1 | 0 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:05 | host2 | 6 | +| 1970-01-01 00:00:10 | host2 | 6 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+----------------------------------+ +``` + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FILL LINEAR FROM host ALIGN '5s'; + ++---------------------+-------+------------------------------------+ +| ts | host | MIN(host.val) RANGE 5s FILL LINEAR | ++---------------------+-------+------------------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:05 | host1 | 2 | +| 1970-01-01 00:00:10 | host1 | 4 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:05 | host2 | 8 | +| 1970-01-01 00:00:10 | host2 | 10 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+------------------------------------+ +``` + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FILL 6 FROM host ALIGN '5s'; + ++---------------------+-------+-------------------------------+ +| ts | host | MIN(host.val) RANGE 5s FILL 6 | ++---------------------+-------+-------------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:05 | host1 | 6 | +| 1970-01-01 00:00:10 | host1 | 6 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:05 | host2 | 6 | +| 1970-01-01 00:00:10 | host2 | 6 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+-------------------------------+ +``` + + + + + +注意，如果存在多个 Range 表达式，只对其中的一个表达式使用了 FILL 方法的话，为了保持 SQL 输出行数的统一，其他 Range 表达式会被使用 FILL NULL 方法来填充缺失的时间片段。 +所以下面两句 SQL 在输出上是等价的： + +```sql +SELECT + ts, + host, + min(val) RANGE '10s', + max(val) RANGE '10s' FILL LINEAR +FROM host_cpu +ALIGN '5s'; +``` + +```sql +SELECT + ts, + host, + min(val) RANGE '10s' FILL NULL, + max(val) RANGE '10s' FILL LINEAR +FROM host_cpu +ALIGN '5s'; +``` + +## `TO` 选项 + +`TO` 选项的值用于组确定范围查询的初始时间点。 +`TO` 选项、`RANGE` 选项和 `ALIGN INTERVAL` 共同决定了范围查询的时间窗口。 +请参考[时间范围窗口](/user-guide/query-data/sql.md#时间范围窗口)。 + +`TO` 选项的默认值为当前查询客户端的时区。如果想要设置时区，请参考 [MySQL 客户端](/user-guide/protocols/mysql.md#时区) 或 [PostgreSQL 客户端](/user-guide/protocols/postgresql.md#时区)文档中的时区设置。其他可用的 `TO` 选项有： + +| TO | 描述 | +| :---------: | :----------------------------------------------------------------: | +| `NOW` | 对齐到当前查询时间 | +| `Timestamp` | 对齐到一个用户指定的时间戳上，支持时间戳格式 `RFC3339` / `ISO8601` | + +假设我们有一个名为 `host` 的表有下面这些数据： + +```sql ++---------------------+-------+------+ +| ts | host | val | ++---------------------+-------+------+ +| 2023-01-01 23:00:00 | host1 | 0 | +| 2023-01-02 01:00:00 | host1 | 1 | +| 2023-01-01 23:00:00 | host2 | 2 | +| 2023-01-02 01:00:00 | host2 | 3 | ++---------------------+-------+------+ +``` + +对不同的 `TO` 选项的查询结果如下： + + + + + +```sql + +-- 使用 mysql 协议查询数据库时区，当前处于 UTC 时区 +> SELECT @@time_zone; + ++-------------+ +| @@time_zone | ++-------------+ +| UTC | ++-------------+ + +-- 如果没有指定 `TO` 选项 +-- 会使用当前查询指定的时区作为初始的对齐时间 + +> SELECT ts, host, min(val) RANGE '1d' FROM host ALIGN '1d'; + ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 1d FILL NULL | ++---------------------+-------+----------------------------------+ +| 2023-01-01 00:00:00 | host2 | 2 | +| 2023-01-01 00:00:00 | host1 | 0 | +| 2023-01-02 00:00:00 | host2 | 3 | +| 2023-01-02 00:00:00 | host1 | 1 | ++---------------------+-------+----------------------------------+ +``` + + + + + +```sql + +-- 如果你想要将查询范围的初始时间对齐到当前时间， +-- 可以使用 `NOW` 关键字。 +-- 假如当前的时间为 `2023-01-02T09:16:40.503000`。 + +> SELECT ts, host, min(val) RANGE '1d' FROM host ALIGN '1d' TO NOW; + ++----------------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 1d FILL NULL | ++----------------------------+-------+----------------------------------+ +| 2023-01-01 09:16:40.503000 | host2 | 2 | +| 2023-01-01 09:16:40.503000 | host1 | 0 | ++----------------------------+-------+----------------------------------+ + +``` + + + + + +```sql + +-- 如果你想要将查询范围的初始时间对其到特定的时间戳， +-- 例如北京时间 2023 年 12 月 1 日， +-- 你可以将 `TO` 选项的值设定为特定的时间戳 '2023-01-01T00:00:00+08:00'。 + +SELECT ts, host, min(val) RANGE '1d' FROM host ALIGN '1d' TO '2023-01-01T00:00:00+08:00'; + ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 1d FILL NULL | ++---------------------+-------+----------------------------------+ +| 2023-01-01 16:00:00 | host2 | 2 | +| 2023-01-01 16:00:00 | host1 | 0 | ++---------------------+-------+----------------------------------+ + +``` + + + + + +如果要查询特定时间范围内的数据，也可以使用 `TO` 关键字指定时间戳达到目的。 +例如，要查询 `val` 在 `00:45` 和 `06:45` 之间的每日最小值， +你可以使用 `2023-01-01T00:45:00` 作为 `TO` 选项以及指定 `6h` 的查询范围。 + +```sql +SELECT ts, host, min(val) RANGE '6h' FROM host ALIGN '1d' TO '2023-01-01T00:45:00'; +``` + +```sql ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 6h FILL NULL | ++---------------------+-------+----------------------------------+ +| 2023-01-02 00:45:00 | host1 | 1 | +| 2023-01-02 00:45:00 | host2 | 3 | ++---------------------+-------+----------------------------------+ +``` + +## `BY` 选项 + +`BY` 选项描述聚合键。如果不指定该字段，则默认使用表的主键作为聚合键。如果表没有指定主键，则不能省略 `BY` 关键字。 + +假设我们有一个名为 `host` 的表有以下数据： + +```sql ++---------------------+-------+------+ +| ts | host | val | ++---------------------+-------+------+ +| 2023-01-01 23:00:00 | host1 | 0 | +| 2023-01-02 01:00:00 | host1 | 1 | +| 2023-01-01 23:00:00 | host2 | 2 | +| 2023-01-02 01:00:00 | host2 | 3 | ++---------------------+-------+------+ +``` +下面的 SQL 使用 `host` 作为聚合键： + +```sql +SELECT + ts, + host, + min(val) RANGE '10s' +FROM host ALIGN '5s' BY (host); +``` + +你还可以使用 `BY` 关键字 + +你还可以使用 `BY` 关键字声明其他列作为数据聚合的依据。比如下面这个 RANGE 查询，使用 `host` 列的字符串长度 `length(host)` 作为数据聚合的依据。 + +```sql +SELECT + ts, + length(host), + min(val) RANGE '10s' +FROM host ALIGN '5s' BY (length(host)); +``` + +得到的结果如下： + +```sql ++---------------------+-----------------------------+-----------------------------------+ +| ts | character_length(host.host) | MIN(host.val) RANGE 10s FILL NULL | ++---------------------+-----------------------------+-----------------------------------+ +| 2023-01-01 22:59:55 | 5 | 0 | +| 2023-01-01 23:00:00 | 5 | 0 | +| 2023-01-02 00:59:55 | 5 | 1 | +| 2023-01-02 01:00:00 | 5 | 1 | ++---------------------+-----------------------------+-----------------------------------+ +``` + +你也可以显式通过 `BY ()` 声明不需要使用聚合键，将所有数据全部聚合到一个 group 里。**但如果直接将 `BY` 关键字省略，则代表着使用数据表的主键来作为数据的聚合键。** + +```sql +SELECT + ts, + min(val) RANGE '10s' +FROM host ALIGN '5s' BY (); +``` + +得到的结果如下： + +```sql ++---------------------+-----------------------------------+ +| ts | MIN(host.val) RANGE 10s FILL NULL | ++---------------------+-----------------------------------+ +| 2023-01-01 22:59:55 | 0 | +| 2023-01-01 23:00:00 | 0 | +| 2023-01-02 00:59:55 | 1 | +| 2023-01-02 01:00:00 | 1 | ++---------------------+-----------------------------------+ +``` + +## 聚合函数中的 `ORDER BY` 选项 + +Range 查询支持在聚合函数 `first_value` 和 `last_value` 中使用 `order by` 表达式，默认情况下，聚合函数使用时间索引列升序排列数据。 + +以该数据表为例： + + +```sql ++---------------------+-------+------+-------+ +| ts | host | val | addon | ++---------------------+-------+------+-------+ +| 1970-01-01 00:00:00 | host1 | 0 | 3 | +| 1970-01-01 00:00:01 | host1 | 1 | 2 | +| 1970-01-01 00:00:02 | host1 | 2 | 1 | ++---------------------+-------+------+-------+ +``` + +如果不指定 `order by` 表达式，默认使用 `ts` 列升序排列。 + +```sql +SELECT ts, first_value(val) RANGE '5s', last_value(val) RANGE '5s' FROM host ALIGN '5s'; +-- 等价于 +SELECT ts, first_value(val order by ts ASC) RANGE '5s', last_value(val order by ts ASC) RANGE '5s' FROM host ALIGN '5s'; +``` + +查询后得到 + +```sql ++---------------------+--------------------------------+-------------------------------+ +| ts | FIRST_VALUE(host.val) RANGE 5s | LAST_VALUE(host.val) RANGE 5s | ++---------------------+--------------------------------+-------------------------------+ +| 1970-01-01 00:00:00 | 0 | 2 | ++---------------------+--------------------------------+-------------------------------+ +``` + +也可以自定义排序规则，比如使用 `addon` 排序： + +```sql +SELECT ts, first_value(val ORDER BY addon ASC) RANGE '5s', last_value(val ORDER BY addon ASC) RANGE '5s' FROM host ALIGN '5s'; +``` + +查询后得到 + +```sql ++---------------------+---------------------------------------------------------------------+--------------------------------------------------------------------+ +| ts | FIRST_VALUE(host.val) ORDER BY [host.addon ASC NULLS LAST] RANGE 5s | LAST_VALUE(host.val) ORDER BY [host.addon ASC NULLS LAST] RANGE 5s | ++---------------------+---------------------------------------------------------------------+--------------------------------------------------------------------+ +| 1970-01-01 00:00:00 | 2 | 0 | ++---------------------+---------------------------------------------------------------------+--------------------------------------------------------------------+ +``` + +## 嵌套使用 Range 表达式 + +Range 表达式支持灵活的嵌套，可以将 Range 表达式结合各种运算，提供更强大的查询能力。 + +以下面这张表为例： + +```sql ++---------------------+-------+------+ +| ts | host | val | ++---------------------+-------+------+ +| 2023-01-01 08:00:00 | host1 | 1.1 | +| 2023-01-01 08:00:05 | host1 | 2.2 | +| 2023-01-01 08:00:00 | host2 | 3.3 | +| 2023-01-01 08:00:05 | host2 | 4.4 | ++---------------------+-------+------+ +``` + +1. 聚合函数内部和外部都支持计算： + +```sql +SELECT ts, host, 2.0 * min(val * 2.0) RANGE '10s' FROM host_cpu ALIGN '5s'; +``` + +运行后得到 + +```sql ++---------------------+-------+-----------------------------------------------------------------+ +| ts | host | Float64(2) * MIN(host_cpu.val * Float64(2)) RANGE 10s FILL NULL | ++---------------------+-------+-----------------------------------------------------------------+ +| 2023-01-01 07:59:55 | host1 | 4.4 | +| 2023-01-01 07:59:55 | host2 | 13.2 | +| 2023-01-01 08:00:00 | host1 | 4.4 | +| 2023-01-01 08:00:00 | host2 | 13.2 | +| 2023-01-01 08:00:05 | host1 | 8.8 | +| 2023-01-01 08:00:05 | host2 | 17.6 | ++---------------------+-------+-----------------------------------------------------------------+ +``` + + +2. 聚合函数内部和外部都支持使用 Scalar 函数： + - `min(round(val)) RANGE '10s'` 表示对每个值先使用 `round` 函数四舍五入后再进行聚合 + - `round(min(val) RANGE '10s')` 表示对每个聚合完成的结果使用 `round` 函数四舍五入 + +```sql +SELECT ts, host, min(round(val)) RANGE '10s' FROM host_cpu ALIGN '5s'; +``` +运行后得到 + +```sql ++---------------------+-------+----------------------------------------------+ +| ts | host | MIN(round(host_cpu.val)) RANGE 10s FILL NULL | ++---------------------+-------+----------------------------------------------+ +| 2023-01-01 07:59:55 | host2 | 3 | +| 2023-01-01 07:59:55 | host1 | 1 | +| 2023-01-01 08:00:00 | host2 | 3 | +| 2023-01-01 08:00:00 | host1 | 1 | +| 2023-01-01 08:00:05 | host2 | 4 | +| 2023-01-01 08:00:05 | host1 | 2 | ++---------------------+-------+----------------------------------------------+ +``` + + +```sql +SELECT ts, host, round(min(val) RANGE '10s') FROM host_cpu ALIGN '5s'; +``` + +运行后得到 + +```sql ++---------------------+-------+----------------------------------------------+ +| ts | host | round(MIN(host_cpu.val) RANGE 10s FILL NULL) | ++---------------------+-------+----------------------------------------------+ +| 2023-01-01 07:59:55 | host2 | 3 | +| 2023-01-01 07:59:55 | host1 | 1 | +| 2023-01-01 08:00:00 | host2 | 3 | +| 2023-01-01 08:00:00 | host1 | 1 | +| 2023-01-01 08:00:05 | host2 | 4 | +| 2023-01-01 08:00:05 | host1 | 2 | ++---------------------+-------+----------------------------------------------+ +``` + +3. 多个 Range 表达式也可以相互计算，并且 Range 表达式支持分配律，下面两个表达式都是合法且等价的： + +```sql +SELECT ts, host, max(val) RANGE '10s' - min(val) RANGE '10s' FROM host_cpu ALIGN '5s'; + +SELECT ts, host, (max(val) - min(val)) RANGE '10s' FROM host_cpu ALIGN '5s'; +``` + +运行后得到 + +```sql ++---------------------+-------+-------------------------------------------------------------------------------+ +| ts | host | MAX(host_cpu.val) RANGE 10s FILL NULL - MIN(host_cpu.val) RANGE 10s FILL NULL | ++---------------------+-------+-------------------------------------------------------------------------------+ +| 2023-01-01 08:00:05 | host1 | 0 | +| 2023-01-01 08:00:05 | host2 | 0 | +| 2023-01-01 08:00:00 | host1 | 1.1 | +| 2023-01-01 08:00:00 | host2 | 1.1 | +| 2023-01-01 07:59:55 | host1 | 0 | +| 2023-01-01 07:59:55 | host2 | 0 | ++---------------------+-------+-------------------------------------------------------------------------------+ +``` + +但注意，Range 表达式修饰的范围是位于 `RANGE` 关键字的前一个表达式，下面的 Range 查询是不合法的，因为 `RANGE` 关键字修饰的是表达式 `2.0`，并不是表达式 `min(val * 2.0) * 2.0` + +```sql +SELECT ts, host, min(val * 2.0) * 2.0 RANGE '10s' FROM host_cpu ALIGN '5s'; + +ERROR 1815 (HY000): sql parser error: Can't use the RANGE keyword in Expr 2.0 without function +``` + +可以为表达式加上括号，`RANGE` 关键字会自动应用到括号中包含的所有聚合函数： + +```sql +SELECT ts, host, (min(val * 2.0) * 2.0) RANGE '10s' FROM host_cpu ALIGN '5s'; +``` + +运行后得到： + +```sql ++---------------------+-------+-----------------------------------------------------------------+ +| ts | host | MIN(host_cpu.val * Float64(2)) RANGE 10s FILL NULL * Float64(2) | ++---------------------+-------+-----------------------------------------------------------------+ +| 2023-01-01 07:59:55 | host2 | 13.2 | +| 2023-01-01 07:59:55 | host1 | 4.4 | +| 2023-01-01 08:00:00 | host2 | 13.2 | +| 2023-01-01 08:00:00 | host1 | 4.4 | +| 2023-01-01 08:00:05 | host2 | 17.6 | +| 2023-01-01 08:00:05 | host1 | 8.8 | ++---------------------+-------+-----------------------------------------------------------------+ +``` + +Range 表达式不允许嵌套，嵌套的 Range 查询是不合法的： + +```sql +SELECT ts, host, max(min(val) RANGE '10s') RANGE '10s' FROM host_cpu ALIGN '5s'; + +ERROR 1815 (HY000): Range Query: Nest Range Query is not allowed +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/select.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/select.md new file mode 100644 index 000000000..239ed3dae --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/select.md @@ -0,0 +1,127 @@ +--- +description: 介绍了 `SELECT` 语句的基本语法和用法，包括 `WHERE`、`LIMIT`、`JOIN` 和 `GROUP BY` 子句的示例。 +--- + +# SELECT + +`SELECT` 语句允许你从一个或多个表中选择列。 + +## Basic Syntax + +`SELECT` 的基本语法如下： + +```sql +SELECT column1, column2, ... +FROM table_name; +``` + +column1, column2 是要从中获取数据的列的名称，table_name 是要从中获取数据的表的名称。 + +该语句从 `FROM` 子句中指定的表中选择列。如果要从表中选择所有列，可以使用星号（*）通配符字符，而不是列出单个列名。 + +```sql +SELECT * +FROM table_name; +``` + +## 使用 WHERE 子句过滤 SELECT 语句 + +`WHERE` 子句用于根据指定条件过滤 `SELECT` 语句的结果，其语法如下： + +```sql +SELECT column1, column2, ..., columnN +FROM table_name +WHERE condition; +``` + +其中 `condition` 是一个表达式，它的值为 `true` 或 `false`。只有满足条件的行才会包含在结果集中。 + +## WHERE 子句示例 + +```sql +-- Select all rows from the system_metrics table where idc is 'idc0' +SELECT * +FROM system_metrics +WHERE idc = 'idc0'; + +-- Select all rows from the system_metrics table where the idc is 'idc0' or 'idc0' +SELECT * +FROM system_metrics +WHERE idc IN ('idc0', 'idc1'); +``` + +## 在 SELECT 语句中使用 LIMIT + +`LIMIT` 用于限制查询返回的行数。当处理大数据集时该子句特别有用，因为它通过减少需要处理的数据量来提高查询性能。 + +```sql +SELECT column1, column2, ... +FROM table_name +LIMIT number_of_rows; +``` + +这里 `number_of_rows` 参数用于指定要返回的最大行数。 + +## LIMIT 子句示例 + +```sql +-- Select the first 10 rows from the system_metrics table +SELECT * +FROM system_metrics +LIMIT 10; +``` + +## 在 SELECT 语句中使用 JOIN + +`JOIN` 用于组合两个或多个表中基于相关列的行，使用 `JOIN` 的语法如下： + +```sql +SELECT column1, column2, ... +FROM table1 +JOIN table2 +ON table1.column = table2.column; +``` + +table1 和 table2 是要连接的表的名称，column 是两个表之间的相关列，请参考[JOIN](join.md) 获取更多信息。 + +## 在 SELECT 语句中使用 GROUP BY 子句 + +`GROUP BY` 语句用于对具有一个或多个列中的相同值的行进行分组，其基本语法如下： + +```sql +SELECT column1, column2, ..., aggregate_function(column) +FROM table_name +GROUP BY column1, column2, ...; +``` + +这里 `aggregate_function` 是对一组值执行计算的函数，例如 AVG、COUNT、MAX、MIN 或 SUM。`column` 是要对数据进行分组的列。 + +## GROUP BY 子句示例 + +```sql +-- Select the total number of idc for each idc +SELECT idc, COUNT(host) as host_mun +FROM system_metrics +GROUP BY idc; + +-- Select the idc's average cpu_util +SELECT idc, AVG(cpu_util) as cpu_avg +FROM system_metrics +GROUP BY idc; +``` + +请参考[GROUP BY](group_by.md) 获取更多信息。 + +## RANGE 查询示例 + +```sql +SELECT + ts, + host, + min(cpu) RANGE '10s', + max(cpu) RANGE '10s' FILL LINEAR +FROM host_cpu +ALIGN '5s' BY (host) FILL PREV; +``` + +请参考[RANGE QUERY](range.md) 获取更多信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/show.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/show.md new file mode 100644 index 000000000..01289e5cf --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/show.md @@ -0,0 +1,385 @@ +--- +description: 介绍了 `SHOW` 关键字的各种用法，包括展示数据库、表、视图和索引等信息的语法和示例。 +--- + +# SHOW + +`SHOW` 关键字提供数据库和表信息。 + +## SHOW DATABASES + +展示所有数据库： + +```sql +SHOW [FULL] DATABASES; +``` + +```sql ++---------+ +| Schemas | ++---------+ +| public | ++---------+ +1 row in set (0.01 sec) +``` + +展示名称符合 `LIKE` 模式的数据库： + +```sql +SHOW DATABASES LIKE 'p%'; +``` + +根据 `where` 表达式展示数据库： + +```sql +SHOW DATABASES WHERE Schemas='test_public_schema'; +``` + +展示所有数据库，包括它们的选项： + +```sql +CREATE DATABASE test WITH(ttl='7d'); +SHOW FULL DATABASES; +``` + +```sql ++--------------------+-------------+ +| Database | Options | ++--------------------+-------------+ +| greptime_private | | +| information_schema | | +| public | | +| test | ttl='7days' | ++--------------------+-------------+ +``` + +## SHOW CREATE DATABASE + +展示创建指定数据库的 `CREATE DATABASE` 语句： + +```sql +SHOW CREATE DATABASE test; +``` + +```sql ++----------+------------------------------------------------------------+ +| Database | Create Database | ++----------+------------------------------------------------------------+ +| test | CREATE DATABASE IF NOT EXISTS test +WITH( + ttl = '7days' +) | ++----------+------------------------------------------------------------+ +1 row in set (0.01 sec) +``` + +## SHOW TABLES + +展示所有表： + +```sql +SHOW TABLES; +``` + +```sql ++---------+ +| Tables | ++---------+ +| numbers | +| scripts | ++---------+ +2 rows in set (0.00 sec) +``` + +展示 `test` 数据库中的所有表： + +```sql +SHOW TABLES FROM test; +``` + +展示名称符合 `LIKE` 模式的表： + +```sql +SHOW TABLES like '%prometheus%'; +``` + +根据 `where` 表达式展示表： + +```sql +SHOW TABLES FROM test WHERE Tables='numbers'; +``` + +## SHOW FULL TABLES + +```sql +SHOW FULL TABLES [IN | FROM] [DATABASE] [LIKE pattern] [WHERE query] +``` + +将会展示指定数据库（或者默认 `public`）中所有的表及其类型： + +```sql +SHOW FULL TABLES; +``` + +```sql ++---------+------------+ +| Tables | Table_type | ++---------+------------+ +| monitor | BASE TABLE | +| numbers | TEMPORARY | ++---------+------------+ +2 rows in set (0.00 sec) +``` + +* `Tables`: 表的名称 +* `Table_type`: 表的类型，例如 `BASE_TABLE`, `TEMPORARY` 和 `VIEW` 等等。 + +同样也支持 `like` 和 `where` 查询： + +```sql +SHOW FULL TABLES FROM public like '%mo%'; +``` + +```sql ++---------+------------+ +| Tables | Table_type | ++---------+------------+ +| monitor | BASE TABLE | ++---------+------------+ +1 row in set (0.01 sec) +``` + +```sql +SHOW FULL TABLES WHERE Table_type='BASE TABLE'; +``` + +```sql ++---------+------------+ +| Tables | Table_type | ++---------+------------+ +| monitor | BASE TABLE | ++---------+------------+ +1 row in set (0.01 sec) +``` + +## SHOW CREATE TABLE + +展示创建指定表的 `CREATE TABLE` 语句： + +```sql +SHOW CREATE TABLE [table] +``` + +例如： + +```sql +SHOW CREATE TABLE system_metrics; +``` + +```sql ++----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Table | Create Table | ++----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| system_metrics | CREATE TABLE IF NOT EXISTS `system_metrics` ( + `host` STRING NULL, + `idc` STRING NULL, + `cpu_util` DOUBLE NULL, + `memory_util` DOUBLE NULL, + `disk_util` DOUBLE NULL, + `ts` TIMESTAMP(3) NOT NULL DEFAULT current_timestamp(), + TIME INDEX (`ts`), + PRIMARY KEY (`host`, `idc`) +) + +ENGINE=mito +WITH( + regions = 1 +) | ++----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +* `Table`: 表的名称 +* `Create Table`: 用于创建该表的 SQL + +## SHOW CREATE FLOW + +展示创建指定 Flow 任务的 `CREATE FLOW` 语句。 + +比如： + +```sql +public=> SHOW CREATE FLOW filter_numbers; +``` + +```sql + Flow | Create Flow +----------------+------------------------------------------------------- + filter_numbers | CREATE OR REPLACE FLOW IF NOT EXISTS filter_numbers + + | SINK TO out_num_cnt + + | AS SELECT number FROM numbers_input WHERE number > 10 +(1 row) +``` + +## SHOW FLOWS + +展示当前所有 Flow 任务： + +```sql +public=> SHOW FLOWS; +``` + +```sql + Flows +---------------- + filter_numbers +(1 row) +``` + +同样也支持 `LIKE` 表达式： +```sql +public=> show flows like "filter%"; +``` + +```sql + Flows +---------------- + filter_numbers +(1 row) +``` + +## SHOW CREATE VIEW + +用于显示视图（View）的定义： + +```sql +SHOW CREATE VIEW cpu_monitor; +``` + +``` ++-------------+--------------------------------------------------------------+ +| View | Create View | ++-------------+--------------------------------------------------------------+ +| cpu_monitor | CREATE VIEW cpu_monitor AS SELECT cpu, host, ts FROM monitor | ++-------------+--------------------------------------------------------------+ +``` + +## SHOW VIEWS + +列出所有视图： + +```sql +SHOW VIEWS; +``` + +```sql ++----------------+ +| Views | ++----------------+ +| cpu_monitor | +| memory_monitor | ++----------------+ +``` + +当然，它也支持 `LIKE` 查询： + +```sql +SHOW VIEWS LIKE 'cpu%'; +``` + +```sql ++-------------+ +| Views | ++-------------+ +| cpu_monitor | ++-------------+ +``` + +以及 `WHERE` 条件： + +```sql +SHOW VIEWS WHERE Views = 'memory_monitor'; +``` + +```sql ++----------------+ +| Views | ++----------------+ +| memory_monitor | ++----------------+ +``` + +## SHOW 语句的扩展 + +与 MySQL 类似，一些 `SHOW` 语句的扩展伴随着 [`INFORMATION_SCHEMA`](/reference/sql/information-schema/overview.md) 的实现，它们还接受 `WHERE` 子句，提供了在指定显示的行时更大的灵活性。 + +GreptimeDB 为 MySQL 兼容性实现了这些扩展的一部分，这对于像 [Navicat for MySQL](https://www.navicat.com/en/products/navicat-for-mysql) 或 [dbeaver](https://dbeaver.io/) 这样的工具连接 GreptimeDB 非常有用。 + +```sql +SHOW CHARACTER SET; +``` + +输出类似于 `INFORMATION_SCHEMA.CHARACTER_SETS` 表： + +```sql ++---------+---------------+-------------------+--------+ +| Charset | Description | Default collation | Maxlen | ++---------+---------------+-------------------+--------+ +| utf8 | UTF-8 Unicode | utf8_bin | 4 | ++---------+---------------+-------------------+--------+ +``` + +使用 `SHOW COLLATION` 来查看 `INFORMATION_SCHEMA.COLLATIONS` 表。 + +```sql +SHOW INDEX FROM monitor; +``` + +列出表中的所有索引： + +```sql ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression | ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +| monitor | 1 | PRIMARY | 1 | host | A | NULL | NULL | NULL | YES | greptime-inverted-index-v1 | | | YES | NULL | +| monitor | 1 | TIME INDEX | 1 | ts | A | NULL | NULL | NULL | NO | greptime-inverted-index-v1 | | | YES | NULL | ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +``` + +这是 `INFORMATION_SCHEMA.TABLE_CONSTRAINTS` 的扩展。 + +列出表中的所有列： + +```sql +SHOW COLUMNS FROM monitor; +``` + +输出类似于 `INFORMATION_SCHEMA.COLUMNS`： + +```sql ++--------+--------------+------+------------+---------------------+-------+----------------------+ +| Field | Type | Null | Key | Default | Extra | Greptime_type | ++--------+--------------+------+------------+---------------------+-------+----------------------+ +| cpu | double | Yes | | 0 | | Float64 | +| host | string | Yes | PRI | NULL | | String | +| memory | double | Yes | | NULL | | Float64 | +| ts | timestamp(3) | No | TIME INDEX | current_timestamp() | | TimestampMillisecond | ++--------+--------------+------+------------+---------------------+-------+----------------------+ +``` + +所有这些 `SHOW` 扩展都接受 `WHERE` 子句： + +```sql +SHOW COLUMNS FROM monitor WHERE Field = 'cpu'; +``` + +```sql ++-------+--------+------+------+---------+-------+---------------+ +| Field | Type | Null | Key | Default | Extra | Greptime_type | ++-------+--------+------+------+---------+-------+---------------+ +| cpu | double | Yes | | 0 | | Float64 | ++-------+--------+------+------+---------+-------+---------------+ +``` + +其他 `SHOW` 扩展语句： +* `SHOW STATUS` 和 `SHOW VARIABLES` 不支持，仅返回空结果。 +* `SHOW TABLE STATUS` 是 `INFORMATION_SCHEMA.TABLES` 的扩展。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/tql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/tql.md new file mode 100644 index 000000000..dee5fa417 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/tql.md @@ -0,0 +1,122 @@ +--- +description: 介绍了 `TQL` 关键字及其在 GreptimeDB 中的用法，包括 `EVAL`、`EXPLAIN` 和 `ANALYZE` 的语法和示例。 +--- + +# TQL + +`TQL` 关键字在 SQL 中执行 TQL 语言。TQL 是 Time-Series Query Language 的缩写，是 GreptimeDB 中对 Prometheus 的 [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) 的扩展。 + +## EVAL + +### Syntax + +```sql +TQL [EVAL | EVALUATE] (start, end, step) expr +``` + +`start`, `end` 和 `step` 是查询参数，就像 [Prometheus Query API](https://prometheus.io/docs/prometheus/latest/querying/api/) 一样： + +- `start`: ``: Start 时间戳, 范围中包含该值。 +- `end`: ``: End 时间戳, 范围中包含该值。 +- `step`: ``: 查询分辨率步长，采用 `duration` 格式或浮点秒数。 + +`expr` 是 TQL 表达式查询字符串。 + +### 示例 + +返回过去 5 分钟内 `http_requests_total` 指标的所有时间序列的每秒值： + +```sql +TQL eval (1677057993, 1677058993, '1m') rate(prometheus_http_requests_total{job="prometheus"}[5m]); +``` + +其查询结果和 SQL 查询结果类似。 + +## EXPLAIN + +`EXPLAIN` 展示特定 PromQL 查询的逻辑计划和执行计划，其语法如下： + +``` +TQL EXPLAIN expr; +``` + +例如，我们可以使用下方示例解释 PromQL `sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50`： + +``` +TQL EXPLAIN sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50; +``` + +注意该查询实际上没有被执行，所以 `(start, end, step)` 不是必需的，但你仍然可以像在 `TQL EVAL` 中一样提供这些参数： + +``` +TQL EXPLAIN (0, 100, '10s') sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50; +``` + +结果如下： + +```txt ++---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| plan_type | plan | ++---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| logical_plan | Sort: node_disk_written_bytes_total.instance ASC NULLS LAST, node_disk_written_bytes_total.ts ASC NULLS LAST + Filter: SUM(prom_rate(ts_range,field,ts)) > Float64(50) + Aggregate: groupBy=[[node_disk_written_bytes_total.instance, node_disk_written_bytes_total.ts]], aggr=[[SUM(prom_rate(ts_range,field,ts))]] + Projection: node_disk_written_bytes_total.ts, prom_rate(ts_range, field, node_disk_written_bytes_total.ts) AS prom_rate(ts_range,field,ts), node_disk_written_bytes_total.instance + Filter: prom_rate(ts_range, field, node_disk_written_bytes_total.ts) IS NOT NULL + Projection: node_disk_written_bytes_total.ts, node_disk_written_bytes_total.instance, field, ts_range + PromRangeManipulate: req range=[0..0], interval=[300000], eval range=[120000], time index=[ts], values=["field"] + PromSeriesNormalize: offset=[0], time index=[ts], filter NaN: [true] + PromSeriesDivide: tags=["instance"] + Sort: node_disk_written_bytes_total.instance DESC NULLS LAST, node_disk_written_bytes_total.ts DESC NULLS LAST + TableScan: node_disk_written_bytes_total projection=[ts, instance, field], partial_filters=[ts >= TimestampMillisecond(-420000, None), ts <= TimestampMillisecond(300000, None)] | +| physical_plan | SortPreservingMergeExec: [instance@0 ASC NULLS LAST,ts@1 ASC NULLS LAST] + SortExec: expr=[instance@0 ASC NULLS LAST,ts@1 ASC NULLS LAST] + CoalesceBatchesExec: target_batch_size=8192 + FilterExec: SUM(prom_rate(ts_range,field,ts))@2 > 50 + AggregateExec: mode=FinalPartitioned, gby=[instance@0 as instance, ts@1 as ts], aggr=[SUM(prom_rate(ts_range,field,ts))] + CoalesceBatchesExec: target_batch_size=8192 + RepartitionExec: partitioning=Hash([Column { name: "instance", index: 0 }, Column { name: "ts", index: 1 }], 32), input_partitions=32 + AggregateExec: mode=Partial, gby=[instance@2 as instance, ts@0 as ts], aggr=[SUM(prom_rate(ts_range,field,ts))] + ProjectionExec: expr=[ts@0 as ts, prom_rate(ts_range@3, field@2, ts@0) as prom_rate(ts_range,field,ts), instance@1 as instance] + CoalesceBatchesExec: target_batch_size=8192 + FilterExec: prom_rate(ts_range@3, field@2, ts@0) IS NOT NULL + ProjectionExec: expr=[ts@0 as ts, instance@1 as instance, field@2 as field, ts_range@3 as ts_range] + PromInstantManipulateExec: req range=[0..0], interval=[300000], eval range=[120000], time index=[ts] + PromSeriesNormalizeExec: offset=[0], time index=[ts], filter NaN: [true] + PromSeriesDivideExec: tags=["instance"] + RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=1 + ExecutionPlan(PlaceHolder) + | ++---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +## ANALYZE + +TQL 同样支持 `ANALYZE` 关键词来分析给定 PromQL 查询的执行，其语法如下： + +``` +TQL ANALYZE (start, end, step) expr; +``` + +例如： + +``` +TQL ANALYZE (0, 10, '5s') test; +``` + +得到结果： + +``` ++-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| plan_type | plan | ++-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Plan with Metrics | CoalescePartitionsExec, metrics=[output_rows=0, elapsed_compute=14.99µs] + PromInstantManipulateExec: range=[0..10000], lookback=[300000], interval=[5000], time index=[j], metrics=[output_rows=0, elapsed_compute=1.08µs] + PromSeriesNormalizeExec: offset=[0], time index=[j], filter NaN: [false], metrics=[output_rows=0, elapsed_compute=1.11µs] + PromSeriesDivideExec: tags=["k"], metrics=[output_rows=0, elapsed_compute=1.3µs] + RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=32, metrics=[send_time=32ns, repart_time=32ns, fetch_time=11.578016ms] + RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=1, metrics=[send_time=1ns, repart_time=1ns, fetch_time=21.07µs] + ExecutionPlan(PlaceHolder), metrics=[] + | ++-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/truncate.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/truncate.md new file mode 100644 index 000000000..e27c406f1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/truncate.md @@ -0,0 +1,15 @@ +--- +description: 介绍了 `TRUNCATE TABLE` 语句的用法，用于高效地删除表中的所有数据。 +--- + +# TRUNCATE + +`TRUNCATE TABLE table` 语句用于删除表中的所有数据。它比 `DELETE FROM table` 高效得多。 + +```sql +TRUNCATE TABLE monitor; +``` + +```sql +Query OK, 0 rows affected (0.02 sec) +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/where.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/where.md new file mode 100644 index 000000000..c8c924865 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/where.md @@ -0,0 +1,57 @@ +--- +description: 介绍了 `WHERE` 子句的用法，包括逻辑运算符、数字比较和列表查找的示例。 +--- + +# WHERE + +`WHERE` 子句允许通过指定条件过滤数据。 + +## Syntax + +```sql +SELECT * +FROM table_name +WHERE condition; +``` + +如果有 `WHERE` 子句，则它必须为布尔类型的表达式，这通常是带有比较和逻辑运算符的表达式。此表达式计算结果为 false 的行将会从进一步的转换或结果中排除。 + +## 示例 + +### 逻辑运算符 + +支持 `AND`、`OR` 作为逻辑运算符，并可以使用括号（）组合条件。 + +```sql +SELECT * FROM system_metrics +WHERE idc = 'idc0' AND (host = 'host1' OR host = 'host2'); +``` + +### 数字 + +支持 `=`, `!=`, `>`, `>=`, `<`, `<=` 作为比较运算符。 + +```sql +SELECT * FROM system_metrics WHERE cpu_util = 20.0; +SELECT * FROM system_metrics WHERE cpu_util != 20.0; +SELECT * FROM system_metrics WHERE cpu_util > 20.0; +SELECT * FROM system_metrics WHERE cpu_util >= 20.0; +SELECT * FROM system_metrics WHERE cpu_util < 20.0; +SELECT * FROM system_metrics WHERE cpu_util <= 20.0; +``` + +### List 查找 + +List 子元素的匹配或不匹配。 + +### List 匹配 + +```sql +SELECT * FROM system_metrics WHERE idc IN ('idc_a', 'idc_b'); +``` + +### List 不匹配 + +```sql +SELECT * FROM system_metrics WHERE idc NOT IN ('idc_a', 'idc_b'); +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/with.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/with.md new file mode 100644 index 000000000..755528a47 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/sql/with.md @@ -0,0 +1,88 @@ +--- +description: 介绍了如何使用 `WITH` 关键字定义公共表表达式（CTE），包括基本语法和示例。 +--- + +# WITH + +使用 `WITH` 来指定一个公共表表达式（CTE）。 + +## 什么是公共表表达式（CTE）？ + +公共表表达式（CTE）是一个可以在 `SELECT`、`INSERT`、`UPDATE` 或 `DELETE` 语句中引用的临时结果集。CTE 有助于将复杂的查询分解成更易读的部分，并且可以在同一个查询中多次引用。 + +## CTE 的基本语法 + +CTE 通常使用 `WITH` 关键字定义。基本语法如下： + +```sql +WITH cte_name [(column1, column2, ...)] AS ( + QUERY +) +SELECT ... +FROM cte_name; +``` + +## 示例 + +### 非递归 CTE + +```sql +WITH cte AS (SELECT number FROM numbers LIMIT 2) SELECT * FROM cte t1, cte t2; +``` + +```sql ++--------+--------+ +| number | number | ++--------+--------+ +| 0 | 0 | +| 0 | 1 | +| 1 | 0 | +| 1 | 1 | ++--------+--------+ +``` + +如果 CTE 名称后面有一个括起来的名称列表，这些名称就是 CTE 的列名，可以在查询里使用： + +```sql +WITH cte (col1, col2) AS +( + SELECT 1, 2 + UNION ALL + SELECT 3, 4 +) +SELECT col1, col2 FROM cte; +``` + +列表中的名称数量必须与结果集中的列数相同。 + +```sql ++------+------+ +| col1 | col2 | ++------+------+ +| 1 | 2 | +| 3 | 4 | ++------+------+ +``` + +联合查询两个 CTE： + +```sql +WITH + cte1 AS (SELECT number AS a FROM NUMBERS LIMIT 2), + cte2 AS (SELECT number AS b FROM NUMBERS LIMIT 2) +SELECT * FROM cte1 JOIN cte2 +ON cte1.a = cte2.b; +``` + +```sql ++------+------+ +| a | b | ++------+------+ +| 1 | 1 | +| 0 | 0 | ++------+------+ +``` + +### 递归 CTE + +递归 CTE 目前尚未实现。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/telemetry.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/telemetry.md new file mode 100644 index 000000000..2d5c79229 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/reference/telemetry.md @@ -0,0 +1,52 @@ +--- +description: 介绍 GreptimeDB 的指标收集功能，包括收集的数据类型、如何禁用指标收集等内容。 +--- + +# 指标收集 + +为了提升我们的服务，GreptimeDB 会收集一些数据，包括 GreptimeDB 版本、节点数量、使用的操作系统、环境架构以及类似的技术细节等信息。但是我们尊重您的隐私，并确保不收集任何特定于用户的数据，其中包括数据库名称、表名称、查询内容等。 + +你的体验和隐私是我们的首要任务。你可以根据自己的喜好轻松管理此指标收集，通过配置选择启用或禁用它。 + +## 将会收集哪些数据 + +详细的数据信息可能会随着时间的推移而发生变化，这些更改（如果有）将在发行说明中公布。 + +启用指标收集后，GreptimeDB 将每半小时收集一次以下信息： + +- GreptimeDB 版本 +- GreptimeDB 的构建 git 哈希 +- 运行 GreptimeDB 的设备的操作系统（Linux、macOS 等） +- GreptimeDB 运行的机器架构（x86_64、arm64 等） +- GreptimeDB 运行模式（独立、分布式） +- 随机生成的安装 ID +- GreptimeDB 集群中的 datanode 数量 + +## 如何禁用指标收集 + +从 GreptimeDB v0.4.0 开始，指标收集将默认启用。你可以通过更改配置来禁用它。 + +### 独立模式 + +将独立配置文件中的 `enable_telemetry` 设置为 `false`： + +```toml +# Node running mode, "standalone" or "distributed". +mode = "standalone" +# Whether to enable greptimedb telemetry, true by default. +enable_telemetry = false +``` + +或者在启动时通过环境变量 `GREPTIMEDB_STANDALONE__ENABLE_TELEMETRY=false` 进行配置。 + +### 分布式模式 + +将 metasrv 配置文件中的 `enable_telemetry` 设置为 `false`： + +```toml +# metasrv config file +# Whether to enable greptimedb telemetry, true by default. +enable_telemetry = false +``` + +或者在启动时设置环境变量 `GREPTIMEDB_METASRV__ENABLE_TELEMETRY=false`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/capacity-plan.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/capacity-plan.md new file mode 100644 index 000000000..e00b10c78 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/capacity-plan.md @@ -0,0 +1,70 @@ +--- +description: 提供 GreptimeDB 的 CPU、内存和存储需求的一般建议，帮助用户根据工作负载进行容量规划。 +--- + +# 容量规划 + +本指南提供了关于 GreptimeDB 的 CPU、内存和存储需求的一般建议。 + +GreptimeDB 具备超轻量级的启动基准， +这使数据库能以最少的服务器资源启动。 +然而当为生产环境配置服务器容量时， +以下关键因素需要被考虑： + +- 每秒处理的数据点数 +- 每秒查询请求 +- 数据量 +- 数据保留策略 +- 硬件成本 + +要监控 GreptimeDB 的各种指标，请参阅[监控](/user-guide/administration/monitoring/export-metrics.md)。 + +## CPU + +一般来说，大量并发查询、处理大量数据或执行其他计算密集型操作的应用需要更多的 CPU 核数。 + +以下是一些关于 CPU 资源使用的建议， +但实际使用的 CPU 核数取决于你实际的工作负载。 + +你可以考虑将 30% 的 CPU 资源用于数据写入， +剩余 70% 用于查询和分析。 + +一般推荐 CPU 到内存的比例为 1:4（例如，8 核 32 GB）， +如果你的主要工作负载是数据写入且查询请求较少， +1:2 的比例（8 核 16 GB）也是可以接受的。 + +## 内存 + +一般来说，内存越大，查询速度越快。 +对于基本工作负载，建议至少有 8 GB 的内存，对于更高级的工作负载，建议至少有 32 GB 的内存。 + +## 存储空间 + +GreptimeDB 具有高效的数据压缩机制，可将原始数据大小减少到其初始大小的约 1/8 到 1/10。 +这使得 GreptimeDB 以更小的空间存储大量数据。 + +数据可以存储在本地文件系统或云存储中，例如 AWS S3。 +有关存储选项的更多信息， +请参阅[存储配置](/user-guide/deployments/configuration.md#存储选项)文档。 + +由于云存储在存储管理方面的简单性，强烈推荐使用云存储进行数据存储。 +使用云存储时，本地存储空间只需要大约 200GB 用于查询相关的缓存和 Write-Ahead Log (WAL)。 + +无论你选择云存储还是本地存储， +建议设置[保留策略](/user-guide/concepts/features-that-you-concern.md#我可以为不同的表或指标设置-ttl-或保留策略吗)以有效管理存储成本。 + +## 举例 + +假设你的数据库每秒处理约 200 个简单查询请求（QPS），每秒处理约 300k 数据点的写入请求，使用云存储存储数据。 + +在这种写入和查询速率下， +以下是你可能分配资源的示例： + +- CPU：8 核 +- 内存：32 GB +- 存储空间：200 GB + +这样的分配旨在优化性能， +确保数据写入和查询处理的平稳进行，而不会导致系统过载。 +然而，请记住这些只是建议， +实际需求可能会根据特定的工作负载特征和性能期望而有所不同。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/back-up-&-restore-data.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/back-up-&-restore-data.md new file mode 100644 index 000000000..52de13d55 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/back-up-&-restore-data.md @@ -0,0 +1,157 @@ +--- +description: 介绍 GreptimeDB 的导出和导入工具，用于数据库备份和恢复，包括命令语法、选项、常见使用场景、最佳实践和故障排除等内容。 +--- + +# GreptimeDB 导出和导入工具 + +本指南描述了如何使用 GreptimeDB 的导出和导入工具进行数据库备份和恢复。 + +导出和导入工具提供了备份和恢复 GreptimeDB 数据库的功能。这些工具可以处理 schema（表结构等）和数据，支持完整或选择性的备份和恢复操作。 + +## 导出工具 + +### 命令语法 +```bash +greptime cli export [OPTIONS] +``` + +### 选项 +| 选项 | 是否必需 | 默认值 | 描述 | +|--------|----------|---------|-------------| +| --addr | 是 | - | 要连接的 GreptimeDB 数据库地址 | +| --output-dir | 是 | - | 存储导出数据的目录 | +| --database | 否 | 所有数据库 | 要导出的数据库名称 | +| --export-jobs, -j | 否 | 1 | 并行导出任务数量（多个数据库可以并行导出） | +| --max-retry | 否 | 3 | 每个任务的最大重试次数 | +| --target, -t | 否 | all | 导出目标（schema/data/all） | +| --start-time | 否 | - | 数据导出的开始时间范围 | +| --end-time | 否 | - | 数据导出的结束时间范围 | +| --auth-basic | 否 | - | 使用 `:` 格式 | +| --timeout | 否 | 0 | 对 DB 进行一次调用的超时时间，默认为 0 代表永不超时 （例如 `30s`, `10min 20s`） | + +### 导出目标 +- `schema`: 仅导出表结构（`SHOW CREATE TABLE`） +- `data`: 仅导出表数据（`COPY DATABASE TO`） +- `all`: 导出表结构和数据（默认） + +### 输出目录结构 +``` +/ +└── greptime/ + └── / + ├── create_database.sql + ├── create_tables.sql + ├── copy_from.sql + └── <数据文件> +``` + +## 导入工具 + +### 命令语法 +```bash +greptime cli import [OPTIONS] +``` + +### 选项 +| 选项 | 是否必需 | 默认值 | 描述 | +|--------|----------|---------|-------------| +| --addr | 是 | - | 要连接的 GreptimeDB 数据库地址 | +| --input-dir | 是 | - | 包含备份数据的目录 | +| --database | 否 | 所有数据库 | 要导入的数据库名称 | +| --import-jobs, -j | 否 | 1 | 并行导入任务数量（多个数据库可以并行导入） | +| --max-retry | 否 | 3 | 每个任务的最大重试次数 | +| --target, -t | 否 | all | 导入目标（schema/data/all） | +| --auth-basic | 否 | - | 使用 `:` 格式 | + +### 导入目标 +- `schema`: 仅导入表结构 +- `data`: 仅导入表数据 +- `all`: 导入表结构和数据（默认） + +## 常见使用场景 + +### 完整数据库备份 +```bash +# 导出所有数据库备份 +greptime cli export --addr localhost:4000 --output-dir /tmp/backup/greptimedb + +# 导入所有数据库 +greptime cli import --addr localhost:4000 --input-dir /tmp/backup/greptimedb +``` + +### 仅表结构操作 +```bash +# 仅导出表结构 +greptime cli export --addr localhost:4000 --output-dir /tmp/backup/schemas --target schema + +# 仅导入表结构 +greptime cli import --addr localhost:4000 --input-dir /tmp/backup/schemas --target schema +``` + +### 基于时间范围的备份 +```bash +# 导出特定时间范围内的数据 +greptime cli export --addr localhost:4000 \ + --output-dir /tmp/backup/timerange \ + --start-time "2024-01-01 00:00:00" \ + --end-time "2024-01-31 23:59:59" +``` + +### 指定数据库备份 +```bash +# 导出指定数据库 +greptime cli export --addr localhost:4000 --output-dir /tmp/backup/greptimedb --database '{my_database_name}' + +# 导入工具也同样适用 +greptime cli import --addr localhost:4000 --input-dir /tmp/backup/greptimedb --database '{my_database_name}' +``` + +## 最佳实践 + +1. **并行度配置** + - 根据可用系统资源调整 `--export-jobs`/`--import-jobs` + - 从较低的值开始，逐步增加 + - 在操作期间监控系统性能 + +2. **备份策略** + - 使用时间范围进行增量数据备份 + - 定期备份用于灾难恢复 + +3. **错误处理** + - 使用 `--max-retry` 处理临时异常 + - 保留日志以便故障排除 + +## 故障排除 + +### 常见问题 + +1. **连接错误** + - 验证服务器地址和端口 + - 检查网络连接 + - 确保身份验证凭据正确 + +2. **权限问题** + - 验证输出/输入目录的读写权限 + +3. **资源限制** + - 减少并行任务数 + - 确保足够的磁盘空间 + - 在操作期间监控系统资源 + +### 性能提示 + +1. **导出性能** + - 对大型数据集使用时间范围 + - 根据 CPU/内存调整并行任务数量 + - 考虑网络带宽限制 + +2. **导入性能** + - 注意监控数据库资源 + +1. **导出性能** + - 对大型数据集使用时间范围 + - 根据 CPU/内存调整并行任务 + - 考虑网络带宽限制 + +2. **导入性能** + - 监控数据库资源 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster.md new file mode 100644 index 000000000..95ffd0f23 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster.md @@ -0,0 +1,124 @@ +--- +description: 介绍 GreptimeDB 基于单集群跨区域部署的灾难恢复（DR）解决方案，包括不同区域和数据中心的部署架构及其比较。 +--- + +# 基于单集群跨区域部署的 DR 解决方案 + +## GreptimeDB DR 的工作原理 +GreptimeDB 非常适合跨区域灾难恢复。GreptimeDB 提供了量身定制的解决方案，以满足不同区域特征和业务需求的多样化要求。 + +GreptimeDB 资源管理涉及 Availability Zones（AZ）的概念。一个 AZ 是一个逻辑上的灾难恢复单元。 +它可以是数据中心（DC），也可以是 DC 的一个分区，这取决于你具体的 DC 条件和部署设计。 + +在跨区域灾难恢复解决方案中，一个 GreptimeDB 区域是一个城市。当两个 DC 在同一区域且其中一个 DC 不可用时，另一个 DC 可以接管不可用 DC 的服务。这是一种本地化策略。 + +在了解每个 DR 解决方案的细节之前，有必要先了解以下知识： +1. Remote wal 组件的 DR 解决方案也非常重要。本质上，它构成了整个 DR 解决方案的基础。因此，对于每个 GreptimeDB 的 DR 解决方案，我们将在图中展示 remote wal 组件。目前，GreptimeDB 默认使用基于 Kafka 实现的 remote wal 组件，将来会提供其他实现；然而，在部署上不会有显著差异。 +2. GreptimeDB 表：每张表可以根据一定范围划分为多个分区，每个分区可能分布在不同的数据节点上。在写入或查询时，会根据相应的路由规则调用到指定的数据节点。一张表的分区可能如下所示： + +``` +Table name: T1 +Table partition count: 4 + T1-1 + T1-2 + T1-3 + T1-4 + +Table name: T2 +Table partition count: 3 + T2-1 + T2-2 + T2-3 +``` + + +### 元数据跨两个区域，数据在同一区域 + +![DR-across-2dc-1region](/DR-across-2dc-1region.png) + +在此解决方案中，数据位于一个区域（2 个 DC），而元数据跨越两个区域。 + +DC1 和 DC2 一起用于处理读写服务，而位于第二区域的 DC3 是用来满足多数派协议的副本。这种架构也被称为 “2-2-1” 解决方案。 + +在极端情况下，DC1 和 DC2 都必须能够处理所有请求，因此请确保分配足够的资源。 + +网络延迟： +- 同一区域内延迟为 2ms +- 两个区域间延迟为 30ms + +支持高可用性级别： +- 单个 AZ 不可用时性能相同 +- 单个 DC 不可用时性能几乎相同 + +如果您想要一个区域级别的灾难恢复解决方案，可以更进一步，在 DC3 上提供读写服务。因此，下一个解决方案是： + +### 数据跨两个区域 + +![DR-across-3dc-2region](/DR-across-3dc-2region.png) + +在此解决方案中，数据跨越两个区域。 + +每个数据中心必须能够在极端情况下处理所有请求，因此请确保分配足够的资源。 + +网络延迟： +- 同一区域内延迟为 2 毫秒 +- 两个区域间延迟为 30 毫秒 + +支持高可用性级别： +- 单个可用区不可用时性能不变 +- 单个数据中心不可用时性能下降 + +如果无法容忍单个数据中心故障导致的性能下降，请考虑升级到五个数据中心和三个区域的解决方案。 + +### 元数据跨三个区域，数据跨两个区域 + +![DR-across-5dc-2region](/DR-across-5dc-2region.png) + +在此解决方案中，数据跨越两个区域，而元数据跨越三个区域。 + +Region1 和 Region2 一起用于处理读写服务，而 Region3 是一个副本，用于满足多数派协议。这种架构也被称为 “2-2-1” 解决方案。 + +两个相邻的区域中的每一个都必须能够在极端情况下处理所有请求，因此请确保分配足够的资源。 + +网络延迟： +- 同一区域内延迟为 2ms +- 两个相邻区域之间延迟为 7ms +- 两个远距离区域之间延迟为 30ms + +支持高可用性级别： +- 单一 AZ 不可用时性能不变 +- 单一 DC 不可用时性能不变 +- 单一区域（城市）不可用时性能略有下降 + +您可以更进一步，在三个区域上提供读写服务。因此，下一个解决方案是： +（此解决方案可能具有更高的延迟，如果无法接受，则不推荐。） + +## 数据跨三个区域 + +![DR-across-5dc-3region](/DR-across-5dc-3region.png) + +在此解决方案中，数据跨越三个区域。 + +如果一个区域发生故障，其他两个区域必须能够处理所有请求，因此请确保分配足够的资源。 + +网络延迟： +- 同一区域内延迟为 2 毫秒 +- 相邻两个区域之间的延迟为 7 毫秒 +- 两个远距离区域之间的延迟为 30 毫秒 + +支持高可用性级别： +- 单个 AZ 不可用时性能不变 +- 单个 DC 不可用时性能不变 +- 单个区域（城市）不可用时性能下降 + +## 解决方案比较 +上述解决方案的目标是在中大型场景中满足高可用性和可靠性的要求。然而，在具体实施过程中，每种解决方案的成本和效果可能会有所不同。下表对每种解决方案进行了比较，以帮助你根据具体场景、需求和成本进行最终选择。 + +以下是内容格式化为表格： + +| 解决方案 | 延迟 | 高可用性 | +| --- | --- | --- | +| 元数据跨两个区域，数据在同一区域 | - 同一区域内延迟 2 毫秒
- 两个区域间延迟 30 毫秒 | - 单个 AZ 不可用时性能不变
- 单个 DC 不可用时性能几乎不变 | +| 数据跨两个区域 | - 同一区域内延迟 2 毫秒
- 两个区域间延迟 30 毫秒 | - 单个 AZ 不可用时性能不变
- 单个 DC 不可用时性能下降 | +| 元数据跨三个区域，数据跨两个区域 | - 同一区域内延迟 2 毫秒
- 相邻两个区域间延迟 7 毫秒
- 两个远距离的区域间延迟 30 毫秒 | - 单个 AZ 不可用时性能不变
- 单个 DC 不可用时性能不变
- 单一区域（城市）不可用时，性能略有下降 | +| 数据跨三个区域 | - 同一区域内延迟 2 毫秒
- 相邻两个区域间延迟 7 毫秒
- 两个远距离的区域间延迟 30 毫秒 | - 单个 AZ 不可用时性能不变
- 单个 DC 不可用时性能不变
- 单一区域（城市）不可用时， 性能下降 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-for-standalone.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-for-standalone.md new file mode 100644 index 000000000..0bf03d6aa --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-for-standalone.md @@ -0,0 +1 @@ +# GreptimeDB Standalone 的 DR 方案 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/overview.md new file mode 100644 index 000000000..776a4ddef --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/disaster-recovery/overview.md @@ -0,0 +1,146 @@ +--- +description: 介绍 GreptimeDB 的灾难恢复（DR）解决方案，包括基本概念、组件架构、不同的 DR 解决方案及其比较。 +--- + +# 概述 + +作为分布式数据库，GreptimeDB 提供了不同的灾难恢复（DR）解决方案。 + +本文档包括以下内容： +* DR 中的基本概念 +* GreptimeDB 中备份与恢复（BR）的部署架构。 +* GreptimeDB 的 DR 解决方案。 +* DR 解决方案的比较。 + +## 基本概念 + +* **恢复时间目标（RTO）**：指灾难发生后业务流程可以停止的最长时间，而不会对业务产生负面影响。 +* **恢复点目标（RPO）**：指自上一个数据恢复点以来可接受的最大时间量，决定了上一个恢复点和服务中断之间可接受的数据丢失量。 + +下图说明了这两个概念： + +![RTO-RPO-explain](/RTO-RPO-explain.png) + +* **预写式日志（WAL）**：持久记录每个数据修改，以确保数据的完整性和一致性。 + +GreptimeDB 存储引擎是一个典型的 [LSM 树](https://en.wikipedia.org/wiki/Log-structured_merge-tree)： + +![LSM-tree-explain](/LSM-tree-explain.png) + +写入的数据首先持久化到 WAL，然后应用到内存中的 Memtable。 +在特定条件下（例如超过内存阈值时）， +Memtable 将被刷新并持久化为 SSTable。 +因此，WAL 和 SSTable 的备份恢复是 GreptimeDB 灾难恢复的关键。 + +* **Region**：表的连续段，也可以被视为某些关系数据库中的分区。请阅读[表分片](/contributor-guide/frontend/table-sharding.md#region)以获取更多详细信息。 + +## 组件架构 + +### GreptimeDB + +在深入了解具体的解决方案之前，让我们从灾难恢复的角度看一下 GreptimeDB 组件的架构： + +![Component-architecture](/Component-architecture.png) + +GreptimeDB 基于存储计算分离的云原生架构设计： + +* **Frontend**：数据插入和查询的服务层，将请求转发到 Datanode 并处理和合并 Datanode 的响应。 +* **Datanode**：GreptimeDB 的存储层，是一个 LSM 存储引擎。Region 是在 Datanode 中存储和调度数据的基本单元。Region 是一个表分区，是一组数据行的集合。Region 中的数据保存在对象存储中（例如 AWS S3）。未刷新的 Memtable 数据被写入 WAL，并可以在灾难发生时恢复。 +* **WAL**：持久化内存中未刷新的 Memtable 数据。当 Memtable 被刷新到 SSTable 文件时，WAL 将被截断。它可以是基于本地磁盘的（本地 WAL）或基于 Kafka 集群的（远程 WAL）。 +* **对象存储**：持久化 SSTable 数据和索引。 + +GreptimeDB 将数据存储在对象存储（如 [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/DataDurability.html)）或兼容的服务中，这些服务在年度范围内提供了 99.999999999％ 的持久性和 99.99％ 的可用性。像 S3 这样的服务提供了[单区域或跨区域的复制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html)，天然具备灾难恢复能力。 + +同时，WAL 组件是可插拔的，例如使用 Kafka 作为 WAL 服务以提供成熟的[灾难恢复解决方案](https://www.confluent.io/blog/disaster-recovery-multi-datacenter-apache-kafka-deployments/)。 + +### 备份与恢复 + +![BR-explain](/BR-explain.png) + +备份与恢复（BR）工具可以在特定时间对数据库或表进行完整快照备份，并支持增量备份。 +当集群遇到灾难时，你可以使用备份数据恢复集群。 +一般来说，BR 是灾难恢复的最后手段。 + +## 解决方案介绍 + +### GreptimeDB Standalone 的 DR 方案 + +如果 GreptimeDB Standalone 在本地磁盘上运行 WAL 和数据，那么： + +* RPO：取决于备份频率。 +* RTO：在 Standalone 没有意义，主要取决于要恢复的数据大小、故障响应时间和操作基础设施。 + +选择将 GreptimeDB Standalone 部署到具有备份和恢复解决方案的 IaaS 平台中是一个很好的开始，例如亚马逊 EC2（结合 EBS 卷）提供了全面的[备份和恢复解决方案](https://docs.aws.amazon.com/zh_cn/prescriptive-guidance/latest/backup-recovery/backup-recovery-ec2-ebs.html)。 + +但是如果使用远程 WAL 和对象存储运行 Standalone，有一个更好的 DR 解决方案： + +![DR-Standalone](/DR-Standalone.png) + +将 WAL 写入 Kafka 集群，并将数据存储在对象存储中，因此数据库本身是无状态的。 +在影响独立数据库的灾难事件发生时，你可以使用远程 WAL 和对象存储来恢复它。 +此方案能实现 RPO=0 和分钟级 RTO。 + +有关此解决方案的更多信息，请参阅[独立模式的 DR 解决方案](./dr-solution-for-standalone.md)。 + +### 基于双活互备的 DR 解决方案 + +![Active-active failover](/active-active-failover.png) + +在某些边缘或中小型场景中，或者如果你没有资源部署远程 WAL 或对象存储，双活互备相对于 Standalone 的灾难恢复提供了更好的解决方案。 +通过在两个独立节点之间同步复制请求，确保了高可用性。 +即使使用基于本地磁盘的 WAL 和数据存储，任何单个节点的故障也不会导致数据丢失或服务可用性降低。 + +在不同区域部署节点也可以满足区域级灾难恢复要求，但可扩展性有限。 + +:::tip 注意 +**双活互备功能仅在 GreptimeDB 企业版中提供。** +::: + +有关此解决方案的更多信息，请参阅[基于双活-备份的 DR 解决方案](/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md)。 + +### 基于单集群跨区域部署的 DR 解决方案 + +![Cross-region-single-cluster](/Cross-region-single-cluster.png) + +对于需要零 RPO 的中大型场景，强烈推荐此解决方案。 +在此部署架构中，整个集群跨越三个 Region，每个 Region 都能处理读写请求。 +两者都必须启用跨 Region DR 并使用远程 WAL 和对象存储实现数据复制。 +如果 Region 1 因灾难而完全不可用，其中的表 Region 将在其他 Region 中打开和恢复。 +Region 3 作为副本遵循 Metasrv 的多种协议。 + +此解决方案提供 Region 级别的容错、可扩展的写入能力、零 RPO 和分钟级或更低的 RTO。 +有关此解决方案的更多信息，请参阅[基于单集群跨区域部署的 DR 解决方案](./dr-solution-based-on-cross-region-deployment-in-single-cluster.md)。 + +### 基于备份恢复的 DR 解决方案 + +![/BR-DR](/BR-DR.png) + +在此架构中，GreptimeDB Cluster 1 部署在 Region 1。 +BR 进程持续定期将数据从 Cluster 1 备份到 Region 2。 +如果 Region 1 遭遇灾难导致 Cluster 1 无法恢复， +你可以使用备份数据恢复 Region 2 中的新集群（Cluster 2）以恢复服务。 + +基于 BR 的 DR 解决方案提供的 RPO 取决于备份频率，RTO 随要恢复的数据大小而变化。 + +阅读[备份与恢复数据](./back-up-&-restore-data.md)获取详细信息，我们计划为此解决方案提供一种内部 BR 工具。 + +### 解决方案比较 + +通过比较这些 DR 解决方案，你可以根据其特定场景、需求和成本选择最终的选项。 + + +| DR 解决方案 | 容错目标 | RPO | RTO | TCO | 场景 | 远程 WAL 和对象存储 | 备注 | +| ------------- | ------------------------- | ----- | ----- | ----- | ---------------- | --------- | --------| +| 独立模式的 DR 解决方案| 单区域 | 备份间隔 | 分钟或小时级 | 低 | 小型场景中对可用性和可靠性要求较低 | 可选 | | +| 基于双活-备份的 DR 解决方案| 跨区域 | 0 | 分钟级 | 低 | 中小型场景中对可用性和可靠性要求较高 | 可选 | 商业功能 | +| 基于单集群跨区域部署的 DR 解决方案| 多区域 | 0 | 分钟级 | 高 | 中大型场景中对可用性和可靠性要求较高 | 必需 | | +| 基于 BR 的 DR 解决方案 | 单区域 | 备份间隔 | 分钟或小时级 | 低 | 可接受的可用性和可靠性要求 | 可选 | | + + +## 参考资料 + +* [备份与恢复数据](./back-up-&-restore-data.md) +* [GreptimeDB Standalone 的 DR 解决方案](./dr-solution-for-standalone.md) +* [基于双活-备份的 DR 解决方案](/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md) +* [基于单集群跨区域部署的 DR 解决方案](./dr-solution-based-on-cross-region-deployment-in-single-cluster.md) +* [S3 对象副本概述](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/basic-table-operations.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/basic-table-operations.md new file mode 100644 index 000000000..d7757fc69 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/basic-table-operations.md @@ -0,0 +1,358 @@ +--- +description: 介绍 GreptimeDB 中表的基本操作，包括创建数据库和表、描述表、显示表定义和索引、列出现有表、修改表和删除表等内容。 +--- + +# 表的基本操作 + +在阅读本文档之前请先阅读 [数据模型](/user-guide/concepts/data-model.md). + +GreptimeDB 通过 SQL 提供了表管理的功能，下面通过 [MySQL Command-Line Client](https://dev.mysql.com/doc/refman/8.0/en/mysql.html) 来演示它。 + +以下部分更详细的关于 SQL 语法的解释，请参考 [SQL reference](/reference/sql/overview.md)。 + +## 创建数据库 + +默认的数据库是 `public`，可以手动创建一个数据库。 + +```sql +CREATE DATABASE test; +``` + +```sql +Query OK, 1 row affected (0.05 sec) +``` + +创建一个具有 7 天 `TTL`（数据存活时间）的数据库，也就是该数据库中的所有表如果没有单独设置 TTL 选项，都将继承此选项值。 + +```sql +CREATE DATABASE test WITH (ttl='7d'); +``` + +列出所有现有的数据库。 + +```sql +SHOW DATABASES; +``` + +```sql ++---------+ +| Schemas | ++---------+ +| test | +| public | ++---------+ +2 rows in set (0.00 sec) +``` + +使用 `like` 语法： + +```sql +SHOW DATABASES LIKE 'p%'; +``` + +```sql ++---------+ +| Schemas | ++---------+ +| public | ++---------+ +1 row in set (0.00 sec) +``` + +然后更改数据库： + +```sql +USE test; +``` + +更改回 `public` 数据库： + +```sql +USE public; +``` + +## 创建表 + +:::tip NOTE +注意：GreptimeDB 提供了一种 schemaless 方法来写入数据，不需要使用额外的协议手动创建表。参见 [自动生成表结构](/user-guide/ingest-data/overview.md#自动生成表结构)\*\*。 +::: + +如果您有特殊需要，仍然可以通过 SQL 手动创建表。假设我们想要创建一个名为 `monitor` 的表，其数据模型如下： + +- `host` 是独立机器的主机名，是 `Tag` 列，用于在查询时过滤数据。 +- `ts` 是收集数据的时间，是 `Timestamp` 列。它也可以在查询数据时用作时间范围的过滤器。 +- `cpu` 和 `memory` 是机器的 CPU 利用率和内存利用率，是包含实际数据且未索引的 `Field` 列。 + +创建表的 SQL 代码如下。在 SQL 中，我们使用 PRIMARY KEY 来指定 `Tag`，使用 `TIME INDEX` 来指定 `Timestamp` 列，其余列是 `Field`。 + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64 DEFAULT 0, + memory FLOAT64, + PRIMARY KEY(host)); +``` + +```sql +Query OK, 0 row affected (0.03 sec) +``` + +创建一个具有 7 天 `TTL`（数据存活时间）的表： + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64 DEFAULT 0, + memory FLOAT64, + PRIMARY KEY(host) +) WITH (ttl='7d'); +``` + + +:::warning NOTE +GreptimeDB 目前不支持在创建表后更改 TIME INDEX 约束， +因此，在创建表之前，仔细选择适当的 TIME INDEX 列。 +::: + +### `CREATE TABLE` 语法 + +- 时间戳列：GreptimeDB 是一个时序数据库系统，在创建表时，必须用 `TIME INDEX` 关键字明确指定时间序列的列。 + 时间序列的列的数据类型必须是 `TIMESTAMP`。 +- 主键：`Primary key`指定的主键列类似于其他时序系统中的 Tag，比如 [InfluxDB][1]。 主键和时间戳列用于唯一地定义一条时间线，这类似于其他时间序列系统中的时间线的概念，如 [InfluxDB][2]。 +- 表选项：当创建一个表时，可以指定一组表选项，点击[这里](/reference/sql/create.md#table-options)了解更多细节。 + +### 表名约束 + +GreptimeDB 支持在表名中使用有限的特殊字符，但必须遵守以下约束： +- 有效的 GreptimeDB 表名必须以字母（小写或大写）或 `-` / `_` / `:` 开头。 +- 表名的其余部分可以是字母数字或以下特殊字符：`-` / `_` / `:` / `@` / `#`。 +- 任何包含特殊字符的表名都必须用反引号括起来。 +- 任何包含大写字母的表名都必须用反引号括起来。 + +以下是有效和无效表名的例子： + +```sql +-- ✅ Ok +create table a (ts timestamp time index); + +-- ✅ Ok +create table a0 (ts timestamp time index); + +-- 🚫 Invalid table name +create table 0a (ts timestamp time index); + +-- 🚫 Invalid table name +create table -a (ts timestamp time index); + +-- ✅ Ok +create table `-a` (ts timestamp time index); + +-- ✅ Ok +create table `a@b` (ts timestamp time index); + +-- 🚫 Invalid table name +create table memory_HugePages (ts timestamp time index); + +-- ✅ Ok +create table `memory_HugePages` (ts timestamp time index); +``` + +[1]: https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#tag-key +[2]: https://docs.influxdata.com/influxdb/v1/concepts/glossary/#series + +## 描述表 + +显示表的详细信息： + +```sql +DESC TABLE monitor; +``` + +```sql ++--------+----------------------+------+------+---------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------+----------------------+------+------+---------------------+---------------+ +| host | String | PRI | YES | | TAG | +| ts | TimestampMillisecond | PRI | NO | current_timestamp() | TIMESTAMP | +| cpu | Float64 | | YES | 0 | FIELD | +| memory | Float64 | | YES | | FIELD | ++--------+----------------------+------+------+---------------------+---------------+ +4 rows in set (0.01 sec) +``` + +Semantic Type 列描述了表的数据模型。`host` 是 `Tag` 列，`ts` 是 `Timestamp` 列，`cpu` 和 `memory` 是 `Field` 列。 + +## 显示表定义和索引 + +使用 `SHOW CREATE TABLE table_name` 来获取创建表时的语句： + +```sql +SHOW CREATE TABLE monitor; +``` + +``` ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Table | Create Table | ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| monitor | CREATE TABLE IF NOT EXISTS `monitor` ( + `host` STRING NULL, + `ts` TIMESTAMP(3) NOT NULL DEFAULT current_timestamp(), + `cpu` DOUBLE NULL DEFAULT 0, + `memory` DOUBLE NULL, + TIME INDEX (`ts`), + PRIMARY KEY (`host`) +) + +ENGINE=mito + | ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +列出表中的所有索引： + +```sql +SHOW INDEXES FROM monitor; +``` + +```sql ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression | ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +| monitor | 1 | PRIMARY | 1 | host | A | NULL | NULL | NULL | YES | greptime-inverted-index-v1 | | | YES | NULL | +| monitor | 1 | TIME INDEX | 1 | ts | A | NULL | NULL | NULL | NO | greptime-inverted-index-v1 | | | YES | NULL | ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +``` + +有关 `SHOW` 语句的更多信息，请阅读 [SHOW 参考](/reference/sql/show.md#show)。 + +## 列出现有的表 + +可以使用 `show tables` 语句来列出现有的表 + +```sql +SHOW TABLES; +``` + +```sql ++------------+ +| Tables | ++------------+ +| monitor | +| scripts | ++------------+ +3 rows in set (0.00 sec) +``` + +注意：`scripts` 表是一个内置的表，用于存放用户定义的函数（UDF）。 + +其目前只支持表名的过滤，可以通过表名字对其进行过滤。 + +```sql +SHOW TABLES LIKE monitor; +``` + +```sql ++---------+ +| Tables | ++---------+ +| monitor | ++---------+ +1 row in set (0.00 sec) +``` + +列出其他数据库中的表： + +```sql +SHOW TABLES FROM test; +``` + +```sql ++---------+ +| Tables | ++---------+ +| monitor | ++---------+ +1 row in set (0.01 sec) +``` + +## 改动表 + +可以像在 MySQL 数据库中一样，改变现有表的模式 + +```sql +ALTER TABLE monitor ADD COLUMN label VARCHAR; +``` + +```sql +Query OK, 0 rows affected (0.03 sec) +``` + +```sql +ALTER TABLE monitor DROP COLUMN label; +``` + +```sql +Query OK, 0 rows affected (0.03 sec) +``` + +`ALTER TABLE` 语句还支持添加、删除、重命名列以及修改列的数据类型等更改。有关更多信息，请参阅[ALTER 参考指南](/reference/sql/alter.md)。 + +## 删除表 + +:::danger 危险操作 +表删除后不可撤销！请谨慎操作！ +::: + +`DROP TABLE [db.]table` 用于删除 `db` 或当前正在使用的数据库中的表。 + +删除当前数据库中的表 `test`： + +```sql +DROP TABLE monitor; +``` + +```sql +Query OK, 1 row affected (0.01 sec) +``` + +## 删除数据库 + +:::danger 危险操作 +数据库删除后不可撤销！请谨慎操作！ +::: + +可以使用 `DROP DATABASE` 删除数据库。 +例如，删除 `test` 数据库： + +```sql +DROP DATABASE test; +``` + +请前往 [DROP](/reference/sql/drop.md#drop-database) 文档了解更多内容。 + +## HTTP API + +使用以下代码，通过 POST 方法创建一个表： + +```shell +curl -X POST \ + -H 'authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql=CREATE TABLE monitor (host STRING, ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP(), cpu FLOAT64 DEFAULT 0, memory FLOAT64, TIME INDEX (ts), PRIMARY KEY(host))' \ +http://localhost:4000/v1/sql?db=public +``` + +```json +{ "code": 0, "output": [{ "affectedrows": 1 }], "execution_time_ms": 10 } +``` + +关于 SQL HTTP 请求的更多信息，请参考 [API 文档](/user-guide/protocols/http.md#post-sql-语句)。 + +## 时区 + +SQL 客户端会话中指定的时区将影响创建或更改表时的默认时间戳值。 +如果将时间戳列的默认值设置为不带时区的字符串，则该默认值会被自动添加客户端的时区信息。 + +有关客户端时区的影响，请参考 [写入数据](/user-guide/ingest-data/for-iot/sql.md#时区) 文档中的时区部分。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/compaction.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/compaction.md new file mode 100644 index 000000000..8786c9d03 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/compaction.md @@ -0,0 +1,147 @@ +--- +description: 介绍 GreptimeDB 中的压缩策略，包括时间窗口压缩策略（TWCS）和严格窗口压缩策略（SWCS），以及它们的概念、参数和使用示例。 +--- + +# Compaction + +对于基于 LSM 树的数据库，压缩是极其关键的。它将重叠的碎片化 SST 文件合并成一个有序的文件，丢弃已删除的数据，同时显著提高查询性能。 + +从 v0.9.1 版本开始，GreptimeDB 提供了控制 SST 文件如何压缩的策略：时间窗口压缩策略（TWCS）和严格窗口压缩策略（SWCS）。 + +## 概念 + +让我们从 GreptimeDB 中压缩的核心概念开始介绍。 + +### SST 文件 + +当内存表刷新到持久存储（如磁盘和对象存储）时，会生成排序的 SST 文件。 + +在 GreptimeDB 中，SST 文件中的数据行按[tag 列](/user-guide/concepts/data-model.md)和时间戳组织，如下所示。每个 SST 文件覆盖特定的时间范围。当查询指定一个时间范围时，GreptimeDB 只检索可能包含该范围内数据的相关 SST 文件，而不是加载所有已持久化的文件。 + +![SST layout](/compaction-sst-file-layout.jpg) + +通常，在实时写入工作负载中，SST 文件的时间范围不会重叠。然而，由于数据删除和乱序写入等因素，SST 文件可能会有重叠的时间范围，这会影响查询性能。 + +### 时间窗口 + +时间序列工作负载呈现出显著的“窗口”特征，即最近插入的行更有可能被读取。因此，GreptimeDB 将时间轴逻辑上划分为不同的时间窗口，我们更关注压缩那些落在同一时间窗口内的 SST 文件。 + +特定表的时间窗口参数通常是从最新 flush 到存储的 SST 文件推断出来的，或者如果选择了 TWCS，您可以在建表时手动指定时间窗口。 + +GreptimeDB 预设了一组窗口大小，它们是： +- 1 小时 +- 2 小时 +- 12 小时 +- 1 天 +- 1 周 +- 1 年 +- 10 年 + +如果未指定时间窗口大小，GreptimeDB 将在第一次压缩时推断窗口，通过从上述集合中选择**能够覆盖所有要压缩文件的整个时间跨度的**，**最小的**时间窗口作为时间窗口大小。 + +例如，在第一次压缩期间，所有输入 SST 文件的时间跨度为 4 小时，那么 GreptimeDB 将选择 12 小时作为该表的时间窗口，并将此参数持久化以便后续的压缩中使用。 + +GreptimeDB 将包含最近插入时间戳的窗口视为**活跃窗口（active window）**，而将之前的那些窗口视为**非活跃窗口（inactive window）**。 + +### 有序组 +有序组（sorted runs）是一个包含已排序且时间范围不重叠的 SST 文件的集合。 + +例如，一个表包含 5 个 SST，时间范围如下（全部包括在内）：`[0, 10]`, `[12, 23]`, `[22, 25]`,`[24, 30]`,`[26,33]`，我们可以找到 2 个有序组： + +![num-of-sorted-runs](/compaction-num-sorted-runs.jpg) + + +有序组的数量往往能够反映 SST 文件的有序性。更多的有序组通常会导致查询性能变差，因为特定时间范围的查询往往会命中多个重叠的文件。压缩的主要目标是减少有序组的数量。 + +### 层级 + +基于 LSM 树的数据库常常有多个层级，数据的键（key）会逐层进行合并。GreptimeDB 只有两个层级，分别是 0（未压缩）和 1（已压缩）。 + +## 压缩策略 + +GreptimeDB 提供了上述两种压缩策略，但在创建表时只能选择时间窗口压缩策略（TWCS）。严格窗口（SWCS）仅在执行手动压缩时可用。 + +## 时间窗口压缩策略（TWCS） + +TWCS 主要旨在减少压缩过程中的读 / 写放大。 + +它将要压缩的文件分配到不同的时间窗口。对于每个窗口，TWCS 会识别有序组。如有序组的数量超过了允许的最大值，TWCS 会找到一个解决方案，在考虑合并惩罚的同时将其减少到阈值以下。如果有序组的数量没有超过阈值，TWCS 会检查是否存在过多的文件碎片，并在必要时合并这些碎片文件，因为 SST 文件数量也会影响查询性能。 + +对于窗口分配，SST 文件可能跨越多个时间窗口。为了确保不受陈旧数据影响，TWCS 根据 SST 的最大时间戳来进行分配。在时间序列工作负载中，无序写入很少发生，即使发生了，最近数据的查询性能也比陈旧数据更为重要。 + +TWCS 提供了 5 个参数供调整: +- `max_active_window_runs`: 活跃窗口中最大允许存在的有序组数量（默认为 4） +- `max_active_window_files`: 活跃窗口中最大允许存在的文件数量（默认为 4） +- `max_inactive_window_runs`: 非活跃窗口中最大允许存在的有序组数量（默认为 1） +- `max_inactive_window_files`: 非活跃窗口中最大允许存在的文件数量（默认为 1） +- `max_output_file_size`: compaction 产生文件的最大大小（默认无限制） + +您可以为活跃窗口和非活跃窗口设置不同的阈值。这很重要，因为乱序写入通常发生在活跃窗口中。通过允许更多重叠文件存在于活跃窗口，TWCS 在数据摄取过程中减少了写放大，并在活跃窗口变为非活跃时合并所有这些文件。 + +以下图表显示了当最大活跃窗口允许的有序组数量为 1 时，活跃窗口中的文件如何被压缩: +- 在 A 中，有两个 SST 文件`[0, 3]`和`[5, 6, 9]`，但由于这两个文件的时间范围不重叠，因此只有一个有序组。 +- 在 B 中，一个新的 SST 文件`[1, 4]`被刷新，因此形成了两个有序组。然后将 `[0, 3]` 和 `[1, 4]` 合并为 `[0, 1, 3, 4]`. +- 在 C 中，一个新的 SST 文件 ` [9, 10 ] ` 被刷新，并且它将与 `[5, 6, 10 ] ` 合并以创建 `[5, 6, 9, 10]`. +- D 是最终状态，两个压缩后的文件中形成一个有序组。 + +![compaction-twcs-active.jpg](/compaction-twcs-active.jpg) + +### 指定 TWCS 参数 +用户可以在创建表时指定前述的 TWCS 参数，例如： + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64 DEFAULT 0, + memory FLOAT64, + PRIMARY KEY(host)) +WITH ( + 'compaction.type'='twcs', + 'compaction.twcs.max_active_window_runs'='4', + 'compaction.twcs.max_active_window_files'='8', + 'compaction.twcs.max_inactive_window_runs'='1', + 'compaction.twcs.max_inactive_window_files'='2', + 'compaction.twcs.max_output_file_size'='500MB' + ); +``` + +## 严格窗口压缩策略（SWCS）和手动压缩 + +与 TWCS 根据 SST 文件的最大时间戳为每个窗口分配一个 SST 文件不同的是，严格窗口策略（SWCS）将 SST 文件分配给**所有与此文件的时间范围重叠**的窗口，正如其名称所示。因此，一个 SST 文件可能会包含在多个压缩输出中。由于其在压缩期间的高读取放大率，SWCS 并不是默认的压缩策略。然而，当用户需要手动触发压缩以重新组织 SST 文件布局时，它是有用的，特别是当单个 SST 文件跨越较大的时间范围而显著减慢查询速度时。GreptimeDB 提供了一个简单的 SQL 函数来触发手动压缩： + +```sql +ADMIN COMPACT_TABLE( + , + , + [] +); +``` + +`` 参数可以是 `twcs` 或 `swcs`（大小写不敏感），分别指定时间窗口压缩策略和严格窗口压缩策略。 +对于 `swcs` 策略， `` 指定用于拆分 SST 文件的窗口大小（以秒为单位）。例如： + +```sql +ADMIN COMPACT_TABLE( + "monitor", + "swcs", + "3600" +); + ++--------------------------------------------------------------------+ +| ADMIN compact_table(Utf8("monitor"),Utf8("swcs"),Utf8("3600")) | ++--------------------------------------------------------------------+ +| 0 | ++--------------------------------------------------------------------+ +1 row in set (0.01 sec) +``` + +执行此语句时，GreptimeDB 会将每个 SST 文件按 1 小时（3600 秒）的时间跨度拆分成多个分块，并将这些分块合并为一个输出文件，确保没有重叠的文件。 + +下图展示了一次 SWCS 压缩的过程： + +在图 A 中，有 3 个重叠的 SST 文件，分别是 `[0, 3]`（也就是包含 0、1、2、3 的时间戳）、`[3, 8]` 和 `[8, 10]`。 +严格窗口压缩策略会将覆盖了窗口 0、4、8 的文件 `[3, 8]` 分别分配给 3 个窗口，从而分别和 `[0, 3]` 以及 `[8, 10]` 合并。 +图 B 给出了最终的压缩结果，分别有 3 个文件： `[0, 3]`、`[4, 7]` 和 `[8, 10]`，它们彼此互相不重叠。 + +![compaction-strict-window.jpg](/compaction-strict-window.jpg) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/overview.md new file mode 100644 index 000000000..2efcf671c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/overview.md @@ -0,0 +1,14 @@ +--- +description: 提供 GreptimeDB 数据管理的概述，包括存储位置说明、表的基本操作、更新或删除数据、TTL 策略、表分片、Region 迁移、Region Failover 和 Compaction 等内容。 +--- + +# 概述 + +* [存储位置说明](/user-guide/concepts/storage-location.md) +* [表的基本操作](basic-table-operations.md): 如何创建、修改和删除表 +* [更新或删除数据](/user-guide/manage-data/overview.md) +* [通过设置 TTL 过期数据](/user-guide/manage-data/overview.md#使用-ttl-策略保留数据) +* [表分片](table-sharding.md): 按 Region 对表进行分区 +* [Region Migration](region-migration.md): 为负载均衡迁移 Region +* [Region Failover](/user-guide/administration/manage-data/region-failover.md) +* [Compaction](compaction.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/region-failover.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/region-failover.md new file mode 100644 index 000000000..51eb48d64 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/region-failover.md @@ -0,0 +1,85 @@ +--- +description: 介绍 Region Failover 功能及其在 GreptimeDB 中的应用，包括开启 Region Failover、恢复时间和改进恢复时间的建议等内容。 +--- + +# Region Failover + +Region Failover 提供了在不丢失数据的情况下从 Region 故障中恢复的能力。这是通过 [Region 迁移](/user-guide/administration/manage-data/region-migration.md) 实现的。 + +## 开启 Region Failover + + +该功能仅在 GreptimeDB 集群模式下可用，并且需要满足以下条件 + +- 使用 Kafka WAL +- 使用[共享存储](/user-guide/deployments/configuration.md#storage-options) (例如：AWS S3) + + +### 通过配置文件 + +在 [metasrv](/user-guide/deployments/configuration.md#metasrv-only-configuration) 配置文件中设置 `enable_region_failover=true`. + +### 通过 GreptimeDB Operator + +通过设置 `meta.enableRegionFailover=true`, 例如 + +```bash +helm install greptimedb greptime/greptimedb-cluster \ + --set meta.enableRegionFailover=true \ + ... +``` + +## Region Failover 的恢复用时 + +Region Failover 的恢复时间取决于： + +- 每个 Topic 的 region 数量 +- Kafka 集群的读取吞吐性能 + + +### 读放大 + +在最佳实践中，[Kafka 集群所支持的 topics/partitions 数量是有限的](https://docs.aws.amazon.com/msk/latest/developerguide/bestpractices.html)（超过这个数量可能会导致 Kafka 集群性能下降）。 +因此，GreptimeDB 允许多个 regions 共享一个 topic 作为 WAL，然而这可能会带来读放大的问题。 + +属于特定 Region 的数据由数据文件和 WAL 中的数据（通常为 WAL[LastCheckpoint...Latest]）组成。特定 Region 的 failover 只需要读取该 Region 的 WAL 数据以重建内存状态，这被称为 Region 重放（region replaying）。然而，如果多个 Region 共享一个 Topic，则从 Topic 重放特定 Region 的数据需要过滤掉不相关的数据（即其他 Region 的数据）。这意味着从 Topic 重放特定 Region 的数据需要读取比该 Region 实际 WAL 数据大小更多的数据，这种现象被称为读取放大（read amplification）。 + +尽管多个 Region 共享同一个 Topic，可以让 Datanode 支持更多的 Region，但这种方法的代价是在 Region 重放过程中产生读取放大。 + +例如，为 [metasrv](/user-guide/deployments/configuration.md#metasrv-only-configuration) 配置 128 个 Topic，如果整个集群包含 1024 个 Region（物理 Region），那么每 8 个 Region 将共享一个 Topic。 + +![Read Amplification](/remote-wal-read-amplification.png) + +

(图 1：恢复 Region 3 需要读取比实际大小大 7 倍的冗余数据)

+ +估算读取放大倍数（重放数据大小/实际数据大小）的简单模型： + +- 对于单个 Topic，如果我们尝试重放属于该 Topic 的所有 Region，那么放大倍数将是 7+6+...+1 = 28 倍。（图 1 显示了 Region WAL 数据分布。重放 Region 3 将读取约为实际大小 7 倍的数据；重放 Region 6 将读取约为实际大小 6 倍的数据，以此类推） +- 在恢复 100 个 Region 时（需要大约 13 个 Topic），放大倍数大约为 28 \* 13 = 364 倍。 + +假设要恢复 100 个 Region，所有 Region 的实际数据大小是 0.5 GB，下表根据每个 Topic 的 Region 数量展示了数据重放的总量。 + +| 每个 Topic 的 Region 数量 | 100 个 Region 所需 Topic 数量 | 单个 Topic 读放大系数 | 总读放大系数 | 重放数据大小（GB） | +| ------------------------- | ----------------------------- | --------------------- | ------------ | ------------------ | +| 1 | 100 | 0 | 0 | 0.5 | +| 2 | 50 | 1 | 50 | 25.5 | +| 4 | 25 | 6 | 150 | 75.5 | +| 8 | 13 | 28 | 364 | 182.5 | +| 16 | 7 | 120 | 840 | 420.5 | + +下表展示了在 Kafka 集群在不同读取吞吐量情况下，100 个 region 的恢复时间。例如在提供 300MB/s 的读取吞吐量的情况下，恢复 100 个 Region 大约需要 10 分钟（182.5GB/0.3GB = 10 分钟）。 + +| 每个主题的区域数 | 重放数据大小（GB） | Kafka 吞吐量 300MB/s- 恢复时间（秒） | Kafka 吞吐量 1000MB/s- 恢复时间（秒） | +| ---------------- | ------------------ | ------------------------------------ | ------------------------------------- | +| 1 | 0.5 | 2 | 1 | +| 2 | 25.5 | 85 | 26 | +| 4 | 75.5 | 252 | 76 | +| 8 | 182.5 | 608 | 183 | +| 16 | 420.5 | 1402 | 421 | + + +### 改进恢复时间的建议 + +在上文中我们根据不同的每个 Topic 包含的 Region 数量计算了恢复时间以供参考。 +在实际场景中，读取放大的现象可能会比这个模型更为严重。 +如果您对恢复时间非常敏感，我们建议每个 Region 都有自己的 Topic（即，每个 Topic 包含的 Region 数量为 1）。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/region-migration.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/region-migration.md new file mode 100644 index 000000000..19ec6c35a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/region-migration.md @@ -0,0 +1,81 @@ +--- +description: 介绍 Region 迁移功能及其在 GreptimeDB 中的应用，包括查询 Region 分布、选择迁移目标节点、发起迁移请求和查询迁移状态等内容。 +--- + +# Region Migration + +Region 迁移允许用户在 Datanode 间移动 Region 数据。 + +:::warning 注意 +该功能仅在 GreptimeDB 集群模式下可用，并且需要满足以下条件 +- 使用 Kafka WAL +- 使用共享存储 (例如：AWS S3) + +无法在任何上述以外的情况下使用 Region 迁移。 +::: + + +## 查询 Region 分布 + +首先需要查询该数据表分区（Region）分布情况，即查询数据表中的 Region 分别在哪一些 Datanode 节点上。 + +```sql +select b.peer_id as datanode_id, + a.greptime_partition_id as region_id +from information_schema.partitions a left join information_schema.region_peers b +on a.greptime_partition_id = b.region_id where a.table_name='migration_target' order by datanode_id asc; +``` + +例如：有以下的 Region 分布 +```sql ++-------------+---------------+ +| datanode_id | region_id | ++-------------+---------------+ +| 1 | 4398046511104 | ++-------------+---------------+ +1 row in set (0.01 sec) +``` + + +更多关于 `region_peers` 表的信息，请阅读 [REGION-PEERS](/reference/sql/information-schema/region-peers.md)。 + +## 选择 Region 迁移的目标节点 +:::warning Warning +当起始节点等于目标节点时，Region 迁移不会被执行 +::: + +如果你通过 GreptimeDB operator 部署 DB 集群，Datanode 的 `peer_id` 总是从 0 开始递增。例如，DB 集群有 3 个 Datanode，则 `peer_id` 应为 0,1,2。 +最后，你可以通过以下 SQL 请求发起 Region 迁移请求： + +```sql +ADMIN migrate_region(4398046511104, 1, 2, 60); +``` + +`migrate_region` 参数说明： + +```sql +ADMIN migrate_region(region_id, from_peer_id, to_peer_id, replay_timeout); +``` + +| Option | Description | Required | | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------ | --- | +| `region_id` | Region Id | **Required** | | +| `from_peer_id` | 迁移起始节点(Datanode) 的 peer id。 | **Required** | | +| `to_peer_id` | 迁移目标节点(Datanode) 的 peer id。 | **Required** | | +| `replay_timeout` | 迁移时回放数据的超时时间（单位：秒）。如果新 Region 未能在指定时间内回放数据，迁移将失败，旧 Region 中的数据不会丢失。 | Optional | | + +## 查询迁移状态 + +`migrate_region` 函数将返回执行迁移的 Procedure Id，可以通过它查询过程状态： + +```sql +ADMIN procedure_state('538b7476-9f79-4e50-aa9c-b1de90710839') +``` + +如果顺利完成，将输出 JSON 格式的状态： + +```json + {"status":"Done"} +``` + +当然，最终可以通过从 `information_schema` 中查询 `region_peers` 和 `partitions` 来确认 Region 分布是否符合预期。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/table-sharding.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/table-sharding.md new file mode 100644 index 000000000..c39e09806 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/manage-data/table-sharding.md @@ -0,0 +1,193 @@ +--- +description: 介绍表分片技术及其在 GreptimeDB 中的应用，包括分片时机、分区规则、创建分布式表、插入数据和分布式查询等内容。 +--- + +# 表分片 + +表分片是一种将大表分成多个小表的技术。 +这种做法通常用于提高数据库系统的性能。 + +在 GreptimeDB 中，数据从逻辑上被分片成多个分区。 +由于 GreptimeDB 使用“表”来分组数据并使用 SQL 来查询数据， +因此采用了 OLTP 数据库中常用的术语“分区”。 + +## 表分片的时机 + +在 GreptimeDB 中，数据管理和调度都是基于 region 级别的， +每个 region 对应一个表分区。 +因此，当你的表太大而无法放入单个节点， +或者表太热而无法由单个节点提供服务时， +应该考虑进行分片。 + +GreptimeDB 中的一个 region 具有相对固定的吞吐量， +表中的 region 数量决定了表的总吞吐量容量。 +如果你想增加表的吞吐量容量， +可以增加表中的 region 数量。 +理想情况下，表的整体吞吐量应与 region 的数量成正比。 + +至于使用哪个特定的分区列或创建多少个 region， +这取决于数据分布和查询模式。 +一个常见的目标是使数据在 region 之间的分布尽可能均匀。 +在设计分区规则集时应考虑查询模式， +因为一个查询可以在 region 之间并行处理。 +换句话说，查询延迟取决于“最慢”的 region 延迟。 + +请注意，region 数量的增加会带来一些基本的消耗并增加系统的复杂性。 +你需要考虑数据写入速率的要求、查询性能、存储系统上的数据分布。 +只有在必要时才应进行表分片。 + +有关分区和 region 之间关系的更多信息，请参阅贡献者指南中的[表分片](/contributor-guide/frontend/table-sharding.md)部分。 + +## 分区 + +在 GreptimeDB 中， +表可以通过多种方式进行水平分区， +并且它使用与 MySQL 相同的分区类型（及相应的语法）。 +目前，GreptimeDB 支持 RANGE COLUMNS 分区。 + +每个分区仅包含表中的一部分数据， +并按某些列的值范围进行分组。 +例如，我们可以在 GreptimeDB 中这样分区一个表： + +```sql +CREATE TABLE (...) +PARTITION ON COLUMNS () ( + +); +``` + +该语法主要由两部分组成： + +1. `PARTITION ON COLUMNS` 后跟一个用逗号分隔的列名列表，指定了将用于分区的列。这里指定的列必须是 Tag 类型（由 PRIMARY KEY 指定）。请注意，所有分区的范围必须**不能**重叠。 + +2. `RULE LIST` 是多个分区规则的列表。每个规则是分区名称和分区条件的组合。这里的表达式可以使用 `=`, `!=`, `>`, `>=`, `<`, `<=`, `AND`, `OR`, 列名和字面量。 + +:::tip 提示 +目前在 “PARTITION BY RANGE” 语法中不支持表达式。 +::: + +### 示例 + +## 创建分布式表 + +你可以使用 MySQL CLI [连接到 GreptimeDB](/user-guide/protocols/mysql.md) 并创建一个分布式表。 +下方的示例创建了一个表并基于 `device_id` 列进行分区。 + +```SQL +CREATE TABLE sensor_readings ( + device_id INT16, + reading_value FLOAT64, + ts TIMESTAMP DEFAULT current_timestamp(), + PRIMARY KEY (device_id), + TIME INDEX (ts) +) +PARTITION ON COLUMNS (device_id) ( + device_id < 100, + device_id >= 100 AND device_id < 200, + device_id >= 200 +); +``` + +你可以使用更多的分区列来创建更复杂的分区规则： + +```sql +CREATE TABLE sensor_readings ( + device_id INT, + area STRING, + reading_value FLOAT64, + ts TIMESTAMP DEFAULT current_timestamp(), + PRIMARY KEY (device_id, area), + TIME INDEX (ts) +) +PARTITION ON COLUMNS (device_id, area) ( + device_id < 100 AND area = 'North', + device_id < 100 AND area = 'South', + device_id >= 100 AND area = 'East', + device_id >= 100 AND area = 'West' +); +``` + +以下内容以具有两个分区列的 `sensor_readings` 表为例。 + +## 向表中插入数据 + +以下代码向 `sensor_readings` 表的每个分区插入 3 行数据。 + +```sql +INSERT INTO sensor_readings (device_id, area, reading_value, ts) +VALUES (1, 'North', 22.5, '2023-09-19 08:30:00'), + (10, 'North', 21.8, '2023-09-19 09:45:00'), + (50, 'North', 23.4, '2023-09-19 10:00:00'); + +INSERT INTO sensor_readings (device_id, area, reading_value, ts) +VALUES (20, 'South', 20.1, '2023-09-19 11:15:00'), + (40, 'South', 19.7, '2023-09-19 12:30:00'), + (90, 'South', 18.9, '2023-09-19 13:45:00'); + +INSERT INTO sensor_readings (device_id, area, reading_value, ts) +VALUES (110, 'East', 25.3, '2023-09-19 14:00:00'), + (120, 'East', 26.5, '2023-09-19 15:30:00'), + (130, 'East', 27.8, '2023-09-19 16:45:00'); + +INSERT INTO sensor_readings (device_id, area, reading_value, ts) +VALUES (150, 'West', 24.1, '2023-09-19 17:00:00'), + (170, 'West', 22.9, '2023-09-19 18:15:00'), + (180, 'West', 23.7, '2023-09-19 19:30:00'); +``` + +## 分布式查询 + +只需使用 `SELECT` 语法查询数据： + +```sql +SELECT * FROM sensor_readings order by reading_value desc LIMIT 5; +``` + +```sql ++-----------+------+---------------+---------------------+ +| device_id | area | reading_value | ts | ++-----------+------+---------------+---------------------+ +| 130 | East | 27.8 | 2023-09-19 16:45:00 | +| 120 | East | 26.5 | 2023-09-19 15:30:00 | +| 110 | East | 25.3 | 2023-09-19 14:00:00 | +| 150 | West | 24.1 | 2023-09-19 17:00:00 | +| 180 | West | 23.7 | 2023-09-19 19:30:00 | ++-----------+------+---------------+---------------------+ +5 rows in set (0.02 sec) +``` + +```sql +SELECT MAX(reading_value) AS max_reading +FROM sensor_readings; +``` + +```sql ++-------------+ +| max_reading | ++-------------+ +| 27.8 | ++-------------+ +1 row in set (0.03 sec) +``` + +```sql +SELECT * FROM sensor_readings +WHERE area = 'North' AND device_id < 50; +``` + +```sql ++-----------+-------+---------------+---------------------+ +| device_id | area | reading_value | ts | ++-----------+-------+---------------+---------------------+ +| 10 | North | 21.8 | 2023-09-19 09:45:00 | +| 1 | North | 22.5 | 2023-09-19 08:30:00 | ++-----------+-------+---------------+---------------------+ +2 rows in set (0.03 sec) +``` + +## 检查分片表 + +GreptimeDB 提供了几个系统表来检查数据库的状态。 +对于表分片信息，你可以查询 [`information_schema.partitions`](/reference/sql/information-schema/partitions.md)， +它提供了一个表内分区的详细信息， +以及 [`information_schema.region_peers`](/reference/sql/information-schema/region-peers.md) 提供了 region 的运行时分布信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/export-metrics.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/export-metrics.md new file mode 100644 index 000000000..2bbf46ecc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/export-metrics.md @@ -0,0 +1,161 @@ +--- +description: 介绍如何导出 GreptimeDB 的监控指标到 Prometheus 或 GreptimeDB 自身，并提供各组件的指标详情。 +--- + +# 导出指标 + +通过监控指标，你可以评估数据库的状态，维护部署并诊断问题。 + +请参考[指标详情](#指标详情)章节了解 GreptimeDB 的具体指标。 + +## 启动 GreptimeDB + +请参考[此处](/getting-started/installation/overview.md)了解如何启动 GreptimeDB。 + +## 导出数据到 Prometheus + +GreptimeDB 支持导出数据到 Prometheus。 在配置导出数据之前，你需要按照 Prometheus 的[官方文档](https://prometheus.io/docs/prometheus/latest/installation/)安装 Prometheus. + +要从 GreptimeDB 中抓取指标，请编写 Prometheus 配置文件并将其保存为 `prometheus.yml`： + +```yml +global: + scrape_interval: 15s + +scrape_configs: + - job_name: 'greptimedb' + static_configs: + # Assuming that GreptimeDB is running locally. + # The default HTTP port of 4000. + - targets: ['localhost:4000'] +``` + +使用该配置文件启动 Prometheus。 +例如，使用 Docker 启动 Prometheus 时，可以将配置文件挂载到 Docker 容器中： + +```bash +docker run \ + -p 9090:9090 \ + -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \ + prom/prometheus +``` + +:::tip NOTE +为了防止不小心退出 Docker 容器，你可能想以 “detached” 模式运行它：在 `docker run` 命令中添加 `-d` 参数即可。 +::: + +## 将指标保存到 GreptimeDB 自身 + +你还可以将指标保存到 GreptimeDB 本身，以便于使用 SQL 语句进行查询和分析。 +本节提供了相关配置示例，有关配置的更多详细信息，请参阅[监控指标选项](/user-guide/deployments/configuration.md#monitor-metrics-options)。 + +### 单机模式 + +在单机模式下，你可以简单地使用 `self_import` 来导出指标。 +相关配置如下： + +```toml +[export_metrics] +enable=true +# The interval of writing metrics. +write_interval = "30s" +[export_metrics.self_import] +db = "information_schema" +``` + +`db` 选项指定了保存指标的数据库，你可以将其修改为其他数据库。 + +### 分布式集群 + +集群中的每个组件都需要编写配置文件。 + +#### Frontend + +你可以简单地使用 `self_import` 来导出指标。 + +```toml +[export_metrics] +enable=true +# The interval of writing metrics. +write_interval = "30s" +[export_metrics.self_import] +db = "information_schema" +``` + +`db` 选项指定了保存指标的数据库，你可以将其修改为其他数据库。 + +#### Datanode 和 Metasrv + +在 Datanode 和 Metasrv 中，你需要使用 `remote_write` 配置来导出指标。 + +```toml +[export_metrics] +enable=true +write_interval = "30s" +[export_metrics.remote_write] +url = "http://127.0.0.1:4000/v1/prometheus/write?db=system" +``` + +GreptimeDB 兼容 Prometheus Remote-Write 协议。 +请参考 [Prometheus Remote-Write](/user-guide/ingest-data/for-observerbility/prometheus.md) 获取更多信息。 + +## 指标详情 + +可以通过执行`curl http://:/metrics`的输出来获取 GreptimeDB 的最新指标。 + +### Frontend + +| Key | Type | +|----------------------------------------------|---------| +| greptime_table_operator_ingest_rows | counter | +| greptime_servers_error | counter | +| greptime_servers_http_requests_total | counter | +| greptime_servers_postgres_connection_count | gauge | +| greptime_servers_mysql_connection_count | gauge | +| greptime_query_merge_scan_regions | summary | +| greptime_servers_http_sql_elapsed | summary | +| greptime_query_optimize_physicalplan_elapsed | summary | +| greptime_frontend_handle_sql_elapsed | summary | +| greptime_http_track_metrics | summary | +| greptime_query_create_physicalplan_elapsed | summary | +| greptime_servers_mysql_query_elapsed | summary | +| greptime_servers_http_requests_elapsed | summary | +| greptime_query_execute_plan_elapsed | summary | +| greptime_catalog_kv_get_remote | summary | +| greptime_grpc_region_request | summary | +| greptime_query_merge_scan_poll_elapsed | summary | +| greptime_catalog_kv_get | summary | +| greptime_table_operator_create_table | summary | + + +### Datanode + +| Key | Type | +|--------------------------------------------|---------| +| greptime_opendal_bytes_total | counter | +| greptime_servers_http_requests_total | counter | +| greptime_opendal_requests_total | counter | +| greptime_catalog_catalog_count | gauge | +| greptime_catalog_schema_count | gauge | +| greptime_opendal_requests_duration_seconds | summary | +| greptime_http_track_metrics | summary | +| greptime_servers_http_requests_elapsed | summary | + + +### Meta + +| Key | Type | +|----------------------------------------|---------| +| greptime_meta_create_schema | counter | +| greptime_servers_http_requests_total | counter | +| greptime_meta_create_catalog | counter | +| greptime_meta_heartbeat_connection_num | gauge | +| greptime_meta_txn_request | summary | +| greptime_meta_kv_request | summary | +| greptime_meta_create_schema | summary | +| greptime_meta_create_catalog | summary | +| greptime_meta_handler_execute | summary | +| greptime_servers_http_requests_elapsed | summary | +| greptime_http_track_metrics | summary | +| greptime_meta_procedure_create_table | summary | +| greptime_grpc_region_request | summary | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/overview.md new file mode 100644 index 000000000..b6d0db7e2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/overview.md @@ -0,0 +1,12 @@ +--- +description: 介绍监控 GreptimeDB 的方法，包括导出指标和链路追踪。 +--- + +# 概述 + +数据库的有效管理在很大程度上依赖于监控。 +你可以使用以下方法监控 GreptimeDB： + +- [导出指标](export-metrics.md) +- [链路追踪](tracing.md) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/tracing.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/tracing.md new file mode 100644 index 000000000..c2457841b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/monitoring/tracing.md @@ -0,0 +1,115 @@ +--- +description: 介绍 GreptimeDB 的分布式链路追踪功能，包括如何使用 Jaeger 进行追踪和配置 tracing 采样率。 +--- + +# 链路追踪 + +GreptimeDB 支持分布式链路追踪。 GreptimeDB 使用基于 gRPC 的 OTLP 协议导出所有采集到的 Span。您可以使用 [Jaeger](https://www.jaegertracing.io/)、[Tempo](https://grafana.com/oss/tempo/) 等支持基于 gRPC 的 OTLP 协议后端接收 GreptimeDB 采集到的 Span。 + +在配置中的 [logging 部分](/user-guide/deployments/configuration.md#logging-选项) 有对 tracing 的相关配置项说明，[standalone.example.toml](https://github.com/GreptimeTeam/greptimedb/blob/main/config/standalone.example.toml) 的 logging 部分提供了参考配置项。 + +## 教程：使用 Jaeger 追踪 GreptimeDB 调用链路 + +[Jaeger](https://www.jaegertracing.io/) 是一个开源的、端到端的分布式链路追踪系统，最初由 Uber 开发并开源。它的目标是帮助开发人员监测和调试复杂的微服务架构中的请求流程。 + +Jaeger 支持基于 gRPC 的 OTLP 协议，所以 GreptimeDB 可以将跟踪数据导出到 Jaeger。 以下教程向您展示如何部署和使用 Jaeger 来跟踪 GreptimeDB。 + +### 步骤一：部署 Jaeger + +使用 jaeger 官方提供的 `all-in-one` docker 镜像启动一个 Jaeger 实例： + +```bash +docker run --rm -d --name jaeger \ + -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \ + -p 6831:6831/udp \ + -p 6832:6832/udp \ + -p 5778:5778 \ + -p 16686:16686 \ + -p 4317:4317 \ + -p 4318:4318 \ + -p 14250:14250 \ + -p 14268:14268 \ + -p 14269:14269 \ + -p 9411:9411 \ + jaegertracing/all-in-one:latest +``` + +### 步骤二：部署 GreptimeDB + +编写配置文件，允许 GreptimeDB 进行链路追踪。将下面的配置项保存为文件 `config.toml` + +```Toml +[logging] +enable_otlp_tracing = true +``` + +之后使用 standalone 模式启动 GreptimeDB + +```bash +greptime standalone start -c config.toml +``` + +参考章节 [Mysql](/user-guide/protocols/mysql.md) 如何连接到 GreptimeDB。在 Mysql Client 中运行下面的 SQL 语句： + +```sql +CREATE TABLE host ( + ts timestamp(3) time index, + host STRING PRIMARY KEY, + val BIGINT, +); + +INSERT INTO TABLE host VALUES + (0, 'host1', 0), + (20000, 'host2', 5); + +SELECT * FROM host ORDER BY ts; + +DROP TABLE host; +``` + +### 步骤三：在 Jaeger 中获取 trace 信息 + +1. 转到 http://127.0.0.1:16686/ 并选择“Search”选项卡。 +2. 在服务下拉列表中选择 `greptime-standalone` 服务。 +3. 单击 **Find Traces** 以显示追踪到的链路信息。 + +![JaegerUI](/jaegerui.png) + +![Select-tracing](/select-tracing.png) + +## 指南：如何配置 tracing 采样率 + +GreptimeDB 提供了许多协议与接口，用于数据的插入、查询等功能。您可以通过 tracing 采集到每种操作的调用链路。但是对于某些高频操作，将所有该操作的 tracing 都采集下来，可能没有必要而且浪费存储空间。这个时候，您可以使用 `tracing_sample_ratio` 来对各种操作 tracing 的采样率进行设置，这样能够很大程度上减少导出 tracing 的数量并有利于系统观测。 + +GreptimeDB 根据接入的协议，还有该协议对应的操作，对所有 tracing 进行了分类： + +| **protocol** | **request_type** | +|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| grpc | inserts / query.sql / query.logical_plan / query.prom_range / query.empty / ddl.create_database / ddl.create_table / ddl.alter / ddl.drop_table / ddl.truncate_table / ddl.empty / deletes / row_inserts / row_deletes | +| mysql | | +| postgres | | +| otlp | metrics / traces | +| opentsdb | | +| influxdb | write_v1 / write_v2 | +| prometheus | remote_read / remote_write / format_query / instant_query / range_query / labels_query / series_query / label_values_query | +| http | sql / promql + +您可以通过 `tracing_sample_ratio` 来配置不同 tracing 的采样率。 + +```toml +[logging] +enable_otlp_tracing = true +[logging.tracing_sample_ratio] +default_ratio = 0.0 +[[logging.tracing_sample_ratio.rules]] +protocol = "mysql" +ratio = 1.0 +[[logging.tracing_sample_ratio.rules]] +protocol = "grpc" +request_types = ["inserts"] +ratio = 0.3 +``` + +上述配置制定了两条采样规则，并制定了默认采样率，GreptimeDB 会根据您提供的采样规则，从第一条开始匹配，并使用第一条匹配到的采样规则作为该 tracing 的采样率，如果没有任何规则匹配，则 `default_ratio` 会被作为默认采样率被使用。采样率的范围是 `[0.0, 1.0]`, `0.0` 代表所有 tracing 都不采样，`1.0` 代表采样所有 tracing。 + +比如上面提供的规则，使用 mysql 协议接入的所有调用都将被采样，使用 grpc 插入的数据会被采样 30%，其余所有 tracing 都不会被采样。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/overview.md new file mode 100644 index 000000000..c44c6f5a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/overview.md @@ -0,0 +1,18 @@ +--- +description: 介绍 GreptimeDB 管理中的策略和实践，包括安装、容量规划、数据管理、配置、灾难恢复、监控和升级等内容。 +--- + +# 概述 + +本文档介绍了在 GreptimeDB 管理中使用的策略和实践。 + +* [安装](/getting-started/installation/overview.md) GreptimeDB 和 [g-t-control](/reference/gtctl.md) 命令行工具 +* 根据工作负载进行 GreptimeDB 的[容量规划](/user-guide/administration/capacity-plan.md) +* [管理数据](/user-guide/administration/manage-data/overview.md) 以避免数据丢失、降低成本和提高性能 +* 数据库配置，请阅读[配置](/user-guide/deployments/configuration.md)参考文档 +* GreptimeDB 的[灾难恢复方案](/user-guide/administration/disaster-recovery/overview.md) +* 通过[设置 Remote WAL](./remote-wal/quick-start.md) 实现 GreptimeDB 的集群容灾 +* GreptimeDB 的[监控指标](/user-guide/administration/monitoring/export-metrics.md)和[链路追踪](/user-guide/administration/monitoring/tracing.md) +* [性能调优技巧](/user-guide/administration/performance-tuning-tips.md) +* [升级](/user-guide/administration/upgrade.md) GreptimeDB 到新版本 +* 获取集群的[运行时信息](/user-guide/administration/runtime-info.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/performance-tuning-tips.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/performance-tuning-tips.md new file mode 100644 index 000000000..32992baa7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/performance-tuning-tips.md @@ -0,0 +1,187 @@ +--- +description: 提供 GreptimeDB 性能调优的技巧，包括查询性能指标、缓存配置、写入优化和表结构设计建议。 +--- + +# 性能调优技巧 + +GreptimeDB 实例的默认配置可能不适合所有场景。因此根据场景调整数据库配置和使用方式相当重要。 + +GreptimeDB 提供了各种指标来帮助监控和排查性能问题。官方仓库里提供了用于独立模式和集群模式的 [Grafana dashboard 模版](https://github.com/GreptimeTeam/greptimedb/tree/main/grafana)。 + +## 查询 + +### 指标 + +以下指标可用于诊断查询性能问题： +| 指标 | 类型 | 描述 | +|---|---|---| +| greptime_mito_read_stage_elapsed_bucket | histogram | 存储引擎中查询不同阶段的耗时。 | +| greptime_mito_cache_bytes | gauge | 缓存内容的大小 | +| greptime_mito_cache_hit | counter | 缓存命中总数 | +| greptime_mito_cache_miss | counter | 缓存未命中总数 | + + +## 为对象存储开启缓存 + +我们推荐在使用对象存储时启用读取缓存和写入缓存。这可以将查询耗时缩短 10 倍以上。 + +> 提示: 从 v0.11 版本开始，在使用远程对象存储服务时，系统会默认启用本地缓存（包括读取和写入）。通常情况下，您只需要根据需求调整缓存容量即可。 + +读取缓存将对象或一段范围的数据存储在本地磁盘上，以避免再次从远程读取相同的数据。以下示例展示了如何为 S3 启用读取缓存。 +- `cache_path` 是存储缓存对象的目录，从 v0.11 版本开始默认值为 `{data_home}/object_cache/read` 目录。 +- `cache_capacity` 是缓存的容量。从 0.11 版本开始，默认初始值为 `5Gib`，建议至少留出总磁盘空间的 1/10 用于缓存。 + +```toml +[storage] +type = "S3" +bucket = "ap-southeast-1-test-bucket" +root = "your-root" +access_key_id = "****" +secret_access_key = "****" +endpoint = "https://s3.amazonaws.com/" +region = "your-region" +cache_path = "/path/to/s3cache" +cache_capacity = "10G" +``` + +写入缓存起到 write-through 缓存的作用，在将文件上传到对象存储之前，会先将它们存储在本地磁盘上。这可以减少第一次查询的延迟。以下示例展示了如何启用写入缓存。 +- `enable_experimental_write_cache` 开关可用来启用写入缓存。从 `v0.11` 版本开始，当配置对象存储服务的时候，该值将默认设置为 `true`，即启用。 +- `experimental_write_cache_size` 用来设置缓存的容量。从 0.11 版本开始，默认初始值为 `5Gib`。 +- `experimental_write_cache_path` 用来设置存储缓存文件的路径。默认情况下它位于数据主目录下。 +- `experimental_write_cache_ttl` 用来设置缓存文件的 TTL。 + + +```toml +[[region_engine]] +[region_engine.mito] +enable_experimental_write_cache = true +experimental_write_cache_size = "10G" +experimental_write_cache_ttl = "8h" +# experimental_write_cache_path = "/path/to/write/cache" +``` + +## 增大缓存大小 + +可以监控 `greptime_mito_cache_bytes` 和 `greptime_mito_cache_miss` 指标来确定是否需要增加缓存大小。这些指标中的 `type` 标签表示缓存的类型。 + +如果 `greptime_mito_cache_miss` 指标一直很高并不断增加，或者 `greptime_mito_cache_bytes` 指标达到缓存容量，可能需要调整存储引擎的缓存大小配置。 + +以下是一个例子： + +```toml +[[region_engine]] +[region_engine.mito] +# 如果使用对象存储则取消该参数的注释 +# enable_experimental_write_cache = true +# 写入缓存的缓存大小。此缓存的 `type` 标签值为 `file`。 +experimental_write_cache_size = "10G" +# SST 元数据的缓存大小。此缓存的 `type` 标签值为 `sst_meta`。 +sst_meta_cache_size = "128MB" +# 向量和箭头数组的缓存大小。此缓存的 `type` 标签值为 `vector`。 +vector_cache_size = "512MB" +# SST 行组页面的缓存大小。此缓存的 `type` 标签值为 `page`。 +page_cache_size = "512MB" +# 时间序列查询结果（例如 `last_value()`）的缓存大小。此缓存的 `type` 标签值为 `selector_result`。 +selector_result_cache_size = "512MB" + +[region_engine.mito.index] +## 索引暂存目录的最大容量。 +staging_size = "10GB" +``` + +一些建议： +- 至少将 `experimental_write_cache_size` 设置为磁盘空间的 1/10 +- 如果数据库内存使用率低于 20%，则可以至少将 `page_cache_size` 设置为总内存大小的 1/4 +- 如果缓存命中率低于 50%，则可以将缓存大小翻倍 +- 如果使用全文索引，至少将 `staging_size` 设置为磁盘空间的 1/10 + +## 扩大扫描并行度 + +存储引擎将每个查询的并发扫描任务数限制为 CPU 内核数的 1/4。如果机器的工作负载相对较低，扩大并行度可以减少查询延迟。 + +```toml +[[region_engine]] +[region_engine.mito] +scan_parallelism = 8 +``` + +## 尽可能使用 append-only 表 + +一般来说，append-only 表具有更高的扫描性能，因为存储引擎可以跳过合并和去重操作。此外，如果表是 append-only 表，查询引擎可以使用统计信息来加速某些查询。 + +如果表不需要去重或性能优先于去重，我们建议为表启用 [append_mode](/reference/sql/create.md##create-an-append-only-table)。例如，日志表应该是 append-only 表，因为日志消息可能具有相同的时间戳。 + + +## 写入 + +### 指标 + +以下指标有助于诊断写入问题： + +| 指标 | 类型 | 描述 | +|---|---|---| +| greptime_mito_write_stage_elapsed_bucket | histogram | 存储引擎中处理写入请求的不同阶段的耗时 | +| greptime_mito_write_buffer_bytes | gauge | 当前为写入缓冲区（memtables）分配的字节数（估算） | +| greptime_mito_write_rows_total | counter | 写入存储引擎的行数 | +| greptime_mito_write_stall_total | gauge | 当前由于内存压力过高而被阻塞的行数 | +| greptime_mito_write_reject_total | counter | 由于内存压力过高而被拒绝的行数 | +| raft_engine_sync_log_duration_seconds_bucket | histogram | 将 WAL 刷入磁盘的耗时 | +| greptime_mito_flush_elapsed | histogram | 刷入 SST 文件的耗时 | + + +### 批量写入行 + +批量写入是指通过同一个请求将多行数据发送到数据库。这可以显著提高写入吞吐量。建议的起始值是每批 1000 行。如果延迟和资源使用仍然可以接受，可以扩大攒批大小。 + +### 按时间窗口写入 +虽然 GreptimeDB 可以处理乱序数据，但乱序数据仍然会影响性能。GreptimeDB 从写入的数据中推断出时间窗口的大小，并根据时间戳将数据划分为多个时间窗口。如果写入的行不在同一个时间窗口内，GreptimeDB 需要将它们拆分，这会影响写入性能。 + +通常，实时数据不会出现上述问题，因为它们始终使用最新的时间戳。如果需要将具有较长时间范围的数据导入数据库，我们建议提前创建表并 [指定 compaction.twcs.time_window 选项](/reference/sql/create.md#create-a-table-with-custom-compaction-options)。 + + +## 表结构 + +### 使用多值 + +在设计架构时，我们建议将可以一起收集的相关指标放在同一个表中。这也可以提高写入吞吐量和压缩率。 + + +例如，以下三个表收集了 CPU 的使用率指标。 + +```sql +CREATE TABLE IF NOT EXISTS cpu_usage_user ( + hostname STRING NULL, + usage_value BIGINT NULL, + ts TIMESTAMP(9) NOT NULL, + TIME INDEX (ts), + PRIMARY KEY (hostname) +); +CREATE TABLE IF NOT EXISTS cpu_usage_system ( + hostname STRING NULL, + usage_value BIGINT NULL, + ts TIMESTAMP(9) NOT NULL, + TIME INDEX (ts), + PRIMARY KEY (hostname) +); +CREATE TABLE IF NOT EXISTS cpu_usage_idle ( + hostname STRING NULL, + usage_value BIGINT NULL, + ts TIMESTAMP(9) NOT NULL, + TIME INDEX (ts), + PRIMARY KEY (hostname) +); +``` + +我们可以将它们合并为一个具有三个字段的表。 + +```sql +CREATE TABLE IF NOT EXISTS cpu ( + hostname STRING NULL, + usage_user BIGINT NULL, + usage_system BIGINT NULL, + usage_idle BIGINT NULL, + ts TIMESTAMP(9) NOT NULL, + TIME INDEX (ts), + PRIMARY KEY (hostname) +); +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/remote-wal/cluster-deployment.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/remote-wal/cluster-deployment.md new file mode 100644 index 000000000..db8e851d1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/remote-wal/cluster-deployment.md @@ -0,0 +1,236 @@ +--- +description: 介绍如何在 Kubernetes 中部署带有 Remote WAL 配置的 GreptimeDB 集群，包括部署 GreptimeDB Operator、etcd 集群、Kafka 集群和 GreptimeDB 集群。 +--- + +# 集群部署 + +我们强烈建议将 GreptimeDB 集群部署在 Kubernetes 中，这里是一些此次部署的前置依赖： + +- Kubernetes(>=1.18) + + 出于测试原因，你可以使用 Kind 或者 MiniKube 来创建 Kubernetes 环境。 + +- Helm v3 + +- kubectl + +## Step 1: 部署 GreptimeDB Operator + +使用如下命令来添加 Helm Chart 仓库： + +``` +helm repo add greptime https://greptimeteam.github.io/helm-charts/ +helm repo update +``` + +创建 `greptimedb-admin` namespace 并将 GreptimeDB Operator 部署在这个 namespace 中： + +``` +kubectl create ns greptimedb-admin +helm upgrade --install greptimedb-operator greptime/greptimedb-operator -n greptimedb-admin +``` + +## Step 2: 部署 GreptimeDB Cluster + +GreptimeDB 集群需要使用 etcd 集群来作为 metasrv 的后端存储。我们建议使用 Bitnami etcd chart 来部署 etcd 集群： + +``` +kubectl create ns metasrv-store +helm upgrade --install etcd oci://registry-1.docker.io/bitnamicharts/etcd \ + --set replicaCount=3 \ + --set auth.rbac.create=false \ + --set auth.rbac.token.enabled=false \ + -n metasrv-store +``` + +当 etcd 集群已经部署完成，你可以用如下命令来检查其健康状况： + +``` +kubectl -n metasrv-store \ + exec etcd-0 -- etcdctl \ + --endpoints etcd-0.etcd-headless.metasrv-store:2379,etcd-1.etcd-headless.metasrv-store:2379,etcd-2.etcd-headless.metasrv-store:2379 \ + endpoint status +``` + +## Step 3: 部署 Kafka 集群 + +我们建议使用 [strimzi-kafka-operator](https://github.com/strimzi/strimzi-kafka-operator) 来部署 KRaft 模式的 Kafka 集群。 + +创建 `kafka` namespace 并安装 strimzi-kafka-operator: + +``` +kubectl create namespace kafka +kubectl create -f 'https://strimzi.io/install/latest?namespace=kafka' -n kafka +``` + +当 operator 部署完成，使用如下 Spec 来创建 Kafka 集群： + +``` +apiVersion: kafka.strimzi.io/v1beta2 +kind: KafkaNodePool +metadata: + name: dual-role + labels: + strimzi.io/cluster: kafka-wal +spec: + replicas: 3 + roles: + - controller + - broker + storage: + type: jbod + volumes: + - id: 0 + type: persistent-claim + size: 20Gi + deleteClaim: false +--- + +apiVersion: kafka.strimzi.io/v1beta2 +kind: Kafka +metadata: + name: kafka-wal + annotations: + strimzi.io/node-pools: enabled + strimzi.io/kraft: enabled +spec: + kafka: + version: 3.7.0 + metadataVersion: 3.7-IV4 + listeners: + - name: plain + port: 9092 + type: internal + tls: false + - name: tls + port: 9093 + type: internal + tls: true + config: + offsets.topic.replication.factor: 3 + transaction.state.log.replication.factor: 3 + transaction.state.log.min.isr: 2 + default.replication.factor: 3 + min.insync.replicas: 2 + entityOperator: + topicOperator: {} + userOperator: {} +``` + +将上述 spec 保存为 `kafka-wal.yaml` 并 apply 到 Kubernetes 中： + +``` +kubectl apply -f kafka-wal.yaml -n kafka +``` + +当 Kafka 集群部署完成，检查其状态： + +``` +kubectl get kafka -n kafka +``` + +预期的输出将会是： + +``` +NAME DESIRED KAFKA REPLICAS DESIRED ZK REPLICAS READY METADATA STATE WARNINGS +kafka-wal True KRaft +``` + +## Step 4: 部署 Remote WAL 配置下的 GrpetimeDB 集群 + +使用如下 remote WAL 配置来创建 GreptimeDB 集群： + +``` +cat <= 5 AND n < 9, + n >= 9 +); +``` + +写入数据： + +``` +INSERT INTO dist_table(n, row_id) VALUES (1, 1); +INSERT INTO dist_table(n, row_id) VALUES (2, 2); +INSERT INTO dist_table(n, row_id) VALUES (3, 3); +INSERT INTO dist_table(n, row_id) VALUES (4, 4); +INSERT INTO dist_table(n, row_id) VALUES (5, 5); +INSERT INTO dist_table(n, row_id) VALUES (6, 6); +INSERT INTO dist_table(n, row_id) VALUES (7, 7); +INSERT INTO dist_table(n, row_id) VALUES (8, 8); +INSERT INTO dist_table(n, row_id) VALUES (9, 9); +INSERT INTO dist_table(n, row_id) VALUES (10, 10); +INSERT INTO dist_table(n, row_id) VALUES (11, 11); +INSERT INTO dist_table(n, row_id) VALUES (12, 12); +``` + +接着查询数据： + +``` +SELECT * from dist_table; +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/remote-wal/quick-start.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/remote-wal/quick-start.md new file mode 100644 index 000000000..a256d17ef --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/remote-wal/quick-start.md @@ -0,0 +1,169 @@ +--- +description: 介绍如何使用 Docker 快速启动带有 Remote WAL 的 Standalone GreptimeDB，包括创建自定义 Docker bridge、启动 Kafka 服务和 GreptimeDB。 +--- + +# 快速开始 + +## 什么是 Remote WAL + +[WAL](/contributor-guide/datanode/wal.md#introduction)(Write-Ahead Logging) 是 GreptimeDB 中的一个关键组件，它持久记录每一次数据修改，以确保不会丢失缓存在内存中的数据。我们在 [Datanode](/user-guide/concepts/why-greptimedb.md) 服务中用持久的嵌入式存储引擎 [raft-engine](https://github.com/tikv/raft-engine) 将 WAL 实现为一个模块。在公共云中部署 GreptimeDB 时，我们可以在云存储（AWS EBS、GCP 持久盘等）中持久存储 WAL 数据，以实现 0 RPO。然而，由于 WAL 与 Datanode 紧密耦合，导致部署过程中的 RTO（Recovery Time Objective）较长。此外，由于 raft-engine 无法支持多日志订阅，这使得实现 region 热备份和 region 迁移变得困难。 + +为了解决上述问题，我们决定设计并实现一个远程 WAL。远程 WAL 将 WAL 从 Datanode 分离到远程服务，我们选择了 Apache Kafka 作为远程服务。Apache Kafka 在流处理中被广泛采用，展现出卓越的分布式容错能力和基于主题的订阅机制。在发布 v0.5.0 版本时，我们引入了 Apache Kafka 作为 WAL 的可选存储引擎。 + + +## 运行带有 Remote WAL 的 Standalone GreptimeDB + +通过以下步骤使用 Docker 体验远程 WAL 非常简单。在这个快速开始中，我们将创建一个采用 KRaft 模式的 Kafka 集群，并将其作为独立 GreptimeDB 的远程 WAL。 + +### Step 1: 创建一个自定义的 Docker bridge + +自定义的 Docker bridge 可以帮助我们创建用于连接多个容器的桥接网络： + +``` +docker network create greptimedb-remote-wal +``` + +### Step 2: 启动 Kafka 服务 + +使用 KRaft 模式来启动单节点 Kafka： + +``` +docker run \ + --name kafka --rm \ + --network greptimedb-remote-wal \ + -p 9092:9092 \ + -e KAFKA_CFG_NODE_ID="1" \ + -e KAFKA_CFG_PROCESS_ROLES="broker,controller" \ + -e KAFKA_CFG_CONTROLLER_QUORUM_VOTERS="1@kafka:9093" \ + -e KAFKA_CFG_ADVERTISED_LISTENERS="PLAINTEXT://kafka:9092" \ + -e KAFKA_CFG_CONTROLLER_LISTENER_NAMES="CONTROLLER" \ + -e KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP="CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT" \ + -e KAFKA_CFG_LISTENERS="PLAINTEXT://:9092,CONTROLLER://:9093" \ + -e ALLOW_PLAINTEXT_LISTENER="yes" \ + -e KAFKA_BROKER_ID="1" \ + -e KAFKA_CFG_LOG_DIRS="/bitnami/kafka/data" \ + -v $(pwd)/kafka-data:/bitnami/kafka/data \ + bitnami/kafka:3.6.0 +``` + +:::tip NOTE +为了防止不小心退出 Docker 容器，你可能想以 “detached” 模式运行它：在 `docker run` 命令中添加 `-d` 参数即可。 +::: + +数据将保存在 `$(pwd)/kafka-data`. + +### Step 3: 用 Remote WAL 模式启动 standalone 模式 GreptimeDB + +使用 Kafka wal provider 来启动 standalone 模式的 GreptimeDB： + +``` +docker run \ + --network greptimedb-remote-wal \ + -p 4000-4003:4000-4003 \ + -v "$(pwd)/greptimedb:/tmp/greptimedb" \ + --name greptimedb --rm \ + -e GREPTIMEDB_STANDALONE__WAL__PROVIDER="kafka" \ + -e GREPTIMEDB_STANDALONE__WAL__BROKER_ENDPOINTS="kafka:9092" \ + greptime/greptimedb standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 +``` + +:::tip NOTE +为了防止不小心退出 Docker 容器，你可能想以 “detached” 模式运行它：在 `docker run` 命令中添加 `-d` 参数即可。 +::: + +我们使用环境变量来指定 provider： + +- `GREPTIMEDB_STANDALONE__WAL__PROVIDER`: 设置为 `kafka` 以此来使用 kafka remote wal； +- `GREPTIMEDB_STANDALONE__WAL__BROKER_ENDPOINTS`: 指定 Kafka 集群中所有 brokers 的地址。在此示例中，我们将使用 Kafka 容器的名称，桥接网络将其解析为 IPv4 地址； + +### Step 4: 写入和查询数据 + +有很多方式来连接 GreptimeDB，这里我们选择使用 `mysql` 命令行工具。 + +1. **用 MySQL 协议连接 GrepimeDB** + + ``` + mysql -h 127.0.0.1 -P 4002 + ``` + + +2. **写入测试数据** + + - 创建 `system_metrics` 表 + + ```sql + CREATE TABLE IF NOT EXISTS system_metrics ( + host STRING, + idc STRING, + cpu_util DOUBLE, + memory_util DOUBLE, + disk_util DOUBLE, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY(host, idc), + TIME INDEX(ts) + ); + ``` + + - 写入测试数据 + + ```sql + INSERT INTO system_metrics + VALUES + ("host1", "idc_a", 11.8, 10.3, 10.3, 1667446797450), + ("host1", "idc_a", 80.1, 70.3, 90.0, 1667446797550), + ("host1", "idc_b", 50.0, 66.7, 40.6, 1667446797650), + ("host1", "idc_b", 51.0, 66.5, 39.6, 1667446797750), + ("host1", "idc_b", 52.0, 66.9, 70.6, 1667446797850), + ("host1", "idc_b", 53.0, 63.0, 50.6, 1667446797950), + ("host1", "idc_b", 78.0, 66.7, 20.6, 1667446798050), + ("host1", "idc_b", 68.0, 63.9, 50.6, 1667446798150), + ("host1", "idc_b", 90.0, 39.9, 60.6, 1667446798250); + ``` + +3. **查询数据** + + ```sql + SELECT * FROM system_metrics; + ``` + +4. **查询 Kafka Topics** + + ``` + # List the Kafka topics. + docker exec kafka /opt/bitnami/kafka/bin/kafka-topics.sh --list --bootstrap-server localhost:9092 + ``` + + 默认所有 topic 都以 `greptimedb_wal_topic` 开头，例如: + + ``` + docker exec kafka /opt/bitnami/kafka/bin/kafka-topics.sh --list --bootstrap-server localhost:9092 + greptimedb_wal_topic_0 + greptimedb_wal_topic_1 + greptimedb_wal_topic_10 + ... + +### Step 5: 清理 + +- 停止 GreptimeDB 和 Kafka + + ``` + docker stop greptimedb + docker stop kafka + ``` + +- 移除 Docker bridge + + ``` + docker network rm greptimedb-remote-wal + ``` + +- 删除数据 + + ``` + rm -r /greptimedb + rm -r /kafka-data + ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/runtime-info.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/runtime-info.md new file mode 100644 index 000000000..7675bebbd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/runtime-info.md @@ -0,0 +1,29 @@ +--- +description: 介绍如何通过 INFORMATION_SCHEMA 数据库访问系统元数据，并提供查询集群拓扑信息和表的 Region 分布的示例。 +--- + +# 运行时信息 + +`INFORMATION_SCHEMA` 数据库提供了对系统元数据的访问，如数据库或表的名称、列的数据类型等。 + +* 通过 [CLUSTER_INFO](/reference/sql/information-schema/cluster-info.md) 表查找集群的拓扑信息。 +* 通过 [PARTITIONS](/reference/sql/information-schema/partitions.md) 表和[REGION_PEERS](/reference/sql/information-schema/region-peers.md) 表查找表的 Region 分布。 + +例如查询一张表的所有 Region Id: + +```sql +SELECT greptime_partition_id FROM PARTITIONS WHERE table_name = 'monitor' +``` + +查询一张表的 region 分布在哪些 datanode 上： + +```sql +SELECT b.peer_id as datanode_id, + a.greptime_partition_id as region_id +FROM information_schema.partitions a LEFT JOIN information_schema.region_peers b +ON a.greptime_partition_id = b.region_id +WHERE a.table_name='monitor' +ORDER BY datanode_id ASC +``` + +请阅读[参考文档](/reference/sql/information-schema/overview.md)获取更多关于 `INFORMATION_SCHEMA` 数据库的信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/upgrade.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/upgrade.md new file mode 100644 index 000000000..240c9408d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/administration/upgrade.md @@ -0,0 +1,183 @@ +--- +description: 介绍如何使用内置工具将 GreptimeDB 从 v0.4 及以上版本升级到最新版本，包括 CLI 工具的使用和具体步骤。 +--- + +# 版本升级 + +从 `v0.4` 开始，我们提供了一个内置的工具来帮助您将以前的 GreptimeDB 部署升级到最新版本。 +如果不同版本之间有 Breaking Change，我们都建议使用此方法在不同版本的 GreptimeDB 之间进行迁移升级。 + +此工具可以将 `v0.3.0` 以上的版本升级到最新版本。 + +## CLI + +该工具在 `greptime` 二进制文件中。在开始之前，您需要准备目标版本的二进制文件。 + +```shell +greptime cli export --help +``` + +帮助文档如下： + +```shell +greptime-cli-export + +USAGE: + greptime cli export [OPTIONS] --addr --output-dir --target + +OPTIONS: + --addr + Server address to connect + + --output-dir + Directory to put the exported data. E.g.: /tmp/greptimedb-export + + --database + The name of the catalog to export + + [default: greptime-*] + + -j, --export-jobs + Parallelism of the export + + [default: 1] + + --max-retry + Max retry times for each job + + [default: 3] + + -t, --target + Things to export + + [default: all] + + Possible values: + - schema: Export all table schemas, corresponding to `SHOW CREATE TABLE` + - data: Export all table data, corresponding to `COPY DATABASE TO` + - all: Export all table schemas and data at once + + --log-dir + + + --start-time + A half-open time range: [start_time, end_time). The start of the time range (time-index column) for data export + + --end-time + A half-open time range: [start_time, end_time). The end of the time range (time-index column) for data export + + --log-level + + + --auth-basic + The basic authentication for connecting to the server + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version +``` + +这里解释一些重要选项的含义： + +- `-addr`：Frontend 节点或者 Standalone 进程的 http server 地址。 +- `-output-dir`：要放置导出数据的目录。需要是当前机器上的路径。导出的 SQL 文件将放在该目录中。 +- `-target`：指定要导出的数据。`schema` 选项会导出每个表的 `CREATE TABLE` 子句。`data` 选项会导出每个数据库的数据以及对应 DB 的 `COPY FROM` 语句。默认情况下会导出 `schema` 和 `data` 的所有数据，推荐不设定选项直接使用默认值以导出所有数据。 + +对于完整的升级，您需要使用每个目标选项两次执行此工具。 + +## 从 0.8.x 升级 + +这一节将演示如何从 `v0.8.x` 升级到 `v0.9.x`。 + +在下面的文本中，我们假设您的数据库的 HTTP 端口为 `127.0.0.1:4000`。 + +### 一次导出表结构和表数据 + +```shell +greptime cli export --addr '127.0.0.1:4000' --output-dir /tmp/greptimedb-export +``` + +如果成功，您将看到类似于以下内容的输出 + +```log +2024-08-01T06:32:26.547809Z INFO cmd: Starting app: greptime-cli +2024-08-01T06:32:27.239639Z INFO cmd::cli::export: Finished exporting greptime.greptime_private with 0 table schemas to path: /tmp/greptimedb-export/greptime/greptime_private/ +2024-08-01T06:32:27.540696Z INFO cmd::cli::export: Finished exporting greptime.pg_catalog with 0 table schemas to path: /tmp/greptimedb-export/greptime/pg_catalog/ +2024-08-01T06:32:27.832018Z INFO cmd::cli::export: Finished exporting greptime.public with 0 table schemas to path: /tmp/greptimedb-export/greptime/public/ +2024-08-01T06:32:28.272054Z INFO cmd::cli::export: Finished exporting greptime.test with 1 table schemas to path: /tmp/greptimedb-export/greptime/test/ +2024-08-01T06:32:28.272166Z INFO cmd::cli::export: Success 4/4 jobs, cost: 1.724222791s +2024-08-01T06:32:28.416532Z INFO cmd::cli::export: Executing sql: COPY DATABASE "greptime"."greptime_private" TO '/tmp/greptimedb-export/greptime/greptime_private/' WITH (FORMAT='parquet'); +2024-08-01T06:32:28.556017Z INFO cmd::cli::export: Finished exporting greptime.greptime_private data into path: /tmp/greptimedb-export/greptime/greptime_private/ +2024-08-01T06:32:28.556330Z INFO cmd::cli::export: Finished exporting greptime.greptime_private copy_from.sql +2024-08-01T06:32:28.556424Z INFO cmd::cli::export: Executing sql: COPY DATABASE "greptime"."pg_catalog" TO '/tmp/greptimedb-export/greptime/pg_catalog/' WITH (FORMAT='parquet'); +2024-08-01T06:32:28.738719Z INFO cmd::cli::export: Finished exporting greptime.pg_catalog data into path: /tmp/greptimedb-export/greptime/pg_catalog/ +2024-08-01T06:32:28.738998Z INFO cmd::cli::export: Finished exporting greptime.pg_catalog copy_from.sql +2024-08-01T06:32:28.739098Z INFO cmd::cli::export: Executing sql: COPY DATABASE "greptime"."public" TO '/tmp/greptimedb-export/greptime/public/' WITH (FORMAT='parquet'); +2024-08-01T06:32:28.875600Z INFO cmd::cli::export: Finished exporting greptime.public data into path: /tmp/greptimedb-export/greptime/public/ +2024-08-01T06:32:28.875888Z INFO cmd::cli::export: Finished exporting greptime.public copy_from.sql +2024-08-01T06:32:28.876005Z INFO cmd::cli::export: Executing sql: COPY DATABASE "greptime"."test" TO '/tmp/greptimedb-export/greptime/test/' WITH (FORMAT='parquet'); +2024-08-01T06:32:29.053681Z INFO cmd::cli::export: Finished exporting greptime.test data into path: /tmp/greptimedb-export/greptime/test/ +2024-08-01T06:32:29.054104Z INFO cmd::cli::export: Finished exporting greptime.test copy_from.sql +2024-08-01T06:32:29.054162Z INFO cmd::cli::export: Success 4/4 jobs, costs: 781.98875ms +2024-08-01T06:32:29.054181Z INFO cmd: Goodbye! + +``` + +此时输出目录的结构如下 + +```plaintext +/tmp/greptimedb-export/ +├── greptime/public +│   ├── copy_from.sql +│   ├── create_tables.sql +│   ├── up.parquet +│   └── other-tables.parquet +``` + +内容包括 `create_tables.sql`, `copy_from.sql` 和 DB `greptime-public` 的每个表的 parquet 文件。`create_tables.sql` 包含当前 DB 所有表的建表语句，`copy_from.sql` 则包含一条 `COPY DATABASE FROM` 的语句，用于将数据文件 COPY 到目标 DB。剩下的 parquet 个数的文件就是每个表的数据文件。 + +### 导入表结构和数据 + +然后您需要执行上一步生成的 SQL 文件。首先是 `create_tables.sql`。在之前的步骤中导出的 SQL 语句使用的是 PostgreSQL 方言，接下来的操作都将通过 [PostgreSQL 协议](/user-guide/protocols/postgresql.md)来进行。本文档假设客户端为 `psql`。 + +:::tip NOTICE +从这一步开始，所有的操作都是在新版本的 GreptimeDB 中完成的。 + +PostgreSQL 协议的默认端口是 `4003`。 +::: + +在执行以下命令之前，您需要在新部署中首先创建相应的数据库（但在本例中，数据库 `greptime-public` 是默认的）。 + +此命令将在新版本的 GreptimeDB 中创建所有表。 + +```shell +psql -h 127.0.0.1 -p 4003 -d public -f /tmp/greptimedb-export/greptime/public/create_tables.sql +``` + +接下来导入数据 + +```shell +psql -h 127.0.0.1 -p 4003 -d public -f /tmp/greptimedb-export/greptime/public/copy_from.sql +``` + +### 清理 + +到这一步，所有的数据都已经迁移完毕。您可以在新集群中检查数据。 + +在确认数据正确后，您可以清理旧集群和临时的 `--output-dir`。在本例中是 `/tmp/greptimedb-export`。 + +## 推荐流程 + +该部分给出了一个推荐的整体流程，以便平滑升级 GreptimeDB。如果您的环境可以在升级过程中离线，可以跳过此部分。 + +1. 创建一个全新的 v0.9.x 集群 +2. 使用 v0.9.x 版本的 cli 工具导出并导入 `create-table` +3. 将工作负载切换到新集群 +4. 使用 v0.9.x 版本的 cli 工具导出并导入 `database-data` + +注意 + +- 在步骤 2 和 3 之间对表结构的更改将丢失 +- 在第四部完成之前，老数据在新集群上是不可见的。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/architecture.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/architecture.md new file mode 100644 index 000000000..98e7e6f1c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/architecture.md @@ -0,0 +1,17 @@ +--- +description: 介绍 GreptimeDB 的基础架构，包括 Metasrv、Frontend 和 Datanodes 三个主要组成部分及其功能。 +--- + +# 基础架构 + +![architecture](/architecture-3.png) + +为了形成一个强大的数据库集群，并控制其复杂性，GreptimeDB 架构中有三个主要组成部分：Metasrv，Frontend 和 Datanodes。 + +- [**Metasrv**](/contributor-guide/metasrv/overview.md) 控制着 GreptimeDB 集群的核心命令。在典型的部署结构中，至少需要三个节点才能建立一个可靠的 _Metasrv_ 小集群。_Metasrv_ 管理着数据库和表的信息，包括数据如何在集群中传递、请求的转发地址等。它还负责监测 `Datanode` 的可用性和性能，以确保路由表的最新状态和有效性。 + +- [**Frontend**](/contributor-guide/frontend/overview.md) 作为无状态的组件，可以根据需求进行伸缩扩容。它负责接收请求并鉴权，将多种协议转化为 GreptimeDB 集群的内部 gRPC 协议，并根据 _Metasrv_ 中的表的分片路由信息将请求转发到相应的 _Datanode_。 + +- [**Datanode**](/contributor-guide/datanode/overview.md) 负责 GreptimeDB 集群中的表的 `region` 数据存储，接收并执行从 _Frontend_ 发来的读写请求，处理查询和写入，并返回对应的结果。 + +通过灵活的架构设计，以上三个组件既可以是集群分布式部署，也可以合并打包在一个二进制包内，支持本地部署下的单机模式，我们称之为 standalone 模式。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/data-model.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/data-model.md new file mode 100644 index 000000000..c14ad1b07 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/data-model.md @@ -0,0 +1,84 @@ +--- +description: 介绍 GreptimeDB 的数据模型，包括表的结构、列类型和设计考虑，适用于指标、日志和事件数据。 +--- + +# 数据模型 + +## 模型 + +GreptimeDB 使用时序表来进行数据的组织、压缩和过期管理。数据模型主要基于关系型数据库中的表模型，同时考虑到了指标（metrics）、日志（logs）及事件（events）数据的特点。 + +GreptimeDB 中的所有数据都被组织成表，每个表中的数据项由三种类型的列组成：`Tag`、`Timestamp` 和 `Field`。 + +- 表名通常与指标、日志的名称相同。 +- `Tag` 列中存储经常被查询的元数据，其中的值是数据源的标签，通常用于描述数据的特定特征。`Tag` 列具有索引，所以使用 `Tag` 列的查询具备良好的性能。 +- `Timestamp` 是指标、日志及事件的时序数据库的基础，它表示数据生成的日期和时间。Timestamp 具有索引，所以使用 `Timestamp` 的查询具有良好的性能。一个表只能有一个 `Timestamp` 列，被称为时间索引列。 +- 其他列是 `Field` 列，其中的值是被收集的数据指标或日志。这些指标通常是数值或字符串，但也可能是其他类型的数据，例如地理位置。`Field` 列默认情况下没有被索引，对该字段做过滤查询会全表扫描。这可能会消耗大量资源并且性能较差，但是字符串字段可以启用[全文索引](/user-guide/logs/query-logs.md#全文索引加速搜索)，以加快日志搜索等查询的速度。 + +### Metric 表 + +假设我们有一个名为 `system_metrics` 的时间序列表用于监控独立设备的资源使用情况。 + +```sql +CREATE TABLE IF NOT EXISTS system_metrics ( + host STRING, + idc STRING, + cpu_util DOUBLE, + memory_util DOUBLE, + disk_util DOUBLE, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY(host, idc), + TIME INDEX(ts) +); +``` + +该表的数据模型如下： + +![time-series-table-model](/time-series-data-model.svg) + +这与大家熟悉的表模型非常相似。不同之处在于 `Timestamp` 约束，它用于将 `ts` 列指定为此表的时间索引列。 + +- 表名为 `system_metrics`。 +- 对于 `Tag` 列，`host` 列表示收集的独立机器的主机名，`idc` 列显示机器所在的数据中心。这些是查询元数据，可以在查询时有效地过滤数据。 +- `Timestamp` 列 `ts` 表示收集数据的时间。使用该列查询具有时间范围的数据时具备较高的性能。 +- `Field` 列中的 `cpu_util`、`memory_util`、`disk_util` 和 `load` 列分别表示机器的 CPU 利用率、内存利用率、磁盘利用率和负载。 + 这些列包含实际的数据并且不被索引，但是可以被高效地计算，例如求最大最小值、均值和百分比分布等。 + 请避免在查询条件中使用 `Field` 列，这会消耗大量资源并且性能较差。 + +### Log 表 + +你还可以创建一个日志表用于存储访问日志： + +```sql +CREATE TABLE access_logs ( + access_time TIMESTAMP TIME INDEX, + remote_addr STRING, + http_status STRING, + http_method STRING, + http_refer STRING, + user_agent STRING, + request STRING FULLTEXT, + PRIMARY KEY (remote_addr, http_status, http_method, http_refer, user_agent) +) +``` +其中： + +- 时间索引列为 `access_time`。 +- `remote_addr`、`http_status`、`http_method`、`http_refer`、`user_agent` 为 Tag。 +- `request` 是通过 [`FULLTEXT` 列选项](/reference/sql/create.md#fulltext-列选项)启用全文索引的字段。 + +要了解如何指定 `Tag`、`Timestamp` 和 `Field` 列，请参见[表管理](/user-guide/administration/manage-data/basic-table-operations.md#创建表)和 [CREATE 语句](/reference/sql/create.md)。 + +当然，无论何时，你都可以将指标和日志放在一张表里，这也是 GreptimeDB 提供的关键能力。 + +## 设计考虑 + +GreptimeDB 基于表进行设计，原因如下： + +- 表格模型易于学习，具有广泛的用户群体，我们只需引入时间索引的概念即可实现对指标、日志和事件的统一。 +- Schema 是描述数据特征的元数据，对于用户来说更方便管理和维护。通过引入 Schema 版本的概念，我们可以更好地管理数据兼容性。 +- Schema 通过其类型、长度等信息带来了巨大的优化存储和计算的好处，我们可以进行有针对性的优化。 +- 当我们有了表格 Schema 后，自然而然地引入了 SQL，并用它来处理各种表之间的关联分析和聚合查询，为用户抵消了学习和使用成本。 +- 比起 OpenTSDB 和 Prometheus 采用的单值模型，GreptimeDB 使用多值模型使其中一行数据可以具有多列数据。多值模型面向数据源建模，一个 metric 可以有用 field 表示的值。多值模型的优势在于它可以一次性向数据库写入或读取多个值，从而减少传输流量并简化查询。相比之下，单值模型则需要将数据拆分成多个记录。阅读[博客](https://greptime.com/blogs/2024-05-09-prometheus)以获取更多详情。 + +GreptimeDB 使用 SQL 管理表 Schema。有关更多信息，请参见[表管理](/user-guide/administration/manage-data/basic-table-operations.md)。但是，我们对 Schema 的定义并不是强制性的，而是倾向于 **Schemaless** 的方式，类似于 MongoDB。有关更多详细信息，请参见[自动生成表结构](../ingest-data/overview.md#自动生成表结构)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/features-that-you-concern.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/features-that-you-concern.md new file mode 100644 index 000000000..90963bd52 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/features-that-you-concern.md @@ -0,0 +1,73 @@ +--- +description: 介绍 GreptimeDB 的关键特性，并解答用户关心的常见问题，如日志处理、数据更新和删除、TTL 策略等。 +--- + +# 关键特性 + +## GreptimeDB 支持处理日志或事件吗？ + +是的，从 v0.9.0 版本开始，GreptimeDB 将所有时间序列视为具有时间戳的上下文事件，从而统一了指标、日志和事件的处理。它支持使用 SQL、PromQL 进行指标和事件分析，并支持通过持续聚合进行流式处理。 + +请阅读[日志处理使用指南](/user-guide/logs/overview.md)。 + +## GreptimeDB 支持更新数据吗？ + +支持，请参考[更新数据](/user-guide/manage-data/overview.md#更新数据)获取更多信息。 + +## GreptimeDB 支持删除数据吗？ + +支持，请参考[删除数据](/user-guide/ingest-data/overview.md#删除数据)获取更多信息。 + +## 我可以为不同的表或指标设置 TTL 或保留策略吗？ + +当然。请参考[使用 TTL 策略保留数据](/user-guide/manage-data/overview.md#使用-ttl-策略保留数据)。 + +## GreptimeDB 的压缩率是多少？ + +答案是视情况而定。 + +GreptimeDB 使用列式存储布局，并通过最佳算法压缩时间序列数据，并且它会根据列数据的统计和分布选择最合适的压缩算法。GreptimeDB 还将提供可以更紧凑地压缩数据但会失去精度的 Rollup 功能。 + +因此，GreptimeDB 的数据压缩率可能在 2 倍到几百倍之间，这取决于你的数据特性以及你是否可以接受精度损失。 + +## GreptimeDB 如何解决高基数问题？ + +GreptimeDB 通过以下方式解决这个问题： + +- **分片**：它将数据和索引分布在不同的 Region 服务器之间。阅读 GreptimeDB 的[架构](./architecture.md)。 +- **智能索引**：它不强制为每个标签创建倒排索引，而是根据标签列的特性和负载类型选择合适的索引类型并自动构建，更多信息可以参考这篇[博客](https://greptime.com/blogs/2022-12-21-storage-engine-design#smart-indexing)。 +- **MPP**: 除了索引之外，查询引擎还会利用向量化执行和分布式并行执行等技术来加速查询。 + +## GreptimeDB 支持持续聚合或降采样吗？ + +从 0.8 版本开始，GreptimeDB 添加了一个名为 `Flow` 的新功能，用于持续聚合和降采样等场景。请阅读[用户指南](/user-guide/continuous-aggregation/overview.md)获取更多信息。 + +## 我可以在云的对象存储中存储数据吗？ + +可以，GreptimeDB 的数据访问层基于 [OpenDAL](https://github.com/apache/incubator-opendal)，它支持大多数类型的对象存储服务。 +数据可以存储在如 AWS S3 或 Azure Blob Storage 等性价比高的云存储服务中，请参考这里的存储[配置指南](./../deployments/configuration.md#storage-options)。 + +GreptimeDB 还提供一个完全托管的云服务 [GreptimeCloud](https://greptime.cn/product/cloud) 来帮助您管理云中的数据。 + +## GreptimeDB 对比其他存储或时序数据库的性能如何？ + +请阅读以下性能报告： + +* [GreptimeDB vs. InfluxDB](https://greptime.cn/blogs/2024-08-08-report) +* [GreptimeDB vs. Grafana Mimir](https://greptime.cn/blogs/2024-08-01-grafana) +* [GreptimeDB vs. ClickHouse vs. ElasticSearch](https://greptime.cn/blogs/2024-08-21-report) +* [GreptimeDB vs. SQLite](https://greptime.cn/blogs/2024-08-30-sqlite) + +## GreptimeDB 有灾难恢复解决方案吗？ + +有的，请参阅[灾难恢复文档](/user-guide/administration/disaster-recovery/overview.md)。 + +## GeptimeDB 有地理空间索引吗? + +我们提供 [内置函数](/reference/sql/functions/geo.md) 支持 Geohash, H3 and S2 索 +引。 + + +## GeptimeDB 支持 JSON 数据吗? + +我们提供 [内置函数](/reference/sql/functions/overview.md#json-functions) 支持访问 JSON 数据类型。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/key-concepts.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/key-concepts.md new file mode 100644 index 000000000..35096fc3c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/key-concepts.md @@ -0,0 +1,50 @@ +--- +description: 介绍 GreptimeDB 的核心概念，包括数据库、时序表、数据类型、索引、视图和 Flow 等。 +--- + +# 核心概念 + +为了理解 GreptimeDB 如何管理和服务其数据，你需要了解这些 GreptimeDB 的构建模块。 + +## 数据库 + +类似于关系型数据库中的 _数据库_，数据库是数据容器的最小单元，数据可以在这个单元中被管理和计算。 +你可以利用数据库来实现数据隔离，形成类似租户的效果。 + +## Time-Series Table + +GreptimeDB 将时序表设计为数据存储的基本单位。 +其类似于传统关系型数据库中的表，但需要一个时间戳列（我们称之为 `TIME INDEX`—— **时间索引**），并且该表持有一组共享一个共同 schema 的数据。 + +表是行和列的集合： + +* 行：表中水平方向的值的集合。 +* 列：表中垂直方向的值的集合，GreptimeDB 将列分为时间索引 Time Index、标签 Tag 和字段 Field。 + +你使用 SQL `CREATE TABLE` 创建表，或者使用[自动生成表结构](/user-guide/ingest-data/overview.md#自动生成表结构)功能通过输入的数据结构自动创建表。在分布式部署中，一个表可以被分割成多个分区，其位于不同的数据节点上。 + +关于时序表的数据模型的更多信息，请参考[数据模型](./data-model.md)。 + +## Table Region + +分布式表的每个分区被称为一个区域。一个区域可能包含一个连续数据的序列，这取决于分区算法，区域信息由 Metasrv 管理。这对发送写入和查询的用户来说是完全透明的。 + +## 数据类型 + +GreptimeDB 中的数据是强类型的，当创建表时，Auto-schema 功能提供了一些灵活性。当表被创建后，同一列的数据必须共享共同的数据类型。 + +在[数据类型](/reference/sql/data-types.md)中找到所有支持的数据类型。 + +## 索引 + +索引是一种性能调优方法，可以加快数据的更快地检索速度。 +GreptimeDB 使用[倒排索引](/contributor-guide/datanode/data-persistence-indexing.md#倒排索引)来加速查询。 + +## View + +从 SQL 查询结果集派生的虚拟表。它像真实表一样包含行和列，但它本身不存储任何数据。 +每次查询视图时，都会从底层表中动态检索视图中显示的数据。 + +## Flow + +GreptimeDB 中的 Flow 是指[持续聚合](/user-guide/continuous-aggregation/overview.md)过程，该过程根据传入数据持续更新和聚合数据。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/overview.md new file mode 100644 index 000000000..47e3261cd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/overview.md @@ -0,0 +1,21 @@ +--- +description: 概述 GreptimeDB 的特点和优势，并提供相关文档链接，帮助用户了解 GreptimeDB 的设计和功能。 +--- + +# 概述 + +- [Why GreptimeDB](./why-greptimedb.md)：介绍了 GreptimeDB 的特点和优势，包括其对指标、日志和事件数据的统一设计，云原生和灵活架构允许在各种环境中部署，从嵌入式到云平台等。GreptimeDB 还具有成本优势、高性能和用户友好等特点。 +- [数据模型](./data-model.md)：介绍了 GreptimeDB 的数据模型，包括表的模式、索引列等。 +- [基础架构](./architecture.md)：获取 GreptimeDB 的云原生架构。 +- [存储位置](./storage-location.md)：介绍了 GreptimeDB 的存储位置，包括本地磁盘、HDFS 、AWS S3 和阿里云 OSS 等云对象存储。 +- [核心概念](./key-concepts.md)：介绍了 GreptimeDB 的核心概念，包括表、时间索引约束、表Region 和数据类型等。 +- [关键特性](./features-that-you-concern.md): 介绍了 TSDB 用户较为关心的指标（metrics）、日志（logs）和事件（events）数据库的特性。 + +## 阅读更多 + +从我们的博客文章中获取 GreptimeDB 路线图和架构设计： + +- [专为实时而生 — GreptimeDB 现已在 GitHub 正式开源](https://greptime.com/blogs/2022-11-15-this-time-for-real) +- [事件管理革命：监控系统中统一日志和指标](https://greptime.com/blogs/2024-06-25-logs-and-metrics) +- [GreptimeDB 架构内幕：基于分布式、云原生原则设计，实现时序处理及分析融合](https://greptime.com/blogs/2022-12-08-GreptimeDB-internal-design) +- [GreptimeDB 存储引擎设计内幕：针对时序场景，检索压缩更智能](https://greptime.com/blogs/2022-12-21-storage-engine-design) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/storage-location.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/storage-location.md new file mode 100644 index 000000000..e1b67675d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/storage-location.md @@ -0,0 +1,44 @@ +--- +description: 介绍 GreptimeDB 支持的存储位置，包括本地文件系统和各种云存储服务，以及存储文件结构。 +--- + +# 存储位置 + +GreptimeDB 支持将数据存储在本地文件系统、AWS S3 及其兼容服务（包括 minio、digitalocean space、腾讯云对象存储(COS)、百度云对象存储(BOS)等）、Azure Blob Storage 和阿里云 OSS 中。 + +## 本地文件结构 + +GreptimeDB 的存储文件结构包括以下内容： + +```cmd +├── metadata + ├── raftlog + ├── rewrite + └── LOCK +├── data +│   ├── greptime +│   └── public +├── logs +├── index_intermediate +│   └── staging +└── wal + ├── raftlog + ├── rewrite + └── LOCK +``` + +- `metadata`: 内部元数据目录，保存 catatalog、数据库以及表的元信息、procedure 状态等内部状态。在集群模式下，此目录不存在，因为所有这些状态（包括区域路由信息）都保存在 `Metasrv` 中。 +- `data`: 存储 GreptimeDB 的实际的时间序列数据和索引文件。如果要自定义此路径，请参阅 [存储选项](../deployments/configuration.md#storage-options)。该目录按照 catalog 和 schema 的两级结构组织。 +- `logs`: GreptimeDB 日志文件目录。 +- `wal`: 预写日志文件目录。 +- `index_intermediate`: 索引构建和查询相关的的临时中间数据目录。 + +## 云存储 + +文件结构中的 `cluster` 和 `data` 目录可以存储在云存储中。请参考[存储选项](../deployments/configuration.md#存储选项)了解更多细节。 + +请注意，仅将 `data` 目录存储在对象存储中不足以确保数据可靠性和灾难恢复，`wal` 和 `metadata` 也需要考虑灾难恢复，更详细地请参阅[灾难恢复文档](/user-guide/administration/disaster-recovery/overview.md)。 + +## 多存储引擎支持 + +GreptimeDB 的另一个强大功能是可以为每张表单独选择存储引擎。例如，您可以将一些表存储在本地磁盘上，将另一些表存储在 Amazon S3 或 Google Cloud Storage 中，请参考 [create table](/reference/sql/create.md#create-table)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/why-greptimedb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/why-greptimedb.md new file mode 100644 index 000000000..c0c2e7124 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/concepts/why-greptimedb.md @@ -0,0 +1,97 @@ +--- +description: 介绍 GreptimeDB 的特点、设计原则和优势，包括统一指标、日志和事件，云原生设计，高性能和用户友好等。 +--- + +# Why GreptimeDB + +GreptimeDB 是一个云原生、分布式且开源的时序数据库，旨在处理、存储和分析海量的指标（metrics）、日志（logs）和事件（events）数据（链路 traces 也在计划中）。 +关于更多 GreptimeDB 创立背景和所能解决的行业痛点分析，欢迎先阅读[这篇文章](https://mp.weixin.qq.com/s/lTXXsBziCIjJJSCQEW-unw)。 + +我们的解决方案能更高效地管理海量的时间序列数据，并且能轻松处理时序数据的写入/查询和分析的混合负载需求。无论你的系统是在本地运行还是在云端，GreptimeDB 都可以轻松处理任何规模的负载。基于过去的经验，我们有信心为用户提供任何符合其需求的解决方案和服务。 + +我们在设计和开发 GreptimeDB 时遵循以下原则： + +- **统一指标、日志和事件**： 时序数据库应该涵盖广义的时序数据，能同时处理指标（metrics）、日志（logs）和事件（events）等时序数据，简化架构并降低用户的部署成本和使用成本。 +- **云原生**：从设计 GreptimeDB 的第一天起，其就被定位为一款完全利用云的基础设施和能力来运行和服务的云原生数据库，因此具有出色的可扩展性和容错性。 +- **用户友好**：我们明白开发者体验至关重要，GreptimeDB 的设计关键原则是对开发者友好。这不仅体现在开发、部署和运营方面，在与数据生态系统的无缝兼容性，以及不断完善的文档和社区指南方面，都无一不体现了 GreptimeDB 用户友好的特性。 +- **高性能**：处理时间序列数据的特性之一就是大规模的数据摄取、查询和分析。在高并发场景下依然持续进行性能优化也是我们设计 GreptimeDB 时的核心原则之一。 +- **灵活的架构**：通过抽象良好的分层和封装隔离，GreptimeDB 的部署形式可以满足从嵌入式、单机版、传统集群到云原生的各种环境。 + +![The architecture of GreptimeDB](/architecture-2.png) + +接下来，我们将逐一展开说明下这些设计原则。 + +## 统一指标、日志和事件 + +通过[时序表](./data-model)的模型设计、SQL 的原生支持，以及存算分离架构带来的混合负载，GreptimeDB 可以同时处理指标、日志和事件，增强不同时间序列数据之间的关联分析，并简化用户的架构、部署和 API。 + +阅读[SQL 示例](/user-guide/overview.md#sql-查询示例)以获取详细信息。 + + +## 云原生 + +GreptimeDB 专为云而生，充分利用云的优势，如弹性、可扩展性和高可用性。 + +![Storage/Compute Disaggregation, Compute/Compute separation](/storage-compute-disaggregation-compute-compute-separation.png) + +### 存算分离 + +在云中分离存储和计算资源有几个好处： + +- 存储和计算可以根据需求轻松地、独立地进行扩展 +- 数据可以写入价格较低的云存储服务，如阿里云 OSS、 AWS S3 或 Azure Blob Storage +- 可以使用 Serverless 容器自动且弹性地扩展计算资源 + +### 算算分离 + +算算分离能将不同工作负载的计算资源隔离开： + +- 隔离不同的计算资源，以避免因数据摄取（Data Ingestion）、实时查询以及数据压缩或降采样等任务产生的资源竞争 +- 在多个应用程序之间共享数据 +- 根据需求提供无限的并发扩展性 + +## 用户友好 + +### Time-Series Table，schemaless 设计 + +「GreptimeDB」结合了 Metric (Measurement/Tag/Field/Timestamp) 模型和关系数据模型（表），提供了一个名为 Time-Series Table 的新数据模型，该模型以行和列的形式呈现数据，将 Metric 中的标签和字段映射到列上，同时通过 `Time Index` 约束来指定时间索引所在列。 + +![Time-Series Table](/time-series-table.png) + +然而，在我们的设计中，对 Schema 的定义并非强制性的，而是更偏向于像 MongoDB 这样的数据库的 Schemaless 方式。当数据被写入时，表将被动态地自动创建，新的列（标签和字段）将也会自动被添加进表中。 + +### PromQL、SQL 和 Python + +GreptimeDB 支持 PromQL 和 SQL，它们都依赖于同一查询引擎。该引擎采用向量化执行，这种执行是并行和分布式的。 + +PromQL 是可观测领域流行的查询语言，用户可以通过 PromQL 查询汇总由 Prometheus 提供的实时的时序数据。与 SQL 相比，它在使用 Grafana 进行可视化和创建警报规则时要简单得多。GreptimeDB 通过解析 PromQL 转化为查询计划，然后由查询引擎优化和执行，从而原生地、高性能地支持 PromQL。 + +SQL 在分析时间跨度大或来自多个表的数据方面更为强大，例如多表连接查询。SQL 也方便于数据库管理。 + +Python 在数据科学家和 AI 专家中非常流行，GreptimeDB 允许在数据库中直接运行 Python 脚本。用户可以编写 Python 自定义函数（UDF）并使用 DataFrame API 来加速数据处理。 + +### 易于部署和维护 + +为简化部署和维护流程，GreptimeDB 为用户提供了 [K8s operator](https://github.com/GreptimeTeam/greptimedb-operator)、[命令行工具](https://github.com/GreptimeTeam/gtctl)、[内嵌式仪表板](https://github.com/GreptimeTeam/dashboard)以及其他有用的工具，方便轻松配置和管理自己的数据库。如果你需要全托管的云服务，我们也提供了基于 GreptimeDB 的格睿云 GreptimeCloud 数据库云服务方案。 + +### 易于集成 + +GreptimeDB 支持多种协议，包括 MySQL，PostgreSQL，InfluxDB，OpenTSDB，Prometheus RemoteStorage 和高性能的 gRPC 等标准开放协议，尽可能的降低数据库接入门槛。此外，我们还为各种编程语言提供了 SDK，例如 Java，Go，Erlang 等。我们持续集成和连接生态系统中的开源软件，以提升开发者的体验。 + +## 高性能 + +就性能优化而言，GreptimeDB 利用 LSM Tree、数据分片和 基于 Quorum 的 WAL 设计等不同技术，来解决大规模时间序列数据的写入工作。 + +GreptimeDB 还通过列式存储、自适应压缩算法和智能索引，来降低存储成本，并解决时间序列数据的高基数问题。 + +强大而高效的查询引擎支持向量化执行，查询可以充分利用索引并分布式并行执行。 + +## 灵活的架构 + +通过模块化和分层设计，不同的模块和组件可以独立地开启、组合或分离。例如，我们可以将 Frontend、Datanode 和 Metasrv 合并为一个独立的二进制文件，并且我们也可以独立地为每个表启用或禁用 WAL。 + +这种灵活的架构设计让 GreptimeDB 能在使用相同的 API 编程接口和控制面的条件下，满足从边缘到云各种场景中的部署和使用需求。 + +## 小结 + +随着时间序列数据的管理和分析需求不断增长，我们相信 GreptimeDB 能够提供一种高效、可扩展和用户友好的解决方案。我们将在 6 月初推出分布式可用的版本 v0.3，无论你的应用场景是什么，我们都有信心为您提供满足需求的服务，也期待任何反馈和建议，以便我们不断改进我们的产品和服务。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/expression.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/expression.md new file mode 100644 index 000000000..f0d9140a6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/expression.md @@ -0,0 +1,27 @@ +--- +description: 列出了 GreptimeDB 中 flow 支持的聚合函数和标量函数。 +--- + +# 表达式 + +## 聚合函数 + +此处列出了 flow 中所有支持的聚合函数。 + +- `count(column)`: 行数。 +- `sum(column)`: 列的和。 +- `avg(column)`: 列的平均值。 +- `min(column)`: 列的最小值。 +- `max(column)`: 列的最大值。 + +未来将添加更多聚合函数。 + +## Scalar functions + +Flow 支持大多数 datafusion 中的标量函数，有关支持的标量函数的完整列表，请参见[datafusion](/reference/sql/functions/df-functions.md#scalar-functions)。 + +以下是一些 flow 中最常用的标量函数： + +- [`date_bin`](/reference/sql/functions/df-functions.md#date_bin): calculate time intervals and returns the start of the interval nearest to the specified timestamp. +- [`date_trunc`](/reference/sql/functions/df-functions.md#date_trunc): truncate a timestamp value to a specified precision. +- [`trunc`](/reference/sql/functions/df-functions.md#trunc): truncate a number to a whole number or truncated to the specified decimal places. \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/manage-flow.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/manage-flow.md new file mode 100644 index 000000000..40a134438 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/manage-flow.md @@ -0,0 +1,220 @@ +--- +description: 介绍如何在 GreptimeDB 中创建和删除 flow，包括创建 sink 表、flow 的 SQL 语法和示例。 +--- + +# 管理 Flows + +每一个 `flow` 是 GreptimeDB 中的一个持续聚合查询。 +它根据传入的数据持续更新并聚合数据。 +本文档描述了如何创建和删除一个 flow。 + +## 创建输入表 + +在创建 `flow` 之前，你需要先创建一张输入表来存储原始的输入数据，比如： +```sql +CREATE TABLE temp_sensor_data ( + sensor_id INT, + loc STRING, + temperature DOUBLE, + ts TIMESTAMP TIME INDEX, + PRIMARY KEY(sensor_id, loc) +); +``` +但是如果你不想存储输入数据，可以在创建输入表时设置表选项 `WITH ('ttl' = 'instant')` 如下： +```sql +CREATE TABLE temp_sensor_data ( + sensor_id INT, + loc STRING, + temperature DOUBLE, + ts TIMESTAMP TIME INDEX, + PRIMARY KEY(sensor_id, loc) +) WITH ('ttl' = 'instant'); +``` + +将 `ttl` 设置为 `'instant'` 会使得输入表成为一张临时的表，也就是说它会自动丢弃一切插入的数据，而表本身一直会是空的，插入数据只会被送到 `flow` 任务处用作计算用途。 + +## 创建 sink 表 + +在创建 flow 之前，你需要有一个 sink 表来存储 flow 生成的聚合数据。 +虽然它与常规的时间序列表相同，但有一些重要的注意事项： + +- **列的顺序和类型**：确保 sink 表中列的顺序和类型与 flow 查询结果匹配。 +- **时间索引**：为 sink 表指定 `TIME INDEX`，通常使用时间窗口函数生成的时间列。 +- **将 `update_at` 指定为 schema 的最后一列**：flow 会自动将数据的更新时间写入 `update_at` 列。请确保此列是 sink 表模式中的最后一列。 +- **Tag**：使用 `PRIMARY KEY` 指定 Tag，与 time index 一起作为行数据的唯一标识，并优化查询性能。 + +例如： + +```sql +/* 创建 sink 表 */ +CREATE TABLE temp_alerts ( + sensor_id INT, + loc STRING, + max_temp DOUBLE, + time_window TIMESTAMP TIME INDEX, + update_at TIMESTAMP, + PRIMARY KEY(sensor_id, loc) +); + +CREATE FLOW temp_monitoring +SINK TO temp_alerts +AS +SELECT + sensor_id, + loc, + max(temperature) AS max_temp, + date_bin(INTERVAL '10 seconds', ts) AS time_window +FROM temp_sensor_data +GROUP BY + sensor_id, + loc, + time_window +HAVING max_temp > 100; +``` + +sink 表包含列 `sensor_id`、`loc`、`max_temp`、`time_window` 和 `update_at`。 + +- 前四列分别对应 flow 的查询结果列 `sensor_id`、`loc`、`max(temperature)` 和 `date_bin(INTERVAL '10 seconds', ts)`。 +- `time_window` 列被指定为 sink 表的 `TIME INDEX`。 +- `update_at` 列是 schema 中的最后一列，用于存储数据的更新时间。 +- 最后的 `PRIMARY KEY` 指定 `sensor_id` 和 `loc` 作为 Tag 列。 + 这意味着 flow 将根据 Tag `sensor_id` 和 `loc` 以及时间索引 `time_window` 插入或更新数据。 + +## 创建 flow + +创建 flow 的语法是： + +```sql +CREATE [ OR REPLACE ] FLOW [ IF NOT EXISTS ] +SINK TO +[ EXPIRE AFTER ] +[ COMMENT '' ] +AS +; +``` + +当指定 `OR REPLACE` 时，如果已经存在同名的 flow，它将被更新为新 flow。请注意，这仅影响 flow 任务本身，source 表和 sink 表将不会被更改。当指定 `IF NOT EXISTS` 时，如果 flow 已经存在，它将不执行任何操作，而不是报告错误。还需要注意的是，`OR REPLACE` 不能与 `IF NOT EXISTS` 一起使用。 + +- `flow-name` 是目录级别的唯一标识符。 +- `sink-table-name` 是存储聚合数据的表名。 + 它可以是一个现有的表或一个新表。如果目标表不存在，`flow` 将创建目标表。 + +- `EXPIRE AFTER` 是一个可选的时间间隔，用于从 Flow 引擎中过期数据。 + 有关更多详细信息，请参考 [`EXPIRE AFTER`](#expire-after-语句) 部分。 +- `COMMENT` 是 flow 的描述。 +- `SQL` 部分定义了用于持续聚合的查询。 + 它定义了为 flow 提供数据的源表。 + 每个 flow 可以有多个源表。 + 有关详细信息，请参考[编写查询](#编写-sql-查询) 部分。 + +一个创建 flow 的简单示例： + +```sql +CREATE FLOW IF NOT EXISTS my_flow +SINK TO my_sink_table +EXPIRE AFTER INTERVAL '1 hour' +COMMENT 'My first flow in GreptimeDB' +AS +SELECT + max(temperature) as max_temp, + date_bin(INTERVAL '10 seconds', ts) as time_window, +FROM temp_sensor_data +GROUP BY time_window; +``` + +创建的 flow 将每 10 秒计算一次 `max(temperature)` 并将结果存储在 `my_sink_table` 中。 +所有在 1 小时内的数据都将用于 flow 计算。 + +### `EXPIRE AFTER` 子句 + +`EXPIRE AFTER` 子句指定数据将在 flow 引擎中过期的时间间隔。 +此过期仅影响 flow 引擎中的数据，不影响 source 表中的数据。 + +当 flow 引擎处理聚合操作（`update_at` 时间）时， +时间索引早于指定间隔的数据将过期。 + +例如，如果 flow 引擎在 10:00:00 处理聚合，并且设置了 `INTERVAL '1 hour'`， +则早于 09:00:00 的数据将过期。 +只有从 09:00:00 开始的数据将用于聚合。 + +### 编写 SQL 查询 + +flow 的 `SQL` 部分类似于标准的 `SELECT` 子句，但有一些不同之处。查询的语法如下： + +```sql +SELECT AGGR_FUNCTION(column1, column2,..), TIME_WINDOW_FUNCTION() as time_window FROM GROUP BY time_window; +``` + +在 `SELECT` 关键字之后只允许以下类型的表达式： +- 聚合函数：有关详细信息，请参阅[表达式](./expression.md)文档。 +- 时间窗口函数：有关详细信息，请参阅[定义时间窗口](#define-time-window)部分。 +- 标量函数：例如 `col`、`to_lowercase(col)`、`col + 1` 等。这部分与 GreptimeDB 中的标准 `SELECT` 子句相同。 + +查询语法中的其他部分需要注意以下几点： +- 必须包含一个 `FROM` 子句以指定 source 表。由于目前不支持 join 子句，因此只能聚合来自单个表的列。 +- 支持 `WHERE` 和 `HAVING` 子句。`WHERE` 子句在聚合之前过滤数据，而 `HAVING` 子句在聚合之后过滤数据。 +- `DISTINCT` 目前仅适用于 `SELECT DISTINCT column1 ..` 语法。它用于从结果集中删除重复行。`SELECT count(DISTINCT column1) ...` 尚不可用，但将来会添加。 +- `GROUP BY` 子句的工作方式与标准查询相同，即按指定列对数据进行分组，在其中指定时间窗口列对于持续聚合场景至关重要。 + `GROUP BY` 中的其他表达式可以是 literal、列名或 scalar 表达式。 +- 不支持`ORDER BY`、`LIMIT` 和 `OFFSET`。 + +有关如何在实时分析、监控和仪表板中使用持续聚合的更多示例，请参阅[用例示例](./usecase-example.md)。 + +### 定义时间窗口 + +时间窗口是持续聚合查询的重要属性。 +它定义了数据在流中的聚合方式。 +这些窗口是左闭右开的区间。 + +时间窗口对应于时间范围。 +source 表中的数据将根据时间索引列映射到相应的窗口。 +时间窗口也是聚合表达式计算的范围，因此每个时间窗口将在结果表中生成一行。 + +你可以在 `SELECT` 关键字之后使用 `date_bin()` 来定义固定的时间窗口。 +例如： + +```sql +SELECT + max(temperature) as max_temp, + date_bin(INTERVAL '10 seconds', ts) as time_window +FROM temp_sensor_data +GROUP BY time_window; +``` + +在此示例中，`date_bin(INTERVAL '10 seconds', ts)` 函数创建从 UTC 00:00:00 开始的 10 秒时间窗口。 +`max(temperature)` 函数计算每个时间窗口内的最大温度值。 + +有关该函数行为的更多详细信息， +请参阅 [`date_bin`](/reference/sql/functions/df-functions.md#date_bin)。 + +:::tip 提示 +目前，flow 的内部状态（例如记录当前计数的 `count(col)` 的累加值）没有持久存储。 +为了在内部状态故障时尽量减少数据丢失，建议使用较小的时间窗口。 + +这种内部状态丢失不会影响 sink 表中的现有数据。 +::: + +## 刷新 flow + +当 source 表中有新数据到达时，flow 引擎会在 1 秒内自动处理聚合操作。 +但你依然可以使用 `ADMIN FLUSH_FLOW` 命令手动触发 flow 引擎立即执行聚合操作。 + +```sql +ADMIN FLUSH_FLOW('') +``` + +## 删除 flow + +请使用以下 `DROP FLOW` 子句删除 flow： + +To delete a flow, use the following `DROP FLOW` clause: + +```sql +DROP FLOW [IF EXISTS] +``` + +例如： + +```sql +DROP FLOW IF EXISTS my_flow; +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/overview.md new file mode 100644 index 000000000..7d3b552d9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/overview.md @@ -0,0 +1,151 @@ +--- +description: GreptimeDB 提供持续聚合功能，允许实时聚合数据，适用于实时计算和查询总和、平均值等。本文介绍了持续聚合的基本概念、快速开始示例以及如何检查和验证聚合结果。 +--- + +# 概述 + +GreptimeDB 提供了一个持续聚合功能，允许你实时聚合数据。这个功能在当你需要实时计算和查询总和、平均值或其他聚合时非常有用。持续聚合功能由 Flow 引擎提供。它不断地基于传入的数据更新聚合数据并将其实现。因此，你可以将其视为一个聪明的物化视图，它知道何时更新结果视图表以及如何以最小的努力更新它。一些常见的用例包括： + +- 下采样数据点，使用如平均池化等方法减少存储和分析的数据量 +- 提供近实时分析，提供可操作的信息 + + +当你将数据插入 source 表时，数据也会被发送到 Flow 引擎并存储在其中。 +Flow 引擎通过时间窗口计算聚合并将结果存储在目标表中。 +整个过程如下图所示： + +![Continuous Aggregation](/flow-ani.svg) + +## 快速开始示例 + +以下是持续聚合查询的一个完整示例。 + + +这个例子是根据输入表中的数据计算一系列统计数据，包括一分钟时间窗口内的总日志数、最小大小、最大大小、平均大小以及大小大于 550 的数据包数。 + +首先，创建一个 source 表 `ngx_access_log` 和一个 sink 表 `ngx_statistics`，如下所示： + +```sql +CREATE TABLE `ngx_access_log` ( + `client` STRING NULL, + `ua_platform` STRING NULL, + `referer` STRING NULL, + `method` STRING NULL, + `endpoint` STRING NULL, + `trace_id` STRING NULL FULLTEXT, + `protocol` STRING NULL, + `status` SMALLINT UNSIGNED NULL, + `size` DOUBLE NULL, + `agent` STRING NULL, + `access_time` TIMESTAMP(3) NOT NULL, + TIME INDEX (`access_time`) +) +WITH( + append_mode = 'true' +); +``` + +```sql +CREATE TABLE `ngx_statistics` ( + `status` SMALLINT UNSIGNED NULL, + `total_logs` BIGINT NULL, + `min_size` DOUBLE NULL, + `max_size` DOUBLE NULL, + `avg_size` DOUBLE NULL, + `high_size_count` BIGINT NULL, + `time_window` TIMESTAMP time index, + `update_at` TIMESTAMP NULL, + PRIMARY KEY (`status`) +); +``` + +然后创建名为 `ngx_aggregation` 的 flow 任务，包括 `count`、`min`、`max`、`avg` `size` 列的聚合函数，以及大于 550 的所有数据包的大小总和。聚合是在 `access_time` 列的 1 分钟固定窗口中计算的，并且还按 `status` 列分组。因此，你可以实时了解有关数据包大小和对其的操作的信息，例如，如果 `high_size_count` 在某个时间点变得太高，你可以进一步检查是否有任何问题，或者如果 `max_size` 列在 1 分钟时间窗口内突然激增，你可以尝试定位该数据包并进一步检查。 + +```sql +CREATE FLOW ngx_aggregation +SINK TO ngx_statistics +AS +SELECT + status, + count(client) AS total_logs, + min(size) as min_size, + max(size) as max_size, + avg(size) as avg_size, + sum(case when `size` > 550 then 1 else 0 end) as high_size_count, + date_bin(INTERVAL '1 minutes', access_time) as time_window, +FROM ngx_access_log +GROUP BY + status, + time_window; +``` + +要检查持续聚合是否正常工作，首先插入一些数据到源表 `ngx_access_log` 中。 + +```sql +INSERT INTO ngx_access_log +VALUES + ("android", "Android", "referer", "GET", "/api/v1", "trace_id", "HTTP", 200, 1000, "agent", "2021-07-01 00:00:01.000"), + ("ios", "iOS", "referer", "GET", "/api/v1", "trace_id", "HTTP", 200, 500, "agent", "2021-07-01 00:00:30.500"), + ("android", "Android", "referer", "GET", "/api/v1", "trace_id", "HTTP", 200, 600, "agent", "2021-07-01 00:01:01.000"), + ("ios", "iOS", "referer", "GET", "/api/v1", "trace_id", "HTTP", 404, 700, "agent", "2021-07-01 00:01:01.500"); +``` + +则 `ngx_access_log` 表将被增量更新以包含以下数据： + +```sql +SELECT * FROM ngx_statistics; +``` + +```sql + status | total_logs | min_size | max_size | avg_size | high_size_count | time_window | update_at +--------+------------+----------+----------+----------+-----------------+----------------------------+---------------------------- + 200 | 2 | 500 | 1000 | 750 | 1 | 2021-07-01 00:00:00.000000 | 2024-07-24 08:36:17.439000 + 200 | 1 | 600 | 600 | 600 | 1 | 2021-07-01 00:01:00.000000 | 2024-07-24 08:36:17.439000 + 404 | 1 | 700 | 700 | 700 | 1 | 2021-07-01 00:01:00.000000 | 2024-07-24 08:36:17.439000 +(3 rows) +``` + +尝试向 `ngx_access_log` 表中插入更多数据： + +```sql +INSERT INTO ngx_access_log +VALUES + ("android", "Android", "referer", "GET", "/api/v1", "trace_id", "HTTP", 200, 500, "agent", "2021-07-01 00:01:01.000"), + ("ios", "iOS", "referer", "GET", "/api/v1", "trace_id", "HTTP", 404, 800, "agent", "2021-07-01 00:01:01.500"); +``` + +结果表 `ngx_statistics` 将被增量更新，注意 `max_size`、`avg_size` 和 `high_size_count` 是如何更新的： + +```sql +SELECT * FROM ngx_statistics; +``` + +```sql + status | total_logs | min_size | max_size | avg_size | high_size_count | time_window | update_at +--------+------------+----------+----------+----------+-----------------+----------------------------+---------------------------- + 200 | 2 | 500 | 1000 | 750 | 1 | 2021-07-01 00:00:00.000000 | 2024-07-24 08:36:17.439000 + 200 | 2 | 500 | 600 | 550 | 1 | 2021-07-01 00:01:00.000000 | 2024-07-24 08:36:46.495000 + 404 | 2 | 700 | 800 | 750 | 2 | 2021-07-01 00:01:00.000000 | 2024-07-24 08:36:46.495000 +(3 rows) +``` + +`ngx_statistics` 表中的列解释如下： + +- `status`: HTTP 响应的状态码。 +- `total_logs`: 相同状态码的日志总数。 +- `min_size`: 相同状态码的数据包的最小大小。 +- `max_size`: 相同状态码的数据包的最大大小。 +- `avg_size`: 相同状态码的数据包的平均大小。 +- `high_size_count`: 包大小大于 550 的数据包数。 +- `time_window`: 聚合的时间窗口。 +- `update_at`: 聚合结果更新的时间。 + +## 下一步 + +恭喜你已经初步了解了持续聚合功能。 +请参考以下章节了解更多： + + +- [用例](./usecase-example.md) 提供了更多关于如何在实时分析、监控和仪表板中使用持续聚合的示例。 +- [管理 Flow](./manage-flow.md) 描述了如何创建和删除 flow。你的每个持续聚合查询都是一个 flow。 +- [表达式](./expression.md) 是持续聚合查询中可用表达式。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/usecase-example.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/usecase-example.md new file mode 100644 index 000000000..6b110fa7f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/continuous-aggregation/usecase-example.md @@ -0,0 +1,265 @@ +--- +description: 持续聚合的用例示例，包括实时分析、实时监控和实时仪表盘的详细示例。 +--- + +# 用例 +持续聚合的三个主要用例示例如下： + +1. **实时分析**：一个实时分析平台，不断聚合来自事件流的数据，提供即时洞察，同时可选择将数据降采样到较低分辨率。例如，此系统可以编译来自高频日志事件流（例如，每毫秒发生一次）的数据，以提供每分钟的请求数、平均响应时间和每分钟的错误率等最新洞察。 + +2. **实时监控**：一个实时监控系统，不断聚合来自事件流的数据，根据聚合数据提供实时警报。例如，此系统可以处理来自传感器事件流的数据，以提供当温度超过某个阈值时的实时警报。 + +3. **实时仪表盘**：一个实时仪表盘，显示每分钟的请求数、平均响应时间和每分钟的错误数。此仪表板可用于监控系统的健康状况，并检测系统中的任何异常。 + +在所有这些用例中，持续聚合系统不断聚合来自事件流的数据，并根据聚合数据提供实时洞察和警报。系统还可以将数据降采样到较低分辨率，以减少存储和处理的数据量。这使得系统能够提供实时洞察和警报，同时保持较低的数据存储和处理成本。 + +## 实时分析示例 + +请参考[概述](/user-guide/continuous-aggregation/overview.md#quick-start-with-an-example)中的实时分析示例。 +该示例用于计算日志的总数、数据包大小的最小、最大和平均值，以及大小大于 550 的数据包数量按照每个状态码在 1 分钟固定窗口中的实时分析。 + +另一个实时分析的示例是从 `ngx_access_log` 表中查询所有不同的国家。 +你可以使用以下查询按时间窗口对国家进行分组： + +```sql +/* source 表 */ +CREATE TABLE ngx_access_log ( + client STRING, + country STRING, + access_time TIMESTAMP TIME INDEX, + PRIMARY KEY(client) +); + +/* sink 表 */ +CREATE TABLE ngx_country ( + country STRING, + time_window TIMESTAMP TIME INDEX, + update_at TIMESTAMP, + PRIMARY KEY(country) +); + +/* 创建 flow 任务以计算不同的国家 */ +CREATE FLOW calc_ngx_country +SINK TO ngx_country +AS +SELECT + DISTINCT country, + date_bin(INTERVAL '1 hour', access_time) as time_window, +FROM ngx_access_log +GROUP BY + country, + time_window; +``` + +上述查询将 `ngx_access_log` 表中的数据聚合到 `ngx_country` 表中，它计算了每个时间窗口内的不同国家。 +`date_bin` 函数用于将数据聚合到一小时的间隔中。 +`ngx_country` 表将不断更新聚合数据，以监控访问系统的不同国家。 + +你可以向 source 表 `ngx_access_log` 插入一些数据： + +```sql +INSERT INTO ngx_access_log VALUES + ("client1", "US", "2022-01-01 01:00:00"), + ("client2", "US", "2022-01-01 01:00:00"), + ("client3", "UK", "2022-01-01 01:00:00"), + ("client4", "UK", "2022-01-01 02:00:00"), + ("client5", "CN", "2022-01-01 02:00:00"), + ("client6", "CN", "2022-01-01 02:00:00"), + ("client7", "JP", "2022-01-01 03:00:00"), + ("client8", "JP", "2022-01-01 03:00:00"), + ("client9", "KR", "2022-01-01 03:00:00"), + ("client10", "KR", "2022-01-01 03:00:00"); +``` + +等待一秒钟，让 flow 将结果写入 sink 表，然后查询： + +```sql +select * from ngx_country; +``` + +```sql ++---------+---------------------+----------------------------+ +| country | time_window | update_at | ++---------+---------------------+----------------------------+ +| CN | 2022-01-01 02:00:00 | 2024-10-22 08:17:47.906000 | +| JP | 2022-01-01 03:00:00 | 2024-10-22 08:17:47.906000 | +| KR | 2022-01-01 03:00:00 | 2024-10-22 08:17:47.906000 | +| UK | 2022-01-01 01:00:00 | 2024-10-22 08:17:47.906000 | +| UK | 2022-01-01 02:00:00 | 2024-10-22 08:17:47.906000 | +| US | 2022-01-01 01:00:00 | 2024-10-22 08:17:47.906000 | ++---------+---------------------+----------------------------+ +``` + +## 实时监控示例 + +假设你有一个来自温度传感器网络的传感器事件流，你希望实时监控这些事件。 +传感器事件包含传感器 ID、温度读数、读数的时间戳和传感器的位置等信息。 +你希望不断聚合这些数据，以便在温度超过某个阈值时提供实时告警。持续聚合的查询如下： + +```sql +/* 创建 source 表 */ +CREATE TABLE temp_sensor_data ( + sensor_id INT, + loc STRING, + temperature DOUBLE, + ts TIMESTAMP TIME INDEX +); + +/* 创建 sink 表 */ +CREATE TABLE temp_alerts ( + sensor_id INT, + loc STRING, + max_temp DOUBLE, + time_window TIMESTAMP TIME INDEX, + update_at TIMESTAMP, + PRIMARY KEY(sensor_id, loc) +); + +CREATE FLOW temp_monitoring +SINK TO temp_alerts +AS +SELECT + sensor_id, + loc, + max(temperature) as max_temp, + date_bin(INTERVAL '10 seconds', ts) as time_window, +FROM temp_sensor_data +GROUP BY + sensor_id, + loc, + time_window +HAVING max_temp > 100; +``` + +上述查询将 `temp_sensor_data` 表中的数据不断聚合到 `temp_alerts` 表中。 +它计算每个传感器和位置的最大温度读数，并过滤出最大温度超过 100 度的数据。 +`temp_alerts` 表将不断更新聚合数据， +当温度超过阈值时提供实时警报（即 `temp_alerts` 表中的新行）。 + +现在我们已经创建了 flow 任务，可以向 source 表 `temp_sensor_data` 插入一些数据： + +```sql +INSERT INTO temp_sensor_data VALUES + (1, "room1", 98.5, "2022-01-01 00:00:00"), + (2, "room2", 99.5, "2022-01-01 00:00:01"); +``` + +表现在应该是空的，等待至少一秒钟让 flow 将结果更新到输出表： + +```sql +SELECT * FROM temp_alerts; +``` + +```sql +Empty set (0.00 sec) +``` + +插入一些会触发警报的数据： + +```sql +INSERT INTO temp_sensor_data VALUES + (1, "room1", 101.5, "2022-01-01 00:00:02"), + (2, "room2", 102.5, "2022-01-01 00:00:03"); +``` + +等待至少一秒钟，让 flow 将结果更新到输出表： + +```sql +SELECT * FROM temp_alerts; +``` + +```sql ++-----------+-------+----------+---------------------+----------------------------+ +| sensor_id | loc | max_temp | time_window | update_at | ++-----------+-------+----------+---------------------+----------------------------+ +| 1 | room1 | 101.5 | 2022-01-01 00:00:00 | 2024-10-22 09:13:07.535000 | +| 2 | room2 | 102.5 | 2022-01-01 00:00:00 | 2024-10-22 09:13:07.535000 | ++-----------+-------+----------+---------------------+----------------------------+ +``` + +## 实时仪表盘 + +假设你需要一个条形图来显示每个状态码的包大小分布，以监控系统的健康状况。持续聚合的查询如下： + +```sql +/* 创建 source 表 */ +CREATE TABLE ngx_access_log ( + client STRING, + stat INT, + size INT, + access_time TIMESTAMP TIME INDEX +); +/* 创建 sink 表 */ +CREATE TABLE ngx_distribution ( + stat INT, + bucket_size INT, + total_logs BIGINT, + time_window TIMESTAMP TIME INDEX, + update_at TIMESTAMP, + PRIMARY KEY(stat, bucket_size) +); +/* 创建 flow 任务以计算每个状态码的包大小分布 */ +CREATE FLOW calc_ngx_distribution SINK TO ngx_distribution AS +SELECT + stat, + trunc(size, -1)::INT as bucket_size, + count(client) AS total_logs, + date_bin(INTERVAL '1 minutes', access_time) as time_window, +FROM + ngx_access_log +GROUP BY + stat, + time_window, + bucket_size; +``` + +该查询将 `ngx_access_log` 表中的数据汇总到 `ngx_distribution` 表中。 +它计算每个时间窗口内的状态代码和数据包大小存储桶（存储桶大小为 10，由 `trunc` 指定，第二个参数为 -1）的日志总数。 +`date_bin` 函数将数据分组为一分钟的间隔。 +因此，`ngx_distribution` 表会不断更新， +提供每个状态代码的数据包大小分布的实时洞察。 + +现在我们已经创建了 flow 任务，可以向 source 表 `ngx_access_log` 插入一些数据： + +```sql +INSERT INTO ngx_access_log VALUES + ("cli1", 200, 100, "2022-01-01 00:00:00"), + ("cli2", 200, 104, "2022-01-01 00:00:01"), + ("cli3", 200, 120, "2022-01-01 00:00:02"), + ("cli4", 200, 124, "2022-01-01 00:00:03"), + ("cli5", 200, 140, "2022-01-01 00:00:04"), + ("cli6", 404, 144, "2022-01-01 00:00:05"), + ("cli7", 404, 160, "2022-01-01 00:00:06"), + ("cli8", 404, 164, "2022-01-01 00:00:07"), + ("cli9", 404, 180, "2022-01-01 00:00:08"), + ("cli10", 404, 184, "2022-01-01 00:00:09"); +``` + +等待至少一秒钟，让 flow 将结果更新到 sink 表： + +```sql +SELECT * FROM ngx_distribution; +``` + +```sql ++------+-------------+------------+---------------------+----------------------------+ +| stat | bucket_size | total_logs | time_window | update_at | ++------+-------------+------------+---------------------+----------------------------+ +| 200 | 100 | 2 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 200 | 120 | 2 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 200 | 140 | 1 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 404 | 140 | 1 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 404 | 160 | 2 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 404 | 180 | 2 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | ++------+-------------+------------+---------------------+----------------------------+ +``` + +## 总结 + +持续聚合是实时分析、监控和仪表盘的强大工具。 +它允许你不断聚合来自事件流的数据，并根据聚合数据提供实时洞察和警报。 +通过将数据降采样到较低分辨率，你可以减少存储和处理的数据量， +从而更容易提供实时洞察和警报，同时保持较低的数据存储和处理成本。 +持续聚合是任何实时数据处理系统的关键组件，可以在各种用例中使用， +以提供基于流数据的实时洞察和警报。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/authentication/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/authentication/overview.md new file mode 100644 index 000000000..fde03cabc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/authentication/overview.md @@ -0,0 +1,12 @@ +--- +description: GreptimeDB 的身份验证概述，介绍了多种用户 Provider 的实现，包括静态用户 Provider 和 LDAP 用户 Provider。 +--- + +# 概述 + +当客户端尝试连接到数据库时，将会进行身份验证。GreptimeDB 通过 “user provider” 进行身份验证。GreptimeDB 中有多种 user +provider 实现： + +- [Static User Provider](./static.md)：一个简单的内置 user provider 实现，从静态文件中查找用户。 +- [LDAP User Provider](/enterprise/deployments/authentication.md)：**企业版功能**，使用外部 LDAP 服务进行用户身份验证。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/authentication/static.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/authentication/static.md new file mode 100644 index 000000000..bfd43d498 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/authentication/static.md @@ -0,0 +1,27 @@ +--- +description: 介绍了 GreptimeDB 的静态用户配置，允许通过配置文件设置固定帐户进行身份验证。 +--- + +# Static User Provider + +GreptimeDB 提供了简单的内置身份验证机制，允许用户配置一个固定的帐户以方便使用，或者配置一个帐户文件以支持多个用户帐户。通过传入文件，GreptimeDB 会加载其中的所有用户。 + +GreptimeDB使用`=`作为分隔符，读取文件内每行中的用户和密码。例如： + +``` +greptime_user=greptime_pwd +alice=aaa +bob=bbb +``` + +接下来在启动服务端时添加 `--user-provider` 参数： + +```shell +./greptime standalone start --user-provider=static_user_provider:file: +``` + +这样，用户 `alice` 和 `bob` 的账户信息就会被加载到 GreptimeDB 中。你可以使用这些用户连接 GreptimeDB。 + +:::tip 注意 +文件的内容只会在启动时被加载到数据库中，在数据库运行时修改或追加的内容不会生效。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/configuration.md new file mode 100644 index 000000000..4789c2cd4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/configuration.md @@ -0,0 +1,815 @@ +--- +description: GreptimeDB 的配置指南，介绍了命令行选项、配置文件、环境变量、协议选项、存储选项、WAL 选项、日志选项等详细配置方法。 +--- + +# 配置 GreptimeDB + +GreptimeDB 提供了层次化的配置能力，按照下列优先顺序来生效配置（每个项目都会覆盖下面的项目）： + +- Greptime 命令行选项 +- 配置文件选项 +- 环境变量 +- 默认值 + +你只需要设置所需的配置项。 +GreptimeDB 将为未配置的任何设置分配默认值。 + +## 如何设置配置项 + +### Greptime 命令行选项 + +你可以使用命令行参数指定多个配置项。 +例如，以配置的 HTTP 地址启动 GreptimeDB 的独立模式： + +```shell +greptime standalone start --http-addr 127.0.0.1:4000 +``` + +有关 Greptime 命令行支持的所有选项，请参阅 [GreptimeDB 命令行界面](/reference/command-lines.md)。 + +### 配置文件选项 + +你可以在 TOML 文件中指定配置项。 +例如，创建一个名为 `standalone.example.toml` 的配置文件，如下所示： + +```toml +[storage] +type = "File" +data_home = "/tmp/greptimedb/" +``` + +然后使用命令行参数 `-c [file_path]` 指定配置文件。 + +```sh +greptime [standalone | frontend | datanode | metasrv] start -c config/standalone.example.toml +``` + +例如以 standalone 模式启动 GreptimeDB： + +```bash +greptime standalone start -c standalone.example.toml +``` + +#### 示例文件 + +以下是每个 GreptimeDB 组件的示例配置文件，包括所有可用配置项。 +在实际场景中，你只需要配置所需的选项，不需要像示例文件中那样配置所有选项。 + +- [独立模式](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/standalone.example.toml) +- [前端](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/frontend.example.toml) +- [数据节点](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/datanode.example.toml) +- [流节点](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/flownode.example.toml) +- [元服务](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/metasrv.example.toml) + +### 环境变量 + +配置文件中的每个项目都可以映射到环境变量。 +例如，使用环境变量设置数据节点的 `data_home` 配置项： + +```toml +# ... +[storage] +data_home = "/data/greptimedb" +# ... +``` + +使用以下 shell 命令以以下格式设置环境变量： + +``` +export GREPTIMEDB_DATANODE__STORAGE__DATA_HOME=/data/greptimedb +``` + +#### 环境变量规则 + +- 每个环境变量应具有组件前缀，例如： + + - `GREPTIMEDB_FRONTEND` + - `GREPTIMEDB_METASRV` + - `GREPTIMEDB_DATANODE` + - `GREPTIMEDB_STANDALONE` + +- 使用**双下划线 `__`**作为分隔符。例如，数据结构 `storage.data_home` 转换为 `STORAGE__DATA_HOME`。 + +环境变量还接受以逗号 `,` 分隔的列表，例如： + +``` +GREPTIMEDB_METASRV__META_CLIENT__METASRV_ADDRS=127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003 +``` + +### 协议选项 + +协议选项适用于 `frontend` 和 `standalone` 子命令，它指定了协议服务器地址和其他协议相关的选项。 + +下面的示例配置包含了所有协议选项的默认值。 +你可以在配置文件中更改这些值或禁用某些协议。 +例如禁用 OpenTSDB 协议支持，可以将 `enable` 参数设置为 `false`。 +请注意，为了保障数据库的正常工作，无法禁用 HTTP 和 gRPC 协议。 + +```toml +[http] +addr = "127.0.0.1:4000" +timeout = "30s" +body_limit = "64MB" + +[grpc] +addr = "127.0.0.1:4001" +runtime_size = 8 + +[mysql] +enable = true +addr = "127.0.0.1:4002" +runtime_size = 2 + +[mysql.tls] +mode = "disable" +cert_path = "" +key_path = "" + +[postgres] +enable = true +addr = "127.0.0.1:4003" +runtime_size = 2 + +[postgres.tls] +mode = "disable" +cert_path = "" +key_path = "" + +[opentsdb] +enable = true + +[influxdb] +enable = true + +[prom_store] +enable = true +``` + +下表描述了每个选项的详细信息： + +| 选项 | 键 | 类型 | 描述 | +| ---------- | ------------------ | ------ | ------------------------------------------------------------ | +| http | | | HTTP 服务器选项 | +| | addr | 字符串 | 服务器地址，默认为 "127.0.0.1:4000" | +| | timeout | 字符串 | HTTP 请求超时时间，默认为 "30s" | +| | body_limit | 字符串 | HTTP 最大体积大小，默认为 "64MB" | +| | is_strict_mode | 布尔值 | 是否启用协议的严格校验模式，启用会轻微影响性能，默认为 false | +| grpc | | | gRPC 服务器选项 | +| | addr | 字符串 | 服务器地址，默认为 "127.0.0.1:4001" | +| | runtime_size | 整数 | 服务器工作线程数量，默认为 8 | +| mysql | | | MySQL 服务器选项 | +| | enable | 布尔值 | 是否启用 MySQL 协议，默认为 true | +| | addr | 字符串 | 服务器地址，默认为 "127.0.0.1:4002" | +| | runtime_size | 整数 | 服务器工作线程数量，默认为 2 | +| influxdb | | | InfluxDB 协议选项 | +| | enable | 布尔值 | 是否在 HTTP API 中启用 InfluxDB 协议，默认为 true | +| opentsdb | | | OpenTSDB 协议选项 | +| | enable | 布尔值 | 是否启用 OpenTSDB 协议，默认为 true | +| prom_store | | | Prometheus 远程存储选项 | +| | enable | 布尔值 | 是否在 HTTP API 中启用 Prometheus 远程读写，默认为 true | +| | with_metric_engine | 布尔值 | 是否在 Prometheus 远程写入中使用 Metric Engine，默认为 true | +| postgres | | | PostgresSQL 服务器选项 | +| | enable | 布尔值 | 是否启用 PostgresSQL 协议，默认为 true | +| | addr | 字符串 | 服务器地址，默认为 "127.0.0.1:4003" | +| | runtime_size | 整数 | 服务器工作线程数量，默认为 2 | + +对 MySQL 和 Postgres 接口，我们支持 TLS 配置 + +| Option | Key | Type | Description | +|-------------------------------|-------------|---------|--------------------------------------------------| +| `mysql.tls` 或 `postgres.tls` | | | MySQL 或 Postgres 的 TLS 配置 | +| | `mode` | String | TLS 模式，支持 `disable`, `prefer` and `require` | +| | `cert_path` | String | TLS 证书文件路径 | +| | `key_path` | String | TLS 私钥文件路径 | +| | `watch` | Boolean | 监控文件变化，自动重新加载证书或私钥 | + + +### 存储选项 + +`存储`选项在 `datanode` 和 `standalone` 模式下有效，它指定了数据库数据目录和其他存储相关的选项。 + +GreptimeDB 支持将数据保存在本地文件系统， AWS S3 以及其兼容服务（比如 MinIO、digitalocean space、腾讯 COS、百度对象存储（BOS）等），Azure Blob Storage 和阿里云 OSS。 + +| 选项 | 键 | 类型 | 描述 | +| ------- | ----------------- | ------ | --------------------------------------------------- | +| storage | | | 存储选项 | +| | type | 字符串 | 存储类型，支持 "File"，"S3" 和 "Oss" 等. | +| File | | | 本地文件存储选项，当 type="File" 时有效 | +| | data_home | 字符串 | 数据库存储根目录，默认为 "/tmp/greptimedb" | +| S3 | | | AWS S3 存储选项，当 type="S3" 时有效 | +| | name | String | 存储提供商名字，默认为 `S3` | +| | bucket | 字符串 | S3 桶名称 | +| | root | 字符串 | S3 桶中的根路径 | +| | endpoint | 字符串 | S3 的 API 端点 | +| | region | 字符串 | S3 区域 | +| | access_key_id | 字符串 | S3 访问密钥 id | +| | secret_access_key | 字符串 | S3 秘密访问密钥 | +| Oss | | | 阿里云 OSS 存储选项，当 type="Oss" 时有效 | +| | name | String | 存储提供商名字，默认为 `Oss` | +| | bucket | 字符串 | OSS 桶名称 | +| | root | 字符串 | OSS 桶中的根路径 | +| | endpoint | 字符串 | OSS 的 API 端点 | +| | access_key_id | 字符串 | OSS 访问密钥 id | +| | secret_access_key | 字符串 | OSS 秘密访问密钥 | +| Azblob | | | Azure Blob 存储选项，当 type="Azblob" 时有效 | +| | name | String | 存储提供商名字，默认为 `Azblob` | +| | container | 字符串 | 容器名称 | +| | root | 字符串 | 容器中的根路径 | +| | endpoint | 字符串 | Azure Blob 存储的 API 端点 | +| | account_name | 字符串 | Azure Blob 存储的账户名 | +| | account_key | 字符串 | 访问密钥 | +| | sas_token | 字符串 | 共享访问签名 | +| Gsc | | | Google Cloud Storage 存储选项，当 type="Gsc" 时有效 | +| | name | String | 存储提供商名字，默认为 `Gsc` | +| | root | 字符串 | Gsc 桶中的根路径 | +| | bucket | 字符串 | Gsc 桶名称 | +| | scope | 字符串 | Gsc 权限 | +| | credential_path | 字符串 | Gsc 访问证书 | +| | endpoint | 字符串 | GSC 的 API 端点 | + +文件存储配置范例： + +```toml +[storage] +type = "File" +data_home = "/tmp/greptimedb/" +``` + +s3 配置范例： + +```toml +[storage] +type = "S3" +bucket = "test_greptimedb" +root = "/greptimedb" +access_key_id = "" +secret_access_key = "" +``` + +### 存储服务的 http 客户端 + +`[storage.http_client]` 设置了向存储服务发送请求的 http 客户端的各种配置。 + +仅当存储服务类型是 “S3”，“Oss”，“Azblob” 或 “Gcs” 时生效。 + +| Key | 类型 | 默认值 | 含义 | +|--------------------------|-----|------------|-------------------------------------------------------------| +| `pool_max_idle_per_host` | 数字 | 1024 | http 连接池中对每个 host 的最大空闲连接数。 | +| `connect_timeout` | 字符串 | “30s”（30秒） | http 客户端在进行连接时的超时 | +| `timeout` | 字符串 | “30s”（30秒） | 总的 http 请求超时，包括了从建立连接到接收完返回值为止的时间。也可视为一个请求从开始到结束的一个完整的截止时间。 | +| `pool_idle_timeout` | 字符串 | “90s”（90秒） | 对空闲连接进行保活（ "keep-alive" ）的超时。 | + +### 存储引擎提供商 + +`[[storage.providers]]` 用来设置存储引擎的提供商列表。基于这个配置，你可以为每张表指定不同的存储引擎，具体请参考 [create table](/reference/sql/create.md#create-table): + +```toml +# Allows using multiple storages +[[storage.providers]] +name = "S3" +type = "S3" +bucket = "test_greptimedb" +root = "/greptimedb" +access_key_id = "" +secret_access_key = "" + +[[storage.providers]] +name = "Gcs" +type = "Gcs" +bucket = "test_greptimedb" +root = "/greptimedb" +credential_path = "" +``` + +所有配置的这些存储引擎提供商的 `name` 都可以在创建表时用作 `storage` 选项。 + +对于同样提供商的存储，比如你希望使用不同 S3 bucket 来作为不同表的存储引擎，你就可以设置不同的 `name`，并在创建表的时候指定 `storage` 选项。 + +### 对象存储缓存 + +在使用 AWS S3、阿里云 OSS 或 Azure Blob Storage 等远程存储服务时，查询过程中获取数据通常会很耗时，尤其在公有云环境。为了解决这个问题，GreptimeDB 提供了本地缓存机制来加速重复数据的访问。 + +从 v0.11 版本开始，GreptimeDB 默认启用远程对象存储的本地文件缓存。默认的缓存目录位于 `{data_home}/object_cache`，读取和写入缓存容量都设置为 `5GiB`。 + +对于 v0.11 之前的版本，你需要通过在存储设置中配置 `cache_path` 来手动启用读取缓存： + +```toml +[storage] +type = "S3" +bucket = "test_greptimedb" +root = "/greptimedb" +access_key_id = "" +secret_access_key = "" +## 启用对象存储缓存 +cache_path = "/var/data/s3_read_cache" +cache_capacity = "5Gib" +``` + +`cache_path` 指定存储缓存文件的本地目录，而 `cache_capacity` 则决定缓存目录中允许的最大文件总大小（以字节为单位）。你可以通过将 `cache_path` 设置为空字符串来禁用读取缓存。 + +对于 v0.11 之前版本的写入缓存，你需要在 `[region_engine.mito]` 部分将 `enable_experimental_write_cache` 设置为 `true` 来启用： + +```toml +[[region_engine]] +[region_engine.mito] + +enable_experimental_write_cache = true +experimental_write_cache_path = "/var/data/s3_write_cache" +experimental_write_cache_size = "5GiB" +``` + +`experimental_write_cache_path` 的默认值是 `{data_home}/object_cache/write`。 +要禁用写入缓存，请将 `enable_experimental_write_cache` 设置为 `false`。 + +更详细的信息请参阅[性能调优技巧](/user-guide/administration/performance-tuning-tips)。 + + +### WAL 选项 + +datanode 和 standalone 在 `[wal]` 部分可以配置 Write-Ahead-Log 的对应参数： + +#### Local WAL + +```toml +[wal] +file_size = "256MB" +purge_threshold = "4GB" +purge_interval = "10m" +read_batch_size = 128 +sync_write = false +``` + +- `dir`: WAL 的日志目录， 当使用文件 `File` 存储的时候, 默认值为`{data_home}/wal` 。当使用对象存储的时候，必须明确指定。 +- `file_size`: 单个日志文件的最大大小，默认为 `256MB`。 +- `purge_threshold` 和 `purge_interval`: 控制清除任务的触发阈值和间隔 +- `sync_write`: 是否在写入每条日志的时候调用 l `fsync` 刷盘。 + +#### Remote WAL + +```toml +[wal] +provider = "kafka" +broker_endpoints = ["127.0.0.1:9092"] +max_batch_bytes = "1MB" +consumer_wait_timeout = "100ms" +backoff_init = "500ms" +backoff_max = "10s" +backoff_base = 2 +backoff_deadline = "5mins" +overwrite_entry_start_id = false +``` + +- `broker_endpoints`：Kafka 端点 +- `max_batch_bytes`：单个 producer batch 的最大值 +- `consumer_wait_timeout`：consumer 的等待超时时间 +- `backoff_init`：backoff 初始延迟 +- `backoff_max`：：backoff 最大延迟 +- `backoff_base`：：backoff 指数 +- `backoff_deadline`：重试的截止时间 +- `overwrite_entry_start_id`: 该选项确保在 Kafka 消息被误删除时，系统仍然能够成功重放内存表数据，而不会抛出超出范围（out-of-range）的错误。然而，启用此选项可能会导致意外的数据丢失，因为系统会跳过缺失的条目，而不是将其视为严重错误。 + +##### Remote WAL 鉴权 (Optional) + +```toml +[wal.sasl] +type = "SCRAM-SHA-512" +username = "user" +password = "secret" +``` + +Kafka 客户端 SASL 鉴权配置，支持的 SASL 机制 : `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`. + +##### Remote WAL TLS (Optional) + +```toml +[wal.tls] +server_ca_cert_path = "/path/to/server_cert" +client_cert_path = "/path/to/client_cert" +client_key_path = "/path/to/key" +``` + +Kafka 客户端 TLS 配置，支持 TLS（使用系统 CA 证书），TLS（使用特定 CA 证书），mTLS。 + +配置示例: + +**TLS (使用系统 CA 证书)** + +```toml +[wal.tls] +``` + +**TLS (使用特定 CA 证书)** + +```toml +[wal.tls] +server_ca_cert_path = "/path/to/server_cert" +``` + +**mTLS** + +```toml +[wal.tls] +server_ca_cert_path = "/path/to/server_cert" +client_cert_path = "/path/to/client_cert" +client_key_path = "/path/to/key" +``` + +### Logging 选项 + +`frontend`、`metasrv`、`datanode` 和 `standalone` 都可以在 `[logging]` 部分配置 log、tracing 相关参数： + +```toml +[logging] +dir = "/tmp/greptimedb/logs" +level = "info" +enable_otlp_tracing = false +otlp_endpoint = "localhost:4317" +append_stdout = true +[logging.tracing_sample_ratio] +default_ratio = 1.0 +``` + +- `dir`: log 输出目录。 +- `level`: log 输出的日志等级，日志等级有 `info`, `debug`, `error`, `warn`，默认等级为 `info`。 +- `enable_otlp_tracing`：是否打开分布式追踪，默认不开启。 +- `otlp_endpoint`：使用基于 gRPC 的 OTLP 协议导出 tracing 的目标端点，默认值为 `localhost:4317`。 +- `append_stdout`：是否将日志打印到 stdout。默认是`true`。 +- `tracing_sample_ratio`：该字段可以配置 tracing 的采样率，如何使用 `tracing_sample_ratio`，请参考 [如何配置 tracing 采样率](/user-guide/administration/monitoring/tracing.md#指南如何配置-tracing-采样率)。 + +如何使用分布式追踪，请参考 [Tracing](/user-guide/administration/monitoring/tracing.md#教程使用-jaeger-追踪-greptimedb-调用链路) + +### Region 引擎选项 + +datanode 和 standalone 在 `[region_engine]` 部分可以配置不同存储引擎的对应参数。目前只可以配置存储引擎 `mito` 的选项。 + +部分常用的选项如下 + +```toml +[[region_engine]] +[region_engine.mito] +num_workers = 8 +manifest_checkpoint_distance = 10 +max_background_jobs = 4 +auto_flush_interval = "1h" +global_write_buffer_size = "1GB" +global_write_buffer_reject_size = "2GB" +sst_meta_cache_size = "128MB" +vector_cache_size = "512MB" +page_cache_size = "512MB" +sst_write_buffer_size = "8MB" +scan_parallelism = 0 + +[region_engine.mito.inverted_index] +create_on_flush = "auto" +create_on_compaction = "auto" +apply_on_query = "auto" +mem_threshold_on_create = "64M" +intermediate_path = "" + +[region_engine.mito.memtable] +type = "time_series" +``` + +此外，`mito` 也提供了一个实验性质的 memtable。该 memtable 主要优化大量时间序列下的写入性能和内存占用。其查询性能可能会不如默认的 `time_series` memtable。 + +```toml +[region_engine.mito.memtable] +type = "partition_tree" +index_max_keys_per_shard = 8192 +data_freeze_threshold = 32768 +fork_dictionary_bytes = "1GiB" +``` + +以下是可供使用的选项 + +| 键 | 类型 | 默认值 | 描述 | +| ---------------------------------------- | ------ | ------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `num_workers` | 整数 | `8` | 写入线程数量 | +| `manifest_checkpoint_distance` | 整数 | `10` | 每写入 `manifest_checkpoint_distance` 个 manifest 文件创建一次 checkpoint | +| `max_background_jobs` | 整数 | `4` | 后台线程数量 | +| `auto_flush_interval` | 字符串 | `1h` | 自动 flush 超过 `auto_flush_interval` 没 flush 的 region | +| `global_write_buffer_size` | 字符串 | `1GB` | 写入缓冲区大小，默认值为内存总量的 1/8，但不会超过 1GB | +| `global_write_buffer_reject_size` | 字符串 | `2GB` | 写入缓冲区内数据的大小超过 `global_write_buffer_reject_size` 后拒绝写入请求，默认为 `global_write_buffer_size` 的 2 倍 | +| `sst_meta_cache_size` | 字符串 | `128MB` | SST 元数据缓存大小。设为 0 可关闭该缓存
默认为内存的 1/32，不超过 128MB | +| `vector_cache_size` | 字符串 | `512MB` | 内存向量和 arrow array 的缓存大小。设为 0 可关闭该缓存
默认为内存的 1/16，不超过 512MB | +| `page_cache_size` | 字符串 | `512MB` | SST 数据页的缓存。设为 0 可关闭该缓存
默认为内存的 1/8 | +| `selector_result_cache_size` | 字符串 | `512MB` | `last_value()` 等时间线检索结果的缓存。设为 0 可关闭该缓存
默认为内存的 1/16，不超过 512MB | +| `sst_write_buffer_size` | 字符串 | `8MB` | SST 的写缓存大小 | +| `scan_parallelism` | 整数 | `0` | 扫描并发度 (默认 1/4 CPU 核数)
- `0`: 使用默认值 (1/4 CPU 核数)
- `1`: 单线程扫描
- `n`: 按并行度 n 扫描 | +| `inverted_index.create_on_flush` | 字符串 | `auto` | 是否在 flush 时构建索引
- `auto`: 自动
- `disable`: 从不 | +| `inverted_index.create_on_compaction` | 字符串 | `auto` | 是否在 compaction 时构建索引
- `auto`: 自动
- `disable`: 从不 | +| `inverted_index.apply_on_query` | 字符串 | `auto` | 是否在查询时使用索引
- `auto`: 自动
- `disable`: 从不 | +| `inverted_index.mem_threshold_on_create` | 字符串 | `64M` | 创建索引时如果超过该内存阈值则改为使用外部排序
设置为空会关闭外排，在内存中完成所有排序 | +| `inverted_index.intermediate_path` | 字符串 | `""` | 存放外排临时文件的路径 (默认 `{data_home}/index_intermediate`). | +| `memtable.type` | 字符串 | `time_series` | Memtable type.
- `time_series`: time-series memtable
- `partition_tree`: partition tree memtable (实验性功能) | +| `memtable.index_max_keys_per_shard` | 整数 | `8192` | 一个 shard 内的主键数
只对 `partition_tree` memtable 生效 | +| `memtable.data_freeze_threshold` | 整数 | `32768` | 一个 shard 内写缓存可容纳的最大行数
只对 `partition_tree` memtable 生效 | +| `memtable.fork_dictionary_bytes` | 字符串 | `1GiB` | 主键字典的大小
只对 `partition_tree` memtable 生效 | + +### 设定 meta client + +`meta_client` 选项适用于 `datanode` 和 `frontend` 模块，用于指定 Metasrv 的相关信息。 + +```toml +[meta_client] +metasrv_addrs = ["127.0.0.1:3002"] +timeout = "3s" +connect_timeout = "1s" +ddl_timeout = "10s" +tcp_nodelay = true +``` + +通过 `meta_client` 配置 metasrv 客户端，包括： + +- `metasrv_addrs`， Metasrv 地址列表，对应 Metasrv 启动配置的 server address。 +- `timeout`， 操作超时时长，默认为 3 秒。 +- `connect_timeout`，连接服务器超时时长，默认为 1 秒。 +- `ddl_timeout`， DDL 执行的超时时间，默认 10 秒。 +- `tcp_nodelay`，接受连接时的 `TCP_NODELAY` 选项，默认为 true。 + +### 指标监控选项 + +这些选项用于将系统监控指标保存到 GreptimeDB 本身。 +有关如何使用此功能的说明，请参见 [监控](/user-guide/administration/monitoring/export-metrics.md) 指南。 + +```toml +[export_metrics] +# Whether to enable export_metrics +enable=true +# Export time interval +write_interval = "30s" +``` + +- `enable`: 是否启用导出指标功能，默认为 `false`。 +- `write_interval`: 指标导出时间间隔。 + +#### `self_import` 方法 + +仅 `frontend` 和 `standalone` 支持使用 `self_import` 方法导出指标。 + +```toml +[export_metrics] +# Whether to enable export_metrics +enable=true +# Export time interval +write_interval = "30s" +[export_metrics.self_import] +db = "information_schema" +``` + +- `db`: 默认的数据库为 `information_schema`，你也可以创建另一个数据库来保存系统指标。 + +#### `remote_write` 方法 + +`datanode`、`frontend`、`metasrv` 和 `standalone` 支持使用 `remote_write` 方法导出指标。 +它将指标发送到与 [Prometheus Remote-Write protocol](https://prometheus.io/docs/concepts/remote_write_spec/) 兼容的接受端。 + +```toml +[export_metrics] +# Whether to enable export_metrics +enable=true +# Export time interval +write_interval = "30s" +[export_metrics.remote_write] +# URL specified by Prometheus Remote-Write protocol +url = "http://127.0.0.1:4000/v1/prometheus/write?db=information_schema" +# Some optional HTTP parameters, such as authentication information +headers = { Authorization = "Basic Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=" } +``` + +- `url`: Prometheus Remote-Write 协议指定的 URL。 +- `headers`: 一些可选的 HTTP 参数，比如认证信息。 + +### Mode 选项 + +`mode` 选项在 `datanode`、`frontend` 和 `standalone` 中可用，它指定了组件的运行模式。 + +在分布式 GreptimeDB 的 `datanode` 和 `frontend` 的配置文件中，需要将值设置为 `distributed`： + +```toml +mode = "distributed" +``` + +在 standalone GreptimeDB 的配置文件中，需要将值设置为 `standalone`： + +```toml +mode = "standalone" +``` + +### 心跳配置 +心跳配置在 `frontend` 和 `datanode` 中可用。 +```toml +[heartbeat] +interval = "3s" +retry_interval = "3s" +``` + +| 键 | 类型 | 默认值 | 描述 | +|----------------------------|-----|------|----------------------------------------------------------| +| `heartbeat` | -- | -- | -- | +| `heartbeat.interval` | 字符串 | `3s` | 向 Metasrv 发送心跳信息的时间间隔 | +| `heartbeat.retry_interval` | 字符串 | `3s` | 向 Metasrv 重试建立心跳连接的时间间隔。（注意在 Datanode 的心跳实现中，这个配置是被忽略的，因为 Datanode 必须在保活机制的租约期内通过心跳完成续租，也就是说其 retry 有特殊策略不允许自定义配置。） | + +### 默认时区配置 + +`default_timezone` 选项适用于 `frontend` 模块和 `standalone` 模式，默认值为 `UTC`。 +它指定了与 GreptimeDB 交互时的客户端默认时区。 +如果在客户端中[指定了时区](/user-guide/timezone.md#在客户端中指定时区)，此选项将在该客户端会话中被覆盖。 + +```toml +default_timezone = "UTC" +``` + +`default_timezone` 的值可以是任何时区名称，例如 `Europe/Berlin` 或 `Asia/Shanghai`。 +有关客户端时区如何影响数据的写入和查询，请参阅[时区](/user-guide/timezone.md#时区对-sql-语句的影响)文档。 + +### 仅限于 Metasrv 的配置 + +```toml +# 工作主目录。 +data_home = "/tmp/metasrv/" +# metasrv 的绑定地址，默认为 "127.0.0.1:3002"。 +bind_addr = "127.0.0.1:3002" +# frontend 和 datanode 连接到 metasrv 的通信服务器地址，本地默认为 "127.0.0.1:3002"。 +server_addr = "127.0.0.1:3002" +# metasrv 存储端服务器地址，默认为 "127.0.0.1:2379"。 +store_addr = "127.0.0.1:2379" +# Datanode 选择器类型。 +# - "lease_based" (默认值) +# - "load_based" +# 详情请参阅 "https://docs.greptime.com/contributor-guide/meta/selector" +selector = "lease_based" +# 将数据存储在内存中，默认值为 false。 +use_memory_store = false +## 是否启用 region failover。 +## 该功能仅适用于运行在集群模式下的 GreptimeDB，并且 +## - 使用 Remote WAL +## - 使用共享存储（例如 s3）。 +enable_region_failover = false +# metasrv 的数据库类型. +## 可选项： +## - "EtcdStore" (默认值) +## - "MemoryStore" (纯内存存储 - 仅用于测试) +## - "PostgresStore" +backend = "EtcdStore" + +## Procedure 选项 +[procedure] + +## 最大重试次数 +max_retry_times = 12 + +## 程序的初始重试延迟 +retry_delay = "500ms" + +# Failure detector 选项 +[failure_detector] + +## Failure detector 检测阈值 +threshold = 8.0 + +## 心跳间隔的最小标准差，用于计算可接受的变化。 +min_std_deviation = "100ms" + +## 心跳之间可接受的暂停时间长度。 +acceptable_heartbeat_pause = "10000ms" + +## 首次心跳间隔的估计值。 +first_heartbeat_estimate = "1000ms" + +## Datanode 选项。 +[datanode] + +## Datanode 客户端配置。 +[datanode.client] + +## 操作超时时间 +timeout = "10s" + +## 连接服务器超时时间。 +connect_timeout = "10s" + +## 接受连接时的 `TCP_NODELAY` 选项，默认为 true。 +tcp_nodelay = true + +[wal] +# 可用的 WAL 提供者： +# - `raft_engine`（默认）：由于 metasrv 目前仅涉及远程 WAL，因此没有 raft-engine WAL 配置。 +# - `kafka`：在 datanode 中使用 kafka WAL 提供者时，metasrv **必须** 配置 kafka WAL 配置。 +provider = "raft_engine" + +# Kafka WAL 配置。 + +## Kafka 集群的代理端点。 +broker_endpoints = ["127.0.0.1:9092"] + +## 自动为 WAL 创建 topics +## 设置为 `true` 则自动为 WAL 创建 topics +## 否则，使用名为 `topic_name_prefix_[0..num_topics)` 的 topics +auto_create_topics = true + +## Topic 数量。 +num_topics = 64 + +## Topic selector 类型。 +## 可用的 selector 类型： +## - `round_robin`（默认） +selector_type = "round_robin" + +## Kafka topic 通过连接 `topic_name_prefix` 和 `topic_id` 构建。 +topic_name_prefix = "greptimedb_wal_topic" + +## 每个分区的预期副本数。 +replication_factor = 1 + +## 超过此时间创建 topic 的操作将被取消。 +create_topic_timeout = "30s" + +## Kafka 客户端的 backoff 初始时间。 +backoff_init = "500ms" + +## Kafka 客户端的 backoff 最大时间。 +backoff_max = "10s" + +## backoff 指数，即下一个 backoff 时间 = 该指数 * 当前 backoff 时间。 +backoff_base = 2 + +## 如果总等待时间达到截止时间，则停止重新连接。如果此配置缺失，则重新连接不会终止。 +backoff_deadline = "5mins" +``` + +| 键 | 类型 | 默认值 | 描述 | +| --------------------------------------------- | ------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `data_home` | String | `/tmp/metasrv/` | 工作目录。 | +| `bind_addr` | String | `127.0.0.1:3002` | Metasrv 的绑定地址。 | +| `server_addr` | String | `127.0.0.1:3002` | 前端和 datanode 连接到 Metasrv 的通信服务器地址，默认为本地主机的 `127.0.0.1:3002`。 | +| `store_addrs` | Array | `["127.0.0.1:2379"]` | 元数据服务地址，默认值为 `["127.0.0.1:2379"]`。支持配置多个服务地址，格式为 `["ip1:port1","ip2:port2",...]`。默认使用 Etcd 做为元数据后端。 | +| `selector` | String | `lease_based` | 创建新表时选择 datanode 的负载均衡策略，详见 [选择器](/contributor-guide/metasrv/selector.md)。 | +| `use_memory_store` | Boolean | `false` | 仅用于在没有 etcd 集群时的测试，将数据存储在内存中，默认值为 `false`。 | +| enable_region_failover | Bool | false | 是否启用 region failover。
该功能仅在以集群模式运行的 GreptimeDB 上可用，并且
- 使用远程 WAL
- 使用共享存储（如 s3）。 | +| `procedure` | -- | -- | | +| `procedure.max_retry_times` | 整数 | `12` | Procedure 的最大重试次数。 | +| `procedure.retry_delay` | 字符串 | `500ms` | Procedure 初始重试延迟，延迟会指数增长。 | +| `failure_detector` | -- | -- | 故障检测选项。 | +| `failure_detector.threshold` | 浮点数 | `8.0` | Failure detector 用来判断故障条件的阈值。 | +| `failure_detector.min_std_deviation` | 字符串 | `100ms` | 心跳间隔的最小标准差，用于计算可接受的变动范围。 | +| `failure_detector.acceptable_heartbeat_pause` | 字符串 | `10000ms` | 允许的最大心跳暂停时间，用于确定心跳间隔是否可接受。 | +| `failure_detector.first_heartbeat_estimate` | 字符串 | `1000ms` | 初始心跳间隔估算值。 | +| `datanode` | -- | -- | | +| `datanode.client` | -- | -- | Datanode 客户端选项。 | +| `datanode.client.timeout` | 字符串 | `10s` | 操作超时。 | +| `datanode.client.connect_timeout` | 字符串 | `10s` | 连接服务器超时。 | +| `datanode.client.tcp_nodelay` | 布尔值 | `true` | 接受连接的 `TCP_NODELAY` 选项。 | +| wal | -- | -- | -- | +| wal.provider | String | raft_engine | -- | +| wal.broker_endpoints | Array | -- | Kafka 集群的端点 | +| `wal.auto_create_topics` | Bool | `true` | 自动为 WAL 创建 topics
设置为 `true` 则自动为 WAL 创建 topics
否则，使用名为 `topic_name_prefix_[0..num_topics)` 的 topics | +| `wal.num_topics` | Integer | `64` | Topic 数量 | +| wal.selector_type | String | round_robin | topic selector 类型
可用 selector 类型：
- round_robin（默认） | +| wal.topic_name_prefix | String | greptimedb_wal_topic | 一个 Kafka topic 是通过连接 topic_name_prefix 和 topic_id 构建的 | +| wal.replication_factor | Integer | 1 | 每个分区的副本数 | +| wal.create_topic_timeout | String | 30s | 超过该时间后，topic 创建操作将被取消 | +| wal.backoff_init | String | 500ms | Kafka 客户端的 backoff 初始时间 | +| wal.backoff_max | String | 10s | Kafka 客户端的 backoff 最大时间 | +| wal.backoff_base | Integer | 2 | backoff 指数，即下一个 backoff 时间 = 该指数 \* 当前 backoff 时间 | +| wal.backoff_deadline | String | 5mins | 如果总等待时间达到截止时间，则停止重新连接。如果此配置缺失，则重新连接不会终止 | +| `wal.sasl` | String | -- | Kafka 客户端 SASL 配置 | +| `wal.sasl.type` | String | -- | SASL 机制, 可选值: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512` | +| `wal.sasl.username` | String | -- | SASL 鉴权用户名 | +| `wal.sasl.password` | String | -- | SASL 鉴权密码 | +| `wal.tls` | String | -- | Kafka 客户端 TLS 配置 | +| `wal.tls.server_ca_cert_path` | String | -- | 服务器 CA 证书地址 | +| `wal.tls.client_cert_path` | String | -- | 客户端证书地址（用于启用 mTLS） | +| `wal.tls.client_key_path` | String | -- | 客户端密钥地址（用于启用 mTLS） | + +### 仅限于 `Datanode` 的配置 + +```toml +node_id = 42 +rpc_hostname = "127.0.0.1" +rpc_addr = "127.0.0.1:3001" +rpc_runtime_size = 8 +``` + +| Key | Type | Description | +| ---------------- | ------ | ------------------------------------------- | +| node_id | 整数 | 该 `datanode` 的唯一标识符。 | +| rpc_hostname | 字符串 | 该 `datanode` 的 Hostname。 | +| rpc_addr | 字符串 | gRPC 服务端地址，默认为`"127.0.0.1:3001"`。 | +| rpc_runtime_size | 整数 | gRPC 服务器工作线程数，默认为 8。 | + +### 仅限于 `Frontend` 的配置 + +```toml +[datanode] +[datanode.client] +connect_timeout = "1s" +tcp_nodelay = true +``` + +| Key | Type | Default | Description | +|-----------------------------------|------|---------|-------------------------| +| `datanode` | -- | -- | | +| `datanode.client` | -- | -- | Datanode 客户端选项。 | +| `datanode.client.connect_timeout` | 字符串 | `1s` | 连接服务器超时。 | +| `datanode.client.tcp_nodelay` | 布尔值 | `true` | 接受连接的 `TCP_NODELAY` 选项。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/getting-started.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/getting-started.md new file mode 100644 index 000000000..bc2ca80c5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/getting-started.md @@ -0,0 +1,555 @@ +--- +description: 在 Kubernetes 上使用 GreptimeDB Operator 部署 GreptimeDB 集群的指南，包括前置条件、创建测试集群、安装和验证步骤。 +--- + +# 立即开始 + +在该指南中，你将学会如何使用 GreptimeDB Operator 在 Kubernetes 上部署 GreptimeDB 集群。 + +:::note +以下输出可能会因 Helm chart 版本和具体环境的不同而有细微差别。 +::: + +## 前置条件 + +- [Docker](https://docs.docker.com/get-started/get-docker/) >= v23.0.0 +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) >= v1.18.0 +- [Helm](https://helm.sh/docs/intro/install/) >= v3.0.0 +- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) >= v0.20.0 + +## 创建一个测试 Kubernetes 集群 + +:::warning +不建议在生产环境或性能测试中使用 `kind`。如有这类需求建议使用公有云托管的 Kubernetes 服务，如 [Amazon EKS](https://aws.amazon.com/eks/)、[Google GKE](https://cloud.google.com/kubernetes-engine/) 或 [Azure AKS](https://azure.microsoft.com/en-us/services/kubernetes-service/)，或者自行搭建生产级 Kubernetes 集群。 +::: + +目前有很多方法可以创建一个用于测试的 Kubernetes 集群。在本指南中，我们将使用 [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) 来创建一个本地 Kubernetes 集群。如果你想使用已有的 Kubernetes 集群，可以跳过这一步。 + +这里是一个使用 `kind` v0.20.0 的示例： + +```bash +kind create cluster +``` + +
+ 预期输出 +```bash +Creating cluster "kind" ... + ✓ Ensuring node image (kindest/node:v1.27.3) 🖼 + ✓ Preparing nodes 📦 + ✓ Writing configuration 📜 + ✓ Starting control-plane 🕹️ + ✓ Installing CNI 🔌 + ✓ Installing StorageClass 💾 +Set kubectl context to "kind-kind" +You can now use your cluster with: + +kubectl cluster-info --context kind-kind + +Thanks for using kind! 😊 +``` +
+ +使用以下命令检查集群的状态： + +```bash +kubectl cluster-info +``` + +
+ 预期输出 +```bash +Kubernetes control plane is running at https://127.0.0.1:60495 +CoreDNS is running at https://127.0.0.1:60495/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy + +To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. +``` +
+ +:::note +中国大陆用户如有网络访问问题，可使用 Greptime 提供的位于阿里云镜像仓库的 `kindest/node:v1.27.3` 镜像： + +```bash +kind create cluster --image greptime-registry.cn-hangzhou.cr.aliyuncs.com/kindest/node:v1.27.3 +``` +::: + +## 添加 Greptime Helm 仓库 + +:::note +中国大陆用户如有网络访问问题，可跳过这一步骤并直接参考下一步中使用阿里云 OCI 镜像仓库的方式。采用这一方式将无需手动添加 Helm 仓库。 +::: + +我们提供了 GreptimeDB Operator 和 GreptimeDB 集群的[官方 Helm 仓库](https://github.com/GreptimeTeam/helm-charts)。你可以通过运行以下命令来添加仓库： + +```bash +helm repo add greptime https://greptimeteam.github.io/helm-charts/ +helm repo update +``` + +检查 Greptime Helm 仓库中的 charts： + +```bash +helm search repo greptime +``` + +
+ 预期输出 +```bash +NAME CHART VERSION APP VERSION DESCRIPTION +greptime/greptimedb-cluster 0.2.25 0.9.5 A Helm chart for deploying GreptimeDB cluster i... +greptime/greptimedb-operator 0.2.9 0.1.3-alpha.1 The greptimedb-operator Helm chart for Kubernetes. +greptime/greptimedb-standalone 0.1.27 0.9.5 A Helm chart for deploying standalone greptimedb +``` +
+ +## 安装和验证 GreptimeDB Operator + +现在我们准备使用 Helm 在 Kubernetes 集群上安装 GreptimeDB Operator。 + +### 安装 GreptimeDB Operator + +[GreptimeDB Operator](https://github.com/GrepTimeTeam/greptimedb-operator) 是一个用于管理 GreptimeDB 集群生命周期的 Kubernetes operator。 + +让我们在 `greptimedb-admin` 命名空间中安装最新版本的 GreptimeDB Operator： + +```bash +helm install greptimedb-operator greptime/greptimedb-operator -n greptimedb-admin --create-namespace +``` + +
+ 预期输出 +```bash +NAME: greptimedb-operator +LAST DEPLOYED: Tue Oct 29 18:40:10 2024 +NAMESPACE: greptimedb-admin +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +*********************************************************************** + Welcome to use greptimedb-operator + Chart version: 0.2.9 + GreptimeDB Operator version: 0.1.3-alpha.1 +*********************************************************************** + +Installed components: +* greptimedb-operator + +The greptimedb-operator is starting, use `kubectl get deployments greptimedb-operator -n greptimedb-admin` to check its status. +``` +
+ +:::note +中国大陆用户如有网络访问问题，可直接使用阿里云 OCI 镜像仓库的方式安装 GreptimeDB Operator： + +```bash +helm install greptimedb-operator \ + oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-operator \ + --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + -n greptimedb-admin \ + --create-namespace +``` + +此时我们也将镜像仓库设置为 Greptime 官方的阿里云镜像仓库。 +::: + +:::note +我们还可以直接使用 `kubectl` 和 `bundle.yaml` 来安装最新版本的 GreptimeDB Operator： + +```bash +kubectl apply -f \ + https://github.com/GreptimeTeam/greptimedb-operator/releases/latest/download/bundle.yaml \ + --server-side +``` + +这种方式仅适用于在测试环境快速部署 GreptimeDB Operator，不建议在生产环境中使用。 +::: + +### 验证 GreptimeDB Operator 安装 + +检查 GreptimeDB Operator 的状态： + +```bash +kubectl get pods -n greptimedb-admin -l app.kubernetes.io/instance=greptimedb-operator +``` + +
+ 预期输出 +```bash +NAME READY STATUS RESTARTS AGE +greptimedb-operator-68d684c6cf-qr4q4 1/1 Running 0 4m8s +``` +
+ +你也可以检查 CRD 的安装： + +```bash +kubectl get crds | grep greptime +``` + +
+ 预期输出 +```bash +greptimedbclusters.greptime.io 2024-10-28T08:46:27Z +greptimedbstandalones.greptime.io 2024-10-28T08:46:27Z +``` +
+ +GreptimeDB Operator 将会使用 `greptimedbclusters.greptime.io` and `greptimedbstandalones.greptime.io` 这两个 CRD 来管理 GreptimeDB 集群和单机实例。 + +## 安装 etcd 集群 + +GreptimeDB 集群需要一个 etcd 集群来存储元数据。让我们使用 Bitnami 的 etcd Helm [chart](https://hub.docker.com/r/bitnami/etcd) 来安装一个 etcd 集群。 + +```bash +helm install etcd \ + oci://registry-1.docker.io/bitnamicharts/etcd \ + --version 10.2.12 \ + --set replicaCount=3 \ + --set auth.rbac.create=false \ + --set auth.rbac.token.enabled=false \ + --create-namespace \ + -n etcd-cluster +``` + +
+ 预期输出 +```bash +NAME: etcd +LAST DEPLOYED: Mon Oct 28 17:01:38 2024 +NAMESPACE: etcd-cluster +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +CHART NAME: etcd +CHART VERSION: 10.2.12 +APP VERSION: 3.5.15 + +** Please be patient while the chart is being deployed ** + +etcd can be accessed via port 2379 on the following DNS name from within your cluster: + + etcd.etcd-cluster.svc.cluster.local + +To create a pod that you can use as a etcd client run the following command: + + kubectl run etcd-client --restart='Never' --image docker.io/bitnami/etcd:3.5.15-debian-12-r6 --env ETCDCTL_ENDPOINTS="etcd.etcd-cluster.svc.cluster.local:2379" --namespace etcd-cluster --command -- sleep infinity + +Then, you can set/get a key using the commands below: + + kubectl exec --namespace etcd-cluster -it etcd-client -- bash + etcdctl put /message Hello + etcdctl get /message + +To connect to your etcd server from outside the cluster execute the following commands: + + kubectl port-forward --namespace etcd-cluster svc/etcd 2379:2379 & + echo "etcd URL: http://127.0.0.1:2379" + +WARNING: There are "resources" sections in the chart not set. Using "resourcesPreset" is not recommended for production. For production installations, please set the following values according to your workload needs: +- disasterRecovery.cronjob.resources +- resources + +info https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +``` +
+ +当 etcd 集群准备好后，你可以使用以下命令检查 Pod 的状态： + +```bash +kubectl get pods -n etcd-cluster -l app.kubernetes.io/instance=etcd +``` + +
+ 预期输出 +```bash +NAME READY STATUS RESTARTS AGE +etcd-0 1/1 Running 0 2m8s +etcd-1 1/1 Running 0 2m8s +etcd-2 1/1 Running 0 2m8s +``` +
+ +:::note +中国大陆用户如有网络访问问题，可直接使用阿里云 OCI 镜像仓库的方式安装 etcd 集群： + +```bash +helm install etcd \ + oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/etcd \ + --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set image.tag=3.5.12 \ + --set replicaCount=3 \ + --set auth.rbac.create=false \ + --set auth.rbac.token.enabled=false \ + --create-namespace \ + -n etcd-cluster +``` +::: + +你可以通过运行以下命令来测试 etcd 集群： + +```bash +kubectl -n etcd-cluster \ + exec etcd-0 -- etcdctl endpoint health \ + --endpoints=http://etcd-0.etcd-headless.etcd-cluster.svc.cluster.local:2379,http://etcd-1.etcd-headless.etcd-cluster.svc.cluster.local:2379,http://etcd-2.etcd-headless.etcd-cluster.svc.cluster.local:2379 +``` + +
+ 预期输出 +```bash +http://etcd-1.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.008575ms +http://etcd-0.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.136576ms +http://etcd-2.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.147702ms +``` +
+ +## 安装带有监控集成的 GreptimeDB 集群 + +目前我们已经准备好了 GreptimeDB Operator 和 etcd 集群，现在我们可以部署一个带监控集成的最小 GreptimeDB 集群： + +:::warning +本文档中的默认配置不适用于生产环境，你应该根据自己的需求调整配置。 +::: + +```bash +helm install mycluster \ + --set monitoring.enabled=true \ + --set grafana.enabled=true \ + greptime/greptimedb-cluster \ + -n default +``` + +:::note +中国大陆用户如有网络访问问题，可直接使用阿里云 OCI 镜像仓库的方式来安装 GreptimeDB 集群： + +```bash +helm install mycluster \ + oci://greptime-registry.cn-hangzhou.cr.aliyuncs.com/charts/greptimedb-cluster \ + --set image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set initializer.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set grafana.enabled=true \ + --set grafana.image.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + --set monitoring.enabled=true \ + --set monitoring.vector.registry=greptime-registry.cn-hangzhou.cr.aliyuncs.com \ + -n default +``` + +如果你使用了不同的集群名称和命名空间，请将 `mycluster` 和 `default` 替换为你的配置。 +::: + +
+ 预期输出 +```bash +Release "mycluster" does not exist. Installing it now. +NAME: mycluster +LAST DEPLOYED: Mon Oct 28 17:19:47 2024 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +NOTES: +*********************************************************************** + Welcome to use greptimedb-cluster + Chart version: 0.2.25 + GreptimeDB Cluster version: 0.9.5 +*********************************************************************** + +Installed components: +* greptimedb-frontend +* greptimedb-datanode +* greptimedb-meta + +The greptimedb-cluster is starting, use `kubectl get pods -n default` to check its status. +``` +
+ +当启用 `monitoring` 选项时，我们将会在 cluster 所属的命名空间下部署一个名为 `${cluster}-monitor` 的 GreptimeDB Standalone 实例，用于存储集群的 metrics 和 logs 这类监控数据。同时，我们也会为集群内的每一个 Pod 部署一个 [Vector](https://github.com/vectordotdev/vector) sidecar 来收集集群的 metrics 和 logs，并发送给 GreptimeDB Standalone 实例。 + + +当启用 `grafana` 选项时，我们将会部署一个 Grafana 实例，并配置 [Grafana](https://grafana.com/) 使用 GreptimeDB Standalone 实例作为数据源（分别使用 Prometheus 和 MySQL 协议），从而我们开箱即可使用 Grafana 来可视化 GreptimeDB 集群的监控数据。默认地，Grafana 将会使用 `mycluster` 和 `default` 作为集群名称和命名空间来创建数据源。如果你想要监控具有不同名称或不同命名空间的集群，那就需要基于不同的集群名称和命名空间来创建不同的数据源配置。你可以创建一个如下所示的 `values.yaml` 文件： + +```yaml +grafana: + datasources: + datasources.yaml: + datasources: + - name: greptimedb-metrics + type: prometheus + url: http://${cluster}-monitor-standalone.${namespace}.svc.cluster.local:4000/v1/prometheus + access: proxy + isDefault: true + + - name: greptimedb-logs + type: mysql + url: ${cluster}-monitor-standalone.${namespace}.svc.cluster.local:4002 + access: proxy + database: public +``` + +上述配置将在 Grafana dashboard 中为 GreptimeDB 集群的指标和日志创建默认的数据源： + +- `greptimedb-metrics`：集群的指标存储在独立的监控数据库中，并对外暴露为 Prometheus 协议（`type: prometheus`）； + +- `greptimedb-logs`：集群的日志存储在独立的监控数据库中，并对外暴露为 MySQL 协议（`type: mysql`）。默认使用 `public` 数据库； + +然后将上面的 `values.yaml` 中的 `${cluster}` 和 `${namespace}` 替换为你想要的值，并使用以下命令安装 GreptimeDB 集群： + +```bash +helm install ${cluster} \ + --set monitoring.enabled=true \ + --set grafana.enabled=true \ + greptime/greptimedb-cluster \ + -f values.yaml \ + -n ${namespace} +``` + +当启动集群安装之后，我们可以用如下命令检查 GreptimeDB 集群的状态。若你使用了不同的集群名和命名空间，可将 `default` 和 `mycluster` 替换为你的配置： + +```bash +kubectl -n default get greptimedbclusters.greptime.io mycluster +``` + +
+ 预期输出 +```bash +NAME FRONTEND DATANODE META FLOWNODE PHASE VERSION AGE +mycluster 1 1 1 0 Running v0.9.5 5m12s +``` +
+ +上面的命令将会显示 GreptimeDB 集群的状态。当 `PHASE` 为 `Running` 时，表示 GreptimeDB 集群已经成功启动。 + +你还可以检查 GreptimeDB 集群的 Pod 状态： + +```bash +kubectl -n default get pods +``` + +
+ 预期输出 +```bash +NAME READY STATUS RESTARTS AGE +mycluster-datanode-0 2/2 Running 0 77s +mycluster-frontend-6ffdd549b-9s7gx 2/2 Running 0 66s +mycluster-grafana-675b64786-ktqps 1/1 Running 0 6m35s +mycluster-meta-58bc88b597-ppzvj 2/2 Running 0 86s +mycluster-monitor-standalone-0 1/1 Running 0 6m35s +``` +
+ +正如你所看到的，我们默认创建了一个最小的 GreptimeDB 集群，包括 1 个 frontend、1 个 datanode 和 1 个 metasrv。关于一个完整的 GreptimeDB 集群的组成，你可以参考 [architecture](/user-guide/concepts/architecture.md)。除此之外，我们还部署了一个独立的 GreptimeDB Standalone 实例（`mycluster-monitor-standalone-0`）用以存储监控数据和一个 Grafana 实例（`mycluster-grafana-675b64786-ktqps`）用以可视化集群的监控数据。 + +## 探索 GreptimeDB 集群 + +### 访问 GreptimeDB 集群 + +你可以通过使用 `kubectl port-forward` 命令转发 frontend 服务来访问 GreptimeDB 集群： + +```bash +kubectl -n default port-forward svc/mycluster-frontend 4000:4000 4001:4001 4002:4002 4003:4003 +``` + +
+ 预期输出 +```bash +Forwarding from 127.0.0.1:4000 -> 4000 +Forwarding from [::1]:4000 -> 4000 +Forwarding from 127.0.0.1:4001 -> 4001 +Forwarding from [::1]:4001 -> 4001 +Forwarding from 127.0.0.1:4002 -> 4002 +Forwarding from [::1]:4002 -> 4002 +Forwarding from 127.0.0.1:4003 -> 4003 +Forwarding from [::1]:4003 -> 4003 +``` +
+ +请注意，当你使用了其他集群名和命名空间时，你可以使用如下命令，并将 `${cluster}` 和 `${namespace}` 替换为你的配置： + +```bash +kubectl -n ${namespace} port-forward svc/${cluster}-frontend 4000:4000 4001:4001 4002:4002 4003:4003 +``` + +:::warning +如果你想将服务暴露给公网访问，可以使用带有 `--address` 选项的 `kubectl port-forward` 命令： + +```bash +kubectl -n default port-forward --address 0.0.0.0 svc/mycluster-frontend 4000:4000 4001:4001 4002:4002 4003:4003 +``` + +在将服务暴露给公网访问之前，请确保你已经配置了适当的安全设置。 +::: + +打开浏览器并访问 `http://localhost:4000/dashboard` 来访问 [GreptimeDB Dashboard](https://github.com/GrepTimeTeam/dashboard)。 + +如果你想使用其他工具如 `mysql` 或 `psql` 来连接 GreptimeDB 集群，你可以参考 [快速入门](/getting-started/quick-start.md)。 + +### 访问 Grafana dashboard + +你可以使用 `kubectl port-forward` 命令转发 Grafana 服务： + +```bash +kubectl -n default port-forward svc/mycluster-grafana 18080:80 +``` + +请注意，当你使用了其他集群名和命名空间时，你可以使用如下命令，并将 `${cluster}` 和 `${namespace}` 替换为你的配置： + +```bash +kubectl -n ${namespace} port-forward svc/${cluster}-grafana 18080:80 +``` + +接着打开浏览器并访问 `http://localhost:18080` 来访问 Grafana dashboard。默认的用户名和密码是 `admin` 和 `gt-operator`： + +![Grafana Dashboard](/kubernetes-cluster-grafana-dashboard.jpg) + +目前有三个可用的 Dashboard： + +- **GreptimeDB Cluster Metrics**: 用于显示 GreptimeDB 集群的 Metrics； +- **GreptimeDB Cluster Logs**: 用于显示 GreptimeDB 集群的日志； +- **GreptimeDB Cluster Slow Queries**: 用于显示 GreptimeDB 集群的慢查询； + +## 清理 + +:::danger +清理操作将会删除 GreptimeDB 集群的元数据和数据。请确保在继续操作之前已经备份了数据。 +::: + +### 停止端口转发 + +可以使用以下命令停止 GreptimeDB 集群的端口转发： + +```bash +pkill -f kubectl port-forward +``` + +### 卸载 GreptimeDB 集群 + +可以使用以下命令卸载 GreptimeDB 集群： + +```bash +helm -n default uninstall mycluster +``` + +### 删除 PVCs + +为了安全起见，PVCs 默认不会被删除。如果你想删除 PV 数据，你可以使用以下命令： + +```bash +kubectl -n default delete pvc -l app.greptime.io/component=mycluster-datanode +kubectl -n default delete pvc -l app.greptime.io/component=mycluster-monitor-standalone +``` + +### 清理 etcd 数据 + +你可以使用以下命令清理 etcd 集群： + +```bash +kubectl -n etcd-cluster exec etcd-0 -- etcdctl del "" --from-key=true +``` + +### 删除 Kubernetes 集群 + +如果你使用 `kind` 创建 Kubernetes 集群，你可以使用以下命令销毁集群： + +```bash +kind delete cluster +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management.md new file mode 100644 index 000000000..1f4b0faa3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management.md @@ -0,0 +1,228 @@ +--- +description: GreptimeDB Operator 的管理指南，包括安装、升级、配置和卸载的详细步骤。 +--- + +# GreptimeDB Operator 的管理 + +GreptimeDB Operator 使用 [Operator 模式](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) 在 [Kubernetes](https://kubernetes.io/) 上管理 [GreptimeDB](https://github.com/GrepTimeTeam/greptimedb) 资源。 + +就像自动驾驶一样，GreptimeDB Operator 自动化了 GreptimeDB 集群和单机实例的部署、配置和管理。 + +GreptimeDB Operator 包括但不限于以下功能： + +- **自动化部署**: 通过提供 `GreptimeDBCluster` 和 `GreptimeDBStandalone` CRD 来自动化在 Kubernetes 上部署 GreptimeDB 集群和单机实例。 + +- **多云支持**: 用户可以在任何 Kubernetes 集群上部署 GreptimeDB，包括私有环境和公有云环境（如 AWS、GCP、阿里云等）。 + +- **扩缩容**: 通过修改 `GreptimeDBCluster` CR 中的 `replicas` 字段即可轻松实现 GreptimeDB 集群的扩缩容。 + +- **监控**: 通过在 `GreptimeDBCluster` CR 中提供 `monitoring` 字段来自动化部署基于 GreptimeDB 的监控组件。 + +本指南将展示如何在 Kubernetes 上安装、升级、配置和卸载 GreptimeDB Operator。 + +:::note +以下输出可能会因 Helm chart 版本和具体环境的不同而有细微差别。 +::: + +## 前置依赖 + +- Kubernetes >= v1.18.0 +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) >= v1.18.0 +- [Helm](https://helm.sh/docs/intro/install/) >= v3.0.0 + +## 生产环境部署 + +对于生产环境部署，推荐使用 Helm 来安装 GreptimeDB Operator。 + +### 安装 + +你可以参考 [安装和验证 GreptimeDB Operator](/user-guide/deployments/deploy-on-kubernetes/getting-started.md#安装和验证-greptimedb-operator) 获取详细的指导。 + +:::note +如果你使用 [Argo CD](https://argo-cd.readthedocs.io/en/stable/) 来部署应用，请确保 `Application` 已设置 [`ServerSideApply=true`](https://argo-cd.readthedocs.io/en/latest/user-guide/sync-options/#server-side-apply) 以启用 server-side apply（其他 GitOps 工具可能也有类似的设置）。 +::: + +### 升级 + +我们总是将最新版本的 GreptimeDB Operator 作为 Helm chart 发布在我们的[官方 Helm 仓库](https://github.com/GreptimeTeam/helm-charts/tree/main)。 + +当最新版本的 GreptimeDB Operator 发布时，您可以通过运行以下命令来升级 GreptimeDB Operator。 + +#### 更新 Helm 仓库 + +```bash +helm repo update greptime +``` + +
+期望输出 +```bash +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "greptime" chart repository +Update Complete. ⎈Happy Helming!⎈ +``` +
+ +你可以使用以下命令来搜索 GreptimeDB Operator 的最新版本： + +```bash +helm search repo greptime/greptimedb-operator +``` + +
+预期输出 +```bash +NAME CHART VERSION APP VERSION DESCRIPTION +greptime/greptimedb-operator 0.2.9 0.1.3-alpha.1 The greptimedb-operator Helm chart for Kubernetes. +``` +
+ +如果你想列出所有可用的版本，你可以使用以下命令： + +``` +helm search repo greptime/greptimedb-operator --versions +``` + +#### 升级 GreptimeDB Operator + +你可以通过运行以下命令升级到最新发布的 GreptimeDB Operator 版本： + +```bash +helm -n greptimedb-admin upgrade greptimedb-operator greptime/greptimedb-operator +``` + +
+期望输出 +```bash +Release "greptimedb-operator" has been upgraded. Happy Helming! +NAME: greptimedb-operator +LAST DEPLOYED: Mon Oct 28 19:30:52 2024 +NAMESPACE: greptimedb-admin +STATUS: deployed +REVISION: 2 +TEST SUITE: None +NOTES: +*********************************************************************** + Welcome to use greptimedb-operator + Chart version: 0.2.9 + GreptimeDB Operator version: 0.1.3-alpha.1 +*********************************************************************** + +Installed components: +* greptimedb-operator + +The greptimedb-operator is starting, use `kubectl get deployments greptimedb-operator -n greptimedb-admin` to check its status. +``` +
+ +如果你想升级到特定版本，你可以使用以下命令： + +```bash +helm -n greptimedb-admin upgrade greptimedb-operator greptime/greptimedb-operator --version +``` + +升级完成后，你可以使用以下命令来验证安装： + +```bash +helm list -n greptimedb-admin +``` + +
+期望输出 +```bash +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +greptimedb-operator greptimedb-admin 1 2024-10-30 17:46:45.570975 +0800 CST deployed greptimedb-operator-0.2.9 0.1.3-alpha.1 +``` +
+ +### CRDs + +这里将有两种类型的 CRD 与 GreptimeDB Operator 一起安装：`GreptimeDBCluster` 和 `GreptimeDBStandalone`。 + +你可以使用以下命令来验证安装： + +```bash +kubectl get crd | grep greptime +``` + +
+ 期望输出 +```bash +greptimedbclusters.greptime.io 2024-10-28T08:46:27Z +greptimedbstandalones.greptime.io 2024-10-28T08:46:27Z +``` +
+ +默认情况下，GreptimeDB Operator chart 将管理 CRDs 的安装和升级，用户不需要手动管理它们。如果你想了解这两类 CRD 的具体定义，可参考 GreptimeDB Operator 的 [API 文档](https://github.com/GreptimeTeam/greptimedb-operator/blob/main/docs/api-references/docs.md)。 + +### 配置 + +GreptimeDB Operator chart 提供了一组配置选项，允许您自行配置，您可以参考 [GreptimeDB Operator Helm Chart](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-operator/README.md) 来获取更多详细信息。 + +你可以创建一个 `values.yaml` 来配置 GreptimeDB Operator chart (完整的 `values.yaml` 配置可以参考 [chart](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-operator/values.yaml))，例如： + +```yaml +image: + # -- The image registry + registry: docker.io + # -- The image repository + repository: greptime/greptimedb-operator + # -- The image pull policy for the controller + imagePullPolicy: IfNotPresent + # -- The image tag + tag: latest + # -- The image pull secrets + pullSecrets: [] + +replicas: 1 + +resources: + limits: + cpu: 200m + memory: 256Mi + requests: + cpu: 100m + memory: 128Mi +``` + +:::note +中国大陆用户如有网络访问问题，可将上文中的 `image.registry` 配置为阿里云镜像仓库地址 `greptime-registry.cn-hangzhou.cr.aliyuncs.com`。 +::: + +你可以使用以下命令来安装带有自定义配置的 GreptimeDB Operator： + +```bash +helm -n greptimedb-admin install greptimedb-operator greptime/greptimedb-operator -f values.yaml +``` + +如果你想使用自定义配置升级 GreptimeDB Operator，你可以使用以下命令： + +```bash +helm -n greptimedb-admin upgrade greptimedb-operator greptime/greptimedb-operator -f values.yaml +``` + +你可以使用以下一条同样的命令来安装或升级带有自定义配置的 GreptimeDB Operator： + +```bash +helm -n greptimedb-admin upgrade --install greptimedb-operator greptime/greptimedb-operator -f values.yaml +``` + +### 卸载 + +你可以使用 `helm` 命令来卸载 GreptimeDB Operator： + +```bash +helm -n greptimedb-admin uninstall greptimedb-operator +``` + +默认情况下，卸载 GreptimeDB Operator 时不会删除 CRDs。 + +:::danger +如果你确实想要删除 CRDs，你可以使用以下命令： + +```bash +kubectl delete crd greptimedbclusters.greptime.io greptimedbstandalones.greptime.io +``` + +删除 CRDs 后，相关资源将被删除。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/overview.md new file mode 100644 index 000000000..31125823c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/overview.md @@ -0,0 +1,19 @@ +--- +description: 在 Kubernetes 上部署 GreptimeDB 的概述，介绍了 GreptimeDB Operator 的功能和使用方法。 +--- + +# 概述 + +## GreptimeDB Operator + +[GreptimeDB Operator](https://github.com/GrepTimeTeam/greptimedb-operator) 采用 [Operator 模式](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)运行于 Kubernetes 中，用于自动化管理 GreptimeDB 资源。基于 GreptimeDB Operator，你可以很轻松地部署、升级和管理 GreptimeDB 集群和单机实例。无论是私有还是公有云部署，GreptimeDB Operator 都将快速部署和扩容 GreptimeDB 变得简单易行。 + +我们**强烈建议**使用 GreptimeDB Operator 在 Kubernetes 上部署 GreptimeDB。 + +## 使用 GreptimeDB Operator 来管理 GreptimeDB + +你可以将 [立即开始](./getting-started.md) 作为你的第一篇指南以了解整体情况。在该指南中，我们提供了用于在 Kubernetes 上部署 GreptimeDB 集群的完整过程。 + +在完成**立即开始**章节后，你可以参考以下文档以获取有关生产部署的更多详细信息。 + +- [GreptimeDB Operator 管理](./greptimedb-operator-management.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/overview.md new file mode 100644 index 000000000..25e2f8c5a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/overview.md @@ -0,0 +1,34 @@ +--- +description: GreptimeDB 部署概述，包括配置项、鉴权、在 Kubernetes 上部署、在 Android 上运行、容量规划和 GreptimeCloud 的介绍。 +--- + +# 概述 + +## 配置项 + +在部署 GreptimeDB 之前，你需要[配置服务器](configuration.md)以满足需求， +其中包括设置协议选项、存储选项等。 + +## 鉴权 + +GreptimeDB 默认不启用鉴权认证。 +了解如何为你的部署手动[配置鉴权](./authentication/overview.md)。 + +## 部署到 Kubernetes + +[在 Kubernetes 集群上部署 GreptimeDB](./deploy-on-kubernetes/overview.md)的逐步说明。 + +## 在 Android 上运行 + +[在 Android 设备上运行 GreptimeDB](run-on-android.md)的指南。 + +## 容量规划 + +了解如何[规划容量](/user-guide/administration/capacity-plan.md)以确保你的 GreptimeDB 部署能够处理你的工作负载。 + +## GreptimeCloud + +比起管理自己的 GreptimeDB 集群， +你可以使用 [GreptimeCloud](https://greptime.cloud) 来管理 GreptimeDB 实例、监控指标和设置警报。 +GreptimeCloud 是由完全托管的无服务器 GreptimeDB 提供支持的云服务，为时间序列数据平台和 Prometheus 后端提供了可扩展和高效的解决方案。 +有关更多信息，请参阅[GreptimeCloud 文档](https://docs.greptime.cn/nightly/greptimecloud/overview)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/run-on-android.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/run-on-android.md new file mode 100644 index 000000000..b248c4ecc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/deployments/run-on-android.md @@ -0,0 +1,107 @@ +--- +description: 在安卓平台运行 GreptimeDB 的指南，包括安装终端模拟器、下载二进制文件、创建配置文件、启动服务和连接数据库的步骤。 +--- + +# 在安卓平台运行 + +从 v0.4.0 开始，GreptimeDB 支持在采用了 ARM64 CPU 和 Android API 23 版本以上的安卓平台运行。 + +## 安装终端模拟器 + +您可以从 [GitHub release 页面](https://github.com/termux/termux-app/releases/latest) 下载 [Termux 终端模拟器](https://termux.dev/) 来运行 GreptimeDB. + + + +## 下载 GreptimeDB 的二进制 + +请执行以下命令来下载安卓平台的 GreptimeDB 二进制： +```bash +VERSION=$(curl -s -XGET "https://api.github.com/repos/GreptimeTeam/greptimedb/releases" | grep tag_name | grep -v nightly | cut -d: -f 2 | sed 's/.*"\(.*\)".*/\1/' | uniq | sort -r | head -n 1) + +curl -sOL "https://github.com/GreptimeTeam/greptimedb/releases/download/${VERSION}/greptime-android-arm64-${VERSION}.tar.gz" +tar zxvf ./greptime-android-arm64-${VERSION}.tar.gz +./greptime -V +``` + +如果下载成功，以上命令将输出当前 GreptimeDB 的版本信息。 + +## 创建 GreptimeDB 的配置文件 + +您可以通过以下命令来创建一个最小化的配置文件以允许从局域网访问 GreptimeDB： + +```bash +DATA_DIR="$(pwd)/greptimedb-data" +mkdir -p ${DATA_DIR} + +cat < ./config.toml +[http] +addr = "0.0.0.0:4000" + +[grpc] +addr = "0.0.0.0:4001" + +[mysql] +addr = "0.0.0.0:4002" + +[storage] +data_home = "${DATA_DIR}" +type = "File" +EOF +``` + +## 从命令行启动 GreptimeDB + +```bash +./greptime --log-dir=$(pwd)/logs standalone start -c ./config.toml +``` + +## 从局域网连接运行在安卓设备上的 GreptimeDB + +> 您可以通过`ifconfig`来获取您所使用的的安卓设备的网络地址。 + +在启动 GreptimeDB 后，您可以从局域网内安装了 MySQL 客户端的设备上通过 MySQL 协议访问 GreptimeDB。 + +```bash +mysql -h -P 4002 +``` + +连接成功后，您可以像在任何其他平台一样使用运行在安卓设备上的 GreptimeDB！ + +``` +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 8 +Server version: 5.1.10-alpha-msql-proxy Greptime + +Copyright (c) 2000, 2023, Oracle and/or its affiliates. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> CREATE TABLE monitor (env STRING, host STRING, ts TIMESTAMP, cpu DOUBLE DEFAULT 0, memory DOUBLE, TIME INDEX (ts), PRIMARY KEY(env,host)); +Query OK, 0 rows affected (0.14 sec) + +mysql> INSERT INTO monitor(ts, env, host, cpu, memory) VALUES + -> (1655276557000,'prod', 'host1', 66.6, 1024), + -> (1655276557000,'prod', 'host2', 66.6, 1024), + -> (1655276557000,'prod', 'host3', 66.6, 1024), + -> (1655276558000,'prod', 'host1', 77.7, 2048), + -> (1655276558000,'prod', 'host2', 77.7, 2048), + -> (1655276558000,'test', 'host3', 77.7, 2048), + -> (1655276559000,'test', 'host1', 88.8, 4096), + -> (1655276559000,'test', 'host2', 88.8, 4096), + -> (1655276559000,'test', 'host3', 88.8, 4096); +Query OK, 9 rows affected (0.14 sec) + +mysql> +mysql> select * from monitor where env='test' and host='host3'; ++------+-------+---------------------+------+--------+ +| env | host | ts | cpu | memory | ++------+-------+---------------------+------+--------+ +| test | host3 | 2022-06-15 15:02:38 | 77.7 | 2048 | +| test | host3 | 2022-06-15 15:02:39 | 88.8 | 4096 | ++------+-------+---------------------+------+--------+ +2 rows in set (0.20 sec) +``` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/emqx.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/emqx.md new file mode 100644 index 000000000..eaee3e802 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/emqx.md @@ -0,0 +1,5 @@ +# EMQX + +[EMQX](https://www.emqx.io/) 是一款开源的大规模分布式 MQTT 消息服务器，专为物联网和实时通信应用而设计。EMQX 支持多种协议，包括 MQTT (3.1、3.1.1 和 5.0)、HTTP、QUIC 和 WebSocket 等，保证各种网络环境和硬件设备的可访问性。 + +GreptimeDB 可以作为 EMQX 的数据系统。请参考[将 MQTT 数据写入 GreptimeDB](https://docs.emqx.com/zh/emqx/latest/data-integration/data-bridge-greptimedb.html) 了解如何将 GreptimeDB 集成到 EMQX 中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/go.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/go.md new file mode 100644 index 000000000..c7873fb19 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/go.md @@ -0,0 +1,262 @@ +--- +description: 介绍如何使用 GreptimeDB 提供的 Go Ingest SDK 写入数据，包括安装、连接、插入数据和调试日志等内容。 +--- + +import DocTemplate from './template.md' + +# Go + + + +
+ +GreptimeDB 提供的 Go Ingest SDK 是一个轻量级、并发安全的库，使用起来非常简单。 + +
+ +
+ +你可以通过[快速开始 Demo](https://github.com/GreptimeTeam/greptimedb-ingester-go/tree/main/examples) 来了解如何使用 GreptimeDB Go SDK。 + +
+ +
+ +使用下方的命令安装 Go Ingest SDK： + +```shell +go get -u github.com/GreptimeTeam/greptimedb-ingester-go@VAR::goSdkVersion +``` + +引入到代码中： + +```go +import ( + greptime "github.com/GreptimeTeam/greptimedb-ingester-go" + "github.com/GreptimeTeam/greptimedb-ingester-go/table" + "github.com/GreptimeTeam/greptimedb-ingester-go/table/types" +) +``` + +
+ +
+ +```go +cfg := greptime.NewConfig("127.0.0.1"). + // 将数据库名称更改为你的数据库名称 + WithDatabase("public"). + // 默认端口 4001 + // WithPort(4001). + // 如果服务配置了 TLS ，设置 TLS 选项来启用安全连接 + // WithInsecure(false). + // 设置鉴权信息 + // 如果数据库不需要鉴权，移除 WithAuth 方法即可 + WithAuth("username", "password") + +cli, _ := greptime.NewClient(cfg) +``` +
+ +
+ +```go +// 为 CPU 指标构建表结构 +cpuMetric, err := table.New("cpu_metric") +if err != nil { + // 处理错误 +} + +// 添加一个 'Tag' 列，用于主机标识符 +cpuMetric.AddTagColumn("host", types.STRING) +// 添加一个 'Timestamp' 列，用于记录数据收集的时间 +cpuMetric.AddTimestampColumn("ts", types.TIMESTAMP_MILLISECOND) +// 添加 'Field' 列，用于测量用户和系统 CPU 使用率 +cpuMetric.AddFieldColumn("cpu_user", types.FLOAT) +cpuMetric.AddFieldColumn("cpu_sys", types.FLOAT) + +// 插入示例数据 +// 注意：参数必须按照定义的表结构中的列的顺序排列：host, ts, cpu_user, cpu_sys +err = cpuMetric.AddRow("127.0.0.1", time.Now(), 0.1, 0.12) +err = cpuMetric.AddRow("127.0.0.1", time.Now(), 0.11, 0.13) +if err != nil { + // 处理错误 +} + +``` + +
+ +
+ +```go +cpuMetric, err := table.New("cpu_metric") +if err != nil { + // 处理错误 +} +cpuMetric.AddTagColumn("host", types.STRING) +cpuMetric.AddTimestampColumn("ts", types.TIMESTAMP_MILLISECOND) +cpuMetric.AddFieldColumn("cpu_user", types.FLOAT) +cpuMetric.AddFieldColumn("cpu_sys", types.FLOAT) +err = cpuMetric.AddRow("127.0.0.1", time.Now(), 0.1, 0.12) +if err != nil { + // 处理错误 +} + +memMetric, err := table.New("mem_metric") +if err != nil { + // 处理错误 +} +memMetric.AddTagColumn("host", types.STRING) +memMetric.AddTimestampColumn("ts", types.TIMESTAMP_MILLISECOND) +memMetric.AddFieldColumn("mem_usage", types.FLOAT) +err = memMetric.AddRow("127.0.0.1", time.Now(), 112) +if err != nil { + // 处理错误 +} +``` + +
+ +
+ +```go +resp, err := cli.Write(context.Background(), cpuMetric, memMetric) +if err != nil { + // 处理错误 +} +log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) +``` + +
+ +
+ +```go +err := cli.StreamWrite(context.Background(), cpuMetric, memMetric) +if err != nil { + // 处理错误 +} +``` + +在所有数据写入完毕后关闭流式写入。 +一般情况下，连续写入数据时不需要关闭流式写入。 + +```go +affected, err := cli.CloseStream(ctx) +``` + +
+ +
+ +```go +type CpuMetric struct { + Host string `greptime:"tag;column:host;type:string"` + CpuUser float64 `greptime:"field;column:cpu_user;type:float64"` + CpuSys float64 `greptime:"field;column:cpu_sys;type:float64"` + Ts time.Time `greptime:"timestamp;column:ts;type:timestamp;precision:millisecond"` +} + +func (CpuMetric) TableName() string { + return "cpu_metric" +} + +cpuMetrics := []CpuMetric{ + { + Host: "127.0.0.1", + CpuUser: 0.10, + CpuSys: 0.12, + Ts: time.Now(), + } +} +``` + +
+ +
+ +```go +resp, err := cli.WriteObject(context.Background(), cpuMetrics) +log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) +``` + +
+ +
+ +```go +err := streamClient.StreamWriteObject(context.Background(), cpuMetrics, memMetrics) +``` + +在所有数据写入完毕后关闭流式写入。 +一般情况下，连续写入数据时不需要关闭流式写入。 + +```go +affected, err := cli.CloseStream(ctx) +``` + +
+ +
+ +在[低层级 API](#低层级-api) 中， +你可以使用 `AddFieldColumn` 方法将列类型指定为 `types.JSON` 来添加 JSON 列。 +然后使用 `struct` 或 `map` 插入 JSON 数据。 + +```go +sensorReadings, err := table.New("sensor_readings") +// 此处省略了创建其他列的代码 +// ... +// 将列类型指定为 JSON +sensorReadings.AddFieldColumn("attributes", types.JSON) + +// 使用 struct 插入 JSON 数据 +type Attributes struct { + Location string `json:"location"` + Action string `json:"action"` +} +attributes := Attributes{ Location: "factory-1" } +sensorReadings.AddRow(... , attributes) + +// 以下省略了写入数据的代码 +// ... +``` + +在[高层级 API](#高层级-api) 中，你可以使用 `greptime:"field;column:details;type:json"` 标签将列类型指定为 JSON。 + +```go +type SensorReadings struct { + // 此处省略了创建其他列的代码 + // ... + // 将列类型指定为 JSON + Attributes string `greptime:"field;column:details;type:json"` + // ... +} + +// 使用 struct 插入 JSON 数据 +type Attributes struct { + Location string `json:"location"` + Action string `json:"action"` +} +attributes := Attributes{ Action: "running" } +sensor := SensorReadings{ + // ... + Attributes: attributes, +} + +// 以下省略了写入数据的代码 +// ... +``` + +请参考 SDK 仓库中的[示例](https://github.com/GreptimeTeam/greptimedb-ingester-go/tree/main/examples/jsondata) 获取插入 JSON 数据的可执行代码。 + +
+ +
+ +- [API 文档](https://pkg.go.dev/github.com/GreptimeTeam/greptimedb-ingester-go) + +
+ + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/java.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/java.md new file mode 100644 index 000000000..896d128b3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/java.md @@ -0,0 +1,368 @@ +--- +description: 介绍如何使用 GreptimeDB 提供的 Java ingester SDK 写入数据，包括安装、连接、插入数据和调试日志等内容。 +--- + +import DocTemplate from './template.md' + +# Java + + + +
+ +GreptimeDB 提供的 Java ingester SDK 是一个轻量级库，具有以下特点： + +- 基于 SPI 的可扩展网络传输层，提供了使用 gRPC 框架的默认实现。 +- 非阻塞、纯异步的易于使用的 API。 +- 默认情况下自动收集各种性能指标，然后可以配置并将其写入本地文件。 +- 能够对关键对象进行内存快照，配置并将其写入本地文件。这对于解决复杂问题很有帮助。 + +
+ +
+ +你可以通过[快速开始 Demo](https://github.com/GreptimeTeam/greptimedb-ingester-java/tree/main/ingester-example/src/main/java/io/greptime) 来了解如何使用 GreptimeDB Java SDK。 + +
+ +
+ +1. 安装 Java 开发工具包（JDK） + +确保你的系统已安装 JDK 8 或更高版本。有关如何检查 Java 版本并安装 JDK 的更多信息，请参见 [Oracle JDK 安装概述文档](https://www.oracle.com/java/technologies/javase-downloads.html) + +2. 将 GreptimeDB Java SDK 添加为依赖项 + +如果你使用的是 [Maven](https://maven.apache.org/)，请将以下内容添加到 pom.xml 的依赖项列表中： + +```xml + + io.greptime + ingester-all + VAR::javaSdkVersion + +``` + +最新版本可以在 [这里](https://central.sonatype.com/search?q=io.greptime&name=ingester-all) 查看。 + +配置依赖项后，请确保它们对项目可用，这可能需要在 IDE 中刷新项目或运行依赖项管理器。 + +
+ +
+ + +下方的代码展示了以最简单的配置连接到 GreptimeDB 的方法。 +如果想要自定义连接选项，请参考 [API 文档](#ingester-库参考)。 +请注意每个选项的注释，它们提供了对其各自角色的详细解释。 + +```java +// GreptimeDB 默认 database 为 "public"，默认 catalog 为 "greptime"， +// 我们可以将其作为测试数据库使用 +String database = "public"; +// 默认情况下，GreptimeDB 使用 gRPC 协议在监听端口 4001。 +// 我们可以提供多个指向同一 GreptimeDB 集群的 endpoints， +// 客户端将根据负载均衡策略调用这些 endpoints。 +String[] endpoints = {"127.0.0.1:4001"}; +// 设置鉴权信息 +AuthInfo authInfo = new AuthInfo("username", "password"); +GreptimeOptions opts = GreptimeOptions.newBuilder(endpoints, database) + // 如果数据库不需要鉴权，我们可以使用 AuthInfo.noAuthorization() 作为参数。 + .authInfo(authInfo) + // 如果服务配置了 TLS ，设置 TLS 选项来启用安全连接 + //.tlsOptions(new TlsOptions()) + // 好的开始 ^_^ + .build(); + +GreptimeDB client = GreptimeDB.create(opts); +``` + +
+ +
+ +```java +// 为 CPU 指标构建表结构 +TableSchema cpuMetricSchema = TableSchema.newBuilder("cpu_metric") + .addTag("host", DataType.String) // 主机的标识符 + .addTimestamp("ts", DataType.TimestampMillisecond) // 毫秒级的时间戳 + .addField("cpu_user", DataType.Float64) // 用户进程的 CPU 使用率 + .addField("cpu_sys", DataType.Float64) // 系统进程的 CPU 使用率 + .build(); + +// 根据定义的模式创建表 +Table cpuMetric = Table.from(cpuMetricSchema); + +// 单行的示例数据 +String host = "127.0.0.1"; // 主机标识符 +long ts = System.currentTimeMillis(); // 当前时间戳 +double cpuUser = 0.1; // 用户进程的 CPU 使用率（百分比） +double cpuSys = 0.12; // 系统进程的 CPU 使用率（百分比） + +// 将一行数据插入表中 +// 注意：参数必须按照定义的表结构的列顺序排列：host, ts, cpu_user, cpu_sys +cpuMetric.addRow(host, ts, cpuUser, cpuSys); +``` + +
+ +
+ +```java +// 创建表结构 +TableSchema cpuMetricSchema = TableSchema.newBuilder("cpu_metric") + .addTag("host", DataType.String) + .addTimestamp("ts", DataType.TimestampMillisecond) + .addField("cpu_user", DataType.Float64) + .addField("cpu_sys", DataType.Float64) + .build(); + +TableSchema memMetricSchema = TableSchema.newBuilder("mem_metric") + .addTag("host", DataType.String) + .addTimestamp("ts", DataType.TimestampMillisecond) + .addField("mem_usage", DataType.Float64) + .build(); + +Table cpuMetric = Table.from(cpuMetricSchema); +Table memMetric = Table.from(memMetricSchema); + +// 添加行数据 +for (int i = 0; i < 10; i++) { + String host = "127.0.0." + i; + long ts = System.currentTimeMillis(); + double cpuUser = i + 0.1; + double cpuSys = i + 0.12; + cpuMetric.addRow(host, ts, cpuUser, cpuSys); +} + +for (int i = 0; i < 10; i++) { + String host = "127.0.0." + i; + long ts = System.currentTimeMillis(); + double memUsage = i + 0.2; + memMetric.addRow(host, ts, memUsage); +} + +``` + +
+ +
+ +```java +// 插入数据 + +// 考虑到尽可能提升性能和降低资源占用，SDK 设计为纯异步的。 +// 返回值是一个 future 对象。如果你想立即获取结果，可以调用 `future.get()`。 +CompletableFuture> future = greptimeDB.write(cpuMetric, memMetric); + +Result result = future.get(); + +if (result.isOk()) { + LOG.info("Write result: {}", result.getOk()); +} else { + LOG.error("Failed to write: {}", result.getErr()); +} + +``` + +
+ +
+ + +```java +StreamWriter writer = greptimeDB.streamWriter(); + +// 写入数据到流中 +writer.write(cpuMetric); +writer.write(memMetric); + +// 你可以对流执行操作，例如删除前 5 行 +writer.write(cpuMetric.subRange(0, 5), WriteOp.Delete); +``` + +在所有数据写入完毕后关闭流式写入。 +一般情况下，连续写入数据时不需要关闭流式写入。 + +```java +// 完成流式写入 +CompletableFuture future = writer.completed(); +WriteOk result = future.get(); +LOG.info("Write result: {}", result); +``` + +
+ + +
+ +GreptimeDB Java Ingester SDK 允许我们使用基本的 POJO 对象进行写入。虽然这种方法需要使用 Greptime 的注解，但它们很容易使用。 + +```java +@Metric(name = "cpu_metric") +public class Cpu { + @Column(name = "host", tag = true, dataType = DataType.String) + private String host; + + @Column(name = "ts", timestamp = true, dataType = DataType.TimestampMillisecond) + private long ts; + + @Column(name = "cpu_user", dataType = DataType.Float64) + private double cpuUser; + @Column(name = "cpu_sys", dataType = DataType.Float64) + private double cpuSys; + + // getters and setters + // ... +} + +@Metric(name = "mem_metric") +public class Memory { + @Column(name = "host", tag = true, dataType = DataType.String) + private String host; + + @Column(name = "ts", timestamp = true, dataType = DataType.TimestampMillisecond) + private long ts; + + @Column(name = "mem_usage", dataType = DataType.Float64) + private double memUsage; + // getters and setters + // ... +} + +// 添加行 +List cpus = new ArrayList<>(); +for (int i = 0; i < 10; i++) { + Cpu c = new Cpu(); + c.setHost("127.0.0." + i); + c.setTs(System.currentTimeMillis()); + c.setCpuUser(i + 0.1); + c.setCpuSys(i + 0.12); + cpus.add(c); +} + +List memories = new ArrayList<>(); +for (int i = 0; i < 10; i++) { + Memory m = new Memory(); + m.setHost("127.0.0." + i); + m.setTs(System.currentTimeMillis()); + m.setMemUsage(i + 0.2); + memories.add(m); +} +``` + +
+ + +
+ +写入 POJO 对象： + +```java +// 插入数据 + +CompletableFuture> puts = greptimeDB.writePOJOs(cpus, memories); + +Result result = puts.get(); + +if (result.isOk()) { + LOG.info("Write result: {}", result.getOk()); +} else { + LOG.error("Failed to write: {}", result.getErr()); +} +``` + +
+ +
+ +```java +StreamWriter, WriteOk> writer = greptimeDB.streamWriterPOJOs(); + +// 写入数据到流中 +writer.write(cpus); +writer.write(memories); + +// 你可以对流执行操作，例如删除前 5 行 +writer.write(cpus.subList(0, 5), WriteOp.Delete); +``` + +在所有数据写入完毕后关闭流式写入。 +一般情况下，连续写入数据时不需要关闭流式写入。 + +```java +// 完成流式写入 +CompletableFuture future = writer.completed(); +WriteOk result = future.get(); +LOG.info("Write result: {}", result); +``` + +
+ +
+ +在[低层级 API](#低层级-api) 中， +你可以使用 `addField` 方法将列类型指定为 `DataType.Json` 来添加 JSON 列， +然后使用 Map 对象添加 JSON 数据。 + +```java +// 为 sensor_readings 表构建表结构 +TableSchema sensorReadings = TableSchema.newBuilder("sensor_readings") + // 此处省略了创建其他列的代码 + // ... + // 将列类型指定为 JSON + .addField("attributes", DataType.Json) + .build(); + +// ... +// 使用 map 添加 JSON 数据 +Map attr = new HashMap<>(); +attr.put("location", "factory-1"); +sensorReadings.addRow(... , attr); + +// 以下省略了写入数据的代码 +// ... +``` + +在[高层级 API](#高层级-api) 中，你可以在 POJO 对象中指定列类型为 `DataType.Json`。 + +```java +@Metric(name = "sensor_readings") +public class Sensor { + // 此处省略了创建其他列的代码 + // ... + // 将列类型指定为 JSON + @Column(name = "attributes", dataType = DataType.Json) + private Map attributes; + // ... +} + +Sensor sensor = new Sensor(); +// ... +// 使用 map 添加 JSON 数据 +Map attr = new HashMap<>(); +attr.put("action", "running"); +sensor.setAttributes(attr); + +// 以下省略了写入数据的代码 +// ... +``` + +
+ +
+ +## 调试日志 + +Java SDK 提供了用于调试的指标和日志。 +请参考 [Metrics & Display](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/docs/metrics-display.md) 和 [Magic Tools](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/docs/magic-tools.md) 了解如何启用或禁用日志。 + +
+ +
+ +- [API 文档](https://javadoc.io/doc/io.greptime/ingester-protocol/latest/index.html) + +
+ + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/overview.md new file mode 100644 index 000000000..049be1b5e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/overview.md @@ -0,0 +1,11 @@ +--- +description: 演示如何使用 SDK 在 GreptimeDB 中写入数据，提供 Go 和 Java 的示例。 +--- + +# 概述 + +本指南将演示如何使用 SDK 在 GreptimeDB 中写入数据。 + +- [Go](go.md) +- [Java](java.md) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/template.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/template.md new file mode 100644 index 000000000..964333374 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/template.md @@ -0,0 +1,103 @@ + +GreptimeDB 提供了用于高吞吐量数据写入的 ingester 库。 +它使用 gRPC 协议，支持自动生成表结构，无需在写入数据前创建表。 +更多信息请参考 [自动生成表结构](/user-guide/ingest-data/overview.md#自动生成表结构)。 + + + +## 快速开始 Demo + + + +## 安装 + + + +## 连接数据库 + +如果你在启动 GreptimeDB 时设置了 [`--user-provider`](/user-guide/deployments/authentication/overview.md)， +则需要提供用户名和密码才能连接到 GreptimeDB。 +以下示例显示了使用 SDK 连接到 GreptimeDB 时如何设置用户名和密码。 + + + +## 数据模型 + +表中的每条行数据包含三种类型的列：`Tag`、`Timestamp` 和 `Field`。更多信息请参考 [数据模型](/user-guide/concepts/data-model.md)。 +列值的类型可以是 `String`、`Float`、`Int`、`JSON`, `Timestamp` 等。更多信息请参考 [数据类型](/reference/sql/data-types.md)。 + +## 低层级 API + +GreptimeDB 的低层级 API 通过向具有预定义模式的 `table` 对象添加 `row` 来写入数据。 + +### 创建行数据 + +以下代码片段首先构建了一个名为 `cpu_metric` 的表，其中包括 `host`、`cpu_user`、`cpu_sys` 和 `ts` 列。 +随后，它向表中插入了一行数据。 + +该表包含三种类型的列： + +- `Tag`：`host` 列，值类型为 `String`。 +- `Field`：`cpu_user` 和 `cpu_sys` 列，值类型为 `Float`。 +- `Timestamp`：`ts` 列，值类型为 `Timestamp`。 + + + +为了提高写入数据的效率，你可以一次创建多行数据以便写入到 GreptimeDB。 + + + +### 插入数据 + +下方示例展示了如何向 GreptimeDB 的表中插入行数据。 + + + +### 流式插入 + +当你需要插入大量数据时，例如导入历史数据，流式插入是非常有用的。 + + + + + + + +## 高层级 API + +SDK 的高层级 API 使用 ORM 风格的对象写入数据， +它允许你以更面向对象的方式创建、插入和更新数据，为开发者提供了更友好的体验。 +然而，高层级 API 不如低层级 API 高效。 +这是因为 ORM 风格的对象在转换对象时可能会消耗更多的资源和时间。 + +### 创建行数据 + + + +### 插入数据 + + + +### 流式插入 + +当你需要插入大量数据时，例如导入历史数据，流式插入是非常有用的。 + + + + + +## 插入 JSON 类型的数据 + +GreptimeDB 支持使用 [JSON 类型数据](/reference/sql/data-types.md#json-类型) 存储复杂的数据结构。 +使用此 ingester 库，你可以通过字符串值插入 JSON 数据。 +假如你有一个名为 `sensor_readings` 的表，并希望添加一个名为 `attributes` 的 JSON 列， +请参考以下代码片段。 + + + + + +## Ingester 库参考 + + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/influxdb-line-protocol.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/influxdb-line-protocol.md new file mode 100644 index 000000000..a10adaf2d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/influxdb-line-protocol.md @@ -0,0 +1,205 @@ +--- +description: 详细介绍如何使用 InfluxDB Line Protocol 将数据写入 GreptimeDB，包括协议、鉴权、Telegraf 集成和数据模型映射。 +--- + +# InfluxDB Line Protocol + +GreptimeDB 支持 HTTP InfluxDB Line 协议。 + +## 写入新数据 + +### 协议 + +#### Post 指标 + +你可以通过 `/influxdb/write` API 写入数据。 +以下是一个示例： + + + + + +```shell +curl -i -XPOST "http://localhost:4000/v1/influxdb/api/v2/write?db=public&precision=ms" \ +--data-binary \ +'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 1667446797450 + monitor,host=127.0.0.2 cpu=0.2,memory=0.3 1667446798450 + monitor,host=127.0.0.1 cpu=0.5,memory=0.2 1667446798450' +``` + + + + +```shell +curl -i -XPOST "http://localhost:4000/v1/influxdb/write?db=public&precision=ms" \ +--data-binary \ +'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 1667446797450 + monitor,host=127.0.0.2 cpu=0.2,memory=0.3 1667446798450 + monitor,host=127.0.0.1 cpu=0.5,memory=0.2 1667446798450' +``` + + + + +`/influxdb/write` 支持查询参数，包括： + +* `db`：指定要写入的数据库。默认值为 `public`。 +* `precision`：定义请求体中提供的时间戳的精度，可接受的值为 `ns`（纳秒）、`us`（微秒）、`ms`（毫秒）和 `s`（秒），默认值为 `ns`（纳秒）。该 API 写入的时间戳类型为 `TimestampNanosecond`，因此默认精度为 `ns`（纳秒）。如果你在请求体中使用了其他精度的的时间戳，需要使用此参数指定精度。该参数确保时间戳能够被准确解释并以纳秒精度存储。 + +你还可以在发送请求时省略 timestamp，GreptimeDB 将使用主机机器的当前系统时间（UTC 时间）作为 timestamp。例如： + + + + + +```shell +curl -i -XPOST "http://localhost:4000/v1/influxdb/api/v2/write?db=public" \ +--data-binary \ +'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 + monitor,host=127.0.0.2 cpu=0.2,memory=0.3 + monitor,host=127.0.0.1 cpu=0.5,memory=0.2' +``` + + + + +```shell +curl -i -XPOST "http://localhost:4000/v1/influxdb/write?db=public" \ +--data-binary \ +'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 + monitor,host=127.0.0.2 cpu=0.2,memory=0.3 + monitor,host=127.0.0.1 cpu=0.5,memory=0.2' +``` + + + + +#### 鉴权 + +GreptimeDB 与 InfluxDB 的行协议鉴权格式兼容，包括 V1 和 V2。 +如果你在 GreptimeDB 中[配置了鉴权](/user-guide/deployments/authentication/overview.md)，需要在 HTTP 请求中提供用户名和密码。 + + + + + +InfluxDB 的 [V2 协议](https://docs.influxdata.com/influxdb/v1.8/tools/api/?t=Auth+Enabled#apiv2query-http-endpoint) 使用了类似 HTTP 标准 basic 认证方案的格式。 + +```shell +curl 'http://localhost:4000/v1/influxdb/api/v2/write?db=public' \ + -H 'authorization: token :' \ + -d 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4' +``` + + + + + +对于 InfluxDB 的 [V1 协议](https://docs.influxdata.com/influxdb/v1.8/tools/api/?t=Auth+Enabled#query-string-parameters-1) 的鉴权格式。在 HTTP 查询字符串中添加 `u` 作为用户和 `p` 作为密码，如下所示： + +```shell +curl 'http://localhost:4000/v1/influxdb/write?db=public&u=&p=' \ + -d 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4' +``` + + + + +### Telegraf + +GreptimeDB 支持 [InfluxDB 行协议](../for-iot/influxdb-line-protocol.md)也意味着 GreptimeDB 与 Telegraf 兼容。 +要配置 Telegraf，只需将 GreptimeDB 的 URL 添加到 Telegraf 配置中： + + + + + +```toml +[[outputs.influxdb_v2]] + urls = ["http://:4000/v1/influxdb"] + token = ":" + bucket = "" + ## Leave empty + organization = "" +``` + + + + + +```toml +[[outputs.influxdb]] + urls = ["http://:4000/v1/influxdb"] + database = "" + username = "" + password = "" +``` + + + + + +## 数据模型 + +你可能已经熟悉了 [InfluxDB 的关键概念](https://docs.influxdata.com/influxdb/v2/reference/key-concepts/)， +GreptimeDB 的[数据模型](/user-guide/concepts/data-model.md) 是值得了解的新事物。 +下方解释了 GreptimeDB 和 InfluxDB 数据模型的相似和不同之处： + +- 两者都是 [schemaless 写入](/user-guide/ingest-data/overview.md#自动生成表结构)的解决方案，这意味着在写入数据之前无需定义表结构。 +- GreptimeDB 的表在自动创建时会设置表选项 [`merge_mode`](/reference/sql/create.md#创建带有-merge-模式的表)为 `last_non_null`。 + 这意味着表会通过保留每个字段的最新值来合并具有相同主键和时间戳的行，该行为与 InfluxDB 相同。 +- 在 InfluxDB 中，一个点代表一条数据记录，包含一个 measurement、tag 集、field 集和时间戳。 + 在 GreptimeDB 中，它被表示为时间序列表中的一行数据。 + 表名对应于 measurement，列由三种类型组成：Tag、Field 和 Timestamp。 +- GreptimeDB 使用 `TimestampNanosecond` 作为来自 [InfluxDB 行协议 API](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md) 的时间戳数据类型。 +- GreptimeDB 使用 `Float64` 作为来自 InfluxDB 行协议 API 的数值数据类型。 + +以 InfluxDB 文档中的[示例数据](https://docs.influxdata.com/influxdb/v2/reference/key-concepts/data-elements/#sample-data)为例： + +|_time|_measurement|location|scientist|_field|_value| +|---|---|---|---|---|---| +|2019-08-18T00:00:00Z|census|klamath|anderson|bees|23| +|2019-08-18T00:00:00Z|census|portland|mullen|ants|30| +|2019-08-18T00:06:00Z|census|klamath|anderson|bees|28| +|2019-08-18T00:06:00Z|census|portland|mullen|ants|32| + +上述数据的 InfluxDB 行协议格式为： + +```shell +census,location=klamath,scientist=anderson bees=23 1566086400000000000 +census,location=portland,scientist=mullen ants=30 1566086400000000000 +census,location=klamath,scientist=anderson bees=28 1566086760000000000 +census,location=portland,scientist=mullen ants=32 1566086760000000000 +``` + +在 GreptimeDB 数据模型中，上述数据将被表示为 `census` 表中的以下内容： + +```sql ++---------------------+----------+-----------+------+------+ +| ts | location | scientist | bees | ants | ++---------------------+----------+-----------+------+------+ +| 2019-08-18 00:00:00 | klamath | anderson | 23 | NULL | +| 2019-08-18 00:06:00 | klamath | anderson | 28 | NULL | +| 2019-08-18 00:00:00 | portland | mullen | NULL | 30 | +| 2019-08-18 00:06:00 | portland | mullen | NULL | 32 | ++---------------------+----------+-----------+------+------+ +``` + +`census` 表结构如下： + +```sql ++-----------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-----------+----------------------+------+------+---------+---------------+ +| location | String | PRI | YES | | TAG | +| scientist | String | PRI | YES | | TAG | +| bees | Float64 | | YES | | FIELD | +| ts | TimestampNanosecond | PRI | NO | | TIMESTAMP | +| ants | Float64 | | YES | | FIELD | ++-----------+----------------------+------+------+---------+---------------+ +``` + +## 参考 + +- [InfluxDB Line protocol](https://docs.influxdata.com/influxdb/v2.7/reference/syntax/line-protocol/) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/opentsdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/opentsdb.md new file mode 100644 index 000000000..d5bee0196 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/opentsdb.md @@ -0,0 +1,60 @@ +--- +description: 介绍如何使用 OpenTSDB 协议通过 HTTP API 将数据写入 GreptimeDB，包括示例代码和注意事项。 +--- + +# OpenTSDB + +GreptimeDB支持通过 HTTP API 使用 OpenTSDB 协议。 + +## 写入新数据 + +### HTTP API + +GreptimeDB 还支持通过 HTTP 接口插入 OpenTSDB 数据，接口是 `/opentsdb/api/put`，使用的请求和响应格式与 OpenTSDB 的 `/api/put` 接口相同。 + +GreptimeDB 的 HTTP Server 默认监听 `4000` 端口。例如使用 curl 写入一个指标数据： + +```shell +curl -X POST http://127.0.0.1:4000/v1/opentsdb/api/put -d ' +{ + "metric": "sys.cpu.nice", + "timestamp": 1667898896, + "value": 18, + "tags": { + "host": "web01", + "dc": "hz" + } +} +' +``` + +插入多个指标数据: + +```shell +curl -X POST http://127.0.0.1:4000/v1/opentsdb/api/put -d ' +[ + { + "metric": "sys.cpu.nice", + "timestamp": 1667898896, + "value": 1, + "tags": { + "host": "web02", + "dc": "hz" + } + }, + { + "metric": "sys.cpu.nice", + "timestamp": 1667898897, + "value": 9, + "tags": { + "host": "web03", + "dc": "sh" + } + } +] +' +``` + +:::tip 注意 +记得在路径前加上 GreptimeDB 的 HTTP API 版本 `v1`。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/overview.md new file mode 100644 index 000000000..93c51d26f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/overview.md @@ -0,0 +1,19 @@ +--- +description: 概述 GreptimeDB 支持的各种数据写入方法，包括 SQL、gRPC SDK、InfluxDB Line Protocol、EMQX 和 OpenTSDB。 +--- + +# 概述 + +数据的写入是物联网数据流程的关键部分。 +它从各种来源（如传感器、设备和应用程序）收集数据并将其存储在中央位置以供进一步处理和分析。 +数据写入过程对于确保数据的准确性、可靠性和安全性至关重要。 + +GreptimeDB 可处理并存储超大规模量级的数据以供分析， +支持各种数据格式、协议和接口，以便集成不同的物联网设备和系统。 + +- [SQL INSERT](sql.md)：简单直接的数据插入方法。 +- [gRPC SDK](./grpc-sdks/overview.md)：提供高效、高性能的数据写入，特别适用于实时数据和复杂的物联网基础设施。 +- [InfluxDB Line Protocol](influxdb-line-protocol.md)：一种广泛使用的时间序列数据协议，便于从 InfluxDB 迁移到 GreptimeDB。该文档同样介绍了 Telegraf 的集成方式。 +- [EMQX](emqx.md)：支持大规模设备连接的 MQTT 代理，可直接将数据写入到 GreptimeDB。 +- [OpenTSDB](opentsdb.md)：使用 OpenTSDB 协议将数据写入到 GreptimeDB。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/sql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/sql.md new file mode 100644 index 000000000..0bf71b5eb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-iot/sql.md @@ -0,0 +1,118 @@ +--- +description: 介绍如何使用 SQL 将数据写入 GreptimeDB，包括创建表、插入数据和时区设置等内容。 +--- + +# SQL + +你可以使用 [MySQL](/user-guide/protocols/mysql.md) 或 [PostgreSQL](/user-guide/protocols/postgresql.md) 客户端执行 SQL 语句， +使用任何你喜欢的编程语言（如Java JDBC）通过 MySQL 或 PostgreSQL 协议访问 GreptimeDB。 + +我们将使用 `monitor` 表作为示例来展示如何写入数据。有关如何创建 `monitor` 表的 SQL 示例，请参见[表管理](/user-guide/administration/manage-data/basic-table-operations.md#创建表)。 + +## 创建表 + +在插入数据之前，你需要创建一个表。例如，创建一个名为 `monitor` 的表： + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64 DEFAULT 0, + memory FLOAT64, + PRIMARY KEY(host)); +``` + +上述语句将创建一个具有以下 schema 的表： + +```sql ++--------+----------------------+------+------+---------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------+----------------------+------+------+---------------------+---------------+ +| host | String | PRI | YES | | TAG | +| ts | TimestampMillisecond | PRI | NO | current_timestamp() | TIMESTAMP | +| cpu | Float64 | | YES | 0 | FIELD | +| memory | Float64 | | YES | | FIELD | ++--------+----------------------+------+------+---------------------+---------------+ +4 rows in set (0.01 sec) +``` + +有关 `CREATE TABLE` 语句的更多信息，请参阅[表管理](/user-guide/administration/manage-data/basic-table-operations.md#create-a-table)。 + +## 插入数据 + +让我们向 `monitor` 表中插入一些测试数据。你可以使用 `INSERT INTO` 语句： + +```sql +INSERT INTO monitor +VALUES + ("127.0.0.1", 1702433141000, 0.5, 0.2), + ("127.0.0.2", 1702433141000, 0.3, 0.1), + ("127.0.0.1", 1702433146000, 0.3, 0.2), + ("127.0.0.2", 1702433146000, 0.2, 0.4), + ("127.0.0.1", 1702433151000, 0.4, 0.3), + ("127.0.0.2", 1702433151000, 0.2, 0.4); +``` + +```sql +Query OK, 6 rows affected (0.01 sec) +``` + +你还可以插入数据时指定列名： + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES + ("127.0.0.1", 1702433141000, 0.5, 0.2), + ("127.0.0.2", 1702433141000, 0.3, 0.1), + ("127.0.0.1", 1702433146000, 0.3, 0.2), + ("127.0.0.2", 1702433146000, 0.2, 0.4), + ("127.0.0.1", 1702433151000, 0.4, 0.3), + ("127.0.0.2", 1702433151000, 0.2, 0.4); +``` + +通过上面的语句，我们成功的向 `monitor` 表中插入了六条数据。请参考 [`INSERT`](/reference/sql/insert.md) 获得更多写入数据的相关信息。 + +## 时区 + +SQL 客户端中指定的时区将影响没有时区信息的字符串格式的时间戳。 +该时间戳值将会自动添加客户端的时区信息。 + +例如，下面的 SQL 将时区设置为 `+8:00`： + +```sql +SET time_zone = '+8:00'; +``` + +然后向 `monitor` 表中插入值： + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES + ("127.0.0.1", "2024-01-01 00:00:00", 0.4, 0.1), + ("127.0.0.2", "2024-01-01 00:00:00+08:00", 0.5, 0.1); +``` + +第一个时间戳值 `2024-01-01 00:00:00` 没有时区信息，因此它将自动添加客户端的时区信息。 +在插入数据后，它将等同于第二个值 `2024-01-01 00:00:00+08:00`。 + +`+8:00` 时区下的结果如下： + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-01-01 00:00:00 | 0.4 | 0.1 | +| 127.0.0.2 | 2024-01-01 00:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` + +`UTC` 时区下的结果如下： + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2023-12-31 16:00:00 | 0.4 | 0.1 | +| 127.0.0.2 | 2023-12-31 16:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/influxdb-line-protocol.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/influxdb-line-protocol.md new file mode 100644 index 000000000..c353085db --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/influxdb-line-protocol.md @@ -0,0 +1,4 @@ +# InfluxDB Line Protocol + + +请参考 [InfluxDB Line Protocol 文档](../for-iot/influxdb-line-protocol.md) 了解如何使用 InfluxDB Line Protocol 将数据写入到 GreptimeDB。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/loki.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/loki.md new file mode 100644 index 000000000..a94cdc395 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/loki.md @@ -0,0 +1,126 @@ +--- +description: 介绍如何使用 Loki 将日志数据发送到 GreptimeDB，包括 API 信息、示例代码和数据模型映射。 +--- + +# Loki + +## 使用方法 + +### API + +要通过原始 HTTP API 将日志发送到 GreptimeDB，请使用以下信息： + +* URL: `http{s}:///v1/loki/api/v1/push` +* Headers: + * `X-Greptime-DB-Name`: `` + * `Authorization`: `Basic` 认证，这是一个 Base64 编码的 `:` 字符串。更多信息，请参考 [认证](https://docs.greptime.com/user-guide/deployments/authentication/static/) 和 [HTTP API](https://docs.greptime.com/user-guide/protocols/http#authentication)。 + * `X-Greptime-Log-Table-Name`: ``（可选）- 存储日志的表名。如果未提供，默认表名为 `loki_logs`。 + +请求使用二进制 protobuf 编码负载，定义的格式与 [logproto.proto](https://github.com/grafana/loki/blob/main/pkg/logproto/logproto.proto) 相同。 + +### 示例代码 + +[Grafana Alloy](https://grafana.com/docs/alloy/latest/) 是一个供应商中立的 OpenTelemetry (OTel) Collector 发行版。Alloy 独特地结合了社区中最好的开源可观测性信号。 + +它提供了一个 Loki 导出器，可以用来将日志发送到 GreptimeDB。以下是一个配置示例： + +```hcl +loki.source.file "greptime" { + targets = [ + {__path__ = "/tmp/foo.txt"}, + ] + forward_to = [loki.write.greptime_loki.receiver] +} + +loki.write "greptime_loki" { + endpoint { + url = "${GREPTIME_SCHEME:=http}://${GREPTIME_HOST:=greptimedb}:${GREPTIME_PORT:=4000}/v1/loki/api/v1/push" + headers = { + "x-greptime-db-name" = "${GREPTIME_DB:=public}", + "x-greptime-log-table-name" = "${GREPTIME_LOG_TABLE_NAME:=loki_demo_logs}", + } + } + external_labels = { + "job" = "greptime" + "from" = "alloy" + } +} +``` + +我们监听文件 `/tmp/foo.txt` 并将日志发送到 GreptimeDB。日志存储在表 `loki_demo_logs` 中，并带有 label `job` 和 `from`。 + +更多信息，请参考 [Grafana Alloy loki.write 文档](https://grafana.com/docs/alloy/latest/reference/components/loki/loki.write/)。 + +你可以运行以下命令来检查表中的数据： + +```sql +SELECT * FROM loki_demo_logs; ++----------------------------+------------------------+--------------+-------+----------+ +| greptime_timestamp | line | filename | from | job | ++----------------------------+------------------------+--------------+-------+----------+ +| 2024-11-25 11:02:31.256251 | Greptime is very cool! | /tmp/foo.txt | alloy | greptime | ++----------------------------+------------------------+--------------+-------+----------+ +1 row in set (0.01 sec) +``` + +## 数据模型 + +Loki 日志数据模型根据以下规则映射到 GreptimeDB 数据模型： + +没有 label 的默认表结构： + +```sql +DESC loki_demo_logs; ++--------------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+---------------------+------+------+---------+---------------+ +| greptime_timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | +| line | String | | YES | | FIELD | ++--------------------+---------------------+------+------+---------+---------------+ +5 rows in set (0.00 sec) +``` + +- greptime_timestamp: 日志的时间戳。 +- line: 日志消息。 + +如果你指定了外部 label，我们会将它们添加为表结构中的 tag。例如上面的 `job` 和 `from`。 +在这种写入方式下不能手动指定，所有 label 都被视为 tag 并且类型为字符串。请不要尝试使用 SQL 提前创建表来指定 tag 列，这会导致类型不匹配而写入失败。 + +### 示例 + +以下是表结构的示例： + +```sql +DESC loki_demo_logs; ++--------------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+---------------------+------+------+---------+---------------+ +| greptime_timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | +| line | String | | YES | | FIELD | +| filename | String | PRI | YES | | TAG | +| from | String | PRI | YES | | TAG | +| job | String | PRI | YES | | TAG | ++--------------------+---------------------+------+------+---------+---------------+ +5 rows in set (0.00 sec) +``` + +```sql +SHOW CREATE TABLE loki_demo_logs\G +*************************** 1. row *************************** + Table: loki_demo_logs +Create Table: CREATE TABLE IF NOT EXISTS `loki_demo_logs` ( + `greptime_timestamp` TIMESTAMP(9) NOT NULL, + `line` STRING NULL, + `filename` STRING NULL, + `from` STRING NULL, + `job` STRING NULL, + TIME INDEX (`greptime_timestamp`), + PRIMARY KEY (`filename`, `from`, `job`) +) + +ENGINE=mito +WITH( + append_mode = 'true' +) +1 row in set (0.00 sec) +``` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/opentelemetry.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/opentelemetry.md new file mode 100644 index 000000000..b59dd3ff1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/opentelemetry.md @@ -0,0 +1,190 @@ +--- +description: 介绍如何使用 OpenTelemetry Protocol (OTLP) 将观测数据（如 metrics 和 logs）导出到 GreptimeDB，包括示例代码和数据模型的映射规则。 +--- + +# OpenTelemetry Protocol (OTLP) + +[OpenTelemetry](https://opentelemetry.io/) 是一个供应商中立的开源可观测性框架，用于检测、生成、收集和导出观测数据，例如 traces, metrics 和 logs。 +OpenTelemetry Protocol (OTLP) 定义了观测数据在观测源和中间进程（例如收集器和观测后端）之间的编码、传输机制。 +## Metrics + +### OTLP/HTTP + +import Includeotlpmetrycsintegration from '../../../db-cloud-shared/clients/otlp-metrics-integration.md' + + + +#### 示例代码 + +下面是一些编程语言设置请求的示例代码： + + + + + +```ts +const auth = Buffer.from(`${username}:${password}`).toString('base64') +const exporter = new OTLPMetricExporter({ + url: `https://${dbHost}/v1/otlp/v1/metrics`, + headers: { + Authorization: `Basic ${auth}`, + "X-Greptime-DB-Name": db, + }, + timeoutMillis: 5000, +}) +``` + + + + + +```Go +auth := base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("%s:%s", *username, *password))) +exporter, err := otlpmetrichttp.New( + context.Background(), + otlpmetrichttp.WithEndpoint(*dbHost), + otlpmetrichttp.WithURLPath("/v1/otlp/v1/metrics"), + otlpmetrichttp.WithHeaders(map[string]string{ + "X-Greptime-DB-Name": *dbName, + "Authorization": "Basic " + auth, + }), + otlpmetrichttp.WithTimeout(time.Second*5), +) +``` + + + + + +```Java +String endpoint = String.format("https://%s/v1/otlp/v1/metrics", dbHost); +String auth = username + ":" + password; +String b64Auth = new String(Base64.getEncoder().encode(auth.getBytes())); +OtlpHttpMetricExporter exporter = OtlpHttpMetricExporter.builder() + .setEndpoint(endpoint) + .addHeader("X-Greptime-DB-Name", db) + .addHeader("Authorization", String.format("Basic %s", b64Auth)) + .setTimeout(Duration.ofSeconds(5)) + .build(); +``` + + + + + +```python +auth = f"{username}:{password}" +b64_auth = base64.b64encode(auth.encode()).decode("ascii") +endpoint = f"https://{host}/v1/otlp/v1/metrics" +exporter = OTLPMetricExporter( + endpoint=endpoint, + headers={"Authorization": f"Basic {b64_auth}", "X-Greptime-DB-Name": db}, + timeout=5) +``` + + + + + +你可以在 Github 中找到可执行的 Demo：[Go](https://github.com/GreptimeCloudStarters/quick-start-go), [Java](https://github.com/GreptimeCloudStarters/quick-start-java), [Python](https://github.com/GreptimeCloudStarters/quick-start-python), and [Node.js](https://github.com/GreptimeCloudStarters/quick-start-node-js). + +:::tip 注意 +示例代码可能会根据 OpenTelemetry 的发展发生变化，因此建议你参考 OpenTelemetry 官方文档以获取最新信息。 +::: + +关于示例代码，请参考 Opentelementry 的官方文档获取它所支持的编程语言获取更多信息。 + +#### 数据模型 + +OTLP 指标数据模型按照下方的规则被映射到 GreptimeDB 数据模型中： + +- Metric 的名称将被作为 GreptimeDB 表的名称，当表不存在时会自动创建。 +- 所有的 Attribute ，包含 resource 级别、scope 级别和 data_point 级别，都被作为 GreptimeDB 表的 tag 列。 +- 数据点的时间戳被作为 GreptimeDB 的时间戳索引，列名 `greptime_timestamp`。 +- Gauge/Sum 两种类型的数据点数据被作为 field 列，列名 `greptime_value`。 +- Summary 类型的每个 quantile 被作为单独的数据列，列名 `greptime_pxx`，其中 xx 是 quantile 的数据，如 90 / 99 等。 +- Histogram 和 ExponentialHistogram 暂时未被支持，我们可能在后续版本中推出 Histogram 数据类型来原生支持这两种类型。 + +## Logs + +### OTLP/HTTP + +import Includeotlplogintegration from '../../../db-cloud-shared/clients/otlp-logs-integration.md' + + + +#### 示例代码 + +以下是一些关于如何使用 Grafana Alloy 将 OpenTelemetry 日志发送到 GreptimeDB 的示例代码： + +```hcl +loki.source.file "greptime" { + targets = [ + {__path__ = "/tmp/foo.txt"}, + ] + forward_to = [otelcol.receiver.loki.greptime.receiver] +} + +otelcol.receiver.loki "greptime" { + output { + logs = [otelcol.exporter.otlphttp.greptimedb_logs.input] + } +} + +otelcol.auth.basic "credentials" { + username = "${GREPTIME_USERNAME}" + password = "${GREPTIME_PASSWORD}" +} + +otelcol.exporter.otlphttp "greptimedb_logs" { + client { + endpoint = "${GREPTIME_SCHEME:=http}://${GREPTIME_HOST:=greptimedb}:${GREPTIME_PORT:=4000}/v1/otlp/" + headers = { + "X-Greptime-DB-Name" = "${GREPTIME_DB:=public}", + "x-greptime-log-table-name" = "demo_logs", + "x-greptime-log-extract-keys" = "filename,log.file.name,loki.attribute.labels", + } + auth = otelcol.auth.basic.credentials.handler + } +} +``` + +此示例监听文件的变化，并通过 OTLP 协议将最新的值发送到 GreptimeDB。 + +:::tip 提示 +上述示例代码可能会因 OpenTelemetry 的更新而过时。我们建议您参考 OpenTelemetry 和 Grafana Alloy 的官方文档以获取最新信息。 +::: + +有关示例代码的更多信息，请参考您首选编程语言的官方文档。 + +#### 数据模型 + +OTLP 日志数据模型根据以下规则映射到 GreptimeDB 数据模型： + +默认表结构： + +```sql ++-----------------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-----------------------+---------------------+------+------+---------+---------------+ +| timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | +| trace_id | String | | YES | | FIELD | +| span_id | String | | YES | | FIELD | +| severity_text | String | | YES | | FIELD | +| severity_number | Int32 | | YES | | FIELD | +| body | String | | YES | | FIELD | +| log_attributes | Json | | YES | | FIELD | +| trace_flags | UInt32 | | YES | | FIELD | +| scope_name | String | PRI | YES | | TAG | +| scope_version | String | | YES | | FIELD | +| scope_attributes | Json | | YES | | FIELD | +| scope_schema_url | String | | YES | | FIELD | +| resource_attributes | Json | | YES | | FIELD | +| resource_schema_url | String | | YES | | FIELD | ++-----------------------+---------------------+------+------+---------+---------------+ +17 rows in set (0.00 sec) +``` + +- 您可以使用 `X-Greptime-Log-Table-Name` 指定存储日志的表名。如果未提供，默认表名为 `opentelemetry_logs`。 +- 所有属性，包括资源属性、范围属性和日志属性，将作为 JSON 列存储在 GreptimeDB 表中。 +- 日志的时间戳将用作 GreptimeDB 中的时间戳索引，列名为 `timestamp`。建议使用 `time_unix_nano` 作为时间戳列。如果未提供 `time_unix_nano`，将使用 `observed_time_unix_nano`。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/overview.md new file mode 100644 index 000000000..b749a95db --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/overview.md @@ -0,0 +1,15 @@ +--- +description: 介绍 GreptimeDB 在可观测性场景中的应用，包括与 Prometheus、Vector、OpenTelemetry 和 InfluxDB Line Protocol 的集成。 +--- + +# 概述 + +在可观测性场景中，实时监控和分析系统性能的能力至关重要。 +GreptimeDB 与领先的可观测性工具无缝集成，为你提供系统健康和性能指标的全面视图。 + +- [Prometheus Remote Write](prometheus.md)：将 GreptimeDB 作为 Prometheus 的远程存储，适用于实时监控和警报。 +- [Vector](vector.md)：将 GreptimeDB 用作 Vector 的接收端，适用于复杂的数据流水线和多样化的数据源。 +- [OpenTelemetry](opentelemetry.md)：将 telemetry 数据收集并导出到 GreptimeDB，以获取详细的可观测性洞察。 +- [InfluxDB Line Protocol](influxdb-line-protocol.md)：一种广泛使用的时间序列数据协议，便于从 InfluxDB 迁移到 GreptimeDB。该文档同样介绍了 Telegraf 的集成方式。 +- [Loki](loki.md)：一种广泛使用的日志写入协议，便于从 Loki 迁移到 GreptimeDB。本文档还介绍了 Alloy 集成方法。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/prometheus.md new file mode 100644 index 000000000..b58d3b734 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/prometheus.md @@ -0,0 +1,154 @@ +--- +description: 介绍如何将 GreptimeDB 作为 Prometheus 的长期存储解决方案，包括配置 Remote Write 和数据模型的映射规则。 +--- + +# Prometheus + +GreptimeDB 可以作为 Prometheus 的长期存储解决方案，提供无缝集成体验。 + +## 配置 Remote Write + +要将 GreptimeDB 集成到 Prometheus 中， +请按照以下步骤更新你的 [Prometheus 配置文件](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#configuration-file)（`prometheus.yml`）： + +```yaml +remote_write: +- url: http://localhost:4000/v1/prometheus/write?db=public +# 如果启用了身份验证，请取消注释并设置鉴权信息 +# basic_auth: +# username: greptime_user +# password: greptime_pwd + +remote_read: +- url: http://localhost:4000/v1/prometheus/read?db=public +# 如果启用了身份验证，请取消注释并设置鉴权信息 +# basic_auth: +# username: greptime_user +# password: greptime_pwd +``` + +- URL 中的 host 和 port 表示 GreptimeDB 服务器。在此示例中，服务器运行在 `localhost:4000` 上。你可以将其替换为你自己的服务器地址。有关 GreptimeDB 中 HTTP 协议的配置，请参阅 [协议选项](/user-guide/deployments/configuration.md#protocol-options)。 +- URL 中的 `db` 参数表示要写入的数据库。它是可选的。默认情况下，数据库设置为 `public`。 +- `basic_auth` 是身份鉴权配置。如果 GreptimeDB 启用了鉴权，请填写用户名和密码。请参阅 [鉴权认证文档](/user-guide/deployments/authentication/overview.md)。 + +## 数据模型 + +在 GreptimeDB 的[数据模型](/user-guide/concepts/data-model.md)中，数据被组织成具有 tag、time index 和 field 的表。 +GreptimeDB 可以被视为多值数据模型，自动将多个 Prometheus 指标分组到相应的表中。 +这样可以实现高效的数据管理和查询。 + +![数据模型](/PromQL-multi-value-data-model.png) + +当指标通过远程写入端点写入 GreptimeDB 时，它们将被转换为以下形式： + +| Sample Metrics | In GreptimeDB | GreptimeDB Data Types | +|----------------|---------------------------|-----------------------| +| Name | Table (Auto-created) Name | String | +| Value | Column (Field) | Double | +| Timestamp | Column (Time Index) | Timestamp | +| Label | Column (Tag) | String | + +例如，以下 Prometheus 指标： + +```txt +prometheus_remote_storage_samples_total{instance="localhost:9090", job="prometheus", +remote_name="648f0c", url="http://localhost:4000/v1/prometheus/write"} 500 +``` + +将被转换为表 `prometheus_remote_storage_samples_total` 中的一行： + +| Column | Value | Column Data Type | +| :----------------- | :------------------------------------------ | :----------------- | +| instance | localhost:9090 | String | +| job | prometheus | String | +| remote_name | 648f0c | String | +| url | `http://localhost:4000/v1/prometheus/write` | String | +| greptime_value | 500 | Double | +| greptime_timestamp | The sample's unix timestamp | Timestamp | + + +## 通过使用 metric engine 提高效率 + +Prometheus Remote Write 写入数据的方式经常会创建大量的小表，这些表在 GreptimeDB 中被归类为逻辑表。 +然而，拥有大量的小表对于数据存储和查询性能来说是低效的。 +为了解决这个问题，GreptimeDB 引入了 [metric engine](/contributor-guide/datanode/metric-engine.md) 功能，将逻辑表表示的数据存储在单个物理表中。 +这种方法减少了存储开销并提高了列式压缩效率。 + +GreptimeDB 默认启用 metric engine，你不需要指定任何额外的配置。 +默认情况下，使用的物理表为 `greptime_physical_table`。 +如果你想使用特定的物理表，可以在 Remote Write URL 中指定 `physical_table` 参数。 +如果指定的物理表不存在，它将被自动创建。 + +```yaml +remote_write: +- url: http://localhost:4000/v1/prometheus/write?db=public&physical_table=greptime_physical_table +``` + +虽然数据被存储在物理表中，但查询可以在逻辑表上执行以提供从指标角度的直观视角。 +例如，当成功写入数据时，你可以使用以下命令显示逻辑表： + +```sql +show tables; +``` + +```sql ++---------------------------------------------------------------+ +| Tables | ++---------------------------------------------------------------+ +| prometheus_remote_storage_enqueue_retries_total | +| prometheus_remote_storage_exemplars_pending | +| prometheus_remote_storage_read_request_duration_seconds_count | +| prometheus_rule_group_duration_seconds | +| ...... | ++---------------------------------------------------------------+ +``` + +物理表本身也可以进行查询。 +它包含了所有逻辑表的列，方便进行多表连接分析和计算。 + +要查看物理表的 schema，请使用 `DESC TABLE` 命令： + +```sql +DESC TABLE greptime_physical_table; +``` + +物理表包含了所有逻辑表的列： + +```sql ++--------------------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+----------------------+------+------+---------+---------------+ +| greptime_timestamp | TimestampMillisecond | PRI | NO | | TIMESTAMP | +| greptime_value | Float64 | | YES | | FIELD | +| __table_id | UInt32 | PRI | NO | | TAG | +| __tsid | UInt64 | PRI | NO | | TAG | +| device | String | PRI | YES | | TAG | +| instance | String | PRI | YES | | TAG | +| job | String | PRI | YES | | TAG | +| error | String | PRI | YES | | TAG | +... +``` + +你可以使用 `SELECT` 语句根据需要从物理表中过滤数据。 +例如，根据逻辑表 A 的 `device` 条件和逻辑表 B 的 `job` 条件来过滤数据： + +```sql +SELECT * +FROM greptime_physical_table +WHERE greptime_timestamp > "2024-08-07 03:27:26.964000" + AND device = "device1" + AND job = "job1"; +``` + +## VictoriaMetrics Remote Write + +VictoriaMetrics 对 Prometheus 远程写入协议进行了轻微修改，以实现更好的压缩效果。 +当你使用 `vmagent` 将数据发送到兼容的后端时，该协议会被自动启用。 + +GreptimeDB 也支持这个变种。只需将 GreptimeDB 的 Remote Write URL 配置为 `vmagent`。 +例如，如果你在本地安装了 GreptimeDB： + +```shell +vmagent -remoteWrite.url=http://localhost:4000/v1/prometheus/write +``` + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/vector.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/vector.md new file mode 100644 index 000000000..61028559b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/for-observerbility/vector.md @@ -0,0 +1,60 @@ +--- +description: 介绍如何使用 Vector 将数据写入 GreptimeDB，包括最小配置示例和数据模型的映射规则。 +--- + +import DocTemplate from '../../../db-cloud-shared/clients/vector-integration.md' + + +# Vector + + + +[Vector](https://vector.dev/) 是一种高性能的可以帮助工程师控制可观测性数据的通道工具。我们的 Vector 集成页面在[这里](https://vector.dev/docs/reference/configuration/sinks/greptimedb/)。 + +
+ +## 集成 + +使用 GreptimeDB 的 Vector 集成的最小配置如下： + +```toml +# sample.toml + +[sources.in] +type = "host_metrics" + +[sinks.my_sink_id] +inputs = ["in"] +type = "greptimedb" +endpoint = ":4001" +dbname = "" +username = "" +password = "" +new_naming = true +``` + +GreptimeDB 使用 gRPC 与 Vector 进行通信，因此 Vector sink 的默认端口是 `4001`。 +如果你在使用 [自定义配置](/user-guide/deployments/configuration.md#configuration-file) 启动 GreptimeDB 时更改了默认的 gRPC 端口，请使用你自己的端口。 + +
+ +
+ +## 数据模型 + +我们使用这样的规则将 Vector 指标存入 GreptimeDB： + +- 使用 `_` 作为 GreptimeDB 的表名，例如 `host_cpu_seconds_total`； +- 将指标中的时间戳作为 GreptimeDB 的时间索引，默认列名 `ts`； +- 指标所关联的 tag 列将被作为 GreptimeDB 的 tag 字段； +- Vector 的指标，和其他指标类似，有多种子类型： + - Counter 和 Gauge 类型的指标，数值直接被存入 `val` 列； + - Set 类型，我们将集合的数据个数存入 `val` 列； + - Distribution 类型，各个百分位数值点分别存入 `pxx` 列，其中 xx 是 quantile 数值，此外我们还会记录 `min/max/avg/sum/count` 列； + - AggregatedHistoragm 类型，每个 bucket 的数值将被存入 `bxx` 列，其中 xx 是 bucket 数值的上限，此外我们还会记录 `sum/count` 列； + - AggregatedSummary 类型，各个百分位数值点分别存入 `pxx` 列，其中 xx 是 quantile 数值，此外我们还会记录 `sum/count` 列； + - Sketch 类型，各个百分位数值点分别存入 `pxx` 列，其中 xx 是 quantile 数值，此外我们还会记录 `min/max/avg/sum` 列； + +
+ + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/overview.md new file mode 100644 index 000000000..c9c248e2d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/ingest-data/overview.md @@ -0,0 +1,25 @@ +--- +description: 介绍 GreptimeDB 的自动生成表结构功能和推荐的数据写入方法，并提供下一步学习的链接。 +--- + +# 概述 + +## 自动生成表结构 + +GreptimeDB 支持无 schema 写入，即在数据写入时自动创建表格并添加必要的列。 +这种能力确保你无需事先手动定义 schema，从而更容易管理和集成各种数据源。 + +此功能适用于所有协议和集成，除了 [SQL](./for-iot/sql.md)。 + +## 推荐的数据写入方法 + +GreptimeDB 支持针对特定场景的各种数据写入方法，以确保最佳性能和集成灵活性。 + +- [可观测场景](./for-observerbility/overview.md)：适用于实时监控和警报。 +- [物联网场景](./for-iot/overview.md)：适用于实时数据和复杂的物联网基础设施。 + +## 下一步 + +- [查询数据](/user-guide/query-data/overview.md): 学习如何通过查询 GreptimeDB 数据库来探索数据。 +- [管理数据](/user-guide/manage-data/overview.md): 学习如何更新和删除数据等，确保数据完整性和高效的数据管理。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/dbeaver.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/dbeaver.md new file mode 100644 index 000000000..94f9e817f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/dbeaver.md @@ -0,0 +1,26 @@ +--- +description: 介绍如何使用 DBeaver 通过 MySQL Driver 连接到 GreptimeDB，包括配置连接的详细步骤。 +--- + +# DBeaver + +[DBeaver](https://dbeaver.io/) 是一个免费、开源且跨平台的数据库工具，支持所有流行的数据库。 +由于其易用性和丰富的功能集，它在开发人员和数据库管理员中非常受欢迎。 +你可以使用 DBeaver 通过 MySQL Driver 连接到 GreptimeDB。 + +点击 DBeaver 工具栏中的 “New Database Connection” 按钮，以创建 GreptimeDB 的新连接。 + +选择 MySQL 并点击“下一步”以配置连接。 +如果你还没有安装 MySQL Driver，请先安装。 +接下来输入以下连接信息： + +- Connect by Host +- Host：如果 GreptimeDB 运行在本机，则为 `localhost` +- Port：如果使用默认的 GreptimeDB 配置，则为 `4002` +- Database：`public`，你也可以使用你创建的其他数据库名称 +- 如果你的 GreptimeDB 启用了身份验证，请输入 username 和 password，否则留空 + +点击 “Test Connection” 以验证连接设置，然后点击 “Finish” 以保存连接。 + +有关 MySQL 与 GreptimeDB 交互的更多信息，请参阅 [MySQL 协议文档](/user-guide/protocols/mysql.md)。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/emqx.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/emqx.md new file mode 100644 index 000000000..c25768dbc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/emqx.md @@ -0,0 +1,4 @@ +# EMQX + +GreptimeDB 可以作为 EMQX 的数据系统。 +更多信息请参考 [通过 EMQX 写入数据](/user-guide/ingest-data/for-iot/emqx.md) 指南。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/grafana.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/grafana.md new file mode 100644 index 000000000..33d813e93 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/grafana.md @@ -0,0 +1,134 @@ +--- +description: 介绍如何将 GreptimeDB 配置为 Grafana 数据源，包括使用 GreptimeDB 数据源插件、Prometheus 数据源和 MySQL 数据源的方法。 +--- + +# Grafana + +GreptimeDB 服务可以配置为 [Grafana 数据源](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/)。 +你可以选择使用以下三个数据源之一连接 GreptimeDB 与 Grafana：GreptimeDB、Prometheus 或 MySQL。 + +## GreptimeDB 数据源插件 + +GreptimeDB 数据源插件基于 Prometheus 数据源开发并附加了特定于 GreptimeDB 的功能。 +该插件完美适配了 GreptimeDB 的数据模型， +从而提供了更好的用户体验。 +此外，和直接使用 Prometheus 数据源相比，它还解决了一些兼容性问题。 + +### 安装 + +GreptimeDB 数据源插件目前仅支持在本地 Grafana 中的安装， +在安装插件前请确保 Grafana 已经安装并运行。 + +你可以任选以下一种安装方式： + +- 下载安装包并解压到相关目录：从[发布页面](https://github.com/GreptimeTeam/greptimedb-grafana-datasource/releases/latest/)获取最新版本，解压文件到你的 [grafana 插件目录](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#plugins)。 +- 使用 Grafana Cli 下载并安装： + ```shell + grafana cli --pluginUrl https://github.com/GreptimeTeam/greptimedb-grafana-datasource/releases/latest/download/info8fcc-greptimedb-datasource.zip plugins install info8fcc + ``` + +注意，安装插件后可能需要重新启动 Grafana 服务器。 + +### 使用 Docker 快速预览 + +Greptime 提供了一个 docker compose 文件， +将 GreptimeDB、Prometheus、Prometheus Node Exporter、Grafana 和该插件集成在一起， +以便你能够快速体验 GreptimeDB 数据源插件。 + +```shell +git clone https://github.com/GreptimeTeam/greptimedb-grafana-datasource.git +cd docker +docker compose up +``` + +你也可以从 Grafana 的 docker 镜像中试用此插件： + +```shell +docker run -d -p 3000:3000 --name=grafana --rm \ + -e "GF_INSTALL_PLUGINS=https://github.com/GreptimeTeam/greptimedb-grafana-datasource/releases/latest/download/info8fcc-greptimedb-datasource.zip;info8fcc" \ + grafana/grafana-oss +``` + +### Connection 配置 + +在 Grafana 中单击 Add data source 按钮，选择 GreptimeDB 作为类型。 + +![grafana-add-greptimedb-data-source](/grafana-add-greptimedb-data-source.png) + + +在 GreptimeDB server URL 中填写以下地址： + +```txt +http://:4000 +``` + +接下来做如下配置： + +- Database Name：填写数据库名称 ``，留空则使用默认数据库 `public` +- 在 Auth 部分中单击 basic auth，并在 Basic Auth Details 中填写 GreptimeDB 的用户名和密码。未设置可留空： + + - User: `` + - Password: `` + +然后单击 Save & Test 按钮以测试连接。 + +### 创建仪表盘 + +在 Grafana 中创建一个新的仪表盘，点击 `Create your first dashboard` 按钮。 +然后，点击 `Add visualization`，选择 `GreptimeDB` 作为数据源。 + +在 `Metric` 下拉列表中选择一个指标，然后点击 `Run query` 查看指标数据。 +当你查看数据并确认无误后，点击 `Save` 保存面板。 + +![grafana-create-panel-with-selecting-metric](/create-panel-with-selecting-metric-greptimedb.png) + +你还可以使用 PromQL 创建面板。 +点击 `Query` 标签页右侧的 `code` 按钮，切换到 PromQL 编辑器。 +然后输入一个 PromQL 语句，例如 `system_memory_usage{state="used"}`，点击 `Run queries` 查看指标数据。 + +![grafana-create-panel-with-promql](/grafana-create-panel-with-promql.png) + +:::tip 注意 +GreptimeDB 兼容大部分 PromQL，但是有一些限制。请参考 [PromQL 限制](/user-guide/query-data/promql.md#局限) 文档获取更多信息。 +::: + +## Prometheus 数据源 + +单击 Add data source 按钮，然后选择 Prometheus 作为类型。 + +在 HTTP 中填写 Prometheus server URL + +```txt +http://:4000/v1/prometheus +``` + +在 Auth 部分中单击 basic auth，并在 Basic Auth Details 中填写 GreptimeDB 的用户名和密码： + +- User: `` +- Password: `` + +在 Custom HTTP Headers 部分中点击 Add header: + +- Header: `x-greptime-db-name` +- Value: `` + +然后单击 Save & Test 按钮以测试连接。 + +有关如何使用 PromQL 查询数据，请参阅 [Prometheus 查询语言](/user-guide/query-data/promql.md)文档。 + +## MySQL 数据源 + +单击 Add data source 按钮，然后选择 MySQL 作为类型。在 MySQL Connection 中填写以下信息： + +- Host: `:4002` +- Database: `` +- User: `` +- Password: `` +- Session timezone: `UTC` + +然后单击 Save & Test 按钮以测试连接。 + +注意目前我们只能使用 raw SQL 创建 Grafana Panel。由于时间戳数据类型的区别，Grafana +的 SQL Builder 暂时无法选择时间戳字段。 + +关于如何用 SQL 查询数据，请参考[使用 SQL 查询数据](/user-guide/query-data/sql.md)文档。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/metabase.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/metabase.md new file mode 100644 index 000000000..4d4eff39b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/metabase.md @@ -0,0 +1,29 @@ +--- +description: 介绍如何将 GreptimeDB 添加到 Metabase 作为数据源，包括安装 Driver 和添加 GreptimeDB 数据库的方法。 +--- + +# Metabase + +[Metabase](https://github.com/metabase/metabase) 是一个用 Clojure 编写的开源 BI +工具，可以通过社区维护的数据库驱动将 GreptimeDB 添加到 Metabase。 + +## 安装 + +从 [发布 +页](https://github.com/greptimeteam/greptimedb-metabase-driver/releases/latest/) +下载最新的驱动插件文件 `greptimedb.metabase-driver.jar`，并将文件拷贝到 Metabase +的工作目录下 `plugins/` 目录中（如果不存在需要创建 `plugins/`）。当 Metabase 启 +动时，会自动检测到插件。 + +## 添加 GreptimeDB 数据库 + +选择 *设置* / *管理员设置* / *数据库*, 点击 *添加数据库* 按钮并选择 GreptimeDB +作为 *数据库类型*. + +进一步添加其他数据库信息： + +- 端口请填写 GreptimeDB 的 Postgres 协议端口 `4003`。 +- 如果没有开启[认证](/user-guide/deployments/authentication/overview.md)，用户名和密码字段 + 是可选的。 +- 默认填写 `public` 作为 *数据库名*。如果是使用 GreptimeCloud 的实例，可以从控制 + 台复制数据库名称。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/overview.md new file mode 100644 index 000000000..0f8c22182 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/overview.md @@ -0,0 +1,11 @@ +# 概述 + +GreptimeDB 可以与流行的数据写入、查询和可视化工具无缝集成。 +本章节提供了将 GreptimeDB 与以下工具集成的指导： + +- [Prometheus](./prometheus.md) +- [Vector](./vector.md) +- [Grafana](./grafana.md) +- [Superset](./superset.md) +- [Metabase](./metabase.md) +- [EMQX](./emqx.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/prometheus.md new file mode 100644 index 000000000..591b6741d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/prometheus.md @@ -0,0 +1,15 @@ +--- +description: 介绍如何将 GreptimeDB 作为 Prometheus 的远程存储后端，并支持使用 Prometheus 查询语言 (PromQL) 查询数据。 +--- + +# Prometheus + +## Remote Write + +GreptimeDB 可以用作 Prometheus 的远程存储后端。 +详细信息请参考[使用 Prometheus Remote Write 写入数据](/user-guide/ingest-data/for-observerbility/prometheus.md)。 + +## Prometheus Query Language (PromQL) + +GreptimeDB 支持使用 Prometheus 查询语言 (PromQL) 来查询数据。 +更多信息请参考[使用 PromeQL 查询数据](/user-guide/query-data/promql.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/superset.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/superset.md new file mode 100644 index 000000000..5ad42689e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/superset.md @@ -0,0 +1,55 @@ +--- +description: 介绍如何将 GreptimeDB 作为 Apache Superset 的数据源，包括使用 Docker Compose 和本地运行 Superset 的安装步骤，以及添加 GreptimeDB 数据库的方法。 +--- + +# Superset + +[Apache Superset](https://superset.apache.org) 是开源的 BI 工具，用 Python 编写。 +以下内容可以帮助你把 GreptimeDB 作为 Superset 的数据源。 + +## 安装 + +### 用 Docker Compose 运行 Superset + +[Docker compose](https://superset.apache.org/docs/installation/docker-compose) +是 Superset 的推荐使用方式。在这种运行方式下，需要在 Superset 代码目录下的 +`docker/` 中添加一个 `requirements-local.txt`。 + +并将 GreptimeDB 依赖加入到 `requirements-local.txt`: + +```txt +greptimedb-sqlalchemy +``` + +启动 Supertset 服务： + +```bash +docker compose -f docker-compose-non-dev.yml up +``` + +### 本地运行 Superset + +假如你通过 [Pypi 包安装和运行 +Superset](https://superset.apache.org/docs/installation/pypi)，需要将 GreptimeDB +的依赖安装到相同的 Python 环境。 + +```bash +pip install greptimedb-sqlalchemy +``` + +## 添加 GreptimeDB 数据库 + +准备添加，选择 *设置* / *数据库连接*. + +添加数据库，并在支持的数据库列表中选择 *GreptimeDB*。 + +根据 SQLAlchemy URI 的规范，填写以下格式的数据库连接地址。 + +``` +greptimedb://:@:/ +``` + +- 如果没有启动[认证](/user-guide/deployments/authentication/overview.md)，可以忽略 + `:@` 部分。 +- 默认端口 `4003` （我们用 PostgresSQL 协议通信）。 +- 默认数据库 `public`。如果是使用 GreptimeCloud 实例，可以从控制台复制数据库名称。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/vector.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/vector.md new file mode 100644 index 000000000..a2d70436c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/integrations/vector.md @@ -0,0 +1,3 @@ +# Vector + +请前往[使用 Vector 写入数据](/user-guide/ingest-data/for-observerbility/vector.md)查看如何使用 Vector 将数据传输到 GreptimeDB。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/manage-pipelines.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/manage-pipelines.md new file mode 100644 index 000000000..9e06b9eee --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/manage-pipelines.md @@ -0,0 +1,296 @@ +--- +description: 介绍如何在 GreptimeDB 中管理 Pipeline，包括创建、删除和查询 Pipeline 的方法，以及内置 Pipeline 的使用。 +--- + +# 管理 Pipeline + +在 GreptimeDB 中，每个 `pipeline` 是一个数据处理单元集合，用于解析和转换写入的日志内容。本文档旨在指导您如何创建和删除 Pipeline，以便高效地管理日志数据的处理流程。 + + +有关 Pipeline 的具体配置，请阅读 [Pipeline 配置](pipeline-config.md)。 + +## 内置 Pipeline + +GreptimeDB 提供了常见日志格式的内置 Pipeline，允许您直接使用而无需创建新的 Pipeline。 + +请注意，内置 Pipeline 的名称以 "greptime_" 为前缀，不可编辑。 + +### `greptime_identity` + +`greptime_identity` Pipeline 适用于写入 JSON 日志，并自动为 JSON 日志中的每个字段创建列。 + +- JSON 日志中的第一层级的 key 是表中的列名。 +- 如果相同字段包含不同类型的数据，则会返回错误。 +- 值为 `null` 的字段将被忽略。 +- 作为时间索引的额外列 `greptime_timestamp` 将被添加到表中，以指示日志写入的时间。 + +#### 类型转换规则 + +- `string` -> `string` +- `number` -> `int64` 或 `float64` +- `boolean` -> `bool` +- `null` -> 忽略 +- `array` -> `json` +- `object` -> `json` + +例如，如果我们有以下 JSON 数据： + +```json +[ + {"name": "Alice", "age": 20, "is_student": true, "score": 90.5,"object": {"a":1,"b":2}}, + {"age": 21, "is_student": false, "score": 85.5, "company": "A" ,"whatever": null}, + {"name": "Charlie", "age": 22, "is_student": true, "score": 95.5,"array":[1,2,3]} +] +``` + +我们将合并每个批次的行结构以获得最终 schema。表 schema 如下所示： + +```sql +mysql> desc pipeline_logs; ++--------------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+---------------------+------+------+---------+---------------+ +| age | Int64 | | YES | | FIELD | +| is_student | Boolean | | YES | | FIELD | +| name | String | | YES | | FIELD | +| object | Json | | YES | | FIELD | +| score | Float64 | | YES | | FIELD | +| company | String | | YES | | FIELD | +| array | Json | | YES | | FIELD | +| greptime_timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | ++--------------------+---------------------+------+------+---------+---------------+ +8 rows in set (0.00 sec) +``` + +数据将存储在表中，如下所示： + +```sql +mysql> select * from pipeline_logs; ++------+------------+---------+---------------+-------+---------+---------+----------------------------+ +| age | is_student | name | object | score | company | array | greptime_timestamp | ++------+------------+---------+---------------+-------+---------+---------+----------------------------+ +| 22 | 1 | Charlie | NULL | 95.5 | NULL | [1,2,3] | 2024-10-18 09:35:48.333020 | +| 21 | 0 | NULL | NULL | 85.5 | A | NULL | 2024-10-18 09:35:48.333020 | +| 20 | 1 | Alice | {"a":1,"b":2} | 90.5 | NULL | NULL | 2024-10-18 09:35:48.333020 | ++------+------------+---------+---------------+-------+---------+---------+----------------------------+ +3 rows in set (0.01 sec) +``` + +## 创建 Pipeline + +GreptimeDB 提供了专用的 HTTP 接口用于创建 Pipeline。 +假设你已经准备好了一个 Pipeline 配置文件 pipeline.yaml，使用以下命令上传配置文件，其中 `test` 是你指定的 Pipeline 的名称： + +```shell +## 上传 pipeline 文件。test 为 Pipeline 的名称 +curl -X "POST" "http://localhost:4000/v1/events/pipelines/test?db=public" -F "file=@pipeline.yaml" +``` + +创建的 Pipeline 会关联到一个 database，可通过 URL 参数 `db` 来指定，默认为 `public`。 +在将日志写入到数据库中时，所使用的 Pipeline 必须和写入的表在同一个 database 下。 + +## 删除 Pipeline + +可以使用以下 HTTP 接口删除 Pipeline： + +```shell +## test 为 Pipeline 的名称 +curl -X "DELETE" "http://localhost:4000/v1/events/pipelines/test?db=public&version=2024-06-27%2012%3A02%3A34.257312110Z" +``` + +上面的例子中，我们删除了一个在 `public` database 下名为 `test` 的 Pipeline。`version` 参数是必须的，用于指定要删除的 Pipeline 的版本号。 + +## 查询 Pipeline + +目前可以使用 SQL 来查询 Pipeline 的信息。 + +```sql +SELECT * FROM greptime_private.pipelines; +``` + +请注意，如果您使用 MySQL 或者 PostgreSQL 协议作为连接 GreptimeDB 的方式，查询出来的 Pipeline 时间信息精度可能有所不同，可能会丢失纳秒级别的精度。 + +为了解决这个问题，可以将 `created_at` 字段强制转换为 timestamp 来查看 Pipeline 的创建时间。例如，下面的查询将 `created_at` 以 `bigint` 的格式展示: + +```sql +SELECT name, pipeline, created_at::bigint FROM greptime_private.pipelines; +``` + +查询结果如下： + +``` + name | pipeline | greptime_private.pipelines.created_at +------+-----------------------------------+--------------------------------------- + test | processors: +| 1719489754257312110 + | - date: +| + | field: time +| + | formats: +| + | - "%Y-%m-%d %H:%M:%S%.3f"+| + | ignore_missing: true +| + | +| + | transform: +| + | - fields: +| + | - id1 +| + | - id2 +| + | type: int32 +| + | - fields: +| + | - type +| + | - logger +| + | type: string +| + | index: tag +| + | - fields: +| + | - log +| + | type: string +| + | index: fulltext +| + | - field: time +| + | type: time +| + | index: timestamp +| + | | +(1 row) +``` + +然后可以使用程序将 SQL 结果中的 bigint 类型的时间戳转换为时间字符串。 + +```shell +timestamp_ns="1719489754257312110"; readable_timestamp=$(TZ=UTC date -d @$((${timestamp_ns:0:10}+0)) +"%Y-%m-%d %H:%M:%S").${timestamp_ns:10}Z; echo "Readable timestamp (UTC): $readable_timestamp" +``` + +输出： + +```shell +Readable timestamp (UTC): 2024-06-27 12:02:34.257312110Z +``` + +输出的 `Readable timestamp (UTC)` 即为 Pipeline 的创建时间同时也是版本号。 + +## 问题调试 + +首先，请参考 [快速入门示例](/user-guide/logs/quick-start.md#使用-pipeline-写入日志)来查看 Pipeline 正确的执行情况。 + +### 调试创建 Pipeline + +在创建 Pipeline 的时候你可能会遇到错误，例如使用如下配置创建 Pipeline： + +```bash +curl -X "POST" "http://localhost:4000/v1/events/pipelines/test" \ + -H 'Content-Type: application/x-yaml' \ + -d $'processors: + - date: + field: time + formats: + - "%Y-%m-%d %H:%M:%S%.3f" + ignore_missing: true + - gsub: + fields: + - message + pattern: "\\\." + replacement: + - "-" + ignore_missing: true + +transform: + - fields: + - message + type: string + - field: time + type: time + index: timestamp' +``` + +Pipeline 配置存在错误。`gsub` processor 期望 `replacement` 字段为字符串，但当前配置提供了一个数组。因此，该 Pipeline 创建失败，并显示以下错误消息： + + +```json +{"error":"Failed to parse pipeline: 'replacement' must be a string"} +``` + +因此，你需要修改 `gsub` processor 的配置，将 `replacement` 字段的值更改为字符串类型。 + +```bash +curl -X "POST" "http://localhost:4000/v1/events/pipelines/test" \ + -H 'Content-Type: application/x-yaml' \ + -d $'processors: + - date: + field: time + formats: + - "%Y-%m-%d %H:%M:%S%.3f" + ignore_missing: true + - gsub: + fields: + - message + pattern: "\\\." + replacement: "-" + ignore_missing: true + +transform: + - fields: + - message + type: string + - field: time + type: time + index: timestamp' +``` + +此时 Pipeline 创建成功，可以使用 `dryrun` 接口测试该 Pipeline。 + +### 调试日志写入 + +我们可以使用 `dryrun` 接口测试 Pipeline。我们将使用错误的日志数据对其进行测试，其中消息字段的值为数字格式，会导致 Pipeline 在处理过程中失败。 + +**此接口仅仅用于测试 Pipeline 的处理结果，不会将日志写入到 GreptimeDB 中。** + +```bash +curl -X "POST" "http://localhost:4000/v1/events/pipelines/dryrun?pipeline_name=test" \ + -H 'Content-Type: application/json' \ + -d $'{"message": 1998.08,"time":"2024-05-25 20:16:37.217"}' + +{"error":"Failed to execute pipeline, reason: gsub processor: expect string or array string, but got Float64(1998.08)"} +``` + +输出显示 Pipeline 处理失败，因为 `gsub` Processor 期望的是字符串类型，而不是浮点数类型。我们需要修改日志数据的格式，确保 Pipeline 能够正确处理。 +我们再将 message 字段的值修改为字符串类型，然后再次测试该 Pipeline。 + +```bash +curl -X "POST" "http://localhost:4000/v1/events/pipelines/dryrun?pipeline_name=test" \ + -H 'Content-Type: application/json' \ + -d $'{"message": "1998.08","time":"2024-05-25 20:16:37.217"}' +``` + +此时 Pipeline 处理成功，输出如下： + +```json +{ + "rows": [ + [ + { + "data_type": "STRING", + "key": "message", + "semantic_type": "FIELD", + "value": "1998-08" + }, + { + "data_type": "TIMESTAMP_NANOSECOND", + "key": "time", + "semantic_type": "TIMESTAMP", + "value": "2024-05-25 20:16:37.217+0000" + } + ] + ], + "schema": [ + { + "colume_type": "FIELD", + "data_type": "STRING", + "fulltext": false, + "name": "message" + }, + { + "colume_type": "TIMESTAMP", + "data_type": "TIMESTAMP_NANOSECOND", + "fulltext": false, + "name": "time" + } + ] +} +``` + +可以看到，`1998.08` 字符串中的 `.` 已经被替换为 `-`，Pipeline 处理成功。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/overview.md new file mode 100644 index 000000000..2496ee4a4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/overview.md @@ -0,0 +1,7 @@ +# 概述 + +- [快速开始](./quick-start.md)：介绍了如何快速开始使用 GreptimeDB 日志服务。 +- [Pipeline 配置](./pipeline-config.md)：深入介绍 GreptimeDB 中的 Pipeline 的每项具体配置。 +- [管理 Pipeline](./manage-pipelines.md)：介绍了如何创建、删除 Pipeline。 +- [配合 Pipeline 写入日志](./write-logs.md): 详细说明了如何结合 Pipeline 机制高效写入日志数据。 +- [查询日志](./query-logs.md)：描述了如何使用 GreptimeDB SQL 接口查询日志。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/pipeline-config.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/pipeline-config.md new file mode 100644 index 000000000..f2d03366b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/pipeline-config.md @@ -0,0 +1,598 @@ +--- +description: 介绍 GreptimeDB 中 Pipeline 的配置，包括 Processor 和 Transform 的使用方法，以及各种 Processor 的详细配置示例。 +--- + +# Pipeline 配置 + +Pipeline 是 GreptimeDB 中对 log 数据进行解析和转换的一种机制， 由一个唯一的名称和一组配置规则组成，这些规则定义了如何对日志数据进行格式化、拆分和转换。目前我们支持 JSON（`application/json`）和纯文本（`text/plain`）格式的日志数据作为输入。 + +这些配置以 YAML 格式提供，使得 Pipeline 能够在日志写入过程中，根据设定的规则对数据进行处理，并将处理后的数据存储到数据库中，便于后续的结构化查询。 + +## 整体结构 + +Pipeline 由两部分组成：Processors 和 Transform，这两部分均为数组形式。一个 Pipeline 配置可以包含多个 Processor 和多个 Transform。Transform 所描述的数据类型会决定日志数据保存到数据库时的表结构。 + +- Processor 用于对 log 数据进行预处理，例如解析时间字段，替换字段等。 +- Transform 用于对数据进行格式转换，例如将字符串类型转换为数字类型。 + +一个包含 Processor 和 Transform 的简单配置示例如下： + +```yaml +processors: + - urlencoding: + fields: + - string_field_a + - string_field_b + method: decode + ignore_missing: true +transform: + - fields: + - string_field_a + - string_field_b + type: string + # 写入的数据必须包含 timestamp 字段 + - fields: + - reqTimeSec, req_time_sec + # epoch 是特殊字段类型，必须指定精度 + type: epoch, ms + index: timestamp +``` + +## Processor + +Processor 用于对 log 数据进行预处理，其配置位于 YAML 文件中的 `processors` 字段下。 +Pipeline 会按照多个 Processor 的顺序依次加工数据，每个 Processor 都依赖于上一个 Processor 处理的结果。 +Processor 由一个 name 和多个配置组成，不同类型的 Processor 配置有不同的字段。 + +我们目前内置了以下几种 Processor： + +- `date`: 解析格式化的时间字符串字段，例如 `2024-07-12T16:18:53.048`。 +- `epoch`: 解析数字时间戳字段，例如 `1720772378893`。 +- `decolorize`: 移除日志数据中的 ANSI 颜色代码。 +- `dissect`: 对 log 数据字段进行拆分。 +- `gsub`: 对 log 数据字段进行替换。 +- `join`: 对 log 中的 array 类型字段进行合并。 +- `letter`: 对 log 数据字段进行字母转换。 +- `regex`: 对 log 数据字段进行正则匹配。 +- `urlencoding`: 对 log 数据字段进行 URL 编解码。 +- `csv`: 对 log 数据字段进行 CSV 解析。 + +大多数 Processor 都有 `field` 或 `fields` 字段，用于指定需要被处理的字段。大部分 Processor 处理完成后会覆盖掉原先的 field。如果你不想影响到原数据中的对应字段，我们可以把结果输出到其他字段来避免覆盖。 + +当字段名称包含 `,` 时，该字段将被重命名。例如，`reqTimeSec, req_time_sec` 表示将 `reqTimeSec` 字段重命名为 `req_time_sec`，处理完成后的数据将写入中间状态的 `req_time_sec` 字段中。原始的 `reqTimeSec` 字段不受影响。如果某些 Processor 不支持字段重命名，则重命名字段名称将被忽略，并将在文档中注明。 + +例如： + +```yaml +processors: + - letter: + fields: + - message, message_upper + method: upper + ignore_missing: true +``` + +`message` 字段将被转换为大写并存储在 `message_upper` 字段中。 + +### `date` + +`date` Processor 用于解析时间字段。示例配置如下： + +```yaml +processors: + - date: + fields: + - time + formats: + - '%Y-%m-%d %H:%M:%S%.3f' + ignore_missing: true + timezone: 'Asia/Shanghai' +``` + +如上所示，`date` Processor 的配置包含以下字段： + +- `fields`: 需要解析的时间字段名列表。 +- `formats`: 时间格式化字符串，支持多个时间格式化字符串。按照提供的顺序尝试解析，直到解析成功。你可以在[这里](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)找到格式化的语法说明。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 +- `timezone`： 时区。使用[tz_database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 中的时区标识符来指定时区。默认为 `UTC`。 + +### `epoch` + +`epoch` Processor 用于解析时间戳字段，示例配置如下： + +```yaml +processors: + - epoch: + fields: + - reqTimeSec + resolution: millisecond + ignore_missing: true +``` + +如上所示，`epoch` Processor 的配置包含以下字段： + +- `fields`: 需要解析的时间戳字段名列表。 +- `resolution`: 时间戳精度，支持 `s`, `sec` , `second` , `ms`, `millisecond`, `milli`, `us`, `microsecond`, `micro`, `ns`, `nanosecond`, `nano`。默认为 `ms`。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 + +### `decolorize` + +`decolorize` Processor 用于移除日志数据中的 ANSI 颜色代码。示例配置如下： + +```yaml +processors: + - decolorize: + fields: + - message +``` + +如上所示，`decolorize` Processor 的配置包含以下字段： + +- `fields`: 需要移除颜色代码的字段名列表。 + +### `dissect` + +`dissect` Processor 用于对 log 数据字段进行拆分，示例配置如下： + +```yaml +processors: + - dissect: + fields: + - message + patterns: + - '%{key1} %{key2}' + ignore_missing: true + append_separator: '-' +``` + +如上所示，`dissect` Processor 的配置包含以下字段： + +- `fields`: 需要拆分的字段名列表。不支持字段重命名。 +- `patterns`: 拆分的 dissect 模式。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 +- `append_separator`: 对于多个追加到一起的字段，指定连接符。默认是一个空字符串。 + +#### Dissect 模式 + +和 Logstash 的 Dissect 模式类似，Dissect 模式由 `%{key}` 组成，其中 `%{key}` 为一个字段名。例如： + +``` +"%{key1} %{key2} %{+key3} %{+key4/2} %{key5->} %{?key6}" +``` + +#### Dissect 修饰符 + +Dissect 模式支持以下修饰符： + +| 修饰符 | 说明 | 示例 | +| ----------- | ---------------------------------------- | --------------------- | +| `+` | 将两个或多个字段追加到一起 | `%{+key} %{+key}` | +| `+` 和 `/n` | 按照指定的顺序将两个或多个字段追加到一起 | `%{+key/2} %{+key/1}` | +| `->` | 忽略右侧的任何重复字符 | `%{key1->} %{key2->}` | +| `?` | 忽略匹配的值 | `%{?key}` | + +#### `dissect` 示例 + +例如，对于以下 log 数据： + +``` +"key1 key2 key3 key4 key5 key6" +``` + +使用以下 Dissect 模式： + +``` +"%{key1} %{key2} %{+key3} %{+key3/2} %{key5->} %{?key6}" +``` + +将得到以下结果： + +``` +{ + "key1": "key1", + "key2": "key2", + "key3": "key3 key4", + "key5": "key5" +} +``` + +### `gsub` + +`gsub` Processor 用于对 log 数据字段进行替换，示例配置如下： + +```yaml +processors: + - gsub: + fields: + - message + pattern: 'old' + replacement: 'new' + ignore_missing: true +``` + +如上所示，`gsub` Processor 的配置包含以下字段： + +- `fields`: 需要替换的字段名列表。 +- `pattern`: 需要替换的字符串。支持正则表达式。 +- `replacement`: 替换后的字符串。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 + +### `join` + +`join` Processor 用于对 log 中的 Array 类型字段进行合并，示例配置如下： + +```yaml +processors: + - join: + fields: + - message + separator: ',' + ignore_missing: true +``` + +如上所示，`join` Processor 的配置包含以下字段： + +- `fields`: 需要合并的字段名列表。注意，这里每行字段的值需要是 Array 类型，每行字段会单独合并自己数组内的值，所有行的字段不会合并到一起。 +- `separator`: 合并后的分隔符。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 + +#### `join` 示例 + +例如，对于以下 log 数据： + +```json +{ + "message": ["a", "b", "c"] +} +``` + +使用以下配置： + +```yaml +processors: + - join: + fields: + - message + separator: ',' +``` + +将得到以下结果： + +```json +{ + "message": "a,b,c" +} +``` + +### `letter` + +`letter` Processor 用于对 log 数据字段进行字母转换，示例配置如下： + +```yaml +processors: + - letter: + fields: + - message + method: upper + ignore_missing: true +``` + +如上所示，`letter` Processor 的配置包含以下字段： + +- `fields`: 需要转换的字段名列表。 +- `method`: 转换方法，支持 `upper`, `lower` ，`capital`。默认为 `lower`。注意 `capital` 只会将第一个字母转换为大写。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 + +### `regex` + +`regex` Processor 用于对 log 数据字段进行正则匹配，示例配置如下： + +```yaml +processors: + - regex: + fields: + - message + patterns: + - ':(?[0-9])' + ignore_missing: true +``` + +如上所示，`regex` Processor 的配置包含以下字段： + +- `fields`: 需要匹配的字段名列表。如果重命名了字段，重命名后的字段名将与 `pattern` 中的命名捕获组名进行拼接。 +- `pattern`: 要进行匹配的正则表达式，需要使用命名捕获组才可以从对应字段中取出对应数据。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 + +#### regex 命名捕获组的规则 + +`regex` Processor 支持使用 `(?...)` 的语法来命名捕获组，最终将数据处理为这种形式： + +```json +{ + "_": "" +} +``` + +例如 `regex` Processor 中 field 填写的字段名为 `message`，对应的内容为 `"[ERROR] error message"`， +你可以将 pattern 设置为 `\[(?[A-Z]+)\] (?.+)`， +最终数据会被处理为： +```json +{ + "message_level": "ERROR", + "message_content": "error message" +} +``` + +### `urlencoding` + +`urlencoding` Processor 用于对 log 数据字段进行 URL 编码，示例配置如下： + +```yaml +processors: + - urlencoding: + fields: + - string_field_a + - string_field_b + method: decode + ignore_missing: true +``` + +如上所示，`urlencoding` Processor 的配置包含以下字段： + +- `fields`: 需要编码的字段名列表。 +- `method`: 编码方法，支持 `encode`, `decode`。默认为 `encode`。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 + +### `csv` + +`csv` Processor 用于对 log 数据中没有携带 header 的 CSV 类型字段解析，示例配置如下： + +```yaml +processors: + - csv: + fields: + - message + separator: ',' + quote: '"' + trim: true + ignore_missing: true +``` + +如上所示，`csv` Processor 的配置包含以下字段： + +- `fields`: 需要解析的字段名列表。 +- `separator`: 分隔符。 +- `quote`: 引号。 +- `trim`: 是否去除空格。默认为 `false`。 +- `ignore_missing`: 忽略字段不存在的情况。默认为 `false`。如果字段不存在，并且此配置为 false，则会抛出异常。 + +### `json_path`（实验性） + +注意：`json_path` 处理器目前处于实验阶段，可能会有所变动。 + +`json_path` 处理器用于从 JSON 数据中提取字段。以下是一个配置示例： + +```yaml +processors: + - json_path: + fields: + - complex_object + json_path: "$.shop.orders[?(@.active)].id" + ignore_missing: true + result_index: 1 +``` + +在上述示例中，`json_path` processor 的配置包括以下字段： + +- `fields`：要提取的字段名称列表。 +- `json_path`：要提取的 JSON 路径。 +- `ignore_missing`：忽略字段缺失的情况。默认为 `false`。如果字段缺失且此配置设置为 `false`，将抛出异常。 +- `result_index`：指定提取数组中要用作结果值的下标。默认情况下，包含所有值。Processor 提取的结果值是包含 path 中所有值的数组。如果指定了索引，将使用提取数组中对应的下标的值作为最终结果。 + +#### JSON 路径语法 + +JSON 路径语法基于 [jsonpath-rust](https://github.com/besok/jsonpath-rust) 库。 + +在此阶段，我们仅推荐使用一些简单的字段提取操作，以便将嵌套字段提取到顶层。 + +#### `json_path` 示例 + +例如，给定以下日志数据： + +```json +{ + "product_object": { + "hello": "world" + }, + "product_array": [ + "hello", + "world" + ], + "complex_object": { + "shop": { + "orders": [ + { + "id": 1, + "active": true + }, + { + "id": 2 + }, + { + "id": 3 + }, + { + "id": 4, + "active": true + } + ] + } + } +} +``` + +使用以下配置： + +```yaml +processors: + - json_path: + fields: + - product_object, object_target + json_path: "$.hello" + result_index: 0 + - json_path: + fields: + - product_array, array_target + json_path: "$.[1]" + result_index: 0 + - json_path: + fields: + - complex_object, complex_target_1 + json_path: "$.shop.orders[?(@.active)].id" + - json_path: + fields: + - complex_target_1, complex_target_2 + json_path: "$.[1]" + result_index: 0 + - json_path: + fields: + - complex_object, complex_target_3 + json_path: "$.shop.orders[?(@.active)].id" + result_index: 1 +transform: + - fields: + - object_target + - array_target + type: string + - fields: + - complex_target_3 + - complex_target_2 + type: uint32 + - fields: + - complex_target_1 + type: json +``` + +结果将是： + +```json +{ + "object_target": "world", + "array_target": "world", + "complex_target_3": 4, + "complex_target_2": 4, + "complex_target_1": [1, 4] +} +``` + +## Transform + +Transform 用于对 log 数据进行转换，其配置位于 YAML 文件中的 `transform` 字段下。 + +Transform 由一个或多个配置组成，每个配置包含以下字段： + +- `fields`: 需要转换的字段名列表。 +- `type`: 转换类型 +- `index`: 索引类型（可选） +- `on_failure`: 转换失败时的处理方式（可选） +- `default`: 默认值（可选） + +### `fields` 字段 + +每个字段名都是一个字符串，当字段名称包含 `,` 时，会进行字段重命名。例如，`reqTimeSec, req_time_sec` 表示将 `reqTimeSec` 字段重命名为 `req_time_sec`， +最终数据将被写入到 GreptimeDB 的 `req_time_sec` 列。 + +### `type` 字段 + +GreptimeDB 目前内置了以下几种转换类型： + +- `int8`, `int16`, `int32`, `int64`: 整数类型。 +- `uint8`, `uint16`, `uint32`, `uint64`: 无符号整数类型。 +- `float32`, `float64`: 浮点数类型。 +- `string`: 字符串类型。 +- `time`: 时间类型。将被转换为 GreptimeDB `timestamp(9)` 类型。 +- `epoch`: 时间戳类型。将被转换为 GreptimeDB `timestamp(n)` 类型。n 为时间戳精度，n 的值视 epoch 精度而定。当精度为 `s` 时，n 为 0；当精度为 `ms` 时，n 为 3；当精度为 `us` 时，n 为 6；当精度为 `ns` 时，n 为 9。 + +如果字段在转换过程中获得了非法值，Pipeline 将会抛出异常。例如将一个字符串 `abc` 转换为整数时，由于该字符串不是一个合法的整数，Pipeline 将会抛出异常。 + +### `index` 字段 + +`Pipeline` 会将处理后的数据写入到 GreptimeDB 自动创建的数据表中。为了提高查询效率，GreptimeDB 会为表中的某些列创建索引。`index` 字段用于指定哪些字段需要被索引。关于 GreptimeDB 的列类型，请参考[数据模型](/user-guide/concepts/data-model.md)文档。 + +GreptimeDB 支持以下三种字段的索引类型： + +- `tag`: 用于指定某列为 Tag 列 +- `fulltext`: 用于指定某列使用 fulltext 类型的索引，该列需要是字符串类型 +- `timestamp`: 用于指定某列是时间索引列 + +不提供 `index` 字段时，GreptimeDB 会将该字段作为 `Field` 列。 + +在 GreptimeDB 中，一张表里必须包含一个 `timestamp` 类型的列作为该表的时间索引列，因此一个 Pipeline 有且只有一个时间索引列。 + +#### 时间戳列 + +通过 `index: timestamp` 指定哪个字段是时间索引列，写法请参考下方的 [Transform 示例](#transform-示例)。 + +#### Tag 列 + +通过 `index: tag` 指定哪个字段是 Tag 列，写法请参考下方的 [Transform 示例](#transform-示例)。 + +#### Fulltext 列 + +通过 `index: fulltext` 指定哪个字段将会被用于全文搜索，该索引可大大提升 [日志搜索](./query-logs.md) 的性能，写法请参考下方的 [Transform 示例](#transform-示例)。 + +### `on_failure` 字段 + +`on_failure` 字段用于指定转换失败时的处理方式，支持以下几种方式： + +- `ignore`: 忽略转换失败的字段，不写入数据库。 +- `default`: 写入默认值。默认值由 `default` 字段指定。 + +### `default` 字段 + +`default` 字段用于指定转换失败时的默认值。 + +### Transform 示例 + +例如，对于以下 log 数据： + +```json +{ + "num_field_a": "3", + "string_field_a": "john", + "string_field_b": "It was snowing when he was born.", + "time_field_a": 1625760000 +} +``` + +使用以下配置： + +```yaml +transform: + - fields: + - string_field_a, name + type: string + index: tag + - fields: + - num_field_a, age + type: int32 + - fields: + - string_field_b, description + type: string + index: fulltext + - fields: + - time_field_a, born_time + type: epoch, s + index: timestamp +``` + +将得到以下结果： + +``` +{ + "name": "john", + "age": 3, + "description": "It was snowing when he was born.", + "born_time": 2021-07-08 16:00:00 +} +``` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/query-logs.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/query-logs.md new file mode 100644 index 000000000..09a6559b2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/query-logs.md @@ -0,0 +1,144 @@ +--- +description: 介绍如何使用 GreptimeDB 提供的查询语言进行日志数据的搜索和分析，包括使用 MATCHES 函数进行全文搜索和配置全文索引。 +--- + +# 查询日志 + +本文档介绍如何使用 GreptimeDB 提供的查询语言进行日志数据的搜索和分析。 + +## 查询概述 + +在 GreptimeDB 中，您可以通过 SQL 语句进行灵活的数据查询。本节将介绍如何使用特定的搜索函数和查询语句来优化您的日志查询。 + +## 使用 `MATCHES` 函数进行全文搜索 + +在 SQL 语句中，可以使用 `MATCHES` 函数来执行全文搜索，这对于日志分析尤其有用。`MATCHES` 函数支持对 `String` 类型的列进行全文搜索。以下是一个典型的使用示例： + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'error OR fail'); +``` + +`MATCHES` 是一个专门用于全文搜索的函数，它接受两个参数： + +- `column_name`：要进行全文搜索的列，该列包含文本数据，列的数据类型必须是 `String`。必须为此列建立[全文索引](#全文索引加速搜索)以优化查询。 +- `search_query`：一个字符串，包含要搜索的关键词和操作符，详情请看下文中的[查询语句类型](#查询语句类型)。 + +## 查询语句类型 + +### 简单词项 (Simple Term) + +简单的搜索词如下： + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'Barack Obama'); +``` + +上述 `MATCHES` 中参数 `search_query` 的值 `Barack Obama` 将被视为 `Barack` 和 `Obama` 两个独立的词项，这意味着该查询将匹配包含 `Barack` 或 `Obama` 的所有行，等价于使用 `OR`： + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'Barack OR Obama'); +``` + +### 否定词项 (Negative Term) + +通过在词项前加上 `-` 符号，可以排除包含某些词的行。例如，查询包含 `apple` 但不包含 `fruit` 的行： + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'apple -fruit'); +``` + +### 必需词项 (Must Term) + +通过在词项前加上 `+` 符号，可以指定必须出现在搜索结果中的词项。例如，查询同时包含 `apple` 和 `fruit` 的行： + +```sql +SELECT * FROM logs WHERE MATCHES(message, '+apple +fruit'); +``` + +### 布尔操作符 (Boolean Operators) + +布尔操作符能够指定搜索的条件逻辑。例如，`AND` 运算符要求搜索结果中同时包含多个词项，而 `OR` 运算符则要求结果中至少包含一个词项。在查询中，`AND` 运算符优先于 `OR` 运算符。因此，表达式 `a AND b OR c` 被解释为 `(a AND b) OR c`。例如： + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'a AND b OR c'); +``` + +这意味着查询将匹配同时包含 `a` 和 `b` 的行，或者包含 `c` 的行。等价于： + +```sql +SELECT * FROM logs WHERE MATCHES(message, '(+a +b) c'); +``` + +### 短语词项 (Phrase Term) + +使用引号 `" "` 包围的短语将作为整体进行匹配。例如，只匹配 `Barack` 后紧跟 `Obama` 的行： + +```sql +SELECT * FROM logs WHERE MATCHES(message, '"Barack Obama"'); +``` + +如果需要在短语中包含引号，可以使用反斜杠 `\` 进行转义： + +```sql +SELECT * FROM logs WHERE MATCHES(message, '"He said \"hello\""'); +``` + +## 全文索引加速搜索 + +全文索引是全文搜索的关键配置，尤其是在需要处理大量数据的搜索查询场景中。没有全文索引，搜索操作可能会非常缓慢，影响整体的查询性能和用户体验。您可以在创建表时直接通过 SQL 配置全文索引，或者通过 Pipeline 配置，确保搜索操作能够高效执行，即使是在数据量极大的情况下也能保持良好的性能。 + +### 通过 SQL 配置全文索引 + +您可以通过在列定义中指定 `FULLTEXT` 选项为某列创建全文索索引。下面是一个在 `message` 列上创建带有全文索引的表的示例： + +```sql +CREATE TABLE `logs` ( + `message` STRING FULLTEXT, + `time` TIMESTAMP TIME INDEX, +) WITH ( + append_mode = 'true' +); +``` + +更多详情，请参见[`FULLTEXT` 列选项](/reference/sql/create.md#fulltext-列选项)。 + +### 通过 Pipeline 配置全文索引 + +在 Pipeline 的配置中，可以[指定某列使用全文索引](./pipeline-config.md#index-字段)。以下是一个配置示例，其中 `message` 列被设置为全文索引： + +```yaml +processors: + - date: + field: time + formats: + - "%Y-%m-%d %H:%M:%S%.3f" + ignore_missing: true + +transform: + - field: message + type: string + index: fulltext + - field: time + type: time + index: timestamp +``` + +#### 查看表结构 + +在数据写入后，可以通过 SQL 命令查看表结构，确认 `message` 列已经被设置为全文索引： + +```sql +SHOW CREATE TABLE logs\G +*************************** 1. row *************************** + Table: logs +Create Table: CREATE TABLE IF NOT EXISTS `logs` ( + `message` STRING NULL FULLTEXT WITH(analyzer = 'English', case_sensitive = 'false'), + `time` TIMESTAMP(9) NOT NULL, + TIME INDEX (`time`), +) + +ENGINE=mito +WITH( + append_mode = 'true' +) +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/quick-start.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/quick-start.md new file mode 100644 index 000000000..2c9b4326e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/quick-start.md @@ -0,0 +1,270 @@ +--- +description: 介绍如何快速开始写入和查询日志，包括直接写入日志和使用 Pipeline 写入日志的方法，以及两者的区别。 +--- + +# 快速开始 + +本指南将引导您快速完成写入并查询日志的过程。 + +您可以直接写入日志或使用 pipeline 写入日志。 +直接写入日志很简单，但不能像 pipeline 方法那样将日志文本拆分为结构化数据。 +以下部分将帮助您了解这两种方法之间的区别。 + +## 直接写入日志 + +这是将日志写入 GreptimeDB 的最简单方法。 + +### 创建表 + +首先，创建一个名为 `origin_logs` 的表来存储您的日志。 +以下 SQL 中 `message` 列的 `FULLTEXT` 表示创建了一个全文索引以优化查询。 + +```sql +CREATE TABLE `origin_logs` ( + `message` STRING FULLTEXT, + `time` TIMESTAMP TIME INDEX +) WITH ( + append_mode = 'true' +); +``` + +### 插入日志 + +#### 使用 SQL 协议写入 + +使用 `INSERT` 语句将日志插入表中。 + +```sql +INSERT INTO origin_logs (message, time) VALUES +('127.0.0.1 - - [25/May/2024:20:16:37 +0000] "GET /index.html HTTP/1.1" 200 612 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"', '2024-05-25 20:16:37.217'), +('192.168.1.1 - - [25/May/2024:20:17:37 +0000] "POST /api/login HTTP/1.1" 200 1784 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36"', '2024-05-25 20:17:37.217'), +('10.0.0.1 - - [25/May/2024:20:18:37 +0000] "GET /images/logo.png HTTP/1.1" 304 0 "-" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0"', '2024-05-25 20:18:37.217'), +('172.16.0.1 - - [25/May/2024:20:19:37 +0000] "GET /contact HTTP/1.1" 404 162 "-" "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1"', '2024-05-25 20:19:37.217'); +``` + +上述 SQL 将整个日志文本插入到一个列中，除此之外，您必须为每条日志添加一个额外的时间戳。 + +#### 使用 gRPC 协议写入 + +您也可以使用 gRPC 协议写入日志，这是一个更高效的方法。 + +请参阅[使用 gRPC 写入数据](/user-guide/ingest-data/for-iot/grpc-sdks/overview.md)以了解如何使用 gRPC 协议写入日志。 + +## 使用 Pipeline 写入日志 + +使用 pipeline 可以自动将日志消息格式化并转换为多个列，并自动创建表。 + +### 使用内置 Pipeline 写入 JSON 日志 + +GreptimeDB 提供了一个内置 pipeline `greptime_identity` 用于处理 JSON 日志格式。该 pipeline 简化了写入 JSON 日志的过程。 + +```shell +curl -X "POST" "http://localhost:4000/v1/events/logs?db=public&table=pipeline_logs&pipeline_name=greptime_identity" \ + -H 'Content-Type: application/json' \ + -d $'[ + {"name": "Alice", "age": 20, "is_student": true, "score": 90.5,"object": {"a":1,"b":2}}, + {"age": 21, "is_student": false, "score": 85.5, "company": "A" ,"whatever": null}, + {"name": "Charlie", "age": 22, "is_student": true, "score": 95.5,"array":[1,2,3]} +]' +``` + +- `pipeline_name=greptime_identity` 指定了内置 pipeline。 +- `table=pipeline_logs` 指定了目标表。如果表不存在，将自动创建。 +`greptime_identity` pipeline 将自动为 JSON 日志中的每个字段创建列。成功执行命令将返回： + +```json +{"output":[{"affectedrows":3}],"execution_time_ms":9} +``` + +有关 `greptime_identity` pipeline 的更多详细信息，请参阅 [管理 Pipeline](manage-pipelines.md#greptime_identity) 文档。 + +### 使用自定义 Pipeline 写入日志 + +#### 创建 Pipeline + +GreptimeDB 提供了一个专用的 HTTP 接口来创建 pipeline。方法如下： + +首先，创建一个 pipeline 文件，例如 `pipeline.yaml`。 + +```yaml +processors: + - dissect: + fields: + - message + patterns: + - '%{ip_address} - - [%{timestamp}] "%{http_method} %{request_line}" %{status_code} %{response_size} "-" "%{user_agent}"' + ignore_missing: true + - date: + fields: + - timestamp + formats: + - "%d/%b/%Y:%H:%M:%S %z" + +transform: + - fields: + - ip_address + - http_method + type: string + index: tag + - fields: + - status_code + type: int32 + index: tag + - fields: + - request_line + - user_agent + type: string + index: fulltext + - fields: + - response_size + type: int32 + - fields: + - timestamp + type: time + index: timestamp +``` + +该 pipeline 使用指定的模式拆分 `message` 字段以提取 `ip_address`、`timestamp`、`http_method`、`request_line`、`status_code`、`response_size` 和 `user_agent`。 +然后，它使用格式 `%d/%b/%Y:%H:%M:%S %z` 解析 `timestamp` 字段，将其转换为数据库可以理解的正确时间戳格式。 +最后，它将每个字段转换为适当的数据类型并相应地建立索引。 +需要注意的是，`request_line` 和 `user_agent` 字段被索引为 `fulltext` 以优化全文搜索查询，且表中必须有一个由 `timestamp` 指定的时间索引列。 + +执行以下命令上传配置文件： + +```shell +curl -X "POST" "http://localhost:4000/v1/events/pipelines/nginx_pipeline" -F "file=@pipeline.yaml" +``` + +成功执行此命令后，将创建一个名为 `nginx_pipeline` 的 pipeline，返回的结果如下： + +```json +{"name":"nginx_pipeline","version":"2024-06-27 12:02:34.257312110Z"}. +``` + +您可以为同一 pipeline 名称创建多个版本。 +所有 pipeline 都存储在 `greptime_private.pipelines` 表中。 +请参阅[查询 Pipelines](manage-pipelines.md#查询-pipeline)以查看表中的 pipeline 数据。 + +#### 写入日志 + +以下示例将日志写入 `pipeline_logs` 表，并使用 `nginx_pipeline` pipeline 格式化和转换日志消息。 + +```shell +curl -X "POST" "http://localhost:4000/v1/events/logs?db=public&table=pipeline_logs&pipeline_name=nginx_pipeline" \ + -H 'Content-Type: application/json' \ + -d $'[ +{"message":"127.0.0.1 - - [25/May/2024:20:16:37 +0000] \\"GET /index.html HTTP/1.1\\" 200 612 \\"-\\" \\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\\""}, +{"message":"192.168.1.1 - - [25/May/2024:20:17:37 +0000] \\"POST /api/login HTTP/1.1\\" 200 1784 \\"-\\" \\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36\\""}, +{"message":"10.0.0.1 - - [25/May/2024:20:18:37 +0000] \\"GET /images/logo.png HTTP/1.1\\" 304 0 \\"-\\" \\"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0\\""}, +{"message":"172.16.0.1 - - [25/May/2024:20:19:37 +0000] \\"GET /contact HTTP/1.1\\" 404 162 \\"-\\" \\"Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1\\""} +]' +``` + +如果命令执行成功，您将看到以下输出： + +```json +{"output":[{"affectedrows":4}],"execution_time_ms":79} +``` + +## 直接写入日志与使用 Pipeline 的区别 + +在上述示例中，直接写入日志的方式创建了表 `origin_logs`，使用 pipeline 写入日志的方式自动创建了表 `pipeline_logs`，让我们来探讨这两个表之间的区别。 + + +```sql +DESC origin_logs; +``` + +```sql ++---------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++---------+----------------------+------+------+---------+---------------+ +| message | String | | YES | | FIELD | +| time | TimestampMillisecond | PRI | NO | | TIMESTAMP | ++---------+----------------------+------+------+---------+---------------+ +``` + +```sql +DESC pipeline_logs; +``` + +```sql ++---------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++---------------+---------------------+------+------+---------+---------------+ +| ip_address | String | PRI | YES | | TAG | +| http_method | String | PRI | YES | | TAG | +| status_code | Int32 | PRI | YES | | TAG | +| request_line | String | | YES | | FIELD | +| user_agent | String | | YES | | FIELD | +| response_size | Int32 | | YES | | FIELD | +| timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | ++---------------+---------------------+------+------+---------+---------------+ +7 rows in set (0.00 sec) +``` + +从表结构中可以看到，`origin_logs` 表只有两列，整个日志消息存储在一个列中。 +而 `pipeline_logs` 表将日志消息存储在多个列中。 + +推荐使用 pipeline 方法将日志消息拆分为多个列，这样可以精确查询某个特定列中的某个值。 +与全文搜索相比，Tag 匹配查询在处理字符串时具有以下几个优势： + +- **性能效率**：Tag 的匹配查询通常都比全文搜索更快。 +- **资源消耗**：由于 GreptimeDB 的存储引擎是列存，结构化的数据更利于数据的压缩，并且 Tag 匹配查询使用的倒排索引，其资源消耗通常显著少于全文索引，尤其是在存储大小方面。 +- **可维护性**：精确匹配查询简单明了，更易于理解、编写和调试。 + +当然，如果需要在大段文本中进行关键词搜索，依然需要使用全文搜索，因为它就是专门为此设计。 + +## 查询日志 + +以 `pipeline_logs` 表为例查询日志。 + +### 按 Tag 查询日志 + +对于 `pipeline_logs` 中的多个 Tag 列，您可以灵活地按 Tag 查询数据。 +例如，查询 `status_code` 为 `200` 且 `http_method` 为 `GET` 的日志。 + +```sql +SELECT * FROM pipeline_logs WHERE status_code = 200 AND http_method = 'GET'; +``` + +```sql ++------------+-------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +| ip_address | http_method | status_code | request_line | user_agent | response_size | timestamp | ++------------+-------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +| 127.0.0.1 | GET | 200 | /index.html HTTP/1.1 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 | 612 | 2024-05-25 20:16:37 | ++------------+-------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +1 row in set (0.02 sec) +``` + +### 全文搜索 + +对于 `request_line` 和 `user_agent` 文本字段，您可以使用 `MATCHES` 函数查询日志。 +请记得我们在[创建 Pipeline](#创建-pipeline) 时为这两个列创建了全文索引，这提高了全文搜索的性能。 + +例如，查询 `request_line` 包含 `/index.html` 或 `/api/login` 的日志。 + +```sql +SELECT * FROM pipeline_logs WHERE MATCHES(request_line, 'index.html /api/login'); +``` + +```sql ++-------------+-------------+-------------+----------------------+--------------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +| ip_address | http_method | status_code | request_line | user_agent | response_size | timestamp | ++-------------+-------------+-------------+----------------------+--------------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +| 127.0.0.1 | GET | 200 | /index.html HTTP/1.1 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 | 612 | 2024-05-25 20:16:37 | +| 192.168.1.1 | POST | 200 | /api/login HTTP/1.1 | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36 | 1784 | 2024-05-25 20:17:37 | ++-------------+-------------+-------------+----------------------+--------------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +2 rows in set (0.00 sec) +``` + +您可以参阅[全文搜索](query-logs.md#使用-matches-函数进行全文搜索)文档以获取 `MATCHES` 函数的详细用法。 + +## 下一步 + +您现在已经体验了 GreptimeDB 的日志记录功能，可以通过以下文档进一步探索： + +- [Pipeline 配置](./pipeline-config.md): 提供 GreptimeDB 中每个 pipeline 配置的深入信息。 +- [管理 Pipeline](./manage-pipelines.md): 解释如何创建和删除 pipeline。 +- [使用 Pipeline 写入日志](./write-logs.md): 介绍利用 pipeline 机制写入日志数据的详细说明。 +- [查询日志](./query-logs.md): 描述如何使用 GreptimeDB SQL 接口查询日志。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/write-logs.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/write-logs.md new file mode 100644 index 000000000..2827bfd33 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/logs/write-logs.md @@ -0,0 +1,112 @@ +--- +description: 介绍如何通过 HTTP 接口使用指定的 Pipeline 将日志写入 GreptimeDB，包括请求参数、数据格式和示例。 +--- + +# 使用 Pipeline 写入日志 + +本文档介绍如何通过 HTTP 接口使用指定的 Pipeline 进行处理后将日志写入 GreptimeDB。 + +在写入日志之前，请先阅读 [Pipeline 配置](pipeline-config.md)和[管理 Pipeline](manage-pipelines.md) 完成配置的设定和上传。 + +## HTTP API + +您可以使用以下命令通过 HTTP 接口写入日志： + +```shell +curl -X "POST" "http://localhost:4000/v1/events/logs?db=&table=&pipeline_name=&version=" \ + -H 'Content-Type: application/json' \ + -d "$" +``` + + +## 请求参数 + +此接口接受以下参数： + +- `db`：数据库名称。 +- `table`：表名称。 +- `pipeline_name`：[Pipeline](./pipeline-config.md) 名称。 +- `version`：Pipeline 版本号。可选，默认使用最新版本。 + +## `Content-Type` 和 Body 数据格式 + +GreptimeDB 使用 `Content-Type` header 来决定如何解码请求体内容。目前我们支持以下两种格式： +- `application/json`: 包括普通的 JSON 格式和 NDJSON 格式。 +- `text/plain`: 通过换行符分割的多行日志文本行。 + +### `application/json` 格式 + +以下是一份 JSON 格式请求体内容的示例： + +```JSON +[ + {"message":"127.0.0.1 - - [25/May/2024:20:16:37 +0000] \"GET /index.html HTTP/1.1\" 200 612 \"-\" \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\""}, + {"message":"192.168.1.1 - - [25/May/2024:20:17:37 +0000] \"POST /api/login HTTP/1.1\" 200 1784 \"-\" \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36\""}, + {"message":"10.0.0.1 - - [25/May/2024:20:18:37 +0000] \"GET /images/logo.png HTTP/1.1\" 304 0 \"-\" \"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0\""}, + {"message":"172.16.0.1 - - [25/May/2024:20:19:37 +0000] \"GET /contact HTTP/1.1\" 404 162 \"-\" \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1\""} +] +``` + +请注意整个 JSON 是一个数组（包含多行日志）。每个 JSON 对象代表即将要被 Pipeline 引擎处理的一行日志。 + +JSON 对象中的 key 名，也就是这里的 `message`，会被用作 Pipeline processor 处理时的 field 名称。比如： + +```yaml +processors: + - dissect: + fields: + # `message` 是 JSON 对象中的 key 名 + - message + patterns: + - '%{ip_address} - - [%{timestamp}] "%{http_method} %{request_line}" %{status_code} %{response_size} "-" "%{user_agent}"' + ignore_missing: true + +# pipeline 文件的剩余部分在这里省略 +``` + +我们也可以将这个请求体内容改写成 NDJSON 的格式，如下所示： + +```JSON +{"message":"127.0.0.1 - - [25/May/2024:20:16:37 +0000] \"GET /index.html HTTP/1.1\" 200 612 \"-\" \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\""} +{"message":"192.168.1.1 - - [25/May/2024:20:17:37 +0000] \"POST /api/login HTTP/1.1\" 200 1784 \"-\" \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36\""} +{"message":"10.0.0.1 - - [25/May/2024:20:18:37 +0000] \"GET /images/logo.png HTTP/1.1\" 304 0 \"-\" \"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0\""} +{"message":"172.16.0.1 - - [25/May/2024:20:19:37 +0000] \"GET /contact HTTP/1.1\" 404 162 \"-\" \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1\""} +``` + +注意到最外层的数组符被消去了，现在每个 JSON 对象通过换行符分割而不是 `,`。 + +### `text/plain` 格式 + +纯文本日志在整个生态系统中被广泛应用。GreptimeDB 同样支持日志数据以 `text/plain` 格式进行输入，使得我们可以直接从日志产生源进行写入。 + +以下是一份和上述样例请求体内容等价的文本请求示例： + +```plain +127.0.0.1 - - [25/May/2024:20:16:37 +0000] "GET /index.html HTTP/1.1" 200 612 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" +192.168.1.1 - - [25/May/2024:20:17:37 +0000] "POST /api/login HTTP/1.1" 200 1784 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36" +10.0.0.1 - - [25/May/2024:20:18:37 +0000] "GET /images/logo.png HTTP/1.1" 304 0 "-" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0" +172.16.0.1 - - [25/May/2024:20:19:37 +0000] "GET /contact HTTP/1.1" 404 162 "-" "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1" +``` + +仅需要将 `Content-Type` header 设置成 `text/plain`，即可将纯文本请求发送到 GreptimeDB。 + +主要注意的是，和 JSON 格式自带 key 名可以被 Pipeline processor 识别和处理不同，`text/plain` 格式直接将整行文本输入到 Pipeline engine。在这种情况下我们可以使用 `line` 来指代整行输入文本，例如： + +```yaml +processors: + - dissect: + fields: + # 使用 `line` 作为 field 名称 + - line + patterns: + - '%{ip_address} - - [%{timestamp}] "%{http_method} %{request_line}" %{status_code} %{response_size} "-" "%{user_agent}"' + ignore_missing: true + +# pipeline 文件的剩余部分在这里省略 +``` + +对于 `text/plain` 格式的输入，推荐首先使用 `dissect` 或者 `regex` processor 将整行文本分割成不同的字段，以便进行后续的处理。 + +## 示例 + +请参考快速开始中的[写入日志](quick-start.md#写入日志)部分。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/manage-data/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/manage-data/overview.md new file mode 100644 index 000000000..67b828661 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/manage-data/overview.md @@ -0,0 +1,332 @@ +--- +description: 介绍如何在 GreptimeDB 中更新和删除数据，包括使用相同的 tag 和 time index 更新数据、删除数据、使用 TTL 策略保留数据等。 +--- + +# 概述 + +## 更新数据 + +### 使用相同的 tag 和 time index 更新数据 + +更新操作可以通过插入操作来实现。 +如果某行数据具有相同的 tag 和 time index，旧数据将被新数据替换，这意味着你只能更新 field 类型的列。 +想要更新数据，只需使用与现有数据相同的 tag 和 time index 插入新数据即可。 + +有关列类型的更多信息，请参阅[数据模型](/user-guide/concepts/data-model.md)。 + +:::warning 注意 +尽管更新操作的性能与插入数据相同，过多的更新可能会对查询性能产生负面影响。 +::: + +#### 更新表中的所有字段 + +在更新数据时，默认情况下所有字段都将被新值覆盖， +而 [InfluxDB 行协议](/user-guide/protocols/influxdb-line-protocol.md) 除外，它只会[更新表中的部分字段](#更新表中的部分字段)。 +以下示例使用 SQL 演示了更新表中所有字段的行为。 + +假设你有一个名为 `monitor` 的表，具有以下 schema。 +`host` 列表示 tag，`ts` 列表示 time index。 + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64, + memory FLOAT64, + PRIMARY KEY(host) +); +``` + +向 `monitor` 表中插入一行新数据： + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.8, 0.1); +``` + +检查表中的数据： + +```sql +SELECT * FROM monitor; +``` + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:00 | 0.8 | 0.1 | ++-----------+---------------------+------+--------+ +1 row in set (0.00 sec) +``` + +要更新数据，你可以使用与现有数据相同的 `host` 和 `ts` 值，并将新的 `cpu` 值设置为 `0.5`： + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +-- 与现有数据相同的标签 `127.0.0.1` 和相同的时间索引 2024-07-11 20:00:00 +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.5, 0.1); +``` + +新数据将为： + +```sql +SELECT * FROM monitor; +``` + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +1 row in set (0.01 sec) +``` + +当使用默认的合并策略时， +如果在 `INSERT INTO` 语句中省略了某列， +它们将被默认值覆盖。 + +例如： + +```sql +INSERT INTO monitor (host, ts, cpu) +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.5); +``` + +`monitor` 表中 `memory` 列的默认值为 `NULL`。因此，新数据将为： + +```sql +SELECT * FROM monitor; +``` + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:00 | 0.5 | NULL | ++-----------+---------------------+------+--------+ +1 row in set (0.01 sec) +``` + +### 更新表中的部分字段 + +默认情况下， [InfluxDB 行协议](/user-guide/protocols/influxdb-line-protocol.md) 支持此种更新策略。 +你还可以使用 SQL 在创建表时通过指定 `merge_mode` 选项为 `last_non_null` 来启用此行为。 +示例如下： + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64, + memory FLOAT64, + PRIMARY KEY(host) +) WITH ('merge_mode'='last_non_null'); +``` + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.8, 0.1); +``` + +要更新 `monitor` 表中的特定字段， +你可以只插入带有要更新的字段的新数据。 +例如： + +```sql +INSERT INTO monitor (host, ts, cpu) +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.5); +``` + +这将更新 `cpu` 字段，同时保持 `memory` 字段不变。 +结果将为： + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` + + +请注意， `last_non_null` 无法将旧值更新为 `NULL`。 +例如： + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES ("127.0.0.1", "2024-07-11 20:00:01", 0.8, 0.1); +``` + +```sql +INSERT INTO monitor (host, ts, cpu) +VALUES ("127.0.0.1", "2024-07-11 20:00:01", NULL); +``` + +不会更新任何内容： + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:01 | 0.8 | 0.1 | ++-----------+---------------------+------+--------+ +``` + +有关 `merge_mode` 选项的更多信息，请参阅 [CREATE TABLE](/reference/sql/create.md##创建带有-merge-模式的表) 语句。 + +### 通过创建带有 `append_mode` 选项的表来避免更新数据 + +在创建表时，GreptimeDB 支持 `append_mode` 选项，该选项始终将新数据插入表中。 +当你想要保留所有历史数据（例如日志）时十分有用。 + +你只能使用 SQL 创建带有 `append_mode` 选项的表。 +成功创建表后，所有[写入数据的协议](/user-guide/ingest-data/overview.md)都将在表中始终插入新数据。 + +例如，你可以创建一个带有 `append_mode` 选项的 `app_logs` 表，如下所示。 +`host` 和 `log_level` 列表示 tag，`ts` 列表示 time index。 + +```sql +CREATE TABLE app_logs ( + ts TIMESTAMP TIME INDEX, + host STRING, + api_path STRING FULLTEXT, + log_level STRING, + log STRING FULLTEXT, + PRIMARY KEY (host, log_level) +) WITH ('append_mode'='true'); +``` + +向 `app_logs` 表中插入一行新数据： + +```sql +INSERT INTO app_logs (ts, host, api_path, log_level, log) +VALUES ('2024-07-11 20:00:10', 'host1', '/api/v1/resource', 'ERROR', 'Connection timeout'); +``` + +检查表中的数据： + +```sql +SELECT * FROM app_logs; +``` + +输出将为： + +```sql ++---------------------+-------+------------------+-----------+--------------------+ +| ts | host | api_path | log_level | log | ++---------------------+-------+------------------+-----------+--------------------+ +| 2024-07-11 20:00:10 | host1 | /api/v1/resource | ERROR | Connection timeout | ++---------------------+-------+------------------+-----------+--------------------+ +1 row in set (0.01 sec) +``` + +你可以插入具有相同 tag 和 time index 的新数据： + +```sql +INSERT INTO app_logs (ts, host, api_path, log_level, log) +-- 与现有数据相同的标签 `host1` 和 `ERROR`，相同的时间索引 2024-07-11 20:00:10 +VALUES ('2024-07-11 20:00:10', 'host1', '/api/v1/resource', 'ERROR', 'Connection reset'); +``` + +然后，你将在表中找到两行数据： + +```sql +SELECT * FROM app_logs; +``` + +```sql ++---------------------+-------+------------------+-----------+--------------------+ +| ts | host | api_path | log_level | log | ++---------------------+-------+------------------+-----------+--------------------+ +| 2024-07-11 20:00:10 | host1 | /api/v1/resource | ERROR | Connection reset | +| 2024-07-11 20:00:10 | host1 | /api/v1/resource | ERROR | Connection timeout | ++---------------------+-------+------------------+-----------+--------------------+ +2 rows in set (0.01 sec) +``` + +## 删除数据 + +你可以通过指定 tag 和 time index 来有效地删除数据。 +未指定 tag 和 time index 进行删除数据不高效，因为它需要两个步骤：查询数据，然后按 tag 和 time index 进行删除。 +有关列类型的更多信息，请参阅[数据模型](/user-guide/concepts/data-model.md)。 + +:::warning 警告 +过多的删除可能会对查询性能产生负面影响。 +::: + +只能使用 SQL 删除数据。 +例如，要从 `monitor` 表中删除具有 tag `host` 和 time index `ts` 的行： + +```sql +DELETE FROM monitor WHERE host='127.0.0.2' AND ts=1667446798450; +``` + +输出将为： + +```sql +Query OK, 1 row affected (0.00 sec) +``` + +有关 `DELETE` 语句的更多信息，请参阅 [SQL DELETE](/reference/sql/delete.md)。 + +## 删除表中的所有数据 + +要删除表中的所有数据，可以使用 SQL 中的 `TRUNCATE TABLE` 语句。 +例如，要清空 `monitor` 表： + +```sql +TRUNCATE TABLE monitor; +``` + +有关 `TRUNCATE TABLE` 语句的更多信息，请参阅 [SQL TRUNCATE TABLE](/reference/sql/truncate.md) 文档。 + +## 使用 TTL 策略保留数据 + +Time to Live (TTL) 允许你设置定期删除表中数据的策略， +你可以使用 TTL 自动删除数据库中的过期数据。 +设置 TTL 策略具有以下好处： + +- 通过清理过期数据来降低存储成本。 +- 减少数据库在某些查询中需要扫描的行数，从而提高查询性能。 + +你可以在创建每个表时设置 TTL。 +例如，以下 SQL 语句创建了一个名为 `monitor` 的表，并设置了 7 天的 TTL 策略： + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64, + memory FLOAT64, + PRIMARY KEY(host) +) WITH ('ttl'='7d'); +``` + +你还可以创建数据库级别的 TTL 策略。 +例如，以下 SQL 语句创建了一个名为 `test` 的数据库，并设置了 7 天的 TTL 策略： + +```sql +CREATE DATABASE test WITH ('ttl'='7d'); +``` + +你可以同时为 table 和 database 设置 TTL 策略。 +如果 table 有自己的 TTL 策略，则该策略将优先于 database 的 TTL 策略， +否则 database 的 TTL 策略将被应用于 table。 + +`'ttl'` 参数的值可以是持续时间（例如 `1hour 12min 5s`）、`instant` 或 `forever`。有关详细信息，请参阅 [CREATE](/reference/sql/create.md#create-a-table-with-ttl) 语句的文档。 + +如果你想移除 TTL 策略，可以使用如下 SQL 语句： + +```sql +-- 针对表移除 'ttl' 设置 +ALTER TABLE monitor UNSET 'ttl'; +-- 针对数据库移除 'ttl' 设置 +ALTER DATABASE test UNSET 'ttl'; +``` + +有关 TTL 策略的更多信息，请参阅 [CREATE](/reference/sql/create.md) 语句。 + +## 更多数据管理操作 + +有关更高级的数据管理操作，例如基本表操作、表分片和 Region 迁移，请参阅 Administration 部分的[数据管理](/user-guide/administration/manage-data/overview.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md new file mode 100644 index 000000000..5ccf2c75c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md @@ -0,0 +1,194 @@ +--- +description: 指导用户从 InfluxDB 迁移到 GreptimeDB，包括使用 HTTP API 和客户端库写入数据的示例。 +--- + +import DocTemplate from '../../db-cloud-shared/migrate/migrate-from-influxdb.md' + +# 从 InfluxDB 迁移 + + + +
+ + + + +```shell +curl -X POST 'http://:4000/v1/influxdb/api/v2/write?db=' \ + -H 'authorization: token ' \ + -d 'census,location=klamath,scientist=anderson bees=23 1566086400000000000' +``` + + + + + +```shell +curl 'http://:4000/v1/influxdb/write?db=&u=&p=' \ + -d 'census,location=klamath,scientist=anderson bees=23 1566086400000000000' +``` + + + + + +
+ +
+ +有关详细的配置说明，请参考[通过 Telegraf 写入数据](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md#telegraf)文档。 + +
+ +
+ + + + +```js +'use strict' +/** @module write +**/ + +import { InfluxDB, Point } from '@influxdata/influxdb-client' + +/** Environment variables **/ +const url = 'http://:4000/v1/influxdb' +const token = ':' +const org = '' +const bucket = '' + +const influxDB = new InfluxDB({ url, token }) +const writeApi = influxDB.getWriteApi(org, bucket) +writeApi.useDefaultTags({ region: 'west' }) +const point1 = new Point('temperature') + .tag('sensor_id', 'TLM01') + .floatField('value', 24.0) +writeApi.writePoint(point1) + +``` + + + + + + +```python +import influxdb_client +from influxdb_client.client.write_api import SYNCHRONOUS + +bucket = "" +org = "" +token = ":" +url="http://:4000/v1/influxdb" + +client = influxdb_client.InfluxDBClient( + url=url, + token=token, + org=org +) + +# Write script +write_api = client.write_api(write_options=SYNCHRONOUS) + +p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3) +write_api.write(bucket=bucket, org=org, record=p) + +``` + + + + + +```go +bucket := "" +org := "" +token := ":" +url := "http://:4000/v1/influxdb" +client := influxdb2.NewClient(url, token) +writeAPI := client.WriteAPIBlocking(org, bucket) + +p := influxdb2.NewPoint("stat", + map[string]string{"unit": "temperature"}, + map[string]interface{}{"avg": 24.5, "max": 45}, + time.Now()) +writeAPI.WritePoint(context.Background(), p) +client.Close() + +``` + + + + + +```java +private static String url = "http://:4000/v1/influxdb"; +private static String org = ""; +private static String bucket = ""; +private static char[] token = ":".toCharArray(); + +public static void main(final String[] args) { + + InfluxDBClient influxDBClient = InfluxDBClientFactory.create(url, token, org, bucket); + WriteApiBlocking writeApi = influxDBClient.getWriteApiBlocking(); + Point point = Point.measurement("temperature") + .addTag("location", "west") + .addField("value", 55D) + .time(Instant.now().toEpochMilli(), WritePrecision.MS); + + writeApi.writePoint(point); + influxDBClient.close(); +} +``` + + + + + +```php +$client = new Client([ + "url" => "http://:4000/v1/influxdb", + "token" => ":", + "bucket" => "", + "org" => "", + "precision" => InfluxDB2\Model\WritePrecision::S +]); + +$writeApi = $client->createWriteApi(); + +$dateTimeNow = new DateTime('NOW'); +$point = Point::measurement("weather") + ->addTag("location", "Denver") + ->addField("temperature", rand(0, 20)) + ->time($dateTimeNow->getTimestamp()); +$writeApi->write($point); +``` + + + + + +
+ +
+ +推荐使用 Grafana 可视化 GreptimeDB 数据， +请参考 [Grafana 文档](/user-guide/integrations/grafana.md)了解如何配置 GreptimeDB。 + +
+ +
+ + +```shell +for file in data.*; do + curl -i --retry 3 \ + -X POST "http://${GREPTIME_HOST}:4000/v1/influxdb/write?db=${GREPTIME_DB}&u=${GREPTIME_USERNAME}&p=${GREPTIME_PASSWORD}" \ + --data-binary @${file} + sleep 1 +done +``` + +
+ + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-mysql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-mysql.md new file mode 100644 index 000000000..077bef03e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-mysql.md @@ -0,0 +1,87 @@ +--- +description: 指导用户从 MySQL 迁移到 GreptimeDB，包括创建数据库和表、双写策略、数据导出和导入等步骤。 +--- + +# 从 MySQL 迁移 + +本文档将指引您完成从 MySQL 迁移到 GreptimeDB。 + +## 在开始迁移之前 + +请注意，尽管 GreptimeDB 支持 MySQL 的协议，并不意味着 GreptimeDB 实现了 MySQL +的所有功能。你可以参考 "[ANSI 兼容性](/reference/sql/compatibility.md)" 查看在 GreptimeDB 中使用 SQL 的约束。 + +## 迁移步骤 + +### 在 GreptimeDB 中创建数据库和表 + +在从 MySQL 迁移数据之前，你首先需要在 GreptimeDB 中创建相应的数据库和表。 +由于 GreptimeDB 有自己的 SQL 语法用于创建表，因此你不能直接重用 MySQL 生成的建表 SQL。 + +当你为 GreptimeDB 编写创建表的 SQL 时，首先请了解其“[数据模型](/user-guide/concepts/data-model.md)”。然后，在创建表的 +SQL 中请考虑以下几点： + +1. 由于 time index 列在表创建后无法更改，所以你需要仔细选择 time index + 列。时间索引最好设置为数据生成时的自然时间戳，因为它提供了查询数据的最直观方式，以及最佳的查询性能。例如，在 IOT + 场景中，你可以使用传感器采集数据时的时间作为 time index；或者在可观测场景中使用事件的发生时间。 +2. 不建议在此迁移过程中另造一个时间戳用作时间索引，例如使用 `DEFAULT current_timestamp()` 创建的新列。也不建议使用具有随机时间戳的列。 +3. 选择合适的 time index 精度也至关重要。和 time index 的选择一样，一旦表创建完毕，time index + 的精度就无法变更了。请根据你的数据集在[这里](/reference/sql/data-types#data-types-compatible-with-mysql-and-postgresql) + 找到最适合的时间戳类型。 +4. 根据您的查询模式选择最适合的 tag 列。tag 列存储经常被查询的元数据，其中的值是数据源的标签，通常用于描述数据的特征。tag 列具有索引，所以使用 tag 列的查询具备良好的性能。 + +请参考[CREATE](/reference/sql/create.md) SQL 文档，了解如何选择正确的数据类型以及“ttl”或“compaction”选项等。 + +### 双写 GreptimeDB 和 MySQL + +双写 GreptimeDB 和 MySQL 是迁移过程中防止数据丢失的有效策略。通过使用 MySQL 的客户端库（JDBC + 某个 MySQL +驱动），你可以建立两个客户端实例 —— 一个用于 GreptimeDB，另一个用于 MySQL。有关如何使用 SQL 将数据写入 +GreptimeDB，请参考[写入数据](/user-guide/ingest-data/for-iot/sql.md)部分。 + +若无需保留所有历史数据，你可以双写一段时间以积累业务所需的最新数据，然后停止向 MySQL 写入数据并仅使用 +GreptimeDB。如果需要完整迁移所有历史数据，请按照接下来的步骤操作。 + +### 从 MySQL 导出数据 + +[mysqldump](https://dev.mysql.com/doc/refman/8.4/en/mysqldump.html) 是一个常用的、从 MySQL 导出数据的工具。使用 +mysqldump，我们可以从 MySQL 中导出后续可直接导入到 GreptimeDB 的数据。例如，如果我们想要从 MySQL 导出两个数据库 `db1` 和 +`db2`，我们可以使用以下命令： + +```bash +mysqldump -h127.0.0.1 -P3306 -umysql_user -p --compact -cnt --skip-extended-insert --databases db1 db2 > /path/to/output.sql +``` + +替换 `-h`、`-P` 和 `-u` 参数为 MySQL 服务的正确值。`--databases` 参数用于指定要导出的数据库。输出将写入 +`/path/to/output.sql` 文件。 + +`/path/to/output.sql` 文件应该具有如下内容： + +```plaintext +~ ❯ cat /path/to/output.sql + +USE `db1`; +INSERT INTO `foo` (`ts`, `a`, `b`) VALUES (1,'hello',1); +INSERT INTO ... + +USE `db2`; +INSERT INTO `foo` (`ts`, `a`, `b`) VALUES (2,'greptime',2); +INSERT INTO ... +``` + +### 将数据导入 GreptimeDB + +[MySQL Command-Line Client](https://dev.mysql.com/doc/refman/8.4/en/mysql.html) 可用于将数据导入 +GreptimeDB。继续上面的示例，假设数据导出到文件 `/path/to/output.sql`，那么我们可以使用以下命令将数据导入 GreptimeDB： + +```bash +mysql -h127.0.0.1 -P4002 -ugreptime_user -p -e "source /path/to/output.sql" +``` + +替换 `-h`、`-P` 和 `-u` 参数为你的 GreptimeDB 服务的值。`source` 命令用于执行 `/path/to/output.sql` 文件中的 SQL +命令。若需要进行 debug，添加 `-vvv` 以查看详细的执行结果。 + +总结一下，数据迁移步骤如下图所示： + +![migrate mysql data steps](/migration-mysql.jpg) + +数据迁移完成后，你可以停止向 MySQL 写入数据，并继续使用 GreptimeDB！ diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-postgresql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-postgresql.md new file mode 100644 index 000000000..dbe1c6d00 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-postgresql.md @@ -0,0 +1,111 @@ +--- +description: 指导用户从 PostgreSQL 迁移到 GreptimeDB，包括创建数据库和表、双写策略、数据导出和导入等步骤。 +--- + +# 从 PostgreSQL 迁移 + +本文档将指引您完成从 PostgreSQL 迁移到 GreptimeDB。 + +## 在开始迁移之前 + +请注意，尽管 GreptimeDB 支持 PostgreSQL 的协议，并不意味着 GreptimeDB 实现了 PostgreSQL +的所有功能。你可以参考 "[ANSI 兼容性](/reference/sql/compatibility.md)" 查看在 GreptimeDB 中使用 SQL 的约束。 + +## 迁移步骤 + +### 在 GreptimeDB 中创建数据库和表 + +在从 PostgreSQL 迁移数据之前，你首先需要在 GreptimeDB 中创建相应的数据库和表。 +由于 GreptimeDB 有自己的 SQL 语法用于创建表，因此你不能直接重用 PostgreSQL 生成的建表 SQL。 + +当你为 GreptimeDB 编写创建表的 SQL 时，首先请了解其“[数据模型](/user-guide/concepts/data-model.md)”。然后，在创建表的 +SQL 中请考虑以下几点： + +1. 由于 time index 列在表创建后无法更改，所以你需要仔细选择 time index + 列。时间索引最好设置为数据生成时的自然时间戳，因为它提供了查询数据的最直观方式，以及最佳的查询性能。例如，在 IOT + 场景中，你可以使用传感器采集数据时的时间作为 time index；或者在可观测场景中使用事件的发生时间。 +2. 不建议在此迁移过程中另造一个时间戳用作时间索引，例如使用 `DEFAULT current_timestamp()` 创建的新列。也不建议使用具有随机时间戳的列。 +3. 选择合适的 time index 精度也至关重要。和 time index 的选择一样，一旦表创建完毕，time index + 的精度就无法变更了。请根据你的数据集在[这里](/reference/sql/data-types#data-types-compatible-with-mysql-and-postgresql)找到最适合的时间戳类型。 +4. 根据您的查询模式选择最适合的 tag 列。tag 列存储经常被查询的元数据，其中的值是数据源的标签，通常用于描述数据的特征。tag + 列具有索引，所以使用 tag 列的查询具备良好的性能。 + +请参考[CREATE](/reference/sql/create.md) SQL 文档，了解如何选择正确的数据类型以及“ttl”或“compaction”选项等。 + +### 双写 GreptimeDB 和 PostgreSQL + +双写 GreptimeDB 和 PostgreSQL 是迁移过程中防止数据丢失的有效策略。通过使用 PostgreSQL 的客户端库（JDBC + 某个 PostgreSQL +驱动），你可以建立两个客户端实例 —— 一个用于 GreptimeDB，另一个用于 PostgreSQL。有关如何使用 SQL 将数据写入 +GreptimeDB，请参考[写入数据](/user-guide/ingest-data/for-iot/sql.md)部分。 + +若无需保留所有历史数据，你可以双写一段时间以积累业务所需的最新数据，然后停止向 PostgreSQL 写入数据并仅使用 +GreptimeDB。如果需要完整迁移所有历史数据，请按照接下来的步骤操作。 + +### 从 PostgreSQL 导出数据 + +[pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html) 是一个常用的、从 PostgreSQL 导出数据的工具。使用 +pg_dump，我们可以从 PostgreSQL 中导出后续可直接导入到 GreptimeDB 的数据。例如，如果我们想要从 PostgreSQL 的 database +`postgres` 中导出以 `db` 开头的 schema，我们可以使用以下命令： + +```bash +pg_dump -h127.0.0.1 -p5432 -Upostgres -ax --column-inserts -n 'db*' postgres | grep -v "^SE" > /path/to/output.sql +``` + +替换 `-h`、`-p` 和 `-U` 参数为 PostgreSQL 服务的正确值。`-n` 参数用于指定要导出的 schema。数据库 `postgres` 被放在了 `pg_dump` 命令的最后。注意这里我们将 +pg_dump 的输出经过了一个特殊的 `grep` 命令以过滤掉不需要的 `SET` 和 `SELECT` 行。最终输出将写入 `/path/to/output.sql` +文件。 + +`/path/to/output.sql` 文件应该具有如下内容： + +```plaintext +~ ❯ cat /path/to/output.sql + +-- +-- PostgreSQL database dump +-- + +-- Dumped from database version 16.4 (Debian 16.4-1.pgdg120+1) +-- Dumped by pg_dump version 16.4 + + +-- +-- Data for Name: foo; Type: TABLE DATA; Schema: db1; Owner: postgres +-- + +INSERT INTO db1.foo (ts, a) VALUES ('2024-10-31 00:00:00', 1); +INSERT INTO db1.foo (ts, a) VALUES ('2024-10-31 00:00:01', 2); +INSERT INTO db1.foo (ts, a) VALUES ('2024-10-31 00:00:01', 3); +INSERT INTO ... + + +-- +-- Data for Name: foo; Type: TABLE DATA; Schema: db2; Owner: postgres +-- + +INSERT INTO db2.foo (ts, b) VALUES ('2024-10-31 00:00:00', '1'); +INSERT INTO db2.foo (ts, b) VALUES ('2024-10-31 00:00:01', '2'); +INSERT INTO db2.foo (ts, b) VALUES ('2024-10-31 00:00:01', '3'); +INSERT INTO ... + + +-- +-- PostgreSQL database dump complete +-- +``` + +### 将数据导入 GreptimeDB + +”[psql -- PostgreSQL interactive terminal](https://www.postgresql.org/docs/current/app-psql.html)“ 可用于将数据导入 +GreptimeDB。继续上面的示例，假设数据导出到文件 `/path/to/output.sql`，那么我们可以使用以下命令将数据导入 GreptimeDB： + +```bash +psql -h127.0.0.1 -p4003 -d public -f /path/to/output.sql +``` + +替换 `-h` 和 `-p` 参数为你的 GreptimeDB 服务的值。psql 命令中的 `-d` 参数用于指定数据库，该参数不能省略，`-d` 的值 `public` 是 GreptimeDB 默认使用的数据库。你还可以添加 `-a` 以查看详细的执行结果，或使用 `-s` 进入单步执行模式。 + +总结一下，数据迁移步骤如下图所示： + +![migrate postgresql data steps](/migration-postgresql.jpg) + +数据迁移完成后，你可以停止向 PostgreSQL 写入数据，并继续使用 GreptimeDB！ diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-prometheus.md new file mode 100644 index 000000000..4c59bd2a9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-prometheus.md @@ -0,0 +1,29 @@ +--- +description: 介绍从 Prometheus 迁移到 GreptimeDB 的步骤和注意事项。 +--- + +import DocTemplate from '../../db-cloud-shared/migrate/_migrate-from-prometheus.md' + +# 从 Prometheus 迁移 + + + +
+ +有关 Prometheus 将数据写入 GreptimeDB 的配置信息，请参阅 [Remote Write](/user-guide/ingest-data/for-observerbility/prometheus.md#配置-remote-write) 文档。 + +
+ +
+ +有关使用 Prometheus 查询语言在 GreptimeDB 中查询数据的详细信息，请参阅 PromQL 文档中的 [HTTP API](/user-guide/query-data/promql.md#prometheus-的-http-api) 部分。 + +
+ +
+ +要在 Grafana 中将 GreptimeDB 添加为 Prometheus 数据源，请参阅 [Grafana](/user-guide/integrations/grafana#prometheus-数据源) 的集成文档。 + +
+ + \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/overview.md new file mode 100644 index 000000000..f56b41fa3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/overview.md @@ -0,0 +1,73 @@ +--- +description: 概述了 GreptimeDB 的功能和特点，并通过 SQL 查询示例展示了其强大的数据处理能力。 +--- + +# 概述 + +欢迎使用 GreptimeDB 用户指南。 + +GreptimeDB 是用于指标、事件和日志的统一时间序列数据库， +可提供从边缘到云的任何规模的实时洞察。 +本指南将帮助你探索 GreptimeDB 的每个强大功能。 + +## SQL 查询示例 + +让我们从一个 SQL 查询示例开始。 + +为了监控特定指标的性能和可靠性， +工程师通常定期查询并分析一段时间内的数据。 +在分析过程中通常涉及到 JOIN 两个数据源， +但如下方的查询在之前是不可能的， +而现在使用 GreptimeDB 就可以做到： + +```sql +SELECT + host, + approx_percentile_cont(latency, 0.95) RANGE '15s' as p95_latency, + count(error) RANGE '15s' as num_errors, +FROM + metrics INNER JOIN logs on metrics.host = logs.host +WHERE + time > now() - INTERVAL '1 hour' AND + matches(path, '/api/v1/avatar') +ALIGN '5s' BY (host) FILL PREV +``` + +该查询分析了过去一小时内特定 API 路径 (`/api/v1/avatar`) 的性能和错误。 +它计算了每个 15 秒间隔内的第 95 百分位延迟和错误数量，并将结果对齐到每个 5 秒间隔以保持连续性和可读性。 + +逐步解析该查询： + +1. SELECT 子句： + - `host`：选择 host 字段。 + - `approx_percentile_cont(latency, 0.95) RANGE '15s' as p95_latency`：计算 15 秒范围内的第 95 百分位延迟，并将其标记为 p95_latency。 + - `count(error) RANGE '15s' as num_errors`：计算 15 秒范围内的错误数量，并将其标记为 num_errors。 +2. FROM 子句： + - `metrics INNER JOIN logs on metrics.host = logs.host`：在 host 字段上将 metrics 和 logs 表进行连接。 +3. WHERE 子句： + - `time > now() - INTERVAL '1 hour'`：筛选出过去一小时内的记录。 + - `matches(path, '/api/v1/avatar')`：筛选出特定 API 路径 `/api/v1/avatar` 的记录。 +4. ALIGN 子句： + - `ALIGN '5s' BY (host) FILL PREV`：将结果对齐到每 5 秒，并使用前一个非空值填充缺失值。 + +接下来解析一下该查询示例展示的 GreptimeDB 关键功能： + +- **统一存储：** GreptimeDB 是支持同时存储和分析指标及[日志](/user-guide/logs/overview.md)的时序数据库。简化的架构和数据一致性增强了分析和解决问题的能力，并可节省成本且提高系统性能。 +- **独特的数据模型：** 独特的[数据模型](/user-guide/concepts/data-model.md)搭配时间索引和全文索引，大大提升了查询性能，并在超大数据集上也经受住了考验。它不仅支持[数据指标的插入](/user-guide/ingest-data/overview.md)和[查询](/user-guide/query-data/overview.md)，也提供了非常友好的方式便于日志的[写入](/user-guide/logs/write-logs.md)和[查询](/user-guide/logs/query-logs.md)，以及[向量类型数据](/user-guide/vectors/vector-type.md)的处理。 +- **范围查询：** GreptimeDB 支持[范围查询](/user-guide/query-data/sql.md#aggregate-data-by-time-window)来计算一段时间内的[表达式](/reference/sql/functions/overview.md)，从而了解指标趋势。你还可以[持续聚合](/user-guide/continuous-aggregation/overview.md)数据以进行进一步分析。 +- **SQL 和多种协议：** GreptimeDB 使用 SQL 作为主要查询语言，并支持[多种协议](/user-guide/protocols/overview.md)，大大降低了学习曲线和接入成本。你可以轻松从 Prometheus 或 [Influxdb 迁移](/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md)至 GreptimeDB，或者从 0 接入 GreptimeDB。 +- **JOIN 操作：** GreptimeDB 的时间序列表的数据模型，使其具备了支持[JOIN](/reference/sql/join.md)数据指标和日志的能力。 + +了解了这些功能后，你现在可以直接探索感兴趣的功能，或按顺序继续阅读下一步骤。 + +## 下一步 + +* [概念](./concepts/overview.md) +* [迁移到 GreptimeDB](./migrate-to-greptimedb/migrate-from-influxdb.md) +* [数据写入](./ingest-data/overview.md) +* [数据查询](./query-data/overview.md) +* [数据管理](./manage-data/overview.md) +* [集成](./integrations/overview.md) +* [协议](./protocols/overview.md) +* [持续聚合](./continuous-aggregation/overview.md) +* [运维操作](./administration/overview.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/grpc.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/grpc.md new file mode 100644 index 000000000..232b3eec6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/grpc.md @@ -0,0 +1,5 @@ +# gRPC + +GreptimeDB 提供了 [gRPC SDK](/user-guide/ingest-data/for-iot/grpc-sdks/overview.md)，用于高效和高性能的数据摄入。 + +如果没有适用于你的编程语言的 SDK，你可以按照贡献者指南[创建自己的 SDK](/contributor-guide/how-to/how-to-write-sdk.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/http.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/http.md new file mode 100644 index 000000000..b2c39f6b7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/http.md @@ -0,0 +1,552 @@ +--- +description: 介绍 GreptimeDB 提供的 HTTP API 用于与数据库进行交互。 +--- + +# HTTP API + +GreptimeDB 提供了 HTTP API 用于与数据库进行交互。如需查看完整的 API 端点列表，请查看 [HTTP Endpoints](/reference/http-endpoints.md)。 + +## Base URL + +API Base URL 是 `http(s)://:/`。 + +- 对于在本地机器上运行的 GreptimeDB 实例，Base URL 是 `http://localhost:4000/`，默认端口配置为 `4000`。你可以在[配置文件](/user-guide/deployments/configuration#protocol-options)中更改服务的 host 和 port。 +- 对于 GreptimeCloud，Base URL 是 `https:///`。你可以在 GreptimeCloud 控制台的 "Connection Information" 中找到 host。 + +在以下内容中，我们使用 `http://{{API-host}}/` 作为 Base URL 来演示 API。 + +## 通用 Headers + +### 鉴权 + +GreptimeDB 支持 HTTP API 中内置的 `Basic` 鉴权机制。要设置鉴权，请按照以下步骤操作： + +1. 使用 `` 格式和 `Base64` 算法对用户名和密码进行编码。 +2. 使用 `Authorization : Basic ` 格式将编码后的凭据附加到 HTTP 请求头中。 + +以下是一个示例。如果要使用用户名 `greptime_user` 和密码 `greptime_pwd` 连接到 GreptimeDB，请使用以下命令： + +```shell +curl -X POST \ +-H 'Authorization: Basic Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=' \ +-H 'Content-Type: application/x-www-form-urlencoded' \ +-d 'sql=show tables' \ +http://localhost:4000/v1/sql +``` + +在此示例中，`Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=` 表示 `greptime_user:greptime_pwd` 的 Base64 编码值。请确保用自己配置的用户名和密码替换它，并使用 Base64 进行编码。 + +:::tip 注意 +InfluxDB 使用自己的鉴权格式，请参阅 [InfluxDB](./influxdb-line-protocol.md) 获取详细信息。 +::: + +### 时区 + +GreptimeDB 支持 HTTP 请求中的 `X-Greptime-Timezone` 头部。 +它用于为当前 SQL 查询指定时区。 + +例如，以下请求使用时区 `+1:00` 进行查询： + +```bash +curl -X POST \ +-H 'X-Greptime-Timezone: +1:00' \ +-H 'Content-Type: application/x-www-form-urlencoded' \ +-d 'sql=SHOW VARIABLES time_zone;' \ +http://localhost:4000/v1/sql +``` + +结果为： + +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "TIME_ZONE", + "data_type": "String" + } + ] + }, + "rows": [ + [ + "+01:00" + ] + ] + } + } + ], + "execution_time_ms": 27 +} +``` + +有关时区如何影响数据的写入和查询，请参考[写入数据](/user-guide/ingest-data/for-iot/sql.md#time-zone)和[查询数据](/user-guide/query-data/sql.md#time-zone)部分中的 SQL 文档。 + +### 请求超时设置 + +GreptimeDB 支持在 HTTP 请求中使用 `X-Greptime-Timeout` 请求头，用于指定数据库服务器中运行的请求超时时间。 + +例如，以下请求为查询设置了 `120s` 的超时时间： + +```bash +curl -X POST \ +-H 'X-Greptime-Timeout: 120s' \ +-H 'Content-Type: application/x-www-form-urlencoded' \ +-d 'sql=show tables' \ +http://localhost:4000/v1/sql +``` + +## Admin APIs + +:::tip 注意 +这些 API 在 GreptimeCloud 中无法使用。 +::: + +### 检查数据库健康状态 + +你可以使用 `/health` 端点检查 GreptimeDB 服务器的健康状况。 +有关更多信息，请参阅[检查数据库健康状态](/getting-started/installation/overview#检查数据库健康状态)。 + +### 检查数据库状态 + +你可以使用 `/status` 端点检查 GreptimeDB 服务器的状态。 + +```shell +curl http://{{API-host}}/status +``` + +例如： + +```shell +curl http://localhost:4000/status +``` + +输出包含数据库版本和源代码信息，类似如下： + +```json +{ + "source_time": "2024-11-08T06:34:49Z", + "commit": "0e0c4faf0d784f25fed8f26e7000f1f869c88587", + "branch": "main", + "rustc_version": "rustc 1.84.0-nightly (e92993dbb 2024-10-18)", + "hostname": "local", + "version": "0.9.5" +} +``` + +### 获取 GreptimeDB 服务器配置 + +你可以使用 `/config` 端点获取 GreptimeDB 服务器的 [TOML 配置](/user-guide/deployments/configuration.md#configuration-file-options)。 + +```shell +curl http://{{API-host}}/config +``` + +例如： + +```shell +curl http://localhost:4000/config +``` + +输出包含 GreptimeDB 服务器的配置信息。 + +```toml +mode = "standalone" +enable_telemetry = true +user_provider = "static_user_provider:file:user" +init_regions_in_background = false +init_regions_parallelism = 16 + +[http] +addr = "127.0.0.1:4000" +timeout = "30s" +body_limit = "64MiB" +is_strict_mode = false + +# ... +``` + +## POST SQL 语句 + +要通过 HTTP API 向 GreptimeDB 服务器提交 SQL 语句，请使用以下格式： + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authentication}}' \ + -H 'X-Greptime-Timeout: {{time precision}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql={{SQL-statement}}' \ +http://{{API-host}}/v1/sql +``` + +### Headers + +- [`Authorization`](#鉴权) +- [`X-Greptime-Timeout`](#请求超时设置) +- `Content-Type`: `application/x-www-form-urlencoded`. +- `X-Greptime-Timezone`: 当前 SQL 查询的时区。可选。请参阅[时区](#时区)。 + +### Query string parameters + +- `db`: 数据库名称。可选。如果未提供，将使用默认数据库 `public`。 +- `format`: 输出格式。可选。 + 除了默认的 JSON 格式外，HTTP API 还允许你通过提供 `format` 查询参数来自定义输出格式，值如下： + - `influxdb_v1`: [influxdb 查询 + API](https://docs.influxdata.com/influxdb/v1/tools/api/#query-http-endpoint) + 兼容格式。附加参数： + - `epoch`: `[ns,u,µ,ms,s,m,h]`，返回指定精度的时间戳 + - `csv`: 逗号分隔值输出 + - `arrow`: [Arrow IPC + 格式](https://arrow.apache.org/docs/python/feather.html)。附加参数： + - `compression`: `zstd` 或 `lz4`，默认：无压缩 + - `table`: 控制台输出的 ASCII 表格格式 + +### Body + +- `sql`: SQL 语句。必填。 + +### 响应 + +响应是一个 JSON 对象，包含以下字段： + +- `output`: SQL 执行结果，请参阅下面的示例以了解详细信息。 +- `execution_time_ms`: 语句的执行时间（毫秒）。 + +### 示例 + +#### `INSERT` 语句 + +例如，要向数据库 `public` 的 `monitor` 表中插入数据，请使用以下命令： + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql=INSERT INTO monitor VALUES ("127.0.0.1", 1667446797450, 0.1, 0.4), ("127.0.0.2", 1667446798450, 0.2, 0.3), ("127.0.0.1", 1667446798450, 0.5, 0.2)' \ + http://localhost:4000/v1/sql?db=public +``` + +Response 包含受影响的行数： + +```shell +{"output":[{"affectedrows":3}],"execution_time_ms":11} +``` + +#### `SELECT` 语句 + +你还可以使用 HTTP API 执行其他 SQL 语句。例如，从 `monitor` 表中查询数据： + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "sql=SELECT * FROM monitor" \ + http://localhost:4000/v1/sql?db=public +``` + +Response 包含 JSON 格式的查询数据： + +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "host", + "data_type": "String" + }, + { + "name": "ts", + "data_type": "TimestampMillisecond" + }, + { + "name": "cpu", + "data_type": "Float64" + }, + { + "name": "memory", + "data_type": "Float64" + } + ] + }, + "rows": [ + [ + "127.0.0.1", + 1720728000000, + 0.5, + 0.1 + ] + ], + "total_rows": 1 + } + } + ], + "execution_time_ms": 7 +} +``` + +Response 包含以下字段： + +- `output`: 执行结果。 + - `records`: 查询结果。 + - `schema`: 结果的 schema，包括每列的 schema。 + - `rows`: 查询结果的行，每行是一个包含 schema 中对应列值的数组。 +- `execution_time_ms`: 语句的执行时间（毫秒）。 + +#### 时区 + +GreptimeDB 支持 HTTP 请求中的 `X-Greptime-Timezone` header。 +它用于为当前 SQL 查询指定时区。 + +例如，以下请求使用时区 `+1:00` 进行查询： + +```bash +curl -X POST \ +-H 'X-Greptime-Timezone: +1:00' \ +-H 'Content-Type: application/x-www-form-urlencoded' \ +-d 'sql=SHOW VARIABLES time_zone;' \ +http://localhost:4000/v1/sql +``` + +查询后的结果为： + +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "TIME_ZONE", + "data_type": "String" + } + ] + }, + "rows": [ + [ + "+01:00" + ] + ] + } + } + ], + "execution_time_ms": 27 +} +``` + +有关时区如何影响数据的写入和查询，请参考[写入数据](/user-guide/ingest-data/for-iot/sql.md#time-zone)和[查询数据](/user-guide/query-data/sql.md#时区)部分中的 SQL 文档。 + +#### 使用 `table` 格式输出查询数据 + +你可以在查询字符串参数中使用 `table` 格式，以 ASCII 表格格式获取输出。 + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "sql=SELECT * FROM monitor" \ + http://localhost:4000/v1/sql?db=public&format=table +``` + +输出 + +``` +┌─host────────┬─ts────────────┬─cpu─┬─memory─┐ +│ "127.0.0.1" │ 1667446797450 │ 0.1 │ 0.4 │ +│ "127.0.0.1" │ 1667446798450 │ 0.5 │ 0.2 │ +│ "127.0.0.2" │ 1667446798450 │ 0.2 │ 0.3 │ +└─────────────┴───────────────┴─────┴────────┘ +``` + +#### 使用 `influxdb_v1` 格式输出查询数据 + +你可以在查询字符串参数中使用 `influxdb_v1` 格式，以 InfluxDB 查询 API 兼容格式获取输出。 + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "sql=SELECT * FROM monitor" \ + http://localhost:4000/v1/sql?db=public&format=influxdb_v1&epoch=ms +``` + +```json +{ + "results": [ + { + "statement_id": 0, + "series": [ + { + "name": "", + "columns": [ + "host", + "cpu", + "memory", + "ts" + ], + "values": [ + [ + ["127.0.0.1", 0.1, 0.4, 1667446797450], + ["127.0.0.1", 0.5, 0.2, 1667446798450], + ["127.0.0.2", 0.2, 0.3, 1667446798450] + ] + ] + } + ] + } + ], + "execution_time_ms": 2 +} +``` + +## POST PromQL 查询 + +### API 返回 Prometheus 查询结果格式 + +GreptimeDB 兼容 Prometheus 查询语言 (PromQL)，可以用于查询 GreptimeDB 中的数据。 +有关所有兼容的 API，请参阅 [Prometheus 查询语言](/user-guide/query-data/promql#prometheus-http-api) 文档。 + +### API 返回 GreptimeDB JSON 格式 + +GreptimeDB 同样暴露了一个自己的 HTTP API 用于 PromQL 查询，即在当前的 API 路径 `/v1` 的后方拼接 `/promql`。 +该接口的返回值是 GreptimeDB 的 JSON 格式，而不是 Prometheus 的格式。 +如下示例： + +```shell +curl -X GET \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -G \ + --data-urlencode 'db=public' \ + --data-urlencode 'query=avg(system_metrics{idc="idc_a"})' \ + --data-urlencode 'start=1667446797' \ + --data-urlencode 'end=1667446799' \ + --data-urlencode 'step=1s' \ + http://localhost:4000/v1/promql +``` + +接口中的参数和 Prometheus' HTTP API 的 [`range_query`](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) 接口相似： + +- `db=`：在使用 GreptimeDB 进行鉴权操作时必填。 +- `query=`：必填。Prometheus 表达式查询字符串。 +- `start=`：必填。开始时间戳，包含在内。它用于设置 `TIME INDEX` 列中的时间范围。 +- `end=`：必填。结束时间戳，包含在内。它用于设置 `TIME INDEX` 列中的时间范围。 +- `step=`：必填。查询步长，可以使用持续时间格式或秒数的浮点数。 + +以下是每种参数的类型的示例： + +- rfc3339 + - `2015-07-01T20:11:00Z` (default to seconds resolution) + - `2015-07-01T20:11:00.781Z` (with milliseconds resolution) + - `2015-07-02T04:11:00+08:00` (with timezone offset) +- unix timestamp + - `1435781460` (default to seconds resolution) + - `1435781460.781` (with milliseconds resolution) +- duration + - `1h` (1 hour) + - `5d1m` (5 days and 1 minute) + - `2` (2 seconds) + - `2s` (also 2 seconds) + +结果格式与 [Post SQL 语句](#post-sql-语句)中描述的 `/sql` 接口相同。 + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "ts", + "data_type": "TimestampMillisecond" + }, + { + "name": "AVG(system_metrics.cpu_util)", + "data_type": "Float64" + }, + { + "name": "AVG(system_metrics.memory_util)", + "data_type": "Float64" + }, + { + "name": "AVG(system_metrics.disk_util)", + "data_type": "Float64" + } + ] + }, + "rows": [ + [ + 1667446798000, + 80.1, + 70.3, + 90 + ], + [ + 1667446799000, + 80.1, + 70.3, + 90 + ] + ] + } + } + ], + "execution_time_ms": 5 +} +``` + +## Post Influxdb line protocol 数据 + + + + + +```shell +curl -X POST \ + -H 'Authorization: token :' \ + -d '{{Influxdb-line-protocol-data}}' \ + http://{{API-host}}/v1/influxdb/api/v2/write?precision={{time-precision}} +``` + + + + + +```shell +curl -X POST \ + -d '{{Influxdb-line-protocol-data}}' \ + http://{{API-host}}/v1/influxdb/api/v1/write?u={{username}}&p={{password}}&precision={{time-precision}} +``` + + + + +### Headers + +- `Authorization`: **与其他 API 不同**，InfluxDB 行协议 API 使用 InfluxDB 鉴权格式。对于 V2 协议，Authorization 是 `token :`。 + +### Query string parameters + +- `u`: 用户名。可选。它是 V1 的鉴权用户名。 +- `p`: 密码。可选。它是 V1 的鉴权密码。 +- `db`: 数据库名称。可选。默认值是 `public`。 +- `precision`: 定义请求体中提供的时间戳的精度。请参考用户指南中的 [InfluxDB 行协议](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md)文档。 + +### Body + +InfluxDB 行协议数据点。请参考 [InfluxDB 行协议](https://docs.influxdata.com/influxdb/v1/write_protocols/line_protocol_tutorial/#syntax) 文档。 + +### 示例 + +请参考用户指南中的 [InfluxDB 行协议](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md)。 + +## 管理 Pipeline 的 API + +在将日志写入 GreptimeDB 时，你可以使用 HTTP API 来管理 Pipeline。 +请参考 [管理 Pipeline](/user-guide/logs/manage-pipelines.md) 文档。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/influxdb-line-protocol.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/influxdb-line-protocol.md new file mode 100644 index 000000000..8568d54b2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/influxdb-line-protocol.md @@ -0,0 +1,36 @@ +--- +description: 介绍如何使用 InfluxDB Line Protocol 向 GreptimeDB 写入数据。 +--- + +# InfluxDB Line Protocol + +## 写入数据 + +请参考[写入数据](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md)文档来了解如何使用 InfluxDB Line Protocol 向 GreptimeDB 写入数据。 + +## PING + +GreptimeDB 同样支持 InfluxDB 的 `ping` 和 `health` API。 + +使用 `curl` 请求 `ping` API： + +```shell +curl -i "127.0.0.1:4000/v1/influxdb/ping" +``` + +```shell +HTTP/1.1 204 No Content +date: Wed, 22 Feb 2023 02:29:44 GMT +``` + +Use `curl` to request `health` API. + +```shell +curl -i "127.0.0.1:4000/v1/influxdb/health" +``` + +```shell +HTTP/1.1 200 OK +content-length: 0 +date: Wed, 22 Feb 2023 02:30:46 GMT +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/mysql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/mysql.md new file mode 100644 index 000000000..2364542bd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/mysql.md @@ -0,0 +1,77 @@ +--- +description: 介绍如何通过 MySQL 协议连接和使用 GreptimeDB。 +--- + +# MySQL + +## 连接数据库 + +你可以通过 MySQL 连接到 GreptimeDB，端口为 `4002`。 + +```shell +mysql -h -P 4002 -u -p +``` + +- 请参考[鉴权认证](/user-guide/deployments/authentication/overview.md) 来设置 GreptimeDB 的用户名和密码。 +- 如果你想使用其他端口连接 MySQL，请参考配置文档中的[协议选项](/user-guide/deployments/configuration.md#协议选项)。 + + +## 管理表 + +请参考[表管理](/user-guide/administration/manage-data/basic-table-operations.md)。 + +## 写入数据 + +请参考[写入数据](/user-guide/ingest-data/for-iot/sql.md). + +## 查询数据 + +请参考[查询数据](/user-guide/query-data/sql.md). + +## 时区 + +GreptimeDB 的 MySQL 协议接口遵循原始 MySQL 服务器的 [时区处理方式](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html)。 + +默认情况下，MySQL 使用服务器的时区来处理时间戳。要覆盖这一行为，可以使用 SQL 语句 `SET time_zone = '';` 来为当前会话设置 `time_zone` 变量。`time_zone` 的值可以是： + +- 服务器的时区：`SYSTEM`。 +- UTC 的偏移量，例如 `+08:00`。 +- 任何时区的命名，例如 `Europe/Berlin`。 + +一些 MySQL 客户端，例如 Grafana 的 MySQL 数据源，允许你为当前会话设置时区。想要知道当前设定的时区，可以通过 SQL 语句 `SELECT @@time_zone;` 来查询。 + +你可以使用 `SELECT` 来查看当前的时区设置。例如： + +```sql +SELECT @@system_time_zone, @@time_zone; +``` + +结果显示系统时区和会话时区都设置为 `UTC`： + +```SQL ++--------------------+-------------+ +| @@system_time_zone | @@time_zone | ++--------------------+-------------+ +| UTC | UTC | ++--------------------+-------------+ +``` + +将会话时区更改为 `+1:00`： + +```SQL +SET time_zone = '+1:00' +``` + +你可以看到系统时区和会话时区之间的差异： + +```SQL +SELECT @@system_time_zone, @@time_zone; + ++--------------------+-------------+ +| @@system_time_zone | @@time_zone | ++--------------------+-------------+ +| UTC | +01:00 | ++--------------------+-------------+ +``` + +有关时区如何影响数据的插入和查询，请参考 [写入数据](/user-guide/ingest-data/for-iot/sql.md#时区) 和 [查询数据](/user-guide/query-data/sql.md#时区) 中的 SQL 文档。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/opentelemetry.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/opentelemetry.md new file mode 100644 index 000000000..c1b83eb67 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/opentelemetry.md @@ -0,0 +1,4 @@ +# OpenTelemetry (OTLP) + +GreptimeDB 可以通过 [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) 协议写入 OpenTelemetry 指标。 +请参考[使用 OpenTelemetry 写入数据](/user-guide/ingest-data/for-observerbility/opentelemetry.md)文档获取详细信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/opentsdb.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/opentsdb.md new file mode 100644 index 000000000..e9ac22103 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/opentsdb.md @@ -0,0 +1,3 @@ +# OpenTSDB + +请参考[使用 OpenTSDB 写入数据](/user-guide/ingest-data/for-iot/opentsdb.md)获取详细信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/overview.md new file mode 100644 index 000000000..b63273576 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/overview.md @@ -0,0 +1,9 @@ +# 概述 + +- [InfluxDB Line Protocol](./influxdb-line-protocol.md) +- [OpenTelemetry (OTLP)](./opentelemetry.md) +- [MySQL](./mysql.md) +- [PostgreSQL](./postgresql.md) +- [HTTP API](./http.md) +- [gRPC](./grpc.md) +- [OpenTSDB](./opentsdb.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/postgresql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/postgresql.md new file mode 100644 index 000000000..8581db5da --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/protocols/postgresql.md @@ -0,0 +1,160 @@ +--- +description: 介绍如何通过 PostgreSQL 协议连接和使用 GreptimeDB。 +--- + +# PostgreSQL + +## 连接数据库 + +你可以通过端口 `4003` 使用 PostgreSQL 连接到 GreptimeDB。 +只需在命令中添加 `-U` 参数，后跟你的用户名和密码。以下是一个示例： + +```shell +psql -h -p 4003 -U -d public +``` + +- 请参考[鉴权认证](/user-guide/deployments/authentication/overview.md) 来设置 GreptimeDB 的用户名和密码。 +- 如果你想使用其他端口连接 PostgreSQL，请参考配置文档中的[协议选项](/user-guide/deployments/configuration.md#协议选项)。 + +## 管理表 + +请参考[管理表](/user-guide/administration/manage-data/basic-table-operations.md)。 + +## 写入数据 + +请参考[写入数据](/user-guide/ingest-data/for-iot/sql.md). + +## 读取数据 + +请参考 [读取数据](../query-data/sql.md). + +## 时区 + +GreptimeDB 的 PostgreSQL 协议遵循原始 PostgreSQL 的 [时区处理方式](https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-TIMEZONES)。 + +默认情况下，PostgreSQL 使用服务器的时区来处理时间戳。 +你可以使用 SQL 语句 `SET TIMEZONE TO '';` 为当前会话设置 `time_zone` 变量来覆盖服务器时区。 +`time_zone` 的值可以是： + +- 时区的全称，例如 `America/New_York`。 +- 时区的缩写，例如 `PST`。 +- UTC 的偏移量，例如 `+08:00`。 + +你可以使用 `SHOW` 来查看当前的时区设置。例如： + +```sql +SHOW VARIABLES time_zone; +``` + +```sql + TIME_ZONE +----------- + UTC +``` + +将会话时区更改为 `+1:00`： + +```SQL +SET TIMEZONE TO '+1:00' +``` + +有关时区如何影响数据的插入和查询，请参考[写入数据](/user-guide/ingest-data/for-iot/sql.md#时区)和[查询数据](/user-guide/query-data/sql.md#时区)中的 SQL 文档。 + +## 外部数据 + +利用 Postgres 的 [FDW 扩 +展](https://www.postgresql.org/docs/current/postgres-fdw.html)， GreptimeDB 可以 +被配置为 Postgres 的外部数据服务。 这使得我们可以用 Postgres 服务器上无缝地查询 +GreptimeDB 里的时序数据，并且可以利用 join 查询同时关联两边的数据。 + +举个例子，类似设备信息类的物联网元数据，通常存储在 Postgres 这样的关系型数据库中。 +现在我们可以利用这个功能，先在 Postgres 利用关系查询过滤出满足条件的设备 ID，然 +后直接关联的 GreptimeDB 承载的外部表上查询设备的时序数据。 + +### 配置 + +首先要确保 GreptimeDB 打开了 Postgres 协议，并且她可以被 Postgres 服务器访问到。 + +在 Postgres 上开启 fdw 扩展。 + +```sql +CREATE EXTENSION postgres_fdw; +``` + +将 GreptimeDB 添加为远程服务器。 + +```sql +CREATE SERVER greptimedb +FOREIGN DATA WRAPPER postgres_fdw +OPTIONS (host 'greptimedb_host', dbname 'public', port '4003'); +``` + +把 Postgres 用户映射到 GreptimeDB 上。这一步是必须步骤。如果你没有在 GreptimeDB +开源版本上启用认证，这里可以填写任意的认证信息。 + +```sql +CREATE USER MAPPING FOR postgres +SERVER greptimedb +OPTIONS (user 'greptime', password '...'); +``` + +在 Postgres 创建与 GreptimeDB 映射的外部表。这一步是为了告知 Postgres 相应表的数 +据结构。注意需要将 GreptimeDB 的数据类型映射到 Postgres 类型上。 + +对于这样的 GreptimeDB 表： + +```sql +CREATE TABLE grpc_latencies ( + ts TIMESTAMP TIME INDEX, + host STRING, + method_name STRING, + latency DOUBLE, + PRIMARY KEY (host, method_name) +) with('append_mode'='true'); + +CREATE TABLE app_logs ( + ts TIMESTAMP TIME INDEX, + host STRING, + api_path STRING FULLTEXT, + log_level STRING, + log STRING FULLTEXT, + PRIMARY KEY (host, log_level) +) with('append_mode'='true'); +``` + +其 Postgres 外部表定义如下： + +```sql +CREATE FOREIGN TABLE ft_grpc_latencies ( + ts TIMESTAMP, + host VARCHAR, + method_name VARCHAR, + latency DOUBLE precision +) +SERVER greptimedb +OPTIONS (table_name 'grpc_latencies'); + +CREATE FOREIGN TABLE ft_app_logs ( + ts TIMESTAMP, + host VARCHAR, + api_path VARCHAR, + log_level VARCHAR, + log VARCHAR +) +SERVER greptimedb +OPTIONS (table_name 'app_logs'); +``` + +至此你可以通过 Postgres 发起查询。并且可以使用一些同时存在在 GreptimeDB 和 +Postgres 上的函数，如 `date_trunc` 等。 + +```sql +SELECT * FROM ft_app_logs ORDER BY ts DESC LIMIT 100; + +SELECT + date_trunc('MINUTE', ts) as t, + host, + avg(latency), + count(latency) +FROM ft_grpc_latencies GROUP BY host, t; +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/api.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/api.md new file mode 100644 index 000000000..8a606ae6c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/api.md @@ -0,0 +1,93 @@ +# API + +## 内置模块和功能 + +我们提供了大量的内置函数供用户使用。下面是一个内置函数的列表。只要在脚本开头写上 `import greptime` 或 `from greptime import *` 就可以调用它们。 + +## 向量函数 + +| Function | Description | +| :--- | :--- | +| `pow(v0, v1)` | Raise a number `v0` to a power of `v1`. | +| `clip(v0, v1, v2)` | Clip all elements in a vector `v0` to a range between vectors `v1` and `v2`. | +| `diff(v0)` | Calculate the difference between adjacent elements in a vector `v0`. | +| `mean(v0)` | Calculate the mean of a vector `v0`. | +| `polyval(v0, v1)` | Evaluate a polynomial `v0` at points `v1`. similar to `numpy.polyval`. | +| `argmax(v0)` | Return the index of the maximum value in a vector `v0`. similar to `numpy.argmax`. | +| `argmin(v0)` | Return the index of the minimum value in a vector `v0`. similar to `numpy.argmin`. | +| `percentile` | Calculate the `q`-th percentile of a vector `v0`. similar to `numpy.percentile`. | +| `scipy_stats_norm_cdf` | Calculate the cumulative distribution function for the normal distribution. similar to `scipy.stats.norm.cdf`. | +| `scipy_stats_norm_pdf` | Calculate the probability density function for the normal distribution. similar to `scipy.stats.norm.pdf`. | + +## 数学函数 + +| Function | Description | +| :--- | :--- | +| `sqrt(v)` | Calculate the square root of a number `v`. | +| `sin(v)` | Calculate the sine of a number `v`. | +| `cos(v)` | Calculate the cosine of a number `v`. | +| `tan(v)` | Calculate the tangent of a number `v`. | +| `asin(v)` | Calculate the arcsine of a number `v`. | +| `acos(v)` | Calculate the arccosine of a number `v`. | +| `atan(v)` | Calculate the arctangent of a number `v`. | +| `floor(v)` | Calculate the floor of a number `v`. | +| `ceil(v)` | Calculate the ceiling of a number `v`. | +| `round(v)` | Calculate the nearest integer of a number `v`. | +| `trunc(v)` | Calculate the truncated integer of a number `v`. | +| `abs(v)` | Calculate the absolute value of a number `v`. | +| `signum(v)` | Calculate the sign(gives 1.0/-1.0) of a number `v`. | +| `exp(v)` | Calculate the exponential of a number `v`. | +| `ln(v)` | Calculate the natural logarithm of a number `v`. | +| `log2(v)` | Calculate the base-2 logarithm of a number `v`. | +| `log10(v)` | Calculate the base-10 logarithm of a number `v`. | + +## 效用函数和聚合函数 + +这些函数是由 `DataFusion` 绑定的。 +| Function | Description | +| :--- | :--- | +| `random(len)` | Generate a random vector with length `len`. | +| `approx_distinct(v0)` | Calculate the approximate number of distinct values in a vector `v0`. | +| `median(v0)` | Calculate the median of a vector `v0`. | +| `approx_percentile_cont(values, percent)` | Calculate the approximate percentile of a vector `values` at a given percentage `percent`. | +| `array_agg(v0)` | Aggregate values into an array. | +| `avg(v0)` | Calculate the average of a vector `v0`. | +| `correlation(v0, v1)` | Calculate the Pearson correlation coefficient of a vector `v0` and a vector `v1`. | +| `count(v0)` | Calculate the count of a vector `v0`. | +| `covariance(v0, v1)` | Calculate the covariance of a vector `v0` and a vector `v1`. | +| `covariance_pop(v0, v1)` | Calculate the population covariance of a vector `v0` and a vector `v1`. | +| `max(v0)` | Calculate the maximum of a vector `v0`. | +| `min(v0)` | Calculate the minimum of a vector `v0`. | +| `stddev(v0)` | Calculate the sample standard deviation of a vector `v0`. | +| `stddev_pop(v0)` | Calculate the population standard deviation of a vector `v0`. | +| `sum(v0)` | Calculate the sum of a vector `v0`. | +| `variance(v0)` | Calculate the sample variance of a vector `v0`. | +| `variance_pop(v0)` | Calculate the population variance of a vector `v0`. | + +## 数据框架的 methods + +| Method | Description | +| --- | --- | +| `select_columns(columns: List[str])` | select columns from DataFrame | +| `select(columns: List[Expr]])` | select columns from DataFrame using `PyExpr` | +| `filter(condition: Expr)` | filter DataFrame using `PyExpr` | +| `aggregate(group_expr: List[Expr], aggr_expr: List[Expr])` | Perform an aggregate query with optional grouping expressions. | +| `limit(skip: int, fetch: Optional[int])` |Limit the number of rows returned from this DataFrame. `skip` - Number of rows to skip before fetch any row; `fetch` - Maximum number of rows to fetch, after skipping skip rows. +| `union(other: DataFrame)` | Union two DataFrame | +| `union_distinct(other: DataFrame)` | Union two DataFrame, but remove duplicate rows | +| `distinct()` | Remove duplicate rows | +| `sort(expr: List[Expr])` | Sort DataFrame by `PyExpr`, Sort the DataFrame by the specified sorting expressions. Any expression can be turned into a sort expression by calling its sort method. | +| `join(right: DataFrame, left_cols: List[str], right_cols: List[str], filter: Optional[Expr])` | Join two DataFrame using the specified columns as join keys. Eight Join Types are supported: `inner`, `left`, `right`, `full`, `leftSemi`, `leftAnti`, `rightSemi`, `rightAnti`. | +| `intersect(other: DataFrame)` | Intersect two DataFrame | +| `except(other: DataFrame)` | Except two DataFrame | +| `collect()` | Collect DataFrame to a list of `PyVector` | + +## Expr 的 methods + +| Method | Description | +| --- | --- | +| `col(name: str)` | Create a `PyExpr` that represents a column | +| `lit(value: Any)` | Create a `PyExpr` that represents a literal value | +| `sort(ascending: bool, null_first: bool)` | Create a `PyExpr` that represents a sort expression | +| comparison operators: `==`, `!=`, `>`, `>=`, `<`, `<=` | Create `PyExpr` from compare two `PyExpr` | +| logical operators: `&`, `\|`, `~` | Create `PyExpr` from logical operation between two `PyExpr` | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/data-types.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/data-types.md new file mode 100644 index 000000000..b4bf41aa0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/data-types.md @@ -0,0 +1,185 @@ +# 数据类型 + +## DataFrame + +DataFrame 表示具有相同命名列的逻辑行集，类似于 [Pandas DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) 或 [Spark DataFrame](https://spark.apache.org/docs/latest/sql-programming-guide.html)。 + +可以从 `sql` 创建一个 DataFrame： + +```python +from greptime import PyDataFrame, col +@copr(returns = ["value"]) +def query_numbers() -> vector[f64]: + df = PyDataFrame.from_sql("select number from numbers") + return df.filter(col('number') <= 5).collect()[0] +``` + +这与 `select number from numbers where number <=5` 相同，但使用了 DataFrame API。 + +事实上，协处理器的 DataFrame API 是 Apache Datafusion [DataFrame API](https://arrow.apache.org/datafusion/user-guide/dataframe.html) 的一个封装器。请参考 [API](api.md) 文档以获得完整的 DataFrame API。 + +## 向量 + +向量是协处理器中的主要数据类型，它是同类值的向量。通常，它是查询结果中提取的一列，但也可以在 Python 脚本中构建它。 + +向量就像编程语言中的数组类型，Apache [Arrow](https://arrow.apache.org/) 中的 `Array` 或 [NumPy](https://numpy.org/doc/stable/reference/arrays.html) 中的 `NDArray`。 + +### 向量类型 + +协处理器引擎支持以下类型的向量： + +| Type | Description | +| -------------- | -------------------------------- | +| `vector[str]` | The string type | +| `vector[bool]` | The boolean type | +| `vector[u8]` | The 8-bit unsigned integer type | +| `vector[u16]` | The 16-bit unsigned integer type | +| `vector[u32]` | The 32-bit unsigned integer type | +| `vector[u64]` | The 64-bit unsigned integer type | +| `vector[i8]` | The 8-bit signed integer type | +| `vector[i16]` | The 16-bit signed integer type | +| `vector[i32]` | The 32-bit signed integer type | +| `vector[i64]` | The 64-bit signed integer type | +| `vector[f32]` | The 32-bit floating point type | +| `vector[f64]` | The 64-bit floating point type | +| `vector[none]` | The any type | + +正如我们在 [Hello, world](./getting-started.md#hello-world-example) 的例子中看到的那样，如果我们想把它作为 SQL UDF 使用，我们可以为协处理器定义返回向量类型。否则，我们可以忽略返回向量类型的声明： + +```python +@coprocessor(returns=['msg']) +def hello() -> vector[str]: + return "hello, GreptimeDB" +``` + +协处理器引擎会根据结果推断出返回向量的类型。但是如果没有声明，除非通过 HTTP API，不然就不能在 SQL 中调用它。 + +### 构建一个向量 + +之前已经展示了在[查询数据](./query-data.md)中通过执行 `@coprocessor` 中的 `sql` 属性从查询结果中提取向量的例子。 + +我们可以从字面意义上创建一个向量： + +```python +@copr(returns=["value"]) +def answer() -> vector[i64]: + return 42 +``` + +结果 `42` 将被包装成 `vector[i64]` 的一个元素的向量。 + +```sql +mysql> select answer(); ++----------+ +| answer() | ++----------+ +| 42 | ++----------+ +1 row in set (0.01 sec) +``` + +我们可以从一个 Python 列表中创建一个向量： + +```python +from greptime import vector + +@copr(returns=["value"]) +def answer() -> vector[i64]: + return vector([42, 43, 44]) +``` + +`greptime` 是一个内置模块，请参考 [API](./api.md) 文档。 + +```sql +mysql> select answer(); ++----------+ +| answer() | ++----------+ +| 42 | +| 43 | +| 44 | ++----------+ +3 rows in set (0.02 sec) +``` + +事实上，`vector` 函数可以从 Python 的任何可迭代对象中创建一个向量。但是它要求所有的元素类型必须相同，而且它选择第一个元素的类型作为它的向量类型。 + +### 向量操作 + +向量支持很多操作： + +1. 支持基本的算术运算，包括 `+`、`-`、`*`、`/`。 +2. 支持基本的逻辑运算，包括 `&`, `|`, `~`。 +3. 也支持基本的比较操作，包括 `>`, `<`, `>=`, `<=`, `==`, `！=`。 + +> 注意：这里我们覆盖了 bitwise 和 `&`，bitwise 或 `|`，bitwise 不是 `~` 的逻辑运算符，因为 Python 不支持逻辑运算符的覆盖(不能覆盖 `and` `or` `not`)。 +> [PEP335](https://peps.python.org/pep-0335/) 提出了一个建议，最终被拒绝。但是位操作符的优先级比比较操作符高，所以记得使用一对小括号来确保结果是想要的。 +> 即如果想过滤一个在 0 和 100 之间的向量，应该使用 `(vector[i32] >= 0) & (vector[i32] <= 100)` 而不是 `vector[i32] >= 0 & vector[i32] <= 100`。后者将被评估为 `vector[i32] >= (0 & vector[i32]) <= 100`。 + +例如，可以将两个向量相加： + +```python +@copr(args=["n1", "n2"], + returns=["value"], + sql="select number as n1,number as n2 from numbers limit 5") +def add_vectors(n1, n2) -> vector[i32]: + return n1 + n2 +``` + +或者用 Numpy 的方式对一个 bool 数组做比较： + +```python +from greptime import vector + +@copr(returns=["value"]) +def compare() -> vector[bool]: + # This returns a vector([False, False, True]) + return vector([1.0, 2.0, 3.0]) > 2.0 +``` + +并使用 bool 数组的索引： + +```python +from greptime import vector + +@copr(returns=["value"]) +def boolean_array() -> vector[f64]: + v = vector([1.0, 2.0, 3.0]) + # This returns a vector([2.0]) + return v[(v > 1) & (v< 3)] +``` + +也支持两个向量之间的比较： + +```python +from greptime import vector + +@copr(returns=["value"]) +def compare_vectors() -> vector[bool]: + # This returns a vector([False, False, True]) + return vector([1.0, 2.0, 3.0]) > vector([1.0, 2.0, 2.0]) +``` + +使用一个有索引的 bool 数组从一个向量中选择元素： + +```python +from greptime import vector + +@copr(returns=["value"]) +def select_elements() -> (vector[f64]): + a = vector([1.0, 2.0, 3.0]) + # This returns a vector([2.0, 3.0]) + return a[a>=2.0] +``` + +当然，我们可以使用列表理解法来构造一个新的向量： + +```python +from greptime import vector + +@copr(returns=["value"]) +def list_comprehension() -> (vector[f64]): + a = vector([1.0, 2.0, 3.0]) + # This returns a vector([3.0, 4.0]) + return [x+1 for x in a if a >= 2.0] +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/define-function.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/define-function.md new file mode 100644 index 000000000..075f449f0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/define-function.md @@ -0,0 +1,270 @@ +# 定义函数 + +## 协处理器注释 + +`@coprocessor` 注释指定一个 python 函数作为 GreptimeDB 的协处理器，并为其设置一些属性。 + +该引擎允许一个且仅有一个用 `@coprocessor` 注释的函数，不能在一个脚本中拥有一个以上的协处理器。 + +| Parameter | Description | Example | +| --- | --- | --- | +| `sql` | Optional. The SQL statement that the coprocessor function will query data from the database and assign them to input `args`. | `@copr(sql="select * from cpu", ..)` | +| `args` | Optional. The argument names that the coprocessor function will be taken as input, which are the columns in query results by `sql`. | `@copr(args=["cpu", "mem"], ..)` | +| `returns` | The column names that the coprocessor function will return. The Coprocessor Engine uses it to generate the output schema. | `@copr(returns=["add", "sub", "mul", "div"], ..)` | +| `backend` | Optional. The coprocessor function will run on available engines like `rspy` and `pyo3`, which are associated with `RustPython` Backend and `CPython` Backend respectively. The default engine is set to `rspy`. | `@copr(backend="rspy", ..)` | + +`sql` 和 `args` 都是可选的；它们必须都可用，或都不可用，并通常在后查询处理中被使用，详情请阅读下文。 + +`returns` 是每个 coprocessor 都需要的，因为输出模式必然存在。 + + 因为 `RustPython` 不能支持 C 语言 API，当尝试使用 `pyo3` 后端来使用只支持 C 语言 API 的第三方 python 库时，例如 `numpy`，`pandas` 等，`backend` 则是必要的。 + +## 协处理器函数的输入 + +该协处理器也接受之前已经看到的参数： + +```python +@coprocessor(args=["number"], sql="select number from numbers limit 20", returns=["value"]) +def normalize(v) -> vector[i64]: + return [normalize0(x) for x in v] +``` + +参数 `v` 是执行 `sql` 返回的查询结果中的 `number` 列（由 `args` 属性指定）。 + +当然，也可以有多个参数： + +```python +@coprocessor(args=["number", "number", "number"], + sql="select number from numbers limit 5", + returns=["value"]) +def normalize(n1, n2, n3) -> vector[i64]: + # returns [0,1,8,27,64] + return n1 * n2 * n3 +``` + +除了 `args`，还可以向协处理器传递用户定义的参数： + +```python +@coprocessor(returns=['value']) +def add(**params) -> vector[i64]: + a = params['a'] + b = params['b'] + return int(a) + int(b) +``` + +然后从 HTTP API 传递 `a` 和 `b`： + +```sh +curl -XPOST \ + "http://localhost:4000/v1/run-script?name=add&db=public&a=42&b=99" +``` + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "value", + "data_type": "Int64" + } + ] + }, + "rows": [ + [ + 141 + ] + ] + } + } + ], + "execution_time_ms": 0 +} +``` + +将 `a=42&b=99` 作为查询参数传入HTTP API，返回结果 `141`。 + +用户定义的参数必须由协处理器中的 `**kwargs` 来完成，其类型都是字符串。可以传递任何想要的东西，如在协处理器中运行的 SQL。 + +## 协处理器函数的输出 + +正如前面的例子所展示的那样，协处理器函数的输出必须是向量。 + +We can return multi vectors: + +```python +from greptime import vector + +@coprocessor(returns=["a", "b", "c"]) +def return_vectors() -> (vector[i64], vector[str], vector[f64]): + a = vector([1, 2, 3]) + b = vector(["a", "b", "c"]) + c = vector([42.0, 43.0, 44.0]) + return a, b, c +``` + +函数 `return_vectors` 的返回类型是 `(vector[i64], vector[str], vector[f64])`。 + +但必须确保所有这些由函数返回的向量具有相同的长度，因为当它们被转换为行时，每一行必须呈现所有的列值。 + +当然，可以返回字面值，它们也会被转化为向量： + +```python +from greptime import vector + +@coprocessor(returns=["a", "b", "c"]) +def return_vectors() -> (vector[i64], vector[str], vector[i64]): + a = 1 + b = "Hello, GreptimeDB!" + c = 42 + return a, b, c +``` + +## HTTP API + +`/scripts` 提交一个 Python 脚本到 GreptimeDB。 + +保存一个 Python 脚本，如 `test.py`： + +```python +@coprocessor(args = ["number"], + returns = [ "number" ], + sql = "select number from numbers limit 5") +def square(number) -> vector[i64]: + return number * 2 +``` + +将其提交到数据库： + +```shell +curl --data-binary @test.py -XPOST \ + "http://localhost:4000/v1/scripts?db=default&name=square" +``` + +```json +{"code":0} +``` + +Python 脚本被插入到 `scripts` 表中并被自动编译： + +```shell +curl -G http://localhost:4000/v1/sql --data-urlencode "sql=select * from scripts" +``` + +```json +{ + "code": 0, + "output": [{ + "records": { + "schema": { + "column_schemas": [ + { + "name": "schema", + "data_type": "String" + }, + { + "name": "name", + "data_type": "String" + }, + { + "name": "script", + "data_type": "String" + }, + { + "name": "engine", + "data_type": "String" + }, + { + "name": "timestamp", + "data_type": "TimestampMillisecond" + }, + { + "name": "gmt_created", + "data_type": "TimestampMillisecond" + }, + { + "name": "gmt_modified", + "data_type": "TimestampMillisecond" + } + ] + }, + "rows": [ + [ + "default", + "square", + "@coprocessor(args = [\"number\"],\n returns = [ \"number\" ],\n sql = \"select number from numbers\")\ndef square(number):\n return number * 2\n", + "python", + 0, + 1676032587204, + 1676032587204 + ] + ] + } + }], + "execution_time_ms": 4 +} +``` + +也可以通过 `/run-script` 执行脚本： + +```shell +curl -XPOST -G "http://localhost:4000/v1/run-script?db=default&name=square" +``` + +```json +{ + "code": 0, + "output": [{ + "records": { + "schema": { + "column_schemas": [ + { + "name": "number", + "data_type": "Float64" + } + ] + }, + "rows": [ + [ + 0 + ], + [ + 2 + ], + [ + 4 + ], + [ + 6 + ], + [ + 8 + ] + ] + } + }], + "execution_time_ms": 8 +} +``` + +### Python 脚本的参数和结果 + +`/scripts` 接受指定数据库的查询参数 `db`，以及命名脚本的 `name`。`/scripts` 处理 POST 方法主体来作为脚本文件内容。 + +`/run-script` 通过 `db` 和 `name` 运行编译好的脚本，然后返回输出，这与 `/sql` API 中的查询结果相同。 + +`/run-script` 也接收其他查询参数，作为传递到协处理器的用户参数，参考[输入和输出](#协处理器函数的输入)。 + + +## 在 GreptimeDB 控制台中编辑脚本 + +[GreptimeDB 控制台](/getting-started/installation/greptimedb-dashboard.md) 提供了编辑器供用户方便地编辑脚本。 + +在启动 GreptimeDB 后，你可以通过 URL `http://localhost:4000/dashboard` 访问控制台。 +点击左侧边栏的 `Scripts` 进入脚本列表页。 +你可以创建一个新的脚本，编辑一个已有的脚本，或者从控制台运行一个脚本。 + +![dashboard-scripts](/db-dashboard-scripts.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/getting-started.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/getting-started.md new file mode 100644 index 000000000..14bda5677 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/getting-started.md @@ -0,0 +1,193 @@ +# 入门指南 + +## 安装 + +### 创建 Python 环境 + +如果您正在使用 Greptime 的 Docker 镜像，那么它已经设置好了脚本功能，您可以跳过这一步。 + +如果您希望使用带有 pyo3 功能的 Greptime 二进制文件，首先需要知道您的 Greptime 二进制文件所需的 Python 版本。您可以通过运行 `ldd greptime | grep 'libpython'`（或在 Mac 上运行 `otool -L greptime|grep Python.framework`）来检查。然后安装相应的 Python 版本（例如，`libpython3.10.so` 需要 Python 3.10 ）。 + +使用 Conda 创建一个 Python3 环境。Conda 是管理 Python 环境的强大工具，请参阅[官方文档](https://docs.conda.io/en/latest/miniconda.html)以获取更多信息。 + +```shell +conda create --name Greptime python=<上一步中特定的Python版本，例如3.10> +conda activate Greptime +``` + +您可能需要为您的 Python 共享库设置正确的 `LD_LIBRARY_PATH`，例如，对于 Conda 环境，您需要将 `LD_LIBRARY_PATH`（或`DYLD_LIBRARY_PATH`）设置为 `$CONDA_PREFIX/lib`。您可以通过运行`ls $CONDA_PREFIX/lib | grep 'libpython'` 来检查该路径是否包含正确的 Python 共享库，并确认版本是否正确。 + +### 安装 GreptimeDB + +请参考 [安装 GreptimeDB](/getting-started/installation/overview.md)。 + +## Hello world 实例 + +让我们从 hello world 实例开始入手： + +```python +@coprocessor(returns=['msg']) +def hello() -> vector[str]: + return "Hello, GreptimeDB" +``` + +将其保存为 `hello.py`，然后通过 [HTTP API](./define-function.md#http-api) 发布： + +### 提交 Python 脚本到 GreptimeDB + +```sh +curl --data-binary "@hello.py" -XPOST "http://localhost:4000/v1/scripts?name=hello&db=public" +``` + +然后在 SQL 中调用： + +```sql +select hello(); +``` + +```sql ++-------------------+ +| hello() | ++-------------------+ +| Hello, GreptimeDB | ++-------------------+ +1 row in set (1.77 sec) +``` + +或者通过 [HTTP API](./define-function.md#http-api) 进行调用： + +```sh +curl -XPOST "http://localhost:4000/v1/run-script?name=hello&db=public" +``` + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "msg", + "data_type": "String" + } + ] + }, + "rows": [["Hello, GreptimeDB"]] + } + } + ], + "execution_time_ms": 1917 +} +``` + +函数 `hello` 带有 `@coprocessor` 注解。 + +`@coprocessor` 中的 `returns` 指定了返回的列名，以及整体的返回格式： + +```json + "schema": { + "column_schemas": [ + { + "name": "msg", + "data_type": "String" + } + ] + } +``` + +参数列表后面的 `-> vector[str]` 指定了函数的返回类型，都是具有具体类型的 vector。返回类型是生成 coprocessor 函数的输出所必需的。 + +`hello` 的函数主体返回一个字面字符串 `"Hello, GreptimeDB"`。Coprocessor 引擎将把它转换成一个常量字符串的 vector 并返回它。 + +总的来说一个协处理器包含三个主要部分： + +- `@coprocessor` 注解 +- 函数的输入和输出 +- 函数主体 + +我们可以像 SQL UDF(User Defined Function) 一样在 SQL 中调用协处理器，或者通过 HTTP API 调用。 + +## SQL 实例 + +将复杂的分析用的 Python 代码（比如下面这个通过 cpu/mem/disk 使用率来确定负载状态的代码）保存到一个文件中（这里命名为 `system_status.py`）： + +```python +@coprocessor(args=["host", "idc", "cpu_util", "memory_util", "disk_util"], + returns = ["host", "idc", "status"], + sql = "SELECT * FROM system_metrics") +def system_status(hosts, idcs, cpus, memories, disks)\ + -> (vector[str], vector[str], vector[str]): + statuses = [] + for host, cpu, memory, disk in zip(hosts, cpus, memories, disks): + if cpu > 80 or memory > 80 or disk > 80: + statuses.append("red") + continue + + status = cpu * 0.4 + memory * 0.4 + disk * 0.2 + + if status > 80: + statuses.append("red") + elif status > 50: + statuses.append("yello") + else: + statuses.append("green") + + + return hosts, idcs, statuses + +``` + +上述代码根据 cpu/memory/disk 的使用情况来评估主机状态。参数来自于查询 `system_metrics` 的数据，由 `@coprocessor` 注释中的参数 `sql` 指定（这里是=`"SELECT * FROM system_metrics"`）。查询结果被分配给 `args=[...]` 中的每个位置参数，然后函数返回三个变量，这些变量被转换为三个列 `returns = ["host", "idc", "status"]`。 + +### 提交 Python 脚本到 GreptimeDB + +可以用 `system_status` 将文件提交给 GreptimeDB，这样以后就可以用这个名称来引用并执行它： + +```shell +curl --data-binary "@system_status.py" \ + -XPOST "http://localhost:4000/v1/scripts?name=system_status&db=public" +``` + +运行该脚本： + +```shell +curl -XPOST \ + "http://localhost:4000/v1/run-script?name=system_status&db=public" +``` + +以 `json` 格式获取结果： + +```json +{ + "code": 0, + "output": { + "records": { + "schema": { + "column_schemas": [ + { + "name": "host", + "data_type": "String" + }, + { + "name": "idc", + "data_type": "String" + }, + { + "name": "status", + "data_type": "String" + } + ] + }, + "rows": [ + ["host1", "idc_a", "green"], + ["host1", "idc_b", "yello"], + ["host2", "idc_a", "red"] + ] + } + } +} +``` + +更多有关 Python 协处理器的信息，请参考[定义函数](./define-function.md)文档。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/overview.md new file mode 100644 index 000000000..6fffbc012 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/overview.md @@ -0,0 +1,31 @@ +# 概述 + +GreptimeDB 支持在数据库内运行 Python 脚本，如果业务逻辑太复杂，无法通过 SQL 表达，则可以使用 Python。Python 目前在数据科学和人工智能领域被广泛使用，为了避免花费大量的时间和精力来传输和转换数据，我们提供了在数据库中执行 Python 脚本的能力。 + +我们认为 GreptimeDB 中的 Python 脚本是传统 RDMS 中存储过程的完美替代品，同时用户也可以创建 SQL UDFs（用户定义的函数）。 + +- [入门指南](./getting-started.md) +- [定义函数](./define-function.md) +- [查询数据](./query-data.md) +- [写入数据](./write-data.md) +- [数据类型](./data-types.md) +- [API](./api.md) + +所有的例子都可以在 [python-coprocessor-examples](https://github.com/GreptimeTeam/python-coprocessor-examples) 中找到。 + +# 注意事项 + +Python 脚本目前正处于实验阶段，API 可能会发生一些变化。 + +用户可以下载支持 PyO3 的 [pre-built binaries](https://greptime.cn/download)，其文件名后缀为 `pyo3`。也可以通过下载没有 `pyo3` 后缀的 binary 文件直接使用 RustPython，它不需要额外的设置。 + +如果有库的链接问题，那么需要检查是否设置了正确的 Python 共享库，这可能会有点难度。一般来说，只需要安装 `python-dev` 包（在大多数基于 Debian 的系统上）。然而，如果用户使用 Homebrew 在 macOS 上安装 Python，则必须创建一个适当的链接到 `Library/Frameworks/Python.framework`。 + +推荐利用 `Conda` 来管理 Python 环境。首先，用下载的 binary 文件所要求的相同版本的 Python 创建一个 Python 环境。或者，可以使用一个 docker 容器，在其中执行 `greptime` binary。 + +另一个可行方案，但并非推荐方案：手动安装所需的 Python 版本，并将 `LD_LIBRARY_PATH`环境变量设置为包含 `libpython.so` 文件的目录。`` 的版本号根据所使用的 Python 的版本而不同。 + +两个 Python 脚本的后端： + +1. RustPython 解释器：无需安装任何 Python 库就可以支持，但它没有 CPython 后端那么快。名称中没有 `pyo3` 的 Release Binary 使用 RustPython Interpreter。虽然仍然可以在 RustPython 解释器中使用 Python 语法，但不能使用任何第三方的库。 +2. CPython 解释器：这是最常用的 Python 版本。它允许使用各种第三方库，但需要安装正确的 Python 共享库。任何名称中带有 `pyo3` 的 Release Binary 都使用 CPython Interpreter。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/query-data.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/query-data.md new file mode 100644 index 000000000..f645c3ba7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/query-data.md @@ -0,0 +1,117 @@ +# 查询数据 + +我们在 Python Corpcessor 中提供了两种方法来轻松查询 GreptimeDB 的数据： + +* SQL：运行一个 SQL 字符串并返回查询结果。 +* DataFrame API：描述和执行查询的内置模块，类似于 [Pandas DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) 或 [Spark DataFrame](https://spark.apache.org/docs/latest/sql-programming-guide.html)。 + +## SQL + +使用 `greptime` 模块的 `query` 方法来检索一个查询引擎，然后调用 `sql` 函数来执行一个 SQL 字符串，比如： + +```python +@copr(returns=["value"]) +def query_numbers()->vector[f64]: + from greptime import query + return query().sql("select number from numbers limit 10")[0] +``` + +通过 SQL 客户端调用它： + +```sql +SQL > select query_numbers(); ++-----------------+ +| query_numbers() | ++-----------------+ +| 0 | +| 1 | +| 2 | +| 3 | +| 4 | +| 5 | +| 6 | +| 7 | +| 8 | +| 9 | ++-----------------+ +10 rows in set (1.78 sec) +``` + + `sql` 函数返回一个列的列表，每个列是一个值的向量。 + +在上面的例子中，`sql("select number from numbers limit 10")` 返回一个向量的列表。并使用 `[0]` 检索第一列向量，这就是 `select` SQL 中的 `number` 列。 + +## 查询后处理 + +在查询结果返回给用户之前进行处理时，协处理器就能派上用场。 + +例如，我们想对数值进行标准化处理： + +* 如果错过了，返回 0，而不是 null 或 `NaN`， +* 如果它大于 5，返回 5， +* 如果它小于 0，则返回 0。 + +然后我们可以创建 `normalize.py`: + +```python +import math + +def normalize0(x): + if x is None or math.isnan(x): + return 0 + elif x > 5: + return 5 + elif x < 0: + return 0 + else: + return x + +@coprocessor(args=["number"], sql="select number from numbers limit 10", returns=["value"]) +def normalize(v) -> vector[i64]: + return [normalize0(x) for x in v] +``` + +`normalize0` 函数的行为如上所述。而 `normalize` 函数是协处理器的入口点： + +* 执行 SQL 的 `select value from demo`， +* 提取查询结果中的列 `value` 并将其作为 `normalize` 函数的参数，然后调用该函数。 +* 在函数中，使用列表理解来处理 `value` 向量，通过 `normalize0` 函数处理每个元素， +* 返回以 `value` 列命名的结果。 + +`->vector[i64]` 部分指定了用于生成输出模式的返回列类型。 + +这个例子还展示了如何导入 stdlib 和定义其他函数（`normalize0`）进行调用。 +`normalize` 协处理器将在流中被调用，查询结果可能包含多个批次，引擎将对每个批次调用协处理器。而且应该记住，从查询结果中提取的列都是向量，我们将在下一章中介绍向量。 + +提交并运行这个脚本将产生输出： + +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "value", + "data_type": "Int64" + } + ] + }, + "rows": [ + [0], + [1], + [2], + [3], + [4], + [5], + [5], + [5], + [5], + [5] + ] + } + } + ] +} +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/write-data.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/write-data.md new file mode 100644 index 000000000..cf9b2e2d4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/python-scripts/write-data.md @@ -0,0 +1,38 @@ +# 写入数据 + +## 插入新数据 + +用户也可以通过 `sql` API 插入数据 + +```python +from greptime import query +@copr(returns=["affected_rows"]) +def insert() -> vector[i32]: + return query().sql("insert into monitor(host, ts, cpu, memory) values('localhost',1667446807000, 15.3, 66.6)") +``` + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "rows", + "data_type": "Int32" + } + ] + }, + "rows": [ + [ + 1 + ] + ] + } + } + ], + "execution_time_ms": 4 +} +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/cte.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/cte.md new file mode 100644 index 000000000..03fb2eeb5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/cte.md @@ -0,0 +1,167 @@ +--- +description: 介绍公共表表达式（CTE）的基本概念和使用方法。 +--- + +# 公共表表达式（CTE） + +CTE 与 [视图](./view.md) 类似，它们帮助您简化查询的复杂性，将长而复杂的 SQL 语句分解，并提高可读性和可重用性。 + +您已经在 [快速开始](/getting-started/quick-start.md#指标和日志的关联查询) 文档中阅读了一个 CTE 的例子。 + +## 什么是公共表表达式 （CTE）？ + +公共表表达式 (CTE) 是可以在 `SELECT`、`INSERT`、`UPDATE` 或 `DELETE` 语句中引用的临时结果集。CTE 有助于将复杂的查询分解成更可读的部分，并且可以在同一个查询中多次引用。 + +## CTE 的基本语法 + +CTE 通常使用 `WITH` 关键字定义。基本语法如下： + +```sql +WITH cte_name [(column1, column2, ...)] AS ( + QUERY +) +SELECT ... +FROM cte_name; +``` + +## 示例解释 + +接下来，我们将通过一个完整的示例来演示如何使用 CTE，包括数据准备、CTE 创建和使用。 + +### 步骤 1：创建示例数据 + +假设我们有以下两个表： + +- `grpc_latencies`：包含 gRPC 请求延迟数据。 +- `app_logs`：包含应用程序日志信息。 + +```sql +CREATE TABLE grpc_latencies ( + ts TIMESTAMP TIME INDEX, + host VARCHAR(255), + latency FLOAT, + PRIMARY KEY(host), +); + +INSERT INTO grpc_latencies VALUES +('2023-10-01 10:00:00', 'host1', 120), +('2023-10-01 10:00:00', 'host2', 150), +('2023-10-01 10:00:05', 'host1', 130); + +CREATE TABLE app_logs ( + ts TIMESTAMP TIME INDEX, + host VARCHAR(255), + log TEXT, + log_level VARCHAR(50), + PRIMARY KEY(host, log_level), +); + +INSERT INTO app_logs VALUES +('2023-10-01 10:00:00', 'host1', 'Error on service', 'ERROR'), +('2023-10-01 10:00:00', 'host2', 'All services OK', 'INFO'), +('2023-10-01 10:00:05', 'host1', 'Error connecting to DB', 'ERROR'); +``` + +### 步骤 2：定义和使用 CTE + +我们将创建两个 CTE 来分别计算第 95 百分位延迟和错误日志的数量。 + +```sql +WITH +metrics AS ( + SELECT + ts, + host, + approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency + FROM + grpc_latencies + ALIGN '5s' FILL PREV +), +logs AS ( + SELECT + ts, + host, + COUNT(log) RANGE '5s' AS num_errors + FROM + app_logs + WHERE + log_level = 'ERROR' + ALIGN '5s' BY (HOST) +) +SELECT + metrics.ts, + metrics.host, + metrics.p95_latency, + COALESCE(logs.num_errors, 0) AS num_errors +FROM + metrics +LEFT JOIN logs ON metrics.host = logs.host AND metrics.ts = logs.ts +ORDER BY + metrics.ts; +``` + +输出： + +```sql ++---------------------+-------+-------------+------------+ +| ts | host | p95_latency | num_errors | ++---------------------+-------+-------------+------------+ +| 2023-10-01 10:00:00 | host2 | 150 | 0 | +| 2023-10-01 10:00:00 | host1 | 120 | 1 | +| 2023-10-01 10:00:05 | host1 | 130 | 1 | ++---------------------+-------+-------------+------------+ +``` + +### 详细说明 + +1. **定义 CTEs**： + - `metrics`: + ```sql + WITH + metrics AS ( + SELECT + ts, + host, + approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency + FROM + grpc_latencies + ALIGN '5s' FILL PREV + ), + ``` + 这里我们使用[范围查询](/user-guide/query-data/sql.md#按时间窗口聚合数据)计算每个 `host` 在每个 5 秒时间窗口内的第 95 百分位延迟。 + + - `logs`: + ```sql + logs AS ( + SELECT + ts, + host, + COUNT(log) RANGE '5s' AS num_errors + FROM + app_logs + WHERE + log_level = 'ERROR' + ALIGN '5s' BY (HOST) + ) + ``` + 同样地，我们计算每个 `host` 在每个 5 秒时间窗口内的错误日志数量。 + +2. **使用 CTEs**： + 在最终的查询部分： + ```sql + SELECT + metrics.ts, + metrics.host, + metrics.p95_latency, + COALESCE(logs.num_errors, 0) AS num_errors + FROM + metrics + LEFT JOIN logs ON metrics.host = logs.host AND metrics.ts = logs.ts + ORDER BY + metrics.ts; + ``` + 我们对两个 CTE 结果集进行左连接，以获得最终的综合分析结果。 + +## 总结 + +通过 CTE，您可以将复杂的 SQL 查询分解为更易于管理和理解的部分。在本示例中，我们分别创建了两个 CTE 来计算第 95 百分位延迟和错误日志的数量，然后将它们合并到最终查询中进行分析。 阅读更多 [WITH](/reference/sql/with.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/overview.md new file mode 100644 index 000000000..9633f2258 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/overview.md @@ -0,0 +1,26 @@ +--- +description: 介绍 GreptimeDB 支持的查询语言和推荐的查询库。 +--- + +# 概述 + +## 查询语言 + +- [SQL](./sql.md) +- [PromQL](promql.md) + +从 v0.9 开始， GreptimeDB 开始支持查询视图和公共表表达式（CTE），用于简化查询语句： + +* [View](./view.md) +* [公共表表达式（CTE）](./cte.md) + +## 推荐的查询库 + +由于 GreptimeDB 使用 SQL 作为主要查询语言，并支持 [MySQL](/user-guide/protocols/mysql.md) 和 [PostgreSQL](/user-guide/protocols/postgresql.md) 协议， +你可以使用支持 MySQL 或 PostgreSQL 的成熟 SQL Driver 来查询数据。 + +有关更多信息，请参考[SQL 工具](/reference/sql-tools.md)文档。 + +## 查询外部数据 + +GreptimeDB 具有查询外部数据文件的能力，更多信息请参考[查询外部数据](./query-external-data.md)文档。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/promql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/promql.md new file mode 100644 index 000000000..8ca811deb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/promql.md @@ -0,0 +1,248 @@ +--- +description: 介绍 GreptimeDB 对 Prometheus 查询语言（PromQL）的支持，包括 HTTP API 和 SQL 扩展。 +--- + +# Prometheus Query Language + +GreptimeDB 可以作为 Grafana 中 Prometheus 的替代品，因为 GreptimeDB 支持 PromQL（Prometheus Query Language）。GreptimeDB 在 Rust 中重新实现了 PromQL，并通过接口将能力开放，包括 Prometheus 的 HTTP API、GreptimeDB 的 HTTP API 和 SQL 接口。 + +## Prometheus 的 HTTP API + + + + +GreptimeDB 实现了兼容 Prometheus 的一系列 API ，通过 `/v1/prometheus` 路径对外提 +供服务： + +- Instant queries `/api/v1/query` +- Range queries `/api/v1/query_range` +- Series `/api/v1/series` +- Label names `/api/v1/labels` +- Label values `/api/v1/label//values` + +这些接口的输入和输出与原生的 Prometheus HTTP API 相同，用户可以把 GreptimeDB 当 +作 Prometheus 的直接替换。例如，在 Grafana 中我们可以设置 +`http://localhost:4000/v1/prometheus/` 作为其 Prometheus 数据源的地址。 + +访问 [Prometheus 文档](https://prometheus.io/docs/prometheus/latest/querying/api) +获得更详细的说明。 + +你可以通过设置 HTTP 请求的 `db` 参数来指定 GreptimeDB 中的数据库名。 + +例如，以下查询将返回 `public` 数据库中 `process_cpu_seconds_total` 指标的 CPU 使用率： + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + --data-urlencode 'query=irate(process_cpu_seconds_total[1h])' \ + --data-urlencode 'start=2024-11-24T00:00:00Z' \ + --data-urlencode 'end=2024-11-25T00:00:00Z' \ + --data-urlencode 'step=1h' \ + --data-urlencode 'db=public' \ + http://localhost:4000/v1/prometheus/api/v1/query_range +``` + +如果你使用启用了身份验证的 GreptimeDB，则需要 Authorization header，请参阅[鉴权](/user-guide/protocols/http.md#鉴权)。 +该 API 的查询字符串参数与原始 [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) 的查询字符串参数相同，但额外的 `db` 参数除外，该参数指定了 GreptimeDB 数据库名称。 + +输出格式与 Prometheus API 完全兼容： + +```json +{ + "status": "success", + "data": { + "resultType": "matrix", + "result": [ + { + "metric": { + "job": "node", + "instance": "node_exporter:9100", + "__name__": "process_cpu_seconds_total" + }, + "values": [ + [ + 1732618800, + "0.0022222222222222734" + ], + [ + 1732622400, + "0.0009999999999999788" + ], + [ + 1732626000, + "0.0029999999999997585" + ], + [ + 1732629600, + "0.002222222222222175" + ] + ] + } + ] + } +} +``` + +## SQL + +GreptimeDB 还扩展了 SQL 语法以支持 PromQL。可以用 `TQL`（Time-series Query Language）为关键字开始写入参数和进行查询。该语法如下： + +```sql +TQL [EVAL|EVALUATE] (, , ) +``` + +`` 指定查询开始时间范围，`` 指定查询结束时间。 `` 识别查询步幅。它们均可为无引号数字（表示``和``的 UNIX 时间戳，以及``的秒数持续时间），或带引号的字符串（表示``和``的 RFC3339 时间戳，以及``的字符串格式的持续时间）。 + +例如: + +```sql +TQL EVAL (1676738180, 1676738780, '10s') sum(some_metric) +``` + +你可以在所有支持 SQL 的地方编写上述命令，包括 GreptimeDB HTTP API、SDK、PostgreSQL 和 MySQL 客户端等。 + +## 多列查询 + +基于表模型，GreptimeDB 支持在单个表（或在 Prometheus 中称为指标）中查询多个字段。默认情况下，查询将应用于每个值字段 (field)。或者也可以使用特殊的过滤器 `__field__` 来查询特定的字段： + +```promql +metric{__field__="field1"} +``` + +反选或正则表达式也都支持 + +```promql +metric{__field__!="field1"} + +metric{__field__=~"field_1|field_2"} + +metric{__field__!~"field_1|field_2"} +``` + +## 局限 + +尽管 GreptimeDB 支持丰富的数据类型，但 PromQL 的实现仍然局限于以下类型： + +- timestamp: `Timestamp` +- tag: `String` +- value: `Double` + +目前 GreptimeDB 只支持 PromQL 的一个子集，下方附上了兼容性列表。你也可以在[跟踪问题](https://github.com/GreptimeTeam/greptimedb/issues/1042)中查看我们最新的兼容性报告。 + +### 字符（Literal） + +支持字符串和浮点数，与 PromQL 的[规则](https://prometheus.io/docs/prometheus/latest/querying/basics/#literals)相同。 + +### 选择器 + +- 支持即时和范围选择器，但唯独不支持 `label` 和指标名字的不匹配判断，例如 `{__name__!="request_count}"`，等价匹配的情况是支持的，例如 `{__name__="request_count}"`。 +- 支持时间长度和偏移量，但不支持 `@` 修改器。 + +### 时间精度 + +PromQL 的时间戳精度受制于查询语法的限制，最高只支持毫秒级精度的计算。然而，GreptimeDB 支持存储微秒和纳秒等高精度时间。在使用 PromQL 进行计算时，这些高精度时间将被隐式转换为毫秒精度进行计算。 + +### Binary + +*目前还不支持像 `1+1` 这样纯粹的 binary 表达式。* + +- 支持: + | Operator | Example | + | :------- | :------- | + | add | `a + b` | + | sub | `a - b` | + | mul | `a * b` | + | div | `a / b` | + | mod | `a % b` | + | eqlc | `a == b` | + | neq | `a != b` | + | gtr | `a > b` | + | lss | `a < b` | + | gte | `a >= b` | + | lte | `a <= b` | + +- 不支持: + | Operator | Progress | + | :------- | :------- | + | power | TBD | + | atan2 | TBD | + | and | TBD | + | or | TBD | + | unless | TBD | + +### Aggregators + +- 支持: + | Aggregator | Example | + | :--------- | :------------------------ | + | sum | `sum by (foo)(metric)` | + | avg | `avg by (foo)(metric)` | + | min | `min by (foo)(metric)` | + | max | `max by (foo)(metric)` | + | stddev | `stddev by (foo)(metric)` | + | stdvar | `stdvar by (foo)(metric)` | + +- 不支持: + | Aggregator | Progress | + | :----------- | :------- | + | count | TBD | + | grouping | TBD | + | topk | TBD | + | bottomk | TBD | + | count_values | TBD | + +### Instant Functions + +- 支持: + | Function | Example | + | :----------------- | :-------------------------------- | + | abs | `abs(metric)` | + | ceil | `ceil(metric)` | + | exp | `exp(metric)` | + | ln | `ln(metric)` | + | log2 | `log2(metric)` | + | log10 | `log10(metric)` | + | sqrt | `sqrt(metric)` | + | acos | `acos(metric)` | + | asin | `asin(metric)` | + | atan | `atan(metric)` | + | sin | `sin(metric)` | + | cos | `cos(metric)` | + | tan | `tan(metric)` | + | acosh | `acosh(metric)` | + | asinh | `asinh(metric)` | + | atanh | `atanh(metric)` | + | sinh | `sinh(metric)` | + | cosh | `cosh(metric)` | + | scalar | `scalar(metric)` | + | tanh | `tanh(metric)` | + | timestamp | `timestamp()` | + | histogram_quantile | `histogram_quantile(phi, metric)` | + +- 不支持: + | Function | Progress | + | :------------------------- | :------- | + | absent | TBD | + | sgn | TBD | + | sort | TBD | + | sort_desc | TBD | + | deg | TBD | + | rad | TBD | + | *other multiple input fns* | TBD | + +### Range Functions + +- 支持: + | Function | Example | + | :----------------- | :----------------------------- | + | idelta | `idelta(metric[5m])` | + | \_over_time | `count_over_time(metric[5m])` | + | stddev_over_time | `stddev_over_time(metric[5m])` | + | stdvar_over_time | `stdvar_over_time(metric[5m])` | + | changes | `changes(metric[5m])` | + | delta | `delta(metric[5m])` | + | rate | `rate(metric[5m])` | + | deriv | `deriv(metric[5m])` | + | increase | `increase(metric[5m])` | + | irate | `irate(metric[5m])` | + | reset | `reset(metric[5m])` | \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/query-external-data.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/query-external-data.md new file mode 100644 index 000000000..118b2ec38 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/query-external-data.md @@ -0,0 +1,123 @@ +--- +description: 介绍如何查询外部数据文件，包括创建外部表和查询目录中的数据。 +--- + +# 查询外部数据 + +## 对文件进行查询 + +目前，我们支持 `Parquet`、`CSV`、`ORC` 和 `NDJson` 格式文件的查询。 + +以 [Taxi Zone Lookup Table](https://d37ci6vzurychx.cloudfront.net/misc/taxi+_zone_lookup.csv) 数据为例。 + +```bash +curl "https://d37ci6vzurychx.cloudfront.net/misc/taxi+_zone_lookup.csv" -o /tmp/taxi+_zone_lookup.csv +``` + +创建一个外部表： + +```sql +CREATE EXTERNAL TABLE taxi_zone_lookup with (location='/tmp/taxi+_zone_lookup.csv',format='csv'); +``` + +检查外部表的组织和结构： + +```sql +DESC TABLE taxi_zone_lookup; +``` + +```sql ++--------------------+----------------------+------+------+--------------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+----------------------+------+------+--------------------------+---------------+ +| LocationID | Int64 | | YES | | FIELD | +| Borough | String | | YES | | FIELD | +| Zone | String | | YES | | FIELD | +| service_zone | String | | YES | | FIELD | +| greptime_timestamp | TimestampMillisecond | PRI | NO | 1970-01-01 00:00:00+0000 | TIMESTAMP | ++--------------------+----------------------+------+------+--------------------------+---------------+ +4 rows in set (0.00 sec) +``` + +:::tip 注意 +在这里，你可能会注意到出现了一个 `greptime_timestamp` 列，这个列作为表的时间索引列，在文件中并不存在。这是因为在创建外部表时，我们没有指定时间索引列，`greptime_timestamp` 列被自动添加作为时间索引列，并且默认值为 `1970-01-01 00:00:00+0000`。你可以在 [create](/reference/sql/create.md#create-external-table) 文档中查找更多详情。 +::: + +现在就可以查询外部表了： + +```sql +SELECT `Zone`, `Borough` FROM taxi_zone_lookup LIMIT 5; +``` + +```sql ++-------------------------+---------------+ +| Zone | Borough | ++-------------------------+---------------+ +| Newark Airport | EWR | +| Jamaica Bay | Queens | +| Allerton/Pelham Gardens | Bronx | +| Alphabet City | Manhattan | +| Arden Heights | Staten Island | ++-------------------------+---------------+ +``` + +## 对目录进行查询 + +首先下载一些数据： + +```bash +mkdir /tmp/external +curl "https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2022-01.parquet" -o /tmp/external/yellow_tripdata_2022-01.parquet +curl "https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2022-02.parquet" -o /tmp/external/yellow_tripdata_2022-02.parquet +``` + +验证下载情况： + +```bash +ls -l /tmp/external +total 165368 +-rw-r--r-- 1 wenyxu wheel 38139949 Apr 28 14:35 yellow_tripdata_2022-01.parquet +-rw-r--r-- 1 wenyxu wheel 45616512 Apr 28 14:36 yellow_tripdata_2022-02.parquet +``` + +创建外部表 + +```sql +CREATE EXTERNAL TABLE yellow_tripdata with(location='/tmp/external/',format='parquet'); +``` + +执行查询： + +```sql +SELECT count(*) FROM yellow_tripdata; +``` + +```sql ++-----------------+ +| COUNT(UInt8(1)) | ++-----------------+ +| 5443362 | ++-----------------+ +1 row in set (0.48 sec) +``` + +```sql +SELECT * FROM yellow_tripdata LIMIT 5; +``` + +```sql ++----------+----------------------+-----------------------+-----------------+---------------+------------+--------------------+--------------+--------------+--------------+-------------+-------+---------+------------+--------------+-----------------------+--------------+----------------------+-------------+---------------------+ +| VendorID | tpep_pickup_datetime | tpep_dropoff_datetime | passenger_count | trip_distance | RatecodeID | store_and_fwd_flag | PULocationID | DOLocationID | payment_type | fare_amount | extra | mta_tax | tip_amount | tolls_amount | improvement_surcharge | total_amount | congestion_surcharge | airport_fee | greptime_timestamp | ++----------+----------------------+-----------------------+-----------------+---------------+------------+--------------------+--------------+--------------+--------------+-------------+-------+---------+------------+--------------+-----------------------+--------------+----------------------+-------------+---------------------+ +| 1 | 2022-02-01 00:06:58 | 2022-02-01 00:19:24 | 1 | 5.4 | 1 | N | 138 | 252 | 1 | 17 | 1.75 | 0.5 | 3.9 | 0 | 0.3 | 23.45 | 0 | 1.25 | 1970-01-01 00:00:00 | +| 1 | 2022-02-01 00:38:22 | 2022-02-01 00:55:55 | 1 | 6.4 | 1 | N | 138 | 41 | 2 | 21 | 1.75 | 0.5 | 0 | 6.55 | 0.3 | 30.1 | 0 | 1.25 | 1970-01-01 00:00:00 | +| 1 | 2022-02-01 00:03:20 | 2022-02-01 00:26:59 | 1 | 12.5 | 1 | N | 138 | 200 | 2 | 35.5 | 1.75 | 0.5 | 0 | 6.55 | 0.3 | 44.6 | 0 | 1.25 | 1970-01-01 00:00:00 | +| 2 | 2022-02-01 00:08:00 | 2022-02-01 00:28:05 | 1 | 9.88 | 1 | N | 239 | 200 | 2 | 28 | 0.5 | 0.5 | 0 | 3 | 0.3 | 34.8 | 2.5 | 0 | 1970-01-01 00:00:00 | +| 2 | 2022-02-01 00:06:48 | 2022-02-01 00:33:07 | 1 | 12.16 | 1 | N | 138 | 125 | 1 | 35.5 | 0.5 | 0.5 | 8.11 | 0 | 0.3 | 48.66 | 2.5 | 1.25 | 1970-01-01 00:00:00 | ++----------+----------------------+-----------------------+-----------------+---------------+------------+--------------------+--------------+--------------+--------------+-------------+-------+---------+------------+--------------+-----------------------+--------------+----------------------+-------------+---------------------+ +5 rows in set (0.11 sec) +``` + +:::tip 注意 +查询结果中包含 `greptime_timestamp` 列的值，尽管它在原始文件中并不存在。这个列的所有值均为 `1970-01-01 00:00:00+0000`，这是因为我们在创建外部表时，自动添加列 `greptime_timestamp`，并且默认值为 `1970-01-01 00:00:00+0000`。你可以在 [create](/reference/sql/create.md#create-external-table) 文档中查找更多详情。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/sql.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/sql.md new file mode 100644 index 000000000..99c302acb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/sql.md @@ -0,0 +1,465 @@ +--- +description: 介绍 GreptimeDB 支持的 SQL 查询功能，包括基础查询、函数使用、数据过滤、排序、聚合等内容。 +--- + +# SQL + +GreptimeDB 在查询数据时支持完整的 `SQL` 语法。 + +在这篇文档中，我们将使用 `monitor` 表中的数据作为示例来演示如何查询数据。关于如何创建 `monitor` 表格并向其中插入数据，请参考[表管理](/user-guide/administration/manage-data/basic-table-operations.md#创建表)和[写入数据](/user-guide/ingest-data/for-iot/sql.md)。 + +## 基础查询 + +通过 `SELECT` 语句来查询数据。例如，下面的查询返回 `monitor` 表中的所有数据： + +```sql +SELECT * FROM monitor; +``` + +查询结果如下： + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2022-11-03 03:39:57 | 0.1 | 0.4 | +| 127.0.0.1 | 2022-11-03 03:39:58 | 0.5 | 0.2 | +| 127.0.0.2 | 2022-11-03 03:39:58 | 0.2 | 0.3 | ++-----------+---------------------+------+--------+ +3 rows in set (0.00 sec) +``` + +`SELECT` 字段列表中也支持使用函数。 +例如，你可以使用 `count()` 函数来获取表中的总行数： + +```sql +SELECT count(*) FROM monitor; +``` + +```sql ++-----------------+ +| COUNT(UInt8(1)) | ++-----------------+ +| 3 | ++-----------------+ +``` + +使用函数 `avg()` 返回某个字段的平均值： + +```sql +SELECT avg(cpu) FROM monitor; +``` + +```sql ++---------------------+ +| AVG(monitor.cpu) | ++---------------------+ +| 0.26666666666666666 | ++---------------------+ +1 row in set (0.00 sec) +``` + +你还可以只返回函数的结果，例如从时间戳中提取一年中的第几天。 +SQL 语句中的 `DOY` 是 `day of the year` 的缩写： + +```sql +SELECT date_part('DOY', '2021-07-01 00:00:00'); +``` + +结果: + +```sql ++----------------------------------------------------+ +| date_part(Utf8("DOY"),Utf8("2021-07-01 00:00:00")) | ++----------------------------------------------------+ +| 182 | ++----------------------------------------------------+ +1 row in set (0.003 sec) +``` + +时间函数的参数和结果与 SQL 客户端的时区保持一致。 +例如，当客户端的时区设置为 `+08:00` 时，下面两个查询的结果是相同的： + +```sql +select to_unixtime('2024-01-02 00:00:00'); +select to_unixtime('2024-01-02 00:00:00+08:00'); +``` + +请参考 [SELECT](/reference/sql/select.md) 和 [Functions](/reference/sql/functions/overview.md) 获取更多信息。 + +## 限制返回的行数 + +时间序列数据通常是海量的。 +为了节省带宽和提高查询性能，你可以使用 `LIMIT` 语句来限制 `SELECT` 语句返回的行数。 + +例如，下面的查询限制返回的行数为 10： + +```sql +SELECT * FROM monitor LIMIT 10; +``` + +## 过滤数据 + +你可以使用 `WHERE` 子句来过滤 `SELECT` 语句返回的行。 +时序数据库中常见的场景是按照标签或时间索引来过滤数据。 +例如，按照标签 `host` 来过滤数据： + +```sql +SELECT * FROM monitor WHERE host='127.0.0.1'; +``` + +按照时间索引 `ts` 来过滤数据，返回 `2022-11-03 03:39:57` 之后的数据： + +```sql +SELECT * FROM monitor WHERE ts > '2022-11-03 03:39:57'; +``` + +你可以使用 `AND` 关键字来组合多个约束条件： + +```sql +SELECT * FROM monitor WHERE host='127.0.0.1' AND ts > '2022-11-03 03:39:57'; +``` + +### 使用时间索引过滤数据 + +按照时间索引来过滤数据是时序数据库的一个关键特性。 + +当处理 Unix 时间值时，数据库会默认将其类型认定为相关列的值类型。 +例如，当 `monitor` 表中的 `ts` 列的值类型为 `TimestampMillisecond` 时， +你可以使用下面的查询来过滤数据： + +Unix 时间值 `1667446797000` 表示一个以毫秒为单位的时间戳。 + +```sql +SELECT * FROM monitor WHERE ts > 1667446797000; +``` + +当处理时间精度为非默认类型的 Unix 时间值时，你需要使用 `::` 语法来指定时间的类型。 +这样可以确保数据库正确地识别时间的类型。 + +例如 `1667446797` 表示一个以秒为单位的时间戳，不是 `ts` 列默认的毫秒时间戳。 +你需要使用 `::TimestampSecond` 语法来指定它的类型为 `TimestampSecond` 来告知数据库 `1667446797` 应该被视为以秒为单位的时间戳。 + +```sql +SELECT * FROM monitor WHERE ts > 1667446797::TimestampSecond; +``` + +请参考[数据类型](/reference/sql/data-types.md#日期和时间类型) 获取更多时间类型。 + +对于标准的 `RFC3339` 或 `ISO8601` 字符串，由于其具备明确的精度，你可以直接在过滤条件中使用它们： + +```sql +SELECT * FROM monitor WHERE ts > '2022-07-25 10:32:16.408'; +``` + +你还可以使用时间函数来过滤数据。 +例如，使用 `now()` 函数和 `INTERVAL` 关键字来获取最近 5 分钟的数据： + +```sql +SELECT * FROM monitor WHERE ts >= now() - INTERVAL '5 minutes'; +``` + +请参考 [Functions](/reference/sql/functions/overview.md) 获取更多时间函数信息。 + +### 时区 + +GreptimeDB 的 SQL 客户端会根据本地时区解释不带时区信息的字符串时间戳。 +例如，当客户端时区为 `+08:00` 时，下面的两个查询是相同的： + +```sql +SELECT * FROM monitor WHERE ts > '2022-07-25 10:32:16.408'; +SELECT * FROM monitor WHERE ts > '2022-07-25 10:32:16.408+08:00'; +``` + +查询结果中的时间戳列值会根据客户端时区格式化。 +例如，下面的代码展示了相同的 `ts` 值在客户端时区 `UTC` 和 `+08:00` 下的结果： + + + + + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2023-12-31 16:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` + + + + + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-01-01 00:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` + + + + +### 函数 + +GreptimeDB 提供了丰富的内置函数和聚合函数，为数据分析应用开发。其特点包括： + ++ Apache Datafusion 查询引擎中继承的函数，包括一组符合 Postgres 命名方式和行为的日期/时间函数。 ++ JSON、位置信息等特殊数据类型的操作函数。 ++ 高级全文匹配能力。 + +查看 [函数列表](/reference/sql/functions/overview.md)。 + + +## 排序 + +GreptimeDB 不保证返回数据的顺序。你需要使用 `ORDER BY` 子句来对返回的数据进行排序。 +例如，在时间序列场景中通常使用时间索引列作为排序键： + +```sql +-- ascending order by ts +SELECT * FROM monitor ORDER BY ts ASC; +``` + +```sql +-- descending order by ts +SELECT * FROM monitor ORDER BY ts DESC; +``` + +## `CASE` 表达式 + +你可以使用 `CASE` 表达式在查询中执行条件逻辑。 +例如，下面的查询根据 `cpu` 字段的值返回 CPU 的状态： + +```sql +SELECT + host, + ts, + CASE + WHEN cpu > 0.5 THEN 'high' + WHEN cpu > 0.3 THEN 'medium' + ELSE 'low' + END AS cpu_status +FROM monitor; +``` + +结果如下： + +```sql ++-----------+---------------------+------------+ +| host | ts | cpu_status | ++-----------+---------------------+------------+ +| 127.0.0.1 | 2022-11-03 03:39:57 | low | +| 127.0.0.1 | 2022-11-03 03:39:58 | medium | +| 127.0.0.2 | 2022-11-03 03:39:58 | low | ++-----------+---------------------+------------+ +3 rows in set (0.01 sec) +``` + +更多信息请参考 [CASE](/reference/sql/case.md)。 + +## 按标签聚合数据 + +你可以使用 `GROUP BY` 语句将具有相同值的行进行分组汇总，例如查询 `idc` 列中的所有不同值的内存均值： + +```sql +SELECT host, avg(cpu) FROM monitor GROUP BY host; +``` + +```sql ++-----------+------------------+ +| host | AVG(monitor.cpu) | ++-----------+------------------+ +| 127.0.0.2 | 0.2 | +| 127.0.0.1 | 0.3 | ++-----------+------------------+ +2 rows in set (0.00 sec) +``` + +请参考 [GROUP BY](/reference/sql/group_by.md) 获取更多相关信息。 + +### 查询时间线中的最新数据 + +你可以通过组合使用 `DISTINCT ON` 和 `ORDER BY` 来查询每条时间线的最新数据点，例如： + +```sql +SELECT DISTINCT ON (host) * FROM monitor ORDER BY host, ts DESC; +``` + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2022-11-03 03:39:58 | 0.5 | 0.2 | +| 127.0.0.2 | 2022-11-03 03:39:58 | 0.2 | 0.3 | ++-----------+---------------------+------+--------+ +2 rows in set (0.00 sec) +``` +## 按时间窗口聚合数据 + +GreptimeDB 支持 [Range Query](/reference/sql/range.md) 来按时间窗口聚合数据。 + +假设我们有以下数据在 [`monitor` 表](/user-guide/administration/manage-data/basic-table-operations.md#创建表) 中： + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2023-12-13 02:05:41 | 0.5 | 0.2 | +| 127.0.0.1 | 2023-12-13 02:05:46 | NULL | NULL | +| 127.0.0.1 | 2023-12-13 02:05:51 | 0.4 | 0.3 | +| 127.0.0.2 | 2023-12-13 02:05:41 | 0.3 | 0.1 | +| 127.0.0.2 | 2023-12-13 02:05:46 | NULL | NULL | +| 127.0.0.2 | 2023-12-13 02:05:51 | 0.2 | 0.4 | ++-----------+---------------------+------+--------+ +``` + +下面的查询返回 10 秒内的平均 CPU 使用率，并且每 5 秒计算一次： + +```sql +SELECT + ts, + host, + avg(cpu) RANGE '10s' FILL LINEAR +FROM monitor +ALIGN '5s' TO '2023-12-01T00:00:00' BY (host) ORDER BY ts ASC; +``` + +1. `avg(cpu) RANGE '10s' FILL LINEAR` 是一个 Range 表达式。`RANGE '10s'` 指定了聚合的时间范围为 10s，`FILL LINEAR` 指定了如果某个点没有数据，使用 `LINEAR` 方法来填充。 +2. `ALIGN '5s'` 指定了查询的步频为 5s。 +3. `TO '2023-12-01T00:00:00` 指定了原始对齐时间。默认值为 Unix 时间 0。 +4. `BY (host)` 指定了聚合的键。如果省略 `BY` 关键字，那么默认使用数据表的主键作为聚合键。 +5. `ORDER BY ts ASC` 指定了结果集的排序方法。如果不指定排序方法，结果集的顺序是不确定的。 + +查询结果如下： + +```sql ++---------------------+-----------+----------------------------------------+ +| ts | host | AVG(monitor.cpu) RANGE 10s FILL LINEAR | ++---------------------+-----------+----------------------------------------+ +| 2023-12-13 02:05:35 | 127.0.0.1 | 0.5 | +| 2023-12-13 02:05:40 | 127.0.0.1 | 0.5 | +| 2023-12-13 02:05:45 | 127.0.0.1 | 0.4 | +| 2023-12-13 02:05:50 | 127.0.0.1 | 0.4 | +| 2023-12-13 02:05:35 | 127.0.0.2 | 0.3 | +| 2023-12-13 02:05:40 | 127.0.0.2 | 0.3 | +| 2023-12-13 02:05:45 | 127.0.0.2 | 0.2 | +| 2023-12-13 02:05:50 | 127.0.0.2 | 0.2 | ++---------------------+-----------+----------------------------------------+ +``` + +### 时间范围窗口 + +将初始时间范围窗口在时间序列中向前和向后移动，就生成了所有时间范围窗口。 +在上面的例子中，初始对齐时间被设置为 `2023-12-01T00:00:00`，这也是初始时间窗口的结束时间。 + +`RANGE` 选项和初始对齐时间定义了初始时间范围窗口，它从 `初始对齐时间` 开始，到 `初始对齐时间 + RANGE` 结束。 +`ALIGN` 选项定义了查询的步频，决定了从初始时间窗口到其他时间窗口的计算步频。 +例如，使用初始对齐时间 `2023-12-01T00:00:00` 和 `ALIGN '5s'`，时间窗口的对齐时间为 `2023-11-30T23:59:55`、`2023-12-01T00:00:00`、`2023-12-01T00:00:05`、`2023-12-01T00:00:10` 等。 + +这些时间窗口是左闭右开区间，满足条件 `[对齐时间, 对齐时间 + 范围)`。 + +下方的图片可以帮助你更直观的理解时间范围窗口： + +当查询的步频大于时间范围窗口时，数据将只会被计算在一个时间范围窗口中。 + +![align > range](/align_greater_than_range.png) + +当查询的步频小于时间范围窗口时，数据将会被计算在多个时间范围窗口中。 + +![align < range](/align_less_than_range.png) + +### 对齐到特定时间戳 + +对齐时间默认基于当前 SQL 客户端会话的时区。 +你可以将初始对齐时间设置为任何你想要的时间戳。例如，使用 `NOW` 将对齐到当前时间： + +```sql +SELECT + ts, + host, + avg(cpu) RANGE '1w' +FROM monitor +ALIGN '1d' TO NOW BY (host); +``` + +或者使用 `ISO 8601` 时间戳将对齐到指定时间： + +```sql +SELECT + ts, + host, + avg(cpu) RANGE '1w' +FROM monitor +ALIGN '1d' TO '2023-12-01T00:00:00+08:00' BY (host); +``` + +### 填充空值 + +`FILL` 选项可以用来填充数据中的空值。 +例如上面的例子使用了 `LINEAR` 方法来填充空值。 +该选项也支持其他填充空值的方法，例如 `PREV` 和常量值 `X`，更多信息请参考 [FILL OPTION](/reference/sql/range.md#fill-option)。 + +### 语法 + +请参考 [Range Query](/reference/sql/range.md) 获取更多信息。 + +## 表名约束 + +如果你的表名包含特殊字符或大写字母，需要将表名用反引号括起来。 +有关示例，请参阅表创建表文档中的[表名约束](/user-guide/administration/manage-data/basic-table-operations.md#表名约束)部分。 + +## HTTP API + +在 HTTP 请求中使用 `POST` 方法来查询数据： + +```shell +curl -X POST \ + -H 'authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql=select * from monitor' \ +http://localhost:4000/v1/sql?db=public +``` + +结果如下： + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "host", + "data_type": "String" + }, + { + "name": "ts", + "data_type": "TimestampMillisecond" + }, + { + "name": "cpu", + "data_type": "Float64" + }, + { + "name": "memory", + "data_type": "Float64" + } + ] + }, + "rows": [ + ["127.0.0.1", 1667446797450, 0.1, 0.4], + ["127.0.0.1", 1667446798450, 0.5, 0.2], + ["127.0.0.2", 1667446798450, 0.2, 0.3] + ] + } + } + ], + "execution_time_ms": 0 +} +``` + +请参考 [API 文档](/user-guide/protocols/http.md#post-sql-语句)获取更详细的 HTTP 请求的内容。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/view.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/view.md new file mode 100644 index 000000000..29dc6f157 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/query-data/view.md @@ -0,0 +1,148 @@ +--- +description: 介绍了视图的定义、使用示例、更新、显示定义、列出视图和删除视图的方法。 +--- + +# 视图 + +在 SQL 中，视图（View）是基于 SQL 语句的结果集的虚拟表。 +它包含与真实的表一样的行和列。 +每次查询视图时，都会运行该视图的查询。 + +在以下情况下，我们可以使用视图： +* 简化复杂查询，避免每次查询都重复编写和发送复杂语句。 +* 对特定用户开放读取权限，限制一些列和行的读取，保证数据安全和隔离。 + +可以使用 `CREATE VIEW` 语句创建视图。 + +## 视图示例 + +```sql +CREATE VIEW cpu_monitor AS + SELECT cpu, host, ts FROM monitor; +``` + +这个视图的名称是 `cpu_monitor`，在 `AS` 之后的查询语句是用于呈现数据的 SQL 语句。查询视图： + +```sql +SELECT * FROM cpu_monitor; +``` + +结果示例： + +```sql ++------+-----------+---------------------+ +| cpu | host | ts | ++------+-----------+---------------------+ +| 0.5 | 127.0.0.1 | 2023-12-13 02:05:41 | +| 0.3 | 127.0.0.1 | 2023-12-13 02:05:46 | +| 0.4 | 127.0.0.1 | 2023-12-13 02:05:51 | +| 0.3 | 127.0.0.2 | 2023-12-13 02:05:41 | +| 0.2 | 127.0.0.2 | 2023-12-13 02:05:46 | +| 0.2 | 127.0.0.2 | 2023-12-13 02:05:51 | ++------+-----------+---------------------+ +``` + +通过 `WHERE` 查询视图： + +```sql +SELECT * FROM cpu_monitor WHERE host = '127.0.0.2'; +``` + +结果示例： + +```sql ++------+-----------+---------------------+ +| cpu | host | ts | ++------+-----------+---------------------+ +| 0.3 | 127.0.0.2 | 2023-12-13 02:05:41 | +| 0.2 | 127.0.0.2 | 2023-12-13 02:05:46 | +| 0.2 | 127.0.0.2 | 2023-12-13 02:05:51 | ++------+-----------+---------------------+ +``` + +创建一个从两个表联合查询数据的视图： + +```sql +CREATE VIEW app_cpu_monitor AS + SELECT cpu, latency, host, ts FROM monitor LEFT JOIN app_monitor + ON monitor.host = app_monitor.host AND monitor.ts = app_monitor.ts +``` + +然后可以像查询一个单表数据一样查询这个视图： + +```sql +SELECT * FROM app_cpu_monitor WHERE host = 'host1' +``` + +## 更新视图 + +使用 `CREATE OR REPLACE VIEW` 来更新视图，如果视图不存在，则会创建： + +```sql +CREATE OR REPLACE VIEW memory_monitor AS + SELECT memory, host, ts FROM monitor; +``` + +## 显示视图定义 + +通过 `SHOW CREATE VIEW view_name` 语句来显示创建视图的 `CREATE VIEW` 语句： + +```sql +SHOW CREATE VIEW cpu_monitor; +``` + +```sql ++-------------+--------------------------------------------------------------+ +| View | Create View | ++-------------+--------------------------------------------------------------+ +| cpu_monitor | CREATE VIEW cpu_monitor AS SELECT cpu, host, ts FROM monitor | ++-------------+--------------------------------------------------------------+ +``` + +## 列出视图 + +使用 `SHOW VIEWS` 语句查找所有视图： + +```sql +> SHOW VIEWS; + ++----------------+ +| Views | ++----------------+ +| cpu_monitor | +| memory_monitor | ++----------------+ +``` + +当然，像 `SHOW TABLES` 一样，它也支持 `LIKE` 和 `WHERE`： + +```sql +> SHOW VIEWS like 'cpu%'; ++-------------+ +| Views | ++-------------+ +| cpu_monitor | ++-------------+ +1 row in set (0.02 sec) + +> SHOW VIEWS WHERE Views = 'memory_monitor'; ++----------------+ +| Views | ++----------------+ +| memory_monitor | ++----------------+ +``` + +## 删除视图 + +使用 `DROP VIEW` 语句删除视图： + +```sql +DROP VIEW cpu_monitor; +``` + +如果希望在视图不存在时不报错，可以使用： + +```sql +DROP VIEW IF EXISTS test; +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/timezone.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/timezone.md new file mode 100644 index 000000000..a986a19db --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/timezone.md @@ -0,0 +1,48 @@ +--- +description: 介绍了如何在客户端会话中指定时区，并解释了时区设置对数据写入和查询的影响。 +--- + +# 时区 + +你可以在客户端会话中指定时区以方便地管理时间数据。 +客户端会话中指定的时区仅应用在客户端向服务器发送请求时， +不影响存储在 GreptimeDB 服务器中的时间数据。 +GreptimeDB 在数据写入或查询时，会根据指定的时区将时间值从字符串表示转换为日期时间，或转换回来。 + +## 在客户端中指定时区 + +默认情况下，所有客户端使用[默认时区配置](/user-guide/deployments/configuration.md#默认时区配置)，即 UTC。 +你也可以在每个客户端会话中指定时区， +这将覆盖默认的时区配置。 + +### MySQL 客户端 + +- **命令行**：有关通过 MySQL 命令行客户端配置时区的内容，请参阅 MySQL 协议文档中的[时区部分](/user-guide/protocols/mysql.md#时区)。 +- **MySQL driver**：如果你使用的是 Java 或 Go 中的 MySQL driver，请查看 SQL 工具文档的[时区部分](/reference/sql-tools.md#时区)。 + +### PostgreSQL 客户端 + +要配置 PostgreSQL 客户端的时区，请参阅 PostgreSQL 协议文档中的[时区部分](/user-guide/protocols/postgresql.md#时区)。 + +### HTTP API + +使用 HTTP API 时，你可以通过 header 参数指定时区。有关更多信息，请参阅 [HTTP API 文档](/user-guide/protocols/http.md#时区)。 + +### 其他客户端 + +对于其他客户端，你可以更改 GreptimeDB 的[默认时区配置](/user-guide/deployments/configuration.md#默认时区配置)。 + +## 时区对 SQL 语句的影响 + +客户端中的时区设置会影响数据的写入和查询。 + +### 写入数据 + +客户端中设置的时区会影响数据的写入。有关更多信息，请参阅[写入数据](/user-guide/ingest-data/for-iot/sql.md#时区)。 +此外，表 schema 中的默认写入的时间戳值也会受到客户端时区的影响，影响方式与数据写入相同。 + +### 查询数据 + +时区设置也会影响数据的查询。 +有关详细信息，请参阅[查询数据](/user-guide/query-data/sql.md#时区)。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/vectors/vector-type.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/vectors/vector-type.md new file mode 100644 index 000000000..b8d4459fc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-0.11/user-guide/vectors/vector-type.md @@ -0,0 +1,98 @@ +--- +description: 介绍了向量数据类型在 GreptimeDB 中的定义、写入和计算方法，适用于 AI 应用中的特征表示和相似度计算。 +--- + +# 向量数据类型 + +## 概述 + +在人工智能领域，向量是一种重要的数据类型，用于表示数据集中的特征或者样本。向量可以用于许多机器学习和深度学习算法中，如推荐系统、自然语言处理和图像识别。引入向量类型后，GreptimeDB 可以更有效地支持这些 AI 应用，提供强大的向量存储和计算能力。 + +## 基本介绍 + +在 GreptimeDB 中，向量表示为固定维度的 Float32（32位浮点数）数组。创建向量类型列时，必须指定向量的维度，并且维度在定义后不能更改。 + +## 定义向量类型列 + +在 SQL 中，可以通过以下语法来定义包含向量类型的表。需要注意的是，维度 `` 必须是一个正整数，用于定义向量的长度。 + +```sql +CREATE TABLE ( + ... + VECTOR() +); +``` + +例如，定义一个具有维度 3 的向量类型列的表： + +```sql +CREATE TABLE vecs ( + ts TIMESTAMP TIME INDEX, + vec_col VECTOR(3) +); +``` + +## 向量写入 + +在 GreptimeDB 中，你可以通过多种方式将向量数据写入数据库。最简单的方法是使用字符串形式，并通过隐式转换将其存储为向量。字符串需要用方括号 `[]` 包围。以下是使用隐式转换的 SQL 示例： + +```sql +INSERT INTO () VALUES +('[, , ...]'), +('[, , ...]'), +... +('[, , ...]'); +``` + +例如，插入 3 个三维向量： + +```sql +INSERT INTO vecs (ts, vec_col) VALUES +('2024-11-18 00:00:01', '[1.0, 2.0, 3.0]'), +('2024-11-18 00:00:02', '[4.0, 5.0, 6.0]'), +('2024-11-18 00:00:03', '[7.0, 8.0, 9.0]'); +``` + +如果你希望更明确地控制数据转换，可以使用 `parse_vec` 函数来显式地解析字符串为向量： + +```sql +INSERT INTO vecs (ts, vec_col) VALUES +('2024-11-18 00:00:01', parse_vec('[1.0, 2.0, 3.0]')), +('2024-11-18 00:00:02', parse_vec('[4.0, 5.0, 6.0]')), +('2024-11-18 00:00:03', parse_vec('[7.0, 8.0, 9.0]')); +``` + +## 向量计算 + +GreptimeDB 支持多种向量函数，用于计算向量之间的相似度，包括 `vec_l2sq_distance`、`vec_cos_distance` 和 `vec_dot_product`。这些函数在 AI 应用中用于搜索最接近的内容。 + +可以使用以下 SQL 格式执行向量计算： + +```sql +SELECT (, ) FROM
; +``` + +例如，若要查找与给定向量 `[5.0, 5.0, 5.0]` 具有最小平方欧几里得距离的向量，并显示它们之间的距离，可以使用如下查询： + +```sql +SELECT vec_to_string(vec_col), vec_l2sq_distance(vec_col, '[5.0, 5.0, 5.0]') AS distance +FROM vecs +ORDER BY distance; +``` + +执行此查询后，您将得到类似以下的结果： + +``` ++-----------------------------+----------+ +| vec_to_string(vecs.vec_col) | distance | ++-----------------------------+----------+ +| [4,5,6] | 2 | +| [1,2,3] | 29 | +| [7,8,9] | 29 | ++-----------------------------+----------+ +3 rows in set (0.01 sec) +``` + +通过这种方式，GreptimeDB 可以帮助你快速识别和查找相似的数据向量，为 AI 应用提供强大的支持。 + +更多关于向量计算函数的信息，请参阅[向量函数参考文档](/reference/sql/functions/vector.md)。 diff --git a/variables/variables-0.11.ts b/variables/variables-0.11.ts new file mode 100644 index 000000000..1ce8abc15 --- /dev/null +++ b/variables/variables-0.11.ts @@ -0,0 +1,7 @@ +export const variables = { + greptimedbVersion: 'v0.11.0', + prometheusVersion: 'v2.52.0', + nodeExporterVersion: 'v1.8.0', + goSdkVersion: 'v0.5.4', + javaSdkVersion: '0.9.1', +}; diff --git a/variables/variables-nightly.ts b/variables/variables-nightly.ts index e84b327e3..1ce8abc15 100644 --- a/variables/variables-nightly.ts +++ b/variables/variables-nightly.ts @@ -1,5 +1,5 @@ export const variables = { - greptimedbVersion: 'v0.10.2', + greptimedbVersion: 'v0.11.0', prometheusVersion: 'v2.52.0', nodeExporterVersion: 'v1.8.0', goSdkVersion: 'v0.5.4', diff --git a/versioned_docs/version-0.10/index.md b/versioned_docs/version-0.10/index.md index 3659e4550..49b4c945a 100644 --- a/versioned_docs/version-0.10/index.md +++ b/versioned_docs/version-0.10/index.md @@ -24,7 +24,6 @@ Before getting started, please read the following documents that include instruc - [Getting Started][1]: Provides an introduction to GreptimeDB for those who are new to it, including installation and database operations. - [User Guide][2]: For application developers to use GreptimeDB or build custom integration. -- [GreptimeCloud][6]: For users of GreptimeCloud to get started. - [Contributor Guide][3]: For contributor interested in learning more about the technical details and enhancing GreptimeDB as a contributor. - [Roadmap][7]: The latest GreptimeDB roadmap. - [Release Notes][4]: Presents all the historical version release notes. @@ -35,5 +34,4 @@ Before getting started, please read the following documents that include instruc [3]: ./contributor-guide/overview.md [4]: /release-notes [5]: ./faq-and-others/faq.md -[6]: ./greptimecloud/overview.md [7]: https://www.greptime.com/blogs/2024-02-29-greptimedb-2024-roadmap diff --git a/versioned_docs/version-0.11/contributor-guide/datanode/data-persistence-indexing.md b/versioned_docs/version-0.11/contributor-guide/datanode/data-persistence-indexing.md new file mode 100644 index 000000000..adc2ece1e --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/datanode/data-persistence-indexing.md @@ -0,0 +1,83 @@ +--- +description: Explanation of data persistence and indexing in GreptimeDB, including SST file format, indexing methods, and the use of OpenDAL. +--- + +# Data Persistence and Indexing + +Similar to all LSMT-like storage engines, data in MemTables is persisted to durable storage, for example, the local disk file system or object storage service. GreptimeDB adopts [Apache Parquet][1] as its persistent file format. + +## SST File Format + +Parquet is an open source columnar format that provides fast data querying and has already been adopted by many projects, such as Delta Lake. + +Parquet has a hierarchical structure like "row groups-columns-data pages". Data in a Parquet file is horizontally partitioned into row groups, in which all values of the same column are stored together to form a data page. Data page is the minimal storage unit. This structure greatly improves performance. + +First, clustering data by column makes file scanning more efficient, especially when only a few columns are queried, which is very common in analytical systems. + +Second, data of the same column tends to be homogeneous which helps with compression when apply techniques like dictionary and Run-Length Encoding (RLE). + +![Parquet file format](/parquet-file-format.png) + +## Data Persistence + +GreptimeDB provides a configuration item `storage.flush.global_write_buffer_size`, which is flush threshold of the total memory usage for all MemTables. + +When the size of data buffered in MemTables reaches that threshold, GreptimeDB will pick MemTables and flush them to SST files. + +## Indexing Data in SST Files + +Apache Parquet file format provides inherent statistics in headers of column chunks and data pages, which are used for pruning and skipping. + +![Column chunk header](/column-chunk-header.png) + +For example, in the above Parquet file, if you want to filter rows where `name` = `Emily`, you can easily skip row group 0 because the max value for `name` field is `Charlie`. This statistical information reduces IO operations. + +## Index Files + +For each SST file, GreptimeDB not only maintains an internal index but also generates a separate file to store the index structures specific to that SST file. + +The index files utilize the [Puffin][3] format, which offers significant flexibility, allowing for the storage of additional metadata and supporting a broader range of index structures. + +![Puffin](/puffin.png) + +Currently, the inverted index is the first supported index structure, and it is stored within the index file as a Blob. + +## Inverted Index + +In version 0.7, GreptimeDB introduced the inverted index to accelerate queries. + +The inverted index is a common index structure used for full-text searches, mapping each word in the document to a list of documents containing that word. Greptime has adopted this technology, which originates from search engines, for use in the time series databases. + +Search engines and time series databases operate in separate domains, yet the principle behind the applied inverted index technology is similar. This similarity requires some conceptual adjustments: +1. Term: In GreptimeDB, it refers to the column value of the time series. +2. Document: In GreptimeDB, it refers to the data segment containing multiple time series. + +The inverted index enables GreptimeDB to skip data segments that do not meet query conditions, thus improving scanning efficiency. + +![Inverted index searching](/inverted-index-searching.png) + +For instance, the query above uses the inverted index to identify data segments where `job` equals `apiserver`, `handler` matches the regex `.*users`, and `status` matches the regex `4...`. It then scans these data segments to produce the final results that meet all conditions, significantly reducing the number of IO operations. + +### Inverted Index Format + +![Inverted index format](/inverted-index-format.png) + +GreptimeDB builds inverted indexes by column, with each inverted index consisting of an FST and multiple Bitmaps. + +The FST (Finite State Transducer) enables GreptimeDB to store mappings from column values to Bitmap positions in a compact format and provides excellent search performance and supports complex search capabilities (such as regular expression matching). The Bitmaps maintain a list of data segment IDs, with each bit representing a data segment. + +### Index Data Segments + +GreptimeDB divides an SST file into multiple indexed data segments, with each segment housing an equal number of rows. This segmentation is designed to optimize query performance by scanning only the data segments that match the query conditions. + +For example, if a data segment contains 1024 rows and the list of data segments identified through the inverted index for the query conditions is `[0, 2]`, then only the 0th and 2nd data segments in the SST file—from rows 0 to 1023 and 2048 to 3071, respectively—need to be scanned. + +The number of rows in a data segment is controlled by the engine option `index.inverted_index.segment_row_count`, which defaults to `1024`. A smaller value means more precise indexing and often results in better query performance but increases the cost of index storage. By adjusting this option, a balance can be struck between storage costs and query performance. + +## Unified Data Access Layer: OpenDAL + +GreptimeDB uses [OpenDAL][2] to provide a unified data access layer, thus, the storage engine does not need to interact with different storage APIs, and data can be migrated to cloud-based storage like AWS S3 seamlessly. + +[1]: https://parquet.apache.org +[2]: https://github.com/datafuselabs/opendal +[3]: https://iceberg.apache.org/puffin-spec diff --git a/versioned_docs/version-0.11/contributor-guide/datanode/metric-engine.md b/versioned_docs/version-0.11/contributor-guide/datanode/metric-engine.md new file mode 100644 index 000000000..f72f9045b --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/datanode/metric-engine.md @@ -0,0 +1,43 @@ +--- +description: Overview of the Metric engine in GreptimeDB, its concepts, architecture, and design for handling small tables. +--- + +# Metric Engine + +## Overview + +The `Metric` engine is a component of GreptimeDB, and it's an implementation of the storage engine. It mainly targets scenarios with a large number of small tables for observable metrics. + +Its main feature is to use synthetic physical wide tables to store a large amount of small table data, achieving effects such as reuse of the same column and metadata. This reduces storage overhead for small tables and improves columnar compression efficiency. The concept of a table becomes even more lightweight under the `Metric` engine. + +## Concepts + +The `Metric` engine introduces two new concepts: "logical table" and "physical table". From the user's perspective, logical tables are exactly like ordinary ones. From a storage point-of-view, physical Regions are just regular Regions. + +### Logical Table + +A logical table refers to user-defined tables. Just like any other ordinary table, its definition includes the name of the table, column definitions, index definitions etc. All operations such as queries or write-ins by users are based on these logical tables. Users don't need to worry about differences between logical and ordinary tables during usage. + +From an implementation standpoint, a logical table is virtual; it doesn't directly read or write physical data but maps read/write requests into corresponding requests for physical tables in order to implement data storage and querying. + +### Physical Table + +A physical table is a table that actually stores data, possessing several physical Regions defined by partition rules. + +## Architecture and Design + +The main design architecture of the `Metric` engine is as follows: + +![Arch](/metric-engine-arch.png) + +In the current version implementation, the `Metric` engine reuses the `Mito` engine to achieve storage and query capabilities for physical data. It also provides access to both physical tables and logical tables simultaneously. + +Regarding partitioning, logical tables have identical partition rules and Region distribution as physical tables. This makes sense because the data of logical tables are directly stored in physical tables, so their partition rules are consistent. + +Concerning routing metadata, the routing address of a logical table is a logical address - what its corresponding physical table is - then through this physical table for secondary routing to obtain the real physical address. This indirect routing method can significantly reduce the number of metadata modifications required when Region migration scheduling occurs in Metric engines. + +Operationally speaking, The `Metric` engine only supports limited operations on physical tables to prevent misoperations such as prohibiting writing into or deleting from a physical table which could affect user's logic-table data. Generally speaking, users can consider that they have read-only access to these physical tables. + +To improve performance during simultaneous DDL (Data Definition Language) operations on many tables, the 'Metric' engine has introduced some batch DDL operations. These batch DDL operations can merge lots of DDL actions into one request thereby reducing queries and modifications times for metadata thus enhancing performance. This feature is particularly beneficial in scenarios such as the automatic creation requests brought about by large amounts of metrics during Prometheus Remote Write cold start-up, as well as the modification requests for numerous route-tables mentioned earlier during migration of many physical regions. + +Apart from physical data regions belonging to physical tables, the 'Metric' engine creates an additional metadata region physically for each individual physical data region used in storing some metadata needed by itself while maintaining mapping and other states. This metadata includes the mapping relationship between logical tables and physical tables, the mapping relationship between logical columns and physical columns etc. diff --git a/versioned_docs/version-0.11/contributor-guide/datanode/overview.md b/versioned_docs/version-0.11/contributor-guide/datanode/overview.md new file mode 100644 index 000000000..17e8567b7 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/datanode/overview.md @@ -0,0 +1,33 @@ +--- +description: Overview of Datanode in GreptimeDB, its responsibilities, components, and interaction with other parts of the system. +--- + +# Overview + +## Introduction + +`Datanode` is mainly responsible for storing the actual data for GreptimeDB. As we know, in GreptimeDB, +a `table` can have one or more `Region`s, and `Datanode` is responsible for managing the reading and writing +of these `Region`s. `Datanode` is not aware of `table` and can be considered as a `region server`. Therefore, +`Frontend` and `Metasrv` operate `Datanode` at the granularity of `Region`. + +![Datanode](/datanode.png) + +## Components + +A `Datanode` contains all the components needed for a `region server`. Here we list some of the vital parts: + +- A gRPC service is provided for reading and writing region data, and `Frontend` uses this service + to read and write data from `Datanode`s. +- An HTTP service, through which you can obtain metrics, configuration information, etc., of the current node. +- `Heartbeat Task` is used to send heartbeat to the `Metasrv`. The heartbeat plays a crucial role in the + distributed architecture of GreptimeDB and serves as a basic communication channel for distributed coordination. + The upstream heartbeat messages contain important information such as the workload of a `Region`. If the + `Metasrv `has made scheduling(such as `Region` migration) decisions, it will send instructions to the + `Datanode` via downstream heartbeat messages. +- The `Datanode` does not include components like the `Physical Planner`, `Optimizer`, etc. (these are placed in + the `Frontend`). The user's query requests for one or more `Table`s will be transformed into `Region` query + requests in the `Frontend`. The `Datanode` is responsible for handling these `Region` query requests. +- A `Region Manager` is used to manage all `Region`s on a `Datanode`. +- GreptimeDB supports a pluggable multi-engine architecture, with existing engines including `File Engine` and + `Mito Engine`. diff --git a/versioned_docs/version-0.11/contributor-guide/datanode/python-scripts.md b/versioned_docs/version-0.11/contributor-guide/datanode/python-scripts.md new file mode 100644 index 000000000..8845770ba --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/datanode/python-scripts.md @@ -0,0 +1,34 @@ +--- +description: Guide on using Python scripts for data analysis in GreptimeDB, including backend options and setup instructions. +--- + +# Python Scripts + +## Introduction + +Python scripts are methods for analyzing data in GreptimeDB, +by running it in the database directly instead of fetching all the data from the database and running it locally. +This approach saves a lot of data transfer costs. +The image below depicts how the script works. +The `RecordBatch` (which is basically a column in a table with type and nullability metadata) +can come from anywhere in the database, +and the returned `RecordBatch` can be annotated in Python grammar to indicate its metadata, +such as type or nullability. +The script will do its best to convert the returned object to a `RecordBatch`, +whether it is a Python list, a `RecordBatch` computed from parameters, +or a constant (which is extended to the same length as the input arguments). + +![Python Coprocessor](/python-coprocessor.png) + +## Two optional backends + +### CPython Backend powered by PyO3 + +This backend is powered by [PyO3](https://pyo3.rs/v0.18.1/), enabling the use of your favourite Python libraries (such as NumPy, Pandas, etc.) and allowing Conda to manage your Python environment. + +But using it also involves some complications. You must set up the correct Python shared library, which can be a bit challenging. In general, you just need to install the `python-dev` package. However, if you are using Homebrew to install Python on macOS, you must create a proper soft link to `Library/Frameworks/Python.framework`. Detailed instructions on using PyO3 crate with different Python Version can be found [here](https://pyo3.rs/v0.18.1/building_and_distribution#configuring-the-python-version) + +### Embedded RustPython Interpreter + +An experiment [python interpreter](https://github.com/RustPython/RustPython) to run +the coprocessor script, it supports Python 3.10 grammar. You can use all the very Python syntax, see [User Guide/Python Coprocessor](/user-guide/python-scripts/overview.md) for more! diff --git a/versioned_docs/version-0.11/contributor-guide/datanode/query-engine.md b/versioned_docs/version-0.11/contributor-guide/datanode/query-engine.md new file mode 100644 index 000000000..beca4d4b0 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/datanode/query-engine.md @@ -0,0 +1,65 @@ +--- +description: Overview of GreptimeDB's query engine, its architecture, data representation, indexing, and extensibility. +--- + +# Query Engine + +## Introduction + +GreptimeDB's query engine is built on [Apache DataFusion][1] (subproject under [Apache +Arrow][2]), a brilliant query engine written in Rust. It provides a set of well functional components from +logical plan, physical plan and the execution runtime. Below explains how each component is orchestrated and their positions during execution. + +![Execution Procedure](/execution-procedure.png) + +The entry point is the logical plan, which is used as the general intermediate representation of a +query or execution logic etc. Two noticeable sources of logical plan are from: 1. the user query, like +SQL through SQL parser and planner; 2. the Frontend's distributed query, which is explained in details in the following section. + +Next is the physical plan, or the execution plan. Unlike the logical plan which is a big +enumeration containing all the logical plan variants (except the special extension plan node), the +physical plan is in fact a trait that defines a group of methods invoked during +execution. All data processing logics are packed in corresponding structures that +implement the trait. They are the actual operations performed on the data, like +aggregator `MIN` or `AVG`, and table scan `SELECT ... FROM`. + +The optimization phase which improves execution performance by transforming both logical and physical plans, is now all based on rules. It is also called, "Rule Based Optimization". Some of the rules are DataFusion native and others are customized in Greptime DB. In the future, we plan to add more +rules and leverage the data statistics for Cost Based Optimization/CBO. + +The last phase "execute" is a verb, stands for the procedure that reads data from storage, performs +calculations and generates the expected results. Although it's more abstract than previously mentioned concepts, you can just +simply imagine it as executing a Rust async function. And it's indeed a future (stream). + +`EXPLAIN [VERBOSE] ` is very useful if you want to see how your SQL is represented in the logical or physical plan. + +## Data Representation + +GreptimeDB uses [Apache Arrow][2] as the in-memory data representation. It's column-oriented, in +cross-platform format, and also contains many high-performance data operators. These features +make it easy to share data in many different environments and implement calculation logic. + +## Indexing + +In time series data, there are two important dimensions: timestamp and tag columns (or like +primary key in a general relational database). GreptimeDB groups data in time buckets, so it's efficient +to locate and extract data within the expected time range at a very low cost. The mainly used persistent file format [Apache Parquet][3] in GreptimeDB helps a lot -- it +provides multi-level indices and filters that make it easy to prune data during querying. In the future, we +will make more use of this feature, and develop our separated index to handle more complex use cases. + +## Extensibility + + + +Extending operations in GreptimeDB is extremely simple. You can implement your operator like [this][5]. + +## Distributed Execution + +Covered in [Distributed Querying][6]. + +[1]: https://github.com/apache/arrow-datafusion +[2]: https://arrow.apache.org/ +[3]: https://parquet.apache.org +[4]: python-scripts.md +[5]: https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-write-aggregate-function.md +[6]: ../frontend/distributed-querying.md diff --git a/versioned_docs/version-0.11/contributor-guide/datanode/storage-engine.md b/versioned_docs/version-0.11/contributor-guide/datanode/storage-engine.md new file mode 100644 index 000000000..0b969db67 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/datanode/storage-engine.md @@ -0,0 +1,64 @@ +--- +description: Overview of the storage engine in GreptimeDB, its architecture, components, and data model. +--- + +# Storage Engine + +## Introduction + +The `storage engine` is responsible for storing the data of the database. Mito, based on [LSMT][1] (Log-structured Merge-tree), is the storage engine we use by default. We have made significant optimizations for handling time-series data scenarios, so mito engine is not suitable for general purposes. + +## Architecture + +The picture below shows the architecture and process procedure of the storage engine. + +![Architecture](/storage-engine-arch.png) + +The architecture is the same as a traditional LSMT engine: + +- [WAL][2] + - Guarantees high durability for data that is not yet being flushed. + - Based on the `Log Store` API, thus it doesn't care about the underlying storage + media. + - Log records of the WAL can be stored in the local disk, or a distributed log service which + implements the `Log Store` API. +- Memtables: + - Data is written into the `active memtable`, aka `mutable memtable` first. + - When a `mutable memtable` is full, it will be changed to a `read-only memtable`, aka `immutable memtable`. +- SST + - The full name of SST, aka SSTable is `Sorted String Table`. + - `Immutable memtable` is flushed to persistent storage and produces an SST file. +- Compactor + - Small `SST` is merged into large `SST` by the compactor via compaction. + - The default compaction strategy is [TWCS][3]. +- Manifest + - The manifest stores the metadata of the engine, such as the metadata of the `SST`. +- Cache + - Speed up queries. + +[1]: https://en.wikipedia.org/wiki/Log-structured_merge-tree +[2]: https://en.wikipedia.org/wiki/Write-ahead_logging +[3]: https://cassandra.apache.org/doc/latest/cassandra/operating/compaction/twcs.html + +## Data Model + +The data model provided by the storage engine is between the `key-value` model and the tabular model. + +```txt +tag-1, ..., tag-m, timestamp -> field-1, ..., field-n +``` + +Each row of data contains multiple tag columns, one timestamp column, and multiple field columns. +- `0 ~ m` tag columns + - Tag columns can be nullable. + - Specified during table creation using `PRIMARY KEY`. +- Must include one timestamp column + - Timestamp column cannot be null. + - Specified during table creation using `TIME INDEX`. +- `0 ~ n` field columns + - Field columns can be nullable. +- Data is sorted by tag columns and timestamp column. + +### Region + +Data in the storage engine is stored in `regions`, which are logical isolated storage units within the engine. Rows within a `region` must have the same `schema`, which defines the tag columns, timestamp column, and field columns within the `region`. The data of tables in the database is stored in one or multiple `regions`. diff --git a/versioned_docs/version-0.11/contributor-guide/datanode/wal.md b/versioned_docs/version-0.11/contributor-guide/datanode/wal.md new file mode 100644 index 000000000..995fa4ae7 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/datanode/wal.md @@ -0,0 +1,35 @@ +--- +description: Introduction to Write-Ahead Logging (WAL) in GreptimeDB, its purpose, architecture, and operational modes. +--- + +# Write-Ahead Logging + +## Introduction + +Our storage engine is inspired by the Log-structured Merge Tree (LSMT). Mutating operations are +applied to a MemTable instead of persisting to disk, which significantly improves performance but +also brings durability-related issues, especially when the Datanode crashes unexpectedly. Similar +to all LSMT-like storage engines, GreptimeDB uses a write-ahead log (WAL) to ensure data durability +and is safe from crashing. + +WAL is an append-only file group. All `INSERT`, `UPDATE` and `DELETE` operations are transformed into +operation entries and then appended to WAL. Once operation entries are persisted to the underlying +file, the operation can be further applied to MemTable. + +When the Datanode restarts, operation entries in WAL are replayed to reconstruct the correct +in-memory state. + +![WAL in Datanode](/wal.png) + +## Namespace + +Namespace of WAL is used to separate entries from different tables (different regions). Append and +read operations must provide a Namespace. Currently, region ID is used as the Namespace, because +each region has a MemTable that needs to be reconstructed when Datanode restarts. + +## Synchronous/Asynchronous flush + +By default, appending to WAL is asynchronous, which means the writer will not wait until entries are +flushed to disk. This setting provides higher performance, but may lose data when running host shutdown unexpectedly. In the other hand, synchronous flush provides higher durability at the cost of performance. + +In v0.4 version, the new region worker architecture can use batching to alleviate the overhead of sync flush. diff --git a/versioned_docs/version-0.11/contributor-guide/flownode/arrangement.md b/versioned_docs/version-0.11/contributor-guide/flownode/arrangement.md new file mode 100644 index 000000000..5b0ed5f57 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/flownode/arrangement.md @@ -0,0 +1,19 @@ +--- +description: Details on the arrangement component in Flownode, which stores state and update streams for querying and updating. +--- + +# Arrangement + +Arrangement stores the state in the dataflow's process. It stores the streams of update flows for further querying and updating. + +The arrangement essentially stores key-value pairs with timestamps to mark their change time. + +Internally, the arrangement receives tuples like +`((Key Row, Value Row), timestamp, diff)` and stores them in memory. One can query key-value pairs at a certain time using the `get(now: Timestamp, key: Row)` method. +The arrangement also assumes that everything older than a certain time (also known as the low watermark) has already been ingested to the sink tables and does not keep a history for them. + +:::tip NOTE + +The arrangement allows for the removal of keys by setting the `diff` to -1 in incoming tuples. Moreover, if a row has been previously added to the arrangement and the same key is inserted with a different value, the original value is overwritten with the new value. + +::: diff --git a/versioned_docs/version-0.11/contributor-guide/flownode/dataflow.md b/versioned_docs/version-0.11/contributor-guide/flownode/dataflow.md new file mode 100644 index 000000000..90e14286b --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/flownode/dataflow.md @@ -0,0 +1,16 @@ +--- +description: Explanation of the dataflow module in Flownode, its operations, internal data handling, and future enhancements. +--- + +# Dataflow + +The `dataflow` module (see `flow::compute` module) is the core computing module of `flow`. +It takes a SQL query and transforms it into flow's internal execution plan. +This execution plan is then rendered into an actual dataflow, which is essentially a directed acyclic graph (DAG) of functions with input and output ports. +The dataflow is triggered to run when needed. + +Currently, this dataflow only supports `map` and `reduce` operations. Support for `join` operations will be added in the future. + +Internally, the dataflow handles data in row format, using a tuple `(row, time, diff)`. Here, `row` represents the actual data being passed, which may contain multiple `Value` objects. +`time` is the system time which tracks the progress of the dataflow, and `diff` typically represents the insertion or deletion of the row (+1 or -1). +Therefore, the tuple represents the insert/delete operation of the `row` at a given system `time`. \ No newline at end of file diff --git a/versioned_docs/version-0.11/contributor-guide/flownode/overview.md b/versioned_docs/version-0.11/contributor-guide/flownode/overview.md new file mode 100644 index 000000000..040a6b1d2 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/flownode/overview.md @@ -0,0 +1,21 @@ +--- +description: Overview of Flownode, a component providing streaming process capabilities to the database, including its components and current limitations. +--- + +# Overview + +## Introduction + + +`Flownode` provides a simple streaming process (known as `flow`) ability to the database. +`Flownode` manages `flows` which are tasks that receive data from the `source` and send data to the `sink`. + +In current version, `Flownode` only supports standalone mode. In the future, we will support distributed mode. + +## Components + +A `Flownode` contains all the components needed for the streaming process of a flow. Here we list the vital parts: + +- A `FlownodeManager` for receiving inserts forwarded from the `Frontend` and sending back results for the flow's sink table. +- A certain number of `FlowWorker` instances, each running in a separate thread. Currently for standalone mode, there is only one flow worker, but this may change in the future. +- A `Flow` is a task that actively receives data from the `source` and sends data to the `sink`. It is managed by the `FlownodeManager` and run by a `FlowWorker`. \ No newline at end of file diff --git a/versioned_docs/version-0.11/contributor-guide/frontend/distributed-querying.md b/versioned_docs/version-0.11/contributor-guide/frontend/distributed-querying.md new file mode 100644 index 000000000..a1d7b4d13 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/frontend/distributed-querying.md @@ -0,0 +1,32 @@ +--- +description: Describes the process of distributed querying in GreptimeDB, focusing on the dist planner and dist plan. +--- + +# Distributed Querying + +Most steps of querying in frontend and datanode are identical. The only difference is that +Frontend have a "special" step in planning phase to make the logical query plan distributed. +Let's reference it as "dist planner" in the following text. + +The modified, distributed logical plan has multiple stages, each of them is executed in different +server node. + +![Frontend query](/frontend-query.png) + +## Dist Planner + +Planner will traverse the input logical plan, and split it into multiple stages by the "[commutativity +rule](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/rfcs/2023-05-09-distributed-planner.md)". + +This rule is under heavy development. At present it will consider things like: +- whether the operator itself is commutative +- how the partition rule is configured +- etc... + +## Dist Plan + +Except the first stage, which have to read data from files in storage. All other stages' leaf node +are actually a gRPC call to its previous stage. + +Sub-plan in a stage is itself a complete logical plan, and can be executed independently without +the follow up stages. The plan is encoded in [substrait format](https://substrait.io). diff --git a/versioned_docs/version-0.11/contributor-guide/frontend/overview.md b/versioned_docs/version-0.11/contributor-guide/frontend/overview.md new file mode 100644 index 000000000..82b2a3c72 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/frontend/overview.md @@ -0,0 +1,25 @@ +--- +description: Provides an overview of the Frontend component in GreptimeDB, its roles, and typical deployment in the cloud. +--- + +# Overview + +The `Frontend` executes requests from clients, and performs some tasks in the cloud +, like tenant management, authorization validation, flow control, etc. + +The `Frontend` can expose multiple endpoints for reading and writing data in various protocols. You +can refer to [Protocols][1] for more details. + +The following picture shows a typical deployment of GreptimeDB in the cloud. The `Frontend` instances +form a cluster to serve the requests from clients: + +![frontend](/frontend.png) + +## Details + +- [Table Sharding][2] +- [Distributed Querying][3] + +[1]: /user-guide/protocols/overview.md +[2]: ./table-sharding.md +[3]: ./distributed-querying.md diff --git a/versioned_docs/version-0.11/contributor-guide/frontend/table-sharding.md b/versioned_docs/version-0.11/contributor-guide/frontend/table-sharding.md new file mode 100644 index 000000000..8b11641ab --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/frontend/table-sharding.md @@ -0,0 +1,54 @@ +--- +description: Explains how table data in GreptimeDB is sharded and distributed, including the concepts of partition and region. +--- + +# Table Sharding + +The sharding of stored data is essential to any distributed database. This document will describe how table's data in GreptimeDB is being sharded, and distributed. + +## Partition + +For the syntax of creating a partitioned table, please refer to the [Table Sharding](/user-guide/administration/manage-data/table-sharding.md) section in the User Guide. + +## Region + +The data within a table is logically split after creating partitions. You may ask the question " +how are the data, after being logically partitioned, stored in the GreptimeDB? The answer is in "`Region`"s. + +Each region is corresponding to a partition, and stores the data in the partition. The regions are distributed among +`Datanode`s. Our +`metasrv` will move regions among Datanodes automatically, according to the states of Datanodes. +Also, `metasrv` can split or merge regions according to their data volume or access pattern. + +The relationship between partition and region can be viewed as the following diagram: + +```text + ┌───────┐ + │ │ + │ Table │ + │ │ + └───┬───┘ + │ + Range [Start, end) │ Horizontally Split Data + ┌──────────────────┼──────────────────┐ + │ │ │ + │ │ │ + ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ + │ │ │ │ │ │ + │ Partition │ │ Partition │ │ Partition │ + │ │ │ │ │ │ + │ P0 │ │ P1 │ │ Px │ + └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ + │ │ │ + │ │ │ One-to-one mapping of +┌───────┼──────────────────┼───────┐ │ Partition and Region +│ │ │ │ │ +│ ┌─────▼─────┐ ┌─────▼─────┐ │ ┌─────▼─────┐ +│ │ │ │ │ │ │ │ +│ │ Region │ │ Region │ │ │ Region │ +│ │ │ │ │ │ │ │ +│ │ R0 │ │ R1 │ │ │ Ry │ +│ └───────────┘ └───────────┘ │ └───────────┘ +│ │ +└──────────────────────────────────┘ + Could be placed in one Datanode diff --git a/versioned_docs/version-0.11/contributor-guide/getting-started.md b/versioned_docs/version-0.11/contributor-guide/getting-started.md new file mode 100644 index 000000000..5fb90a887 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/getting-started.md @@ -0,0 +1,69 @@ +--- +description: Instructions for setting up and running GreptimeDB from source, including prerequisites, build dependencies, and running unit tests. +--- + +# Getting started + +This page describes how to run GreptimeDB from source in your local environment. + +## Prerequisite + +### System & Architecture + +At the moment, GreptimeDB supports Linux(both amd64 and arm64), macOS (both amd64 and Apple Silicone) and Windows. + +### Build Dependencies + +- [Git](https://git-scm.com/book/en/v2/Getting-Started-The-Command-Line) (optional) +- C/C++ Toolchain: provides essential tools for compiling and linking. This is available either as `build-essential` on ubuntu or a similar name on other platforms. +- Rust ([guide][1]) + - Compile the source code +- Protobuf ([guide][2]) + - Compile the proto file + - Note that the version needs to be >= 3.15. You can check it with `protoc --version` +- Machine: Recommended memory is 16GB or more, or use the [mold](https://github.com/rui314/mold) tool to reduce memory usage during linking. + +[1]: +[2]: + +## Compile and Run + +Start GreptimeDB standalone instance in just a few commands! + +```shell +git clone https://github.com/GreptimeTeam/greptimedb.git +cd greptimedb +cargo run -- standalone start +``` + +Next, you can choose the protocol you like to interact with in GreptimeDB. + +Or if you just want to build the server without running it: + +```shell +cargo build # --release +``` + +The artifacts can be found under `$REPO/target/debug` or `$REPO/target/release`, depending on the build mode (whether the `--release` option is passed) + +## Unit test + +GreptimeDB is well-tested, the entire unit test suite is shipped with source code. To test them, run with [nextest](https://nexte.st/index.html). + +To install nextest using cargo, run: + +```shell +cargo install cargo-nextest --locked +``` + +Or you can check their [docs](https://nexte.st/docs/installation/pre-built-binaries/) for other ways to install. + +After nextest is ready, you can run the test suite with: + +```shell +cargo nextest run +``` + +## Docker + +We also provide pre-build binary via Docker. It's which is available in dockerhub: [https://hub.docker.com/r/greptime/greptimedb](https://hub.docker.com/r/greptime/greptimedb) diff --git a/versioned_docs/version-0.11/contributor-guide/how-to/how-to-trace-greptimedb.md b/versioned_docs/version-0.11/contributor-guide/how-to/how-to-trace-greptimedb.md new file mode 100644 index 000000000..a87a257b0 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/how-to/how-to-trace-greptimedb.md @@ -0,0 +1,79 @@ +--- +description: Describes how to use Rust's tracing framework in GreptimeDB for distributed tracing, including defining tracing context in RPC, passing it, and instrumenting code. +--- + +# How to trace GreptimeDB + +GreptimeDB uses Rust's [tracing](https://docs.rs/tracing/latest/tracing/) framework for code instrument. For the specific details and usage of tracing, please refer to the official documentation of tracing. + +By transparently transmitting `trace_id` and other information on the entire distributed system, we can record the function call chain of the entire distributed link, know the time of each tracked function take and other related information, so as to monitor the entire system. + +## Define tracing context in RPC + +Because the tracing framework does not natively support distributed tracing, we need to manually pass information such as `trace_id` in the RPC message to correctly identify the function calling relationship. We use standards based on [w3c](https://www.w3.org/TR/trace-context/#traceparent-header-field-values) to encode relevant information into `tracing_context` and attach the message to the RPC header. Mainly defined in: + +- `frontend` interacts with `datanode`: `tracing_context` is defined in [`RegionRequestHeader`](https://github.com/GreptimeTeam/greptime-proto/blob/main/proto/greptime/v1/region/server.proto) +- `frontend` interacts with `metasrv`: `tracing_context` is defined in [`RequestHeader`](https://github.com/GreptimeTeam/greptime-proto/blob/main/proto/greptime/v1/meta/common.proto) +- Client interacts with `frontend`: `tracing_context` is defined in [`RequestHeader`](https://github.com/GreptimeTeam/greptime-proto/blob/main/proto/greptime/v1/common.proto) + +## Pass tracing context in RPC call + +We build a `TracingContext` structure that encapsulates operations related to the tracing context. [Related code](https://github.com/GreptimeTeam/greptimedb/blob/main/src/common/telemetry/src/tracing_context.rs) + +GreptimeDB uses `TracingContext::from_current_span()` to obtain the current tracing context, uses the `to_w3c()` method to encode the tracing context into a w3c-compliant format, and attaches it to the RPC message, so that the tracing context is correctly distributed passed within the component. + +The following example illustrates how to obtain the current tracing context and pass the parameters correctly when constructing the RPC message, so that the tracing context is correctly passed among the distributed components. + + +```rust +let request = RegionRequest { + header: Some(RegionRequestHeader { + tracing_context: TracingContext::from_current_span().to_w3c(), + ..Default::default() + }), + body: Some(region_request::Body::Alter(request)), +}; +``` + +On the receiver side of the RPC message, the tracing context needs to be correctly decoded and used to build the first `span` to trace the function call. For example, the following code will correctly decode the `tracing_context` in the received RPC message using the `TracingContext::from_w3c` method. And use the `attach` method to attach the context message to the newly created `info_span!("RegionServer::handle_read")`, so that the call can be tracked across distributed components. + +```rust +... +let tracing_context = request + .header + .as_ref() + .map(|h| TracingContext::from_w3c(&h.tracing_context)) + .unwrap_or_default(); +let result = self + .handle_read(request) + .trace(tracing_context.attach(info_span!("RegionServer::handle_read"))) + .await?; +... +``` + +## Use `tracing::instrument` to instrument the code + +We use the `instrument` macro provided by tracing to instrument the code. We only need to annotate the `instrument` macro in the function that needs to be instrument. The `instrument` macro will print every function parameter on each function call into the span in the form of `Debug`. For parameters that do not implement the `Debug` trait, or the structure is too large and has too many parameters, resulting in a span that is too large. If you want to avoid these situations, you need to use `skip_all` to skip printing all parameters. + +```rust +#[tracing::instrument(skip_all)] +async fn instrument_function(....) { + ... +} +``` + +## Code instrument across runtime + +Rust's tracing library will automatically handle the nested relationship between instrument functions in the same runtime, but if a function call across the runtime, tracing library cannot automatically trace such calls, and we need to manually pass the context across the runtime. + +```rust +let tracing_context = TracingContext::from_current_span(); +let handle = runtime.spawn(async move { + handler + .handle(query) + .trace(tracing_context.attach(info_span!("xxxxx"))) + ... +}); +``` + +For example, the above code needs to perform tracing across runtimes. We first obtain the current tracing context through `TracingContext::from_current_span()`, create a span in another runtime, and attach the span to the current context, and we are done. The hidden code points that span the runtime are eliminated, and the call chain is correctly traced. \ No newline at end of file diff --git a/versioned_docs/version-0.11/contributor-guide/how-to/how-to-use-tokio-console.md b/versioned_docs/version-0.11/contributor-guide/how-to/how-to-use-tokio-console.md new file mode 100644 index 000000000..c22f174b6 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/how-to/how-to-use-tokio-console.md @@ -0,0 +1,34 @@ +--- +description: Guides on using tokio-console in GreptimeDB, including building with specific features and connecting to the tokio console subscriber. +--- + +# How to use tokio-console in GreptimeDB + +This document introduces how to use the [tokio-console](https://github.com/tokio-rs/console) in GreptimeDB. + +First, build GreptimeDB with feature `cmd/tokio-console`. Also the `tokio_unstable` cfg must be enabled: + +```bash +RUSTFLAGS="--cfg tokio_unstable" cargo build -F cmd/tokio-console +``` + +Then start GreptimeDB with tokio console binding address config: `--tokio-console-addr`. Remember to run with +the `tokio_unstable` cfg. For example: + +```bash +RUSTFLAGS="--cfg tokio_unstable" greptime --tokio-console-addr="127.0.0.1:6669" standalone start +``` + +Now you can use `tokio-console` to connect to GreptimeDB's tokio console subscriber: + +```bash +tokio-console [TARGET_ADDR] +``` + +"TARGET_ADDR" defaults to "\". + +:::tip Note + +You can refer to [tokio-console](https://github.com/tokio-rs/console) to see the installation of `tokio-console`. + +::: diff --git a/versioned_docs/version-0.11/contributor-guide/how-to/how-to-write-sdk.md b/versioned_docs/version-0.11/contributor-guide/how-to/how-to-write-sdk.md new file mode 100644 index 000000000..1bd5f08bf --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/how-to/how-to-write-sdk.md @@ -0,0 +1,76 @@ +--- +description: Explains how to write a gRPC SDK for GreptimeDB, focusing on the GreptimeDatabase service, its methods, and the structure of requests and responses. +--- + +# How to write a gRPC SDK for GreptimeDB + +A GreptimeDB gRPC SDK only needs to handle the writes. The reads are standard SQL and PromQL, can be handled by any JDBC +client or Prometheus client. This is also why GreptimeDB gRPC SDKs are all named +like "`greptimedb-ingester-`". Please make sure your GreptimeDB SDK follow the same naming convention. + +## `GreptimeDatabase` Service + +GreptimeDB defines a custom gRPC service called `GreptimeDatabase`. All you need to do in your SDK are implement it. You +can find its Protobuf +definitions [here](https://github.com/GreptimeTeam/greptime-proto/blob/main/proto/greptime/v1/database.proto). + +The service contains two RPC methods: + +```protobuf +service GreptimeDatabase { + rpc Handle(GreptimeRequest) returns (GreptimeResponse); + + rpc HandleRequests(stream GreptimeRequest) returns (GreptimeResponse); +} +``` + +The `Handle` method is for unary call: when a `GreptimeRequest` is received and processed by a GreptimeDB +server, it responds with a `GreptimeResponse` immediately. + +The `HandleRequests` acts in +a "[Client streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#client-streaming-rpc)" style. It ingests a +stream of `GreptimeRequest`, and handles them on the fly. After all the requests have been handled, it returns a +summarized `GreptimeResponse`. Through `HandleRequests`, we can achieve a very high throughput of requests handling. + +### `GreptimeRequest` + +The `GreptimeRequest` is a Protobuf message defined like this: + +```protobuf +message GreptimeRequest { + RequestHeader header = 1; + oneof request { + InsertRequests inserts = 2; + QueryRequest query = 3; + DdlRequest ddl = 4; + DeleteRequests deletes = 5; + RowInsertRequests row_inserts = 6; + RowDeleteRequests row_deletes = 7; + } +} +``` + +A `RequestHeader` is needed, it includes some context, authentication and others. The "oneof" field contains the request +to the GreptimeDB server. + +Note that we have two types of insertions, one is in the form of "column" (the `InsertRequests`), and the other is " +row" (`RowInsertRequests`). It's generally recommended to use the "row" form, since it's more natural for insertions on +a table, and easier to use. However, if there's a need to insert a large number of columns at once, or there're plenty +of "null" values to insert, the "column" form is better to be used. + +### `GreptimeResponse` + +The `GreptimeResponse` is a Protobuf message defined like this: + +```protobuf +message GreptimeResponse { + ResponseHeader header = 1; + oneof response {AffectedRows affected_rows = 2;} +} +``` + +The `ResponseHeader` contains the response's status code, and error message (if there's any). The "oneof" response only +contains the affected rows for now. + +GreptimeDB has a lot of SDKs now, you can refer to +them [here](https://github.com/GreptimeTeam?q=ingester&type=all&language=&sort=) for some examples. diff --git a/versioned_docs/version-0.11/contributor-guide/metasrv/admin-api.md b/versioned_docs/version-0.11/contributor-guide/metasrv/admin-api.md new file mode 100644 index 000000000..51f4026c5 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/metasrv/admin-api.md @@ -0,0 +1,297 @@ +--- +description: Details the Admin API for Metasrv, including endpoints for health checks, leader queries, heartbeat data, and maintenance mode. +--- + +# Admin API + +The Admin API provides a simple way to view cluster information, including metasrv health detection, metasrv leader query, database metadata query, and datanode heartbeat detection. + +The Admin API is an HTTP service that provides a set of RESTful APIs that can be called through HTTP requests. The Admin API is simple, user-friendly and safe. +Available APIs: + +- /health +- /leader +- /heartbeat +- /maintenance + +All these APIs are under the parent resource `/admin`. + +In the following sections, we assume that your metasrv instance is running on localhost port 3002. + +## /health HTTP endpoint + +The `/health` endpoint accepts GET HTTP requests and you can use this endpoint to check the health of your metasrv instance. + +### Definition + +```bash +curl -X GET http://localhost:3002/admin/health +``` + +### Examples + +#### Request + +```bash +curl -X GET http://localhost:3002/admin/health +``` + +#### Response + +```json +OK +``` + +## /leader HTTP endpoint + +The `/leader` endpoint accepts GET HTTP requests and you can use this endpoint to query the leader's addr of your metasrv instance. + +### Definition + +```bash +curl -X GET http://localhost:3002/admin/leader +``` + +### Examples + +#### Request + +```bash +curl -X GET http://localhost:3002/admin/leader +``` + +#### Response + +```json +127.0.0.1:3002 +``` + +## /heartbeat HTTP endpoint + +The `/heartbeat` endpoint accepts GET HTTP requests and you can use this endpoint to query the heartbeat of all datanodes. + +You can also query the heartbeat data of the datanode for a specified `addr`, however, specifying `addr` in the path is optional. + +### Definition + +```bash +curl -X GET http://localhost:3002/admin/heartbeat +``` + +| Query String Parameter | Type | Optional/Required | Definition | +|:-----------------------|:-------|:------------------|:--------------------------| +| addr | String | Optional | The addr of the datanode. | + +### Examples + +#### Request + +```bash +curl -X GET 'http://localhost:3002/admin/heartbeat?addr=127.0.0.1:4100' +``` + +#### Response + +```json +[ + [{ + "timestamp_millis": 1677049348651, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049344048, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049343624, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049339036, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049338609, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049334019, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049333592, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049329002, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049328573, + "cluster_id": 0, + "id": 1, + "addr": "127.0.0.1:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }, { + "timestamp_millis": 1677049323986, + "cluster_id": 0, + "id": 1, + "addr": "0.0.0.0:4100", + "is_leader": false, + "rcus": 0, + "wcus": 0, + "table_num": 0, + "region_num": 2, + "cpu_usage": 0.0, + "load": 0.0, + "read_io_rate": 0.0, + "write_io_rate": 0.0, + "region_stats": [] + }] +] +``` + +## /maintenance HTTP endpoint + +The metasrv will ignore detected region failures when under maintenance. This is useful when the datanodes are planned to be unavailable for a short period of time; for example, rolling upgrade for datanodes. + +### GET + +The `/maintenance` endpoint accepts GET HTTP requests and you can use this endpoint to query the maintenance status of your metasrv instance. + +```bash +curl -X GET http://localhost:3002/admin/maintenance +``` + +#### Request + +```bash +curl -X GET http://localhost:3002/admin/maintenance +``` + +#### Response + +```text +Maintenance mode is disabled +``` + +### PUT + +The `/maintenance` endpoint accepts PUT HTTP requests and you can toggle the maintenance status of your metasrv instance. + +```bash +curl -X PUT http://localhost:3002/admin/maintenance +``` + +| Query String Parameter | Type | Optional/Required | Definition | +|:-----------------------|:-------|:------------------|:--------------------------| +| enable | String | Required | 'true' or 'false' | + +#### Request + +```bash +curl -X PUT http://localhost:3002/admin/maintenance?enable=true +``` + +#### Response + +```text +Maintenance mode enabled +``` diff --git a/versioned_docs/version-0.11/contributor-guide/metasrv/overview.md b/versioned_docs/version-0.11/contributor-guide/metasrv/overview.md new file mode 100644 index 000000000..f8a535694 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/metasrv/overview.md @@ -0,0 +1,160 @@ +--- +description: Provides an overview of the Metasrv service, its components, interactions with the Frontend, architecture, and key functionalities like distributed consensus and heartbeat management. +--- + +# Overview + +![meta](/meta.png) + +## What's in Metasrv + +- Store metadata (Catalog, Schema, Table, Region, etc.) +- Request-Router. It tells the Frontend where to write and read data. +- Load balancing for Datanode, determines who should handle new table creation requests, more precisely, it makes resource allocation decisions. +- Election & High Availability, GreptimeDB is designed in a Leader-Follower architecture, only Leader nodes can write while Follower nodes can read, the number of Follower nodes is usually >= 1, and Follower nodes need to be able to switch to Leader quickly when Leader is not available. +- Statistical data collection (reported via Heartbeats on each node), such as CPU, Load, number of Tables on the node, average/peak data read/write size, etc., can be used as the basis for distributed scheduling. + +## How the Frontend interacts with Metasrv + +First, the routing table in Request-Router is in the following structure (note that this is only the logical structure, the actual storage structure varies, for example, endpoints may have dictionary compression). + +``` + table_A + table_name + table_schema // for physical plan + regions + region_1 + mutate_endpoint + select_endpoint_1, select_endpoint_2 + region_2 + mutate_endpoint + select_endpoint_1, select_endpoint_2, select_endpoint_3 + region_xxx + table_B + ... +``` + +### Create Table + +1. The Frontend sends `CREATE TABLE` requests to Metasrv. +2. Plan the number of Regions according to the partition rules contained in the request. +3. Check the global view of resources available to Datanodes (collected by Heartbeats) and assign one node to each region. +4. The Frontend creates the table and stores the `Schema` to Metasrv after successful creation. + +### Insert + +1. The Frontend fetches the routes of the specified table from Metasrv. Note that the smallest routing unit is the route of the table (several regions), i.e., it contains the addresses of all regions of this table. +2. The best practice is that the Frontend first fetches the routes from its local cache and forwards the request to the Datanode. If the route is no longer valid, then Datanode is obliged to return an `Invalid Route` error, and the Frontend re-fetches the latest data from Metasrv and updates its cache. Route information does not change frequently, thus, it's sufficient for Frontend uses the Lazy policy to maintain the cache. +3. The Frontend processes a batch of writes that may contain multiple tables and multiple regions, so the Frontend needs to split user requests based on the 'route table'. + +### Select + +1. As with `Insert`, the Frontend first fetches the route table from the local cache. +2. Unlike `Insert`, for `Select`, the Frontend needs to extract the read-only node (follower) from the route table, then dispatch the request to the leader or follower node depending on the priority. +3. The distributed query engine in the Frontend distributes multiple sub-query tasks based on the routing information and aggregates the query results. + +## Metasrv Architecture + +![metasrv-architecture](/metasrv-architecture.png) + +## Distributed Consensus + +As you can see, Metasrv has a dependency on distributed consensus because: + +1. First, Metasrv has to elect a leader, Datanode only sends heartbeats to the leader, and we only use a single metasrv node to receive heartbeats, which makes it easy to do some calculations or scheduling accurately and quickly based on global information. As for how the Datanode connects to the leader, this is for MetaClient to decide (using a redirect, Heartbeat requests becomes a gRPC stream, and using redirect will be less error-prone than forwarding), and it is transparent to the Datanode. +2. Second, Metasrv must provide an election API for Datanode to elect "write" and "read-only" nodes and help Datanode achieve high availability. +3. Finally, `Metadata`, `Schema` and other data must be reliably and consistently stored on Metasrv. Therefore, consensus-based algorithms are the ideal approach for storing them. + +For the first version of Metasrv, we choose Etcd as the consensus algorithm component (Metasrv is designed to consider adapting different implementations and even creating a new wheel) for the following reasons: + +1. Etcd provides exactly the API we need, such as `Watch`, `Election`, `KV`, etc. +2. We only perform two tasks with distributed consensus: elections (using the `Watch` mechanism) and storing (a small amount of metadata), and neither of them requires us to customize our own state machine, nor do we need to customize our own state machine based on raft; the small amount of data also does not require multi-raft-group support. +3. The initial version of Metasrv uses Etcd, which allows us to focus on the capabilities of Metasrv and not spend too much effort on distributed consensus algorithms, which improves the design of the system (avoiding coupling with consensus algorithms) and helps with rapid development at the beginning, as well as allows easy access to good consensus algorithm implementations in the future through good architectural designs. + +## Heartbeat Management + +The primary means of communication between Datanode and Metasrv is the Heartbeat Request/Response Stream, and we want this to be the only way to communicate. This idea is inspired by the design of [TiKV PD](https://github.com/tikv/pd), and we have practical experience in [RheaKV](https://github.com/sofastack/sofa-jraft/tree/master/jraft-rheakv/rheakv-pd). The request sends its state, while Metasrv sends different scheduling instructions via Heartbeat Response. + +A heartbeat will probably carry the data listed below, but this is not the final design, and we are still discussing and exploring exactly which data should be mostly collected. + +``` +service Heartbeat { + // Heartbeat, there may be many contents of the heartbeat, such as: + // 1. Metadata to be registered to metasrv and discoverable by other nodes. + // 2. Some performance metrics, such as Load, CPU usage, etc. + // 3. The number of computing tasks being executed. + rpc Heartbeat(stream HeartbeatRequest) returns (stream HeartbeatResponse) {} +} + +message HeartbeatRequest { + RequestHeader header = 1; + + // Self peer + Peer peer = 2; + // Leader node + bool is_leader = 3; + // Actually reported time interval + TimeInterval report_interval = 4; + // Node stat + NodeStat node_stat = 5; + // Region stats in this node + repeated RegionStat region_stats = 6; + // Follower nodes and stats, empty on follower nodes + repeated ReplicaStat replica_stats = 7; +} + +message NodeStat { + // The read capacity units during this period + uint64 rcus = 1; + // The write capacity units during this period + uint64 wcus = 2; + // Table number in this node + uint64 table_num = 3; + // Region number in this node + uint64 region_num = 4; + + double cpu_usage = 5; + double load = 6; + // Read disk I/O in the node + double read_io_rate = 7; + // Write disk I/O in the node + double write_io_rate = 8; + + // Others + map attrs = 100; +} + +message RegionStat { + uint64 region_id = 1; + TableName table_name = 2; + // The read capacity units during this period + uint64 rcus = 3; + // The write capacity units during this period + uint64 wcus = 4; + // Approximate region size + uint64 approximate_size = 5; + // Approximate number of rows + uint64 approximate_rows = 6; + + // Others + map attrs = 100; +} + +message ReplicaStat { + Peer peer = 1; + bool in_sync = 2; + bool is_learner = 3; +} +``` + +## Central Nervous System (CNS) + +We are to build an algorithmic system, which relies on real-time and historical heartbeat data from each node, should make some smarter scheduling decisions and send them to Metasrv's Autoadmin unit, which distributes the scheduling decisions, either by the Datanode itself or more likely by the PaaS platform. + +## Abstraction of Workloads + +The level of workload abstraction determines the efficiency and quality of the scheduling strategy generated by Metasrv such as resource allocation. + +DynamoDB defines RCUs & WCUs (Read Capacity Units / Write Capacity Units), explaining that a RCU is a read request of 4KB data, and a WCU is a write request of 1KB data. When using RCU and WCU to describe workloads, it's easier to achieve performance measurability and get more informative resource preallocation because we can abstract different hardware capabilities as a combination of RCU and WCU. + +However, GreptimeDB still faces a more complex situation than DynamoDB, in particular, RCU doesn't fit to describe GreptimeDB's read workloads which require a lot of computation. We are working on that. diff --git a/versioned_docs/version-0.11/contributor-guide/metasrv/selector.md b/versioned_docs/version-0.11/contributor-guide/metasrv/selector.md new file mode 100644 index 000000000..4ced285a6 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/metasrv/selector.md @@ -0,0 +1,46 @@ +--- +description: Describes the different types of selectors in the Metasrv service, their characteristics, and how to configure them. +--- + +# Selector + +## Introduction + +What is the `Selector`? As its name suggests, it allows users to select specific items from a given `namespace` and `context`. There is a related trait, also named `Selector`, whose definition can be found [below][0]. + +[0]: https://github.com/GreptimeTeam/greptimedb/blob/main/src/meta-srv/src/selector.rs + +There is a specific scenario in `Metasrv` service. When a request to create a table is sent to the `Metasrv` service, it creates a routing table (the details of table creation will not be described here). The `Metasrv` service needs to select the appropriate `Datanode` list when creating a routing table. + +## Selector Type + +The `Metasrv` service currently offers the following types of `Selectors`: + +### LeasebasedSelector + +`LeasebasedSelector` randomly selects from all available (in lease) `Datanode`s, its characteristic is simplicity and fast. + +### LoadBasedSelector + +The `LoadBasedSelector` load value is determined by the number of regions on each `Datanode`, fewer regions indicate lower load, and `LoadBasedSelector` prioritizes selecting low-load `Datanodes`. + +### RoundRobinSelector [default] +`RoundRobinSelector` selects `Datanode`s in a round-robin fashion. It is recommended and the default option in most cases. If you're unsure which to choose, it's usually the right choice. + +## Configuration + +You can configure the `Selector` by its name when starting the `Metasrv` service. + +- LeasebasedSelector: `lease_based` or `LeaseBased` +- LoadBasedSelector: `load_based` or `LoadBased` +- RoundRobinSelector: `round_robin` or `RoundRobin` + +For example: + +```shell +cargo run -- metasrv start --selector round_robin +``` + +```shell +cargo run -- metasrv start --selector RoundRobin +``` diff --git a/versioned_docs/version-0.11/contributor-guide/overview.md b/versioned_docs/version-0.11/contributor-guide/overview.md new file mode 100644 index 000000000..fb1ab15a2 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/overview.md @@ -0,0 +1,70 @@ +--- +description: Overview of GreptimeDB's architecture, key components, and how they interact to process user requests. +--- + +# Overview + +## Architecture + +`GreptimeDB` consists of the following key components: + +- `Frontend` that exposes read and write service in various protocols, forwards requests to + `Datanode`. +- `Datanode` is responsible for storing data to persistent storage such as local disk or object storage in the cloud such as AWS S3, Azure Blob Storage etc. +- `Metasrv` server that coordinates the operations between the `Frontend` and `Datanode`. + +![Architecture](/architecture-3.png) + +## Concepts + +To better understand `GreptimeDB`, a few concepts need to be introduced: + +- A `table` is where user data is stored in `GreptimeDB`. A `table` has a schema and a totally + ordered primary key. A `table` is split into segments called `region` by its partition key. +- A `region` is a contiguous segment of a table, and also could be regarded as a partition in some + relational databases. A `region` could be replicated on multiple `datanode` and only one of these + replicas is writable and can serve write requests, while any replica can serve read requests. +- A `datanode` stores and serves `region` to `frontends`. One `datanode` can serve multiple `regions` + and one `region` can be served by multiple `datanodes`. +- The `metasrv` stores the metadata of the cluster, such as tables, `datanodes`, `regions` of each + table, etc. It also coordinates `frontends` and `datanodes`. +- The `frontend` has a catalog implementation, which fetches the metadata from + `metasrv`, tells which `region` of a `table` is served by which `datanode`. +- A `frontend` is a stateless service that serves requests from client. It acts as a proxy to + forward read and write requests to corresponding `datanode`, according to the mapping from catalog. +- A timeseries of a `table` is identified by its primary key. Each `table` must have a timestamp + column, as `GreptimeDB` is a timeseries database. Data in `table` will be sorted by its primary key + and + timestamp, but the actual order is implementation specific and may change in the future. + +## How it works + +![Interactions between components](/how-it-works.png) + +Before diving into each component, let's take a high level view of how the database works. + +- Users can interact with the database via various protocols, such as ingesting data using + `InfluxDB line protocol`, then exploring the data using SQL or PromQL. The `frontend` is the + component users or clients connect to and operate, thus hide `datanode` and `metasrv` behind it. +- Assumes a user uses the HTTP API to insert data into the database, by sending a HTTP request to a + `frontend` instance. When the `frontend` receives the request, it then parses the request body using + corresponding protocol parser, and finds the table to write to from a catalog manager based on + `metasrv`. +- The `frontend` relies on a push-pull strategy to cache metadata from `metasrv`, thus it knows which + `datanode`, or more precisely, the `region` a request should be sent to. A request may be split and + sent to multiple `region`s, if its contents need to be stored in different `region`s. +- When `datanode` receives the request, it writes the data to the `region`, and then sends response + back to the `frontend`. Writing to the `region` will then write to the underlying storage engine, + which will eventually put the data to persistent device. +- Once `frontend` has received all responses from the target `datanode`s, it then sends the result + back to the user. + +For more details on each component, see the following guides: + +- [frontend][1] +- [datanode][2] +- [metasrv][3] + +[1]: ./frontend/overview.md +[2]: ./datanode/overview.md +[3]: ./metasrv/overview.md diff --git a/versioned_docs/version-0.11/contributor-guide/tests/integration-test.md b/versioned_docs/version-0.11/contributor-guide/tests/integration-test.md new file mode 100644 index 000000000..9dc17b576 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/tests/integration-test.md @@ -0,0 +1,12 @@ +--- +description: Guide on writing and running integration tests in GreptimeDB, covering scenarios involving multiple components. +--- + +# Integration Test + +## Introduction + +Integration testing is written with Rust test harness (`#[test]`), unlike unit testing, they are placed separately +[here](https://github.com/GreptimeTeam/greptimedb/tree/main/tests-integration). +It covers scenarios involving multiple components, in which one typical case is HTTP/gRPC-related features. You can check +its [documentation](https://github.com/GreptimeTeam/greptimedb/blob/main/tests-integration/README.md) for more information. diff --git a/versioned_docs/version-0.11/contributor-guide/tests/overview.md b/versioned_docs/version-0.11/contributor-guide/tests/overview.md new file mode 100644 index 000000000..d1ac1cc2e --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/tests/overview.md @@ -0,0 +1,7 @@ +--- +description: Overview of the testing methods used in GreptimeDB to ensure its behavior and performance. +--- + +# Overview + +Our team has conducted lots of tests to ensure the behaviours of `GreptimeDB` . This chapter will introduce several significant methods used to test `GreptimeDB`, and how to work with them. diff --git a/versioned_docs/version-0.11/contributor-guide/tests/sqlness-test.md b/versioned_docs/version-0.11/contributor-guide/tests/sqlness-test.md new file mode 100644 index 000000000..11757d286 --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/tests/sqlness-test.md @@ -0,0 +1,60 @@ +--- +description: Instructions for running SQL tests in GreptimeDB using the `sqlness` test suite, including file types, case organization, and running tests. +--- + +# Sqlness Test + +## Introduction + +SQL is an important user interface for `GreptimeDB`. We have a separate test suite for it (named `sqlness`). + +## Sqlness manual + +### Case file + +Sqlness has three types of file + +- `.sql`: test input, SQL only +- `.result`: expected test output, SQL and its results +- `.output`: different output, SQL and its results + +Both `.result` and `.output` are output (execution result) files. The difference is that `.result` is the +the standard (expected) output, and `.output` is the error output. Therefore, if you see `.output` files generated, +it means this test gets a different result and indicates it fails. You should +check change logs to solve the problem. + +You only need to write test SQL in `.sql` file, and run the test. On the first run it produces +an `.output` file because there is no `.result` to compare with. If you can make sure the content in +`.output` is correct, you can rename it to `.result`, which means it is the expected output. + +And at any time there should only be two file types, `.sql` and `.result` -- otherwise, an existing `.output` +file means your test fails. That's why we should not ignore `.output` file type in `.gitignore`, instead, track +it and make sure it doesn't exist. + +### Case organization + +The root dir of input cases is `tests/cases`. It contains several sub-directories stand for different test +modes. E.g., `standalone/` contains all the tests to run under `greptimedb standalone start` mode. + +Under the first level of sub-directory (e.g. the `cases/standalone`), you can organize your cases as you like. +Sqlness walks through every file recursively and runs them. + +## Run the test + +Unlike other tests, this harness is in a binary target form. You can run it with + +```shell +cargo run --bin sqlness-runner +``` + +It automatically finishes the following procedures: compile `GreptimeDB`, start it, grab tests and feed it to +the server, then collect and compare the results. You only need to check whether there are new `.output` files. +If not, congratulations, the test is passed 🥳! + +### Run a specific test + +```shell +cargo sqlness -t your_test +``` + +If you specify a second argument, only test cases containing the specified string in their names will be executed. Sqlness also supports filtering based on environment. The filter is accepted as a regex string and the case name will be examined in the format of `env:case`. diff --git a/versioned_docs/version-0.11/contributor-guide/tests/unit-test.md b/versioned_docs/version-0.11/contributor-guide/tests/unit-test.md new file mode 100644 index 000000000..1b9b3fb7c --- /dev/null +++ b/versioned_docs/version-0.11/contributor-guide/tests/unit-test.md @@ -0,0 +1,31 @@ +--- +description: Guide on writing and running unit tests in GreptimeDB using Rust's `#[test]` attribute and `cargo nextest`. +--- + +# Unit Test + +## Introduction + +Unit tests are embedded into the codebase, usually placed next to the logic being tested. +They are written using Rust's `#[test]` attribute and can run with `cargo nextest run`. + +The default test runner ships with `cargo` is not supported in GreptimeDB codebase. It's recommended +to use [`nextest`](https://nexte.st/) instead. You can install it with + +```shell +cargo install cargo-nextest --locked +``` + +And run the tests (here the `--workspace` is not necessary) + +```shell +cargo nextest run +``` + +Notes if your Rust is installed via `rustup`, be sure to install `nextest` with `cargo` rather +than the package manager like `homebrew`. Otherwise it will mess up your local environment. + +## Coverage + +Our continuous integration (CI) jobs have a "coverage checking" step. It will report how many +codes are covered by unit tests. Please add the necessary unit test to your patch. diff --git a/versioned_docs/version-0.11/db-cloud-shared/clients/otlp-logs-integration.md b/versioned_docs/version-0.11/db-cloud-shared/clients/otlp-logs-integration.md new file mode 100644 index 000000000..4a6191164 --- /dev/null +++ b/versioned_docs/version-0.11/db-cloud-shared/clients/otlp-logs-integration.md @@ -0,0 +1,22 @@ +GreptimeDB is an observability backend to consume OpenTelemetry Logs natively via [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) protocol. + +#### API + +To send OpenTelemetry Logs to GreptimeDB through OpenTelemetry SDK libraries, use the following information: + +* URL: `http{s}:///v1/otlp/v1/logs` +* Headers: + * `X-Greptime-DB-Name`: `` + * `Authorization`: `Basic` authentication, which is a Base64 encoded string of `:`. For more information, please refer to [Authentication](https://docs.greptime.com/user-guide/deployments/authentication/static/) and [HTTP API](https://docs.greptime.com/user-guide/protocols/http#authentication). + * `X-Greptime-Log-Table-Name`: `` (optional) - The table name to store the logs. If not provided, the default table name is `opentelemetry_logs`. + * `X-Greptime-Log-Extract-Keys`: `` (optional) - The keys to extract from the attributes. The keys should be separated by commas (`,`). For example, `key1,key2,key3` will extract the keys `key1`, `key2`, and `key3` from the attributes and promote them to the top level of the log, setting them as tags. If the field type is array, float, or object, an error will be returned. If a pipeline is provided, this setting will be ignored. + * `X-Greptime-Log-Pipeline-Name`: `` (optional) - The pipeline name to process the logs. If not provided, the extract keys will be used to process the logs. + * `X-Greptime-Log-Pipeline-Version`: `` (optional) - The pipeline version to process the logs. If not provided, the latest version of the pipeline will be used. + +The request uses binary protobuf to encode the payload, so you need to use packages that support `HTTP/protobuf`. + +:::tip NOTE +The package names may change according to OpenTelemetry, so we recommend that you refer to the official OpenTelemetry documentation for the most up-to-date information. +::: + +For more information about the OpenTelemetry SDK, please refer to the official documentation for your preferred programming language. diff --git a/versioned_docs/version-0.11/db-cloud-shared/clients/otlp-metrics-integration.md b/versioned_docs/version-0.11/db-cloud-shared/clients/otlp-metrics-integration.md new file mode 100644 index 000000000..7a8a31ecf --- /dev/null +++ b/versioned_docs/version-0.11/db-cloud-shared/clients/otlp-metrics-integration.md @@ -0,0 +1,18 @@ +GreptimeDB is an observability backend to consume OpenTelemetry Metrics natively via [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) protocol. + +#### API + +To send OpenTelemetry Metrics to GreptimeDB through OpenTelemetry SDK libraries, use the following information: + +* URL: `http{s}:///v1/otlp/v1/metrics` +* Headers: + * `X-Greptime-DB-Name`: `` + * `Authorization`: `Basic` authentication, which is a Base64 encoded string of `:`. For more information, please refer to [Authentication](https://docs.greptime.com/user-guide/deployments/authentication/static/) and [HTTP API](https://docs.greptime.com/user-guide/protocols/http#authentication) + +The request uses binary protobuf to encode the payload, so you need to use packages that support `HTTP/protobuf`. For example, in Node.js, you can use [`exporter-trace-otlp-proto`](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-proto); in Go, you can use [`go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp`](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp); in Java, you can use [`io.opentelemetry:opentelemetry-exporter-otlp`](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-exporter-otlp); and in Python, you can use [`opentelemetry-exporter-otlp-proto-http`](https://pypi.org/project/opentelemetry-exporter-otlp-proto-http/). + +:::tip NOTE +The package names may change according to OpenTelemetry, so we recommend that you refer to the official OpenTelemetry documentation for the most up-to-date information. +::: + +For more information about the OpenTelemetry SDK, please refer to the official documentation for your preferred programming language. diff --git a/versioned_docs/version-0.11/db-cloud-shared/clients/vector-integration.md b/versioned_docs/version-0.11/db-cloud-shared/clients/vector-integration.md new file mode 100644 index 000000000..fa773c0f9 --- /dev/null +++ b/versioned_docs/version-0.11/db-cloud-shared/clients/vector-integration.md @@ -0,0 +1,19 @@ + +Vector is [a high performance observability data +pipeline](https://vector.dev). It has native support for GreptimeDB metrics data +sink. With vector, you can ingest metrics data from various sources, including +Prometheus, OpenTelemetry, StatsD and many more. +GreptimeDB can be used as a Vector Sink component to receive metrics. + + + +Execute Vector with: + +``` +vector -c sample.toml +``` + +For more configuration options, see [Vector GreptimeDB +Configuration](https://vector.dev/docs/reference/sinks/greptimedb/). + + diff --git a/versioned_docs/version-0.11/db-cloud-shared/migrate/_migrate-from-prometheus.md b/versioned_docs/version-0.11/db-cloud-shared/migrate/_migrate-from-prometheus.md new file mode 100644 index 000000000..2c0a95463 --- /dev/null +++ b/versioned_docs/version-0.11/db-cloud-shared/migrate/_migrate-from-prometheus.md @@ -0,0 +1,31 @@ +GreptimeDB can be used to store time series data for [Prometheus](https://prometheus.io/). +Additionally, GreptimeDB supports the Prometheus query language via its HTTP API. +This allows for an easy migration of your Prometheus long-term storage to GreptimeDB. + +## Data model in difference + +To understand the differences between the data models of Prometheus and GreptimeDB, please refer to the [Data Model](/user-guide/ingest-data/for-observerbility/prometheus.md#data-model) in the Ingest Data documentation. + +## Prometheus Remote Write + + + +## Prometheus HTTP API and PromQL + +GreptimeDB supports the Prometheus query language (PromQL) via its HTTP API. + + +## Visualize data using Grafana + +For developers accustomed to using Grafana for visualizing Prometheus data, +you can continue to use the same Grafana dashboards to visualize data stored in GreptimeDB. + + + +## Reference + +For tutorials and user stories on integrating GreptimeDB with Prometheus, please refer to the following blog posts: + +- [Setting Up GreptimeDB for Long-Term Prometheus Storage](https://greptime.com/blogs/2024-08-09-prometheus-backend-tutorial) +- [Scale Prometheus - Deploying GreptimeDB Cluster as Long-Term Storage for Prometheus in K8s](https://greptime.com/blogs/2024-10-07-scale-prometheus) +- [User Story — Why We Switched from Thanos to GreptimeDB for Prometheus Long-Term Storage](https://greptime.com/blogs/2024-10-16-thanos-migration-to-greptimedb) diff --git a/versioned_docs/version-0.11/db-cloud-shared/migrate/migrate-from-influxdb.md b/versioned_docs/version-0.11/db-cloud-shared/migrate/migrate-from-influxdb.md new file mode 100644 index 000000000..da9382c73 --- /dev/null +++ b/versioned_docs/version-0.11/db-cloud-shared/migrate/migrate-from-influxdb.md @@ -0,0 +1,257 @@ +This guide will help you understand the differences between the data models of GreptimeDB and InfluxDB, and guide you through the migration process. + +## Data model in difference + +To understand the differences between the data models of InfluxDB and GreptimeDB, please refer to the [Data Model](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md#data-model) in the Ingest Data documentation. + +## Database connection information + +Before you begin writing or querying data, it's crucial to comprehend the differences in database connection information between InfluxDB and GreptimeDB. + +- **Token**: The InfluxDB API token, used for authentication, aligns with the GreptimeDB authentication. When interacting with GreptimeDB using InfluxDB's client libraries or HTTP API, you can use `` as the token. +- **Organization**: Unlike InfluxDB, GreptimeDB does not require an organization for connection. +- **Bucket**: In InfluxDB, a bucket serves as a container for time series data, which is equivalent to the database name in GreptimeDB. + + + +## Ingest data + +GreptimeDB is compatible with both v1 and v2 of InfluxDB's line protocol format, +facilitating a seamless migration from InfluxDB to GreptimeDB. + +### HTTP API + +To write a measurement to GreptimeDB, you can use the following HTTP API request: + + + +### Telegraf + +GreptimeDB's support for the Influxdb line protocol ensures its compatibility with Telegraf. +To configure Telegraf, simply add GreptimeDB URL into Telegraf configurations: + + + +### Client libraries + +Writing data to GreptimeDB is a straightforward process when using InfluxDB client libraries. +Simply include the URL and authentication details in the client configuration. + +For example: + + + +In addition to the languages previously mentioned, +GreptimeDB also accommodates client libraries for other languages supported by InfluxDB. +You can code in your language of choice by referencing the connection information and code snippets provided earlier. + +## Query data + +GreptimeDB does not support Flux and InfluxQL, opting instead for SQL and PromQL. + +SQL is a universal language designed for managing and manipulating relational databases. +With flexible capabilities for data retrieval, manipulation, and analytics, +it is also reduce the learning curve for users who are already familiar with SQL. + +PromQL (Prometheus Query Language) allows users to select and aggregate time series data in real time, +The result of an expression can either be shown as a graph, viewed as tabular data in Prometheus's expression browser, +or consumed by external systems via the [HTTP API](/user-guide/query-data/promql.md#prometheus-http-api). + +Suppose you are querying the maximum cpu usage from the `monitor` table, recorded over the past 24 hours. +In influxQL, the query might look something like this: + +```sql [InfluxQL] +SELECT + MAX("cpu") +FROM + "monitor" +WHERE + time > now() - 24h +GROUP BY + time(1h) +``` + +This InfluxQL query computes the maximum value of the `cpu` field from the `monitor` table, +considering only the data where the time is within the last 24 hours. +The results are then grouped into one-hour intervals. + +In Flux, the query might look something like this: + +```flux [Flux] +from(bucket: "public") + |> range(start: -24h) + |> filter(fn: (r) => r._measurement == "monitor") + |> aggregateWindow(every: 1h, fn: max) +``` + +The similar query in GreptimeDB SQL would be: + +```sql [SQL] +SELECT + ts, + host, + AVG(cpu) RANGE '1h' as mean_cpu +FROM + monitor +WHERE + ts > NOW() - INTERVAL '24 hours' +ALIGN '1h' TO NOW +ORDER BY ts DESC; +``` + +In this SQL query, +the `RANGE` clause determines the time window for the `AVG(cpu)` aggregation function, +while the `ALIGN` clause sets the alignment time for the time series data. +For more information on time window grouping, please refer to the [Aggregate data by time window](/user-guide/query-data/sql.md#aggregate-data-by-time-window) document. + +The similar query in PromQL would be something like: + +```promql +avg_over_time(monitor[1h]) +``` +To query time series data from the last 24 hours, +you need to execute this PromQL, using the `start` and `end` parameters of the HTTP API to define the time range. +For more information on PromQL, please refer to the [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) document. + +## Visualize data + + + +## Migrate data + +For a seamless migration of data from InfluxDB to GreptimeDB, you can follow these steps: + +![Double write to GreptimeDB and InfluxDB](/migrate-influxdb-to-greptimedb.drawio.svg) + +1. Write data to both GreptimeDB and InfluxDB to avoid data loss during migration. +2. Export all historical data from InfluxDB and import the data into GreptimeDB. +3. Stop writing data to InfluxDB and remove the InfluxDB server. + +### Write data to both GreptimeDB and InfluxDB simultaneously + +Writing data to both GreptimeDB and InfluxDB simultaneously is a practical strategy to avoid data loss during migration. +By utilizing InfluxDB's [client libraries](#client-libraries), +you can set up two client instances - one for GreptimeDB and another for InfluxDB. +For guidance on writing data to GreptimeDB using the InfluxDB line protocol, please refer to the [Ingest Data](#ingest-data) section. + +If retaining all historical data isn't necessary, +you can simultaneously write data to both GreptimeDB and InfluxDB for a specific period to accumulate the required recent data. +Subsequently, cease writing to InfluxDB and continue exclusively with GreptimeDB. +If a complete migration of all historical data is needed, please proceed with the following steps. + +### Export data from InfluxDB v1 Server + +Create a temporary directory to store the exported data of InfluxDB. + +```shell +mkdir -p /path/to/export +``` + +Use the [`influx_inspect export` command](https://docs.influxdata.com/influxdb/v1/tools/influx_inspect/#export) of InfluxDB to export data. + +```shell +influx_inspect export \ + -database \ + -end \ + -lponly \ + -datadir /var/lib/influxdb/data \ + -waldir /var/lib/influxdb/wal \ + -out /path/to/export/data +``` + +- The `-database` flag specifies the database to be exported. +- The `-end` flag specifies the end time of the data to be exported. +Must be in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339), such as `2024-01-01T00:00:00Z`. +You can use the timestamp when simultaneously writing data to both GreptimeDB and InfluxDB as the end time. +- The `-lponly` flag specifies that only the Line Protocol data should be exported. +- The `-datadir` flag specifies the path to the data directory, as configured in the [InfluxDB data settings](https://docs.influxdata.com/influxdb/v1/administration/config/#data-settings). +- The `-waldir` flag specifies the path to the WAL directory, as configured in the [InfluxDB data settings](https://docs.influxdata.com/influxdb/v1/administration/config/#data-settings). +- The `-out` flag specifies the output directory. + +The exported data in InfluxDB line protocol looks like the following: + +```txt +disk,device=disk1s5s1,fstype=apfs,host=bogon,mode=ro,path=/ inodes_used=356810i 1714363350000000000 +diskio,host=bogon,name=disk0 iops_in_progress=0i 1714363350000000000 +disk,device=disk1s6,fstype=apfs,host=bogon,mode=rw,path=/System/Volumes/Update inodes_used_percent=0.0002391237988702021 1714363350000000000 +... +``` + +### Export Data from InfluxDB v2 Server + +Create a temporary directory to store the exported data of InfluxDB. + +```shell +mkdir -p /path/to/export +``` + +Use the [`influx inspect export-lp` command](https://docs.influxdata.com/influxdb/v2/reference/cli/influxd/inspect/export-lp/) of InfluxDB to export data in the bucket to line protocol. + +```shell +influxd inspect export-lp \ + --bucket-id \ + --engine-path /var/lib/influxdb2/engine/ \ + --end \ + --output-path /path/to/export/data +``` + +- The `--bucket-id` flag specifies the bucket ID to be exported. +- The `--engine-path` flag specifies the path to the engine directory, as configured in the [InfluxDB data settings](https://docs.influxdata.com/influxdb/v2.0/reference/config-options/#engine-path). +- The `--end` flag specifies the end time of the data to be exported. Must be in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339), such as `2024-01-01T00:00:00Z`. +You can use the timestamp when simultaneously writing data to both GreptimeDB and InfluxDB as the end time. +- The `--output-path` flag specifies the output directory. + +The outputs look like the following: + +```json +{"level":"info","ts":1714377321.4795408,"caller":"export_lp/export_lp.go:219","msg":"exporting TSM files","tsm_dir":"/var/lib/influxdb2/engine/data/307013e61d514f3c","file_count":1} +{"level":"info","ts":1714377321.4940555,"caller":"export_lp/export_lp.go:315","msg":"exporting WAL files","wal_dir":"/var/lib/influxdb2/engine/wal/307013e61d514f3c","file_count":1} +{"level":"info","ts":1714377321.4941633,"caller":"export_lp/export_lp.go:204","msg":"export complete"} +``` + +The exported data in InfluxDB line protocol looks like the following: + +```txt +cpu,cpu=cpu-total,host=bogon usage_idle=80.4448912910468 1714376180000000000 +cpu,cpu=cpu-total,host=bogon usage_idle=78.50167052182304 1714376190000000000 +cpu,cpu=cpu-total,host=bogon usage_iowait=0 1714375700000000000 +cpu,cpu=cpu-total,host=bogon usage_iowait=0 1714375710000000000 +... +``` + +### Import Data to GreptimeDB + +Before importing data to GreptimeDB, if the data file is too large, it's recommended to split the data file into multiple slices: + +```shell +split -l 100000 -d -a 10 data data. +# -l [line_count] Create split files line_count lines in length. +# -d Use a numeric suffix instead of a alphabetic suffix. +# -a [suffix_length] Use suffix_length letters to form the suffix of the file name. +``` + +You can import data using the HTTP API as described in the [write data section](#http-api). +The script provided below will help you in reading data from the files and importing it into GreptimeDB. + +Suppose you are in the directory where the data files are stored: + +```shell +. +├── data.0000000000 +├── data.0000000001 +├── data.0000000002 +... +``` + +Replace the following placeholders with your GreptimeDB connection information to setup the environment variables: + +```shell +export GREPTIME_USERNAME= +export GREPTIME_PASSWORD= +export GREPTIME_HOST= +export GREPTIME_DB= +``` + +Import the data from the files into GreptimeDB: + + diff --git a/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/go-demo.md b/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/go-demo.md new file mode 100644 index 000000000..c8d3ad88d --- /dev/null +++ b/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/go-demo.md @@ -0,0 +1,58 @@ +In this section, we will create a quick start demo and showcase the core code to collect host metrics and send them to GreptimeDB. The demo is based on [OTLP/HTTP](https://opentelemetry.io/). For reference, you can obtain the entire demo on [GitHub](https://github.com/GreptimeCloudStarters/quick-start-go). + +To begin, create a new directory named `quick-start-go` to host our project. Then, run the command `go mod init quick-start` in the directory from your terminal. This will generate a `go.mod` file, which is used by Go to manage imports. + +Next, create new file named `app.go` and install the required OpenTelemetry packages: + +```shell +go get go.opentelemetry.io/otel@v1.16.0 \ + go.opentelemetry.io/contrib/instrumentation/host@v0.42.0 \ + go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp@v0.39.0 +``` + +Once the required packages are installed, write the code to create a metric export object that sends metrics to GreptimeDB in `app.go`. +For the configuration about the exporter, please refer to OTLP integration documentation in [GreptimeDB](/user-guide/protocols/opentelemetry.md) or [GreptimeCloud](/greptimecloud/integrations/otlp.md). + +```go +auth := base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("%s:%s", *username, *password))) +exporter, err := otlpmetrichttp.New( + context.Background(), + otlpmetrichttp.WithEndpoint(*dbHost), + otlpmetrichttp.WithURLPath("/v1/otlp/v1/metrics"), + otlpmetrichttp.WithHeaders(map[string]string{ + "x-greptime-db-name": *db, + "Authorization": "Basic " + auth, + }), + otlpmetrichttp.WithTimeout(time.Second*5), +) + +if err != nil { + panic(err) +} + +reader := metric.NewPeriodicReader(exporter, metric.WithInterval(time.Second*2)) +``` + +Then attach the exporter to the MeterProvider and start the host metrics collection: + +```go +res := resource.NewWithAttributes( + semconv.SchemaURL, + semconv.ServiceName("quick-start-go"), +) + +meterProvider := metric.NewMeterProvider( + metric.WithResource(res), + metric.WithReader(reader), +) + +log.Print("Sending metrics...") +err = appHost.Start(appHost.WithMeterProvider(meterProvider)) +if err != nil { + log.Fatal(err) +} +``` + +For more details about the code, you can refer to the [OpenTelemetry Documentation](https://opentelemetry.io/docs/instrumentation/go/). + +Congratulations on successfully completing the core section of the demo! You can now run the complete demo by following the instructions in the `README.md` file on the [GitHub repository](https://github.com/GreptimeCloudStarters/quick-start-go). diff --git a/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/influxdb-demo.md b/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/influxdb-demo.md new file mode 100644 index 000000000..d010c39e4 --- /dev/null +++ b/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/influxdb-demo.md @@ -0,0 +1,57 @@ +We will write a Bash script and showcase the core code to collect host metrics and send them to GreptimeDB. For reference, you can view the complete demo on [GitHub](https://github.com/GreptimeCloudStarters/quick-start-influxdb-line-protocol). + +To begin, create a new directory named `quick-start-influxdb` to host our project. Then create a new file named `quick-start.sh` and make it executable: + +```bash +touch quick-start.sh +chmod +x quick-start.sh +``` + +Write code to collect CPU and memory metrics and format the data into InfluxDB line protocol format: + +```bash +#!/bin/bash + +generate_data() +{ + unameOut="$(uname -s)" + case "${unameOut}" in + Linux*) + user_cpu_util=$(top -bn1 | grep "Cpu(s)" | awk '{print $2 + $4}') + sys_cpu_util=$(top -bn1 | grep "Cpu(s)" | awk '{print $6}') + idle_cpu_util=$(top -bn1 | grep "Cpu(s)" | awk -F "," '{print $4}' | awk -F " " '{print $1}') + mem_util=$(free | grep Mem | awk '{print $3}') + ;; + Darwin*) + user_cpu_util=$(top -l 1 | awk '/^CPU usage: / { print substr($3, 1, length($3)-1) }') + sys_cpu_util=$(top -l 1 | awk '/^CPU usage: / { print substr($5, 1, length($5)-1) }') + idle_cpu_util=$(top -l 1 | awk '/^CPU usage: / { print substr($7, 1, length($7)-1) }') + mem_util=$(top -l 1 | awk '/^PhysMem:/ { print substr($6, 1, length($6)-1) }') + ;; + *) + user_cpu_util=$(shuf -i 10-15 -n 1) + sys_cpu_util=$(shuf -i 5-10 -n 1) + idle_cpu_util=$(shuf -i 70-80 -n 1) + mem_util=$(shuf -i 50-60 -n 1) + esac + now=$(($(date +%s)*1000000000)) + cat <` to any timeseries scraped from this config. + - job_name: 'node' + static_configs: + - targets: ['node_exporter:9100'] + +remote_write: + - url: https:///v1/prometheus/write?db= + basic_auth: + username: + password: +``` + +The configuration file above configures Prometheus to scrape metrics from the node exporter and send them to GreptimeDB. For the configuration about ``, ``, ``, and ``, please refer to the Prometheus documentation in [GreptimeDB](/user-guide/integrations/prometheus.md) or [GreptimeCloud](/greptimecloud/integrations/prometheus.md). + +Finally, start the containers: + +```bash +docker-compose up +``` diff --git a/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/python-demo.md b/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/python-demo.md new file mode 100644 index 000000000..bb3acb699 --- /dev/null +++ b/versioned_docs/version-0.11/db-cloud-shared/tutorials/monitor-host-metrics/python-demo.md @@ -0,0 +1,65 @@ +### Prerequisites + +- [Python 3.10+](https://www.python.org) + +### Example Application + +In this section, we will create a quick start demo and showcase the core code to collect host metrics and send them to GreptimeDB. The demo is based on [OTLP/HTTP](https://opentelemetry.io/). For reference, you can obtain the entire demo on [GitHub](https://github.com/GreptimeCloudStarters/quick-start-python). + +To begin, create a new directory named `quick-start-python` to house our project and create a new file named `requirements.txt` in the directory and add the following: + +```txt +opentelemetry-api==1.19.0 +opentelemetry-exporter-otlp-proto-common==1.19.0 +opentelemetry-exporter-otlp-proto-http==1.19.0 +opentelemetry-instrumentation==0.40b0 +opentelemetry-instrumentation-system-metrics==0.40b0 +opentelemetry-proto==1.19.0 +opentelemetry-sdk==1.19.0 +``` + +Install the dependencies: + +```bash +pip install -r requirements.txt +``` + +Once the required packages are installed,create a new file named `main.py` and write the code to create a metric export object that sends metrics to GreptimeDB. +For the configuration about the exporter, please refer to OTLP integration documentation in [GreptimeDB](/user-guide/protocols/opentelemetry.md) or [GreptimeCloud](/greptimecloud/integrations/otlp.md). + +```python +from opentelemetry import metrics +from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor +from opentelemetry.sdk.resources import SERVICE_NAME, Resource +from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter + +auth = f"{username}:{password}" +b64_auth = base64.b64encode(auth.encode()).decode("ascii") +endpoint = f"https://{host}/v1/otlp/v1/metrics" +exporter = OTLPMetricExporter( + endpoint=endpoint, + headers={"Authorization": f"Basic {b64_auth}", "x-greptime-db-name": db}, + timeout=5) +``` + +Then attach the exporter to the MetricReader and start the host metrics collection: + +```python +metric_reader = PeriodicExportingMetricReader(exporter, 5000) +provider = MeterProvider(resource=resource, metric_readers=[metric_reader]) + +# Sets the global default meter provider +metrics.set_meter_provider(provider) +configuration = { + "system.memory.usage": ["used", "free", "cached"], + "system.cpu.time": ["idle", "user", "system", "irq"], + "process.runtime.memory": ["rss", "vms"], + "process.runtime.cpu.time": ["user", "system"], +} +SystemMetricsInstrumentor(config=configuration).instrument() + +``` + +For more details about the code, you can refer to the [OpenTelemetry Documentation](https://opentelemetry.io/docs/instrumentation/python/getting-started/). + +Congratulations on successfully completing the core section of the demo! You can now run the complete demo by following the instructions in the `README.md` file on the [GitHub repository](https://github.com/GreptimeCloudStarters/quick-start-python). diff --git a/versioned_docs/version-0.11/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md b/versioned_docs/version-0.11/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md new file mode 100644 index 000000000..542914a2e --- /dev/null +++ b/versioned_docs/version-0.11/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md @@ -0,0 +1,58 @@ +--- +description: Detailed explanation of the active-active failover disaster recovery solution in GreptimeDB Enterprise, including read/write modes, RPO, and RTO configurations. +--- + +# DR Solution Based on Active-Active Failover + +## RPO + +In GreptimeDB's "Active-Active Failover" architecture, there are two nodes. Both nodes can provide the ability to execute reads and writes from clients. However, to achieve the goals of the RTO and RPO, we need to do some configurations about them. First of all, let me introduce the modes to reads and writes. + +For reads: + +- `SingleRead`: a read operation is executed in one node only, and the results are returned to the client directly. +- `DualRead`: a read operation is executed in both nodes. The results are merged and deduplicated before returning to the client. + +The following picture illustrates the difference between the two read modes: + +![disaster-recovery-read-mode](/disaster-recovery-read-mode.png) + +For writes: + +- `SyncWrite`: a write operation is executed in both nodes, and is considered success only if it is succeeded in both nodes before returning to the clients. +- `AsyncWrite`: a write operation is still executed in both nodes, but the result is returned to the clients when it is done on the issued node. The other node will receive a copy of the write operation from the issued node, asynchronously. + +The following picture illustrates the difference between the two write modes: + +![disaster-recovery-write-mode](/disaster-recovery-write-mode.png) + +So there are four combinations on reads and writes, and their RPOs are: + +| RPO | `SingleRead` | `DualRead` | +| - | - | - | +| `SyncWrite` | 0 | 0 | +| `AsyncWrite` | network latency between two nodes | 0 | + +Since the writes are synchronized between the two nodes in `SyncWrite` mode, the RPO is always zero regardless what read mode is. However, `SyncWrite` requires both nodes functioned well simultaneously to handle writes. If your workload is write-light-read-heavy, and can tolerate some system unavailable time to bring back the healthiness of both nodes when the disaster happened, we recommend the `SyncWrite + SingleRead` combination. + +Another combination that can achieve 0 RPO is `AsyncWrite + DualRead`. It's the opposite of the said above, suitable for the workload of write-heavy-read-light, and the restriction of the system availability can be relaxed. + +The final combination is `AsyncWrite + SingleRead`. This is the most relaxed setup. If the network between the nodes is good, and the nodes are hosted reliably, for example, the two nodes are hosted in a virtual machine system inside one AZ (Available Zone, or "Data Center"), you may prefer this combination. Of course, just remember that the RPO is not zero. + +## RTO + +To retain the minimality of requirements of our active-active architecture, we don't have a third node or a third service to handle the failover of GreptimeDB. Generally speaking, there are several ways to handle the failover: + +- Through a LoadBalancer. If you can spare another node for deploying a LoadBalancer like the [Nginx](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/), or if you have your own LoadBalance service can be used, we recommend this way. + DR-LoadBalancer +- By client SDK's failover mechanism. For example, if you are using MySQL Connector/j, you can configure the failover by setting multiple hosts and ports in the connection URL (see its document [here](https://dev.mysql.com/doc/connector-j/en/connector-j-config-failover.html)). PostgreSQL's driver [has the same mechanism](https://jdbc.postgresql.org/documentation/use/#connection-fail-over). This is the most easy way to handle the failover, but not every client SDK supports this failover mechanism. + DR-SDK +- Custom endpoint update mechanism. If you can detect the fall of nodes, you can retroactively update the GreptimeDB's endpoint set in your code. + +:::tip NOTE +To compare the RPO and RTO across different disaster recovery solutions, please refer to "[Solution Comparison](/user-guide/administration/disaster-recovery/overview.md#solution-comparison)". +::: + +## Summary + +You can choose different read/write modes combination to achieve your goal for RPO. This is inherent to GreptimeDB active-active architecture. As to RTO, we rely on external efforts to handle the failover. A LoadBalancer is best suited for this job. diff --git a/versioned_docs/version-0.11/enterprise/administration/disaster-recovery/overview.md b/versioned_docs/version-0.11/enterprise/administration/disaster-recovery/overview.md new file mode 100644 index 000000000..2a4f40b80 --- /dev/null +++ b/versioned_docs/version-0.11/enterprise/administration/disaster-recovery/overview.md @@ -0,0 +1,13 @@ +--- +description: Overview of disaster recovery solutions in GreptimeDB Enterprise, focusing on the active-active failover architecture for high availability and data protection. +--- + +# Overview + +GreptimeDB is a distributed database designed to withstand disasters. + +Please refer to the [Disaster Recovery Overview](/user-guide/administration/disaster-recovery/overview.md) in the GreptimeDB OSS documentation to learn about all the disaster recovery solutions provided by Greptime. +This section only introduces the solutions provided in GreptimeDB Enterprise. + +- [DR Solution Based on Active-Active Failover](./dr-solution-based-on-active-active-failover.md) + diff --git a/versioned_docs/version-0.11/enterprise/autopilot/region-balancer.md b/versioned_docs/version-0.11/enterprise/autopilot/region-balancer.md new file mode 100644 index 000000000..89d827395 --- /dev/null +++ b/versioned_docs/version-0.11/enterprise/autopilot/region-balancer.md @@ -0,0 +1,38 @@ +--- +description: Configuration guide for the region balancer plugin in GreptimeDB Enterprise, which balances write loads across datanodes to prevent frequent region migrations. +--- + +# Region Balancer + +This plugin balances the write load of regions across datanodes, using specified window sizes and load thresholds to prevent frequent region migrations. + +```toml +[[plugins]] +[plugins.region_balancer] + +max_window = "45s" + +window_stability_threshold = 2 + +min_load_threshold = "10MB" + +tick_interval = "45s" +``` + +## Configuration Parameters + +- `max_window`: string + - **Description**: Defines the time span for the sliding window used to calculate the short-term average load of a region. This window helps smooth out temporary spikes in load, reducing the chance of unnecessary rebalancing. + - **Units**: Time (e.g., `"45s"` represents 45 seconds). + - **Recommendation**: Adjust according to load volatility. Larger values smooth more effectively but may delay load balancing responses. +- `window_stability_threshold`: integer + - **Description**: Specifies the number of consecutive windows that must meet the load-balancing criteria before a region migration is triggered. This threshold helps prevent frequent balancing actions, ensuring region migration only occurs when imbalance is sustained. + - **Recommendation**: Higher values delay rebalancing triggers and suit environments with volatile loads; a value of 2 means that at least two consecutive windows must meet the threshold before triggering. +- `min_load_threshold`: string + - **Description**: Minimum write load threshold (in bytes per second) to trigger region migration. Nodes with load below this value will not trigger rebalancing. + - **Units**: Bytes (e.g., `"10MB"` represents 10 MiB). + - **Recommendation**: Set an appropriate minimum to avoid triggering region migration with low load. Adjust based on typical traffic. +- `tick_interval`: string + - **Description**: Interval at which the balancer checks and potentially triggers a rebalancing task. + - **Units**: Time (e.g., `"45s"` represents 45 seconds). + - **Recommendation**: Set based on desired responsiveness and load volatility. Shorter intervals allow faster responses but may increase overhead. \ No newline at end of file diff --git a/versioned_docs/version-0.11/enterprise/deployments/audit-logging.md b/versioned_docs/version-0.11/enterprise/deployments/audit-logging.md new file mode 100644 index 000000000..84dcd415d --- /dev/null +++ b/versioned_docs/version-0.11/enterprise/deployments/audit-logging.md @@ -0,0 +1,90 @@ +--- +description: Guide to configuring audit logging in GreptimeDB Enterprise, including examples and configuration options to monitor and record database activities. +--- + +# Audit Logging + +Database audit logging is the process of recording the actions performed on the database. The audit logs help monitor +user activities, detect suspicious actions, and ensure compliance with regulations inside or outside of an organization. +This document provides an overview of audit logging in GreptimeDB and how to configure it. + +## Overview + +A statement (SQL or PromQL) that is executed on GreptimeDB is recorded in the audit log (if it is configured to be +audited, of course). This is an example record in the audit log: + +```json +{ + "time": "2024-11-05T06:13:19.903713Z", + "user": "greptime_user", + "source": "Mysql", + "class": "Ddl", + "command": "Create", + "object_type": "Database", + "object_names": [ + "audit_test" + ], + "statement": "CREATE DATABASE audit_test" +} +``` + +As you can see, the record is formatted as a JSON string. It contains the following fields: + +- `time`: The time when the statement was executed. It's formatted as an ISO 8601 date and time string with UTC timezone. +- `user`: The user who sends the request. +- `source`: The protocol used to connect to GreptimeDB. +- `class`: The class of the statement, like "Read", "Write" or "DDL" etc. +- `command`: The command of the statement, like "Select", "Insert" or "Create" etc. +- `object_type`: The type of the object that the statement operates on, like "Database", "Table" or "Flow" etc. +- `object_names`: The names of the objects that the statement operates on. +- `statement`: The statement itself. + +## Configuration + +Audit logging is provided as a plugin in GreptimeDB. To enable and configure it, add the following TOML to your +GreptimeDB config file: + +```toml +[[plugins]] +# Add the audit log plugin to your GreptimeDB. +[plugins.audit_log] +# Whether to enable audit logging, defaults to true. +enable = true +# The directory to store the audit log files. Defaults to a directory in "/tmp". +dir = "/tmp/greptimedb/logs/" +# The allowed auditing sources. This option works as a filter: +# if a statement is not coming from one of these configured sources, it won't be recorded in the audit logs. +# Multiple sources are separated by comma(","). +# All sources are: "Http", "Mysql" and "Postgres". +# A special "all" (which is the default value) means all the sources. +sources = "all" +# The allowed auditing classes. This option works as a filter: +# if a statement's class do not match one of these configured values, it won't be recorded in the audit logs. +# Multiple classes are separated by comma(","). +# All classes are: "Read", "Write", "Admin", "DDL" and "Misc". +# A special "all" means all the classes. +# Defaults to "DDL" and "Admin". +classes = "ddl,admin" +# The allowed auditing commands. This option works as a filter: +# if a statement's command do not match one of these configured values, they won't be recorded in the audit logs. +# Multiple commands are separated by comma(","). +# All commands are: "Promql", "Select", "Copy", "Insert", "Delete", "Create", "Alter", "Truncate", "Drop", "Admin" and "Misc". +# A special "all" (which is the default value) means all the commands. +commands = "all" +# The allowed auditing object types. This option works as a filter: +# if a statement's target object do not match one of these configured values, they won't be recorded in the audit logs. +# Multiple object types are separated by comma(","). +# All object types are: "Database", "Table", "View", "Flow", "Index", and "Misc". +# A special "all" (which is the default value) means all the object types. +object_types = "all" +# The max retained audit log files. Defaults to 30. +# A audit log is rotated daily. +max_log_files = 30 +``` + +## Caveats + +Audit logs can be huge if not properly configured. For example, in a busy loaded GreptimeDB, setting "`all`" to all the +`sources`, `classes`, `commands` and `object_types` will record all the statements executed on GreptimeDB, resulting in +a very large audit log file. That could easily explode the disk space. So, it's highly recommended to configure the +audit log plugin properly to avoid such a situation. diff --git a/versioned_docs/version-0.11/enterprise/deployments/authentication.md b/versioned_docs/version-0.11/enterprise/deployments/authentication.md new file mode 100644 index 000000000..3574551b5 --- /dev/null +++ b/versioned_docs/version-0.11/enterprise/deployments/authentication.md @@ -0,0 +1,88 @@ +--- +description: Configuration guide for LDAP authentication in GreptimeDB Enterprise, detailing both simple bind and search bind modes. +--- + +# LDAP Authentication + +In addition to the built-in [static user provider](/user-guide/deployments/authentication/static.md) in GreptimeDB OSS, +GreptimeDB Enterprise offers the capability to connect to an external LDAP server for authentication. + +## Configuration + +Similar to [LDAP in PostgreSQL](https://www.postgresql.org/docs/current/auth-ldap.html), in GreptimeDB, LDAP authentication is +operated in two modes: "simple bind" and "search bind", too. + +In the "simple bind" mode, GreptimeDB will bind to the "DN"(distinguished name) constructed as +`{prefix}{username}{suffix}`. Typically, the `prefix` parameter is used to specify `cn=`, and the `suffix` is used to +specify the remaining part of the DN. The `username`, of course, is provided by the client. + +Here's the configuration file example for the "simple bind" mode in GreptimeDB's LDAP user provider: + +```toml +# Name or IP address of the LDAP server to connect to. +server = "127.0.0.1" +# Port number on LDAP server to connect to. +port = 636 +# Set to "ldap" to use LDAP, "ldaps" to use LDAPS. +# The connection between GreptimeDB and the LDAP server starts as an initially unencrypted one, +# then upgrades to TLS as the first action against the server, per the LDAPv3 standard ("StartTLS"). +scheme = "ldaps" + +# The authentication mode to the LDAP server, either `bind = "simple"` or `bind = "search"`. +[auth_mode] +# The following options are used in simple bind mode only: +bind = "simple" +# String to prepend to the username when forming the DN to bind as, when doing simple bind authentication. +prefix = "cn=" +# String to append to the username when forming the DN to bind as, when doing simple bind authentication. +suffix = ",dc=example,dc=com" +``` + +In the "search bind" mode, GreptimeDB will first try to bind to the LDAP directory with a fixed username and password, +which are set in the configuration file (`bind_dn` and `bind_passwd`), Then GreptimeDB performs a search for the user +trying to log in to the database. The search will be performed over the subtree at `base_dn`, filtered by the +`search_filter`, and will try to do an exact match of the attribute specified in `search_attribute`. Once the user has +been found in this search, GreptimeDB re-binds to the directory as this user, using the password specified by the +client, to verify that the login is correct. This method allows for significantly more flexibility in where the user +objects are located in the directory, but will cause two additional requests to the LDAP server to be made. + +The following toml snippets show the configuration file example for the "search bind" mode in GreptimeDB's LDAP user +provider. The common parts of `server`, `port`, and `scheme` as shown in the "simple bind" mode configuration file above +are omitted: + +```toml +[auth_mode] +# The following options are used in search bind mode only: +bind = "search" +# Root DN to begin the search for the user in, when doing search bind authentication. +base_dn = "ou=people,dc=example,dc=com" +# DN of user to bind to the directory with to perform the search when doing search bind authentication. +bind_dn = "cn=admin,dc=example,dc=com" +# Password for user to bind to the directory with to perform the search when doing search bind authentication. +bind_passwd = "secret" +# Attribute to match against the username in the search when doing search bind authentication. +# If no attribute is specified, the uid attribute will be used. +search_attribute = "cn" +# The search filter to use when doing search bind authentication. +# Occurrences of "$username" will be replaced with the username. +# This allows for more flexible search filters than search_attribute. +search_filter = "(cn=$username)" +``` + +## Use LDAP user provider in GreptimeDB + +To use the LDAP user provider, first config your LDAP authentication mode like above, then start GreptimeDB with the +`--user-provider` parameter set to `ldap_user_provider:`. For example, if you have +a configuration file `/home/greptimedb/ldap.toml`, you can start a GreptimeDB standalone server with the following +command: + +```shell +greptime standalone start --user-provider=ldap_user_provider:/home/greptimedb/ldap.toml +``` + +Now you can create a connection to GreptimeDB using your LDAP user accounts. + +:::tip NOTE +If you are using the MySQL CLI to connect to GreptimeDB that is configured with LDAP user provider, you need +to specify the `--enable-cleartext-plugin` in the MySQL CLI. +::: diff --git a/versioned_docs/version-0.11/enterprise/overview.md b/versioned_docs/version-0.11/enterprise/overview.md new file mode 100644 index 000000000..2537fd5a0 --- /dev/null +++ b/versioned_docs/version-0.11/enterprise/overview.md @@ -0,0 +1,30 @@ +--- +description: Overview of GreptimeDB Enterprise, detailing its advanced features, solutions, and enhancements over the open-source version to optimize data efficiency and reduce costs. +--- + +# Overview + +GreptimeDB Enterprise is a powerful time-series database solution designed to meet the specific needs of enterprises. +In addition to the features available in the open-source version of GreptimeDB, +the Enterprise edition offers enhancements that help businesses optimize data efficiency and significantly reduce costs, enabling smarter and faster decision-making with time-series data. + +GreptimeDB Enterprise solutions include: + +- **Bring Your Own Cloud (BYOC)**: Leverage your own cloud infrastructure to host GreptimeDB, offering extensive customization and flexibility tailored to your business needs. This service includes comprehensive management of your cloud resources and robust security measures to protect your infrastructure. +- **Fully Managed Dedicated Cloud**: GreptimeDB team offers a fully managed, dedicated cloud environment, ensuring peak performance, enhanced security, and exceptional reliability tailored to your enterprise needs. +- **[Edge-Cloud Integrated Solution](https://greptime.com/product/carcloud)**: A comprehensive solution for managing time-series data from edge devices to the cloud, enabling real-time analytics and insights across your entire infrastructure. +- Industry-specific solutions for the Internet of Things (IoT), observerbility, and more. + + +This section provides an overview of the advanced features available in GreptimeDB Enterprise. For information on obtaining trial access or purchasing licenses, please [contact us](https://greptime.com/contactus). + +## Features + +- [Active-Active Failover Disaster Recovery Solution](./administration/disaster-recovery/overview.md): Ensure uninterrupted service and data protection with advanced disaster recovery solution. +- [LDAP Authentication](./deployments/authentication.md): Secure your system with LDAP-based authentication for access management. +- [Audit Logging](./deployments/audit-logging.md): Track and monitor user activity with detailed audit logs. +- More feature documentation coming soon! + +## Release Notes + +- [24.11](./release-notes/release-24_11.md) diff --git a/versioned_docs/version-0.11/enterprise/release-notes/release-24_11.md b/versioned_docs/version-0.11/enterprise/release-notes/release-24_11.md new file mode 100644 index 000000000..4e2ac7630 --- /dev/null +++ b/versioned_docs/version-0.11/enterprise/release-notes/release-24_11.md @@ -0,0 +1,59 @@ +--- +description: Release notes for GreptimeDB Enterprise version 24.11, highlighting new features like region rebalancing, management console, LDAP user provider, and audit logs. +--- + +# Release 24.11 + +We are pleased to introduce the 24.11 release of GreptimeDB Enterprise. + +## Feature Highlights + +### Region Rebalance + +To enhance the overall resilience of GreptimeDB, region rebalancing enables +flexible relocation of regions among data nodes, whether initiated manually or +dynamically. + +This proactive approach facilitates several key benefits, including +redistributing workload across nodes and efficiently migrating regions to ensure +uninterrupted operation during planned maintenance activities. + +### GreptimeDB Enterprise Management Console + +Introducing the Console UI for Managing GreptimeDB Enterprise + +This initial release provides a comprehensive set of features, including: + +* In-depth slow query analysis and troubleshooting +* Detailed cluster topology information +* Real-time cluster metrics and log viewer + +### LDAP User Provider + +Bridging your own LDAP user database and authentication to GreptimeDB +Enterprise. We implemented flexible configuration options for LDAP connections, +supporting both simple and complex authentication mechanisms. + +### Audit Logs + +We provided logs to track queries in the database, with information of: + +- Query type: read, write, DDL or others +- Command: select, insert, etc. +- Object type: target of the operation, for example, table, database, etc. + +## Features From GreptimeDB OSS + +This release is based on GreptimeDB OSS v0.10. The OSS base introduces a few +new features includes + +- Vector data type support for similarity search. +- Secondary index update: user can now create secondary index on any columns. +- Alter table options are added for updating table TTL, compaction parameters + and full-text index settings. +- JSON data type and functions support. +- More geospatial UDF: spatial relation and measurement, S2 index and etc. +- Initial release of Loki remote write support. + +See [this](https://docs.greptime.com/release-notes/release-0-10-0) for a +complete changelog of 0.10 diff --git a/versioned_docs/version-0.11/faq-and-others/faq.md b/versioned_docs/version-0.11/faq-and-others/faq.md new file mode 100644 index 000000000..7069c72ab --- /dev/null +++ b/versioned_docs/version-0.11/faq-and-others/faq.md @@ -0,0 +1,219 @@ +--- +description: Frequently Asked Questions about GreptimeDB, covering use cases, performance, compatibility, features, and more. +--- + +# Frequently Asked Questions + +### How is GreptimeDB's performance compared to other solutions? + +GreptimeDB has released v0.10.2, with functionalities set to improve progressively. For detailed TSBS test results, refer to the link [here](https://github.com/GreptimeTeam/greptimedb/tree/main/docs/benchmarks/tsbs). + +### How does this compare to Loki? Is there a crate with Rust bindings available, preferably as a tracing or logging subscriber? + +GreptimeDB now supports log data types and has introduced compatibility with various industry protocols in version 0.10. These include Loki Remote Write, Vector plugins, and the full range of OTLP data types (Metrics, Traces, Logs). + +We plan to further refine the log engine, focusing on improving query performance and user experience. Future enhancements will include (but are not limited to) extending the functionality of GreptimeDB's log query DSL and implementing compatibility with some Elasticsearch/Loki APIs, providing users with more efficient and flexible log query capabilities. + +For more information about using GreptimeDB with logs, refer to the documentation: +- [Log Overview](/user-guide/logs/overview.md) +- [OpenTelemetry compatibility](/user-guide/ingest-data/for-observerbility/opentelemetry.md) +- [Loki protocol compatibility](/user-guide/ingest-data/for-observerbility/opentelemetry.md) +- [Vector compatibility](/user-guide/ingest-data/for-observerbility/vector.md) + +### What would be the use cases for a time-series database? + +Common use cases for time-series database include but are not limited to the following four scenarios: + +1. Monitor applications and infrastructure +2. Store and access IoT data +3. Process self-driving vehicle data +4. Understand financial trends + +### Does GreptimeDB have a Go driver? + +Yes, you can find our Go SDK [here](https://github.com/GreptimeTeam/greptimedb-ingester-go). + +### When will GreptimeDB release its first GA version? + +The current version has not yet reached General Availability version standards. We are trying to published v1.0 asap. + +### Are there any plans/works done for the official UI for GreptimeDB so that it would be possible to check cluster status, list of tables, statistics etc？ + +Yes, we open sourced the dashboard for users to query and visualize their data. + +Please check out our initial version on [GitHub Repo](https://github.com/GreptimeTeam/dashboard). + +### Can GreptimeDB be used as a Rust alternative to Prometheus in the observable area? + +GreptimeDB has implemented native support for PromQL, with over 90% compatibility that can cover most common usage requirement. We are keeping making it comparable to VictoriaMetrics. + +### Is GreptimeDB compatible with Grafana? + +Yes, It's compatible with Grafana. + +GreptimeDB has an official Grafana plugin: [greptimedb-grafana-datasource](https://github.com/GreptimeTeam/greptimedb-grafana-datasource/) + +GreptimeDB also supports MySQL and PostgreSQL protocol, so you can use [MySQL or PG grafana +plugin](https://grafana.com/docs/grafana/latest/datasources/mysql/) to config GreptimeDB as a datasource. Then you can use SQL to query the data. + +Also, we are implementing PromQL natively which is frequently used with Grafana. + +### How is the performance of GreptimeDB when used for non-time-series DB tables? + +GreptimeDB supports SQL and can deal with non-time-series data, especially efficient for high concurrent and throughput data writing. However, we develop GreptimeDB for a specific domain (time-series scenarios), and it doesn't support transactions and can't delete data efficiently. + +### Are there any retention policy? + +GreptimeDB supports both database-level and table-level TTLs. By default, a table inherits the TTL of its database. However, if a table is assigned a specific TTL, the table-level TTL takes precedence. For details, refer to the official documentation on TTL: [TTL Syntax Documentation](/reference/sql/create.md). + +### Where’s the name “Greptime” coming from? + +Because `grep` is the most useful command line tool on \*nix platform to search data, and time means time series. So Greptime is to help everybody to search/find value in time series data. + +### How do you measure the passing rate of PromQL compatibility tests? Is there any testing framework？ + +There’s [an issue](https://github.com/GreptimeTeam/greptimedb/issues/1042) to track the PromQL compatibility tests passing rate. It's based on Prometheus's compliance test. + +### Does GreptimeDB support schemaless? + +Yes, GreptimeDB is a schemaless database without need for creating tables in advance. The table and columns will be created automatically when writing data with protocol gRPC, InfluxDB Line Protocol, OpenTSDB, Prometheus Remote Write. + +### Does GreptimeDB support dumping table-level data to S3? + +You can use the [`COPY TO` command](/reference/sql/copy.md#s3) to dump table-level data to S3. + +### Can [Nightingale](https://n9e.github.io) now be directly integrated with GreptimeDB? How is its compatibility? + +Currently, GreptimeDB's compatibility efforts are primarily focused on the implementation of native PromQL. Going forward, we will continue to enhance compatibility with MetricQL's extended syntax. + +### Can GreptimeDB be used for a large-scale internal metrics collection system similar to Fb's Gorilla or Google's Monarch, with a preference for in-memory data and high availability? Are there plans for asynchronous WAL or optional disk storage, and how is data replication handled without WAL? + +GreptimeDB supports asynchronous WAL and is developing a per-table WAL toggle for more control. A tiered storage approach, starting with in-memory caching, is also in development. For data replication, data flushed to remote stores like S3 is replicated independently of WAL. The details for tiered storage are tracked in issue [db#2516](https://github.com/GreptimeTeam/greptimedb/issues/2516). A remote WAL implementation based on Apache Kafka ensures the durability of unflushed data in cluster mode. + +### If I delete the database, can I use the `DROP DATABASE` command? + +Yes, the `DROP DATABASE` command has been implemented in version 0.8. You can refer to the official documentation for usage: [`Drop Database`](/reference/sql/drop.md#drop). + +### What are the main differences between Greptime and another time-series database built on DataFusion like InfluxDB? + +At GreptimeDB, we share some technical similarities with InfluxDB, both using Datafusion, Arrow, Parquet, and built on object storage. However, we differ in several key aspects: + +- Open-Source Strategy: Unlike InfluxDB, which only open-sources its standalone version, our entire distributed cluster version is open-source. Our architecture can even run on edge Android systems. +- Distributed Architecture: Our architecture is more aligned with HBase's Region/RegionServer design. Our Write-Ahead Log (WAL) uses Kafka, and we're exploring a quorum-based implementation in the future. +- Workload and Services: We focus on a hybrid workload combining time series and analytics. This integration aims to enhance resource efficiency and real-time performance for users. We also offer [GreptimeCloud](https://greptime.com/product/cloud), a commercial cloud service. +- Storage Engine Design: Our pluggable storage engine is versatile. For scenarios with many small data tables, like in Prometheus, we have a dedicated Metrics storage engine. +- Query Language Support: We support PromQL for observability and SQL for data analysis, and incorporate Python for complex data processing. InfluxDB, on the other hand, uses InfluxQL and SQL. + +We're a young, rapidly evolving project and always looking to improve. For more details, visit [our Blog](https://greptime.com/blogs/) and [Contributor Guide](https://docs.greptime.com/contributor-guide/overview). We welcome your interest and contributions! + +### As a first-timer looking to contribute to GreptimeDB, where can I find a comprehensive guide to get started? + +Welcome! Please refer to our [contribution guide](https://github.com/GreptimeTeam/greptimedb/blob/main/CONTRIBUTING.md). For those new to GreptimeDB, we have a selected collection of [good first issues](https://github.com/GreptimeTeam/greptimedb/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+first+issue%22). Feel free to reach us in Slack channel anytime! + +### Does GreptimeDB have a way to handle absolute counters that can reset, like InfluxDB's non-negative differential? How do aggregations work with these counters, and is PromQL preferred over SQL for them? Also, is there a plan to integrate PromQL functions into SQL, similar to InfluxDB v3? + +GreptimeDB, like Prometheus, handles counters effectively. Functions like` reset()`, `rate()`, or `delta()` in GreptimeDB are designed to automatically detect and adjust for counter resets. While it's not recommended to use the `deriv()` function on a counter since it's meant for gauges, you can apply `rate()` to your counter and then use `deriv()`. PromQL is indeed more suitable for operations involving counters, given its origin in Prometheus. However, we are exploring the integration of PromQL functions into SQL for greater flexibility. If you're interested in implementing functions into GreptimeDB, we have documentation available which you can check out: [Greptime Documentation](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-write-aggregate-function.md). + +### What are the feature differences between the open-source version and the cloud version of GreptimeDB? + +Below are some key points: + +- **Foundational Features**: The foundational features, including the ingestion protocol, SQL capabilities, and storage functions, are largely identical between the two versions. However, GreptimeCloud offers advanced SQL functions and additional features. +- **Fully Managed Service**: GreptimeCloud is a fully managed service that supports multi-tenancy, data encryption, and security audits for compliance, which are not available in the open-source version. +- **Enhanced Dashboard**: Another significant advantage of GreptimeCloud is its superior dashboard, which is more user-friendly and includes a unique Prometheus workbench. This workbench facilitates online editing of Prometheus dashboards and alert rules, as well as GitOps integration. +- **Specialized Solutions**: GreptimeCloud introduces specialized solutions like GreptimeAI, which leverages DBaaS technology. We are also expanding our offerings to include more innovative solutions, such as those for IoT. + +As mentioned, the cloud version offers more ready-to-use features to help you get started quickly. The core features are almost identical, especially on our dedicated plan. + +### Where can I find documentation related to on-premises deployment and performance benchmark reports? + +You can find the public TSBS benchmark results [here](https://github.com/GreptimeTeam/greptimedb/tree/main/docs/benchmarks/tsbs) and the deployment documentation [here](/getting-started/installation/overview.md). + +### What should I do if the region becomes `DOWNGRADED` and the tables on that node become read-only after the datanode restarts? Is there a way to automatically reactivate it? + +According to your configuration, the failover in metasrv, which may mark the region as `DOWNGRADED`, is disabled. Another procedure that may mark a region as `DOWNGRADED` is the region migration procedure. Please try running the region migration procedure and provide feedback for further assistance. + +### Is there a guide or suggestions for compiling GreptimeDB into a standalone binary with only the necessary modules and features for an embedded environment? + +We have prebuilt binaries for Android ARM64 platforms, which have been successfully used in some enterprise projects. However, these binaries are not available for bare metal devices, as some fundamental components of GreptimeDB require a standard library. + +### Is there a built-in SQL command like `compaction table t1` that can be used for manual compaction? + +Please refer [here](/reference/sql/admin.md). + +### Can GreptimeDB be used to store logs? + +Yes, please refer [here](/user-guide/logs/overview.md ) for detailed information. + +### How is the query performance for non-primary key fields? Can inverted indexes be set? Will the storage cost be lower compared to Elasticsearch? + +Currently, non-primary key fields (or non-tag fields) do not have default inverted indexes, and we have not yet provided a `CREATE INDEX` syntax. Inverted index support will be released in an upcoming iteration along with full-text indexing. Without indexes, queries rely on MPP brute-force scanning. Although there is some parallel processing, the efficiency may not be optimal. + +As for storage costs, they will certainly be lower. You can use containers and object storage directly without relying on disks, using small local disks for buffering/caching to speed up performance. GreptimeDB employs a tiered storage architecture. For more details, please refer to our documentation on [architecture](/user-guide/concepts/architecture.md) and [storage location](/user-guide/concepts/storage-location.md). + +### Is the Log-Structured Merge-Tree engine similar to Kafka's engine model? + +From a technical storage perspective, they are similar. However, the actual data formats differ: GreptimeDB reads and writes Parquet format, while Kafka uses its own RecordBatch format. To analyze time-series data temporarily stored in Kafka, it needs to be written into GreptimeDB first. + +You can replace Kafka with EMQX, which is also a message queue. Here is a reference example: [EMQX Data Integration with GreptimeDB](https://www.emqx.com/en). The process of writing data from Kafka to GreptimeDB is quite similar. + +As mentioned, to analyze the data, it must be written into GreptimeDB first. Consume Kafka messages and write them into GreptimeDB using the provided protocols. If analyzing data directly in Kafka is necessary, you might consider the KSQL project: [KSQL GitHub Repository](https://github.com/confluentinc/ksql). However, our past attempts with KSQL encountered several issues. + +We are also working on releasing a Kafka consumer component that will automate the consumption and writing process. + +### Are there limitations on the number of tables or columns in GreptimeDB? Does having many columns affect read and write performance? + +Generally, there are no strict limitations. With a few hundred tables, as long as there aren't many primary key columns, the impact on write performance is minimal (measured by the number of points written per second, not rows). + +Similarly, for reads, if queries only involve a subset of columns, the memory and computational load will not be significantly high. + +### Can tables be dynamically partitioned by day based on timestamps, or is this unnecessary because the timestamp field already has an index? + +GreptimeDB's data is distributed in timestamp order, so there is no need to additionally shard/partition by timestamp. It is recommended to shard by primary key instead. + +### How many servers are generally needed to set up a reliable GreptimeDB cluster, and how should Frontend, Datanode, and Metasrv be deployed? Should each node run all three services regardless of the number of nodes? + +A minimum of 3 nodes is required, with each node running the 3 services: metasrv, frontend, and datanode. However, the exact number of nodes depends on the scale of data being handled. + +It is not necessary to deploy all three services on each node. A small-sized cluster can be set up with 3 nodes dedicated to metasrv. Frontend and datanode can be deployed on equal nodes, with one container running two processes. + +For more general advice for deployment, please read [Capacity Plan](/user-guide/administration/capacity-plan.md). + +### In the latest version, does the Flow Engine (pre-computation) feature support PromQL syntax for calculations? + +This is a good suggestion. Currently, the Flow Engine does not support PromQL syntax for calculations. We will evaluate this, as it seems theoretically feasible. + +### Will Metasrv support storage backends like MySQL or PostgreSQL? + +The latest version of GreptimeDB now supports PostgreSQL as the storage backend for Metasrv. For details, please refer to [here](/user-guide/deployments/configuration.md#metasrv-only-configuration). + +### What is the best way to downsample interface traffic rates (maximum rate within every hour) from multiple NICs(network interface controller) across thousands of computers every 30 seconds, so that the data can be kept for many years? + +Using a flow table is the appropriate tool for this task. A simple flow task should suffice. The output of a flow task is stored in a normal table, allowing it to be kept indefinitely. + +### Can GreptimeDB create dynamic day partitions? + +Yes. Time-based data partitioning is available by default without additional configuration. + +### Which parts of DataFusion are customized in GreptimeDB? + +GreptimeDB customizes the following aspects of DataFusion: +- PromQL query support. +- Distributed query execution. +- Custom UDFs (User-Defined Functions) and UDAFs (User-Defined Aggregate Functions). + +### Does the open-source version of GreptimeDB support fine-grained access control? + +The open-source version supports basic username-password authentication only. Fine-grained access control like RBAC is available in the enterprise edition. + +### Does writing TIMESTAMP values in datetime format affect query performance? + +No, writing in datetime format (e.g., yyyy-MM-dd HH:mm:ss) does not affect query performance. The underlying storage format remains consistent. + +### When assessing data compression, should I consider only the data directory size or include the wal directory? + +You only need to consider the data directory size. The WAL directory is cyclically reused and does not factor into data compression metrics. + +### In cluster mode, without using PARTITION during table creation, does data automatically balance across datanodes? + +Currently, data does not automatically balance across datanodes without the PARTITION feature. This capability requires the implementation of region split and auto-rebalance, which is planned for versions v1.2 or v1.3. diff --git a/versioned_docs/version-0.11/faq-and-others/overview.md b/versioned_docs/version-0.11/faq-and-others/overview.md new file mode 100644 index 000000000..33a027477 --- /dev/null +++ b/versioned_docs/version-0.11/faq-and-others/overview.md @@ -0,0 +1,3 @@ +# Overview + +In this section, we present the [most frequently asked questions](./faq.md) and some additional information. diff --git a/versioned_docs/version-0.11/getting-started/installation/greptimedb-cluster.md b/versioned_docs/version-0.11/getting-started/installation/greptimedb-cluster.md new file mode 100644 index 000000000..dba5b8a43 --- /dev/null +++ b/versioned_docs/version-0.11/getting-started/installation/greptimedb-cluster.md @@ -0,0 +1,53 @@ +--- +description: Instructions to deploy GreptimeDB in cluster mode using Kubernetes or Docker Compose, including steps for setup and cleanup. +--- + +# GreptimeDB Cluster + +The GreptimeDB cluster can run in cluster mode to scale horizontally. + +## Deploy the GreptimeDB cluster in Kubernetes + +For production environments, we recommend deploying the GreptimeDB cluster in Kubernetes. Please refer to [Deploy on Kubernetes](/user-guide/deployments/deploy-on-kubernetes/overview.md). + +## Use Docker Compose + +:::tip NOTE +Although Docker Compose is a convenient way to run the GreptimeDB cluster, it is only for development and testing purposes. + +For production environments or benchmarking, we recommend using Kubernetes. +::: + +### Prerequisites + +Using Docker Compose is the easiest way to run the GreptimeDB cluster. Before starting, make sure you have already installed the Docker. + +### Step1: Download the YAML file for Docker Compose + +``` +wget https://raw.githubusercontent.com/GreptimeTeam/greptimedb/VAR::greptimedbVersion/docker/docker-compose/cluster-with-etcd.yaml +``` + +### Step2: Start the cluster + +``` +GREPTIMEDB_VERSION=VAR::greptimedbVersion \ + docker compose -f ./cluster-with-etcd.yaml up +``` + +If the cluster starts successfully, it will listen on 4000-4003. , you can access the cluster by referencing the [Quick Start](../quick-start.md). + +### Clean up + +You can use the following command to stop the cluster: + +``` +docker compose -f ./cluster-with-etcd.yaml down +``` + +By default, the data will be stored in `/tmp/greptimedb-cluster-docker-compose`. You also can remove the data directory if you want to clean up the data. + + +## Next Steps + +Learn how to write data to GreptimeDB in [Quick Start](../quick-start.md). diff --git a/versioned_docs/version-0.11/getting-started/installation/greptimedb-dashboard.md b/versioned_docs/version-0.11/getting-started/installation/greptimedb-dashboard.md new file mode 100644 index 000000000..b95d22a5a --- /dev/null +++ b/versioned_docs/version-0.11/getting-started/installation/greptimedb-dashboard.md @@ -0,0 +1,16 @@ +--- +description: Information on accessing and using the GreptimeDB Dashboard for visualizing time series data. +--- + +# GreptimeDB Dashboard + +Visualization plays a crucial role in effectively utilizing time series data. To help users leverage the various features of GreptimeDB, Greptime offers a simple [dashboard](https://github.com/GreptimeTeam/dashboard). + +The Dashboard is embedded into GreptimeDB's binary since GreptimeDB v0.2.0. After starting [GreptimeDB Standalone](greptimedb-standalone.md) or [GreptimeDB Cluster](greptimedb-cluster.md), the dashboard can be accessed via the HTTP endpoint `http://localhost:4000/dashboard`. The dashboard supports multiple query languages, including [SQL queries](/user-guide/query-data/sql.md), and [PromQL queries](/user-guide/query-data/promql.md). + +We offer various chart types to choose from based on different scenarios. The charts become more informative when you have sufficient data. + +![line](/dashboard-line.png) +![scatter](/dashboard-scatter.png) + +We are committed to the ongoing development and iteration of this open-source project, and we plan to expand the application of time series data in monitoring, analysis, and other relevant fields in the future. diff --git a/versioned_docs/version-0.11/getting-started/installation/greptimedb-standalone.md b/versioned_docs/version-0.11/getting-started/installation/greptimedb-standalone.md new file mode 100644 index 000000000..1981fd5b9 --- /dev/null +++ b/versioned_docs/version-0.11/getting-started/installation/greptimedb-standalone.md @@ -0,0 +1,131 @@ +--- +description: Guide to install and run GreptimeDB in standalone mode using binary or Docker, including binding address configuration. +--- + +# GreptimeDB Standalone + +We use the simplest configuration for you to get started. For a comprehensive list of configurations available in GreptimeDB, see the [configuration documentation](/user-guide/deployments/configuration.md). + +## Binary + +### Download from website + +You can try out GreptimeDB by downloading the latest stable build releases from the [Download page](https://greptime.com/download). + +### Linux and macOS + +For Linux and macOS users, you can download the latest build of the `greptime` binary by using the following commands: + +```shell +curl -fsSL \ + https://raw.githubusercontent.com/greptimeteam/greptimedb/main/scripts/install.sh | sh -s VAR::greptimedbVersion +``` + +Once the download is completed, the binary file `greptime` will be stored in your current directory. + +You can run GreptimeDB in the standalone mode: + +```shell +./greptime standalone start +``` + +### Windows + +If you have WSL([Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/about)) enabled, you can lunch a latest Ubuntu and run GreptimeDB like above! + +Otherwise please download the GreptimeDB binary for Windows at our [official site](https://greptime.com/resources), and unzip the downloaded artifact. + +To run GreptimeDB in standalone mode, open a terminal (like Powershell) at the directory where the GreptimeDB binary locates, and execute: + +```shell +.\greptime standalone start +``` + +## Docker + +Make sure the [Docker](https://www.docker.com/) is already installed. If not, you can follow the official [documents](https://www.docker.com/get-started/) to install Docker. + +```shell +docker run -p 127.0.0.1:4000-4003:4000-4003 \ + -v "$(pwd)/greptimedb:/tmp/greptimedb" \ + --name greptime --rm \ + greptime/greptimedb:VAR::greptimedbVersion standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 +``` + +:::tip NOTE +To avoid accidentally exit the Docker container, you may want to run it in the "detached" mode: add the `-d` flag to +the `docker run` command. +::: + +The data will be stored in the `greptimedb/` directory in your current directory. + +If you want to use another version of GreptimeDB's image, you can download it from our [GreptimeDB Dockerhub](https://hub.docker.com/r/greptime/greptimedb). In particular, we support GreptimeDB based on CentOS, and you can try image `greptime/greptimedb-centos`. + +:::tip NOTE +If you are using a Docker version lower than [v23.0](https://docs.docker.com/engine/release-notes/23.0/), you may experience problems with insufficient permissions when trying to run the command above, due to a [bug](https://github.com/moby/moby/pull/42681) in the older version of Docker Engine. + +You can: + +1. Set `--security-opt seccomp=unconfined`, for example: + + ```shell + docker run --security-opt seccomp=unconfined -p 4000-4003:4000-4003 \ + -v "$(pwd)/greptimedb:/tmp/greptimedb" \ + --name greptime --rm \ + greptime/greptimedb:VAR::greptimedbVersion standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 + ``` + +2. Upgrade the Docker version to v23.0.0 or higher; +::: + +## Binding address + +GreptimeDB binds to `127.0.0.1` by default. If you need to accept connections from other addresses, you can start with the following parameters. + +:::danger Warning + +If the computer running GreptimeDB is directly exposed to the internet, binding to `0.0.0.0` is dangerous and will expose the instance to everybody on the internet. + + + + + +```shell +./greptime standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 +``` + + + + + +```shell +docker run -p 0.0.0.0:4000-4003:4000-4003 \ + -v "$(pwd)/greptimedb:/tmp/greptimedb" \ + --name greptime --rm \ + greptime/greptimedb:VAR::greptimedbVersion standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 +``` + + + + +You can also refer to the [Configuration](/user-guide/deployments/configuration.md) document to modify the bind address in the configuration file. + +## Next Steps + +Learn how to write data to GreptimeDB in the [Quick Start](../quick-start.md). diff --git a/versioned_docs/version-0.11/getting-started/installation/overview.md b/versioned_docs/version-0.11/getting-started/installation/overview.md new file mode 100644 index 000000000..3909469b0 --- /dev/null +++ b/versioned_docs/version-0.11/getting-started/installation/overview.md @@ -0,0 +1,30 @@ +--- +description: Instructions to install GreptimeDB, check its health status, and proceed to the quick start guide. +--- + +# Overview + +## Installation + +Follow these instructions to install GreptimeDB: + +- [GreptimeDB Standalone](greptimedb-standalone.md) runs as a standalone system in a single process. +- [GreptimeDB Cluster](greptimedb-cluster.md) runs as a distributed, clustered time series database. + +## Check database health + +After starting GreptimeDB, you can check its status to ensure it is running. + +```shell +curl http://localhost:4000/health +``` + +If the GreptimeDB instance is running healthily, you will see the following response: + +```json +{} +``` + +## Next steps + +- [Quick Start](/getting-started/quick-start.md): Ingest and query data in GreptimeDB using MySQL or PostgreSQL clients. diff --git a/versioned_docs/version-0.11/getting-started/overview.md b/versioned_docs/version-0.11/getting-started/overview.md new file mode 100644 index 000000000..0a4646db2 --- /dev/null +++ b/versioned_docs/version-0.11/getting-started/overview.md @@ -0,0 +1,6 @@ +# Overview + +Get started with GreptimeDB quickly by following these steps: + +- [Installation](./installation/overview.md): Learn how to install GreptimeDB as a standalone or cluster. +- [Quick Start](./quick-start.md): Get started with GreptimeDB using your preferred protocols or languages. diff --git a/versioned_docs/version-0.11/getting-started/quick-start.md b/versioned_docs/version-0.11/getting-started/quick-start.md new file mode 100644 index 000000000..aa8f09faa --- /dev/null +++ b/versioned_docs/version-0.11/getting-started/quick-start.md @@ -0,0 +1,387 @@ +--- +description: A guide to quickly start with GreptimeDB, including connecting to the database, creating tables, inserting data, querying data, and using the GreptimeDB dashboard. +--- + +# Quick Start + +Before proceeding, please ensure you have [installed GreptimeDB](./installation/overview.md). + +This guide will walk you through creating a metric table and a log table, highlighting the core features of GreptimeDB. + +## Connect to GreptimeDB + +GreptimeDB supports [multiple protocols](/user-guide/protocols/overview.md) for interacting with the database. +In this quick start document, we use SQL for simplicity. + +If your GreptimeDB instance is running on `127.0.0.1` with the MySQL client default port `4002` or the PostgreSQL client default port `4003`, +you can connect to GreptimeDB using the following commands. + +By default, GreptimeDB does not have [authentication](/user-guide/deployments/authentication/overview.md) enabled. +You can connect to the database without providing a username and password in this section. + +```shell +mysql -h 127.0.0.1 -P 4002 +``` + +Or + +```shell +psql -h 127.0.0.1 -p 4003 -d public +``` + +## Create tables + +Suppose you have a table named `grpc_latencies` that stores the gRPC latencies of your application. +The table schema is as follows: + +```sql +CREATE TABLE grpc_latencies ( + ts TIMESTAMP TIME INDEX, + host STRING, + method_name STRING, + latency DOUBLE, + PRIMARY KEY (host, method_name) +) with('append_mode'='true'); +``` + +- `ts`: The timestamp when the metric was collected. It is the time index column. +- `host`: The hostname of the application server. It is a tag column. +- `method_name`: The name of the RPC request method. It is a tag column. +- `latency`: The latency of the RPC request. + +Additionally, there is a table `app_logs` for storing application logs: + +```sql +CREATE TABLE app_logs ( + ts TIMESTAMP TIME INDEX, + host STRING, + api_path STRING FULLTEXT, + log_level STRING, + log STRING FULLTEXT, + PRIMARY KEY (host, log_level) +) with('append_mode'='true'); +``` + +- `ts`: The timestamp of the log entry. It is the time index column. +- `host`: The hostname of the application server. It is a tag column. +- `api_path`: The API path, [indexed with `FULLTEXT`](/user-guide/logs/query-logs.md#full-text-index-for-accelerated-search) for accelerated search.. +- `log_level`: The log level of the log entry. It is a tag column. +- `log`: The log message, [indexed with `FULLTEXT`](/user-guide/logs/query-logs.md#full-text-index-for-accelerated-search) for accelerated search. + +## Write data + +Let's insert some mocked data to simulate collected metrics and error logs. + +Two application servers, `host1` and `host2`, +have been recording gRPC latencies. Starting from `2024-07-11 20:00:10`, +`host1` experienced a significant increase in latency. + +The following image shows the unstable latencies of `host1`. + +unstable latencies + +The following SQL statements insert the mocked data. + +Before `2024-07-11 20:00:10`, the hosts were functioning normally: + +```sql +INSERT INTO grpc_latencies (ts, host, method_name, latency) VALUES + ('2024-07-11 20:00:06', 'host1', 'GetUser', 103.0), + ('2024-07-11 20:00:06', 'host2', 'GetUser', 113.0), + ('2024-07-11 20:00:07', 'host1', 'GetUser', 103.5), + ('2024-07-11 20:00:07', 'host2', 'GetUser', 107.0), + ('2024-07-11 20:00:08', 'host1', 'GetUser', 104.0), + ('2024-07-11 20:00:08', 'host2', 'GetUser', 96.0), + ('2024-07-11 20:00:09', 'host1', 'GetUser', 104.5), + ('2024-07-11 20:00:09', 'host2', 'GetUser', 114.0); +``` + +After `2024-07-11 20:00:10`, `host1`'s latencies becomes unstable: + +```sql + +INSERT INTO grpc_latencies (ts, host, method_name, latency) VALUES + ('2024-07-11 20:00:10', 'host1', 'GetUser', 150.0), + ('2024-07-11 20:00:10', 'host2', 'GetUser', 110.0), + ('2024-07-11 20:00:11', 'host1', 'GetUser', 200.0), + ('2024-07-11 20:00:11', 'host2', 'GetUser', 102.0), + ('2024-07-11 20:00:12', 'host1', 'GetUser', 1000.0), + ('2024-07-11 20:00:12', 'host2', 'GetUser', 108.0), + ('2024-07-11 20:00:13', 'host1', 'GetUser', 80.0), + ('2024-07-11 20:00:13', 'host2', 'GetUser', 111.0), + ('2024-07-11 20:00:14', 'host1', 'GetUser', 4200.0), + ('2024-07-11 20:00:14', 'host2', 'GetUser', 95.0), + ('2024-07-11 20:00:15', 'host1', 'GetUser', 90.0), + ('2024-07-11 20:00:15', 'host2', 'GetUser', 115.0), + ('2024-07-11 20:00:16', 'host1', 'GetUser', 3000.0), + ('2024-07-11 20:00:16', 'host2', 'GetUser', 95.0), + ('2024-07-11 20:00:17', 'host1', 'GetUser', 320.0), + ('2024-07-11 20:00:17', 'host2', 'GetUser', 115.0), + ('2024-07-11 20:00:18', 'host1', 'GetUser', 3500.0), + ('2024-07-11 20:00:18', 'host2', 'GetUser', 95.0), + ('2024-07-11 20:00:19', 'host1', 'GetUser', 100.0), + ('2024-07-11 20:00:19', 'host2', 'GetUser', 115.0), + ('2024-07-11 20:00:20', 'host1', 'GetUser', 2500.0), + ('2024-07-11 20:00:20', 'host2', 'GetUser', 95.0); +``` + +Some error logs were collected when the `host1` latencies of RPC requests encounter latency issues. + +```sql +INSERT INTO app_logs (ts, host, api_path, log_level, log) VALUES + ('2024-07-11 20:00:10', 'host1', '/api/v1/resource', 'ERROR', 'Connection timeout'), + ('2024-07-11 20:00:10', 'host1', '/api/v1/billings', 'ERROR', 'Connection timeout'), + ('2024-07-11 20:00:11', 'host1', '/api/v1/resource', 'ERROR', 'Database unavailable'), + ('2024-07-11 20:00:11', 'host1', '/api/v1/billings', 'ERROR', 'Database unavailable'), + ('2024-07-11 20:00:12', 'host1', '/api/v1/resource', 'ERROR', 'Service overload'), + ('2024-07-11 20:00:12', 'host1', '/api/v1/billings', 'ERROR', 'Service overload'), + ('2024-07-11 20:00:13', 'host1', '/api/v1/resource', 'ERROR', 'Connection reset'), + ('2024-07-11 20:00:13', 'host1', '/api/v1/billings', 'ERROR', 'Connection reset'), + ('2024-07-11 20:00:14', 'host1', '/api/v1/resource', 'ERROR', 'Timeout'), + ('2024-07-11 20:00:14', 'host1', '/api/v1/billings', 'ERROR', 'Timeout'), + ('2024-07-11 20:00:15', 'host1', '/api/v1/resource', 'ERROR', 'Disk full'), + ('2024-07-11 20:00:15', 'host1', '/api/v1/billings', 'ERROR', 'Disk full'), + ('2024-07-11 20:00:16', 'host1', '/api/v1/resource', 'ERROR', 'Network issue'), + ('2024-07-11 20:00:16', 'host1', '/api/v1/billings', 'ERROR', 'Network issue'); +``` + +## Query data + +### Filter by tags and time index + +You can filter data using the WHERE clause. +For example, to query the latency of `host1` after `2024-07-11 20:00:15`: + +```sql +SELECT * + FROM grpc_latencies + WHERE host = 'host1' AND ts > '2024-07-11 20:00:15'; +``` + +```sql ++---------------------+-------+-------------+---------+ +| ts | host | method_name | latency | ++---------------------+-------+-------------+---------+ +| 2024-07-11 20:00:16 | host1 | GetUser | 3000 | +| 2024-07-11 20:00:17 | host1 | GetUser | 320 | +| 2024-07-11 20:00:18 | host1 | GetUser | 3500 | +| 2024-07-11 20:00:19 | host1 | GetUser | 100 | +| 2024-07-11 20:00:20 | host1 | GetUser | 2500 | ++---------------------+-------+-------------+---------+ +5 rows in set (0.14 sec) +``` + +You can also use functions when filtering the data. +For example, you can use `approx_percentile_cont` to calculate the 95th percentile of the latency grouped by the host: + +```sql +SELECT + approx_percentile_cont(latency, 0.95) AS p95_latency, + host +FROM grpc_latencies +WHERE ts >= '2024-07-11 20:00:10' +GROUP BY host; +``` + +```sql ++-------------------+-------+ +| p95_latency | host | ++-------------------+-------+ +| 4164.999999999999 | host1 | +| 115 | host2 | ++-------------------+-------+ +2 rows in set (0.11 sec) +``` + +### Range query + +You can use [range queries](/reference/sql/range.md#range-query) to monitor latencies in real-time. +For example, to calculate the p95 latency of requests using a 5-second window: + +```sql +SELECT + ts, + host, + approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency +FROM + grpc_latencies +ALIGN '5s' FILL PREV; +``` + +```sql ++---------------------+-------+-------------+ +| ts | host | p95_latency | ++---------------------+-------+-------------+ +| 2024-07-11 20:00:05 | host2 | 114 | +| 2024-07-11 20:00:10 | host2 | 111 | +| 2024-07-11 20:00:15 | host2 | 115 | +| 2024-07-11 20:00:20 | host2 | 95 | +| 2024-07-11 20:00:05 | host1 | 104.5 | +| 2024-07-11 20:00:10 | host1 | 4200 | +| 2024-07-11 20:00:15 | host1 | 3500 | +| 2024-07-11 20:00:20 | host1 | 2500 | ++---------------------+-------+-------------+ +8 rows in set (0.06 sec) +``` + +### Full-text search + +You can use `matches` to search for the columns with the `FULLTEXT` index. +For example, to search for logs with error `timeout`: + +```sql +SELECT + ts, + api_path, + log +FROM + app_logs +WHERE + matches(log, 'timeout'); +``` + +```sql ++---------------------+------------------+--------------------+ +| ts | api_path | log | ++---------------------+------------------+--------------------+ +| 2024-07-11 20:00:10 | /api/v1/billings | Connection timeout | +| 2024-07-11 20:00:10 | /api/v1/resource | Connection timeout | ++---------------------+------------------+--------------------+ +2 rows in set (0.01 sec) +``` + +### Correlate Metrics and Logs + +By combining the data from the two tables, +you can easily and quickly determine the time of failure and the corresponding logs. +The following SQL query uses the `JOIN` operation to correlate the metrics and logs: + +```sql +WITH + metrics AS ( + SELECT + ts, + host, + approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency + FROM + grpc_latencies + ALIGN '5s' FILL PREV + ), + logs AS ( + SELECT + ts, + host, + count(log) RANGE '5s' AS num_errors, + FROM + app_logs + WHERE + log_level = 'ERROR' + ALIGN '5s' +) +--- Analyze and correlate metrics and logs --- +SELECT + metrics.ts, + p95_latency, + coalesce(num_errors, 0) as num_errors, + metrics.host +FROM + metrics + LEFT JOIN logs ON metrics.host = logs.host + AND metrics.ts = logs.ts +ORDER BY + metrics.ts; +``` + + +```sql ++---------------------+-------------+------------+-------+ +| ts | p95_latency | num_errors | host | ++---------------------+-------------+------------+-------+ +| 2024-07-11 20:00:05 | 114 | 0 | host2 | +| 2024-07-11 20:00:05 | 104.5 | 0 | host1 | +| 2024-07-11 20:00:10 | 4200 | 10 | host1 | +| 2024-07-11 20:00:10 | 111 | 0 | host2 | +| 2024-07-11 20:00:15 | 115 | 0 | host2 | +| 2024-07-11 20:00:15 | 3500 | 4 | host1 | +| 2024-07-11 20:00:20 | 110 | 0 | host2 | +| 2024-07-11 20:00:20 | 2500 | 0 | host1 | ++---------------------+-------------+------------+-------+ +8 rows in set (0.02 sec) +``` + + + +## GreptimeDB Dashboard + +GreptimeDB offers a [dashboard](./installation/greptimedb-dashboard.md) for data exploration and management. + +### Explore data + +Once GreptimeDB is started as mentioned in the [installation section](./installation/overview.md), you can access the dashboard through the HTTP endpoint `http://localhost:4000/dashboard`. + +To add a new query, click on the `+` button, write your SQL command in the command text, and then click on `Run All`. +The following SQL will retrieve all the data from the `grpc_latencies` table. + +```sql +SELECT * FROM grpc_latencies; +``` + +Then click on the `Chart` button in the result panel to visualize the data. + +![select gRPC latencies](/select-grpc-latencies.png) + +### Ingest data by InfluxDB Line Protocol + +Besides SQL, GreptimeDB also supports multiple protocols, one of the most popular is InfluxDB Line Protocol. +By click `Ingest` icon in the dashboard, you can upload data in InfluxDB Line Protocol format. + +For example, paste the following data into the input box: + +```txt +grpc_metrics,host=host1,method_name=GetUser latency=100,code=0 1720728021000000000 +grpc_metrics,host=host2,method_name=GetUser latency=110,code=1 1720728021000000000 +``` + +Then click the `Write` button to ingest the data to the table `grpc_metrics`. +The `grpc_metrics` table will be created automatically if it does not exist. + +## Next steps + +You have now experienced the core features of GreptimeDB. +To further explore and utilize GreptimeDB: + +- [Visualize data using Grafana](/user-guide/integrations/grafana.md) +- [Explore more demos of GreptimeDB](https://github.com/GreptimeTeam/demo-scene/) +- [Read the user guide document to learn more details about GreptimeDB](/user-guide/overview.md) diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/create-service.md b/versioned_docs/version-0.11/greptimecloud/getting-started/create-service.md similarity index 100% rename from versioned_docs/version-0.10/greptimecloud/getting-started/create-service.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/create-service.md diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/go.md b/versioned_docs/version-0.11/greptimecloud/getting-started/go.md similarity index 84% rename from versioned_docs/version-0.10/greptimecloud/getting-started/go.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/go.md index 90bf010c5..79bc7ce63 100644 --- a/versioned_docs/version-0.10/greptimecloud/getting-started/go.md +++ b/versioned_docs/version-0.11/greptimecloud/getting-started/go.md @@ -1,3 +1,7 @@ +--- +description: Instructions on creating a service, writing data using Go, and visualizing data in GreptimeDB. +--- + # Go ## Create Service diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/influxdb.md b/versioned_docs/version-0.11/greptimecloud/getting-started/influxdb.md similarity index 84% rename from versioned_docs/version-0.10/greptimecloud/getting-started/influxdb.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/influxdb.md index 6e0093592..b048a4d92 100644 --- a/versioned_docs/version-0.10/greptimecloud/getting-started/influxdb.md +++ b/versioned_docs/version-0.11/greptimecloud/getting-started/influxdb.md @@ -1,3 +1,7 @@ +--- +description: Instructions on creating a service, writing data using InfluxDB Line Protocol, and visualizing data in GreptimeDB. +--- + # InfluxDB Line Protocol ## Create Service diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/java.md b/versioned_docs/version-0.11/greptimecloud/getting-started/java.md similarity index 86% rename from versioned_docs/version-0.10/greptimecloud/getting-started/java.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/java.md index 4a776988a..f07157c1d 100644 --- a/versioned_docs/version-0.10/greptimecloud/getting-started/java.md +++ b/versioned_docs/version-0.11/greptimecloud/getting-started/java.md @@ -1,3 +1,7 @@ +--- +description: Instructions on creating a service, writing data using Java, and visualizing data in GreptimeDB. +--- + # Java ## Create Service diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/mysql.md b/versioned_docs/version-0.11/greptimecloud/getting-started/mysql.md similarity index 84% rename from versioned_docs/version-0.10/greptimecloud/getting-started/mysql.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/mysql.md index a669e3e87..529a8d3a4 100644 --- a/versioned_docs/version-0.10/greptimecloud/getting-started/mysql.md +++ b/versioned_docs/version-0.11/greptimecloud/getting-started/mysql.md @@ -1,3 +1,7 @@ +--- +description: Instructions on creating a service, writing data using MySQL, and visualizing data in GreptimeDB. +--- + # MySQL ## Create Service diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/node.md b/versioned_docs/version-0.11/greptimecloud/getting-started/node.md similarity index 84% rename from versioned_docs/version-0.10/greptimecloud/getting-started/node.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/node.md index 0ff4d986d..2fafbf607 100644 --- a/versioned_docs/version-0.10/greptimecloud/getting-started/node.md +++ b/versioned_docs/version-0.11/greptimecloud/getting-started/node.md @@ -1,3 +1,7 @@ +--- +description: Instructions on creating a service, writing data using Node.js, and visualizing data in GreptimeDB. +--- + # Node.js ## Create Service diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/overview.md b/versioned_docs/version-0.11/greptimecloud/getting-started/overview.md similarity index 100% rename from versioned_docs/version-0.10/greptimecloud/getting-started/overview.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/overview.md diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/prometheus.md b/versioned_docs/version-0.11/greptimecloud/getting-started/prometheus.md similarity index 88% rename from versioned_docs/version-0.10/greptimecloud/getting-started/prometheus.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/prometheus.md index e4e00f4f2..f0d2b247a 100644 --- a/versioned_docs/version-0.10/greptimecloud/getting-started/prometheus.md +++ b/versioned_docs/version-0.11/greptimecloud/getting-started/prometheus.md @@ -1,3 +1,7 @@ +--- +description: Instructions on creating a service, writing data using Prometheus, and visualizing data in GreptimeDB. +--- + # Prometheus ## Create Service diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/python.md b/versioned_docs/version-0.11/greptimecloud/getting-started/python.md similarity index 86% rename from versioned_docs/version-0.10/greptimecloud/getting-started/python.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/python.md index f71ce7a98..b5eec5f78 100644 --- a/versioned_docs/version-0.10/greptimecloud/getting-started/python.md +++ b/versioned_docs/version-0.11/greptimecloud/getting-started/python.md @@ -1,3 +1,7 @@ +--- +description: Instructions on creating a service, writing data using Python, and visualizing data in GreptimeDB. +--- + # Python ## Create Service diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/vector.md b/versioned_docs/version-0.11/greptimecloud/getting-started/vector.md similarity index 69% rename from versioned_docs/version-0.10/greptimecloud/getting-started/vector.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/vector.md index 5a6f2a7b5..038f67fbd 100644 --- a/versioned_docs/version-0.10/greptimecloud/getting-started/vector.md +++ b/versioned_docs/version-0.11/greptimecloud/getting-started/vector.md @@ -1,7 +1,11 @@ +--- +description: Instructions on creating a service, writing data using Vector, and visualizing data in GreptimeDB. +--- + # Vector ## Create Service -import Includecreateservice from './create-service.md' +import Includecreateservice from './create-service.md' @@ -17,10 +21,12 @@ scrape_interval_secs = 30 [sinks.greptime] inputs = ["in"] type = "greptimedb" -endpoint = ":4001" +endpoint = ":5001" dbname = "" username = "" password = "" +new_naming = true +tls = {} ``` Then start vector with the specified configuration file: @@ -30,6 +36,6 @@ vector --config vector.toml ``` ## Visualize Data -import Includevisualizedata from './visualize-data.md' +import Includevisualizedata from './visualize-data.md' diff --git a/versioned_docs/version-0.10/greptimecloud/getting-started/visualize-data.md b/versioned_docs/version-0.11/greptimecloud/getting-started/visualize-data.md similarity index 100% rename from versioned_docs/version-0.10/greptimecloud/getting-started/visualize-data.md rename to versioned_docs/version-0.11/greptimecloud/getting-started/visualize-data.md diff --git a/versioned_docs/version-0.10/greptimecloud/greptimeai/langchain.md b/versioned_docs/version-0.11/greptimecloud/greptimeai/langchain.md similarity index 100% rename from versioned_docs/version-0.10/greptimecloud/greptimeai/langchain.md rename to versioned_docs/version-0.11/greptimecloud/greptimeai/langchain.md diff --git a/versioned_docs/version-0.10/greptimecloud/greptimeai/openai.md b/versioned_docs/version-0.11/greptimecloud/greptimeai/openai.md similarity index 100% rename from versioned_docs/version-0.10/greptimecloud/greptimeai/openai.md rename to versioned_docs/version-0.11/greptimecloud/greptimeai/openai.md diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/alloy.md b/versioned_docs/version-0.11/greptimecloud/integrations/alloy.md similarity index 88% rename from versioned_docs/version-0.10/greptimecloud/integrations/alloy.md rename to versioned_docs/version-0.11/greptimecloud/integrations/alloy.md index a6153c12f..ddd8c0fa4 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/alloy.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/alloy.md @@ -1,3 +1,7 @@ +--- +description: Instructions on integrating GreptimeCloud with Grafana Alloy for Prometheus Remote Write and OpenTelemetry. +--- + # Alloy [Grafana Alloy](https://grafana.com/docs/alloy/latest/) is an observability data pipeline as well as an OpenTelemetry diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/dbeaver.md b/versioned_docs/version-0.11/greptimecloud/integrations/dbeaver.md similarity index 90% rename from versioned_docs/version-0.10/greptimecloud/integrations/dbeaver.md rename to versioned_docs/version-0.11/greptimecloud/integrations/dbeaver.md index 5e69f0c1f..dd63d000f 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/dbeaver.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/dbeaver.md @@ -1,3 +1,7 @@ +--- +description: Guide on using DBeaver to connect to GreptimeCloud via MySQL database drivers. +--- + # DBeaver [DBeaver](https://dbeaver.io/) is a free, open-source, and cross-platform database tool that supports all popular databases. It is a popular choice among developers and database administrators for its ease of use and extensive feature set. diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/emqx.md b/versioned_docs/version-0.11/greptimecloud/integrations/emqx.md similarity index 89% rename from versioned_docs/version-0.10/greptimecloud/integrations/emqx.md rename to versioned_docs/version-0.11/greptimecloud/integrations/emqx.md index d223c1135..2a2d6f3a9 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/emqx.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/emqx.md @@ -1,3 +1,7 @@ +--- +description: Instructions on configuring GreptimeCloud as a data sink in EMQX Platform for IoT data ingestion. +--- + # EMQX Platform [EMQX Platform](https://www.emqx.io/) is an MQTT Gateway, designed to handle diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/grafana.md b/versioned_docs/version-0.11/greptimecloud/integrations/grafana.md similarity index 93% rename from versioned_docs/version-0.10/greptimecloud/integrations/grafana.md rename to versioned_docs/version-0.11/greptimecloud/integrations/grafana.md index 60a866392..1ce9d70ec 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/grafana.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/grafana.md @@ -1,3 +1,7 @@ +--- +description: Guide on configuring GreptimeCloud as a data source in Grafana using GreptimeDB, Prometheus, or MySQL data sources. +--- + # Grafana GreptimeDB can be configured as a [Grafana data source](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/). diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/influxdb.md b/versioned_docs/version-0.11/greptimecloud/integrations/influxdb.md similarity index 91% rename from versioned_docs/version-0.10/greptimecloud/integrations/influxdb.md rename to versioned_docs/version-0.11/greptimecloud/integrations/influxdb.md index 244077781..1141d04c0 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/influxdb.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/influxdb.md @@ -1,3 +1,7 @@ +--- +description: Instructions on using InfluxDB line protocol and Telegraf to ingest data into GreptimeCloud. +--- + # InfluxDB and Telegraf GreptimeCloud provides [Influxdb line diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/kafka.md b/versioned_docs/version-0.11/greptimecloud/integrations/kafka.md similarity index 92% rename from versioned_docs/version-0.10/greptimecloud/integrations/kafka.md rename to versioned_docs/version-0.11/greptimecloud/integrations/kafka.md index 712f31343..174e68e50 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/kafka.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/kafka.md @@ -1,3 +1,7 @@ +--- +description: Guide on using Kafka with Vector to ingest logs and metrics data into GreptimeCloud. +--- + # Kafka If you are using Kafka or Kafka-compatible message queue for observability data diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/metabase.md b/versioned_docs/version-0.11/greptimecloud/integrations/metabase.md similarity index 79% rename from versioned_docs/version-0.10/greptimecloud/integrations/metabase.md rename to versioned_docs/version-0.11/greptimecloud/integrations/metabase.md index e86e6b901..cb0fd3b7f 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/metabase.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/metabase.md @@ -1,3 +1,7 @@ +--- +description: Instructions on configuring GreptimeCloud as a data source in Metabase using a community driver plugin. +--- + # Metabase [Metabase](https://github.com/metabase/metabase) is an open source BI tool that diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/mindsdb.md b/versioned_docs/version-0.11/greptimecloud/integrations/mindsdb.md similarity index 86% rename from versioned_docs/version-0.10/greptimecloud/integrations/mindsdb.md rename to versioned_docs/version-0.11/greptimecloud/integrations/mindsdb.md index d45471145..ed73adbcc 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/mindsdb.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/mindsdb.md @@ -1,3 +1,7 @@ +--- +description: Guide on configuring GreptimeCloud as a data source in MindsDB for machine learning capabilities. +--- + # MindsDB [MindsDB](https://mindsdb.com/) is an open-source machine learning platform that diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/mysql.md b/versioned_docs/version-0.11/greptimecloud/integrations/mysql.md similarity index 88% rename from versioned_docs/version-0.10/greptimecloud/integrations/mysql.md rename to versioned_docs/version-0.11/greptimecloud/integrations/mysql.md index d0bc279ed..16347eabb 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/mysql.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/mysql.md @@ -1,3 +1,7 @@ +--- +description: Instructions for connecting to GreptimeCloud using MySQL protocol, including connection details, MySQL CLI, MariaDB CLI, and JDBC URL. +--- + # MySQL GreptimeCloud exposes GreptimeDB access in MySQL server-client protocol. Most diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/otlp.md b/versioned_docs/version-0.11/greptimecloud/integrations/otlp.md similarity index 93% rename from versioned_docs/version-0.10/greptimecloud/integrations/otlp.md rename to versioned_docs/version-0.11/greptimecloud/integrations/otlp.md index ed56bd780..620c4f354 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/otlp.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/otlp.md @@ -1,3 +1,7 @@ +--- +description: Guide for using GreptimeDB as an observability backend with OpenTelemetry, including API/SDK configuration and OpenTelemetry Collector setup. +--- + # OpenTelemetry GreptimeDB is an observability backend to consume OpenTelemetry Metrics natively diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/postgresql.md b/versioned_docs/version-0.11/greptimecloud/integrations/postgresql.md similarity index 70% rename from versioned_docs/version-0.10/greptimecloud/integrations/postgresql.md rename to versioned_docs/version-0.11/greptimecloud/integrations/postgresql.md index b01d23141..c9549e5e3 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/postgresql.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/postgresql.md @@ -1,3 +1,7 @@ +--- +description: Instructions for connecting to GreptimeCloud using PostgreSQL protocol, including connection details, psql CLI, connection strings, and JDBC URL. +--- + # PostgreSQL GreptimeCloud exposes GreptimeDB access in PostgreSQL v3 wire protocol. Most @@ -44,3 +48,18 @@ If you are using clients from Python, you might be able to use following URL ```text postgresql://:@:4003/ ``` + +## Postgres Foreign Data Wrapper + +Configure your GreptimeCloud instance as Postgres FDW. Change server name and +username to your own. + +```sql +CREATE SERVER greptimedb +FOREIGN DATA WRAPPER postgres_fdw +OPTIONS (host '', dbname '', port '4003'); + +CREATE USER MAPPING FOR postgres +SERVER greptimedb +OPTIONS (user '', password ''); +``` diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/prometheus.md b/versioned_docs/version-0.11/greptimecloud/integrations/prometheus.md similarity index 91% rename from versioned_docs/version-0.10/greptimecloud/integrations/prometheus.md rename to versioned_docs/version-0.11/greptimecloud/integrations/prometheus.md index 6cedde981..e4708d1f5 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/prometheus.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/prometheus.md @@ -1,3 +1,7 @@ +--- +description: Guide for integrating Prometheus with GreptimeCloud, including remote write configuration, HTTP API access, and using PromQL. +--- + # Prometheus GreptimeCloud with GreptimeDB is fully compatible with Prometheus. This ensures diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/sdk-libraries/go.md b/versioned_docs/version-0.11/greptimecloud/integrations/sdk-libraries/go.md similarity index 86% rename from versioned_docs/version-0.10/greptimecloud/integrations/sdk-libraries/go.md rename to versioned_docs/version-0.11/greptimecloud/integrations/sdk-libraries/go.md index 9c1861831..7eed8f322 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/sdk-libraries/go.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/sdk-libraries/go.md @@ -1,3 +1,7 @@ +--- +description: Instructions on how to use the GreptimeDB Go SDK to connect to GreptimeCloud using gRPC. +--- + # Go SDK The GreptimeDB Go ingester library utilizes gRPC for writing data to the database. For how to use the library, please refer to the [Go library documentation](https://docs.greptime.com/user-guide/ingest-data/for-iot/grpc-sdks/go). diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/sdk-libraries/java.md b/versioned_docs/version-0.11/greptimecloud/integrations/sdk-libraries/java.md similarity index 87% rename from versioned_docs/version-0.10/greptimecloud/integrations/sdk-libraries/java.md rename to versioned_docs/version-0.11/greptimecloud/integrations/sdk-libraries/java.md index d6350a799..dc7dbb03b 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/sdk-libraries/java.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/sdk-libraries/java.md @@ -1,3 +1,7 @@ +--- +description: Instructions on how to use the GreptimeDB Java SDK to connect to GreptimeCloud using gRPC. +--- + # Java SDK The GreptimeDB Java ingester library utilizes gRPC for writing data to the database. For how to use the library, please refer to the [Java library documentation](https://docs.greptime.com/user-guide/ingest-data/for-iot/grpc-sdks/java). diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/streamlit.md b/versioned_docs/version-0.11/greptimecloud/integrations/streamlit.md similarity index 82% rename from versioned_docs/version-0.10/greptimecloud/integrations/streamlit.md rename to versioned_docs/version-0.11/greptimecloud/integrations/streamlit.md index 937790a4f..5b71031b0 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/streamlit.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/streamlit.md @@ -1,3 +1,7 @@ +--- +description: Instructions for using GreptimeCloud with Streamlit to build data apps, including creating a SQL connection and running SQL queries. +--- + # Streamlit Streamlit is a faster way to build and share data apps. It's possible to build diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/superset.md b/versioned_docs/version-0.11/greptimecloud/integrations/superset.md similarity index 76% rename from versioned_docs/version-0.10/greptimecloud/integrations/superset.md rename to versioned_docs/version-0.11/greptimecloud/integrations/superset.md index 53c5b7840..8600dbc46 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/superset.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/superset.md @@ -1,3 +1,7 @@ +--- +description: Guide for configuring GreptimeCloud as a data source in Superset, including connection information and SQLAlchemy URL format. +--- + # Superset [Superset](https://superset.apache.org) is an open source BI tool that written diff --git a/versioned_docs/version-0.10/greptimecloud/integrations/vector.md b/versioned_docs/version-0.11/greptimecloud/integrations/vector.md similarity index 86% rename from versioned_docs/version-0.10/greptimecloud/integrations/vector.md rename to versioned_docs/version-0.11/greptimecloud/integrations/vector.md index 2f8f24b44..0d4809754 100644 --- a/versioned_docs/version-0.10/greptimecloud/integrations/vector.md +++ b/versioned_docs/version-0.11/greptimecloud/integrations/vector.md @@ -1,3 +1,7 @@ +--- +description: Guide for using Vector with GreptimeCloud, including configuration for metrics and logs ingestion, and running Vector with a sample configuration. +--- + # Vector Vector is [a high performance observability data @@ -22,6 +26,7 @@ dbname = "" username = "" password = "" tls = {} +new_naming = true ## logs [sources.logs_in] diff --git a/versioned_docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md b/versioned_docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md similarity index 96% rename from versioned_docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md rename to versioned_docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md index 3d5d65d31..dfb36946c 100644 --- a/versioned_docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md +++ b/versioned_docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb.md @@ -1,3 +1,7 @@ +--- +description: Instructions for migrating from InfluxDB to GreptimeCloud, including database connection, writing data using HTTP API, Telegraf, client libraries, and data visualization. +--- + import DocTemplate from '../../db-cloud-shared/migrate/migrate-from-influxdb.md' # Migrate from InfluxDB diff --git a/versioned_docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md b/versioned_docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md similarity index 82% rename from versioned_docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md rename to versioned_docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md index 72945de04..bdfeef391 100644 --- a/versioned_docs/version-0.10/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md +++ b/versioned_docs/version-0.11/greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus.md @@ -1,3 +1,7 @@ +--- +description: Instructions for migrating from Prometheus to GreptimeCloud, including configuring remote write, querying with PromQL, and integrating with Grafana. +--- + import DocTemplate from '../../db-cloud-shared/migrate/_migrate-from-prometheus.md' # Migrate from Prometheus diff --git a/versioned_docs/version-0.10/greptimecloud/overview.md b/versioned_docs/version-0.11/greptimecloud/overview.md similarity index 61% rename from versioned_docs/version-0.10/greptimecloud/overview.md rename to versioned_docs/version-0.11/greptimecloud/overview.md index 7c5bec6db..81f5ec967 100644 --- a/versioned_docs/version-0.10/greptimecloud/overview.md +++ b/versioned_docs/version-0.11/greptimecloud/overview.md @@ -1,3 +1,7 @@ +--- +description: Provides an overview of GreptimeCloud, a fully-managed serverless GreptimeDB service for scalable and efficient time-series data management. +--- + import DocCardList from '@theme/DocCardList'; # Overview diff --git a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/go.md b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/go.md similarity index 82% rename from versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/go.md rename to versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/go.md index 05a820811..8c3ac32c0 100644 --- a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/go.md +++ b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/go.md @@ -1,3 +1,7 @@ +--- +description: Guide on monitoring host metrics using Go, including creating a service, writing data, and visualizing data. +--- + # Go import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/influxdb.md b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/influxdb.md similarity index 81% rename from versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/influxdb.md rename to versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/influxdb.md index f74bcfe89..b155989a4 100644 --- a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/influxdb.md +++ b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/influxdb.md @@ -1,3 +1,7 @@ +--- +description: Guide on monitoring host metrics using InfluxDB Line Protocol, including creating a service, writing data, and visualizing data. +--- + # InfluxDB Line Protocol import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/java.md b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/java.md similarity index 82% rename from versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/java.md rename to versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/java.md index dbba20354..dd90a6624 100644 --- a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/java.md +++ b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/java.md @@ -1,3 +1,7 @@ +--- +description: Guide on monitoring host metrics using Java, including creating a service, writing data, and visualizing data. +--- + # Java import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/mysql.md b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/mysql.md similarity index 82% rename from versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/mysql.md rename to versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/mysql.md index 122d67548..7527810e8 100644 --- a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/mysql.md +++ b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/mysql.md @@ -1,3 +1,7 @@ +--- +description: Guide on monitoring host metrics using MySQL, including creating a service, writing data, and visualizing data. +--- + # MySQL import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/node-js.md b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/node-js.md similarity index 82% rename from versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/node-js.md rename to versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/node-js.md index 120191829..3514ee5ad 100644 --- a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/node-js.md +++ b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/node-js.md @@ -1,3 +1,7 @@ +--- +description: Guide on monitoring host metrics using Node.js, including creating a service, writing data, and visualizing data. +--- + # Node.js import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/prometheus.md b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/prometheus.md similarity index 82% rename from versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/prometheus.md rename to versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/prometheus.md index 41141c549..7029f14ba 100644 --- a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/prometheus.md +++ b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/prometheus.md @@ -1,3 +1,7 @@ +--- +description: Guide on monitoring host metrics using Prometheus, including creating a service, writing data, and visualizing data. +--- + # Prometheus import Includeoverview from '../../../db-cloud-shared/tutorials/monitor-host-metrics/overview.md' diff --git a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/python.md b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/python.md similarity index 100% rename from versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/python.md rename to versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/python.md diff --git a/versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md b/versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md similarity index 100% rename from versioned_docs/version-0.10/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md rename to versioned_docs/version-0.11/greptimecloud/tutorials/monitor-host-metrics/visualize-data.md diff --git a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/billing.md b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/billing.md similarity index 90% rename from versioned_docs/version-0.10/greptimecloud/usage-&-billing/billing.md rename to versioned_docs/version-0.11/greptimecloud/usage-&-billing/billing.md index 5bbaf3470..c0c0a4742 100644 --- a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/billing.md +++ b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/billing.md @@ -1,3 +1,7 @@ +--- +description: Explains the billing process, invoice generation, usage tracking, and cost calculation for different plans in GreptimeCloud. +--- + # Billing ## Invoice diff --git a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/dedicated.md b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/dedicated.md similarity index 89% rename from versioned_docs/version-0.10/greptimecloud/usage-&-billing/dedicated.md rename to versioned_docs/version-0.11/greptimecloud/usage-&-billing/dedicated.md index 90b666eb5..7e0a6a99b 100644 --- a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/dedicated.md +++ b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/dedicated.md @@ -1,3 +1,7 @@ +--- +description: Details the Dedicated Plan, including dedicated CPUs, storage, resource isolation, and cost calculation for GreptimeCloud. +--- + # Dedicated Plan The dedicated plan allows you to purchase dedicated CPUs and storage to host GreptimeDB. diff --git a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/hobby.md b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/hobby.md similarity index 87% rename from versioned_docs/version-0.10/greptimecloud/usage-&-billing/hobby.md rename to versioned_docs/version-0.11/greptimecloud/usage-&-billing/hobby.md index e9b92d7fd..368c44f1c 100644 --- a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/hobby.md +++ b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/hobby.md @@ -1,3 +1,7 @@ +--- +description: Describes the free tier Hobby Plan, its limitations, and the data retention policy for GreptimeCloud users. +--- + # Hobby Plan ## Introduction diff --git a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/overview.md b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/overview.md similarity index 58% rename from versioned_docs/version-0.10/greptimecloud/usage-&-billing/overview.md rename to versioned_docs/version-0.11/greptimecloud/usage-&-billing/overview.md index 1647814db..4cab359d3 100644 --- a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/overview.md +++ b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/overview.md @@ -1,3 +1,7 @@ +--- +description: Provides an overview of the usage and billing documents for Greptime Cloud, including links to detailed guides on various plans and capacity units. +--- + # Overview These documents will help you understand the usage and billing of Greptime Cloud. diff --git a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/request-capacity-unit.md b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/request-capacity-unit.md similarity index 97% rename from versioned_docs/version-0.10/greptimecloud/usage-&-billing/request-capacity-unit.md rename to versioned_docs/version-0.11/greptimecloud/usage-&-billing/request-capacity-unit.md index 8ed276921..a88656ec5 100644 --- a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/request-capacity-unit.md +++ b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/request-capacity-unit.md @@ -1,3 +1,7 @@ +--- +description: Introduces the calculation algorithms for request capacity units (WCU and RCU) and provides tips for optimizing CU usage. +--- + # Request Capacity Unit This document introduces the calculation algorithms for request capacity units. To monitor your service usage, you can visit the [GreptimeCloud Console](https://console.greptime.cloud/). diff --git a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/serverless.md b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/serverless.md similarity index 92% rename from versioned_docs/version-0.10/greptimecloud/usage-&-billing/serverless.md rename to versioned_docs/version-0.11/greptimecloud/usage-&-billing/serverless.md index a0dd643aa..2bdd1f046 100644 --- a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/serverless.md +++ b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/serverless.md @@ -1,3 +1,7 @@ +--- +description: Details the Serverless Plan, including request capacities, support, cost calculation, and billing information. +--- + # Serverless Plan The serverless plan allows you to purchase request capacities according to your needs diff --git a/versioned_docs/version-0.10/greptimecloud/usage-&-billing/shared-storage-capacity.md b/versioned_docs/version-0.11/greptimecloud/usage-&-billing/shared-storage-capacity.md similarity index 100% rename from versioned_docs/version-0.10/greptimecloud/usage-&-billing/shared-storage-capacity.md rename to versioned_docs/version-0.11/greptimecloud/usage-&-billing/shared-storage-capacity.md diff --git a/versioned_docs/version-0.11/index.md b/versioned_docs/version-0.11/index.md new file mode 100644 index 000000000..e156564eb --- /dev/null +++ b/versioned_docs/version-0.11/index.md @@ -0,0 +1,42 @@ +--- +description: Introduction to GreptimeDB, an open-source unified time-series database for metrics, logs, and events, with links to getting started, user guide, contributor guide, and more. +--- +# Introduction + +

+ GreptimeDB Logo +

+ +**GreptimeDB** is an open-source unified time-series database for **Metrics**, **Logs**, and **Events** (also **Traces** in plan). You can gain real-time insights from Edge to Cloud at any scale. + +GreptimeDB is also on cloud as [GreptimeCloud](https://greptime.com/product/cloud), +a fully-managed time-series database service that features serverless scalability, +seamless integration with ecoystem and improved Prometheus compatibility. + +Our core developers have been building time-series data platforms for years. Based on their best-practices, GreptimeDB is born to give you: + +- Unified all kinds of time series; GreptimeDB treats all time series as contextual events with timestamp, and thus unifies the processing of metrics, logs, and events. It supports analyzing metrics, logs, and events with SQL and PromQL, and doing streaming with continuous aggregation. +- Optimized columnar layout for handling time-series data; compacted, compressed, and stored on various storage backends, particularly cloud object storage with 50x cost efficiency. +- Fully open-source distributed cluster architecture that harnesses the power of cloud-native elastic computing resources. +- Seamless scalability from a standalone binary at edge to a robust, highly available distributed cluster in cloud, with a transparent experience for both developers and administrators. +- Flexible indexing capabilities and distributed, parallel-processing query engine, tackling high cardinality issues down. +- Widely adopted database protocols and APIs, including MySQL, PostgreSQL, and Prometheus Remote Storage, etc. +- Schemaless writing that automatically creates tables for data. + +Before getting started, please read the following documents that include instructions for setting up, fundamental concepts, architectural designs, and tutorials: + +- [Getting Started][1]: Provides an introduction to GreptimeDB for those who are new to it, including installation and database operations. +- [User Guide][2]: For application developers to use GreptimeDB or build custom integration. +- [GreptimeCloud][6]: For users of GreptimeCloud to get started. +- [Contributor Guide][3]: For contributor interested in learning more about the technical details and enhancing GreptimeDB as a contributor. +- [Roadmap][7]: The latest GreptimeDB roadmap. +- [Release Notes][4]: Presents all the historical version release notes. + [FAQ][5]: Presents the most frequently asked questions. + +[1]: ./getting-started/overview.md +[2]: ./user-guide/overview.md +[3]: ./contributor-guide/overview.md +[4]: /release-notes +[5]: ./faq-and-others/faq.md +[6]: ./greptimecloud/overview.md +[7]: https://www.greptime.com/blogs/2024-02-29-greptimedb-2024-roadmap diff --git a/versioned_docs/version-0.11/reference/about-greptimedb-version.md b/versioned_docs/version-0.11/reference/about-greptimedb-version.md new file mode 100644 index 000000000..4ce55f8d3 --- /dev/null +++ b/versioned_docs/version-0.11/reference/about-greptimedb-version.md @@ -0,0 +1,30 @@ +--- +description: Explanation of GreptimeDB's version numbering scheme, including the significance of major, minor, and revision numbers. +--- + +# About GreptimeDB Version Number + +GreptimeDB follows the [Semantic Versioning](https://semver.org/) scheme: + +1.2.3 where: +- 1 is the major release +- 2 is the minor release +- 3 is the revision number + +## Major release(1) +The major version indicates a significant milestone in the software’s lifecycle, often introducing extensive changes. +- Characteristics: Includes major architectural updates, substantial new features, or system overhauls. +- Impact: Typically not backward-compatible, requiring adjustments from users or developers. +- Examples: Major API redesigns, foundational architectural shifts, or the introduction of new core modules. + +## Minor release(2) +The minor version focuses on feature enhancements and minor improvements, aiming to refine the existing system. +- Characteristics: Adds new features, small updates, or interface improvements. +- Impact: While it strives for backward compatibility within the same major version, minor breaking changes might occasionally occur. +- Examples: Introducing optional functionality, updating user interfaces, or expanding configuration options with slight adjustments to existing behaviors. + +## Revision number(3) +The revision number is used for patches or minor refinements that address specific issues. +- Characteristics: Focuses on bug fixes, security updates, or performance optimizations. +- Impact: Does not introduce new features or change the overall behavior of the system. +- Examples: Fixing known bugs, addressing security vulnerabilities, or improving system stability. \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/command-lines.md b/versioned_docs/version-0.11/reference/command-lines.md new file mode 100644 index 000000000..f9f1ba173 --- /dev/null +++ b/versioned_docs/version-0.11/reference/command-lines.md @@ -0,0 +1,205 @@ +--- +description: Overview of the GreptimeDB command-line interface, including installation, available commands, options, and examples for starting services and upgrading versions. +--- + +# Greptime Command Line Interface + +The `greptime` command can start/stop GreptimeDB and pass configuration options. + +## Install the Greptime CLI + +The Greptime CLI comes bundled with the GreptimeDB binary. +After [installing GreptimeDB](/getting-started/installation/overview.md), +you can execute the `./greptime` command within the GreptimeDB directory. + +For convenience, if you wish to run commands using `greptime` instead of `./greptime`, +consider moving the CLI binary to your system's `bin` directory or appending the binary's path to your `PATH` environment variable. + +## CLI Options + +The `help` command lists all available commands and options of `greptime`. + +```sh +$ greptime help +Usage: greptime [OPTIONS] + +Commands: + datanode Start datanode service + frontend Start frontend service + metasrv Start metasrv service + standalone Run greptimedb as a standalone service + cli Execute the cli tools for greptimedb + help Print this message or the help of the given subcommand(s) + +Options: + --log-dir + --log-level + -h, --help Print help + -V, --version Print version +``` + +- `--log-dir=[dir]` specify logs directory, `/tmp/greptimedb/logs` by default. +- `--log-level=[info | debug | error | warn | trace]` specify the log level, `info` by default. + +### Global options + +- `-h`/`--help`: Print help information; +- `-V`/`--version`: Print version information; +- `--log-dir `: The logging directory; +- `--log-level `: The logging level; + +### Datanode subcommand options + +You can list all the options from the following command: + +``` +greptime datanode start --help +``` + +- `-c`/`--config-file`: The configuration file for datanode; +- `--data-home`: Database storage root directory; +- `--env-prefix `: The prefix of environment variables, default is `GREPTIMEDB_DATANODE`; +- `--http-addr `: HTTP server address; +- `--http-timeout `: HTTP request timeout in seconds. +- `--metasrv-addrs `: Metasrv address list; +- `--node-id `: The datanode ID; +- `--rpc-addr `: The datanode RPC addr; +- `--rpc-hostname `: The datanode hostname; +- `--wal-dir `: The directory of WAL; + +All the `addr` options are in the form of `ip:port`. + +### Metasrv subcommand options + +You can list all the options from the following command: + +``` +greptime metasrv start --help +``` + +- `-c`/`--config-file`: The configuration file for metasrv; +- `--enable-region-failover`: Whether to enable region failover, default is `false`. +- `--env-prefix `: The prefix of environment variables, default is `GREPTIMEDB_METASRV`; +- `--bind-addr `: The bind address of metasrv; +- `--http-addr `: HTTP server address; +- `--http-timeout `: HTTP request timeout in seconds. +- `--selector `: You can refer [selector-type](/contributor-guide/metasrv/selector.md#selector-type); +- `--server-addr `: The communication server address for frontend and datanode to connect to metasrv; +- `--store-addrs `: Comma or space separated key-value storage server (default is etcd) address, used for storing metadata; +- `--use-memory-store`: Use memory store instead of etcd, for test purpose only; + +### Frontend subcommand options + +You can list all the options from the following command: + +``` +greptime frontend start --help +``` + +- `-c`/`--config-file`: The configuration file for frontend; +- `--disable-dashboard`: Disable dashboard http service, default is `false`. +- `--env-prefix `: The prefix of environment variables, default is `GREPTIMEDB_FRONTEND`; +- `--rpc-addr `: GRPC server address; +- `--http-addr `: HTTP server address; +- `--http-timeout `: HTTP request timeout in seconds. +- `--influxdb-enable`: Whether to enable InfluxDB protocol in HTTP API; +- `--metasrv-addrs `: Metasrv address list; +- `--mysql-addr `: MySQL server address; +- `--postgres-addr `: Postgres server address; +- `--tls-cert-path `: The TLS public key file path; +- `--tls-key-path `: The TLS private key file path; +- `--tls-mode `: TLS Mode; +- `--user-provider `: You can refer [authentication](/user-guide/deployments/authentication/overview.md); + +### Flownode subcommand options + +You can list all the options from the following command: + +``` +greptime flownode start --help +``` + +- `--node-id `: Flownode's id +- `--rpc-addr `: Bind address for the gRPC server +- `--rpc-hostname `: Hostname for the gRPC server +- `--metasrv-addrs ...`: Metasrv address list +- `-c, --config-file `: The configuration file for the flownode +- `--env-prefix `: The prefix of environment variables, default is `GREPTIMEDB_FLOWNODE` + +### Standalone subcommand options + +You can list all the options from the following command: + + +``` +greptime standalone start --help +``` + +- `-c`/`--config-file`: The configuration file for frontend; +- `--env-prefix `: The prefix of environment variables, default is `GREPTIMEDB_STANDALONE`; +- `--http-addr `: HTTP server address; +- `--influxdb-enable`: Whether to enable InfluxDB protocol in HTTP API; +- `--mysql-addr `: MySQL server address; +- `--postgres-addr `: Postgres server address; +- `--rpc-addr `: gRPC server address; + +## Examples + +### Start service with configurations + +Starts GreptimeDB in standalone mode with customized configurations: + +```sh +greptime --log-dir=/tmp/greptimedb/logs --log-level=info standalone start -c config/standalone.example.toml +``` + +The `standalone.example.toml` configuration file comes from the `config` directory of the `[GreptimeDB](https://github.com/GreptimeTeam/greptimedb/)` repository. You can find more example configuration files there. The `-c` option specifies the configuration file, for more information check [Configuration](../user-guide/deployments/configuration.md). + +To start GreptimeDB in distributed mode, you need to start each component separately. The following commands show how to start each component with customized configurations or command line arguments. + +Starts a metasrv with customized configurations: + +```sh +greptime metasrv start -c config/metasrv.example.toml +``` + +Starts a datanode instance with customized configurations: + +```sh +greptime datanode start -c config/datanode.example.toml +``` + +Starts a datanode instance with command line arguments specifying the gRPC service address, the MySQL service address, the address of the metasrv, and the node id of the instance: + +```sh +greptime datanode start --rpc-addr=0.0.0.0:4001 --mysql-addr=0.0.0.0:4002 --metasrv-addrs=0.0.0.0:3002 --node-id=1 +``` + +Starts a frontend instance with customized configurations: + +```sh +greptime frontend start -c config/frontend.example.toml +``` + +Starts a frontend instance with command line arguments specifying the address of the metasrv: + +```sh +greptime frontend start --metasrv-addrs=0.0.0.0:3002 +``` + +Starts a flownode instance with customized configurations: + +```sh +greptime flownode start -c config/flownode.example.toml +``` + +Starts a flownode instance with command line arguments specifying the address of the metasrv: + +```sh +greptime flownode start --node-id=0 --rpc-addr=127.0.0.1:6800 --metasrv-addrs=127.0.0.1:3002; +``` + +### Upgrade GreptimeDB version + +Please refer to [the upgrade steps](/user-guide/administration/upgrade.md) + diff --git a/versioned_docs/version-0.11/reference/gtctl.md b/versioned_docs/version-0.11/reference/gtctl.md new file mode 100644 index 000000000..1ec8be178 --- /dev/null +++ b/versioned_docs/version-0.11/reference/gtctl.md @@ -0,0 +1,245 @@ +--- +description: Instructions for installing and using gtctl, a command-line tool for managing GreptimeDB clusters, including installation methods, autocompletion setup, and deployment modes. +--- + +# gtctl + +[gtctl][1], g-t-control, is a command-line tool for managing the GreptimeDB clusters. gtctl is the **All-in-One** binary that integrates with multiple operations of GreptimeDB clusters. + +## Installation + +### One-line Installation + +Download the binary using the following command: + +```bash +curl -fsSL https://raw.githubusercontent.com/greptimeteam/gtctl/develop/hack/install.sh | sh +``` + +After downloading, the gtctl will be in the current directory. + +You also can install gtctl from the AWS-CN S3 bucket: + +```bash +curl -fsSL https://downloads.greptime.cn/releases/scripts/gtctl/install.sh | sh -s -- -s aws +``` + +### Homebrew + +On macOS, gtctl is available via Homebrew: + +```bash +brew tap greptimeteam/greptime +brew install gtctl +``` + +### From Source + +If you already have the [Go][2] installed, you can run the `make` command under this project to build gtctl: + +```bash +make gtctl +``` + +After building, the gtctl will be generated in `./bin/`. If you want to install gtctl, you can run the `install` command: + +```bash +# The built gtctl will be installed in /usr/local/bin. +make install + +# The built gtctl will be installed in your customed path. +make install INSTALL_DIR= +``` + +## Enable gtctl Autocompletion (Optional) + +The gtctl supports autocompletion of several different shells. + +### Bash + +The gtctl completion script for Bash can be generated with the command `gtctl completion bash`. Sourcing the completion script in your shell enables gtctl autocompletion. + +```bash +echo 'source <(gtctl completion bash)' >> ~/.bashrc +``` + +### Zsh + +The gtctl completion script for Zsh can be generated with the command `gtctl completion zsh`. Sourcing the completion script in your shell enables gtctl autocompletion. + +```bash +mkdir -p $ZSH/completions && gtctl completion zsh > $ZSH/completions/_gtctl +``` + +### Fish + +The gtctl completion script for Fish can be generated with the command `gtctl completion fish`. Sourcing the completion script in your shell enables gtctl autocompletion. + +```bash +gtctl completion fish | source +``` + +## Quick Start + +The **fastest** way to experience the GreptimeDB cluster is to use the playground: + +```bash +gtctl playground +``` + +The `playground` will deploy the minimal GreptimeDB cluster on your environment in **bare-metal** mode. + +## Deployments + +The gtctl supports two deployment mode: Kubernetes and Bare-Metal. + +### Kubernetes + +#### Prerequisites + +* Kubernetes 1.18 or higher version is required. + + You can use the [kind][3] to create your own Kubernetes cluster: + + ```bash + kind create cluster + ``` + +#### Create + +Create your own GreptimeDB cluster and etcd cluster: + +```bash +gtctl cluster create mycluster -n default +``` + +If you want to use artifacts(charts and images) that are stored in the CN region, you can enable `--use-greptime-cn-artifacts`: + +```bash +gtctl cluster create mycluster -n default --use-greptime-cn-artifacts +``` + +After creating, the whole GreptimeDB cluster will start in the default namespace: + +```bash +# Get the cluster. +gtctl cluster get mycluster -n default + +# List all clusters. +gtctl cluster list +``` + +All the values used for cluster, etcd and operator which provided in [charts][4] are configurable, you can use `--set` to configure them. The gtctl also surface some commonly used configurations, you can use `gtctl cluster create --help` to browse them. + +```bash +# Configure cluster datanode replicas to 5 +gtctl cluster create mycluster --set cluster.datanode.replicas=5 + +# Two same ways to configure etcd storage size to 15Gi +gtctl cluster create mycluster --set etcd.storage.volumeSize=15Gi +gtctl cluster create mycluster --etcd-storage-size 15Gi +``` + +#### Dry Run + +gtctl provides `--dry-run` option in cluster creation. If a user executes the command with `--dry-run`, gtctl will output the manifests content without applying them: + +```bash +gtctl cluster create mycluster -n default --dry-run +``` + +#### Connect + +You can use the kubectl `port-forward` command to forward frontend requests: + +```bash +kubectl port-forward svc/mycluster-frontend 4002:4002 > connections.out & +``` + +Use gtctl `connect` command or your `mysql` client to connect to your cluster: + +```bash +gtctl cluster connect mycluster -p mysql + +mysql -h 127.0.0.1 -P 4002 +``` + +#### Scale (Experimental) + +You can use the following commands to scale (or down-scale) your cluster: + +```bash +# Scale datanode to 3 replicas. +gtctl cluster scale -n -c datanode --replicas 3 + +# Scale frontend to 5 replicas. +gtctl cluster scale -n -c frontend --replicas 5 +``` + +#### Delete + +If you want to delete the cluster, you can: + +```bash +# Delete the cluster. +gtctl cluster delete mycluster -n default + +# Delete the cluster, including etcd cluster. +gtctl cluster delete mycluster -n default --tear-down-etcd +``` + +### Bare-Metal + +#### Create + +You can deploy the GreptimeDB cluster on a bare-metal environment by the following simple command: + +```bash +gtctl cluster create mycluster --bare-metal +``` + +It will create all the necessary meta information on `${HOME}/.gtctl`. + +If you want to do more configurations, you can use the yaml format config file: + +```bash +gtctl cluster create mycluster --bare-metal --config +``` + +You can refer to the example config `cluster.yaml` and `cluster-with-local-artifacts.yaml` provided in [`examples/bare-metal`][5]. + +#### Delete + +Since the cluster in bare-metal mode runs in the foreground, any `SIGINT` and `SIGTERM` will delete the cluster. For example, the cluster will be deleted after pressing `Ctrl+C` on keyboard. + +The deletion will also delete the meta information of one cluster which located in `${HOME}/.gtctl`. The logs of cluster will remain if `--retain-logs` is enabled (enabled by default). + +## Development + +There are many useful tools provided through Makefile, you can simply run make help to get more information: + +* Compile the project + + ```bash + make + ``` + + Then the gtctl will be generated in `./bin/`. + +* Run the unit test + + ```bash + make test + ``` + +* Run the e2e test + + ```bash + make e2e + ``` + +[1]: +[2]: +[3]: +[4]: +[5]: diff --git a/versioned_docs/version-0.11/reference/http-endpoints.md b/versioned_docs/version-0.11/reference/http-endpoints.md new file mode 100644 index 000000000..e915633f3 --- /dev/null +++ b/versioned_docs/version-0.11/reference/http-endpoints.md @@ -0,0 +1,193 @@ +# HTTP API Endpoint List + +Here is the full list for the various HTTP paths and their usage in GreptimeDB: + +## Admin APIs + +Endpoints that is not versioned (under `/v1`). For admin usage like health check, status, metrics, etc. + +### Health Check + +- **Path**: `/health` +- **Methods**: `GET`, `POST` +- **Description**: Provides a health check endpoint to verify that the server is running. +- **Usage**: Access this endpoint to check the health status of the server. + +### Status + +- **Path**: `/status` +- **Methods**: `GET` +- **Description**: Retrieves the current status of the server. +- **Usage**: Use this endpoint to obtain server status information. + +### Metrics + +- **Path**: `/metrics` +- **Methods**: `GET` +- **Description**: Exposes Prometheus metrics for monitoring purposes. +- **Usage**: Prometheus can scrape this endpoint to collect metrics data. + +### Configuration + +- **Path**: `/config` +- **Methods**: `GET` +- **Description**: Retrieves the server's configuration options. +- **Usage**: Access this endpoint to get configuration details. + +### Dashboard + +- **Paths**: `/dashboard` +- **Methods**: `GET`, `POST` +- **Description**: Provides access to the server's dashboard interface. +- **Usage**: Access these endpoints to interact with the web-based dashboard. + +This dashboard is packaged with the GreptimeDB server and provides a user-friendly interface for interacting with the server. It requires corresponding compile flags to be enabled when building GreptimeDB. The original source code for the dashboard can be found at https://github.com/GreptimeTeam/dashboard + +### Log Level + +- **Path**: `/debug/log_level` +- **Methods**: `POST` +- **Description**: Adjusts the server's log level dynamically. +- **Usage**: Send a log level change request to this endpoint. + +For more information, refer to the [how-to documentation](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-change-log-level-on-the-fly.md). + +### Profiling Tools + +- **Base Path**: `/debug/prof/` +- **Endpoints**: + - `cpu` + - `mem` +- **Methods**: `POST` for profiling the database node. +- **Description**: Runtime profiling for CPU or Memory usage. +- **Usage**: + - Refer to [Profiling CPU](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-profile-cpu.md) for detailed guide for CPU profiling. + - Refer to [Profiling Memory](https://github.com/GreptimeTeam/greptimedb/blob/main/docs/how-to/how-to-profile-memory.md) for detailed guide for Memory profiling. + +## Query Endpoints + +Various query APIs for sending query to GreptimeDB. + +### SQL API + +- **Path**: `/v1/sql` +- **Methods**: `GET`, `POST` +- **Description**: Executes SQL queries against the server. +- **Usage**: Send SQL queries in the request body. + +For more information on the SQL API, refer to the [HTTP API documentation](/user-guide/protocols/http.md#post-sql-statements) in the user guide. + +### PromQL API + +- **Path**: `/v1/promql` +- **Methods**: `GET`, `POST` +- **Description**: Executes PromQL queries for Prometheus-compatible metrics, and returns data in GreptimeDB's JSON format. +- **Usage**: Send PromQL queries in the request body. + +For more information on the PromQL API, refer to the [PromQL documentation](/user-guide/query-data/promql.md). + +## Protocol Endpoints + +Endpoints for various protocols that are compatible with GreptimeDB. Like InfluxDB, Prometheus, OpenTelemetry, etc. + +### InfluxDB Compatibility + +- **Paths**: + - `/v1/influxdb/write` + - `/v1/influxdb/api/v2/write` + - `/v1/influxdb/ping` + - `/v1/influxdb/health` +- **Methods**: + - `POST` for write endpoints. + - `GET` for ping and health endpoints. +- **Description**: Provides endpoints compatible with InfluxDB for data ingestion and health checks. +- **Usage**: + - Ingest data using InfluxDB line protocol. + - Use ping and health endpoints to check server status. + +The detailed documentation for InfluxDB protocol can be found at [here](/user-guide/protocols/influxdb-line-protocol.md). + +### Prometheus Remote Write/Read + +- **Paths**: + - `/v1/prometheus/write` + - `/v1/prometheus/read` +- **Methods**: `POST` +- **Description**: Supports Prometheus remote write and read APIs. +- **Usage**: + - Send metric data using Prometheus remote write protocol. + - Read metric data using Prometheus remote read protocol. + +### Prometheus HTTP API + +- **Base Path**: `/v1/prometheus/api/v1` +- **Endpoints**: + - `/format_query` + - `/status/buildinfo` + - `/query` + - `/query_range` + - `/labels` + - `/series` + - `/parse_query` + - `/label/{label_name}/values` +- **Methods**: `GET`, `POST` +- **Description**: Provides Prometheus HTTP API endpoints for querying and retrieving metric data. +- **Usage**: Use these endpoints to interact with metrics using standard Prometheus HTTP API. + +Refer to the original Prometheus documentation for more information on the [Prometheus HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/). + +### OpenTelemetry Protocol (OTLP) + +- **Paths**: + - `/v1/otlp/v1/metrics` + - `/v1/otlp/v1/traces` + - `/v1/otlp/v1/logs` +- **Methods**: `POST` +- **Description**: Supports OpenTelemetry protocol for ingesting metrics, traces, and logs. +- **Usage**: Send OpenTelemetry formatted data to these endpoints. + +### Loki Compatibility + +- **Path**: `/v1/loki/api/v1/push` +- **Methods**: `POST` +- **Description**: Compatible with Loki's API for log ingestion. +- **Usage**: Send log data in Loki's format to this endpoint. + +### OpenTSDB Protocol + +- **Path**: `/v1/opentsdb/api/put` +- **Methods**: `POST` +- **Description**: Supports data ingestion using the OpenTSDB protocol. +- **Usage**: Ingest time series data using OpenTSDB's JSON format. + +## Log Ingestion Endpoints + +- **Paths**: + - `/v1/events/logs` + - `/v1/events/pipelines/{pipeline_name}` + - `/v1/events/pipelines/dryrun` +- **Methods**: + - `POST` for ingesting logs and adding pipelines. + - `DELETE` for deleting pipelines. +- **Description**: Provides endpoints for log ingestion and pipeline management. +- **Usage**: + - Ingest logs via the `/logs` endpoint. + - Manage log pipelines using the `/pipelines` endpoints. + +For more information on log ingestion and pipeline management, refer to the [log overview](/user-guide/logs/overview.md). + +## Script Endpoints + +### Script Management + +- **Path**: `/v1/scripts` +- **Methods**: `POST` +- **Description**: Manages scripts on the server. +- **Usage**: Submit scripts for execution or management. + +### Run Script + +- **Path**: `/v1/run-script` +- **Methods**: `POST` +- **Description**: Executes a script on the server. +- **Usage**: Send the script content to be executed. diff --git a/versioned_docs/version-0.11/reference/sql-tools.md b/versioned_docs/version-0.11/reference/sql-tools.md new file mode 100644 index 000000000..634d11196 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql-tools.md @@ -0,0 +1,289 @@ +--- +description: Guide on using SQL tools with GreptimeDB, including recommended libraries, installation, connection setup, and usage examples for Java and Go. +--- + +# SQL Tools + +GreptimeDB uses SQL as its main query language and supports many popular SQL tools. +This document guides you on how to use SQL tools with GreptimeDB. + +## Language drivers + +It is recommended to use mature SQL drivers to query data. + +### Recommended libraries + + + + Java Database Connectivity (JDBC) is the JavaSoft specification of a standard application programming interface (API) that allows Java programs to access database management systems. + + Many databases, such as MySQL or PostgreSQL, have implemented their own drivers based on the JDBC API. + Since GreptimeDB supports [multiple protocols](/user-guide/protocols/overview.md), we use MySQL as an example to demonstrate how to use JDBC. + If you want to use other protocols, just replace the MySQL driver with the corresponding driver. + + + It is recommended to use the [GORM](https://gorm.io/) library, which is popular and developer-friendly. + + + +### Installation + + + + If you are using [Maven](https://maven.apache.org/), add the following to your `pom.xml` dependencies list: + + ```xml + + mysql + mysql-connector-java + 8.0.33 + + ``` + + + + Use the following command to install the GORM library: + + ```shell + go get -u gorm.io/gorm + ``` + + Then install the MySQL driver: + + ```shell + go get -u gorm.io/driver/mysql + ``` + + Import the libraries in your code: + + ```go + import ( + "gorm.io/gorm" + "gorm.io/driver/mysql" + ) + ``` + + + +### Connect to database + +The following use MySQL as an example to demonstrate how to connect to GreptimeDB. + + + + ```java + public static Connection getConnection() throws IOException, ClassNotFoundException, SQLException { + Properties prop = new Properties(); + prop.load(QueryJDBC.class.getResourceAsStream("/db-connection.properties")); + + String dbName = (String) prop.get("db.database-driver"); + String dbConnUrl = (String) prop.get("db.url"); + String dbUserName = (String) prop.get("db.username"); + String dbPassword = (String) prop.get("db.password"); + + Class.forName(dbName); + Connection dbConn = DriverManager.getConnection(dbConnUrl, dbUserName, dbPassword); + + return Objects.requireNonNull(dbConn, "Failed to make connection!"); + } + ``` + + You need a properties file to store the DB connection information. Place it in the resources directory and name it `db-connection.properties`. The file content is as follows: + + ```txt + # DataSource + db.database-driver=com.mysql.cj.jdbc.Driver + db.url=jdbc:mysql://localhost:4002/public + db.username= + db.password= + ``` + + Or you can get the file from [here](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/ingester-example/src/main/resources/db-connection.properties). + + + ```go + type Mysql struct { + Host string + Port string + User string + Password string + Database string + + DB *gorm.DB + } + + m := &Mysql{ + Host: "127.0.0.1", + Port: "4002", // default port for MySQL + User: "username", + Password: "password", + Database: "public", + } + + dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local", + m.Host, m.Port, m.Database) + dsn = fmt.Sprintf("%s:%s@%s", m.User, m.Password, dsn) + db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{}) + if err != nil { + // error handling + } + m.DB = db + ``` + + + +#### Time zone + + + + Set the JDBC time zone by setting URL parameters: + + ```txt + jdbc:mysql://127.0.0.1:4002?connectionTimeZone=Asia/Shanghai&forceConnectionTimeZoneToSession=true + ``` + + * `connectionTimeZone={LOCAL|SERVER|user-defined-time-zone}` specifies the connection time zone. + * `forceConnectionTimeZoneToSession=true` sets the session `time_zone` variable to the value specified in `connectionTimeZone`. + + + Set the time zone in the DSN. For example, set the time zone to `Asia/Shanghai`: + + ```go + dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local&time_zone=%27Asia%2FShanghai%27", + m.Host, m.Port, m.Database) + ``` + + For more information, see the [MySQL Driver Documentation](https://github.com/go-sql-driver/mysql?tab=readme-ov-file#system-variables). + + + +### Raw SQL + +It is recommended to use raw SQL to experience the full features of GreptimeDB. +The following example shows how to use raw SQL to query data. + + + + ```java + try (Connection conn = getConnection()) { + Statement statement = conn.createStatement(); + + // DESC table; + ResultSet rs = statement.executeQuery("DESC cpu_metric"); + LOG.info("Column | Type | Key | Null | Default | Semantic Type "); + while (rs.next()) { + LOG.info("{} | {} | {} | {} | {} | {}", + rs.getString(1), + rs.getString(2), + rs.getString(3), + rs.getString(4), + rs.getString(5), + rs.getString(6)); + } + + // SELECT COUNT(*) FROM cpu_metric; + rs = statement.executeQuery("SELECT COUNT(*) FROM cpu_metric"); + while (rs.next()) { + LOG.info("Count: {}", rs.getInt(1)); + } + + // SELECT * FROM cpu_metric ORDER BY ts DESC LIMIT 5; + rs = statement.executeQuery("SELECT * FROM cpu_metric ORDER BY ts DESC LIMIT 5"); + LOG.info("host | ts | cpu_user | cpu_sys"); + while (rs.next()) { + LOG.info("{} | {} | {} | {}", + rs.getString("host"), + rs.getTimestamp("ts"), + rs.getDouble("cpu_user"), + rs.getDouble("cpu_sys")); + } + } + ``` + + For the complete code of the demo, please refer to [here](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/ingester-example/src/main/java/io/greptime/QueryJDBC.java). + + + The following code declares a GORM object model: + + ```go + type CpuMetric struct { + Host string `gorm:"column:host;primaryKey"` + Ts time.Time `gorm:"column:ts;primaryKey"` + CpuUser float64 `gorm:"column:cpu_user"` + CpuSys float64 `gorm:"column:cpu_sys"` + } + ``` + + If you are using the [High-level API](/user-guide/ingest-data/for-iot/grpc-sdks/go.md#high-level-api) to insert data, you can declare the model with both GORM and GreptimeDB tags. + + ```go + type CpuMetric struct { + Host string `gorm:"column:host;primaryKey" greptime:"tag;column:host;type:string"` + Ts time.Time `gorm:"column:ts;primaryKey" greptime:"timestamp;column:ts;type:timestamp;precision:millisecond"` + CpuUser float64 `gorm:"column:cpu_user" greptime:"field;column:cpu_user;type:float64"` + CpuSys float64 `gorm:"column:cpu_sys" greptime:"field;column:cpu_sys;type:float64"` + } + ``` + + Declare the table name as follows: + + ```go + func (CpuMetric) TableName() string { + return "cpu_metric" + } + ``` + + Use raw SQL to query data: + + ```go + var cpuMetric CpuMetric + db.Raw("SELECT * FROM cpu_metric LIMIT 10").Scan(&result) + ``` + + + +### Query library reference + +For more information about how to use the query library, please see the documentation of the corresponding library: + + + + - [JDBC Online Tutorials](https://docs.oracle.com/javase/tutorial/jdbc/basics/index.html) + + + - [GORM](https://gorm.io/docs/index.html) + + + +## Command line tools + +### MySQL + +You can use the `mysql` command line tool to connect to the GreptimeDB. +Please refer to the [MySQL protocol](/user-guide/protocols/mysql.md) document for connection information. + +After you connect to the server, you can use all [GreptimeDB SQL commands](/reference/sql/overview.md) to interact with the database. + +### PostgreSQL + +You can use the `psql` command line tool to connect to the GreptimeDB. +Please refer to the [PostgreSQL protocol](/user-guide/protocols/postgresql.md) document for connection information. + +After you connect to the server, you can use all [GreptimeDB SQL commands](/reference/sql/overview.md) to interact with the database. + +## GreptimeDB Dashboard + +You can run SQL and visualize data in the [GreptimeDB Dashboard](/getting-started/installation/greptimedb-dashboard.md). + +## GUI tools + +### DBeaver + +Please refer to the [DBeaver Integration Guide](/user-guide/integrations/dbeaver.md). + + + +## HTTP API + +You can POST SQL queries to the GreptimeDB HTTP API to query data. +Please refer to the [HTTP API](/user-guide/protocols/http.md) document for more information. diff --git a/versioned_docs/version-0.11/reference/sql/admin.md b/versioned_docs/version-0.11/reference/sql/admin.md new file mode 100644 index 000000000..345babc4d --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/admin.md @@ -0,0 +1,33 @@ +--- +description: Describes the `ADMIN` statement used to run administration functions, including examples for flushing tables, scheduling compactions, migrating regions, and querying procedure states. +--- + +# ADMIN + +`ADMIN` is used to run administration functions. + +```sql +ADMIN function(arg1, arg2, ...) +``` + + +## Admin Functions + +GreptimeDB provides some administration functions to manage the database and data: + +* `flush_table(table_name)` to flush a table's memtables into SST file by table name. +* `flush_region(region_id)` to flush a region's memtables into SST file by region id. Find the region id through [PARTITIONS](./information-schema/partitions.md) table. +* `compact_table(table_name, [type], [options])` to schedule a compaction task for a table by table name, read [compaction](/user-guide/administration/manage-data/compaction.md#strict-window-compaction-strategy-swcs-and-manual-compaction) for more details. +* `compact_region(region_id)` to schedule a compaction task for a region by region id. +* `migrate_region(region_id, from_peer, to_peer, [timeout])` to migrate regions between datanodes, please read the [Region Migration](/user-guide/administration/manage-data/region-migration.md). +* `procedure_state(procedure_id)` to query a procedure state by its id. +* `flush_flow(flow_name)` to flush a flow's output into the sink table. + +For example: +```sql +-- Flush the table test -- +admin flush_table("test"); + +-- Schedule a compaction for table test -- +admin compact_table("test"); +``` diff --git a/versioned_docs/version-0.11/reference/sql/alter.md b/versioned_docs/version-0.11/reference/sql/alter.md new file mode 100644 index 000000000..81802c647 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/alter.md @@ -0,0 +1,180 @@ +--- +description: Describes the `ALTER` statement used to modify database options, table options, or metadata, including syntax and examples for altering databases and tables. +--- + +# ALTER + +`ALTER` can be used to modify any database options, table options or metadata of the table, including: + +* Modify database options +* Add/Drop/Modify a column +* Rename a table +* Modify table options + +## ALTER DATABASE + +`ALTER DATABASE` statements can be used to modify the options of databases. + +### Syntax + +```sql +ALTER DATABASE db + [SET = [, ...] + | UNSET [, ...] + ] +``` + +Currently following options are supported: +- `ttl`: the default retention time of data in database. + +### Examples + +#### Modify default retention time of data in database + +Change the default retention time of data in the database to 1 day: + +```sql +ALTER DATABASE db SET 'ttl'='1d'; +``` + +Remove the default retention time of data in the database: + +```sql +ALTER DATABASE db UNSET 'ttl'; +``` + +## ALTER TABLE + +### Syntax + +```sql +ALTER TABLE [db.]table + [ADD COLUMN name type [options] + | DROP COLUMN name + | MODIFY COLUMN name type + | MODIFY COLUMN name SET FULLTEXT [WITH ] + | MODIFY COLUMN name UNSET FULLTEXT + | RENAME name + | SET = [, ...] + | UNSET [, ...] + ] +``` + +### Examples + +#### Add column + +Adds a new column to the table: + +```sql +ALTER TABLE monitor ADD COLUMN load_15 double; +``` + +Definition of column is the same as in [CREATE](./create.md). + +We can set the new column's location. In first position for example: + +```sql +ALTER TABLE monitor ADD COLUMN load_15 double FIRST; +``` + +After an existing column: + +```sql +ALTER TABLE monitor ADD COLUMN load_15 double AFTER memory; +``` + +Adds a new column as a tag(primary key) with a default value: +```sql +ALTER TABLE monitor ADD COLUMN app STRING DEFAULT 'shop' PRIMARY KEY; +``` + +#### Remove column + +Removes a column from the table: + +```sql +ALTER TABLE monitor DROP COLUMN load_15; +``` + +The removed column can't be retrieved immediately by all subsequent queries. + +#### Modify column type + +Modify the date type of a column + +```sql +ALTER TABLE monitor MODIFY COLUMN load_15 STRING; +``` + +The modified column cannot be a tag (primary key) or time index, and it must be nullable to ensure that the data can be safely converted (returns `NULL` on cast failures). + +#### Alter table options + +`ALTER TABLE` statements can also be used to change the options of tables. + +Currently following options are supported: +- `ttl`: the retention time of data in table. +- `compaction.twcs.time_window`: the time window parameter of TWCS compaction strategy. +- `compaction.twcs.max_output_file_size`: the maximum allowed output file size of TWCS compaction strategy. +- `compaction.twcs.max_active_window_runs`: the maximum allowed sorted runs in the active window of TWCS compaction strategy. +- `compaction.twcs.max_inactive_window_runs`: the maximum allowed sorted runs in the inactive windows of TWCS compaction strategy. +- `compaction.twcs.max_active_window_files`: the maximum allowed number of files in the active window of TWCS compaction strategy. +- `compaction.twcs.max_inactive_window_files`: the maximum allowed number of files in the inactive windows of TWCS compaction strategy. + +```sql +ALTER TABLE monitor SET 'ttl'='1d'; + +ALTER TABLE monitor SET 'compaction.twcs.time_window'='2h'; + +ALTER TABLE monitor SET 'compaction.twcs.max_output_file_size'='500MB'; + +ALTER TABLE monitor SET 'compaction.twcs.max_inactive_window_files'='2'; + +ALTER TABLE monitor SET 'compaction.twcs.max_active_window_files'='2'; + +ALTER TABLE monitor SET 'compaction.twcs.max_active_window_runs'='6'; + +ALTER TABLE monitor SET 'compaction.twcs.max_inactive_window_runs'='6'; +``` + +#### Unset options: + +```sql +ALTER TABLE monitor UNSET 'ttl'; +``` + +#### Modify column fulltext index options + +Enable fulltext index on a column: + +```sql +ALTER TABLE monitor MODIFY COLUMN load_15 SET FULLTEXT WITH (analyzer = 'Chinese', case_sensitive = 'false'); +``` + +You can specify the following options using `FULLTEXT WITH` when enabling fulltext options: + +- `analyzer`: Sets the language analyzer for the full-text index. Supported values are `English` and `Chinese`. Default is `English`. +- `case_sensitive`: Determines whether the full-text index is case-sensitive. Supported values are `true` and `false`. Default is `false`. + +If `WITH ` is not specified, `FULLTEXT` will use the default values. + +#### Disable fulltext index on a column + +```sql +ALTER TABLE monitor MODIFY COLUMN load_15 UNSET FULLTEXT; +``` + +The column must be a string type to alter the fulltext index. + +If the fulltext index has never been enabled, you can enable it and specify the `analyzer` and `case_sensitive` options. When the fulltext index is already enabled on a column, you can disable it but **cannot modify the options**. + +#### Rename table + +Renames the table: + +```sql +ALTER TABLE monitor RENAME monitor_new; +``` + +This command only renames the table; it doesn't modify the data within the table. diff --git a/versioned_docs/version-0.11/reference/sql/case.md b/versioned_docs/version-0.11/reference/sql/case.md new file mode 100644 index 000000000..0e8411a81 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/case.md @@ -0,0 +1,95 @@ +--- +description: Describes the `CASE` statement used for conditional logic within queries, including syntax and examples for usage in `SELECT`, `WHERE`, `GROUP BY`, and `ORDER BY` clauses. +--- + +# CASE + +The `CASE` statement allows you to perform conditional logic within your queries, +similar to an IF-THEN-ELSE structure in programming languages. +It enables you to return specific values based on evaluated conditions, +making data retrieval and manipulation more dynamic. + +## Syntax + +```sql +CASE + WHEN condition1 THEN result1 + WHEN condition2 THEN result2 + ... + ELSE result +END +``` + +- `condition1`, `condition2`, ...: The conditions to evaluate against the expression. +- `result1`, `result2`, ...: The values to return when the corresponding condition is met. +- `result`: The value to return when none of the conditions are met (optional). + + +## Examples + +The `CASE` statement can be used in various clauses, such as `SELECT`, `WHERE`, `ORDER BY` and `GROUP BY`. + +### Use `CASE` in `SELECT` + +In the `SELECT` clause, you can use the `CASE` statement to create new columns based on conditions. +please see [the example](/user-guide/query-data/sql.md#case) in the query data guide. + +You can also use `CASE` with functions like `SUM` to conditionally aggregate data. +for example, you can calculate the total number of logs with status 200 and 404: + +```sql +SELECT + SUM(CASE WHEN status_code = '200' THEN 1 ELSE 0 END) AS status_200_count, + SUM(CASE WHEN status_code = '404' THEN 1 ELSE 0 END) AS status_404_count +FROM nginx_logs; +``` + +### Use `CASE` in `WHERE` + +In the `WHERE` clause, you can filter rows based on conditions. +For example, the following query retrieves data from the `monitor` table based on the `ts` condition: + +```sql +SELECT * +FROM monitor +WHERE host = CASE + WHEN ts > '2023-12-13 02:05:46' THEN '127.0.0.1' + ELSE '127.0.0.2' + END; +``` + +### Use `CASE` in `GROUP BY` + +The `CASE` statement can be utilized in the `GROUP BY` clause to categorize data based on specific conditions. For instance, the following query groups data by the `host` column and classifies the `cpu` column into three categories: 'high', 'medium', and 'low': + +```sql +SELECT + host, + COUNT(*) AS count, + CASE + WHEN cpu > 0.5 THEN 'high' + WHEN cpu > 0.3 THEN 'medium' + ELSE 'low' + END AS cpu_status +FROM monitor +GROUP BY + host, cpu_status; +``` + +### Use `CASE` in `ORDER BY` + +According to GreptimeDB's [data model](/user-guide/concepts/data-model.md), +the `Tag` columns are indexed and can be used in the `ORDER BY` clause to enhance query performance. +For instance, if the `status_code` and `http_method` columns in the `nginx_logs` table are `Tag` columns storing string values, +you can utilize the `CASE` statement to sort the data based on these columns as follows: + +```sql +SELECT * +FROM nginx_logs +ORDER BY + CASE + WHEN status_code IS NOT NULL THEN status_code + ELSE http_method + END; +``` + diff --git a/versioned_docs/version-0.11/reference/sql/cast.md b/versioned_docs/version-0.11/reference/sql/cast.md new file mode 100644 index 000000000..0e44aace0 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/cast.md @@ -0,0 +1,34 @@ +--- +description: Describes the `CAST` function used to convert an expression of one data type to another, including syntax and examples. +--- + +# CAST + +`CAST` is used to convert an expression of one data type to another. + +## Syntax + +```sql +CAST (expression AS data_type) +``` + +## Parameters + +- expression: the expression to be converted. +- data_type: the data type to convert the expression to. + +# Examples + + Convert a string to an integer: + +```sql + SELECT CAST('123' AS INT) ; +``` + +```sql ++-------------+ +| Utf8("123") | ++-------------+ +| 123 | ++-------------+ +``` diff --git a/versioned_docs/version-0.11/reference/sql/compatibility.md b/versioned_docs/version-0.11/reference/sql/compatibility.md new file mode 100644 index 000000000..2ec389892 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/compatibility.md @@ -0,0 +1,24 @@ +--- +description: Describes the subset of ANSI SQL supported by GreptimeDB and its unique extensions, including major incompatibilities and extensions for table creation, data insertion, updates, queries, and deletions. +--- + +# ANSI Compatibility + +GreptimeDB supports a subset of ANSI SQL and has some unique extensions. Some major incompatibilities and extensions are described below: + +1. Create a table: + * Supports the unique `TIME INDEX` constraint. Please refer to the [Data Model](/user-guide/concepts/data-model.md) and the [CREATE](./create.md) table creation syntax for details. + * Currently only supports `PRIMARY KEY` constraints and does not support other types of constraints or foreign keys. + * GreptimeDB is a native distributed database, so the table creation syntax for distributed tables supports partitioning rules. Please also refer to the [CREATE](./create.md). +2. Insert data: Consistent with ANSI SQL syntax, but requires the `TIME INDEX` column value (or default value) to be provided. +3. Update data: Does not support `UPDATE` syntax, but if the primary key and `TIME INDEX` corresponding column values are the same during `INSERT`, subsequent inserted rows will overwrite previously written rows, effectively achieving an update. + * Since 0.8, GreptimeDB supports [append mode](/reference/sql/create.md#create-an-append-only-table) that creates an append-only table with `append_mode="true"` option which keeps duplicate rows. + * GreptimeDB supports [merge mode](/reference/sql/create.md#create-an-append-only-table) that creates a table with `merge_mode="last_non_null"` option which allow updating a field partially. +4. Query data: Query syntax is compatible with ANSI SQL, with some functional differences and omissions. + * Since v0.9.0, begins to support [VIEW](/user-guide/query-data/view.md). + * TQL syntax extension: Supports executing PromQL in SQL via TQL subcommands. Please refer to the [TQL](./tql.md) section for details. + * [Range Query](/reference/sql/range.md#range-query) to query and aggregate data within a range of time. +5. Delete data: Deletion syntax is basically consistent with ANSI SQL. +6. Others: + * Identifiers such as table names and column names have constraints similar to ANSI SQL, are case sensitive, and require double quotes when encountering special characters or uppercase letters. + * GreptimeDB has optimized identifier rules for different dialects. For example, when you connect with a MySQL or PostgreSQL client, you can use identifier rules specific to that SQL dialect, such as using backticks `` ` `` for MySQL and standard double quotes `"` for PostgreSQL. diff --git a/versioned_docs/version-0.11/reference/sql/copy.md b/versioned_docs/version-0.11/reference/sql/copy.md new file mode 100644 index 000000000..f36aac363 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/copy.md @@ -0,0 +1,182 @@ +--- +description: Describes the `COPY` statement used to export and import table or database data to and from files, including options for file format, time range, and cloud storage connections. +--- + +# COPY + +## COPY TABLE +### COPY TO + +`COPY TO` is used to export the contents of a table to a file. + +The syntax for using `COPY TO` is as follows: + +```sql +COPY tbl TO '/xxx/xxx/output.parquet' WITH (FORMAT = 'parquet'); +``` + +The command starts with the keyword `COPY`, followed by the name of the table you want to export data from (`tbl` in this case). + +`TO` specifies the file path and name to save the exported +data (`/xxx/xxx/output.parquet` in this case). + +#### `WITH` Option + +`WITH` adds options such as the file `FORMAT` which specifies the format of the exported file. In this example, the format is Parquet; it is a columnar storage format used for big data processing. Parquet efficiently compresses and encodes columnar data for big data analytics. + +| Option | Description | Required | +|---|---|---| +| `FORMAT` | Target file(s) format, e.g., JSON, CSV, Parquet | **Required** | +| `START_TIME`/`END_TIME`| The time range within which data should be exported. `START_TIME` is inclusive and `END_TIME` is exclusive. | Optional | + +#### `CONNECTION` Option + +`COPY TO` supports exporting data to cloud storage services like S3. See [connect-to-s3](#connect-to-s3) for more detail. + +### COPY FROM + +`COPY FROM` is used to import data from a file into a table. + +The syntax for using `COPY FROM` is as follows: + +```sql +COPY [.] +FROM { '/[]' } +[ [ WITH ] + ( + [ FORMAT = { 'CSV' | 'JSON' | 'PARQUET' | 'ORC' } ] + [ PATTERN = '' ] + ) +] +[LIMIT NUM] +``` + +The command starts with the keyword `COPY`, followed by the name of the table you want to import data into. + +#### `WITH` Option + +`FORMAT` specifies the file format of the imported file. In this example, the format is Parquet. + +The option `PATTERN` allows the usage of wildcard characters like * to specify multiple input files that +match a certain pattern. For example, you can use the following syntax to import all files in the +directory(which must be an absolute path) "/path/to/folder" with the filename that contains `parquet`: + +```sql +COPY tbl FROM '/path/to/folder/' WITH (FORMAT = 'parquet', PATTERN = '.*parquet.*'); +``` + +Specifically, if you only have one file to import, you can use the following syntax: + +```sql +COPY tbl FROM '/path/to/folder/xxx.parquet' WITH (FORMAT = 'parquet'); +``` + +| Option | Description | Required | +|---|---|---| +| `FORMAT` | Target file(s) format, e.g., JSON, CSV, Parquet, ORC | **Required** | +| `PATTERN` | Use regex to match files. e.g., `*_today.parquet` | Optional | + +#### `CONNECTION` Option + +`COPY FROM` also supports importing data from cloud storage services like S3. See [connect-to-s3](#connect-to-s3) for more detail. + +### Connect to S3 + +You can copy data from/to S3 + +```sql +-- COPY FROM +COPY tbl FROM '' WITH (FORMAT = 'parquet') CONNECTION(REGION = 'us-west-2'); + +-- COPY TO +COPY tbl TO '' WITH (FORMAT = 'parquet') CONNECTION(REGION = 'us-west-2'); +``` + +#### URL + +Notes: You should specify a file using `S3://bucket/key-name`. The following example shows the correct format. + +``` +s3://my-bucket/data.parquet +``` + +Another way is using Virtual-hosted–style(`ENABLE_VIRTUAL_HOST_STYLE` must be set to `true` to enable this). The following example shows the correct format. + +``` +s3://bucket-name.s3.region-code.amazonaws.com/key-name +``` + +:::tip NOTE +You can use `Copy S3 URI` or `COPY URL` on S3 console to get S3 URI/HTTP URL prefix or full path. +::: + +#### Options + +You can set the following **CONNECTION** options: + +| Option | Description | Required | +|---|---|---| +| `REGION` | AWS region name. e.g., `us-west-2` | **Required** | +| `ENDPOINT` | The bucket endpoint. e.g., `s3.us-west-2.amazonaws.com` | Optional | +| `ACCESS_KEY_ID` | ACCESS_KEY_ID Your access key ID for connecting the AWS S3 compatible object storage. | Optional | +| `SECRET_ACCESS_KEY` | Your secret access key for connecting the AWS S3 compatible object storage. | Optional | +| `ENABLE_VIRTUAL_HOST_STYLE` | If you use virtual hosting to address the bucket, set it to "true".| Optional | +| `SESSION_TOKEN` | Your temporary credential for connecting the AWS S3 service. | Optional | + +#### LIMIT + +You can use `LIMIT` to restrict maximum number of rows inserted at once. + +## COPY DATABASE + +Beside copying specific table to/from some path, `COPY` statement can also be used to copy whole database to/from some path. The syntax for copying databases is: + +```sql +COPY DATABASE + [TO | FROM] '' + WITH ( + FORMAT = { 'CSV' | 'JSON' | 'PARQUET' }, + START_TIME = "", + END_TIME = "" + ) + [CONNECTION( + REGION = "", + ENDPOINT = "", + ACCESS_KEY_ID = "", + SECRET_ACCESS_KEY = "", + ENABLE_VIRTUAL_HOST_STYLE = "[true | false]", + )] +``` + +| Option | Description | Required | +|---|---|---| +| `FORMAT` | Export file format, available options: JSON, CSV, Parquet | **Required** | +| `START_TIME`/`END_TIME`| The time range within which data should be exported. `START_TIME` is inclusive and `END_TIME` is exclusive. | Optional | + +> - When copying databases, `` must end with `/`. +> - `CONNECTION` parameters can also be used to copying databases to/from object storage services like AWS S3. + +### Examples + +```sql +-- Export all tables' data to /tmp/export/ +COPY DATABASE public TO '/tmp/export/' WITH (FORMAT='parquet'); + +-- Export all tables' data within time range 2022-04-11 08:00:00~2022-04-11 09:00:00 to /tmp/export/ +COPY DATABASE public TO '/tmp/export/' WITH (FORMAT='parquet', START_TIME='2022-04-11 08:00:00', END_TIME='2022-04-11 09:00:00'); + +-- Import files under /tmp/export/ directory to database named public. +COPY DATABASE public FROM '/tmp/export/' WITH (FORMAT='parquet'); +``` + +## Special reminder for Windows platforms + +Please notice that when executing `COPY`/`COPY DATABASE` statements on Windows platforms, backslashes (`\`) in paths should be replaced with `/` for compatibility. + +```sql +-- Won't work +COPY tbl TO 'C:\xxx\xxx\output.parquet' WITH (FORMAT = 'parquet'); + +-- Correct path: +COPY tbl TO 'C:/xxx/xxx/output.parquet' WITH (FORMAT = 'parquet'); +``` diff --git a/versioned_docs/version-0.11/reference/sql/create.md b/versioned_docs/version-0.11/reference/sql/create.md new file mode 100644 index 000000000..ac08bcabd --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/create.md @@ -0,0 +1,432 @@ +--- +description: Explains the SQL CREATE statement for creating databases, tables, external tables, flows, and views in GreptimeDB, including syntax, table constraints, options, and examples. +--- + +# CREATE + +`CREATE` is used to create new databases or tables. + +## CREATE DATABASE + +### Syntax + +Creates a new database: + +```sql +CREATE DATABASE [IF NOT EXISTS] db_name [WITH ] +``` + +If the `db_name` database already exists, then GreptimeDB has the following behaviors: + +- Doesn't create a new database. +- Doesn't return an error when the clause `IF NOT EXISTS` is presented. +- Otherwise, returns an error. + +The database can also carry options similar to the `CREATE TABLE` statement by using the `WITH` keyword. All options available in [Table Options](#table-options) can be utilized here as well (one exception is that database's TTL can't be `instant`). When creating a table, if the corresponding table options are not provided, the options configured at the database level will be applied. + +### Examples + +Creates a `test` database: + +```sql +CREATE DATABASE test; +``` + +```sql +Query OK, 1 row affected (0.05 sec) +``` + +Creates it again with `IF NOT EXISTS`: + +```sql +CREATE DATABASE IF NOT EXISTS test; +``` + +Create a database with a `TTL` (Time-To-Live) of seven days, which means all the tables in this database will inherit this option if they don't have their own `TTL` setting: + +```sql +CREATE DATABASE test with(ttl='7d'); +``` + +## CREATE TABLE + +### Syntax + +Creates a new table in the `db` database or the current database in use: + +```sql +CREATE TABLE [IF NOT EXISTS] [db.]table_name +( + column1 type1 [NULL | NOT NULL] [DEFAULT expr1] [TIME INDEX] [PRIMARY KEY] [FULLTEXT | FULLTEXT WITH options] [COMMENT comment1], + column2 type2 [NULL | NOT NULL] [DEFAULT expr2] [TIME INDEX] [PRIMARY KEY] [FULLTEXT | FULLTEXT WITH options] [COMMENT comment2], + ... + [TIME INDEX (column)], + [PRIMARY KEY(column1, column2, ...)], + [INVERTED INDEX(column1, column2, ...)] +) ENGINE = engine WITH([TTL | storage | ...] = expr, ...) +[ + PARTITION ON COLUMNS(column1, column2, ...) ( + , + ... + ) +] +``` + +The table schema is specified by the brackets before the `ENGINE`. The table schema is a list of column definitions and table constraints. +A column definition includes the column `column_name`, `type`, and options such as nullable or default values, etc. Please see below. + +### Table constraints + +The table constraints contain the following: + +- `TIME INDEX` specifies the time index column, which always has one and only one column. It indicates the `Timestamp` type in the [data model](/user-guide/concepts/data-model.md) of GreptimeDB. +- `PRIMARY KEY` specifies the table's primary key column, which indicates the `Tag` type in the [data model](/user-guide/concepts/data-model.md) of GreptimeDB. It cannot include the time index column, but it always implicitly adds the time index column to the end of keys. +- The Other columns are `Field` columns in the [data model](/user-guide/concepts/data-model.md) of GreptimeDB. + +:::tip NOTE +The `PRIMARY KEY` specified in the `CREATE` statement is **not** the primary key in traditional relational databases. +Actually, The `PRIMARY KEY` in traditional relational databases is equivalent to the combination of `PRIMARY KEY` and `TIME INDEX` in GreptimeDB. In other words, the `PRIMARY KEY` and `TIME INDEX` together constitute the unique identifier of a row in GreptimeDB. +::: + +The statement won't do anything if the table already exists and `IF NOT EXISTS` is presented; otherwise returns an error. + +#### Inverted Index + +`INVERTED INDEX` specifies the table's [Inverted Index](/contributor-guide/datanode/data-persistence-indexing#inverted-index) column. The inverted index column can be any column. For each specified column, GreptimeDB creates an inverted index to accelerate queries. + +- If `INVERTED INDEX` is not specified, inverted indexes will be created for the columns in the `PRIMARY KEY`. +- If `INVERTED INDEX` is specified, inverted indexes will only be created for the columns listed in the `INVERTED INDEX`. Specifically, when `INVERTED INDEX()` is specified, it means that no inverted index will be created for any column. + +### Table options + +Users can add table options by using `WITH`. The valid options contain the following: + +| Option | Description | Value | +| ------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ttl` | The storage time of the table data | A time duration string such as `'60m'`, `'1h'` for one hour, `'14d'` for 14 days etc. Supported time units are: `s` / `m` / `h` / `d`. | +| `storage` | The name of the table storage engine provider | String value, such as `S3`, `Gcs`, etc. It must be configured in `[[storage.providers]]`, see [configuration](/user-guide/deployments/configuration.md#storage-engine-provider). | +| `compaction.type` | Compaction strategy of the table | String value. Only `twcs` is allowed. | +| `compaction.twcs.max_active_window_files` | Max num of files that can be kept in active writing time window | String value, such as '8'. Only available when `compaction.type` is `twcs`. You can refer to this [document](https://cassandra.apache.org/doc/latest/cassandra/managing/operating/compaction/twcs.html) to learn more about the `twcs` compaction strategy. | +| `compaction.twcs.max_inactive_window_files` | Max num of files that can be kept in inactive time window. | String value, such as '1'. Only available when `compaction.type` is `twcs`. | +| `compaction.twcs.time_window` | Compaction time window | String value, such as '1d' for 1 day. The table usually partitions rows into different time windows by their timestamps. Only available when `compaction.type` is `twcs`. | +| `memtable.type` | Type of the memtable. | String value, supports `time_series`, `partition_tree`. | +| `append_mode` | Whether the table is append-only | String value. Default is 'false', which removes duplicate rows by primary keys and timestamps according to the `merge_mode`. Setting it to 'true' to enable append mode and create an append-only table which keeps duplicate rows. | +| `merge_mode` | The strategy to merge duplicate rows | String value. Only available when `append_mode` is 'false'. Default is `last_row`, which keeps the last row for the same primary key and timestamp. Setting it to `last_non_null` to keep the last non-null field for the same primary key and timestamp. | +| `comment` | Table level comment | String value. | + +#### Create a table with TTL +For example, to create a table with the storage data TTL(Time-To-Live) is seven days: + +```sql +CREATE TABLE IF NOT EXISTS temperatures( + ts TIMESTAMP TIME INDEX, + temperature DOUBLE DEFAULT 10, +) with(ttl='7d'); +``` + +The `ttl` value can be one of the following: + +- A duration like `1hour 12min 5s`, The duration object is a concatenation of time spans. Where each time span is an integer number and a suffix. Supported suffixes: + - `nsec`, `ns` – nanoseconds + - `usec`, `us` – microseconds + - `msec`, `ms` – milliseconds + - `seconds`, `second`, `sec`, `s` + - `minutes`, `minute`, `min`, `m` + - `hours`, `hour`, `hr`, `h` + - `days`, `day`, `d` + - `weeks`, `week`, `w` + - `months`, `month`, `M` – defined as 30.44 days + - `years`, `year`, `y` – defined as 365.25 days +- `forever`, `NULL`, an empty string `''` and `0s` (or any zero length duration, like `0d`), means the data will never be deleted. +- `instant`, note that database's TTL can't be set to `instant`. `instant` means the data will be deleted instantly when inserted, useful if you want to send input to a flow task without saving it, see more details in [flow management documents](/user-guide/continuous-aggregation/manage-flow.md#manage-flows). +- Unset, `ttl` can be unset by using `ALTER TABLE UNSET 'ttl'`, which means the table will inherit the database's ttl policy (if any). + +If a table has its own TTL policy, it will take precedence over the database TTL policy. +Otherwise, the database TTL policy will be applied to the table. + +So if table's TTL is set to `forever`, no matter what the database's TTL is, the data will never be deleted. But if you unset table TTL using: +```sql +ALTER TABLE UNSET 'ttl'; +``` +Then the database's TTL will be applied to the table. + +Note that the default TTL setting for table and database is unset, which also means the data will never be deleted. + +#### Create a table with custom storage +Create a table that stores the data in Google Cloud Storage: + +```sql +CREATE TABLE IF NOT EXISTS temperatures( + ts TIMESTAMP TIME INDEX, + temperature DOUBLE DEFAULT 10, +) with(ttl='7d', storage="Gcs"); +``` + +#### Create a table with custom compaction options +Create a table with custom compaction options. The table will attempt to partition data into 1-day time window based on the timestamps of the data. +- It merges files within the latest time window if they exceed 8 files +- It merges files within inactive windows into a single file + +```sql +CREATE TABLE IF NOT EXISTS temperatures( + ts TIMESTAMP TIME INDEX, + temperature DOUBLE DEFAULT 10, +) +with( + 'compaction.type'='twcs', + 'compaction.twcs.time_window'='1d', + 'compaction.twcs.max_active_window_files'='8', + 'compaction.twcs.max_inactive_window_files'='1', +); +``` + +#### Create an append-only table +Create an append-only table which disables deduplication. +```sql +CREATE TABLE IF NOT EXISTS temperatures( + ts TIMESTAMP TIME INDEX, + temperature DOUBLE DEFAULT 10, +) with('append_mode'='true'); +``` + +#### Create a table with merge mode +Create a table with `last_row` merge mode, which is the default merge mode. +```sql +create table if not exists metrics( + host string, + ts timestamp, + cpu double, + memory double, + TIME INDEX (ts), + PRIMARY KEY(host) +) +with('merge_mode'='last_row'); +``` + +Under `last_row` mode, the table merges rows with the same primary key and timestamp by only keeping the latest row. +```sql +INSERT INTO metrics VALUES ('host1', 0, 0, NULL), ('host2', 1, NULL, 1); +INSERT INTO metrics VALUES ('host1', 0, NULL, 10), ('host2', 1, 11, NULL); + +SELECT * from metrics ORDER BY host, ts; + ++-------+-------------------------+------+--------+ +| host | ts | cpu | memory | ++-------+-------------------------+------+--------+ +| host1 | 1970-01-01T00:00:00 | | 10.0 | +| host2 | 1970-01-01T00:00:00.001 | 11.0 | | ++-------+-------------------------+------+--------+ +``` + + +Create a table with `last_non_null` merge mode. +```sql +create table if not exists metrics( + host string, + ts timestamp, + cpu double, + memory double, + TIME INDEX (ts), + PRIMARY KEY(host) +) +with('merge_mode'='last_non_null'); +``` + +Under `last_non_null` mode, the table merges rows with the same primary key and timestamp by keeping the latest value of each field. +```sql +INSERT INTO metrics VALUES ('host1', 0, 0, NULL), ('host2', 1, NULL, 1); +INSERT INTO metrics VALUES ('host1', 0, NULL, 10), ('host2', 1, 11, NULL); + +SELECT * from metrics ORDER BY host, ts; + ++-------+-------------------------+------+--------+ +| host | ts | cpu | memory | ++-------+-------------------------+------+--------+ +| host1 | 1970-01-01T00:00:00 | 0.0 | 10.0 | +| host2 | 1970-01-01T00:00:00.001 | 11.0 | 1.0 | ++-------+-------------------------+------+--------+ +``` + + +### Column options + +GreptimeDB supports the following column options: + +| Option | Description | +| ----------------- | ------------------------------------------------------------------------------------- | +| NULL | The column value can be `null`. | +| NOT NULL | The column value can't be `null`. | +| DEFAULT `expr` | The column's default value is `expr`, which its result type must be the column's type | +| COMMENT `comment` | The column comment. It must be a string value | +| FULLTEXT | Creates a full-text index to speed up full-text search operations. Applicable only to string-type columns. | + +The table constraints `TIME INDEX` and `PRIMARY KEY` can also be set by column option, but they can only be specified once in column definitions. So you can't specify `PRIMARY KEY` for more than one column except by the table constraint `PRIMARY KEY` : + +```sql +CREATE TABLE system_metrics ( + host STRING PRIMARY KEY, + idc STRING PRIMARY KEY, + cpu_util DOUBLE, + memory_util DOUBLE, + disk_util DOUBLE, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP(), + TIME INDEX(ts) +); +``` + +Goes wrong: + +```sql + Illegal primary keys definition: not allowed to inline multiple primary keys in columns options +``` + +```sql +CREATE TABLE system_metrics ( + host STRING, + idc STRING, + cpu_util DOUBLE, + memory_util DOUBLE, + disk_util DOUBLE, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + PRIMARY KEY(host, idc), +); +``` + +```sql +Query OK, 0 rows affected (0.01 sec) +``` + +#### `FULLTEXT` Column Option + +The `FULLTEXT` option is used to create a full-text index, accelerating full-text search operations. This option can only be applied to string-type columns. + +You can specify the following options using `FULLTEXT WITH`: + +- `analyzer`: Sets the language analyzer for the full-text index. Supported values are `English` and `Chinese`. +- `case_sensitive`: Determines whether the full-text index is case-sensitive. Supported values are `true` and `false`. + +If `WITH` is not specified, `FULLTEXT` will use the following default values: + +- `analyzer`: default is `English` +- `case_sensitive`: default is `false` + +For example, to create a table with a full-text index on the `log` column, configuring the analyzer to `Chinese` and setting `case_sensitive` to `false`: + +```sql +CREATE TABLE IF NOT EXISTS logs( + host STRING PRIMARY KEY, + log STRING FULLTEXT WITH(analyzer = 'Chinese', case_sensitive = 'false'), + ts TIMESTAMP TIME INDEX +); +``` + +For more information on using full-text indexing and search, refer to the [Log Query Documentation](/user-guide/logs/query-logs.md). + +### Region partition rules + +Please refer to [Partition](/contributor-guide/frontend/table-sharding.md#partition) for more details. + +## CREATE EXTERNAL TABLE + +### Syntax + +Creates a new file external table in the `db` database or the current database in use: + +```sql +CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name +[ + ( + column1 type1 [NULL | NOT NULL] [DEFAULT expr1] [TIME INDEX] [PRIMARY KEY] [COMMENT comment1], + column2 type2 [NULL | NOT NULL] [DEFAULT expr2] [TIME INDEX] [PRIMARY KEY] [COMMENT comment2], + ... + [TIME INDEX (column)], + [PRIMARY KEY(column1, column2, ...)] + ) +] WITH ( + LOCATION = url, + FORMAT = { 'CSV' | 'JSON' | 'PARQUET' | 'ORC' } + [,PATTERN = regex_pattern ] + [,REGION = region ] + [,ENDPOINT = uri ] + [,ACCESS_KEY_ID = key_id ] + [,SECRET_ACCESS_KEY = access_key ] + [,ENABLE_VIRTUAL_HOST_STYLE = { TRUE | FALSE }] + [,SESSION_TOKEN = token ] + ... +) +``` + +### Table options + +| Option | Description | Required | +| ---------- | ------------------------------------------------------------------------------- | ------------ | +| `LOCATION` | External files locations, e.g., `s3://[]`, `//[]` | **Required** | +| `FORMAT` | Target file(s) format, e.g., JSON, CSV, Parquet, ORC | **Required** | +| `PATTERN` | Use regex to match files. e.g., `*_today.parquet` | Optional | + +#### S3 + +| Option | Description | Required | +| --------------------------- | ------------------------------------------------------------------------------------- | ------------ | +| `REGION` | AWS region name. e.g., us-east-1. | **Required** | +| `ENDPOINT` | The bucket endpoint | Optional | +| `ACCESS_KEY_ID` | ACCESS_KEY_ID Your access key ID for connecting the AWS S3 compatible object storage. | Optional | +| `SECRET_ACCESS_KEY` | Your secret access key for connecting the AWS S3 compatible object storage. | Optional | +| `ENABLE_VIRTUAL_HOST_STYLE` | If you use virtual hosting to address the bucket, set it to "true". | Optional | +| `SESSION_TOKEN` | Your temporary credential for connecting the AWS S3 service. | Optional | + +### Time Index Column + +When creating an external table using the `CREATE EXTERNAL TABLE` statement, you are required to use the `TIME INDEX` constraint to specify a Time Index column. + +### Examples + +You can create an external table without columns definitions, the column definitions will be automatically inferred: + +```sql +CREATE EXTERNAL TABLE IF NOT EXISTS city WITH (location='/var/data/city.csv',format='csv'); +``` + +In this example, we did not explicitly define the columns of the table. To satisfy the requirement that the external table must specify a **Time Index** column, the `CREATE EXTERNAL TABLE` statement will infer the Time Index column according to the following rules: + +1. If the Time Index column can be inferred from the file metadata, then that column will be used as the Time Index column. +2. If there is a column named `greptime_timestamp` (the type of this column must be `TIMESTAMP`, otherwise, an error will be thrown), then this column will be used as the Time Index column. +3. Otherwise, a column named `greptime_timestamp` will be automatically created as the Time Index column, and a `DEFAULT '1970-01-01 00:00:00+0000'` constraint will be added. + +Or + +```sql +CREATE EXTERNAL TABLE city ( + host string, + ts timestamp, + cpu float64 default 0, + memory float64, + TIME INDEX (ts), + PRIMARY KEY(host) +) WITH (location='/var/data/city.csv', format='csv'); +``` + +In this example, we explicitly defined the `ts` column as the Time Index column. If there is no suitable Time Index column in the file, you can also create a placeholder column and add a `DEFAULT expr` constraint. + + +## CREATE FLOW + +```sql +CREATE [OR REPLACE] FLOW [ IF NOT EXISTS ] +SINK TO +[ EXPIRE AFTER ] +[ COMMENT '' ] +AS +; +``` + +For the statement to create or update a flow, please read the [flow management documents](/user-guide/continuous-aggregation/manage-flow.md#create-a-flow). + +## CREATE VIEW + +```sql +CREATE [OR REPLACE] VIEW [ IF NOT EXISTS ] +AS select_statement +``` + +For the statement to create or update a view, please read the [view user guide](/user-guide/query-data/view.md#view). diff --git a/versioned_docs/version-0.11/reference/sql/data-types.md b/versioned_docs/version-0.11/reference/sql/data-types.md new file mode 100644 index 000000000..86325d3aa --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/data-types.md @@ -0,0 +1,376 @@ +--- +description: Provides an overview of SQL data types supported by GreptimeDB, including string, binary, numeric, decimal, date and time, interval, JSON, and boolean types, with examples and compatibility with MySQL and PostgreSQL. +--- + +# Data Types + +SQL data types define the type of data that a column can store. When you run the `DESC TABLE` command, you can see the data type of each column. + +## String and Binary Data Types + +| Type Name | Description | Size | +|-----------|-------------|------| +| `String` | UTF-8 encoded strings. Holds up to 2,147,483,647 bytes of data | The length of the strings | +| `Binary` | Variable-length binary values. Holds up to 2,147,483,647 bytes of data | The length of the data + 2 bytes | + +The maximum capacities of `String` and `Binary` are determined by their encodings and how the storage engine handles them. For example, `String` values are encoded into UTF-8. If all characters are 3 bytes in length, this field can store up to 715,827,882 characters. As for `Binary` types, they can store a maximum of 2,147,483,647 bytes. + +## Numeric Data Types + +| Type Name | Description | Size | +|-----------|-------------|------| +| `Int8` | -128 ~ 127 | 1 Byte | +| `Int16` | -32768 ~ 32767 | 2 Bytes | +| `Int32` | -2147483648 ~ 2147483647 | 4 Bytes | +| `Int64` | -9223372036854775808 ~ 9223372036854775807 | 8 Bytes | +| `UInt8` | 0 ~ 255 | 1 Byte | +| `UInt16` | 0 ~ 65535 | 2 Bytes | +| `UInt32` | 0 ~ 4294967295 | 4 Bytes | +| `UInt64` | 0 ~ 18446744073709551615 | 8 Bytes | +| `Float32` | 32-bit IEEE754 floating point values | 4 Bytes | +| `Float64` | Double precision IEEE 754 floating point values | 8 Bytes | + +## Decimal Type + +GreptimeDB supports the `decimal` type, a fixed-point type represented as `decimal(precision, scale)`, where `precision` is the total number of digits, and `scale` is the number of digits in the fractional part. For example, `123.45` has a precision of 5 and a scale of 2. + +- `precision` can range from [1, 38]. +- `scale` can range from [0, precision]. + +The default decimal is `decimal(38, 10)` if the precision and scale are not specified. + +```sql +CREATE TABLE decimals( + d DECIMAL(3, 2), + ts TIMESTAMP TIME INDEX, +); + +INSERT INTO decimals VALUES ('0.1',1000), ('0.2',2000); + +SELECT * FROM decimals; +``` + +Output: +```sql ++------+---------------------+ +| d | ts | ++------+---------------------+ +| 0.10 | 1970-01-01T00:00:01 | +| 0.20 | 1970-01-01T00:00:02 | ++------+---------------------+ +``` + +## Date and Time Types + +| Type Name | Description | Size | +|-----------|-------------|------| +| `TimestampSecond` | 64-bit timestamp values with seconds precision, range: `[-262144-01-01 00:00:00, +262143-12-31 23:59:59]` | 8 Bytes | +| `TimestampMillisecond` | 64-bit timestamp values with milliseconds precision, range: `[-262144-01-01 00:00:00.000, +262143-12-31 23:59:59.999]` | 8 Bytes | +| `TimestampMicroSecond` | 64-bit timestamp values with microseconds precision, range: `[-262144-01-01 00:00:00.000000, +262143-12-31 23:59:59.999999]` | 8 Bytes | +| `TimestampNanosecond` | 64-bit timestamp values with nanoseconds precision, range: `[1677-09-21 00:12:43.145225, 2262-04-11 23:47:16.854775807]` | 8 Bytes | +| `Interval`| Time interval | 4 Bytes for `YearMonth`, 8 Bytes for `DayTime` and 16 Bytes for `MonthDayNano`| + +:::tip NOTE +When inserting Timestamp string literals to GreptimeDB using MySQL/PostgreSQL protocol, the value range is limited to '0001-01-01 00:00:00' to '9999-12-31 23:59:59'. +::: + +### Interval Type + +`Interval` type is used in scenarios where you need to track and manipulate time durations. It can be written using the following verbose syntax: + +``` +QUANTITY UNIT [QUANTITY UNIT...] +``` + +* `QUANTITY`: is a number (possibly signed), +* `UNIT`: is `microsecond`, `millisecond`, `second`, `minute`, `hour`, `day`, `week`, `month`, `year`, `decade`, `century`, or abbreviations or plurals of these units; + +The amounts of the different units are combined, with each unit's sign determining if it adds or subtracts from the total interval. For example, '1 year -2 months' results in a net interval of ten months. Unfortunately, GreptimeDB doesn't support writing the interval in the format of [ISO 8601 time intervals](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) such as `P3Y3M700DT133H17M36.789S` etc. But it's output supports it. + +Let's take some examples: + +```sql +SELECT '2 years 15 months 100 weeks 99 hours 123456789 milliseconds'::INTERVAL; +``` + +```sql ++---------------------------------------------------------------------+ +| Utf8("2 years 15 months 100 weeks 99 hours 123456789 milliseconds") | ++---------------------------------------------------------------------+ +| P3Y3M700DT133H17M36.789S | ++---------------------------------------------------------------------+ +``` + +55 minutes ago: + +```sql +SELECT '-1 hour 5 minute'::INTERVAL; +``` + +```sql ++--------------------------+ +| Utf8("-1 hour 5 minute") | ++--------------------------+ +| P0Y0M0DT0H-55M0S | ++--------------------------+ +``` + +1 hour and 5 minutes ago: + +```sql +SELECT '-1 hour -5 minute'::INTERVAL; +``` + +```sql ++---------------------------+ +| Utf8("-1 hour -5 minute") | ++---------------------------+ +| P0Y0M0DT-1H-5M0S | ++---------------------------+ +``` + +And of course, you can manipulate time with intervals by arithmetics. +Get the time of 5 minutes go: + +```sql +SELECT now() - INTERVAL '5 minute'; +``` + +```sql ++----------------------------------------------+ +| now() - IntervalMonthDayNano("300000000000") | ++----------------------------------------------+ +| 2024-06-24 21:24:05.012306 | ++----------------------------------------------+ +``` + +Note that you can also input the interval type using the `INTERVAL 'literal'` format. Using the syntax `'-1 hour -5 minute'::INTERVAL` explicitly casts the string to an interval type, which is how SQL handles type conversion. + +GreptimeDB also supports shorthand forms without spaces, such as `3y2mon4h`: + +```sql +SELECT INTERVAL '3y2mon4h'; +SELECT '3y2mon4h'::INTERVAL; +``` + +``` ++---------------------------------------------------------+ +| IntervalMonthDayNano("3010670175542044842954670112768") | ++---------------------------------------------------------+ +| P3Y2M0DT4H0M0S | ++---------------------------------------------------------+ ++---------------------------------------------------------+ +| IntervalMonthDayNano("3010670175542044842954670112768") | ++---------------------------------------------------------+ +| P3Y2M0DT4H0M0S | ++---------------------------------------------------------+ +``` + +It also supports signed numbers: + +```sql +SELECT INTERVAL '-1h5m'; +SELECT '-1h5m'::INTERVAL; +``` + +``` ++----------------------------------------------+ +| IntervalMonthDayNano("18446740773709551616") | ++----------------------------------------------+ +| P0Y0M0DT0H-55M0S | ++----------------------------------------------+ ++----------------------------------------------+ +| IntervalMonthDayNano("18446740773709551616") | ++----------------------------------------------+ +| P0Y0M0DT0H-55M0S | ++----------------------------------------------+ +``` + +Supported abbreviations include: + +| Abbreviation | Full name | +|-------|---------------| +| y | years | +| mon | months | +| w | weeks | +| d | days | +| h | hours | +| m | minutes | +| s | seconds | +| millis| milliseconds | +| ms | milliseconds | +| us | microseconds | +| ns | nanoseconds | + +## JSON Type +GreptimeDB supports the JSON type, allowing users to store and query JSON-formatted data. The JSON type is highly flexible and can store various forms of structured or unstructured data, making it suitable for use cases such as logging, analytics, and semi-structured data storage. + +```sql +CREATE TABLE json_data( + my_json JSON, + ts TIMESTAMP TIME INDEX +); + +INSERT INTO json_data VALUES ('{"key1": "value1", "key2": 10}', 1000), + ('{"name": "GreptimeDB", "open_source": true}', 2000); + +SELECT * FROM json_data; +``` + +Output: + +``` ++------------------------------------------+---------------------+ +| my_json | ts | ++------------------------------------------+---------------------+ +| {"key1":"value1","key2":10} | 1970-01-01 00:00:01 | +| {"name":"GreptimeDB","open_source":true} | 1970-01-01 00:00:02 | ++------------------------------------------+---------------------+ +``` + +### Query JSON data + +You can query the JSON data directly or extract specific fields using [JSON functions](./functions/overview.md#json-functions) provided by GreptimeDB. Here's an example: + +```sql +SELECT json_get_string(my_json, '$.name') as name FROM json_data; +``` + +Output: + +``` ++---------------------------------------------------+ +| name | ++---------------------------------------------------+ +| NULL | +| GreptimeDB | ++---------------------------------------------------+ +``` + + +## Boolean Type + +| Type Name | Description | Size | +|-----------|-------------|------| +| `Boolean` | Bool values | 1 Byte | + +Use `TRUE` or `FALSE` to represent boolean values in SQL statements. For example: + +```sql +CREATE TABLE bools( + b BOOLEAN, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, +); +``` + +```sql +INSERT INTO bools(b) VALUES (TRUE), (FALSE); +``` + +## Data types compatible with MySQL and PostgreSQL + +### Type aliases + +For users migrating from MySQL or PostgreSQL to GreptimeDB, GreptimeDB supports the following alias types. + +| Data Type | Alias Types | +| ---------------------- | --------------------------------------------------------------- | +| `String` | `Text`, `TinyText`, `MediumText`, `LongText`, `Varchar`, `Char` | +| `Binary` | `Varbinary` | +| `Int8` | `TinyInt` | +| `Int16` | `SmallInt` | +| `Int32` | `Int` | +| `Int64` | `BigInt` | +| `UInt8` | `UnsignedInt` | +| `UInt16` | `UnsignedTinyInt` | +| `UInt32` | `UnsignedSmallInt` | +| `UInt64` | `UnsignedBigInt` | +| `Float32` | `Float` | +| `Float64` | `Double` | +| `TimestampSecond` | `Timestamp_s`, `Timestamp_sec`, `Timestamp(0)` | +| `TimestampMillisecond` | `Timestamp`, `Timestamp_ms`, `Timestamp(3)` | +| `TimestampMicroSecond` | `Timestamp_us`, `Timestamp(6)` | +| `TimestampNanosecond` | `Timestamp_ns`, `Timestamp(9)` | + +You can use these alias types when creating tables. +For example, use `Varchar` instead of `String`, `Double` instead of `Float64`, and `Timestamp(0)` instead of `TimestampSecond`. + +```sql +CREATE TABLE alias_types ( + s TEXT, + i DOUBLE, + ts0 TIMESTAMP(0) DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + PRIMARY KEY(s) +); +``` + +### Date and time types + +In addition to the `Timestamp` types used as the default time type in GreptimeDB, GreptimeDB also supports `Date` and `DateTime` types for compatibility with MySQL and PostgreSQL. + +| Type name | Description | Size | +|-----------|-------------|------| +|`Date` |32-bit date values represent the days since UNIX Epoch | 4 Bytes | +|`DateTime` |64-bit datetime values represent the milliseconds since UNIX Epoch| 8 Bytes | + +## Examples + +### Create Table + +```sql +CREATE TABLE data_types ( + s STRING, + vbi BINARY, + b BOOLEAN, + tint INT8, + sint INT16, + i INT32, + bint INT64, + utint UINT8, + usint UINT16, + ui UINT32, + ubint UINT64, + f FLOAT32, + d FLOAT64, + dm DECIMAL(3, 2), + dt DATE, + dtt DATETIME, + ts0 TIMESTAMPSECOND, + ts3 TIMESTAMPMILLISECOND, + ts6 TIMESTAMPMICROSECOND, + ts9 TIMESTAMPNANOSECOND DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + PRIMARY KEY(s)); +``` + +### Describe Table + +```sql +DESC TABLE data_types; +``` + +```sql ++--------+----------------------+------+------+---------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------+----------------------+------+------+---------------------+---------------+ +| s | String | PRI | YES | | TAG | +| vbi | Binary | | YES | | FIELD | +| b | Boolean | | YES | | FIELD | +| tint | Int8 | | YES | | FIELD | +| sint | Int16 | | YES | | FIELD | +| i | Int32 | | YES | | FIELD | +| bint | Int64 | | YES | | FIELD | +| utint | UInt8 | | YES | | FIELD | +| usint | UInt16 | | YES | | FIELD | +| ui | UInt32 | | YES | | FIELD | +| ubint | UInt64 | | YES | | FIELD | +| f | Float32 | | YES | | FIELD | +| d | Float64 | | YES | | FIELD | +| dm | Decimal(3, 2) | | YES | | FIELD | +| dt | Date | | YES | | FIELD | +| dtt | DateTime | | YES | | FIELD | +| ts0 | TimestampSecond | | YES | | FIELD | +| ts3 | TimestampMillisecond | | YES | | FIELD | +| ts6 | TimestampMicrosecond | | YES | | FIELD | +| ts9 | TimestampNanosecond | PRI | NO | current_timestamp() | TIMESTAMP | ++--------+----------------------+------+------+---------------------+---------------+ +``` diff --git a/versioned_docs/version-0.11/reference/sql/delete.md b/versioned_docs/version-0.11/reference/sql/delete.md new file mode 100644 index 000000000..9b4386c1d --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/delete.md @@ -0,0 +1,29 @@ +--- +description: Details the SQL DELETE statement for removing rows from a table based on a specified condition, including syntax and examples. +--- + +# DELETE + +`DELETE` is used to remove rows from a table. + +## Syntax + +```sql +DELETE FROM [db.]table WHERE expr +``` + +It removes rows from the table `[db.]table` that satisfies the expression `expr` after `WHERE`. The removed rows are marked immediately and can't be retrieved by all subsequent queries. + +## Example + +For example, there is a table with the primary key `host`: + +```sql +CREATE TABLE monitor ( host STRING, ts TIMESTAMP, cpu DOUBLE DEFAULT 0, memory DOUBLE, TIME INDEX (ts), PRIMARY KEY(host)) ; +``` + +To delete a row from it by primary key `host` and timestamp index `ts`: + +```sql +DELETE FROM monitor WHERE host = 'host1' and ts = 1655276557000; +``` diff --git a/versioned_docs/version-0.11/reference/sql/describe_table.md b/versioned_docs/version-0.11/reference/sql/describe_table.md new file mode 100644 index 000000000..193ec2bc4 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/describe_table.md @@ -0,0 +1,44 @@ +--- +description: Describes the SQL DESCRIBE TABLE statement to display the structure of a table, including column names, data types, keys, nullability, default values, and semantic types, with examples. +--- + +# DESCRIBE TABLE + +`DESCRIBE [TABLE] [db.]table` describes the table structure in the `db` or the current database in-use. + +## Examples + +Describes the table `monitor`: + +```sql +DESCRIBE TABLE monitor; +``` + +or + +```sql +DESCRIBE monitor; +``` + +Output: + +```sql ++--------+----------------------+------+------+---------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------+----------------------+------+------+---------------------+---------------+ +| host | String | PRI | YES | | TAG | +| ts | TimestampMillisecond | PRI | NO | current_timestamp() | TIMESTAMP | +| cpu | Float64 | | YES | 0 | FIELD | +| memory | Float64 | | YES | | FIELD | ++--------+----------------------+------+------+---------------------+---------------+ +4 rows in set (0.00 sec) +``` + +It produces the table structure: + +* `Column`: the column names +* `Type`: the column data types +* `Key`: `PRI` means the column is in the primary key constraint. +* `Null`: `YES` means nullable, otherwise `NO` +* `Default`: default value or expression of the column +* `Semantic Type`: This column represents the semantic type, corresponding to `TAG`, `FIELD` or `TIMESTAMP` in the data model. diff --git a/versioned_docs/version-0.11/reference/sql/distinct.md b/versioned_docs/version-0.11/reference/sql/distinct.md new file mode 100644 index 000000000..8a6f81570 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/distinct.md @@ -0,0 +1,25 @@ +--- +description: Explains the SQL SELECT DISTINCT statement used to retrieve unique values from a dataset, with examples of using DISTINCT with and without filters. +--- + +# DISTINCT + +`SELECT DISTINCT` is used to select unique values from a set of data. This keyword returns distinct values +from the output of the query. + +The basic syntax for a `SELECT DISTINCT` statement is as followings: + +```sql +SELECT DISTINCT idc +FROM system_metrics; +``` + +`SELECT DISTINCT` can be used in conjunction with filters. + +```sql +SELECT DISTINCT idc, host +FROM system_metrics +WHERE host != 'host2'; +``` + +`SELECT DISTINCT` is a simple but powerful command of GreptimeDB SQL that allows users to easily condense the data into a summary of unique values. It can be used on one column or multiple columns, making it very versatile for data analysis and reporting. Using "SELECT DISTINCT" is a great way to get an overview of the types of data stored in the tables. diff --git a/versioned_docs/version-0.11/reference/sql/drop.md b/versioned_docs/version-0.11/reference/sql/drop.md new file mode 100644 index 000000000..99c3b1264 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/drop.md @@ -0,0 +1,96 @@ +--- +description: Covers the SQL DROP statement for removing databases, tables, flows, and views in GreptimeDB, including syntax, examples. +--- + +# DROP + +## DROP DATABASE + +`DROP DATABASE` drops a database. It removes the catalog entries for the database and deletes the directory containing the data. + +:::danger Danger + +`DROP DATABASE` cannot be undone. Use it with care! + +::: + +### Syntax + +```sql +DROP DATABASE [ IF EXISTS ] db_name +``` + +- `IF EXISTS`: Do not throw an error if the database does not exist. +- `db_name`: The name of the database to remove. + +### Examples + +To drop a database named `test`: + +```sql +DROP DATABASE test; +``` + + +## DROP TABLE + +`DROP TABLE` removes tables from the database. It will remove the table definition and all table data, indexes, rules, and constraints for that table. + +:::danger Danger + +`DROP TABLE` cannot be undone. Use it with care! + +::: + +### Syntax + +```sql +DROP TABLE [ IF EXISTS ] table_name +``` + +- `IF EXISTS`: Do not throw an error if the table does not exist. +- `table_name`: The name of the table to remove. + + +### Examples + +Drop the table `monitor` in the current database: + +```sql +DROP TABLE monitor; +``` + + +## DROP FLOW + +```sql +DROP FLOW [ IF EXISTS ] flow_name; +``` + +- `IF EXISTS`: Do not throw an error if the flow does not exist. +- `flow_name`: The name of the flow to destroy. + +```sql +DROP FLOW IF EXISTS test_flow; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +## DROP VIEW + +```sql +DROP VIEW [ IF EXISTS ] view_name; +``` + +- `IF EXISTS`: Do not throw an error if the view does not exist. +- `view_name`: The name of the view to remove. + +```sql +DROP VIEW IF EXISTS test_view; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` diff --git a/versioned_docs/version-0.11/reference/sql/explain.md b/versioned_docs/version-0.11/reference/sql/explain.md new file mode 100644 index 000000000..3b8418639 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/explain.md @@ -0,0 +1,59 @@ +--- +description: Provides information on the SQL EXPLAIN statement to obtain the execution plan of a query, including the optional ANALYZE clause to measure execution time and output rows, with examples. +--- + +# EXPLAIN + +`EXPLAIN` is used to provide the execution plan of a statement. + +## Syntax + +```sql +EXPLAIN [ANALYZE] SELECT ... +``` + +The `ANALYZE` clause will execute the statement and measure time spent at each plan node and the total rows of the output etc. + +## Examples + +Explains the following query: + +```sql +EXPLAIN SELECT * FROM monitor where host='host1'; +``` + +```sql +| plan_type | plan +| logical_plan | Projection: monitor.host, monitor.ts, monitor.cpu, monitor.memory + Filter: monitor.host = Utf8("host1") + TableScan: monitor projection=[host, ts, cpu, memory], partial_filters=[monitor.host = Utf8("host1")] | +| physical_plan | ProjectionExec: expr=[host@0 as host, ts@1 as ts, cpu@2 as cpu, memory@3 as memory] + CoalesceBatchesExec: target_batch_size=4096 + FilterExec: host@0 = host1 + RepartitionExec: partitioning=RoundRobinBatch(10) + ExecutionPlan(PlaceHolder) +``` + +The column `plan_type` indicates whether it's a`logical_plan` or `physical_plan`. And the column `plan` explains the plan in detail. + +Explains the execution of the plan by `ANALYZE`: + +```sql +EXPLAIN ANALYZE SELECT * FROM monitor where host='host1'; +``` + +```sql +| plan_type | plan +| Plan with Metrics | CoalescePartitionsExec, metrics=[output_rows=1, elapsed_compute=79.167µs, spill_count=0, spilled_bytes=0, mem_used=0] + ProjectionExec: expr=[host@0 as host, ts@1 as ts, cpu@2 as cpu, memory@3 as memory], metrics=[output_rows=1, elapsed_compute=17.176µs, spill_count=0, spilled_bytes=0, mem_used=0] + CoalesceBatchesExec: target_batch_size=4096, metrics=[output_rows=1, elapsed_compute=14.248µs, spill_count=0, spilled_bytes=0, mem_used=0] + CoalesceBatchesExec: target_batch_size=4096, metrics=[output_rows=1, elapsed_compute=17.21µs, spill_count=0, spilled_bytes=0, mem_used=0] + FilterExec: host@0 = host1, metrics=[output_rows=1, elapsed_compute=541.801µs, spill_count=0, spilled_bytes=0, mem_used=0] + CoalesceBatchesExec: target_batch_size=4096, metrics=[output_rows=3, elapsed_compute=43.004µs, spill_count=0, spilled_bytes=0, mem_used=0] + RepartitionExec: partitioning=RoundRobinBatch(10), metrics=[fetch_time=5.832958ms, repart_time=10ns, send_time=2.467µs] + RepartitionExec: partitioning=RoundRobinBatch(10), metrics=[fetch_time=386.585µs, repart_time=1ns, send_time=7.833µs] + ExecutionPlan(PlaceHolder), metrics=[] + +``` + +TODO: explains the output of `ANALYZE`. diff --git a/versioned_docs/version-0.11/reference/sql/functions/df-functions.md b/versioned_docs/version-0.11/reference/sql/functions/df-functions.md new file mode 100644 index 000000000..84ca60050 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/functions/df-functions.md @@ -0,0 +1,5036 @@ +--- +description: Generated from the Apache DataFusion project's documents, this page lists and describes DataFusion functions, including scalar, window, and array functions. +--- + +# DataFusion Functions + +This page is generated from the Apache DataFusion project's documents: + * [DataFusion Scalar Functions](https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/scalar_functions.md) + * [DataFusion Scalar Functions (NEW)](https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/scalar_functions_new.md) + * [DataFusion Aggregate Functions](https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/aggregate_functions.md) + * [DataFusion Window Functions](https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/window_functions.md) + + + +## Scalar Functions + +Scalar functions operate on a single row at a time and return a single value. + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. +Please see the [Scalar Functions (new)](#scalar-functions-new) page for +the rest of the documentation. + +### Math Functions + +- [abs](#abs) +- [acos](#acos) +- [acosh](#acosh) +- [asin](#asin) +- [asinh](#asinh) +- [atan](#atan) +- [atanh](#atanh) +- [atan2](#atan2) +- [cbrt](#cbrt) +- [ceil](#ceil) +- [cos](#cos) +- [cosh](#cosh) +- [degrees](#degrees) +- [exp](#exp) +- [factorial](#factorial) +- [floor](#floor) +- [gcd](#gcd) +- [isnan](#isnan) +- [iszero](#iszero) +- [lcm](#lcm) +- [ln](#ln) +- [log10](#log10) +- [log2](#log2) +- [nanvl](#nanvl) +- [pi](#pi) +- [power](#power) +- [pow](#pow) +- [radians](#radians) +- [random](#random) +- [round](#round) +- [signum](#signum) +- [sin](#sin) +- [sinh](#sinh) +- [sqrt](#sqrt) +- [tan](#tan) +- [tanh](#tanh) +- [trunc](#trunc) + +##### `abs` + +Returns the absolute value of a number. + +``` +abs(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `acos` + +Returns the arc cosine or inverse cosine of a number. + +``` +acos(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `acosh` + +Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. + +``` +acosh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `asin` + +Returns the arc sine or inverse sine of a number. + +``` +asin(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `asinh` + +Returns the area hyperbolic sine or inverse hyperbolic sine of a number. + +``` +asinh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `atan` + +Returns the arc tangent or inverse tangent of a number. + +``` +atan(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `atanh` + +Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. + +``` +atanh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `atan2` + +Returns the arc tangent or inverse tangent of `expression_y / expression_x`. + +``` +atan2(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `cbrt` + +Returns the cube root of a number. + +``` +cbrt(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `ceil` + +Returns the nearest integer greater than or equal to a number. + +``` +ceil(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `cos` + +Returns the cosine of a number. + +``` +cos(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `cosh` + +Returns the hyperbolic cosine of a number. + +``` +cosh(numeric_expression) +``` + +##### `degrees` + +Converts radians to degrees. + +``` +degrees(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `exp` + +Returns the base-e exponential of a number. + +``` +exp(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to use as the exponent. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `factorial` + +Factorial. Returns 1 if value is less than 2. + +``` +factorial(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `floor` + +Returns the nearest integer less than or equal to a number. + +``` +floor(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `gcd` + +Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero. + +``` +gcd(expression_x, expression_y) +``` + +###### Arguments + +- **expression_x**: First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `isnan` + +Returns true if a given number is +NaN or -NaN otherwise returns false. + +``` +isnan(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `iszero` + +Returns true if a given number is +0.0 or -0.0 otherwise returns false. + +``` +iszero(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `lcm` + +Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero. + +``` +lcm(expression_x, expression_y) +``` + +###### Arguments + +- **expression_x**: First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `ln` + +Returns the natural logarithm of a number. + +``` +ln(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `log10` + +Returns the base-10 logarithm of a number. + +``` +log10(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `log2` + +Returns the base-2 logarithm of a number. + +``` +log2(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `nanvl` + +Returns the first argument if it's not _NaN_. +Returns the second argument otherwise. + +``` +nanvl(expression_x, expression_y) +``` + +###### Arguments + +- **expression_x**: Numeric expression to return if it's not _NaN_. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Numeric expression to return if the first expression is _NaN_. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `pi` + +Returns an approximate value of π. + +``` +pi() +``` + +##### `power` + +Returns a base expression raised to the power of an exponent. + +``` +power(base, exponent) +``` + +###### Arguments + +- **base**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **exponent**: Exponent numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +###### Aliases + +- pow + +##### `pow` + +_Alias of [power](#power)._ + +##### `radians` + +Converts degrees to radians. + +``` +radians(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `random` + +Returns a random float value in the range [0, 1). +The random seed is unique to each row. + +``` +random() +``` + +##### `round` + +Rounds a number to the nearest integer. + +``` +round(numeric_expression[, decimal_places]) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **decimal_places**: Optional. The number of decimal places to round to. + Defaults to 0. + +##### `signum` + +Returns the sign of a number. +Negative numbers return `-1`. +Zero and positive numbers return `1`. + +``` +signum(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `sin` + +Returns the sine of a number. + +``` +sin(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `sinh` + +Returns the hyperbolic sine of a number. + +``` +sinh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `sqrt` + +Returns the square root of a number. + +``` +sqrt(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `tan` + +Returns the tangent of a number. + +``` +tan(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `tanh` + +Returns the hyperbolic tangent of a number. + +``` +tanh(numeric_expression) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `trunc` + +Truncates a number to a whole number or truncated to the specified decimal places. + +``` +trunc(numeric_expression[, decimal_places]) +``` + +###### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +- **decimal_places**: Optional. The number of decimal places to + truncate to. Defaults to 0 (truncate to a whole number). If + `decimal_places` is a positive integer, truncates digits to the + right of the decimal point. If `decimal_places` is a negative + integer, replaces digits to the left of the decimal point with `0`. + +### Conditional Functions + +See the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) + +### String Functions + +See the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) + +##### `position` + +Returns the position of `substr` in `origstr` (counting from 1). If `substr` does +not appear in `origstr`, return 0. + +``` +position(substr in origstr) +``` + +###### Arguments + +- **substr**: The pattern string. +- **origstr**: The model string. + +### Time and Date Functions + +- [now](#now) +- [current_date](#current-date) +- [current_time](#current-time) +- [date_bin](#date-bin) +- [date_trunc](#date-trunc) +- [datetrunc](#datetrunc) +- [date_part](#date-part) +- [datepart](#datepart) +- [extract](#extract) +- [today](#today) +- [make_date](#make-date) +- [to_char](#to-char) +- [to_local_time](#to-local-time) +- [to_timestamp](#to-timestamp) +- [to_timestamp_millis](#to-timestamp-millis) +- [to_timestamp_micros](#to_timestamp-micros) +- [to_timestamp_seconds](#to_timestamp-seconds) +- [to_timestamp_nanos](#to_timestamp-nanos) +- [from_unixtime](#from-unixtime) +- [to_unixtime](#to-unixtime) + +##### `now` + +Returns the current UTC timestamp. + +The `now()` return value is determined at query time and will return the same timestamp, +no matter when in the query plan the function executes. + +``` +now() +``` + +##### `current_date` + +Returns the current UTC date. + +The `current_date()` return value is determined at query time and will return the same date, +no matter when in the query plan the function executes. + +``` +current_date() +``` + +###### Aliases + +- today + +##### `today` + +_Alias of [current_date](#current-date)._ + +##### `current_time` + +Returns the current UTC time. + +The `current_time()` return value is determined at query time and will return the same time, +no matter when in the query plan the function executes. + +``` +current_time() +``` + +##### `date_bin` + +Calculates time intervals and returns the start of the interval nearest to the specified timestamp. +Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" +and applying an aggregate or selector function to each window. + +For example, if you "bin" or "window" data into 15 minute intervals, an input +timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 +minute bin it is in: `2023-01-01T18:15:00Z`. + +``` +date_bin(interval, expression, origin-timestamp) +``` + +###### Arguments + +- **interval**: Bin interval. +- **expression**: Time expression to operate on. + Can be a constant, column, or function. +- **origin-timestamp**: Optional. Starting point used to determine bin boundaries. If not specified + defaults `1970-01-01T00:00:00Z` (the UNIX epoch in UTC). + +The following intervals are supported: + +- nanoseconds +- microseconds +- milliseconds +- seconds +- minutes +- hours +- days +- weeks +- months +- years +- century + +##### `date_trunc` + +Truncates a timestamp value to a specified precision. + +``` +date_trunc(precision, expression) +``` + +###### Arguments + +- **precision**: Time precision to truncate to. + The following precisions are supported: + + - year / YEAR + - quarter / QUARTER + - month / MONTH + - week / WEEK + - day / DAY + - hour / HOUR + - minute / MINUTE + - second / SECOND + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +###### Aliases + +- datetrunc + +##### `datetrunc` + +_Alias of [date_trunc](#date-trunc)._ + +##### `date_part` + +Returns the specified part of the date as an integer. + +``` +date_part(part, expression) +``` + +###### Arguments + +- **part**: Part of the date to return. + The following date parts are supported: + + - year + - quarter _(emits value in inclusive range [1, 4] based on which quartile of the year the date is in)_ + - month + - week _(week of the year)_ + - day _(day of the month)_ + - hour + - minute + - second + - millisecond + - microsecond + - nanosecond + - dow _(day of the week)_ + - doy _(day of the year)_ + - epoch _(seconds since Unix epoch)_ + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +###### Aliases + +- datepart + +##### `datepart` + +_Alias of [date_part](#date-part)._ + +##### `extract` + +Returns a sub-field from a time value as an integer. + +``` +extract(field FROM source) +``` + +Equivalent to calling `date_part('field', source)`. For example, these are equivalent: + +```sql +extract(day FROM '2024-04-13'::date) +date_part('day', '2024-04-13'::date) +``` + +See [date_part](#date-part). + +##### `make_date` + +Make a date from year/month/day component parts. + +``` +make_date(year, month, day) +``` + +###### Arguments + +- **year**: Year to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **month**: Month to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **day**: Day to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. + +###### Example + +``` +> select make_date(2023, 1, 31); ++-------------------------------------------+ +| make_date(Int64(2023),Int64(1),Int64(31)) | ++-------------------------------------------+ +| 2023-01-31 | ++-------------------------------------------+ +> select make_date('2023', '01', '31'); ++-----------------------------------------------+ +| make_date(Utf8("2023"),Utf8("01"),Utf8("31")) | ++-----------------------------------------------+ +| 2023-01-31 | ++-----------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/make_date.rs) + +##### `to_char` + +Returns a string representation of a date, time, timestamp or duration based +on a [Chrono format]. Unlike the PostgreSQL equivalent of this function +numerical formatting is not supported. + +``` +to_char(expression, format) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function that results in a + date, time, timestamp or duration. +- **format**: A [Chrono format] string to use to convert the expression. + +###### Example + +``` +> select to_char('2023-03-01'::date, '%d-%m-%Y'); ++----------------------------------------------+ +| to_char(Utf8("2023-03-01"),Utf8("%d-%m-%Y")) | ++----------------------------------------------+ +| 01-03-2023 | ++----------------------------------------------+ +``` + +Additional examples can be found [here] + +[here]: https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_char.rs + +###### Aliases + +- date_format + +##### `to_local_time` + +Converts a timestamp with a timezone to a timestamp without a timezone (with no offset or +timezone information). This function handles daylight saving time changes. + +``` +to_local_time(expression) +``` + +###### Arguments + +- **expression**: Time expression to operate on. Can be a constant, column, or function. + +###### Example + +``` +> SELECT to_local_time('2024-04-01T00:00:20Z'::timestamp); ++---------------------------------------------+ +| to_local_time(Utf8("2024-04-01T00:00:20Z")) | ++---------------------------------------------+ +| 2024-04-01T00:00:20 | ++---------------------------------------------+ + +> SELECT to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels'); ++---------------------------------------------+ +| to_local_time(Utf8("2024-04-01T00:00:20Z")) | ++---------------------------------------------+ +| 2024-04-01T00:00:20 | ++---------------------------------------------+ + +> SELECT + time, + arrow_typeof(time) as type, + to_local_time(time) as to_local_time, + arrow_typeof(to_local_time(time)) as to_local_time_type +FROM ( + SELECT '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' AS time +); ++---------------------------+------------------------------------------------+---------------------+-----------------------------+ +| time | type | to_local_time | to_local_time_type | ++---------------------------+------------------------------------------------+---------------------+-----------------------------+ +| 2024-04-01T00:00:20+02:00 | Timestamp(Nanosecond, Some("Europe/Brussels")) | 2024-04-01T00:00:20 | Timestamp(Nanosecond, None) | ++---------------------------+------------------------------------------------+---------------------+-----------------------------+ + +## combine `to_local_time()` with `date_bin()` to bin on boundaries in the timezone rather +## than UTC boundaries + +> SELECT date_bin(interval '1 day', to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels')) AS date_bin; ++---------------------+ +| date_bin | ++---------------------+ +| 2024-04-01T00:00:00 | ++---------------------+ + +> SELECT date_bin(interval '1 day', to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels')) AT TIME ZONE 'Europe/Brussels' AS date_bin_with_timezone; ++---------------------------+ +| date_bin_with_timezone | ++---------------------------+ +| 2024-04-01T00:00:00+02:00 | ++---------------------------+ +``` + +##### `to_timestamp` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00Z`). +Supports strings, integer, unsigned integer, and double types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats] are provided. +Integers, unsigned integers, and doubles are interpreted as seconds since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding timestamp. + +Note: `to_timestamp` returns `Timestamp(Nanosecond)`. The supported range for integer input is between `-9223372037` and `9223372036`. +Supported range for string input is between `1677-09-21T00:12:44.0` and `2262-04-11T23:47:16.0`. Please use `to_timestamp_seconds` +for the input outside of supported bounds. + +``` +to_timestamp(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +[chrono format]: https://docs.rs/chrono/latest/chrono/format/strftime/index.html + +###### Example + +``` +> select to_timestamp('2023-01-31T09:26:56.123456789-05:00'); ++-----------------------------------------------------------+ +| to_timestamp(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++-----------------------------------------------------------+ +| 2023-01-31T14:26:56.123456789 | ++-----------------------------------------------------------+ +> select to_timestamp('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++--------------------------------------------------------------------------------------------------------+ +| to_timestamp(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++--------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00.123456789 | ++--------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `to_timestamp_millis` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`). +Supports strings, integer, and unsigned integer types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format]s are provided. +Integers and unsigned integers are interpreted as milliseconds since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding timestamp. + +``` +to_timestamp_millis(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_timestamp_millis('2023-01-31T09:26:56.123456789-05:00'); ++------------------------------------------------------------------+ +| to_timestamp_millis(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++------------------------------------------------------------------+ +| 2023-01-31T14:26:56.123 | ++------------------------------------------------------------------+ +> select to_timestamp_millis('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++---------------------------------------------------------------------------------------------------------------+ +| to_timestamp_millis(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++---------------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00.123 | ++---------------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `to_timestamp_micros` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000Z`). +Supports strings, integer, and unsigned integer types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format]s are provided. +Integers and unsigned integers are interpreted as microseconds since the unix epoch (`1970-01-01T00:00:00Z`) +Returns the corresponding timestamp. + +``` +to_timestamp_micros(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_timestamp_micros('2023-01-31T09:26:56.123456789-05:00'); ++------------------------------------------------------------------+ +| to_timestamp_micros(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++------------------------------------------------------------------+ +| 2023-01-31T14:26:56.123456 | ++------------------------------------------------------------------+ +> select to_timestamp_micros('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++---------------------------------------------------------------------------------------------------------------+ +| to_timestamp_micros(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++---------------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00.123456 | ++---------------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `to_timestamp_nanos` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000000Z`). +Supports strings, integer, and unsigned integer types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format]s are provided. +Integers and unsigned integers are interpreted as nanoseconds since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding timestamp. + +``` +to_timestamp_nanos(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_timestamp_nanos('2023-01-31T09:26:56.123456789-05:00'); ++-----------------------------------------------------------------+ +| to_timestamp_nanos(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++-----------------------------------------------------------------+ +| 2023-01-31T14:26:56.123456789 | ++-----------------------------------------------------------------+ +> select to_timestamp_nanos('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++--------------------------------------------------------------------------------------------------------------+ +| to_timestamp_nanos(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++--------------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00.123456789 | ++---------------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `to_timestamp_seconds` + +Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`). +Supports strings, integer, and unsigned integer types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format]s are provided. +Integers and unsigned integers are interpreted as seconds since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding timestamp. + +``` +to_timestamp_seconds(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_timestamp_seconds('2023-01-31T09:26:56.123456789-05:00'); ++-------------------------------------------------------------------+ +| to_timestamp_seconds(Utf8("2023-01-31T09:26:56.123456789-05:00")) | ++-------------------------------------------------------------------+ +| 2023-01-31T14:26:56 | ++-------------------------------------------------------------------+ +> select to_timestamp_seconds('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y'); ++----------------------------------------------------------------------------------------------------------------+ +| to_timestamp_seconds(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) | ++----------------------------------------------------------------------------------------------------------------+ +| 2023-05-17T03:59:00 | ++----------------------------------------------------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_timestamp.rs) + +##### `from_unixtime` + +Converts an integer to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). +Integers and unsigned integers are interpreted as nanoseconds since the unix epoch (`1970-01-01T00:00:00Z`) +return the corresponding timestamp. + +``` +from_unixtime(expression) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `to_unixtime` + +Converts a value to seconds since the unix epoch (`1970-01-01T00:00:00Z`). +Supports strings, dates, timestamps and double types as input. +Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats] are provided. + +``` +to_unixtime(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Chrono format] strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +``` +> select to_unixtime('2020-09-08T12:00:00+00:00'); ++------------------------------------------------+ +| to_unixtime(Utf8("2020-09-08T12:00:00+00:00")) | ++------------------------------------------------+ +| 1599566400 | ++------------------------------------------------+ +> select to_unixtime('01-14-2023 01:01:30+05:30', '%q', '%d-%m-%Y %H/%M/%S', '%+', '%m-%d-%Y %H:%M:%S%#z'); ++-----------------------------------------------------------------------------------------------------------------------------+ +| to_unixtime(Utf8("01-14-2023 01:01:30+05:30"),Utf8("%q"),Utf8("%d-%m-%Y %H/%M/%S"),Utf8("%+"),Utf8("%m-%d-%Y %H:%M:%S%#z")) | ++-----------------------------------------------------------------------------------------------------------------------------+ +| 1673638290 | ++-----------------------------------------------------------------------------------------------------------------------------+ +``` + +### Array Functions + +- [array_any_value](#array-any-value) +- [array_append](#array-append) +- [array_sort](#array-sort) +- [array_cat](#array-cat) +- [array_concat](#array-concat) +- [array_contains](#array-contains) +- [array_dims](#array-dims) +- [array_distance](#array-distance) +- [array_distinct](#array-distinct) +- [array_has](#array-has) +- [array_has_all](#array-has-all) +- [array_has_any](#array-has-any) +- [array_element](#array-element) +- [array_empty](#array-empty) +- [array_except](#array-except) +- [array_extract](#array-extract) +- [array_fill](#array-fill) +- [array_indexof](#array-indexof) +- [array_intersect](#array-intersect) +- [array_join](#array-join) +- [array_length](#array-length) +- [array_ndims](#array-ndims) +- [array_prepend](#array-prepend) +- [array_pop_front](#array-pop-front) +- [array_pop_back](#array-pop-back) +- [array_position](#array-position) +- [array_positions](#array-positions) +- [array_push_back](#array-push-back) +- [array_push_front](#array-push-front) +- [array_repeat](#array-repeat) +- [array_resize](#array-resize) +- [array_remove](#array-remove) +- [array_remove_n](#array-remove-n) +- [array_remove_all](#array-remove-all) +- [array_replace](#array-replace) +- [array_replace_n](#array-replace-n) +- [array_replace_all](#array-replace-all) +- [array_reverse](#array-reverse) +- [array_slice](#array-slice) +- [array_to_string](#array-to-string) +- [array_union](#array-union) +- [cardinality](#cardinality) +- [empty](#empty) +- [flatten](#flatten) +- [generate_series](#generate-series) +- [list_any_value](#list-any-value) +- [list_append](#list-append) +- [list_sort](#list-sort) +- [list_cat](#list-cat) +- [list_concat](#list-concat) +- [list_dims](#list-dims) +- [list_distance](#list-distance) +- [list_distinct](#list-distinct) +- [list_element](#list-element) +- [list_except](#list-except) +- [list_extract](#list-extract) +- [list_has](#list-has) +- [list_has_all](#list-has-all) +- [list_has_any](#list-has-any) +- [list_indexof](#list-indexof) +- [list_intersect](#list-intersect) +- [list_join](#list-join) +- [list_length](#list-length) +- [list_ndims](#list-ndims) +- [list_prepend](#list-prepend) +- [list_pop_back](#list-pop-back) +- [list_pop_front](#list-pop-front) +- [list_position](#list-position) +- [list_positions](#list-positions) +- [list_push_back](#list-push-back) +- [list_push_front](#list-push-front) +- [list_repeat](#list-repeat) +- [list_resize](#list-resize) +- [list_remove](#list-remove) +- [list_remove_n](#list-remove-n) +- [list_remove_all](#list-remove-all) +- [list_replace](#list-replace) +- [list_replace_n](#list-replace-n) +- [list_replace_all](#list-replace-all) +- [list_slice](#list-slice) +- [list_to_string](#list-to-string) +- [list_union](#list-union) +- [make_array](#make-array) +- [make_list](#make-list) +- [string_to_array](#string-to-array) +- [string_to_list](#string-to-list) +- [trim_array](#trim-array) +- [unnest](#unnest) +- [range](#range) + +##### `array_any_value` + +Returns the first non-null element in the array. + +``` +array_any_value(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_any_value([NULL, 1, 2, 3]); ++--------------------------------------------------------------+ +| array_any_value(List([NULL,1,2,3])) | ++--------------------------------------------------------------+ +| 1 | ++--------------------------------------------------------------+ +``` + +##### `array_append` + +Appends an element to the end of an array. + +``` +array_append(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to append to the array. + +###### Example + +``` +> select array_append([1, 2, 3], 4); ++--------------------------------------+ +| array_append(List([1,2,3]),Int64(4)) | ++--------------------------------------+ +| [1, 2, 3, 4] | ++--------------------------------------+ +``` + +###### Aliases + +- array_push_back +- list_append +- list_push_back + +##### `array_sort` + +Sort array. + +``` +array_sort(array, desc, nulls_first) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **desc**: Whether to sort in descending order(`ASC` or `DESC`). +- **nulls_first**: Whether to sort nulls first(`NULLS FIRST` or `NULLS LAST`). + +###### Example + +``` +> select array_sort([3, 1, 2]); ++-----------------------------+ +| array_sort(List([3,1,2])) | ++-----------------------------+ +| [1, 2, 3] | ++-----------------------------+ +``` + +###### Aliases + +- list_sort + +##### `array_resize` + +Resizes the list to contain size elements. Initializes new elements with value or empty if value is not set. + +``` +array_resize(array, size, value) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **size**: New size of given array. +- **value**: Defines new elements' value or empty if value is not set. + +###### Example + +``` +> select array_resize([1, 2, 3], 5, 0); ++-------------------------------------+ +| array_resize(List([1,2,3],5,0)) | ++-------------------------------------+ +| [1, 2, 3, 0, 0] | ++-------------------------------------+ +``` + +###### Aliases + +- list_resize + +##### `array_cat` + +_Alias of [array_concat](#array-concat)._ + +##### `array_concat` + +Concatenates arrays. + +``` +array_concat(array[, ..., array_n]) +``` + +###### Arguments + +- **array**: Array expression to concatenate. + Can be a constant, column, or function, and any combination of array operators. +- **array_n**: Subsequent array column or literal array to concatenate. + +###### Example + +``` +> select array_concat([1, 2], [3, 4], [5, 6]); ++---------------------------------------------------+ +| array_concat(List([1,2]),List([3,4]),List([5,6])) | ++---------------------------------------------------+ +| [1, 2, 3, 4, 5, 6] | ++---------------------------------------------------+ +``` + +###### Aliases + +- array_cat +- list_cat +- list_concat + +##### `array_contains` + +_Alias of [array_has](#array-has)._ + +##### `array_has` + +Returns true if the array contains the element + +``` +array_has(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Scalar or Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Aliases + +- list_has + +##### `array_has_all` + +Returns true if all elements of sub-array exist in array + +``` +array_has_all(array, sub-array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **sub-array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Aliases + +- list_has_all + +##### `array_has_any` + +Returns true if any elements exist in both arrays + +``` +array_has_any(array, sub-array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **sub-array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Aliases + +- list_has_any + +##### `array_dims` + +Returns an array of the array's dimensions. + +``` +array_dims(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_dims([[1, 2, 3], [4, 5, 6]]); ++---------------------------------+ +| array_dims(List([1,2,3,4,5,6])) | ++---------------------------------+ +| [2, 3] | ++---------------------------------+ +``` + +###### Aliases + +- list_dims + +##### `array_distance` + +Returns the Euclidean distance between two input arrays of equal length. + +``` +array_distance(array1, array2) +``` + +###### Arguments + +- **array1**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_distance([1, 2], [1, 4]); ++------------------------------------+ +| array_distance(List([1,2], [1,4])) | ++------------------------------------+ +| 2.0 | ++------------------------------------+ +``` + +###### Aliases + +- list_distance + +##### `array_distinct` + +Returns distinct values from the array after removing duplicates. + +``` +array_distinct(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_distinct([1, 3, 2, 3, 1, 2, 4]); ++---------------------------------+ +| array_distinct(List([1,2,3,4])) | ++---------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------+ +``` + +###### Aliases + +- list_distinct + +##### `array_element` + +Extracts the element with the index n from the array. + +``` +array_element(array, index) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **index**: Index to extract the element from the array. + +###### Example + +``` +> select array_element([1, 2, 3, 4], 3); ++-----------------------------------------+ +| array_element(List([1,2,3,4]),Int64(3)) | ++-----------------------------------------+ +| 3 | ++-----------------------------------------+ +``` + +###### Aliases + +- array_extract +- list_element +- list_extract + +##### `array_extract` + +_Alias of [array_element](#array-element)._ + +##### `array_fill` + +Returns an array filled with copies of the given value. + +DEPRECATED: use `array_repeat` instead! + +``` +array_fill(element, array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to copy to the array. + +##### `flatten` + +Converts an array of arrays to a flat array + +- Applies to any depth of nested arrays +- Does not change arrays that are already flat + +The flattened array contains all the elements from all source arrays. + +###### Arguments + +- **array**: Array expression + Can be a constant, column, or function, and any combination of array operators. + +``` +flatten(array) +``` + +##### `array_indexof` + +_Alias of [array_position](#array-position)._ + +##### `array_intersect` + +Returns an array of elements in the intersection of array1 and array2. + +``` +array_intersect(array1, array2) +``` + +###### Arguments + +- **array1**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [3, 4] | ++----------------------------------------------------+ +> select array_intersect([1, 2, 3, 4], [5, 6, 7, 8]); ++----------------------------------------------------+ +| array_intersect([1, 2, 3, 4], [5, 6, 7, 8]); | ++----------------------------------------------------+ +| [] | ++----------------------------------------------------+ +``` + +--- + +###### Aliases + +- list_intersect + +##### `array_join` + +_Alias of [array_to_string](#array-to-string)._ + +##### `array_length` + +Returns the length of the array dimension. + +``` +array_length(array, dimension) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **dimension**: Array dimension. + +###### Example + +``` +> select array_length([1, 2, 3, 4, 5]); ++---------------------------------+ +| array_length(List([1,2,3,4,5])) | ++---------------------------------+ +| 5 | ++---------------------------------+ +``` + +###### Aliases + +- list_length + +##### `array_ndims` + +Returns the number of dimensions of the array. + +``` +array_ndims(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_ndims([[1, 2, 3], [4, 5, 6]]); ++----------------------------------+ +| array_ndims(List([1,2,3,4,5,6])) | ++----------------------------------+ +| 2 | ++----------------------------------+ +``` + +###### Aliases + +- list_ndims + +##### `array_prepend` + +Prepends an element to the beginning of an array. + +``` +array_prepend(element, array) +``` + +###### Arguments + +- **element**: Element to prepend to the array. +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_prepend(1, [2, 3, 4]); ++---------------------------------------+ +| array_prepend(Int64(1),List([2,3,4])) | ++---------------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------------+ +``` + +###### Aliases + +- array_push_front +- list_prepend +- list_push_front + +##### `array_pop_front` + +Returns the array without the first element. + +``` +array_pop_front(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_pop_front([1, 2, 3]); ++-------------------------------+ +| array_pop_front(List([1,2,3])) | ++-------------------------------+ +| [2, 3] | ++-------------------------------+ +``` + +###### Aliases + +- list_pop_front + +##### `array_pop_back` + +Returns the array without the last element. + +``` +array_pop_back(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_pop_back([1, 2, 3]); ++-------------------------------+ +| array_pop_back(List([1,2,3])) | ++-------------------------------+ +| [1, 2] | ++-------------------------------+ +``` + +###### Aliases + +- list_pop_back + +##### `array_position` + +Returns the position of the first occurrence of the specified element in the array. + +``` +array_position(array, element) +array_position(array, element, index) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to search for position in the array. +- **index**: Index at which to start searching. + +###### Example + +``` +> select array_position([1, 2, 2, 3, 1, 4], 2); ++----------------------------------------------+ +| array_position(List([1,2,2,3,1,4]),Int64(2)) | ++----------------------------------------------+ +| 2 | ++----------------------------------------------+ +``` + +###### Aliases + +- array_indexof +- list_indexof +- list_position + +##### `array_positions` + +Searches for an element in the array, returns all occurrences. + +``` +array_positions(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to search for positions in the array. + +###### Example + +``` +> select array_positions([1, 2, 2, 3, 1, 4], 2); ++-----------------------------------------------+ +| array_positions(List([1,2,2,3,1,4]),Int64(2)) | ++-----------------------------------------------+ +| [2, 3] | ++-----------------------------------------------+ +``` + +###### Aliases + +- list_positions + +##### `array_push_back` + +_Alias of [array_append](#array-append)._ + +##### `array_push_front` + +_Alias of [array_prepend](#array-prepend)._ + +##### `array_repeat` + +Returns an array containing element `count` times. + +``` +array_repeat(element, count) +``` + +###### Arguments + +- **element**: Element expression. + Can be a constant, column, or function, and any combination of array operators. +- **count**: Value of how many times to repeat the element. + +###### Example + +``` +> select array_repeat(1, 3); ++---------------------------------+ +| array_repeat(Int64(1),Int64(3)) | ++---------------------------------+ +| [1, 1, 1] | ++---------------------------------+ +``` + +``` +> select array_repeat([1, 2], 2); ++------------------------------------+ +| array_repeat(List([1,2]),Int64(2)) | ++------------------------------------+ +| [[1, 2], [1, 2]] | ++------------------------------------+ +``` + +###### Aliases + +- list_repeat + +##### `array_remove` + +Removes the first element from the array equal to the given value. + +``` +array_remove(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. + +###### Example + +``` +> select array_remove([1, 2, 2, 3, 2, 1, 4], 2); ++----------------------------------------------+ +| array_remove(List([1,2,2,3,2,1,4]),Int64(2)) | ++----------------------------------------------+ +| [1, 2, 3, 2, 1, 4] | ++----------------------------------------------+ +``` + +###### Aliases + +- list_remove + +##### `array_remove_n` + +Removes the first `max` elements from the array equal to the given value. + +``` +array_remove_n(array, element, max) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. +- **max**: Number of first occurrences to remove. + +###### Example + +``` +> select array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2); ++---------------------------------------------------------+ +| array_remove_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(2)) | ++---------------------------------------------------------+ +| [1, 3, 2, 1, 4] | ++---------------------------------------------------------+ +``` + +###### Aliases + +- list_remove_n + +##### `array_remove_all` + +Removes all elements from the array equal to the given value. + +``` +array_remove_all(array, element) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. + +###### Example + +``` +> select array_remove_all([1, 2, 2, 3, 2, 1, 4], 2); ++--------------------------------------------------+ +| array_remove_all(List([1,2,2,3,2,1,4]),Int64(2)) | ++--------------------------------------------------+ +| [1, 3, 1, 4] | ++--------------------------------------------------+ +``` + +###### Aliases + +- list_remove_all + +##### `array_replace` + +Replaces the first occurrence of the specified element with another specified element. + +``` +array_replace(array, from, to) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. + +###### Example + +``` +> select array_replace([1, 2, 2, 3, 2, 1, 4], 2, 5); ++--------------------------------------------------------+ +| array_replace(List([1,2,2,3,2,1,4]),Int64(2),Int64(5)) | ++--------------------------------------------------------+ +| [1, 5, 2, 3, 2, 1, 4] | ++--------------------------------------------------------+ +``` + +###### Aliases + +- list_replace + +##### `array_replace_n` + +Replaces the first `max` occurrences of the specified element with another specified element. + +``` +array_replace_n(array, from, to, max) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. +- **max**: Number of first occurrences to replace. + +###### Example + +``` +> select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2); ++-------------------------------------------------------------------+ +| array_replace_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(5),Int64(2)) | ++-------------------------------------------------------------------+ +| [1, 5, 5, 3, 2, 1, 4] | ++-------------------------------------------------------------------+ +``` + +###### Aliases + +- list_replace_n + +##### `array_replace_all` + +Replaces all occurrences of the specified element with another specified element. + +``` +array_replace_all(array, from, to) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. + +###### Example + +``` +> select array_replace_all([1, 2, 2, 3, 2, 1, 4], 2, 5); ++------------------------------------------------------------+ +| array_replace_all(List([1,2,2,3,2,1,4]),Int64(2),Int64(5)) | ++------------------------------------------------------------+ +| [1, 5, 5, 3, 5, 1, 4] | ++------------------------------------------------------------+ +``` + +###### Aliases + +- list_replace_all + +##### `array_reverse` + +Returns the array with the order of the elements reversed. + +``` +array_reverse(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_reverse([1, 2, 3, 4]); ++------------------------------------------------------------+ +| array_reverse(List([1, 2, 3, 4])) | ++------------------------------------------------------------+ +| [4, 3, 2, 1] | ++------------------------------------------------------------+ +``` + +###### Aliases + +- list_reverse + +##### `array_slice` + +Returns a slice of the array based on 1-indexed start and end positions. + +``` +array_slice(array, begin, end) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **begin**: Index of the first element. + If negative, it counts backward from the end of the array. +- **end**: Index of the last element. + If negative, it counts backward from the end of the array. +- **stride**: Stride of the array slice. The default is 1. + +###### Example + +``` +> select array_slice([1, 2, 3, 4, 5, 6, 7, 8], 3, 6); ++--------------------------------------------------------+ +| array_slice(List([1,2,3,4,5,6,7,8]),Int64(3),Int64(6)) | ++--------------------------------------------------------+ +| [3, 4, 5, 6] | ++--------------------------------------------------------+ +``` + +###### Aliases + +- list_slice + +##### `array_to_string` + +Converts each element to its text representation. + +``` +array_to_string(array, delimiter) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **delimiter**: Array element separator. + +###### Example + +``` +> select array_to_string([[1, 2, 3, 4], [5, 6, 7, 8]], ','); ++----------------------------------------------------+ +| array_to_string(List([1,2,3,4,5,6,7,8]),Utf8(",")) | ++----------------------------------------------------+ +| 1,2,3,4,5,6,7,8 | ++----------------------------------------------------+ +``` + +###### Aliases + +- array_join +- list_join +- list_to_string + +##### `array_union` + +Returns an array of elements that are present in both arrays (all elements from both arrays) with out duplicates. + +``` +array_union(array1, array2) +``` + +###### Arguments + +- **array1**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_union([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_union([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [1, 2, 3, 4, 5, 6] | ++----------------------------------------------------+ +> select array_union([1, 2, 3, 4], [5, 6, 7, 8]); ++----------------------------------------------------+ +| array_union([1, 2, 3, 4], [5, 6, 7, 8]); | ++----------------------------------------------------+ +| [1, 2, 3, 4, 5, 6, 7, 8] | ++----------------------------------------------------+ +``` + +--- + +###### Aliases + +- list_union + +##### `array_except` + +Returns an array of the elements that appear in the first array but not in the second. + +``` +array_except(array1, array2) +``` + +###### Arguments + +- **array1**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select array_except([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_except([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [1, 2] | ++----------------------------------------------------+ +> select array_except([1, 2, 3, 4], [3, 4, 5, 6]); ++----------------------------------------------------+ +| array_except([1, 2, 3, 4], [3, 4, 5, 6]); | ++----------------------------------------------------+ +| [1, 2] | ++----------------------------------------------------+ +``` + +--- + +###### Aliases + +- list_except + +##### `cardinality` + +Returns the total number of elements in the array. + +``` +cardinality(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]); ++--------------------------------------+ +| cardinality(List([1,2,3,4,5,6,7,8])) | ++--------------------------------------+ +| 8 | ++--------------------------------------+ +``` + +##### `empty` + +Returns 1 for an empty array or 0 for a non-empty array. + +``` +empty(array) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. + +###### Example + +``` +> select empty([1]); ++------------------+ +| empty(List([1])) | ++------------------+ +| 0 | ++------------------+ +``` + +###### Aliases + +- array_empty, +- list_empty + +##### `generate_series` + +Similar to the range function, but it includes the upper bound. + +``` +generate_series(start, stop, step) +``` + +###### Arguments + +- **start**: start of the series. Ints, timestamps, dates or string types that can be coerced to Date32 are supported. +- **end**: end of the series (included). Type must be the same as start. +- **step**: increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges. + +###### Example + +``` +> select generate_series(1,3); ++------------------------------------+ +| generate_series(Int64(1),Int64(3)) | ++------------------------------------+ +| [1, 2, 3] | ++------------------------------------+ +``` + +##### `list_any_value` + +_Alias of [array_any_value](#array-any-value)._ + +##### `list_append` + +_Alias of [array_append](#array-append)._ + +##### `list_cat` + +_Alias of [array_concat](#array-concat)._ + +##### `list_concat` + +_Alias of [array_concat](#array-concat)._ + +##### `list_dims` + +_Alias of [array_dims](#array-dims)._ + +##### `list_distance` + +_Alias of [array_distance](#array-distance)._ + +##### `list_distinct` + +_Alias of [array_distinct](#array-distinct)._ + +##### `list_element` + +_Alias of [array_element](#array-element)._ + +##### `list_empty` + +_Alias of [empty](#empty)._ + +##### `list_except` + +_Alias of [array_element](#array-except)._ + +##### `list_extract` + +_Alias of [array_element](#array-element)._ + +##### `list_has` + +_Alias of [array_has](#array-has)._ + +##### `list_has_all` + +_Alias of [array_has_all](#array-has-all)._ + +##### `list_has_any` + +_Alias of [array_has_any](#array-has-any)._ + +##### `list_indexof` + +_Alias of [array_position](#array-position)._ + +##### `list_intersect` + +_Alias of [array_position](#array-intersect)._ + +##### `list_join` + +_Alias of [array_to_string](#array-to-string)._ + +##### `list_length` + +_Alias of [array_length](#array-length)._ + +##### `list_ndims` + +_Alias of [array_ndims](#array-ndims)._ + +##### `list_prepend` + +_Alias of [array_prepend](#array-prepend)._ + +##### `list_pop_back` + +_Alias of [array_pop_back](#array-pop-back)._ + +##### `list_pop_front` + +_Alias of [array_pop_front](#array-pop-front)._ + +##### `list_position` + +_Alias of [array_position](#array-position)._ + +##### `list_positions` + +_Alias of [array_positions](#array-positions)._ + +##### `list_push_back` + +_Alias of [array_append](#array-append)._ + +##### `list_push_front` + +_Alias of [array_prepend](#array-prepend)._ + +##### `list_repeat` + +_Alias of [array_repeat](#array-repeat)._ + +##### `list_resize` + +_Alias of [array_resize](#array-resize)._ + +##### `list_remove` + +_Alias of [array_remove](#array-remove)._ + +##### `list_remove_n` + +_Alias of [array_remove_n](#array-remove-n)._ + +##### `list_remove_all` + +_Alias of [array_remove_all](#array-remove-all)._ + +##### `list_replace` + +_Alias of [array_replace](#array-replace)._ + +##### `list_replace_n` + +_Alias of [array_replace_n](#array-replace-n)._ + +##### `list_replace_all` + +_Alias of [array_replace_all](#array-replace-all)._ + +##### `list_reverse` + +_Alias of [array_reverse](#array-reverse)._ + +##### `list_slice` + +_Alias of [array_slice](#array-slice)._ + +##### `list_sort` + +_Alias of [array_sort](#array-sort)._ + +##### `list_to_string` + +_Alias of [array_to_string](#array-to-string)._ + +##### `list_union` + +_Alias of [array_union](#array-union)._ + +##### `make_array` + +Returns an Arrow array using the specified input expressions. + +``` +make_array(expression1[, ..., expression_n]) +``` + +##### `array_empty` + +_Alias of [empty](#empty)._ + +###### Arguments + +- **expression_n**: Expression to include in the output array. + Can be a constant, column, or function, and any combination of arithmetic or + string operators. + +###### Example + +``` +> select make_array(1, 2, 3, 4, 5); ++----------------------------------------------------------+ +| make_array(Int64(1),Int64(2),Int64(3),Int64(4),Int64(5)) | ++----------------------------------------------------------+ +| [1, 2, 3, 4, 5] | ++----------------------------------------------------------+ +``` + +###### Aliases + +- make_list + +##### `make_list` + +_Alias of [make_array](#make-array)._ + +##### `string_to_array` + +Splits a string in to an array of substrings based on a delimiter. Any substrings matching the optional `null_str` argument are replaced with NULL. +`SELECT string_to_array('abc##def', '##')` or `SELECT string_to_array('abc def', ' ', 'def')` + +``` +starts_with(str, delimiter[, null_str]) +``` + +###### Arguments + +- **str**: String expression to split. +- **delimiter**: Delimiter string to split on. +- **null_str**: Substring values to be replaced with `NULL` + +###### Aliases + +- string_to_list + +##### `string_to_list` + +_Alias of [string_to_array](#string-to-array)._ + +##### `trim_array` + +Removes the last n elements from the array. + +DEPRECATED: use `array_slice` instead! + +``` +trim_array(array, n) +``` + +###### Arguments + +- **array**: Array expression. + Can be a constant, column, or function, and any combination of array operators. +- **n**: Element to trim the array. + +##### `unnest` + +Transforms an array into rows. + +###### Arguments + +- **array**: Array expression to unnest. + Can be a constant, column, or function, and any combination of array operators. + +###### Examples + +``` +> select unnest(make_array(1, 2, 3, 4, 5)); ++------------------------------------------------------------------+ +| unnest(make_array(Int64(1),Int64(2),Int64(3),Int64(4),Int64(5))) | ++------------------------------------------------------------------+ +| 1 | +| 2 | +| 3 | +| 4 | +| 5 | ++------------------------------------------------------------------+ +``` + +``` +> select unnest(range(0, 10)); ++-----------------------------------+ +| unnest(range(Int64(0),Int64(10))) | ++-----------------------------------+ +| 0 | +| 1 | +| 2 | +| 3 | +| 4 | +| 5 | +| 6 | +| 7 | +| 8 | +| 9 | ++-----------------------------------+ +``` + +##### `range` + +Returns an Arrow array between start and stop with step. `SELECT range(2, 10, 3) -> [2, 5, 8]` or `SELECT range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH);` + +The range start..end contains all values with `start <= x < end`. It is empty if `start >= end`. + +Step can not be 0 (then the range will be nonsense.). + +Note that when the required range is a number, it accepts (stop), (start, stop), and (start, stop, step) as parameters, but when the required range is a date or timestamp, it must be 3 non-NULL parameters. +For example, + +``` +SELECT range(3); +SELECT range(1,5); +SELECT range(1,5,1); +``` + +are allowed in number ranges + +but in date and timestamp ranges, only + +``` +SELECT range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH); +SELECT range(TIMESTAMP '1992-09-01', TIMESTAMP '1993-03-01', INTERVAL '1' MONTH); +``` + +is allowed, and + +``` +SELECT range(DATE '1992-09-01', DATE '1993-03-01', NULL); +SELECT range(NULL, DATE '1993-03-01', INTERVAL '1' MONTH); +SELECT range(DATE '1992-09-01', NULL, INTERVAL '1' MONTH); +``` + +are not allowed + +###### Arguments + +- **start**: start of the range. Ints, timestamps, dates or string types that can be coerced to Date32 are supported. +- **end**: end of the range (not included). Type must be the same as start. +- **step**: increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges. + +###### Aliases + +- generate_series + +### Struct Functions + +- [unnest](#unnest-struct) + +For more struct functions see the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) + +##### `unnest (struct)` + +Unwraps struct fields into columns. + +###### Arguments + +- **struct**: Object expression to unnest. + Can be a constant, column, or function, and any combination of object operators. + +###### Examples + +``` +> select * from foo; ++---------------------+ +| column1 | ++---------------------+ +| {a: 5, b: a string} | ++---------------------+ + +> select unnest(column1) from foo; ++-----------------------+-----------------------+ +| unnest(foo.column1).a | unnest(foo.column1).b | ++-----------------------+-----------------------+ +| 5 | a string | ++-----------------------+-----------------------+ +``` + +### Map Functions + +- [map](#map) +- [make_map](#make-map) +- [map_extract](#map-extract) +- [map_keys](#map-keys) +- [map_values](#map-values) + +##### `map` + +Returns an Arrow map with the specified key-value pairs. + +``` +map(key, value) +map(key: value) +``` + +###### Arguments + +- **key**: Expression to be used for key. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. +- **value**: Expression to be used for value. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. + +###### Example + +``` +SELECT MAP(['POST', 'HEAD', 'PATCH'], [41, 33, null]); +---- +{POST: 41, HEAD: 33, PATCH: } + +SELECT MAP([[1,2], [3,4]], ['a', 'b']); +---- +{[1, 2]: a, [3, 4]: b} + +SELECT MAP { 'a': 1, 'b': 2 }; +---- +{a: 1, b: 2} +``` + +##### `make_map` + +Returns an Arrow map with the specified key-value pairs. + +``` +make_map(key_1, value_1, ..., key_n, value_n) +``` + +###### Arguments + +- **key_n**: Expression to be used for key. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. +- **value_n**: Expression to be used for value. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. + +###### Example + +``` +SELECT MAKE_MAP('POST', 41, 'HEAD', 33, 'PATCH', null); +---- +{POST: 41, HEAD: 33, PATCH: } +``` + +##### `map_extract` + +Return a list containing the value for a given key or an empty list if the key is not contained in the map. + +``` +map_extract(map, key) +``` + +###### Arguments + +- `map`: Map expression. + Can be a constant, column, or function, and any combination of map operators. +- `key`: Key to extract from the map. + Can be a constant, column, or function, any combination of arithmetic or + string operators, or a named expression of previous listed. + +###### Example + +``` +SELECT map_extract(MAP {'a': 1, 'b': NULL, 'c': 3}, 'a'); +---- +[1] +``` + +###### Aliases + +- element_at + +##### `map_keys` + +Return a list of all keys in the map. + +``` +map_keys(map) +``` + +###### Arguments + +- `map`: Map expression. + Can be a constant, column, or function, and any combination of map operators. + +###### Example + +``` +SELECT map_keys(MAP {'a': 1, 'b': NULL, 'c': 3}); +---- +[a, b, c] + +select map_keys(map([100, 5], [42,43])); +---- +[100, 5] +``` + +##### `map_values` + +Return a list of all values in the map. + +``` +map_values(map) +``` + +###### Arguments + +- `map`: Map expression. + Can be a constant, column, or function, and any combination of map operators. + +###### Example + +``` +SELECT map_values(MAP {'a': 1, 'b': NULL, 'c': 3}); +---- +[1, , 3] + +select map_values(map([100, 5], [42,43])); +---- +[42, 43] +``` + +### Other Functions + +See the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) + + + + +## Scalar Functions (NEW) + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. +Please see the [Scalar Functions (old)](#aggregate-functions) page for +the rest of the documentation. + +### Math Functions + +- [log](#log) + +##### `log` + +Returns the base-x logarithm of a number. Can either provide a specified base, or if omitted then takes the base-10 of a number. + +``` +log(base, numeric_expression) +log(numeric_expression) +``` + +###### Arguments + +- **base**: Base numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### Conditional Functions + +- [coalesce](#coalesce) +- [ifnull](#ifnull) +- [nullif](#nullif) +- [nvl](#nvl) +- [nvl2](#nvl2) + +##### `coalesce` + +Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. This function is often used to substitute a default value for _null_ values. + +``` +coalesce(expression1[, ..., expression_n]) +``` + +###### Arguments + +- **expression1, expression_n**: Expression to use if previous expressions are _null_. Can be a constant, column, or function, and any combination of arithmetic operators. Pass as many expression arguments as necessary. + +###### Example + +```sql +> select coalesce(null, null, 'datafusion'); ++----------------------------------------+ +| coalesce(NULL,NULL,Utf8("datafusion")) | ++----------------------------------------+ +| datafusion | ++----------------------------------------+ +``` + +##### `ifnull` + +_Alias of [nvl](#nvl)._ + +##### `nullif` + +Returns _null_ if _expression1_ equals _expression2_; otherwise it returns _expression1_. +This can be used to perform the inverse operation of [`coalesce`](#coalesce). + +``` +nullif(expression1, expression2) +``` + +###### Arguments + +- **expression1**: Expression to compare and return if equal to expression2. Can be a constant, column, or function, and any combination of operators. +- **expression2**: Expression to compare to expression1. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select nullif('datafusion', 'data'); ++-----------------------------------------+ +| nullif(Utf8("datafusion"),Utf8("data")) | ++-----------------------------------------+ +| datafusion | ++-----------------------------------------+ +> select nullif('datafusion', 'datafusion'); ++-----------------------------------------------+ +| nullif(Utf8("datafusion"),Utf8("datafusion")) | ++-----------------------------------------------+ +| | ++-----------------------------------------------+ +``` + +##### `nvl` + +Returns _expression2_ if _expression1_ is NULL otherwise it returns _expression1_. + +``` +nvl(expression1, expression2) +``` + +###### Arguments + +- **expression1**: Expression to return if not null. Can be a constant, column, or function, and any combination of operators. +- **expression2**: Expression to return if expr1 is null. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select nvl(null, 'a'); ++---------------------+ +| nvl(NULL,Utf8("a")) | ++---------------------+ +| a | ++---------------------+\ +> select nvl('b', 'a'); ++--------------------------+ +| nvl(Utf8("b"),Utf8("a")) | ++--------------------------+ +| b | ++--------------------------+ +``` + +###### Aliases + +- ifnull + +##### `nvl2` + +Returns _expression2_ if _expression1_ is not NULL; otherwise it returns _expression3_. + +``` +nvl2(expression1, expression2, expression3) +``` + +###### Arguments + +- **expression1**: Expression to test for null. Can be a constant, column, or function, and any combination of operators. +- **expression2**: Expression to return if expr1 is not null. Can be a constant, column, or function, and any combination of operators. +- **expression3**: Expression to return if expr1 is null. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select nvl2(null, 'a', 'b'); ++--------------------------------+ +| nvl2(NULL,Utf8("a"),Utf8("b")) | ++--------------------------------+ +| b | ++--------------------------------+ +> select nvl2('data', 'a', 'b'); ++----------------------------------------+ +| nvl2(Utf8("data"),Utf8("a"),Utf8("b")) | ++----------------------------------------+ +| a | ++----------------------------------------+ +``` + +### String Functions + +- [ascii](#ascii) +- [bit_length](#bit-length) +- [btrim](#btrim) +- [char_length](#char-length) +- [character_length](#character-length) +- [chr](#chr) +- [concat](#concat) +- [concat_ws](#concat-ws) +- [contains](#contains) +- [ends_with](#ends-with) +- [find_in_set](#find-in-set) +- [initcap](#initcap) +- [instr](#instr) +- [left](#left) +- [length](#length) +- [levenshtein](#levenshtein) +- [lower](#lower) +- [lpad](#lpad) +- [ltrim](#ltrim) +- [octet_length](#octet-length) +- [position](#position) +- [repeat](#repeat) +- [replace](#replace) +- [reverse](#reverse) +- [right](#right) +- [rpad](#rpad) +- [rtrim](#rtrim) +- [split_part](#split-part) +- [starts_with](#starts-with) +- [strpos](#strpos) +- [substr](#substr) +- [substr_index](#substr-index) +- [substring](#substring) +- [substring_index](#substring-index) +- [to_hex](#to-hex) +- [translate](#translate) +- [trim](#trim) +- [upper](#upper) +- [uuid](#uuid) + +##### `ascii` + +Returns the Unicode character code of the first character in a string. + +``` +ascii(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select ascii('abc'); ++--------------------+ +| ascii(Utf8("abc")) | ++--------------------+ +| 97 | ++--------------------+ +> select ascii('🚀'); ++-------------------+ +| ascii(Utf8("🚀")) | ++-------------------+ +| 128640 | ++-------------------+ +``` + +**Related functions**: + +- [chr](#chr) + +##### `bit_length` + +Returns the bit length of a string. + +``` +bit_length(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select bit_length('datafusion'); ++--------------------------------+ +| bit_length(Utf8("datafusion")) | ++--------------------------------+ +| 80 | ++--------------------------------+ +``` + +**Related functions**: + +- [length](#length) +- [octet_length](#octet-length) + +##### `btrim` + +Trims the specified trim string from the start and end of a string. If no trim string is provided, all whitespace is removed from the start and end of the input string. + +``` +btrim(str[, trim_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **trim_str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. _Default is whitespace characters._ + +###### Example + +```sql +> select btrim('__datafusion____', '_'); ++-------------------------------------------+ +| btrim(Utf8("__datafusion____"),Utf8("_")) | ++-------------------------------------------+ +| datafusion | ++-------------------------------------------+ +``` + +###### Aliases + +- trim + +**Related functions**: + +- [ltrim](#ltrim) +- [rtrim](#rtrim) + +##### `char_length` + +_Alias of [character_length](#character-length)._ + +##### `character_length` + +Returns the number of characters in a string. + +``` +character_length(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select character_length('Ångström'); ++------------------------------------+ +| character_length(Utf8("Ångström")) | ++------------------------------------+ +| 8 | ++------------------------------------+ +``` + +###### Aliases + +- length +- char_length + +**Related functions**: + +- [bit_length](#bit-length) +- [octet_length](#octet-length) + +##### `chr` + +Returns the character with the specified ASCII or Unicode code value. + +``` +chr(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select chr(128640); ++--------------------+ +| chr(Int64(128640)) | ++--------------------+ +| 🚀 | ++--------------------+ +``` + +**Related functions**: + +- [ascii](#ascii) + +##### `concat` + +Concatenates multiple strings together. + +``` +concat(str[, ..., str_n]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **str_n**: Subsequent string expressions to concatenate. + +###### Example + +```sql +> select concat('data', 'f', 'us', 'ion'); ++-------------------------------------------------------+ +| concat(Utf8("data"),Utf8("f"),Utf8("us"),Utf8("ion")) | ++-------------------------------------------------------+ +| datafusion | ++-------------------------------------------------------+ +``` + +**Related functions**: + +- [concat_ws](#concat-ws) + +##### `concat_ws` + +Concatenates multiple strings together with a specified separator. + +``` +concat_ws(separator, str[, ..., str_n]) +``` + +###### Arguments + +- **separator**: Separator to insert between concatenated strings. +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **str_n**: Subsequent string expressions to concatenate. expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select concat_ws('_', 'data', 'fusion'); ++--------------------------------------------------+ +| concat_ws(Utf8("_"),Utf8("data"),Utf8("fusion")) | ++--------------------------------------------------+ +| data_fusion | ++--------------------------------------------------+ +``` + +**Related functions**: + +- [concat](#concat) + +##### `contains` + +Return true if search_str is found within string (case-sensitive). + +``` +contains(str, search_str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **search_str**: The string to search for in str. + +###### Example + +```sql +> select contains('the quick brown fox', 'row'); ++---------------------------------------------------+ +| contains(Utf8("the quick brown fox"),Utf8("row")) | ++---------------------------------------------------+ +| true | ++---------------------------------------------------+ +``` + +##### `ends_with` + +Tests if a string ends with a substring. + +``` +ends_with(str, substr) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring to test for. + +###### Example + +```sql +> select ends_with('datafusion', 'soin'); ++--------------------------------------------+ +| ends_with(Utf8("datafusion"),Utf8("soin")) | ++--------------------------------------------+ +| false | ++--------------------------------------------+ +> select ends_with('datafusion', 'sion'); ++--------------------------------------------+ +| ends_with(Utf8("datafusion"),Utf8("sion")) | ++--------------------------------------------+ +| true | ++--------------------------------------------+ +``` + +##### `find_in_set` + +Returns a value in the range of 1 to N if the string str is in the string list strlist consisting of N substrings. + +``` +find_in_set(str, strlist) +``` + +###### Arguments + +- **str**: String expression to find in strlist. +- **strlist**: A string list is a string composed of substrings separated by , characters. + +###### Example + +```sql +> select find_in_set('b', 'a,b,c,d'); ++----------------------------------------+ +| find_in_set(Utf8("b"),Utf8("a,b,c,d")) | ++----------------------------------------+ +| 2 | ++----------------------------------------+ +``` + +##### `initcap` + +Capitalizes the first character in each word in the input string. Words are delimited by non-alphanumeric characters. + +``` +initcap(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select initcap('apache datafusion'); ++------------------------------------+ +| initcap(Utf8("apache datafusion")) | ++------------------------------------+ +| Apache Datafusion | ++------------------------------------+ +``` + +**Related functions**: + +- [lower](#lower) +- [upper](#upper) + +##### `instr` + +_Alias of [strpos](#strpos)._ + +##### `left` + +Returns a specified number of characters from the left side of a string. + +``` +left(str, n) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: Number of characters to return. + +###### Example + +```sql +> select left('datafusion', 4); ++-----------------------------------+ +| left(Utf8("datafusion"),Int64(4)) | ++-----------------------------------+ +| data | ++-----------------------------------+ +``` + +**Related functions**: + +- [right](#right) + +##### `length` + +_Alias of [character_length](#character-length)._ + +##### `levenshtein` + +Returns the [`Levenshtein distance`](https://en.wikipedia.org/wiki/Levenshtein_distance) between the two given strings. + +``` +levenshtein(str1, str2) +``` + +###### Arguments + +- **str1**: String expression to compute Levenshtein distance with str2. +- **str2**: String expression to compute Levenshtein distance with str1. + +###### Example + +```sql +> select levenshtein('kitten', 'sitting'); ++---------------------------------------------+ +| levenshtein(Utf8("kitten"),Utf8("sitting")) | ++---------------------------------------------+ +| 3 | ++---------------------------------------------+ +``` + +##### `lower` + +Converts a string to lower-case. + +``` +lower(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select lower('Ångström'); ++-------------------------+ +| lower(Utf8("Ångström")) | ++-------------------------+ +| ångström | ++-------------------------+ +``` + +**Related functions**: + +- [initcap](#initcap) +- [upper](#upper) + +##### `lpad` + +Pads the left side of a string with another string to a specified string length. + +``` +lpad(str, n[, padding_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: String length to pad to. +- **padding_str**: Optional string expression to pad with. Can be a constant, column, or function, and any combination of string operators. _Default is a space._ + +###### Example + +```sql +> select lpad('Dolly', 10, 'hello'); ++---------------------------------------------+ +| lpad(Utf8("Dolly"),Int64(10),Utf8("hello")) | ++---------------------------------------------+ +| helloDolly | ++---------------------------------------------+ +``` + +**Related functions**: + +- [rpad](#rpad) + +##### `ltrim` + +Trims the specified trim string from the beginning of a string. If no trim string is provided, all whitespace is removed from the start of the input string. + +``` +ltrim(str[, trim_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **trim_str**: String expression to trim from the beginning of the input string. Can be a constant, column, or function, and any combination of arithmetic operators. _Default is whitespace characters._ + +###### Example + +```sql +> select ltrim(' datafusion '); ++-------------------------------+ +| ltrim(Utf8(" datafusion ")) | ++-------------------------------+ +| datafusion | ++-------------------------------+ +> select ltrim('___datafusion___', '_'); ++-------------------------------------------+ +| ltrim(Utf8("___datafusion___"),Utf8("_")) | ++-------------------------------------------+ +| datafusion___ | ++-------------------------------------------+ +``` + +**Related functions**: + +- [btrim](#btrim) +- [rtrim](#rtrim) + +##### `octet_length` + +Returns the length of a string in bytes. + +``` +octet_length(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select octet_length('Ångström'); ++--------------------------------+ +| octet_length(Utf8("Ångström")) | ++--------------------------------+ +| 10 | ++--------------------------------+ +``` + +**Related functions**: + +- [bit_length](#bit-length) +- [length](#length) + +##### `position` + +_Alias of [strpos](#strpos)._ + +##### `repeat` + +Returns a string with an input string repeated a specified number. + +``` +repeat(str, n) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: Number of times to repeat the input string. + +###### Example + +```sql +> select repeat('data', 3); ++-------------------------------+ +| repeat(Utf8("data"),Int64(3)) | ++-------------------------------+ +| datadatadata | ++-------------------------------+ +``` + +##### `replace` + +Replaces all occurrences of a specified substring in a string with a new substring. + +``` +replace(str, substr, replacement) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring expression to replace in the input string. Substring expression expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **replacement**: Replacement substring expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select replace('ABabbaBA', 'ab', 'cd'); ++-------------------------------------------------+ +| replace(Utf8("ABabbaBA"),Utf8("ab"),Utf8("cd")) | ++-------------------------------------------------+ +| ABcdbaBA | ++-------------------------------------------------+ +``` + +##### `reverse` + +Reverses the character order of a string. + +``` +reverse(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select reverse('datafusion'); ++-----------------------------+ +| reverse(Utf8("datafusion")) | ++-----------------------------+ +| noisufatad | ++-----------------------------+ +``` + +##### `right` + +Returns a specified number of characters from the right side of a string. + +``` +right(str, n) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: Number of characters to return + +###### Example + +```sql +> select right('datafusion', 6); ++------------------------------------+ +| right(Utf8("datafusion"),Int64(6)) | ++------------------------------------+ +| fusion | ++------------------------------------+ +``` + +**Related functions**: + +- [left](#left) + +##### `rpad` + +Pads the right side of a string with another string to a specified string length. + +``` +rpad(str, n[, padding_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **n**: String length to pad to. +- **padding_str**: String expression to pad with. Can be a constant, column, or function, and any combination of string operators. _Default is a space._ + +###### Example + +```sql +> select rpad('datafusion', 20, '_-'); ++-----------------------------------------------+ +| rpad(Utf8("datafusion"),Int64(20),Utf8("_-")) | ++-----------------------------------------------+ +| datafusion_-_-_-_-_- | ++-----------------------------------------------+ +``` + +**Related functions**: + +- [lpad](#lpad) + +##### `rtrim` + +Trims the specified trim string from the end of a string. If no trim string is provided, all whitespace is removed from the end of the input string. + +``` +rtrim(str[, trim_str]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **trim_str**: String expression to trim from the end of the input string. Can be a constant, column, or function, and any combination of arithmetic operators. _Default is whitespace characters._ + +###### Example + +```sql +> select rtrim(' datafusion '); ++-------------------------------+ +| rtrim(Utf8(" datafusion ")) | ++-------------------------------+ +| datafusion | ++-------------------------------+ +> select rtrim('___datafusion___', '_'); ++-------------------------------------------+ +| rtrim(Utf8("___datafusion___"),Utf8("_")) | ++-------------------------------------------+ +| ___datafusion | ++-------------------------------------------+ +``` + +**Related functions**: + +- [btrim](#btrim) +- [ltrim](#ltrim) + +##### `split_part` + +Splits a string based on a specified delimiter and returns the substring in the specified position. + +``` +split_part(str, delimiter, pos) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **delimiter**: String or character to split on. +- **pos**: Position of the part to return. + +###### Example + +```sql +> select split_part('1.2.3.4.5', '.', 3); ++--------------------------------------------------+ +| split_part(Utf8("1.2.3.4.5"),Utf8("."),Int64(3)) | ++--------------------------------------------------+ +| 3 | ++--------------------------------------------------+ +``` + +##### `starts_with` + +Tests if a string starts with a substring. + +``` +starts_with(str, substr) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring to test for. + +###### Example + +```sql +> select starts_with('datafusion','data'); ++----------------------------------------------+ +| starts_with(Utf8("datafusion"),Utf8("data")) | ++----------------------------------------------+ +| true | ++----------------------------------------------+ +``` + +##### `strpos` + +Returns the starting position of a specified substring in a string. Positions begin at 1. If the substring does not exist in the string, the function returns 0. + +``` +strpos(str, substr) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring expression to search for. + +###### Example + +```sql +> select strpos('datafusion', 'fus'); ++----------------------------------------+ +| strpos(Utf8("datafusion"),Utf8("fus")) | ++----------------------------------------+ +| 5 | ++----------------------------------------+ +``` + +###### Aliases + +- instr +- position + +##### `substr` + +Extracts a substring of a specified number of characters from a specific starting position in a string. + +``` +substr(str, start_pos[, length]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **start_pos**: Character position to start the substring at. The first character in the string has a position of 1. +- **length**: Number of characters to extract. If not specified, returns the rest of the string after the start position. + +###### Example + +```sql +> select substr('datafusion', 5, 3); ++----------------------------------------------+ +| substr(Utf8("datafusion"),Int64(5),Int64(3)) | ++----------------------------------------------+ +| fus | ++----------------------------------------------+ +``` + +###### Aliases + +- substring + +##### `substr_index` + +Returns the substring from str before count occurrences of the delimiter delim. +If count is positive, everything to the left of the final delimiter (counting from the left) is returned. +If count is negative, everything to the right of the final delimiter (counting from the right) is returned. + +``` +substr_index(str, delim, count) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **delim**: The string to find in str to split str. +- **count**: The number of times to search for the delimiter. Can be either a positive or negative number. + +###### Example + +```sql +> select substr_index('www.apache.org', '.', 1); ++---------------------------------------------------------+ +| substr_index(Utf8("www.apache.org"),Utf8("."),Int64(1)) | ++---------------------------------------------------------+ +| www | ++---------------------------------------------------------+ +> select substr_index('www.apache.org', '.', -1); ++----------------------------------------------------------+ +| substr_index(Utf8("www.apache.org"),Utf8("."),Int64(-1)) | ++----------------------------------------------------------+ +| org | ++----------------------------------------------------------+ +``` + +###### Aliases + +- substring_index + +##### `substring` + +_Alias of [substr](#substr)._ + +##### `substring_index` + +_Alias of [substr_index](#substr-index)._ + +##### `to_hex` + +Converts an integer to a hexadecimal string. + +``` +to_hex(int) +``` + +###### Arguments + +- **int**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select to_hex(12345689); ++-------------------------+ +| to_hex(Int64(12345689)) | ++-------------------------+ +| bc6159 | ++-------------------------+ +``` + +##### `translate` + +Translates characters in a string to specified translation characters. + +``` +translate(str, chars, translation) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **chars**: Characters to translate. +- **translation**: Translation characters. Translation characters replace only characters at the same position in the **chars** string. + +###### Example + +```sql +> select translate('twice', 'wic', 'her'); ++--------------------------------------------------+ +| translate(Utf8("twice"),Utf8("wic"),Utf8("her")) | ++--------------------------------------------------+ +| there | ++--------------------------------------------------+ +``` + +##### `trim` + +_Alias of [btrim](#btrim)._ + +##### `upper` + +Converts a string to upper-case. + +``` +upper(str) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select upper('dataFusion'); ++---------------------------+ +| upper(Utf8("dataFusion")) | ++---------------------------+ +| DATAFUSION | ++---------------------------+ +``` + +**Related functions**: + +- [initcap](#initcap) +- [lower](#lower) + +##### `uuid` + +Returns [`UUID v4`]() string value which is unique per row. + +``` +uuid() +``` + +###### Example + +```sql +> select uuid(); ++--------------------------------------+ +| uuid() | ++--------------------------------------+ +| 6ec17ef8-1934-41cc-8d59-d0c8f9eea1f0 | ++--------------------------------------+ +``` + +### Binary String Functions + +- [decode](#decode) +- [encode](#encode) + +##### `decode` + +Decode binary data from textual representation in string. + +``` +decode(expression, format) +``` + +###### Arguments + +- **expression**: Expression containing encoded string data +- **format**: Same arguments as [encode](#encode) + +**Related functions**: + +- [encode](#encode) + +##### `encode` + +Encode binary data into a textual representation. + +``` +encode(expression, format) +``` + +###### Arguments + +- **expression**: Expression containing string or binary data +- **format**: Supported formats are: `base64`, `hex` + +**Related functions**: + +- [decode](#decode) + +### Regular Expression Functions + +Apache DataFusion uses a [PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions) +regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax) +(minus support for several features including look-around and backreferences). +The following regular expression functions are supported: + +- [regexp_like](#regexp-like) +- [regexp_match](#regexp-match) +- [regexp_replace](#regexp-replace) + +##### `regexp_like` + +Returns true if a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has at least one match in a string, false otherwise. + +``` +regexp_like(str, regexp[, flags]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **regexp**: Regular expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: + - **i**: case-insensitive: letters match both upper and lower case + - **m**: multi-line mode: ^ and $ match begin/end of line + - **s**: allow . to match \n + - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used + - **U**: swap the meaning of x* and x*? + +###### Example + +```sql +select regexp_like('Köln', '[a-zA-Z]ö[a-zA-Z]{2}'); ++--------------------------------------------------------+ +| regexp_like(Utf8("Köln"),Utf8("[a-zA-Z]ö[a-zA-Z]{2}")) | ++--------------------------------------------------------+ +| true | ++--------------------------------------------------------+ +SELECT regexp_like('aBc', '(b|d)', 'i'); ++--------------------------------------------------+ +| regexp_like(Utf8("aBc"),Utf8("(b|d)"),Utf8("i")) | ++--------------------------------------------------+ +| true | ++--------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) + +##### `regexp_match` + +Returns a list of [regular expression](https://docs.rs/regex/latest/regex/#syntax) matches in a string. + +``` +regexp_match(str, regexp[, flags]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **regexp**: Regular expression to match against. + Can be a constant, column, or function. +- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: + - **i**: case-insensitive: letters match both upper and lower case + - **m**: multi-line mode: ^ and $ match begin/end of line + - **s**: allow . to match \n + - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used + - **U**: swap the meaning of x* and x*? + +###### Example + +```sql + > select regexp_match('Köln', '[a-zA-Z]ö[a-zA-Z]{2}'); + +---------------------------------------------------------+ + | regexp_match(Utf8("Köln"),Utf8("[a-zA-Z]ö[a-zA-Z]{2}")) | + +---------------------------------------------------------+ + | [Köln] | + +---------------------------------------------------------+ + SELECT regexp_match('aBc', '(b|d)', 'i'); + +---------------------------------------------------+ + | regexp_match(Utf8("aBc"),Utf8("(b|d)"),Utf8("i")) | + +---------------------------------------------------+ + | [B] | + +---------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) + +##### `regexp_replace` + +Replaces substrings in a string that match a [regular expression](https://docs.rs/regex/latest/regex/#syntax). + +``` +regexp_replace(str, regexp, replacement[, flags]) +``` + +###### Arguments + +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **regexp**: Regular expression to match against. + Can be a constant, column, or function. +- **replacement**: Replacement string expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: +- **g**: (global) Search globally and don't return after the first match +- **i**: case-insensitive: letters match both upper and lower case +- **m**: multi-line mode: ^ and $ match begin/end of line +- **s**: allow . to match \n +- **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used +- **U**: swap the meaning of x* and x*? + +###### Example + +```sql +> select regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g'); ++------------------------------------------------------------------------+ +| regexp_replace(Utf8("foobarbaz"),Utf8("b(..)"),Utf8("X\1Y"),Utf8("g")) | ++------------------------------------------------------------------------+ +| fooXarYXazY | ++------------------------------------------------------------------------+ +SELECT regexp_replace('aBc', '(b|d)', 'Ab\\1a', 'i'); ++-------------------------------------------------------------------+ +| regexp_replace(Utf8("aBc"),Utf8("(b|d)"),Utf8("Ab\1a"),Utf8("i")) | ++-------------------------------------------------------------------+ +| aAbBac | ++-------------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) + +### Time and Date Functions + +- [to_date](#to-date) + +##### `to_date` + +Converts a value to a date (`YYYY-MM-DD`). +Supports strings, integer and double types as input. +Strings are parsed as YYYY-MM-DD (e.g. '2023-07-20') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. +Integers and doubles are interpreted as days since the unix epoch (`1970-01-01T00:00:00Z`). +Returns the corresponding date. + +Note: `to_date` returns Date32, which represents its values as the number of days since unix epoch(`1970-01-01`) stored as signed 32 bit value. The largest supported date value is `9999-12-31`. + +``` +to_date('2017-05-31', '%Y-%m-%d') +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **format_n**: Optional [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) strings to use to parse the expression. Formats will be tried in the order + they appear with the first successful one being returned. If none of the formats successfully parse the expression + an error will be returned. + +###### Example + +```sql +> select to_date('2023-01-31'); ++-----------------------------+ +| to_date(Utf8("2023-01-31")) | ++-----------------------------+ +| 2023-01-31 | ++-----------------------------+ +> select to_date('2023/01/31', '%Y-%m-%d', '%Y/%m/%d'); ++---------------------------------------------------------------+ +| to_date(Utf8("2023/01/31"),Utf8("%Y-%m-%d"),Utf8("%Y/%m/%d")) | ++---------------------------------------------------------------+ +| 2023-01-31 | ++---------------------------------------------------------------+ +``` + +Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs) + +### Struct Functions + +- [named_struct](#named-struct) +- [row](#row) +- [struct](#struct) + +##### `named_struct` + +Returns an Arrow struct using the specified name and input expressions pairs. + +``` +named_struct(expression1_name, expression1_input[, ..., expression_n_name, expression_n_input]) +``` + +###### Arguments + +- **expression_n_name**: Name of the column field. Must be a constant string. +- **expression_n_input**: Expression to include in the output struct. Can be a constant, column, or function, and any combination of arithmetic or string operators. + +###### Example + +For example, this query converts two columns `a` and `b` to a single column with +a struct type of fields `field_a` and `field_b`: + +```sql +> select * from t; ++---+---+ +| a | b | ++---+---+ +| 1 | 2 | +| 3 | 4 | ++---+---+ +> select named_struct('field_a', a, 'field_b', b) from t; ++-------------------------------------------------------+ +| named_struct(Utf8("field_a"),t.a,Utf8("field_b"),t.b) | ++-------------------------------------------------------+ +| {field_a: 1, field_b: 2} | +| {field_a: 3, field_b: 4} | ++-------------------------------------------------------+ +``` + +##### `row` + +_Alias of [struct](#struct)._ + +##### `struct` + +Returns an Arrow struct using the specified input expressions optionally named. +Fields in the returned struct use the optional name or the `cN` naming convention. +For example: `c0`, `c1`, `c2`, etc. + +``` +struct(expression1[, ..., expression_n]) +``` + +###### Arguments + +- **expression1, expression_n**: Expression to include in the output struct. Can be a constant, column, or function, any combination of arithmetic or string operators. + +###### Example + +For example, this query converts two columns `a` and `b` to a single column with +a struct type of fields `field_a` and `c1`: + +```sql +> select * from t; ++---+---+ +| a | b | ++---+---+ +| 1 | 2 | +| 3 | 4 | ++---+---+ + +-- use default names `c0`, `c1` +> select struct(a, b) from t; ++-----------------+ +| struct(t.a,t.b) | ++-----------------+ +| {c0: 1, c1: 2} | +| {c0: 3, c1: 4} | ++-----------------+ + +-- name the first field `field_a` +select struct(a as field_a, b) from t; ++--------------------------------------------------+ +| named_struct(Utf8("field_a"),t.a,Utf8("c1"),t.b) | ++--------------------------------------------------+ +| {field_a: 1, c1: 2} | +| {field_a: 3, c1: 4} | ++--------------------------------------------------+ +``` + +###### Aliases + +- row + +### Hashing Functions + +- [digest](#digest) +- [md5](#md5) +- [sha224](#sha224) +- [sha256](#sha256) +- [sha384](#sha384) +- [sha512](#sha512) + +##### `digest` + +Computes the binary hash of an expression using the specified algorithm. + +``` +digest(expression, algorithm) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **algorithm**: String expression specifying algorithm to use. Must be one of: +- md5 +- sha224 +- sha256 +- sha384 +- sha512 +- blake2s +- blake2b +- blake3 + +###### Example + +```sql +> select digest('foo', 'sha256'); ++------------------------------------------+ +| digest(Utf8("foo"), Utf8("sha256")) | ++------------------------------------------+ +| | ++------------------------------------------+ +``` + +##### `md5` + +Computes an MD5 128-bit checksum for a string expression. + +``` +md5(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select md5('foo'); ++-------------------------------------+ +| md5(Utf8("foo")) | ++-------------------------------------+ +| | ++-------------------------------------+ +``` + +##### `sha224` + +Computes the SHA-224 hash of a binary string. + +``` +sha224(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select sha224('foo'); ++------------------------------------------+ +| sha224(Utf8("foo")) | ++------------------------------------------+ +| | ++------------------------------------------+ +``` + +##### `sha256` + +Computes the SHA-256 hash of a binary string. + +``` +sha256(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select sha256('foo'); ++--------------------------------------+ +| sha256(Utf8("foo")) | ++--------------------------------------+ +| | ++--------------------------------------+ +``` + +##### `sha384` + +Computes the SHA-384 hash of a binary string. + +``` +sha384(expression) +``` + +###### Arguments + +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select sha384('foo'); ++-----------------------------------------+ +| sha384(Utf8("foo")) | ++-----------------------------------------+ +| | ++-----------------------------------------+ +``` + +##### `sha512` + +Computes the SHA-512 hash of a binary string. + +``` +sha512(expression) +``` + +###### Arguments + +- **expression**: String + +###### Example + +```sql +> select sha512('foo'); ++-------------------------------------------+ +| sha512(Utf8("foo")) | ++-------------------------------------------+ +| | ++-------------------------------------------+ +``` + +### Other Functions + +- [arrow_cast](#arrow-cast) +- [arrow_typeof](#arrow-typeof) +- [get_field](#get-field) +- [version](#version) + +##### `arrow_cast` + +Casts a value to a specific Arrow data type. + +``` +arrow_cast(expression, datatype) +``` + +###### Arguments + +- **expression**: Expression to cast. The expression can be a constant, column, or function, and any combination of operators. +- **datatype**: [Arrow data type](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html) name to cast to, as a string. The format is the same as that returned by [`arrow_typeof`] + +###### Example + +```sql +> select arrow_cast(-5, 'Int8') as a, + arrow_cast('foo', 'Dictionary(Int32, Utf8)') as b, + arrow_cast('bar', 'LargeUtf8') as c, + arrow_cast('2023-01-02T12:53:02', 'Timestamp(Microsecond, Some("+08:00"))') as d + ; ++----+-----+-----+---------------------------+ +| a | b | c | d | ++----+-----+-----+---------------------------+ +| -5 | foo | bar | 2023-01-02T12:53:02+08:00 | ++----+-----+-----+---------------------------+ +``` + +##### `arrow_typeof` + +Returns the name of the underlying [Arrow data type](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html) of the expression. + +``` +arrow_typeof(expression) +``` + +###### Arguments + +- **expression**: Expression to evaluate. The expression can be a constant, column, or function, and any combination of operators. + +###### Example + +```sql +> select arrow_typeof('foo'), arrow_typeof(1); ++---------------------------+------------------------+ +| arrow_typeof(Utf8("foo")) | arrow_typeof(Int64(1)) | ++---------------------------+------------------------+ +| Utf8 | Int64 | ++---------------------------+------------------------+ +``` + +##### `get_field` + +Returns a field within a map or a struct with the given key. +Note: most users invoke `get_field` indirectly via field access +syntax such as `my_struct_col['field_name']` which results in a call to +`get_field(my_struct_col, 'field_name')`. + +``` +get_field(expression1, expression2) +``` + +###### Arguments + +- **expression1**: The map or struct to retrieve a field for. +- **expression2**: The field name in the map or struct to retrieve data for. Must evaluate to a string. + +###### Example + +```sql +> create table t (idx varchar, v varchar) as values ('data','fusion'), ('apache', 'arrow'); +> select struct(idx, v) from t as c; ++-------------------------+ +| struct(c.idx,c.v) | ++-------------------------+ +| {c0: data, c1: fusion} | +| {c0: apache, c1: arrow} | ++-------------------------+ +> select get_field((select struct(idx, v) from t), 'c0'); ++-----------------------+ +| struct(t.idx,t.v)[c0] | ++-----------------------+ +| data | +| apache | ++-----------------------+ +> select get_field((select struct(idx, v) from t), 'c1'); ++-----------------------+ +| struct(t.idx,t.v)[c1] | ++-----------------------+ +| fusion | +| arrow | ++-----------------------+ +``` + +##### `version` + +Returns the version of DataFusion. + +``` +version() +``` + +###### Example + +```sql +> select version(); ++--------------------------------------------+ +| version() | ++--------------------------------------------+ +| Apache DataFusion 42.0.0, aarch64 on macos | ++--------------------------------------------+ +``` + + +## Aggregate Functions + +Aggregate functions operate on a set of values to compute a single result. + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. +Please see the [Aggregate Functions (new)](#aggregate-functions-new) page for +the rest of the documentation. + +[automatically created from the codebase]: https://github.com/apache/datafusion/issues/12740 + +### Statistical + +- [covar](#covar) +- [regr_avgx](#regr-avgx) +- [regr_avgy](#regr-avgy) +- [regr_count](#regr-count) +- [regr_intercept](#regr-intercept) +- [regr_r2](#regr-r2) +- [regr_slope](#regr-slope) +- [regr_sxx](#regr-sxx) +- [regr_syy](#regr-syy) +- [regr_sxy](#regr-sxy) + +##### `covar` + +Returns the covariance of a set of number pairs. + +``` +covar(expression1, expression2) +``` + +###### Arguments + +- **expression1**: First expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression2**: Second expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_slope` + +Returns the slope of the linear regression line for non-null pairs in aggregate columns. +Given input column Y and X: regr_slope(Y, X) returns the slope (k in Y = k\*X + b) using minimal RSS fitting. + +``` +regr_slope(expression1, expression2) +``` + +###### Arguments + +- **expression_y**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_avgx` + +Computes the average of the independent variable (input) `expression_x` for the non-null paired data points. + +``` +regr_avgx(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_avgy` + +Computes the average of the dependent variable (output) `expression_y` for the non-null paired data points. + +``` +regr_avgy(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_count` + +Counts the number of non-null paired data points. + +``` +regr_count(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_intercept` + +Computes the y-intercept of the linear regression line. For the equation \(y = kx + b\), this function returns `b`. + +``` +regr_intercept(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_r2` + +Computes the square of the correlation coefficient between the independent and dependent variables. + +``` +regr_r2(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_sxx` + +Computes the sum of squares of the independent variable. + +``` +regr_sxx(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_syy` + +Computes the sum of squares of the dependent variable. + +``` +regr_syy(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### `regr_sxy` + +Computes the sum of products of paired data points. + +``` +regr_sxy(expression_y, expression_x) +``` + +###### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + + +## Window Functions + +A _window function_ performs a calculation across a set of table rows that are somehow related to the current row. + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. +Please see the [Window Functions (new)](#window-functions-new) page for +the rest of the documentation. + +[automatically created from the codebase]: https://github.com/apache/datafusion/issues/12740 + +Window functions are comparable to the type of calculation that can be done with an aggregate function. However, window functions do not cause rows to become grouped into a single output row like non-window aggregate calls would. Instead, the rows retain their separate identities. Behind the scenes, the window function is able to access more than just the current row of the query result + +Here is an example that shows how to compare each employee's salary with the average salary in his or her department: + +```sql +SELECT depname, empno, salary, avg(salary) OVER (PARTITION BY depname) FROM empsalary; + ++-----------+-------+--------+-------------------+ +| depname | empno | salary | avg | ++-----------+-------+--------+-------------------+ +| personnel | 2 | 3900 | 3700.0 | +| personnel | 5 | 3500 | 3700.0 | +| develop | 8 | 6000 | 5020.0 | +| develop | 10 | 5200 | 5020.0 | +| develop | 11 | 5200 | 5020.0 | +| develop | 9 | 4500 | 5020.0 | +| develop | 7 | 4200 | 5020.0 | +| sales | 1 | 5000 | 4866.666666666667 | +| sales | 4 | 4800 | 4866.666666666667 | +| sales | 3 | 4800 | 4866.666666666667 | ++-----------+-------+--------+-------------------+ +``` + +A window function call always contains an OVER clause directly following the window function's name and argument(s). This is what syntactically distinguishes it from a normal function or non-window aggregate. The OVER clause determines exactly how the rows of the query are split up for processing by the window function. The PARTITION BY clause within OVER divides the rows into groups, or partitions, that share the same values of the PARTITION BY expression(s). For each row, the window function is computed across the rows that fall into the same partition as the current row. The previous example showed how to count the average of a column per partition. + +You can also control the order in which rows are processed by window functions using ORDER BY within OVER. (The window ORDER BY does not even have to match the order in which the rows are output.) Here is an example: + +```sql +SELECT depname, empno, salary, + rank() OVER (PARTITION BY depname ORDER BY salary DESC) +FROM empsalary; + ++-----------+-------+--------+--------+ +| depname | empno | salary | rank | ++-----------+-------+--------+--------+ +| personnel | 2 | 3900 | 1 | +| develop | 8 | 6000 | 1 | +| develop | 10 | 5200 | 2 | +| develop | 11 | 5200 | 2 | +| develop | 9 | 4500 | 4 | +| develop | 7 | 4200 | 5 | +| sales | 1 | 5000 | 1 | +| sales | 4 | 4800 | 2 | +| personnel | 5 | 3500 | 2 | +| sales | 3 | 4800 | 2 | ++-----------+-------+--------+--------+ +``` + +There is another important concept associated with window functions: for each row, there is a set of rows within its partition called its window frame. Some window functions act only on the rows of the window frame, rather than of the whole partition. Here is an example of using window frames in queries: + +```sql +SELECT depname, empno, salary, + avg(salary) OVER(ORDER BY salary ASC ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING) AS avg, + min(salary) OVER(ORDER BY empno ASC ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS cum_min +FROM empsalary +ORDER BY empno ASC; + ++-----------+-------+--------+--------------------+---------+ +| depname | empno | salary | avg | cum_min | ++-----------+-------+--------+--------------------+---------+ +| sales | 1 | 5000 | 5000.0 | 5000 | +| personnel | 2 | 3900 | 3866.6666666666665 | 3900 | +| sales | 3 | 4800 | 4700.0 | 3900 | +| sales | 4 | 4800 | 4866.666666666667 | 3900 | +| personnel | 5 | 3500 | 3700.0 | 3500 | +| develop | 7 | 4200 | 4200.0 | 3500 | +| develop | 8 | 6000 | 5600.0 | 3500 | +| develop | 9 | 4500 | 4500.0 | 3500 | +| develop | 10 | 5200 | 5133.333333333333 | 3500 | +| develop | 11 | 5200 | 5466.666666666667 | 3500 | ++-----------+-------+--------+--------------------+---------+ +``` + +When a query involves multiple window functions, it is possible to write out each one with a separate OVER clause, but this is duplicative and error-prone if the same windowing behavior is wanted for several functions. Instead, each windowing behavior can be named in a WINDOW clause and then referenced in OVER. For example: + +```sql +SELECT sum(salary) OVER w, avg(salary) OVER w +FROM empsalary +WINDOW w AS (PARTITION BY depname ORDER BY salary DESC); +``` + +### Syntax + +The syntax for the OVER-clause is + +``` +function([expr]) + OVER( + [PARTITION BY expr[, …]] + [ORDER BY expr [ ASC | DESC ][, …]] + [ frame_clause ] + ) +``` + +where **frame_clause** is one of: + +``` + { RANGE | ROWS | GROUPS } frame_start + { RANGE | ROWS | GROUPS } BETWEEN frame_start AND frame_end +``` + +and **frame_start** and **frame_end** can be one of + +```sql +UNBOUNDED PRECEDING +offset PRECEDING +CURRENT ROW +offset FOLLOWING +UNBOUNDED FOLLOWING +``` + +where **offset** is an non-negative integer. + +RANGE and GROUPS modes require an ORDER BY clause (with RANGE the ORDER BY must specify exactly one column). + +### Aggregate functions + +All [aggregate functions](#aggregate-functions) can be used as window functions. + +### Ranking functions + +- [rank](#rank) +- [dense_rank](#dense-rank) +- [ntile](#ntile) + +##### `rank` + +Rank of the current row with gaps; same as row_number of its first peer. + +```sql +rank() +``` + +##### `dense_rank` + +Rank of the current row without gaps; this function counts peer groups. + +```sql +dense_rank() +``` + +##### `ntile` + +Integer ranging from 1 to the argument value, dividing the partition as equally as possible. + +```sql +ntile(expression) +``` + +###### Arguments + +- **expression**: An integer describing the number groups the partition should be split into + +### Analytical functions + +- [cume_dist](#cume-dist) +- [percent_rank](#percent-rank) +- [lag](#lag) +- [lead](#lead) +- [first_value](#first-value) +- [last_value](#last-value) +- [nth_value](#nth-value) + +##### `cume_dist` + +Relative rank of the current row: (number of rows preceding or peer with current row) / (total rows). + +```sql +cume_dist() +``` + +##### `percent_rank` + +Relative rank of the current row: (rank - 1) / (total rows - 1). + +```sql +percent_rank() +``` + +##### `lag` + +Returns value evaluated at the row that is offset rows before the current row within the partition; if there is no such row, instead return default (which must be of the same type as value). Both offset and default are evaluated with respect to the current row. If omitted, offset defaults to 1 and default to null. + +```sql +lag(expression, offset, default) +``` + +###### Arguments + +- **expression**: Expression to operate on +- **offset**: Integer. Specifies how many rows back the value of _expression_ should be retrieved. Defaults to 1. +- **default**: The default value if the offset is not within the partition. Must be of the same type as _expression_. + +##### `lead` + +Returns value evaluated at the row that is offset rows after the current row within the partition; if there is no such row, instead return default (which must be of the same type as value). Both offset and default are evaluated with respect to the current row. If omitted, offset defaults to 1 and default to null. + +```sql +lead(expression, offset, default) +``` + +###### Arguments + +- **expression**: Expression to operate on +- **offset**: Integer. Specifies how many rows forward the value of _expression_ should be retrieved. Defaults to 1. +- **default**: The default value if the offset is not within the partition. Must be of the same type as _expression_. + +##### `first_value` + +Returns value evaluated at the row that is the first row of the window frame. + +```sql +first_value(expression) +``` + +###### Arguments + +- **expression**: Expression to operate on + +##### `last_value` + +Returns value evaluated at the row that is the last row of the window frame. + +```sql +last_value(expression) +``` + +###### Arguments + +- **expression**: Expression to operate on + +##### `nth_value` + +Returns value evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row. + +```sql +nth_value(expression, n) +``` + +###### Arguments + +- **expression**: The name the column of which nth value to retrieve +- **n**: Integer. Specifies the _n_ in nth diff --git a/versioned_docs/version-0.11/reference/sql/functions/geo.md b/versioned_docs/version-0.11/reference/sql/functions/geo.md new file mode 100644 index 000000000..aa10e45ff --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/functions/geo.md @@ -0,0 +1,455 @@ +--- +description: Lists all geospatial related functions in GreptimeDB, including their usage, examples, and details on geospatial types, geohash, H3, S2, and encodings. +--- + +import TOCInline from '@theme/TOCInline'; + +# Geospatial Functions + +This page lists all geospatial related functions in GreptimeDB. These functions +are enabled when you have `common-function/geo` feature turned on (default: on). + + + +## Geo Types + +Convert data between geospatial types. + +### `wkt_point_from_latlng` + +Convert latitude and longitude to WKT point. + +```sql +SELECT wkt_point_from_latlng(37.76938, -122.3889) AS point; +``` + +## Geohash + +See [more about geohash encoding +algorithms](https://en.wikipedia.org/wiki/Geohash). + +### `geohash` + +Get geohash encoded string from latitude, longitude and resolution. + +```sql +SELECT geohash(37.76938, -122.3889, 11); +``` + +### `geohash_neighbours` + +Get all geohash neighbours for given coordinate and resolution. + +Note that this function returns a String array and it only works on our HTTP +Query API and Postgres channel. + +```sql +SELECT geohash_neighbours(37.76938, -122.3889, 11); +``` + +## H3 + +H3 is a geospatial index algorithm. See [more about h3 +encoding](https://h3geo.org/). + +### `h3_latlng_to_cell` + +Encode coordinate (latitude, longitude) into h3 index at given +resolution. Returns UInt64 representation of the cell. + +```sql +SELECT h3_latlng_to_cell(37.76938, -122.3889, 1); +``` + +### `h3_latlng_to_cell_string` + +Similar to `h3_latlng_to_cell` but returns hex encoding of the cell. + +```sql +h3_latlng_to_cell_string(37.76938, -122.3889, 1); +``` + +### `h3_cell_to_string` + +Convert cell index (UInt64) to its string representation. + +```sql +SELECT h3_cell_to_string(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_string_to_cell` + +Convert hex-encoded cell ID to its UInt64 form + +```sql +h3_string_to_cell(h3_latlng_to_cell_string(37.76938, -122.3889, 8::UInt64)); +``` + +### `h3_cell_center_latlng` + +Returns cell centroid as latitude and longitude. + +Note that this function returns a Float array and it only works on our HTTP +Query API and Postgres channel. + +```sql +SELECT h3_cell_center_latlng(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_cell_resolution` + +Returns resolution for given cell. + +```sql +SELECT h3_cell_resolution(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_cell_base` + +Returns the base cell of given cell. + +```sql +SELECT h3_cell_base(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_cell_is_pentagon` + +Returns true if cell is a pentagon. + +```sql +SELECT h3_cell_is_pentagon(h3_latlng_to_cell(37.76938, -122.3889, 8)); +``` + +### `h3_cell_parent` + +Returns parent cell at given resolution. + +```sql +h3_cell_parent(h3_latlng_to_cell(37.76938, -122.3889, 8), 6); +``` + +### `h3_cell_to_children` + +Returns children cells at given resolution. + +Note that this function returns a UInt64 array and it only works on our HTTP +Query API and Postgres channel. + +```sql +h3_cell_to_children(h3_latlng_to_cell(37.76938, -122.3889, 8), 10); +``` + +### `h3_cell_to_children_size` + +Returns cell children count at given resolution. + +```sql +h3_cell_to_children_size(h3_latlng_to_cell(37.76938, -122.3889, 8), 10); +``` + +### `h3_cell_to_child_pos` + +Return the child position for its parent at given resolution. Position is the +index of child in its children. + +```sql +h3_cell_to_child_pos(h3_latlng_to_cell(37.76938, -122.3889, 8), 6) +``` + +### `h3_child_pos_to_cell` + +Returns the cell at given position of the parent at given resolution. + +Arguments: + +- position +- cell index +- resolution + +```sql +h3_child_pos_to_cell(25, h3_latlng_to_cell(37.76938, -122.3889, 8), 11); +``` + +### `h3_cells_contains` + +Return true if given cells contains cell, or cell's parent. + +Arguments: + +- cell set: it can be int64/uint64/string array, and comma-separated string cell + ID. +- cell index: the cell to test + +```sql +SELECT + h3_cells_contains('86283470fffffff,862834777ffffff, 862834757ffffff, 86283471fffffff, 862834707ffffff', '8b283470d112fff') AS R00, + h3_cells_contains(['86283470fffffff', '862834777ffffff', '862834757ffffff', '86283471fffffff', '862834707ffffff'], '8b283470d112fff') AS R11, + h3_cells_contains([604189641255419903, 604189643000250367, 604189642463379455, 604189641523855359, 604189641121202175], 604189641792290815) AS R21; +``` + +### `h3_grid_disk` + +Returns cells with k distances of given cell. + +Note that this function returns a UInt64 array and it only works on our HTTP +Query API and Postgres channel. + +```sql +h3_grid_disk(h3_latlng_to_cell(37.76938, -122.3889, 8), 3); +``` + +### `h3_grid_disk_distances` + +Returns all cells **within** k distances of given cell. + +Note that this function returns a UInt64 array and it only works on our HTTP +Query API and Postgres channel. + +```sql +h3_grid_disk_distance(h3_latlng_to_cell(37.76938, -122.3889, 8), 3); +``` + +### `h3_grid_distance` + +Returns distance between two cells. + +```sql +SELECT + h3_grid_distance(cell1, cell2) AS distance, +FROM + ( + SELECT + h3_latlng_to_cell(37.76938, -122.3889, 8) AS cell1, + h3_latlng_to_cell(39.634, -104.999, 8) AS cell2 + ); +``` + +### `h3_grid_path_cells` + +Returns path cells between two cells. Note that this function can fail if two +cells are very far apart. + +```sql +SELECT + h3_grid_path_cells(cell1, cell2) AS path_cells, +FROM + ( + SELECT + h3_latlng_to_cell(37.76938, -122.3889, 8) AS cell1, + h3_latlng_to_cell(39.634, -104.999, 8) AS cell2 + ); +``` + +### `h3_distance_sphere_km` + +Returns sphere distance between centroid of two cells, in km + +```sql +SELECT + round(h3_distance_sphere_km(cell1, cell2), 5) AS sphere_distance +FROM + ( + SELECT + h3_string_to_cell('86283082fffffff') AS cell1, + h3_string_to_cell('86283470fffffff') AS cell2 + ); + +``` + +### `h3_distance_degree` + +Returns euclidean distance between centroid of two cells, in degree. + +```sql +SELECT + round(h3_distance_degree(cell1, cell2), 14) AS euclidean_distance +FROM + ( + SELECT + h3_string_to_cell('86283082fffffff') AS cell1, + h3_string_to_cell('86283470fffffff') AS cell2 + ); +``` + +## S2 + +Learn [more about S2 encoding](http://s2geometry.io/). + +### `s2_latlng_to_cell` + +Returns s2 cell index of given coordinate. + +```sql +SELECT s2_latlng_to_cell(37.76938, -122.3889); +``` + +### `s2_cell_to_token` + +Returns string representation of given cell. + +```sql +SELECT s2_cell_to_token(s2_latlng_to_cell(37.76938, -122.3889)); +``` + +### `s2_cell_level` + +Returns s2 level of given cell. + +```sql +SELECT s2_cell_level(s2_latlng_to_cell(37.76938, -122.3889)); +``` + +### `s2_cell_parent` + +Returns parent of given cell at level. + +```sql +SELECT s2_cell_parent(s2_latlng_to_cell(37.76938, -122.3889), 3); +``` + +## Encodings + +### `json_encode_path` + +Encode rows of latitude, longitude in a JSON array, sorted by timestamp. + +Arguments: + +- latitude +- longitude +- timestamp + +Returns a JSON array in string type. Note that the sequence in result coordinate +is [longitude, latitude] to align with GeoJSON spec. + +```sql +SELECT json_encode_path(lat, lon, ts); +``` + +Example output: + +```json +[[-122.3888,37.77001],[-122.3839,37.76928],[-122.3889,37.76938],[-122.382,37.7693]] +``` + +## Spatial Relation + +### `st_contains` + +Test spatial relationship between two objects: contains. + +Arguments: two spatial objects encoded with WKT. + +```sql +SELECT + st_contains(polygon1, p1), + st_contains(polygon2, p1), +FROM + ( + SELECT + wkt_point_from_latlng(37.383287, -122.01325) AS p1, + 'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2, + ); + +``` + +### `st_within` + +Test spatial relationship between two objects: within. + +Arguments: two spatial objects encoded with WKT. + +```sql +SELECT + st_within(p1, polygon1), + st_within(p1, polygon2), + ROM + ( + SELECT + wkt_point_from_latlng(37.383287, -122.01325) AS p1, + 'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2, + ); + +``` + + +### `st_intersects` + +Test spatial relationship between two objects: intersects. + +Arguments: two spatial objects encoded with WKT. + +```sql +SELECT + st_intersects(polygon1, polygon2), + st_intersects(polygon1, polygon3), +FROM + ( + SELECT + 'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2, + 'POLYGON ((-122.089628 37.450332, -122.20535 37.378342, -122.093062 37.36088, -122.044301 37.372886, -122.089628 37.450332))' AS polygon3, + ); + +``` + + +## Spatial Measurement + +### `st_distance` + +Returns WGS84(SRID: 4326) euclidean distance between two geometry object, in +degree. + +Arguments: two spatial objects encoded with WKT. + +```sql +SELECT + st_distance(p1, p2) AS euclidean_dist, + st_distance(p1, polygon1) AS euclidean_dist_pp, +FROM + ( + SELECT + wkt_point_from_latlng(37.76938, -122.3889) AS p1, + wkt_point_from_latlng(38.5216, -121.4247) AS p2, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon1, + ); +``` + +### `st_distance_sphere_m` + +Return great circle distance between two point, in meters. + +Arguments: two spatial objects encoded with WKT. + +```sql +SELECT + st_distance_sphere_m(p1, p2) AS sphere_dist_m, +FROM + ( + SELECT + wkt_point_from_latlng(37.76938, -122.3889) AS p1, + wkt_point_from_latlng(38.5216, -121.4247) AS p2, + ); + +``` + +### `st_area` + +Returns area of given geometry object. + +Arguments: the spatial object encoded with WKT. + +```sql +SELECT + st_area(p1) as area_point, + st_area(polygon1) as area_polygon, +FROM + ( + SELECT + wkt_point_from_latlng(37.76938, -122.3889) AS p1, + 'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon1, + ); +``` diff --git a/versioned_docs/version-0.11/reference/sql/functions/json.md b/versioned_docs/version-0.11/reference/sql/functions/json.md new file mode 100644 index 000000000..3caef7595 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/functions/json.md @@ -0,0 +1,124 @@ +--- +description: Lists and describes JSON functions available in GreptimeDB, including their usage and examples. +--- + +# JSON Functions + +This page lists all json type related functions in GreptimeDB. + + +## Conversion + +Conversion between JSON and other types. + +* `parse_json(string)` to parse a JSON string into a JSON value. Illegal JSON strings will return an error. +* `json_to_string(json)` to convert a JSON value to a string. + +```sql +SELECT json_to_string(parse_json('{"a": 1, "b": 2}')); + ++----------------------------------------------------------+ +| json_to_string(parse_json(Utf8("{\"a\": 1, \"b\": 2}"))) | ++----------------------------------------------------------+ +| {"a":1,"b":2} | ++----------------------------------------------------------+ +``` + +## Extraction + +Extracts values with specific types from JSON values through specific paths. + +* `json_get_bool(json, path)` to extract a boolean value from a JSON value by the path. +* `json_get_int(json, path)` to extract an integer value from a JSON value by the path, while boolean values will be converted to integers. +* `json_get_float(json, path)` to extract a float value from a JSON value by the path, while integer and boolean values will be converted to floats. +* `json_get_string(json, path)` to extract a string value from a JSON value by the path. All valid JSON values will be converted to strings, including null values, objects and arrays. + +`path` is a string that select and extract elements from a json value. The following operators in the path are supported: + +| Operator | Description | Examples | +|--------------------------|--------------------------------------------------------------|--------------------| +| `$` | The root element | `$` | +| `@` | The current element in the filter expression | `$.event?(@ == 1)` | +| `.*` | Selecting all elements in an Object | `$.*` | +| `.` | Selecting element that match the name in an Object | `$.event` | +| `:` | Alias of `.` | `$:event` | +| `[""]` | Alias of `.` | `$["event"]` | +| `[*]` | Selecting all elements in an Array | `$[*]` | +| `[, ..]` | Selecting 0-based `n-th` elements in an Array | `$[1, 2]` | +| `[last - , ..]` | Selecting `n-th` element before the last element in an Array | `$[0, last - 1]` | +| `[ to , ..]` | Selecting all elements of a range in an Array | `$[1 to last - 2]` | +| `?()` | Selecting all elements that matched the filter expression | `$?(@.price < 10)` | + +If the path is invalid, the function will return a NULL value. + +```sql +SELECT json_get_int(parse_json('{"a": {"c": 3}, "b": 2}'), 'a.c'); + ++-----------------------------------------------------------------------+ +| json_get_int(parse_json(Utf8("{"a": {"c": 3}, "b": 2}")),Utf8("a.c")) | ++-----------------------------------------------------------------------+ +| 3 | ++-----------------------------------------------------------------------+ +``` + +## Validation + +Check the type of a JSON value. + +* `json_is_null(json)` to check whether a JSON value is a null value. +* `json_is_bool(json)` to check whether a JSON value is a boolean value. +* `json_is_int(json)` to check whether a JSON value is an integer value. +* `json_is_float(json)` to check whether a JSON value is a float value. +* `json_is_string(json)` to check whether a JSON value is a string value. +* `json_is_object(json)` to check whether a JSON value is an object value. +* `json_is_array(json)` to check whether a JSON value is an array value. + +```sql +SELECT json_is_array(parse_json('[1, 2, 3]')); + ++----------------------------------------------+ +| json_is_array(parse_json(Utf8("[1, 2, 3]"))) | ++----------------------------------------------+ +| 1 | ++----------------------------------------------+ + +SELECT json_is_object(parse_json('1')); + ++---------------------------------------+ +| json_is_object(parse_json(Utf8("1"))) | ++---------------------------------------+ +| 0 | ++---------------------------------------+ +``` + +* `json_path_exists(json, path)` to check whether a path exists in a JSON value. + +If the path is invalid, the function will return an error. + +If the path or the JSON value is `NULL`, the function will return a `NULL` value. + +```sql +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'a'); + ++------------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("a")) | ++------------------------------------------------------------------+ +| 1 | ++------------------------------------------------------------------+ + +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), 'c.d'); + ++--------------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),Utf8("c.d")) | ++--------------------------------------------------------------------+ +| 0 | ++--------------------------------------------------------------------+ + +SELECT json_path_exists(parse_json('{"a": 1, "b": 2}'), NULL); + ++-------------------------------------------------------------+ +| json_path_exists(parse_json(Utf8("{"a": 1, "b": 2}")),NULL) | ++-------------------------------------------------------------+ +| NULL | ++-------------------------------------------------------------+ +``` diff --git a/versioned_docs/version-0.11/reference/sql/functions/overview.md b/versioned_docs/version-0.11/reference/sql/functions/overview.md new file mode 100644 index 000000000..c32979f84 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/functions/overview.md @@ -0,0 +1,244 @@ +--- +description: Provides an overview of the SQL functions available in GreptimeDB, including categories and examples of their usage. +--- + +import TOCInline from '@theme/TOCInline'; + +# Overview + + + + + +## Datafusion Functions + +Since GreptimeDB's query engine is built based on Apache Arrow DataFusion, GreptimeDB inherits all built-in +functions in DataFusion. These functions include: + +* **Aggregate functions**: such as `COUNT`, `SUM`, `MIN`, `MAX`, etc. For a detailed list, please refer to [Aggregate Functions](./df-functions.md#aggregate-functions) +* **Scalar functions**: such as `ABS`, `COS`, `FLOOR`, etc. For a detailed list, please refer to [Scalar Functions](./df-functions.md#scalar-functions) +* **Window functions**: performs a calculation across a set of table rows that are somehow related to the current row. For a detailed list, please refer to [Window Functions](./df-functions.md#window-functions) + +To find all the DataFusion functions, please refer to [DataFusion Functions](./df-functions). + +### `arrow_cast` + +`arrow_cast` function is from DataFusion's [`arrow_cast`](./df-functions.md#arrow-cast). It's illustrated as: + +```sql +arrow_cast(expression, datatype) +``` + +Where the `datatype` can be any valid Arrow data type in this [list](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html). The four timestamp types are: + +- Timestamp(Second, None) +- Timestamp(Millisecond, None) +- Timestamp(Microsecond, None) +- Timestamp(Nanosecond, None) + +(Notice that the `None` means the timestamp is timezone naive) + +## GreptimeDB Functions + +### String Functions + +DataFusion [String Function](./df-functions.md#string-functions).GreptimeDB provides: +* `matches(expression, pattern)` for full text search. + +For details, read the [Query Logs](/user-guide/logs/query-logs.md). + +### Math Functions + +DataFusion [Math Function](./df-functions.md#math-functions). + +GreptimeDB provides: + +* `clamp(value, lower, upper)` to restrict a given value between a lower and upper bound: + +```sql +SELECT CLAMP(10, 0, 1); + ++------------------------------------+ +| clamp(Int64(10),Int64(0),Int64(1)) | ++------------------------------------+ +| 1 | ++------------------------------------+ +``` + +```sql +SELECT CLAMP(0.5, 0, 1) + ++---------------------------------------+ +| clamp(Float64(0.5),Int64(0),Int64(1)) | ++---------------------------------------+ +| 0.5 | ++---------------------------------------+ +``` + +* `mod(x, y)` to get the remainder of a number divided by another number: +```sql +SELECT mod(18, 4); + ++-------------------------+ +| mod(Int64(18),Int64(4)) | ++-------------------------+ +| 2 | ++-------------------------+ +``` + +* `pow(x, y)` to get the value of a number raised to the power of another number: +```sql +SELECT pow(2, 10); + ++-------------------------+ +| pow(Int64(2),Int64(10)) | ++-------------------------+ +| 1024 | ++-------------------------+ +``` + +### Date and Time Functions + +DataFusion [Time and Date Function](./df-functions.md#time-and-date-functions). +GreptimeDB provides: + +* `date_add(expression, interval)` to add an interval value to Timestamp, Date, or DateTime + +```sql +SELECT date_add('2023-12-06'::DATE, '3 month 5 day'); +``` + +``` ++----------------------------------------------------+ +| date_add(Utf8("2023-12-06"),Utf8("3 month 5 day")) | ++----------------------------------------------------+ +| 2024-03-11 | ++----------------------------------------------------+ +``` + +* `date_sub(expression, interval)` to subtract an interval value to Timestamp, Date, or DateTime + +```sql +SELECT date_sub('2023-12-06 07:39:46.222'::TIMESTAMP_MS, INTERVAL '5 day'); +``` + +``` ++-----------------------------------------------------------------------------------------------------------------------------------------+ +| date_sub(arrow_cast(Utf8("2023-12-06 07:39:46.222"),Utf8("Timestamp(Millisecond, None)")),IntervalMonthDayNano("92233720368547758080")) | ++-----------------------------------------------------------------------------------------------------------------------------------------+ +| 2023-12-01 07:39:46.222000 | ++-----------------------------------------------------------------------------------------------------------------------------------------+ +``` + +* `date_format(expression, fmt)` to format Timestamp, Date, or DateTime into string by the format: + +```sql +SELECT date_format('2023-12-06 07:39:46.222'::TIMESTAMP, '%Y-%m-%d %H:%M:%S:%3f'); +``` + +``` ++-----------------------------------------------------------------------------------------------------------------------------+ +| date_format(arrow_cast(Utf8("2023-12-06 07:39:46.222"),Utf8("Timestamp(Millisecond, None)")),Utf8("%Y-%m-%d %H:%M:%S:%3f")) | ++-----------------------------------------------------------------------------------------------------------------------------+ +| 2023-12-06 07:39:46:222 | ++-----------------------------------------------------------------------------------------------------------------------------+ +``` + +Supported specifiers refer to the [chrono::format::strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) module. + +* `to_unixtime(expression)` to convert the expression into the Unix timestamp in seconds. The argument can be integers (Unix timestamp in milliseconds), Timestamp, Date, DateTime, or String. If the argument is the string type, the function will first try to convert it into a DateTime, Timestamp, or Date. + +```sql +select to_unixtime('2023-03-01T06:35:02Z'); +``` + +``` ++-------------------------------------------+ +| to_unixtime(Utf8("2023-03-01T06:35:02Z")) | ++-------------------------------------------+ +| 1677652502 | ++-------------------------------------------+ +``` + +```sql +select to_unixtime('2023-03-01'::date); +``` + +``` ++---------------------------------+ +| to_unixtime(Utf8("2023-03-01")) | ++---------------------------------+ +| 1677628800 | ++---------------------------------+ +``` + +* `timezone()` to retrieve the current session timezone: + +```sql +select timezone(); +``` + +``` ++------------+ +| timezone() | ++------------+ +| UTC | ++------------+ +``` + +### System Functions + +* `isnull(expression)` to check whether an expression is `NULL`: +```sql + SELECT isnull(1); + + +------------------+ +| isnull(Int64(1)) | ++------------------+ +| 0 | ++------------------+ +``` + +```sql +SELECT isnull(NULL); + ++--------------+ +| isnull(NULL) | ++--------------+ +| 1 | ++--------------+ +``` + + +* `build()` retrieves the GreptimeDB build info. +* `version()` retrieves the GreptimeDB version. +* `database()` retrieves the current session database: + +```sql +select database(); + ++------------+ +| database() | ++------------+ +| public | ++------------+ +``` + +### Admin Functions + +GreptimeDB provides `ADMIN` statement to run the administration functions, please refer to [ADMIN](.(/reference/sql/admin.md) reference. + +### JSON Functions + +GreptimeDB provide functions for jsons. [Learn more about these functions](./json.md) + +## Geospatial Functions + +GreptimeDB provide functions for geo-index, trajectory analytics. [Learn more +about these functions](./geo.md) + +## Vector Functions + +GreptimeDB supports vector functions for vector operations, such as distance calculation, similarity measurement, etc. [Learn more about these functions](./vector.md) diff --git a/versioned_docs/version-0.11/reference/sql/functions/vector.md b/versioned_docs/version-0.11/reference/sql/functions/vector.md new file mode 100644 index 000000000..7205585b2 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/functions/vector.md @@ -0,0 +1,114 @@ +--- +description: Lists and describes vector functions available in GreptimeDB, including their usage and examples. +--- + +# Vector Functions + +This page lists all vector-related functions supported in GreptimeDB. Vector functions are primarily used for operations such as distance calculation, similarity measurement, and more. + +## Distance Calculations + +* `vec_l2sq_distance(vec1, vec2)`: Computes the squared L2 distance between two vectors. +* `vec_cos_distance(vec1, vec2)`: Computes the cosine distance between two vectors. +* `vec_dot_product(vec1, vec2)`: Computes the dot product of two vectors. + +These functions accept vector values as parameters. You can use the `parse_vec` function to convert a string into a vector value, such as `parse_vec('[1.0, 2.0, 3.0]')`. Also, vector strings (e.g., `[1.0, 2.0, 3.0]`) can be used directly and will be automatically converted. Regardless of the method used, the dimensionality of the vectors must remain consistent. + +--- + +### `vec_l2sq_distance` + +Calculates the squared Euclidean distance (squared L2 distance) between two vectors. L2 distance is the straight-line distance between two points in geometric space. This function returns the squared value to improve computational efficiency. + +Example: + +```sql +SELECT vec_l2sq_distance(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')); +``` + +Or + +```sql +SELECT vec_l2sq_distance('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]'); +``` + + +Details: + +* Parameters are two vectors with consistent dimensions. +* Output: A scalar value of type `Float32`. + +--- + +### `cos_distance` + +Calculates the cosine distance between two vectors. Cosine distance measures the cosine of the angle between two vectors and is used to quantify similarity. + +Example: + +```sql +SELECT vec_cos_distance(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')); +``` + +Or + +```sql +SELECT vec_cos_distance('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]'); +``` + +Details: + +* Parameters are two vectors with consistent dimensions. +* Output: A scalar value of type `Float32`. + +--- + +### `dot_product` + +Computes the dot product of two vectors. The dot product is the sum of the element-wise multiplications of two vectors. It is commonly used to measure similarity or for linear transformations in machine learning. + +Example: + +```sql +SELECT vec_dot_product(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')); +``` + +Or + +```sql +SELECT vec_dot_product('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]'); +``` + +Details: + +* Parameters are two vectors with consistent dimensions. +* Output: A scalar value of type `Float32`. + +## Conversion Functions + +When dealing with vector data in the database, GreptimeDB provides convenient functions for converting between strings and vector values. + +### `parse_vec` + +Converts a string to a vector value. The string must be enclosed in square brackets `[]` and contain elements of type `Float32`, separated by commas. + +Example: + +```sql +CREATE TABLE vectors ( + ts TIMESTAMP, + vec_col VECTOR(3) +); + +INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:01', parse_vec('[1.0, 2.0, 3.0]')); +``` + +### `vec_to_string` + +Converts a vector object to a string. The converted string format is `[, , ...]`. + +Example: + +```sql +SELECT vec_to_string(vec_col) FROM vectors; +``` diff --git a/versioned_docs/version-0.11/reference/sql/group_by.md b/versioned_docs/version-0.11/reference/sql/group_by.md new file mode 100644 index 000000000..83743f86d --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/group_by.md @@ -0,0 +1,73 @@ +--- +description: Details the SQL GROUP BY clause used to group rows with the same values in specified columns, typically used with aggregate functions like COUNT, SUM, and AVG, with examples. +--- + +# GROUP BY + +The `GROUP BY` clause in SQL is used to group rows that have the same values in one or more columns. +This clause is typically used with aggregate functions such as `COUNT`, `SUM`, `AVG`, etc., to generate +summary reports. + +## Syntax + +The basic syntax of the `GROUP BY` clause is as follows: + +```sql +SELECT column1, column2, ..., aggregate_function(column_name) +FROM table_name +GROUP BY column1, column2, ...; +``` + +The `GROUP BY` clause groups the result set based on the columns specified in the clause. The aggregate +function is applied to each group of rows that have the same values in the specified columns. + +## Examples + +Consider the following table named "system_metrics": + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` + +### Group by Tags + +To get the avg memory_util for each idc, the following SQL query can be used: + +```sql +SELECT idc, AVG(memory_util) +FROM system_metrics +GROUP BY idc; +``` + +The result of the above query would be: + +```sql ++-------+---------------------------------+ +| idc | AVG(system_metrics.memory_util) | ++-------+---------------------------------+ +| idc_b | 66.7 | +| idc_c | 66.8 | +| idc_e | 66.7 | +| idc_a | 40.3 | ++-------+---------------------------------+ +``` + +### Group by Time Interval + +To get the avg memory_util for each day, the following SQL query can be used: + +```sql +SELECT date_trunc('day', ts) as dt, avg(memory_util) +FROM system_metrics +GROUP BY dt +``` + +Please refer to [date_trunc](./functions/overview.md#date_trunc) for more details. diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/build-info.md b/versioned_docs/version-0.11/reference/sql/information-schema/build-info.md new file mode 100644 index 000000000..0dd27509f --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/build-info.md @@ -0,0 +1,32 @@ +--- +description: Contains build information for the SQL information schema, including version details, build date, and other relevant metadata. +--- + +# BUILD_INFO + +The `BUILD_INFO` table provides the system build info: + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM BUILD_INFO; +``` + +The output is as follows: + +```sql ++------------+------------------------------------------+------------------+-----------+-------------+ +| git_branch | git_commit | git_commit_short | git_clean | pkg_version | ++------------+------------------------------------------+------------------+-----------+-------------+ +| | c595a56ac89bef78b19a76aa60d8c6bcac7354a5 | c595a56a | true | 0.9.0 | ++------------+------------------------------------------+------------------+-----------+-------------+ +``` + +The columns in the output: + +* `branch`: the build git branch name. +* `git_commit`: the build commit revision. +* `git_commit_short`: the short commit revision. +* `git_clean`: `true` if the build source directory contains all the committed changes. +* `pkg_version`: the GreptimeDB version. + diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/character-sets.md b/versioned_docs/version-0.11/reference/sql/information-schema/character-sets.md new file mode 100644 index 000000000..ba378901b --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/character-sets.md @@ -0,0 +1,30 @@ +--- +description: Provides details on the character sets available in the SQL information schema, including how to use and manage different character sets. +--- + +# CHARACTER_SETS + +The `CHARACTER_SETS` provides the available character sets that GreptimeDB supports. + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM CHARACTER_SETS; +``` + +The output is as follows: + +```sql ++--------------------+----------------------+---------------+--------+ +| character_set_name | default_collate_name | description | maxlen | ++--------------------+----------------------+---------------+--------+ +| utf8 | utf8_bin | UTF-8 Unicode | 4 | ++--------------------+----------------------+---------------+--------+ +``` + +The columns in the output: + +* `character_set_name`: the name of the character set. +* `default_collate_name`: the default collation name of the character set. +* `description`: the description of the character set. +* `MAXLEN`: the maximum number of bytes required to store one character. \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/cluster-info.md b/versioned_docs/version-0.11/reference/sql/information-schema/cluster-info.md new file mode 100644 index 000000000..b77bbbbb9 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/cluster-info.md @@ -0,0 +1,75 @@ +--- +description: Contains information about the cluster configuration and status within the SQL information schema, including nodes, roles, and other cluster-related details. +--- + +# CLUSTER_INFO + +The `CLUSTER_INFO` table provides the topology information of the cluster. + + +```sql +USE INFORMATION_SCHEMA; + +DESC TABLE CLUSTER_INFO; +``` + +The output is as follows: + +```sql ++-------------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-------------+----------------------+------+------+---------+---------------+ +| peer_id | Int64 | | NO | | FIELD | +| peer_type | String | | NO | | FIELD | +| peer_addr | String | | YES | | FIELD | +| version | String | | NO | | FIELD | +| git_commit | String | | NO | | FIELD | +| start_time | TimestampMillisecond | | YES | | FIELD | +| uptime | String | | YES | | FIELD | +| active_time | String | | YES | | FIELD | ++-------------+----------------------+------+------+---------+---------------+ +``` + + +The columns in table: + +* `peer_id`: the server id of the node. It's always `0` for standalone mode and `-1` for frontends because it doesn't make sense in such cases. +* `peer_type`: the node type, `METASRV`,`FRONTEND`, or `DATANODE` for distributed clusters and `STANDALONE` for standalone deployments. +* `peer_addr`: the GRPC server address of the node. It's always empty for standalone deployments. +* `version`: The build version of the node, such as `0.7.2` etc. +* `git_commit`: The build git commit of the node. +* `start_time`: The node start time. +* `uptime`: The uptime of the node, in the format of duration string `24h 10m 59s 150ms`. +* `active_time`: The duration string in the format of `24h 10m 59s 150ms` since the node's last active time(sending the heartbeats), it's always empty for standalone deployments. + +Query the table: + +```sql +SELECT * FROM CLUSTER_INFO; +``` + +An example output in standalone deployments: + +```sql ++---------+------------+-----------+---------+------------+-------------------------+--------+-------------+ +| peer_id | peer_type | peer_addr | version | git_commit | start_time | uptime | active_time | ++---------+------------+-----------+---------+------------+-------------------------+--------+-------------+ +| 0 | STANDALONE | | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:02.074 | 18ms | | ++---------+------------+-----------+---------+------------+-------------------------+--------+-------------+ +``` + +Another example is from a distributed cluster that has three Datanodes, one Frontend, and one Metasrv. + +```sql ++---------+-----------+----------------+---------+------------+-------------------------+----------+-------------+ +| peer_id | peer_type | peer_addr | version | git_commit | start_time | uptime | active_time | ++---------+-----------+----------------+---------+------------+-------------------------+----------+-------------+ +| 1 | DATANODE | 127.0.0.1:4101 | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:04.791 | 4s 478ms | 1s 467ms | +| 2 | DATANODE | 127.0.0.1:4102 | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:06.098 | 3s 171ms | 162ms | +| 3 | DATANODE | 127.0.0.1:4103 | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:07.425 | 1s 844ms | 1s 839ms | +| -1 | FRONTEND | 127.0.0.1:4001 | 0.7.2 | 86ab3d9 | 2024-04-30T06:40:08.815 | 454ms | 47ms | +| 0 | METASRV | 127.0.0.1:3002 | unknown | unknown | | | | ++---------+-----------+----------------+---------+------------+-------------------------+----------+-------------+ +``` + + diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/collation-character-set-applicability.md b/versioned_docs/version-0.11/reference/sql/information-schema/collation-character-set-applicability.md new file mode 100644 index 000000000..4e23752a8 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/collation-character-set-applicability.md @@ -0,0 +1,28 @@ +--- +description: Describes the applicability of collation character sets within the SQL information schema, detailing how they can be applied and managed. +--- + +# COLLATION_CHARACTER_SET_APPLICABILITY + +The `COLLATION_CHARACTER_SET_APPLICABILITY` table indicates what character set is applicable for what collation. + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM COLLATION_CHARACTER_SET_APPLICABILITY; +``` + +The output is as follows: + +```sql ++----------------+--------------------+ +| collation_name | character_set_name | ++----------------+--------------------+ +| utf8_bin | utf8 | ++----------------+--------------------+ +``` + +The output has these columns: + +* `collation_name`: the collation name. +* `character_set_name`: the name of the character set with which the collation is associated. diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/collations.md b/versioned_docs/version-0.11/reference/sql/information-schema/collations.md new file mode 100644 index 000000000..0b3c0eca1 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/collations.md @@ -0,0 +1,32 @@ +--- +description: Provides information about the collations available in the SQL information schema, including details on how to use and manage them. +--- + +# COLLATIONS + +The `COLLATIONS` provides information about collations for each character set. + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM COLLATIONS; +``` + +The output is as follows: + +```sql ++----------------+--------------------+------+------------+-------------+---------+ +| collation_name | character_set_name | id | is_default | is_compiled | sortlen | ++----------------+--------------------+------+------------+-------------+---------+ +| utf8_bin | utf8 | 1 | Yes | Yes | 1 | ++----------------+--------------------+------+------------+-------------+---------+ +``` + +The table has these columns: + +* `collation_name`: the collation name. +* `character_set_name`: the name of the character set. +* `id`: the collation ID. +* `is_default`: Whether this collation is the default collation of the character set it belongs to. +* `is_compiled`: Whether the character set is compiled into the system. +* `sortlen`: the minimum amount of memory required to sort strings expressed in the character set. \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/columns.md b/versioned_docs/version-0.11/reference/sql/information-schema/columns.md new file mode 100644 index 000000000..19da7455a --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/columns.md @@ -0,0 +1,178 @@ +--- +description: Provides detailed information about columns in tables, including column names, data types, default values, and other attributes. +--- + +# COLUMNS + +The `COLUMNS` provides detailed information about columns in tables. + +```sql +USE INFORMATION_SCHEMA; +DESC COLUMNS; +``` +The output is as follows: + +```sql ++--------------------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------------+--------+------+------+---------+---------------+ +| table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| column_name | String | | NO | | FIELD | +| ordinal_position | Int64 | | NO | | FIELD | +| character_maximum_length | Int64 | YES | | FIELD | +| character_octet_length | Int64 | YES | | FIELD | +| numeric_precision | Int64 | YES | | FIELD | +| numeric_scale | Int64 | YES | | FIELD | +| datetime_precision | Int64 | YES | | FIELD | +| character_set_name | String | | YES | | FIELD | +| collation_name | String | | YES | | FIELD | +| column_key | String | | NO | | FIELD | +| extra | String | | NO | | FIELD | +| privileges | String | | NO | | FIELD | +| generation_expression | String | | NO | | FIELD | +| greptime_data_type | String | | NO | | FIELD | +| data_type | String | | NO | | FIELD | +| semantic_type | String | | NO | | FIELD | +| column_default | String | | YES | | FIELD | +| is_nullable | String | | NO | | FIELD | +| column_type | String | | NO | | FIELD | +| column_comment | String | | YES | | FIELD | +| srs_id | Int64 | | YES | | FIELD | ++--------------------------+--------+------+------+---------+---------------+ +24 rows in set (0.00 sec) +``` +Create a table `public.t1` and query the information in the `COLUMNS` table: + +```sql +CREATE TABLE public.t1 (h STRING, v FLOAT64, ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, PRIMARY KEY(h)); +SELECT * FROM COLUMNS WHERE table_schema='public' AND TABLE_NAME='t1'\G +``` + +The output is as follows: + +```sql +*************************** 1. row *************************** + table_catalog: greptime + table_schema: public + table_name: t1 + column_name: h + ordinal_position: 1 +character_maximum_length: 2147483647 + character_octet_length: 2147483647 + numeric_precision: NULL + numeric_scale: NULL + datetime_precision: NULL + character_set_name: utf8 + collation_name: utf8_bin + column_key: PRI + extra: + privileges: select,insert + generation_expression: + greptime_data_type: String + data_type: string + semantic_type: TAG + column_default: NULL + is_nullable: Yes + column_type: string + column_comment: NULL + srs_id: NULL +*************************** 2. row *************************** + table_catalog: greptime + table_schema: public + table_name: t1 + column_name: v + ordinal_position: 2 +character_maximum_length: NULL + character_octet_length: NULL + numeric_precision: 22 + numeric_scale: NULL + datetime_precision: NULL + character_set_name: NULL + collation_name: NULL + column_key: + extra: + privileges: select,insert + generation_expression: + greptime_data_type: Float64 + data_type: double + semantic_type: FIELD + column_default: NULL + is_nullable: Yes + column_type: double + column_comment: NULL + srs_id: NULL +*************************** 3. row *************************** + table_catalog: greptime + table_schema: public + table_name: t1 + column_name: ts + ordinal_position: 3 +character_maximum_length: NULL + character_octet_length: NULL + numeric_precision: NULL + numeric_scale: NULL + datetime_precision: 3 + character_set_name: NULL + collation_name: NULL + column_key: TIME INDEX + extra: + privileges: select,insert + generation_expression: + greptime_data_type: TimestampMillisecond + data_type: timestamp(3) + semantic_type: TIMESTAMP + column_default: current_timestamp() + is_nullable: No + column_type: timestamp(3) + column_comment: NULL + srs_id: NULL +3 rows in set (0.03 sec) +``` + +The description of columns in the `COLUMNS` table is as follows: + +- `table_catalog`: The name of the catalog to which the table with the column belongs. The value is always `greptime` in OSS project. +- `table_schema`: The name of the database in which the table with the column is located. +- `table_name`: The name of the table with the column. +- `column_name`: The name of the column. +- `ordinal_position`: The position of the column in the table. +- `character_maximum_length`: For string columns, the maximum length in characters. +- `character_octet_length`: For string columns, the maximum length in bytes. +- `numeric_precision`: The precision of the column for numeric data types. +- `numeric_scale`: The scale of the column for numeric data types. +- `datetime_precision`: The fractional seconds precision of the column for datetime data types. +- `character_set_name`: The name of the character set of a string column. +- `collation_name`: The name of the collation of a string column. +- `column_key`: The key type of the column. It can be one of the following: `PRI`, `TIME INDEX`, or an empty string. +- `extra`: Additional information about the column. +- `privileges`: The privilege that the current user has on this column. +- `generation_expression`: For generated columns, this value displays the expression used to calculate the column value. For non-generated columns, the value is empty. +- `greptime_data_type`: The GreptimeDB [data type](/reference/sql/data-types.md) of the column. +- `data_type`: The type of data in the column. +- `semantic_type`: The type of the column. It can be one of the following: `TAG`, `FIELD`, or `TIMESTAMP`. +- `column_default`: The default value of the column. If the explicit default value is `NULL`, or if the column definition does not include the `default` clause, this value is `NULL`. +- `is_nullable`: Whether the column is nullable. If the column can store null values, this value is `YES`; otherwise, it is `NO`. +- `column_type`: The data type of the column. It is the same as the `DATA_TYPE` column. +- `column_comment`: Comments contained in the column definition. +- `srs_id`: The ID of the spatial reference system (SRS) of the column. + +The corresponding `SHOW` statement is as follows: + +```sql +SHOW COLUMNS FROM t1 FROM public; +``` + +The output is as follows: + +```sql ++-------+--------------+------+------------+---------------------+-------+----------------------+ +| Field | Type | Null | Key | Default | Extra | Greptime_type | ++-------+--------------+------+------------+---------------------+-------+----------------------+ +| h | string | Yes | PRI | NULL | | String | +| ts | timestamp(3) | No | TIME INDEX | current_timestamp() | | TimestampMillisecond | +| v | double | Yes | | NULL | | Float64 | ++-------+--------------+------+------------+---------------------+-------+----------------------+ +3 rows in set (0.01 sec) +``` diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/engines.md b/versioned_docs/version-0.11/reference/sql/information-schema/engines.md new file mode 100644 index 000000000..45d6daf94 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/engines.md @@ -0,0 +1,49 @@ +--- +description: Provides information about storage engines, including their support level, comments, and whether they support transactions, XA transactions, and savepoints. +--- + +# ENGINES + +The `ENGINES` table provides information about storage engines. This is particularly useful for checking whether a storage engine is supported, or to see what the default engine is. + +The `ENGINES` table has the following columns: + +* `engine`: the storage engine name. +* `support`: the level of support for the storage engine: + +| Value | Meaning | +| --- | --- | +| `YES` | The engine is supported and is active | +| `DEFAULT` | Like `YES`, plus this is the default engine | +| `NO` | The engine is not supported | +| `DISABLED` | The engine is supported but has been disabled | + +* `comment`: A brief description of the storage engine. +* `transactions`: Whether the storage engine supports transactions. +* `xa`: Whether the storage engine supports XA transactions. +* `savepoints`: Whether the storage engine supports savepoints. + +For example: + +```sql +SELECT * from INFORMATION_SCHEMA.ENGINES\G +``` + +The output is as follows: + +```sql +*************************** 1. row *************************** + engine: mito + support: DEFAULT + comment: Storage engine for time-series data +transactions: NO + xa: NO + savepoints: NO +*************************** 2. row *************************** + engine: metric + support: YES + comment: Storage engine for observability scenarios, which is adept at handling a large number of small tables, making it particularly suitable for cloud-native monitoring +transactions: NO + xa: NO + savepoints: NO +``` diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/flows.md b/versioned_docs/version-0.11/reference/sql/information-schema/flows.md new file mode 100644 index 000000000..b6d349e07 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/flows.md @@ -0,0 +1,39 @@ +--- +description: Provides the flow task information, including flow name, ID, definition, source table IDs, sink table name, and other details. +--- + +# FLOWS +The `Flows` table provides the flow task information. + +```sql +DESC TABLE INFORMATION_SCHEMA.FLOWS; +``` + +```sql + Column | Type | Key | Null | Default | Semantic Type +------------------+--------+-----+------+---------+--------------- + flow_name | String | | NO | | FIELD + flow_id | UInt32 | | NO | | FIELD + table_catalog | String | | NO | | FIELD + flow_definition | String | | NO | | FIELD + comment | String | | YES | | FIELD + expire_after | Int64 | | YES | | FIELD + source_table_ids | String | | YES | | FIELD + sink_table_name | String | | NO | | FIELD + flownode_ids | String | | YES | | FIELD + options | String | | YES | | FIELD +(10 rows) +``` + +The columns in table: + +* `flow_name`: the flow task's name. +* `flow_id`: the flow task's id. +* `table_catalog`: the catalog this flow belongs to, named as `table_catalog` to keep consistent with the `INFORMATION_SCHEMA` standard. +* `flow_definition`: the flow task's definition. It's the SQL statement used to create the flow task. +* `comment`: the comment of the flow task. +* `expire_after`: the expire time of the flow task. +* `source_table_ids`: the source table ids of the flow task. +* `sink_table_name`: the sink table name of the flow task. +* `flownode_ids`: the flownode ids used by the flow task. +* `options`: extra options of the flow task. \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/key-column-usage.md b/versioned_docs/version-0.11/reference/sql/information-schema/key-column-usage.md new file mode 100644 index 000000000..64b5f1bdc --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/key-column-usage.md @@ -0,0 +1,87 @@ +--- +description: Describes the key constraints of the columns, such as the time index key constraint. +--- + +# KEY_COLUMN_USAGE + +The `KEY_COLUMN_USAGE` table describes the key constraints of the columns, such as the time index key constraint. + +```sql +USE INFORMATION_SCHEMA; +DESC KEY_COLUMN_USAGE; +``` + +The output is as follows: + +```sql ++-------------------------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-------------------------------+--------+------+------+---------+---------------+ +| constraint_catalog | String | | NO | | FIELD | +| constraint_schema | String | | NO | | FIELD | +| constraint_name | String | | NO | | FIELD | +| table_catalog | String | | NO | | FIELD | +| real_table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| column_name | String | | NO | | FIELD | +| ordinal_position | UInt32 | | NO | | FIELD | +| position_in_unique_constraint | UInt32 | | YES | | FIELD | +| referenced_table_schema | String | | YES | | FIELD | +| referenced_table_name | String | | YES | | FIELD | +| referenced_column_name | String | | YES | | FIELD | ++-------------------------------+--------+------+------+---------+---------------+ +``` + +```sql +SELECT * FROM key_column_usage WHERE table_schema='public' and table_name='monitor'\G +``` + +```sql +*************************** 1. row *************************** + constraint_catalog: def + constraint_schema: public + constraint_name: TIME INDEX + table_catalog: def + real_table_catalog: greptime + table_schema: public + table_name: monitor + column_name: ts + ordinal_position: 1 +position_in_unique_constraint: NULL + referenced_table_schema: NULL + referenced_table_name: NULL + referenced_column_name: NULL +*************************** 2. row *************************** + constraint_catalog: def + constraint_schema: public + constraint_name: PRIMARY + table_catalog: def + real_table_catalog: greptime + table_schema: public + table_name: monitor + column_name: host + ordinal_position: 1 +position_in_unique_constraint: NULL + referenced_table_schema: NULL + referenced_table_name: NULL + referenced_column_name: NULL +2 rows in set (0.02 sec) +``` + +The description of columns in the `KEY_COLUMN_USAGE` table is as follows: + +- `constraint_catalog`: The name of the catalog to which the constraint belongs. The value is always `def`. +- `constraint_schema`: The name of the database to which the constraint belongs. +- `constraint_name`: The name of the constraint. +- `table_catalog`: The name of the catalog to which the table with the constraint belongs. The value is always `def`. +- `real_table_catalog`: The real name of the catalog to which the table with the constraint belongs. The value is always `greptime`. +- `table_schema`: The name of the database to which the table belongs. +- `table_name`: The name of the table with the constraint. +- `column_name`: The name of the column with the constraint. +- `ordinal_position`: The position of the column in the constraint, rather than in the table. The position number starts from `1`. +- `position_in_unique_constraint`: The unique constraint and the primary key constraint are empty. For foreign key constraints, this column is the position of the referenced table's key. +- `referenced_table_schema`: The name of the schema referenced by the constraint. Currently in GreptimeDB, the value of this column in all constraints is `NULL`, except for the foreign key constraint. +- `referenced_table_name`: The name of the table referenced by the constraint. Currently in GreptimeDB, the value of this column in all constraints is `NULL`, except for the foreign key constraint. +- `referenced_column_name`: The name of the column referenced by the constraint. Currently in TiDB, the value of this column in all constraints is `NULL`, except for the foreign key constraint. + diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/overview.md b/versioned_docs/version-0.11/reference/sql/information-schema/overview.md new file mode 100644 index 000000000..8b77ae0a4 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/overview.md @@ -0,0 +1,63 @@ +--- +description: Provides access to system metadata, such as database or table names, column data types, and INFORMATION_SCHEMA tables for querying GreptimeDB system metadata. +--- + +# Overview + +`INFORMATION_SCHEMA` provides access to system metadata, such as the name of a database or table, the data type of a column, etc. GreptimeDB also provides some custom `INFORMATION_SCHEMA` tables to query metadata about the GreptimeDB system itself, cluster information, and runtime telemetry for example. + +Many `INFORMATION_SCHEMA` tables have a corresponding `SHOW` command. The benefit of querying `INFORMATION_SCHEMA` is that it is possible to join between tables. + +There is still lots of work to do for `INFORMATION_SCHEMA`. The tracking [issue](https://github.com/GreptimeTeam/greptimedb/issues/2931) for `INFORMATION_SCHEMA`. + +## Tables for MySQL compatibility + +| Table Name | Description | +| --- | --- | +| [`CHARACTER_SETS`](./character-sets.md) | provides information about available character sets. | +| `CHECK_CONSTRAINTS`| Not implemented. Returns zero rows. | +| [`COLLATIONS`](./collations.md) | Provides a list of collations that the server supports. | +| [`COLLATION_CHARACTER_SET_APPLICABILITY`](./collation-character-set-applicability.md) | Explains which collations apply to which character sets. | +| [`COLUMNS`](./columns.md) | Provides a list of columns for all tables. | +| `COLUMN_PRIVILEGES` | Not implemented. Returns zero rows. | +| `COLUMN_STATISTICS` | Not supported. | +| [`ENGINES`](./engines.md) | Provides a list of supported storage engines. | +| `EVENTS` | Not implemented. Returns zero rows. | +| `FILES` | Not implemented. Returns zero rows. | +| `GLOBAL_STATUS` | Not implemented. Returns zero rows. | +| `GLOBAL_VARIABLES` | Not supported. | +| [`KEY_COLUMN_USAGE`](./key-column-usage.md) | Describes the key constraints of the columns, such as the primary key, and time index constraint. | +| `OPTIMIZER_TRACE` | Not implemented. Returns zero rows. | +| `PARAMETERS` | Not implemented. Returns zero rows. | +| [`PARTITIONS`](./partitions.md) | Provides a list of table partitions. | +| `PLUGINS` | Not supported.| +| `PROCESSLIST` | Not supported. | +| `PROFILING` | Not implemented. Returns zero rows. | +| `REFERENTIAL_CONSTRAINTS` | Not implemented. Returns zero rows. | +| `ROUTINES` | Not implemented. Returns zero rows. | +| [`SCHEMATA`](./schemata.md) | Provides similar information to `SHOW DATABASES`. | +| `SCHEMA_PRIVILEGES` | Not implemented. Returns zero rows. | +| `SESSION_STATUS` | Not implemented. Returns zero rows. | +| `SESSION_VARIABLES` | Not supported. | +| `STATISTICS` | Not supported. | +| [`TABLES`](./tables.md) | Provides a list of tables that the current user has visibility of. Similar to `SHOW TABLES`. | +| `TABLESPACES` | Not supported. | +| `TABLE_PRIVILEGES` | Not implemented. Returns zero rows. | +| `TRIGGERS` | Not implemented. Returns zero rows. | +| `USER_ATTRIBUTES` | Not supported. | +| `USER_PRIVILEGES` | Not supported.| +| `VARIABLES_INFO` | Not supported. | +| [`VIEWS`](./views.md)| Provides a list of views that the current user has visibility of. Similar to running `SHOW FULL TABLES WHERE table_type = 'VIEW'` | +| [`TABLE_CONSTRAINTS`](./table-constraints.md) | Provides information on primary keys, unique indexes, and foreign keys. | + +## Tables that GreptimeDB provides + +| Table Name | Description | +| --- | --- | +| [`BUILD_INFO`](./build-info.md) | Provides the system build info. | +| [`REGION_PEERS`](./region-peers.md) | Provides details about where regions are stored. | +| [`REGION_STATISTICS`](./region-statistics.md) | Provides details about region statistics info, such as disk size, etc. | +| [`RUNTIME_METRICS`](./runtime-metrics.md)| Provides the system runtime metrics.| +| [`CLUSTER_INFO`](./cluster-info.md)| Provides the topology information of the cluster.| +| [`FLOWS`](./flows.md) | Provides the flow information.| +| [`PROCEDURE_INFO`](./procedure-info.md) | Procedure information.| diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/partitions.md b/versioned_docs/version-0.11/reference/sql/information-schema/partitions.md new file mode 100644 index 000000000..837e01c85 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/partitions.md @@ -0,0 +1,163 @@ +--- +description: Provides information about partitioned tables, including partition names, methods, expressions, and other details. +--- + +# PARTITIONS + +The `PARTITIONS` table provides information about partitioned tables. + +```sql +USE INFORMATION_SCHEMA; +DESC PARTITIONS; +``` + +The output is as follows: + +```sql ++-------------------------------+----------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-------------------------------+----------+------+------+---------+---------------+ +| table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| partition_name | String | | NO | | FIELD | +| subpartition_name | String | | YES | | FIELD | +| partition_ordinal_position | Int64 | | YES | | FIELD | +| subpartition_ordinal_position | Int64 | | YES | | FIELD | +| partition_method | String | | YES | | FIELD | +| subpartition_method | String | | YES | | FIELD | +| partition_expression | String | | YES | | FIELD | +| subpartition_expression | String | | YES | | FIELD | +| partition_description | String | | YES | | FIELD | +| table_rows | Int64 | | YES | | FIELD | +| avg_row_length | Int64 | | YES | | FIELD | +| data_length | Int64 | | YES | | FIELD | +| max_data_length | Int64 | | YES | | FIELD | +| index_length | Int64 | | YES | | FIELD | +| data_free | Int64 | | YES | | FIELD | +| create_time | DateTime | | YES | | FIELD | +| update_time | DateTime | | YES | | FIELD | +| check_time | DateTime | | YES | | FIELD | +| checksum | Int64 | | YES | | FIELD | +| partition_comment | String | | YES | | FIELD | +| nodegroup | String | | YES | | FIELD | +| tablespace_name | String | | YES | | FIELD | +| greptime_partition_id | UInt64 | | YES | | FIELD | ++-------------------------------+----------+------+------+---------+---------------+ +26 rows in set (0.01 sec) +``` + +Main columns: +* `table_catalog`: The name of the catalog to which the table belongs. This value is always `def`. +* `table_schema`: The name of the schema (database) to which the table belongs. +* `table_name`: The name of the table containing the partition(region). +* `partition_name`: The name of the partition(region). +* `partition_ordinal_position`: All partitions are indexed in the same order as they are defined, with 1 being the number assigned to the first partition. +* `partition_method`: This value is always `RANGE`, GreptimeDB only supports range partitioning. +* `partition_expression`: The expression of this partition. +* `create_time`: The time that the partition was created. +* `greptime_partition_id`: GreptimeDB extended field, it's the Region Id. + +For example, create a partitioned table: + +```sql +CREATE TABLE public.test_p ( + a INT PRIMARY KEY, + b STRING, + ts TIMESTAMP TIME INDEX, +) +PARTITION ON COLUMNS (a) ( + a < 10, + a >= 10 AND a < 20, + a >= 20 +); + +--- Query the partitions of the table -- +SELECT * FROM PARTITIONS WHERE table_schema='public' AND table_name='test_p'\G +``` + +Outputs: + +```sql +*************************** 1. row *************************** + table_catalog: greptime + table_schema: public + table_name: test_p + partition_name: p0 + subpartition_name: NULL + partition_ordinal_position: 1 +subpartition_ordinal_position: NULL + partition_method: RANGE + subpartition_method: NULL + partition_expression: (a) VALUES LESS THAN (PartitionExpr { lhs: Column("a"), op: Lt, rhs: Value(Int32(10)) }) + subpartition_expression: NULL + partition_description: NULL + table_rows: NULL + avg_row_length: NULL + data_length: NULL + max_data_length: NULL + index_length: NULL + data_free: NULL + create_time: 2024-04-01 10:49:49.468000 + update_time: NULL + check_time: NULL + checksum: NULL + partition_comment: NULL + nodegroup: NULL + tablespace_name: NULL + greptime_partition_id: 4453881085952 +*************************** 2. row *************************** + table_catalog: greptime + table_schema: public + table_name: test_p + partition_name: p1 + subpartition_name: NULL + partition_ordinal_position: 2 +subpartition_ordinal_position: NULL + partition_method: RANGE + subpartition_method: NULL + partition_expression: (a) VALUES LESS THAN (PartitionExpr { lhs: Column("a"), op: GtEq, rhs: Value(Int32(20)) }) + subpartition_expression: NULL + partition_description: NULL + table_rows: NULL + avg_row_length: NULL + data_length: NULL + max_data_length: NULL + index_length: NULL + data_free: NULL + create_time: 2024-04-01 10:49:49.468000 + update_time: NULL + check_time: NULL + checksum: NULL + partition_comment: NULL + nodegroup: NULL + tablespace_name: NULL + greptime_partition_id: 4453881085954 +*************************** 3. row *************************** + table_catalog: greptime + table_schema: public + table_name: test_p + partition_name: p2 + subpartition_name: NULL + partition_ordinal_position: 3 +subpartition_ordinal_position: NULL + partition_method: RANGE + subpartition_method: NULL + partition_expression: (a) VALUES LESS THAN (PartitionExpr { lhs: Expr(PartitionExpr { lhs: Column("a"), op: Gt, rhs: Value(Int32(10)) }), op: And, rhs: Expr(PartitionExpr { lhs: Column("a"), op: Lt, rhs: Value(Int32(20)) }) }) + subpartition_expression: NULL + partition_description: NULL + table_rows: NULL + avg_row_length: NULL + data_length: NULL + max_data_length: NULL + index_length: NULL + data_free: NULL + create_time: 2024-04-01 10:49:49.468000 + update_time: NULL + check_time: NULL + checksum: NULL + partition_comment: NULL + nodegroup: NULL + tablespace_name: NULL + greptime_partition_id: 4453881085953 +``` diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/procedure-info.md b/versioned_docs/version-0.11/reference/sql/information-schema/procedure-info.md new file mode 100644 index 000000000..4bc901763 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/procedure-info.md @@ -0,0 +1,36 @@ +--- +description: Provides detailed information about various procedures, including procedure ID, type, start and end time, status, and locked keys. +--- + +# PROCEDURE_INFO +The `PROCEDURE_INFO` table provides detailed information about various procedures. + +:::tip NOTE +This table is not available on [GreptimeCloud](https://greptime.cloud/). +::: + +```sql +DESC TABLE INFORMATION_SCHEMA.PROCEDURE_INFO; +``` + +```sql ++----------------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++----------------+----------------------+------+------+---------+---------------+ +| procedure_id | String | | NO | | FIELD | +| procedure_type | String | | NO | | FIELD | +| start_time | TimestampMillisecond | | YES | | FIELD | +| end_time | TimestampMillisecond | | YES | | FIELD | +| status | String | | NO | | FIELD | +| lock_keys | String | | YES | | FIELD | ++----------------+----------------------+------+------+---------+---------------+ +``` + +Fields in the `PROCEDURE_INFO` table are described as follows: + +- `procedure_id`: The ID of the Procedure. +- `procedure_type`: The type of the Procedure. +- `start_time`: Timestamp indicating when the procedure started. +- `end_time`: Timestamp indicating when the procedure ended. +- `status`: Current status of the procedure. +- `lock_keys`: Keys locked by the procedure, if any. \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/region-peers.md b/versioned_docs/version-0.11/reference/sql/information-schema/region-peers.md new file mode 100644 index 000000000..c3ef9bc18 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/region-peers.md @@ -0,0 +1,43 @@ +--- +description: Shows detailed information of a single Region node in GreptimeDB, such as whether it is a learner or leader. +--- + +# REGION_PEERS + +The `REGION_PEERS` table shows detailed information of a single Region node in GreptimeDB, such as whether it is a learner or leader. + +:::tip NOTE +This table is not available on [GreptimeCloud](https://greptime.cloud/). +::: + +```sql +USE INFORMATION_SCHEMA; +DESC REGION_PEERS; +``` + +The output is as follows: + +```sql ++--------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------+--------+------+------+---------+---------------+ +| region_id | UInt64 | | NO | | FIELD | +| peer_id | UInt64 | | YES | | FIELD | +| peer_addr | String | | YES | | FIELD | +| is_leader | String | | YES | | FIELD | +| status | String | | YES | | FIELD | +| down_seconds | Int64 | | YES | | FIELD | ++--------------+--------+------+------+---------+---------------+ +6 rows in set (0.00 sec) +``` + +Fields in the `REGION_PEERS` table are described as follows: + +- `region_id`: The ID of the Region. +- `peer_id`: The ID of the Region peer. +- `peer_addr`: The address of the peer. +- `is_leader`: Whether the peer is the leader. +- `status`: The status of the peer, `ALIVE` or `DOWNGRADED`. + - `ALIVE`: The peer is online. + - `DOWNGRADED`: The Region peer is unavailable (e.g., crashed, network disconnected), or the Region peer was planned to migrate to another peer. +- `down_seconds`: The duration of being offline, in seconds. diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/region-statistics.md b/versioned_docs/version-0.11/reference/sql/information-schema/region-statistics.md new file mode 100644 index 000000000..f01e67e2c --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/region-statistics.md @@ -0,0 +1,68 @@ +--- +description: Provides detailed information about a region's statistics, including the total number of rows, disk size, and more. These statistics are approximate values. +--- + +# REGION_STATISTICS + +The `REGION_STATISTICS` table provides detailed information about a region's statistics, including the total number of rows, disk size, and more. These statistics are approximate values. + +:::tip NOTE +This table is not available on [GreptimeCloud](https://greptime.cloud/). +::: + +```sql +USE INFORMATION_SCHEMA; +DESC REGION_STATISTICS; +``` + +The output is as follows: + +```sql ++---------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++---------------+--------+------+------+---------+---------------+ +| region_id | UInt64 | | NO | | FIELD | +| table_id | UInt32 | | NO | | FIELD | +| region_number | UInt32 | | NO | | FIELD | +| region_rows | UInt64 | | YES | | FIELD | +| disk_size | UInt64 | | YES | | FIELD | +| memtable_size | UInt64 | | YES | | FIELD | +| manifest_size | UInt64 | | YES | | FIELD | +| sst_size | UInt64 | | YES | | FIELD | +| index_size | UInt64 | | YES | | FIELD | +| engine | String | | YES | | FIELD | +| region_role | String | | YES | | FIELD | ++---------------+--------+------+------+---------+---------------+ +``` + +Fields in the `REGION_STATISTICS` table are described as follows: + +- `region_id`: The ID of the Region. +- `table_id`: The ID of the table. +- `region_number`: The number of the region in the table. +- `region_rows`: The number of rows in the region. +- `disk_size`: The total size of data files in the region, including data, index and metadata etc. +- `memtable_size`: The region's total size of memtables. +- `manifest_size`: The region's total size of manifest files. +- `sst_size`: The region's total size of SST files. +- `index_size`: The region's total size of index files. +- `engine`: The engine type of the region, `mito` or `metric`. +- `region_role`: The region's role, `Leader` or `Follower`. + + +Retrieve a table's region statistics information as follows: + +```sql +SELECT r.* FROM REGION_STATISTICS r LEFT JOIN TABLES t on r.table_id = t.table_id \ +WHERE t.table_name = 'system_metrics'; +``` + + +Output: +```sql ++---------------+----------+---------------+-------------+-----------+---------------+---------------+----------+------------+--------+-------------+ +| region_id | table_id | region_number | region_rows | disk_size | memtable_size | manifest_size | sst_size | index_size | engine | region_role | ++---------------+----------+---------------+-------------+-----------+---------------+---------------+----------+------------+--------+-------------+ +| 4398046511104 | 1024 | 0 | 8 | 4922 | 0 | 1338 | 3249 | 335 | mito | Leader | ++---------------+----------+---------------+-------------+-----------+---------------+---------------+----------+------------+--------+-------------+ +``` \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/runtime-metrics.md b/versioned_docs/version-0.11/reference/sql/information-schema/runtime-metrics.md new file mode 100644 index 000000000..e4f579641 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/runtime-metrics.md @@ -0,0 +1,58 @@ +--- +description: Provides information about the `RUNTIME_METRICS` table, which includes system runtime metrics from the `/metrics` HTTP endpoint output in the cluster. +--- + +# RUNTIME_METRICS + +The `RUNTIME_METRICS` table provides system runtime metrics. It includes all metrics from the `/metrics` HTTP endpoint output in the cluster. + +```sql +USE INFORMATION_SCHEMA; + +SELECT * FROM RUNTIME_METRICS; +``` + +Sample output is as follows: + +```sql ++------------------------------------------------------+------------------------+--------------------------------------------------------+---------+-----------+----------------------------+ +| metric_name | value | labels | node | node_type | timestamp | ++------------------------------------------------------+------------------------+--------------------------------------------------------+---------+-----------+----------------------------+ +| greptime_app_version | 1 | short_version=0.7.1, version=greptimedb-main-92a8e86 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_catalog_catalog_count | 1 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_catalog_schema_count | 2 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.005 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.01 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.025 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.05 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.1 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.25 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=0.5 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=1 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=2.5 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=5 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=10 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_bucket | 1 | le=+Inf | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_sum | 0.000290333 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_count | 1 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_catalog_counter | 1 | | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.005 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.01 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.025 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.05 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.1 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.25 | unknown | unknown | 2024-03-27 22:43:12.898000 | +| greptime_meta_create_schema_bucket | 3 | le=0.5 | unknown | unknown | 2024-03-27 22:43:12.898000 | + +... +``` + +The columns in the output: + +* `metric_name`: the metric name. +* `value`: the metric value. +* `labels`: the metric labels and values, separated by `,`. +* `node:` the metric which peer it comes from +* `node_type`: the peer type, such as `datanode`, `frontend` etc. +* `timestamp`: the metric timestamp + diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/schemata.md b/versioned_docs/version-0.11/reference/sql/information-schema/schemata.md new file mode 100644 index 000000000..ba6c20b5c --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/schemata.md @@ -0,0 +1,51 @@ +--- +description: Provides information about databases, including details about each database's catalog, schema name, default character set, collation, and options. +--- + +# SCHEMATA + +The `SCHEMATA` table provides information about databases. The table data is equivalent to the result of the `SHOW DATABASES` statement. + +```sql +USE INFORMATION_SCHEMA; +DESC SCHEMATA; +``` + +The output is as follows: + +```sql ++----------------------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++----------------------------+--------+------+------+---------+---------------+ +| catalog_name | String | | NO | | FIELD | +| schema_name | String | | NO | | FIELD | +| default_character_set_name | String | | NO | | FIELD | +| default_collation_name | String | | NO | | FIELD | +| sql_path | String | | YES | | FIELD | +| options | String | | YES | | FIELD | ++----------------------------+--------+------+------+---------+---------------+ +``` + +```sql +SELECT * FROM SCHEMATA; +``` + +```sql ++--------------+--------------------+----------------------------+------------------------+----------+-------------+ +| catalog_name | schema_name | default_character_set_name | default_collation_name | sql_path | options | ++--------------+--------------------+----------------------------+------------------------+----------+-------------+ +| greptime | greptime_private | utf8 | utf8_bin | NULL | | +| greptime | information_schema | utf8 | utf8_bin | NULL | | +| greptime | public | utf8 | utf8_bin | NULL | | +| greptime | test | utf8 | utf8_bin | NULL | ttl='7days' | ++--------------+--------------------+----------------------------+------------------------+----------+-------------+ +``` + +Fields in the `SCHEMATA` table are described as follows: + +- `catalog_name`: The catalog to which the database belongs. +- `schema_name`: The name of the database. +- `default_character_set_name`: The default character set of the database. +- `default_collation_name`: The default collation of the database. +- `sql_path`: The value of this item is always `NULL`. +- `options`: Extending column in GreptimeDB. The database options. diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/table-constraints.md b/versioned_docs/version-0.11/reference/sql/information-schema/table-constraints.md new file mode 100644 index 000000000..68090f53f --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/table-constraints.md @@ -0,0 +1,59 @@ +--- +description: Describes which tables have constraints, including details about each constraint's catalog, schema, name, type, and enforcement status. +--- + +# TABLE_CONSTRAINTS + +The `TABLE_CONSTRAINTS` table describes which tables have constraints. + +```sql +DESC INFORMATION_SCHEMA.table_constraints; +``` + +```sql ++--------------------+--------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+--------+------+------+---------+---------------+ +| constraint_catalog | String | | NO | | FIELD | +| constraint_schema | String | | NO | | FIELD | +| constraint_name | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| constraint_type | String | | NO | | FIELD | +| enforced | String | | NO | | FIELD | ++--------------------+--------+------+------+---------+---------------+ +``` + +The columns in the table: + +* `CONSTRAINT_CATALOG`: The name of the catalog to which the constraint belongs. This value is always `def`. +* `CONSTRAINT_SCHEMA`: The name of the database to which the constraint belongs. +* `CONSTRAINT_NAME`: The name of the constraint, `TIME INDEX` or `PRIMARY`. +* `TABLE_NAME`: The name of the table. +* `CONSTRAINT_TYPE`: The type of the constraint. The value can be `TIME INDEX` or `PRIMARY KEY`. The `TIME INDEX` and `PRIMARY KEY` information is similar to the execution result of the `SHOW INDEX` statement. +* `enforced`: Doesn't support `CHECK` constraints, the value is always` YES`. + +```sql +select * from INFORMATION_SCHEMA.table_constraints WHERE table_name = 'monitor'\G; +``` + +The output: + +```sql +*************************** 1. row *************************** +constraint_catalog: def + constraint_schema: public + constraint_name: TIME INDEX + table_schema: public + table_name: monitor + constraint_type: TIME INDEX + enforced: YES +*************************** 2. row *************************** +constraint_catalog: def + constraint_schema: public + constraint_name: PRIMARY + table_schema: public + table_name: monitor + constraint_type: PRIMARY KEY + enforced: YES + diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/tables.md b/versioned_docs/version-0.11/reference/sql/information-schema/tables.md new file mode 100644 index 000000000..6b8fbd441 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/tables.md @@ -0,0 +1,110 @@ +--- +description: Provides information about tables in databases, including details about each table's catalog, schema, name, type, and other properties. +--- + +# TABLES + +The `TABLES` table provides information about tables in databases: + +```sql +USE INFORMATION_SCHEMA; +DESC TABLES; +``` + +The output is as follows: + +```sql ++------------------+----------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++------------------+----------+------+------+---------+---------------+ +| table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| table_type | String | | NO | | FIELD | +| table_id | UInt32 | | YES | | FIELD | +| data_length | UInt64 | | YES | | FIELD | +| max_data_length | UInt64 | | YES | | FIELD | +| index_length | UInt64 | | YES | | FIELD | +| max_index_length | UInt64 | | YES | | FIELD | +| avg_row_length | UInt64 | | YES | | FIELD | +| engine | String | | YES | | FIELD | +| version | UInt64 | | YES | | FIELD | +| row_format | String | | YES | | FIELD | +| table_rows | UInt64 | | YES | | FIELD | +| data_free | UInt64 | | YES | | FIELD | +| auto_increment | UInt64 | | YES | | FIELD | +| create_time | DateTime | | YES | | FIELD | +| update_time | DateTime | | YES | | FIELD | +| check_time | DateTime | | YES | | FIELD | +| table_collation | String | | YES | | FIELD | +| checksum | UInt64 | | YES | | FIELD | +| create_options | String | | YES | | FIELD | +| table_comment | String | | YES | | FIELD | +| temporary | String | | YES | | FIELD | ++------------------+----------+------+------+---------+---------------+ +``` + +```sql +SELECT * FROM tables WHERE table_schema='public' AND table_name='monitor'\G +``` + +```sql +*************************** 1. row *************************** + table_catalog: greptime + table_schema: public + table_name: monitor + table_type: BASE TABLE + table_id: 1054 + data_length: 0 + max_data_length: 0 + index_length: 0 +max_index_length: 0 + avg_row_length: 0 + engine: mito + version: 11 + row_format: Fixed + table_rows: 0 + data_free: 0 + auto_increment: 0 + create_time: 2024-07-24 22:06:18.085000 + update_time: NULL + check_time: NULL + table_collation: NULL + checksum: 0 + create_options: + table_comment: NULL + temporary: N +1 row in set (0.01 sec) +``` + +The following statements are equivalent: + +```sql +SELECT table_name FROM INFORMATION_SCHEMA.TABLES + WHERE table_schema = '' + [AND table_name LIKE 'monitor'] + +SHOW TABLES + FROM db_name + [LIKE 'monitor'] +``` + +The description of columns in the `TABLES` table is as follows: + +- `table_catalog`: The catalog to which the table belongs. The value is always `greptime`. +- `table_schema`: The database to which the table belongs. +- `table_name`: The name of the table. +- `table_type`: The type of the table. + - `BASE TABLE` for a table. + - `TEMPORARY` for a temporary result set. + - `VIEW` for a view. +- `table_id`: The ID of the table. +- `data_length`: The total length of the table's SST files in bytes, which is an approximate value. +- `index_length`: The total length of the table's index files in bytes, which is an approximate value. +- `table_rows`: The table's total row number, which is an approximate value. +- `avg_row_length`: The average row length in bytes, which is an approximate value. +- `engine`: The storage engine of the table used. +- `version`: Version. The value is `11` by default. +- `create_time`: The table created timestamp. +- `table_comment`: The table comment. +- Other columns such as `auto_increment`, `row_format` etc. are not supported, just for compatibility with MySQL. GreptimeDB may support some of them in the future. diff --git a/versioned_docs/version-0.11/reference/sql/information-schema/views.md b/versioned_docs/version-0.11/reference/sql/information-schema/views.md new file mode 100644 index 000000000..a5d7716cd --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/information-schema/views.md @@ -0,0 +1,41 @@ +--- +description: Provides a list of views that the current user has visibility of, including details about each view's catalog, schema, name, definition, and other properties. +--- + +# VIEWS + +The `VIEWS` table provides a list of views that the current user has visibility of. + +```sql +DESC TABLE INFORMATION_SCHEMA.VIEWS; +``` + +```sql ++----------------------+---------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++----------------------+---------+------+------+---------+---------------+ +| table_catalog | String | | NO | | FIELD | +| table_schema | String | | NO | | FIELD | +| table_name | String | | NO | | FIELD | +| view_definition | String | | NO | | FIELD | +| check_option | String | | YES | | FIELD | +| is_updatable | Boolean | | YES | | FIELD | +| definer | String | | YES | | FIELD | +| security_type | String | | YES | | FIELD | +| character_set_client | String | | YES | | FIELD | +| collation_connection | String | | YES | | FIELD | ++----------------------+---------+------+------+---------+---------------+ +``` + +The columns in table: + +* `table_catalog`: The name of the catalog to which the view belongs. +* `table_schema`: The name of the database to which the view belongs. +* `table_name`: The view name. +* `view_definition`: The definition of view, which is made by the `SELECT` statement when the view is created. +* `check_option`: Doesn't support, is always `NULL`. +* `is_updatable`: Whether `UPDATE/INSERT/DELETE` is applicable to the view, always `NO`. +* `definer`: The name of the user who creates the view. +* `security_type`: Doesn't support, is always `NULL`. +* `character_set_client`: The value of the `character_set_client` session variable when the view is created, is always `utf8`. +* `collation_connection`: The value of the `collation_connection` session variable when the view is created, is always `utf8_bin`. diff --git a/versioned_docs/version-0.11/reference/sql/insert.md b/versioned_docs/version-0.11/reference/sql/insert.md new file mode 100644 index 000000000..c6bb32d67 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/insert.md @@ -0,0 +1,142 @@ +--- +description: Describes the SQL INSERT statement for adding records to a table in GreptimeDB, including syntax, examples for inserting single and multiple records, default values, binary data, special numeric values, and the INSERT INTO SELECT statement. +--- + +# INSERT + +The `INSERT` statement is used to insert one or more records into a table in the GreptimeDB. + +## `INSERT INTO` Statement + +### Syntax + +The syntax for the INSERT INTO statement is as follows: + +```sql +INSERT INTO table_name (column1, column2, column3, ...) +VALUES (value1, value2, value3, ...); +``` + +In the above syntax, `table_name` is the name of the table into which you want to insert data, +and `column1`, `column2`, `column3`, etc. are the names of the columns in the table. +You can specify the columns in the `INSERT INTO` statement if you want to insert data into specific columns. +If you do not specify the columns, the values will be inserted into all the columns in the table. + +The `VALUES` keyword is followed by a list of values that correspond to the columns in the `INSERT INTO` +statement. The values must be in the same order as the columns. + +The following types of values are supported: + +- The `DEFAULT` keyword specifies that the default value for that column should be inserted. +This is useful when you do not want to explicitly specify values for some columns when inserting records. +It allows the column's default value, as defined in the table schema, to be used instead. +If no default value is defined for the column, the database's default value will be used (often NULL). +- Use hexadecimal literal to insert a literal binary. +- use the `{Value}::{Type}` syntax to cast the special numeric values `Infinity`, `-Infinity`, and `NaN` into the desired numeric type. + +### Examples + +#### Insert Data + +Here is an example of an `INSERT INTO` statement that inserts a record into a table named `system_metrics`: + +```sql +INSERT INTO system_metrics (host, idc, cpu_util, memory_util, disk_util, ts) +VALUES + ("host1", "idc_b", 50.0, 66.7, 40.6, 1667446797462); +``` + +This statement inserts a record with the host "host1", idc "idc_b", cpu_util 50.0, memory_util 66.7, +disk_util 40.6, ts 1667446797462 into the `system_metrics` table. + +You can also use the `INSERT INTO` statement to insert multiple records into a table at the same time. +Here is an example of an `INSERT INTO` statement that inserts multiple records into the `system_metrics` table: + +```sql +INSERT INTO system_metrics (host, idc, cpu_util, memory_util, disk_util, ts) +VALUES + ("host1", "idc_a", 11.8, 10.3, 10.3, 1667446797460), + ("host2", "idc_a", 80.1, 70.3, 90.0, 1667446797461), + ("host1", "idc_c", 50.1, 66.8, 40.8, 1667446797463); +``` + +This statement inserts three records into the `system_metrics` table with the specified values for each column. + +#### Insert Data with Default Values + +The following sql statement use `DEFAULT` keyword to insert the default value for the `cpu_util` column: + +```sql +INSERT INTO system_metrics (host, idc, cpu_util, memory_util, disk_util, ts) +VALUES ("host1", "idc_a", DEFAULT, 10.3, 10.3, 1667446797460); +``` + +#### Insert Binary Data + +When we want to insert binary data which their column datatypes are `blob` or `bytea`: + +```sql +CREATE TABLE test(b BLOB, ts TIMESTAMP TIME INDEX); +``` + +Recommend using the prepared statement, JDBC for example: + +```java + PreparedStatement pstmt = conn.prepareStatement("insert into test values(?,?)"); + pstmt.setBytes(1, "hello".getBytes()); + pstmt.setInt(2, 1687867163); + pstmt.addBatch(); + ...... + pstmt.executeBatch(); +``` + +If we want to insert a literal binary, we can insert a hexadecimal literal: + +```sql +INSERT INTO test VALUES(X'9fad5e9eefdfb449', 1687867163); +-- or -- +INSERT INTO test VALUES(0x9fad5e9eefdfb449', 1687867163); +``` + +#### Insert Special Numeric Values + +Use `{Value}::{Type}` to cast `Infinity`, `-Infinity`, and `NaN` into the desired numeric type: + +```sql +INSERT INTO system_metrics (host, idc, cpu_util, memory_util, disk_util, ts) +VALUES ("host1", "idc_a", 66.6, 'NaN'::double, 'Infinity'::double, 1667446797460); +``` + +## `INSERT INTO SELECT` Statement + +The statement copies data from one table and inserts it into another table. + +### Syntax + +The syntax for the `INSERT INTO SELECT` statement is as follows: + +```sql +INSERT INTO table2 (column1, column2, ...) +SELECT column1, column2, ... +FROM table1; +``` + +In the above syntax, `table1` is the source table from which you want to copy data, and `table2` is the target table +into which the data will be inserted. +`table1` and `table2` should have the same names and data types for the columns that you want to copy. +The `SELECT` statement selects the columns you want to insert from the source +table. If you do not specify the column names in the `INSERT INTO` statement, then the data will be inserted into +all columns in the target table. + +The `INSERT INTO SELECT` statement is useful when you want to copy data from one table to another, for example when +archiving or backing up data. It is more efficient than creating a backup of the entire database and restoring it. + +### Examples + +Here is an example of an `INSERT INTO SELECT` statement: + +```sql +INSERT INTO system_metrics2 (host, idc, cpu_util, memory_util, disk_util, ts) +SELECT host, idc, cpu_util, memory_util, disk_util, ts +FROM system_metrics; +``` diff --git a/versioned_docs/version-0.11/reference/sql/join.md b/versioned_docs/version-0.11/reference/sql/join.md new file mode 100644 index 000000000..84e167ea1 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/join.md @@ -0,0 +1,39 @@ +--- +description: Explains the usage of SQL JOIN clauses to combine rows from multiple tables based on related columns, including INNER JOIN, LEFT JOIN, RIGHT JOIN, and FULL OUTER JOIN, with examples. +--- + +# JOIN + +`JOIN` is used to combine rows from two or more tables based on a related column between them. +It allows you to extract data from multiple tables and present it as a single result set. + +There are several types of JOIN clauses: + +- INNER JOIN: Returns only the rows that have matching values in both tables. +- LEFT JOIN: Returns all the rows from the left table and the matching rows from the right table. +- RIGHT JOIN: Returns all the rows from the right table and the matching rows from the left table. +- FULL OUTER JOIN: Returns all the rows from both tables. + +## Examples + +Here are some examples of using JOIN clauses: + +```sql +-- Select all rows from the system_metrics table and idc_info table where the idc_id matches +SELECT a.* +FROM system_metrics a +JOIN idc_info b +ON a.idc = b.idc_id; + +-- Select all rows from the idc_info table and system_metrics table where the idc_id matches, and include null values for idc_info without any matching system_metrics +SELECT a.* +FROM idc_info a +LEFT JOIN system_metrics b +ON a.idc_id = b.idc; + +-- Select all rows from the system_metrics table and idc_info table where the idc_id matches, and include null values for idc_info without any matching system_metrics +SELECT b.* +FROM system_metrics a +RIGHT JOIN idc_info b +ON a.idc = b.idc_id; +``` diff --git a/versioned_docs/version-0.11/reference/sql/limit.md b/versioned_docs/version-0.11/reference/sql/limit.md new file mode 100644 index 000000000..a50428a3e --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/limit.md @@ -0,0 +1,88 @@ +--- +description: Describes the LIMIT clause in SQL for restricting the number of rows returned by a query, including syntax and examples. +--- + +# LIMIT + +`LIMIT` clause is used to limit the number of rows returned by a query. This clause is particularly +useful when working with large data sets, as it allows for faster query performance by reducing the +amount of data that needs to be processed. + +## Syntax + +The basic syntax of the `LIMIT` clause is as follows: + +```sql +SELECT column1, column2, ... +FROM table_name +LIMIT number_of_rows; +``` + +The number_of_rows parameter specifies the maximum number of rows to be returned. If the value of this parameter is negative, no rows will be returned. + +## Examples + +Consider the following table named "system_metrics": + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` + +To retrieve the top 3 rows by `memory_util`, we can use the`LIMIT` clause: + +```sql +SELECT host, idc, memory_util +FROM system_metrics +ORDER BY memory_util DESC +LIMIT 3; +``` + +The result of the above query would be: + +```sql ++-------+-------+-------------+ +| host | idc | memory_util | ++-------+-------+-------------+ +| host2 | idc_a | 70.3 | +| host1 | idc_c | 66.8 | +| host1 | idc_b | 66.7 | ++-------+-------+-------------+ +``` + +`LIMIT n, m` allows to select the m rows from the result after skipping the first n rows. The `LIMIT m OFFSET n` syntax +is equivalent. + +```sql +SELECT host, idc, memory_util +FROM system_metrics +ORDER BY memory_util DESC +LIMIT 2 OFFSET 1; +``` + +OR + +```sql +SELECT host, idc, memory_util +FROM system_metrics +ORDER BY memory_util DESC +LIMIT 1, 2; +``` + +The result of the above query would be: + +```sql ++-------+-------+-------------+ +| host | idc | memory_util | ++-------+-------+-------------+ +| host1 | idc_c | 66.8 | +| host1 | idc_b | 66.7 | ++-------+-------+-------------+ +``` diff --git a/versioned_docs/version-0.11/reference/sql/order_by.md b/versioned_docs/version-0.11/reference/sql/order_by.md new file mode 100644 index 000000000..da1a09fbb --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/order_by.md @@ -0,0 +1,79 @@ +--- +description: Details the ORDER BY clause in SQL for sorting data in ascending or descending order based on one or more columns, with syntax and examples. +--- + +# ORDER BY + +The `ORDER BY` clause is used to order the data in ascending or descending order based on one or more columns in the +`SELECT` statement. + +## Syntax + +The basic syntax of the `ORDER BY` clause is as follows: + +```sql +SELECT column1, column2, ... +FROM table_name +ORDER BY column1 [ASC | DESC], column2 [ASC | DESC], ...; +``` + +The `ORDER BY` clause can be used with one or more columns. The ASC keyword is used to sort the data +in ascending order (default), and the DESC keyword is used to sort the data in descending order. + +## Examples + +Consider the following table named "system_metrics": + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` + +To sort the data in ascending order based on the "memory_util" column, the following SQL query can be used: + +```sql +SELECT * FROM system_metrics +ORDER BY memory_util ASC; +``` + +The result of the above query would be: + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` + +To sort the data in descending order based on the "disk_util" column, the following SQL query can be used: + +```sql +SELECT * FROM system_metrics +ORDER BY disk_util DESC; +``` + +The result of the above query would be: + +```sql ++-------+-------+----------+-------------+-----------+---------------------+ +| host | idc | cpu_util | memory_util | disk_util | ts | ++-------+-------+----------+-------------+-----------+---------------------+ +| host2 | idc_a | 80.1 | 70.3 | 90 | 2022-11-03 03:39:57 | +| host1 | idc_c | 50.1 | 66.8 | 40.8 | 2022-11-03 03:39:57 | +| host1 | idc_b | 50 | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_e | NULL | 66.7 | 40.6 | 2022-11-03 03:39:57 | +| host1 | idc_a | 11.8 | 10.3 | 10.3 | 2022-11-03 03:39:57 | ++-------+-------+----------+-------------+-----------+---------------------+ +``` diff --git a/versioned_docs/version-0.11/reference/sql/overview.md b/versioned_docs/version-0.11/reference/sql/overview.md new file mode 100644 index 000000000..f7c552f0b --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/overview.md @@ -0,0 +1,28 @@ +# Overview + +* [Data Types](./data-types) +* [INSERT](./insert.md) +* [CAST](./cast.md) +* [COPY](./copy.md) +* [DROP](./drop.md) +* [SELECT](./select.md) +* [DISTINCT](./distinct.md) +* [WHERE](./where.md) +* [ORDER BY](./order_by.md) +* [GROUP BY](./group_by.md) +* [LIMIT](./limit.md) +* [JOIN](./join.md) +* [RANGE](./range.md) +* [DELETE](./delete.md) +* [SHOW](./show.md) +* [TQL](./tql.md) +* [TRUNCATE](./truncate.md) +* [CREATE](./create.md) +* [DESCRIBE TABLE](./describe_table.md) +* [WITH](./with.md) +* [ALTER](./alter.md) +* [EXPLAIN](./explain.md) +* [Functions](./functions/overview.md) +* [ADMIN](./admin.md) +* [ANSI Compatibility](./compatibility.md) +* [INFORMATION_SCHEMA](./information-schema/overview.md) diff --git a/versioned_docs/version-0.11/reference/sql/range.md b/versioned_docs/version-0.11/reference/sql/range.md new file mode 100644 index 000000000..2013f4f32 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/range.md @@ -0,0 +1,611 @@ +--- +description: Explains range queries in SQL for time series data, including syntax, FILL options, TO options, BY options, ORDER BY in aggregate functions, and nested range expressions. +--- + +# RANGE QUERY + +Querying and aggregating data within a range of time is a common query pattern for time series data, such as the `Range selector` in `PromQL`. GreptimeDB supports Range queries in SQL, which is used to summarize time series data into time chunks and aggregate data on time chunks. As part of the `SELECT` statement, Range query can be flexibly combined with SQL to provide more powerful time series data query capabilities in SQL. + +## Syntax + +Range query uses `Time Index` column as the timeline basis for aggregation. A legal Range query syntax structure is as follows: + +```sql +SELECT + AGGR_FUNCTION(column1, column2,..) RANGE INTERVAL [FILL FILL_OPTION], + ... +FROM table_name + [ WHERE ] +ALIGN INTERVAL [ TO TO_OPTION ] [BY (columna, columnb,..)] [FILL FILL_OPTION] + [ ORDER BY ] +[ LIMIT ]; + +INTERVAL := TIME_INTERVAL | ( INTERVAL expr ) +``` + +- Keyword `ALIGN`, required field, followed by parameter `INTERVAL`, `ALIGN` specifies the step of Range query. + - Subkeyword `TO`, optional field, specifies the time point to which Range query is aligned. For legal `TO_OPTION` parameters, see [TO Option](#to-option). + - Subkeyword `BY`, optional field, followed by parameter `(columna, columnb,..)`, describes the aggregate key. For legal `BY_OPTION` parameters, see [BY Option](#by-option). +- The parameter `INTERVAL` is mainly used to give the length of a period of time. There are two parameter forms: + - Strings based on the `PromQL Time Durations` format (eg: `3h`, `1h30m`). Visit the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations) for a more detailed description of this format. + - `Interval` type. To use the `Interval` type, you need to carry parentheses, (for example: `(INTERVAL '1 year 3 hours 20 minutes')`). Visit [Interval](./data-types.md#interval-type) for a more detailed description of this format. +- `AGGR_FUNCTION(column1, column2,..) RANGE INTERVAL [FILL FILL_OPTION]` is called a Range expression. + - `AGGR_FUNCTION(column1, column2,..)` is an aggregate function that represents the expression that needs to be aggregated. + - Keyword `RANGE`, required field, followed by parameter `INTERVAL` specifies the time range of each data aggregation. + - Keyword `FILL`, optional field, please see [`FILL` Option](#fill-option) for details. + - Range expressions can be combined with other operations to implement more complex queries. For details, see [Nested Range Expressions](#nested-range-expressions). +- `FILL` keyword after `ALIGN`, optional field. See [FILL Option](#fill-option) for details. + +## `FILL` Option + +The `FILL` option specifies the data filling method when there is no data in an aggregated time slot, or the value of the aggregate field is empty. + +The `FILL` keyword can be used after the `RANGE` keyword to indicate the filling method for the Range expression. +The `FILL` keyword can also be used after the `ALIGN` keyword to specify the default filling method for a Range expression +if no fill option is provided. + +For example, in the following SQL code, +the `max(val) RANGE '10s'` Range expression uses the fill option `LINEAR`, while the `min(val) RANGE '10s'` Range expression, +which does not specify a fill option, uses the fill option `PREV` specified after the `ALIGN` keyword. + +```sql +SELECT + ts, + host, + min(val) RANGE '10s', + max(val) RANGE '10s' FILL LINEAR +FROM host_cpu +ALIGN '5s' BY (host) FILL PREV; +``` + +`FILL` has the following filling methods: + +| FILL | DESCRIPTION | +| :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| `NULL` | Fill directly with `NULL` | +| `PREV` | Fill with data from previous point | +| `LINEAR` | Use [linear interpolation](https://en.wikipedia.org/wiki/Linear_interpolation) to fill the data. If an integer type is filled with `LINEAR`, the variable type of the column will be implicitly converted to a floating point type during calculation | +| `X` | Fill in a constant, the data type of the constant must be consistent with the variable type of the Range expression | + +Take the following table as an example: + +```sql ++---------------------+-------+------+ +| ts | host | val | ++---------------------+-------+------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+------+ +``` + +The result of each `FILL` option is as follows: + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FROM host ALIGN '5s'; + ++---------------------+-------+------------------------+ +| ts | host | MIN(host.val) RANGE 5s | ++---------------------+-------+------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+------------------------+ + +``` + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FILL NULL FROM host ALIGN '5s'; + ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 5s FILL NULL | ++---------------------+-------+----------------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:05 | host1 | NULL | +| 1970-01-01 00:00:10 | host1 | NULL | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:05 | host2 | NULL | +| 1970-01-01 00:00:10 | host2 | NULL | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+----------------------------------+ + +``` + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FILL PREV FROM host ALIGN '5s'; + ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 5s FILL PREV | ++---------------------+-------+----------------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:05 | host1 | 0 | +| 1970-01-01 00:00:10 | host1 | 0 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:05 | host2 | 6 | +| 1970-01-01 00:00:10 | host2 | 6 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+----------------------------------+ +``` + + + + + +```sql + +> SELECT ts, host, min(val) RANGE '5s' FILL LINEAR FROM host ALIGN '5s'; + ++---------------------+-------+------------------------------------+ +| ts | host | MIN(host.val) RANGE 5s FILL LINEAR | ++---------------------+-------+------------------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:05 | host1 | 2 | +| 1970-01-01 00:00:10 | host1 | 4 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:05 | host2 | 8 | +| 1970-01-01 00:00:10 | host2 | 10 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+------------------------------------+ +``` + + + + + +```sql [FILL Constant Value 6.0] + +> SELECT ts, host, min(val) RANGE '5s' FILL 6 FROM host ALIGN '5s'; + ++---------------------+-------+-------------------------------+ +| ts | host | MIN(host.val) RANGE 5s FILL 6 | ++---------------------+-------+-------------------------------+ +| 1970-01-01 00:00:00 | host1 | 0 | +| 1970-01-01 00:00:05 | host1 | 6 | +| 1970-01-01 00:00:10 | host1 | 6 | +| 1970-01-01 00:00:15 | host1 | 6 | +| 1970-01-01 00:00:00 | host2 | 6 | +| 1970-01-01 00:00:05 | host2 | 6 | +| 1970-01-01 00:00:10 | host2 | 6 | +| 1970-01-01 00:00:15 | host2 | 12 | ++---------------------+-------+-------------------------------+ +``` + + + + + + + +If there are multiple Range expressions but only one of them specifies the `Fill` option, the other Range expressions will use the `FILL NULL` method to fill in the missing time slots. +The following two SQL statements are equivalent in output: + +```sql +SELECT + ts, + host, + min(val) RANGE '10s', + max(val) RANGE '10s' FILL LINEAR +FROM host_cpu +ALIGN '5s'; +``` + +```sql +SELECT + ts, + host, + min(val) RANGE '10s' FILL NULL, + max(val) RANGE '10s' FILL LINEAR +FROM host_cpu +ALIGN '5s'; +``` + +## `TO` Option + +The `TO` keyword specifies the origin time point to which the range query is aligned. +`TO` option along with `RANGE` option and `ALIGN INTERVAL` determine the time range windows. +Please refer to [Time Range Window](/user-guide/query-data/sql.md#time-range-window) for details. + +The default value of the `TO` option is the current query client timezone. To set the timezone, +please refer to [MySQL client](/user-guide/protocols/mysql.md#time-zone) or [PostgreSQL client](/user-guide/protocols/postgresql.md#time-zone). +Other valid `TO` options are: + +| TO | DESCRIPTION | +| :---------: | :----------------------------------------------------------------------------------: | +| `NOW` | Align to current query time | +| `Timestamp` | Align to a user-specified timestamp, supports timestamp format `RFC3339` / `ISO8601` | + + +Suppose we have a tale `host` with the following data: + +```sql ++---------------------+-------+------+ +| ts | host | val | ++---------------------+-------+------+ +| 2023-01-01 23:00:00 | host1 | 0 | +| 2023-01-02 01:00:00 | host1 | 1 | +| 2023-01-01 23:00:00 | host2 | 2 | +| 2023-01-02 01:00:00 | host2 | 3 | ++---------------------+-------+------+ +``` + +The query results by each `TO` options shown below: + + + + + +```sql + +-- Querying the database timezone using the MySQL protocol, currently in the UTC timezone +> SELECT @@time_zone; + ++-------------+ +| @@time_zone | ++-------------+ +| UTC | ++-------------+ + +-- If we do not specify the `TO` keyword, +-- the timezone will be used as the default origin alignment time. + +> SELECT ts, host, min(val) RANGE '1d' FROM host ALIGN '1d'; + ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 1d FILL NULL | ++---------------------+-------+----------------------------------+ +| 2023-01-01 00:00:00 | host2 | 2 | +| 2023-01-01 00:00:00 | host1 | 0 | +| 2023-01-02 00:00:00 | host2 | 3 | +| 2023-01-02 00:00:00 | host1 | 1 | ++---------------------+-------+----------------------------------+ +``` + + + + + +```sql + +-- If you want to align the origin time to the current time, +-- use the `NOW` keyword. +-- Assume that the current query time is `2023-01-02T09:16:40.503000`. + +> SELECT ts, host, min(val) RANGE '1d' FROM host ALIGN '1d' TO NOW; + ++----------------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 1d FILL NULL | ++----------------------------+-------+----------------------------------+ +| 2023-01-01 09:16:40.503000 | host2 | 2 | +| 2023-01-01 09:16:40.503000 | host1 | 0 | ++----------------------------+-------+----------------------------------+ + +``` + + + + + +```sql + +-- If you want to align the origin time to a specific timestamp, +-- for example, "+08:00" Beijing time on December 1, 2023, +-- you can set the `TO` option to the specific timestamp '2023-01-01T00:00:00+08:00'. + +SELECT ts, host, min(val) RANGE '1d' FROM host ALIGN '1d' TO '2023-01-01T00:00:00+08:00'; + ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 1d FILL NULL | ++---------------------+-------+----------------------------------+ +| 2023-01-01 16:00:00 | host2 | 2 | +| 2023-01-01 16:00:00 | host1 | 0 | ++---------------------+-------+----------------------------------+ + +``` + + + + + +If you want to query data for a specific time range, you can specify the timestamp using the `TO` keyword. +For example, to query the daily minimum value of `val` between `00:45` and `06:45`, +you can use `2023-01-01T00:45:00` as the `TO` option along with a `6h` range. + +```sql +SELECT ts, host, min(val) RANGE '6h' FROM host ALIGN '1d' TO '2023-01-01T00:45:00'; +``` + +```sql ++---------------------+-------+----------------------------------+ +| ts | host | MIN(host.val) RANGE 6h FILL NULL | ++---------------------+-------+----------------------------------+ +| 2023-01-02 00:45:00 | host1 | 1 | +| 2023-01-02 00:45:00 | host2 | 3 | ++---------------------+-------+----------------------------------+ +``` + +## `BY` Option + +`BY` option describes the aggregate key. If this field is not given, the primary key of the table is used as the aggregate key by default. If the table does not specify a primary key, the `BY` keyword cannot be omitted. + +Suppose we have a tale `host` with the following data: + +```sql ++---------------------+-------+------+ +| ts | host | val | ++---------------------+-------+------+ +| 2023-01-01 23:00:00 | host1 | 0 | +| 2023-01-02 01:00:00 | host1 | 1 | +| 2023-01-01 23:00:00 | host2 | 2 | +| 2023-01-02 01:00:00 | host2 | 3 | ++---------------------+-------+------+ +``` + +The following SQL uses `host` as the aggregate key: + +```sql +SELECT + ts, + host, + min(val) RANGE '10s' +FROM host ALIGN '5s' BY (host); +``` + +You can also use the `BY` keyword to declare other columns as the basis for data aggregation. +For example, the following RANGE query uses the string length `length(host)` of the `host` column as the basis for data aggregation. + +```sql +SELECT + ts, + length(host), + min(val) RANGE '10s' +FROM host ALIGN '5s' BY (length(host)); +``` + +Get after running + +```sql ++---------------------+-----------------------------+-----------------------------------+ +| ts | character_length(host.host) | MIN(host.val) RANGE 10s FILL NULL | ++---------------------+-----------------------------+-----------------------------------+ +| 2023-01-01 22:59:55 | 5 | 0 | +| 2023-01-01 23:00:00 | 5 | 0 | +| 2023-01-02 00:59:55 | 5 | 1 | +| 2023-01-02 01:00:00 | 5 | 1 | ++---------------------+-----------------------------+-----------------------------------+ +``` + +You can explicitly use `BY ()`, +which means you do not need to use aggregation keys and aggregate all data into a group. +**However, if you omit the `BY` keyword directly, it means using the primary key of the table as the aggregate key.** + +```sql +SELECT + ts, + min(val) RANGE '10s' +FROM host ALIGN '5s' BY (); +``` + +Get after running + +```sql ++---------------------+-----------------------------------+ +| ts | MIN(host.val) RANGE 10s FILL NULL | ++---------------------+-----------------------------------+ +| 2023-01-01 22:59:55 | 0 | +| 2023-01-01 23:00:00 | 0 | +| 2023-01-02 00:59:55 | 1 | +| 2023-01-02 01:00:00 | 1 | ++---------------------+-----------------------------------+ +``` + +## `ORDER BY` option in aggregate functions + +Range queries support the use of `order by` expressions in the parameters of the `first_value` and `last_value` aggregate functions. By default, the data is sorted in ascending order based on the time index column. + +Take this table as an example: + +```sql ++---------------------+-------+------+-------+ +| ts | host | val | addon | ++---------------------+-------+------+-------+ +| 1970-01-01 00:00:00 | host1 | 0 | 3 | +| 1970-01-01 00:00:01 | host1 | 1 | 2 | +| 1970-01-01 00:00:02 | host1 | 2 | 1 | ++---------------------+-------+------+-------+ +``` + +When the `order by` expression is not specified in the function parameter, the default behavior is to sort the data in ascending order based on the time index column. + +```sql +SELECT ts, first_value(val) RANGE '5s', last_value(val) RANGE '5s' FROM host ALIGN '5s'; +-- Equivalent to +SELECT ts, first_value(val order by ts ASC) RANGE '5s', last_value(val order by ts ASC) RANGE '5s' FROM host ALIGN '5s'; +``` + +Get after query + +```sql ++---------------------+--------------------------------+-------------------------------+ +| ts | FIRST_VALUE(host.val) RANGE 5s | LAST_VALUE(host.val) RANGE 5s | ++---------------------+--------------------------------+-------------------------------+ +| 1970-01-01 00:00:00 | 0 | 2 | ++---------------------+--------------------------------+-------------------------------+ +``` + +You can specify your own sorting rules. For example, the following SQL sorts the data by the `addon` column in ascending order: + +```sql +SELECT ts, first_value(val ORDER BY addon ASC) RANGE '5s', last_value(val ORDER BY addon ASC) RANGE '5s' FROM host ALIGN '5s'; +``` + +Get after query + +```sql ++---------------------+---------------------------------------------------------------------+--------------------------------------------------------------------+ +| ts | FIRST_VALUE(host.val) ORDER BY [host.addon ASC NULLS LAST] RANGE 5s | LAST_VALUE(host.val) ORDER BY [host.addon ASC NULLS LAST] RANGE 5s | ++---------------------+---------------------------------------------------------------------+--------------------------------------------------------------------+ +| 1970-01-01 00:00:00 | 2 | 0 | ++---------------------+---------------------------------------------------------------------+--------------------------------------------------------------------+ +``` + +## Nested Range Expressions + +Range expressions support flexible nesting, and range expressions can be combined with various operations to provide more powerful query capabilities. + +Take the following table as an example: + +```sql ++---------------------+-------+------+ +| ts | host | val | ++---------------------+-------+------+ +| 2023-01-01 08:00:00 | host1 | 1.1 | +| 2023-01-01 08:00:05 | host1 | 2.2 | +| 2023-01-01 08:00:00 | host2 | 3.3 | +| 2023-01-01 08:00:05 | host2 | 4.4 | ++---------------------+-------+------+ +``` + +1. Aggregation functions support calculations both internally and externally： + +```sql +SELECT ts, host, 2.0 * min(val * 2.0) RANGE '10s' FROM host_cpu ALIGN '5s'; +``` + +Get after running + +```sql ++---------------------+-------+-----------------------------------------------------------------+ +| ts | host | Float64(2) * MIN(host_cpu.val * Float64(2)) RANGE 10s FILL NULL | ++---------------------+-------+-----------------------------------------------------------------+ +| 2023-01-01 07:59:55 | host1 | 4.4 | +| 2023-01-01 07:59:55 | host2 | 13.2 | +| 2023-01-01 08:00:00 | host1 | 4.4 | +| 2023-01-01 08:00:00 | host2 | 13.2 | +| 2023-01-01 08:00:05 | host1 | 8.8 | +| 2023-01-01 08:00:05 | host2 | 17.6 | ++---------------------+-------+-----------------------------------------------------------------+ +``` + + +2. Scalar functions are supported both inside and outside aggregate functions: + - `min(round(val)) RANGE '10s'` means that each value is rounded using the `round` function before aggregation + - `round(min(val) RANGE '10s')` means rounding the result of each aggregation using the `round` function + +```sql +SELECT ts, host, min(round(val)) RANGE '10s' FROM host_cpu ALIGN '5s'; +``` +Get after running + +```sql ++---------------------+-------+----------------------------------------------+ +| ts | host | MIN(round(host_cpu.val)) RANGE 10s FILL NULL | ++---------------------+-------+----------------------------------------------+ +| 2023-01-01 07:59:55 | host2 | 3 | +| 2023-01-01 07:59:55 | host1 | 1 | +| 2023-01-01 08:00:00 | host2 | 3 | +| 2023-01-01 08:00:00 | host1 | 1 | +| 2023-01-01 08:00:05 | host2 | 4 | +| 2023-01-01 08:00:05 | host1 | 2 | ++---------------------+-------+----------------------------------------------+ +``` + + +```sql +SELECT ts, host, round(min(val) RANGE '10s') FROM host_cpu ALIGN '5s'; +``` + +Get after running + +```sql ++---------------------+-------+----------------------------------------------+ +| ts | host | round(MIN(host_cpu.val) RANGE 10s FILL NULL) | ++---------------------+-------+----------------------------------------------+ +| 2023-01-01 07:59:55 | host2 | 3 | +| 2023-01-01 07:59:55 | host1 | 1 | +| 2023-01-01 08:00:00 | host2 | 3 | +| 2023-01-01 08:00:00 | host1 | 1 | +| 2023-01-01 08:00:05 | host2 | 4 | +| 2023-01-01 08:00:05 | host1 | 2 | ++---------------------+-------+----------------------------------------------+ +``` + +3. Multiple Range expressions can also evaluate together, and Range expressions support the distributive law. The following two Range query are legal and equivalent: + +```sql +SELECT ts, host, max(val) RANGE '10s' - min(val) RANGE '10s' FROM host_cpu ALIGN '5s'; + +SELECT ts, host, (max(val) - min(val)) RANGE '10s' FROM host_cpu ALIGN '5s'; +``` + +Get after running + +```sql ++---------------------+-------+-------------------------------------------------------------------------------+ +| ts | host | MAX(host_cpu.val) RANGE 10s FILL NULL - MIN(host_cpu.val) RANGE 10s FILL NULL | ++---------------------+-------+-------------------------------------------------------------------------------+ +| 2023-01-01 08:00:05 | host1 | 0 | +| 2023-01-01 08:00:05 | host2 | 0 | +| 2023-01-01 08:00:00 | host1 | 1.1 | +| 2023-01-01 08:00:00 | host2 | 1.1 | +| 2023-01-01 07:59:55 | host1 | 0 | +| 2023-01-01 07:59:55 | host2 | 0 | ++---------------------+-------+-------------------------------------------------------------------------------+ +``` + +But note that the `RANGE` keyword apply to the expression before the `RANGE` keyword. The following Range query is illegal because the `RANGE` keyword apply to the expression `2.0`, not the expression `min(val * 2.0) * 2.0` + +```sql +SELECT ts, host, min(val * 2.0) * 2.0 RANGE '10s' FROM host_cpu ALIGN '5s'; + +ERROR 1815 (HY000): sql parser error: Can't use the RANGE keyword in Expr 2.0 without function +``` + +Expressions can be bracketed, and the `RANGE` keyword is automatically applied to any aggregate functions contained within the brackets: + +```sql +SELECT ts, host, (min(val * 2.0) * 2.0) RANGE '10s' FROM host_cpu ALIGN '5s'; +``` + +After running, we get: + +```sql ++---------------------+-------+-----------------------------------------------------------------+ +| ts | host | MIN(host_cpu.val * Float64(2)) RANGE 10s FILL NULL * Float64(2) | ++---------------------+-------+-----------------------------------------------------------------+ +| 2023-01-01 07:59:55 | host2 | 13.2 | +| 2023-01-01 07:59:55 | host1 | 4.4 | +| 2023-01-01 08:00:00 | host2 | 13.2 | +| 2023-01-01 08:00:00 | host1 | 4.4 | +| 2023-01-01 08:00:05 | host2 | 17.6 | +| 2023-01-01 08:00:05 | host1 | 8.8 | ++---------------------+-------+-----------------------------------------------------------------+ +``` + +Nesting of Range expressions is not allowed. Nested Range queries are illegal: + +```sql +SELECT ts, host, max(min(val) RANGE '10s') RANGE '10s' FROM host_cpu ALIGN '5s'; + +ERROR 1815 (HY000): Range Query: Nest Range Query is not allowed +``` + diff --git a/versioned_docs/version-0.11/reference/sql/select.md b/versioned_docs/version-0.11/reference/sql/select.md new file mode 100644 index 000000000..a4b681afc --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/select.md @@ -0,0 +1,137 @@ +--- +description: Describes the SELECT statement in SQL for retrieving data from tables, including syntax, filtering with WHERE, limiting results with LIMIT, joining tables, and grouping results with GROUP BY. +--- + +# SELECT + +The `SELECT` statement allows you to specify a list of columns and expressions to be selected from +one or more tables. + +## Basic Syntax + +The basic syntax for a `SELECT` statement is as follows: + +```sql +SELECT column1, column2, ... +FROM table_name; +``` + +Here, column1, column2, etc. refer to the names of the columns from which we want to retrieve data, +and table_name refers to the name of the table from which we want to retrieve the data. + +This statement selects all the columns from the table specified in the +`FROM` clause. If you want to select all columns from the table, you can use the asterisk (*) wildcard +character instead of listing individual columns. + +```sql +SELECT * +FROM table_name; +``` + +## Filtering SELECT Statements with WHERE Clause + +The WHERE clause is used to filter the results of a `SELECT` statement based on a specified condition. The +syntax for using WHERE clause is as follows: + +```sql +SELECT column1, column2, ..., columnN +FROM table_name +WHERE condition; +``` + +Here, the condition is an expression that evaluates to either true or false. Only the rows that satisfy the condition will be included in the result set. + +## Examples of WHERE Clause + +```sql +-- Select all rows from the system_metrics table where idc is 'idc0' +SELECT * +FROM system_metrics +WHERE idc = 'idc0'; + +-- Select all rows from the system_metrics table where the idc is 'idc0' or 'idc0' +SELECT * +FROM system_metrics +WHERE idc IN ('idc0', 'idc1'); +``` + +## SELECT Statements with LIMIT Clause + +The `LIMIT` clause is used to limit the number of rows returned by a SELECT statement. The syntax for using +`LIMIT` clause is as follows: + +```sql +SELECT column1, column2, ... +FROM table_name +LIMIT number_of_rows; +``` + +Here, the number_of_rows parameter specifies the maximum number of rows to return. + +## Examples of LIMIT Clause + +Here are some examples of using the `LIMIT` clause: + +```sql +-- Select the first 10 rows from the system_metrics table +SELECT * +FROM system_metrics +LIMIT 10; +``` + +## Joining Tables with SELECT Statements + +The `JOIN` clause is used to combine rows from two or more tables based on a related column between them. The syntax for using `JOIN` clause is as follows: + +```sql +SELECT column1, column2, ... +FROM table1 +JOIN table2 +ON table1.column = table2.column; +``` + +Here, the table1 and table2 are the names of the tables to be joined. The column is the related column between the two tables. + +Please refer to [JOIN](join.md) for more information. + +## Grouping SELECT Statements with GROUP BY Clause + +The `GROUP BY` clause is used to group the rows in a `SELECT` statement based on one or more columns. The syntax for using `GROUP BY` clause is as follows: + +```sql +SELECT column1, column2, ..., aggregate_function(column) +FROM table_name +GROUP BY column1, column2, ...; +``` + +Here, the aggregate_function is a function that performs a calculation on a set of values, such as AVG, COUNT, MAX, MIN, or SUM. The column is the column to group the data by. + +## Examples of GROUP BY Clause + +```sql +-- Select the total number of idc for each idc +SELECT idc, COUNT(host) as host_mun +FROM system_metrics +GROUP BY idc; + +-- Select the idc's average cpu_util +SELECT idc, AVG(cpu_util) as cpu_avg +FROM system_metrics +GROUP BY idc; +``` + +Please refer to [GROUP BY](group_by.md) for more information. + +## Example of RANGE query + +```sql +SELECT + ts, + host, + min(cpu) RANGE '10s', + max(cpu) RANGE '10s' FILL LINEAR +FROM host_cpu +ALIGN '5s' BY (host) FILL PREV; +``` + +Please refer to [RANGE QUERY](range.md) for more information. \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/sql/show.md b/versioned_docs/version-0.11/reference/sql/show.md new file mode 100644 index 000000000..88bbe1af6 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/show.md @@ -0,0 +1,384 @@ +--- +description: Provides information on the SHOW keyword in SQL for displaying database and table details, including various SHOW commands with syntax and examples. +--- + +# SHOW + +The `SHOW` keyword provides database and table information. + +## SHOW DATABASES + +Show all databases: + +```sql +SHOW [FULL] DATABASES; +``` + +```sql ++---------+ +| Schemas | ++---------+ +| public | ++---------+ +1 row in set (0.01 sec) +``` + +Show databases by `LIKE` pattern: + +```sql +SHOW DATABASES LIKE 'p%'; +``` + +Show databases by `where` expr: + +```sql +SHOW DATABASES WHERE Schemas='test_public_schema'; +``` + +Show all databases with options: + +```sql +CREATE DATABASE test WITH(ttl='7d'); +SHOW FULL DATABASES; +``` + +```sql ++--------------------+-------------+ +| Database | Options | ++--------------------+-------------+ +| greptime_private | | +| information_schema | | +| public | | +| test | ttl='7days' | ++--------------------+-------------+ +``` + +## SHOW CREATE DATABASE + +Shows the `CREATE DATABASE` statement that creates the named database: + +```sql +SHOW CREATE DATABASE test; +``` + +```sql ++----------+------------------------------------------------------------+ +| Database | Create Database | ++----------+------------------------------------------------------------+ +| test | CREATE DATABASE IF NOT EXISTS test +WITH( + ttl = '7days' +) | ++----------+------------------------------------------------------------+ +1 row in set (0.01 sec) +``` + +## SHOW TABLES + +Show all tables: + +```sql +SHOW TABLES; +``` + +```sql ++---------+ +| Tables | ++---------+ +| numbers | +| scripts | ++---------+ +2 rows in set (0.00 sec) +``` + +Show tables in the `test` database: + +```sql +SHOW TABLES FROM test; +``` + +Show tables by `like` pattern: + +```sql +SHOW TABLES like '%prometheus%'; +``` + +Show tables by `where` expr: + +```sql +SHOW TABLES FROM test WHERE Tables='numbers'; +``` + +## SHOW FULL TABLES + +```sql +SHOW FULL TABLES [IN | FROM] [DATABASE] [LIKE pattern] [WHERE query] +``` + +It will list all tables and table types in the database: + +```sql +SHOW FULL TABLES; +``` + +```sql ++---------+------------+ +| Tables | Table_type | ++---------+------------+ +| monitor | BASE TABLE | +| numbers | TEMPORARY | ++---------+------------+ +2 rows in set (0.00 sec) +``` + +* `Tables`: the table names. +* `Table_type`: the table types, such as `BASE_TABLE`, `TEMPORARY`, and `VIEW` etc. + +It supports `like` and `where` query too: + +```sql +SHOW FULL TABLES FROM public like '%mo%'; +``` + +```sql ++---------+------------+ +| Tables | Table_type | ++---------+------------+ +| monitor | BASE TABLE | ++---------+------------+ +1 row in set (0.01 sec) +``` + +```sql +SHOW FULL TABLES WHERE Table_type='BASE TABLE'; +``` + +```sql ++---------+------------+ +| Tables | Table_type | ++---------+------------+ +| monitor | BASE TABLE | ++---------+------------+ +1 row in set (0.01 sec) +``` + +## SHOW CREATE TABLE + +Shows the `CREATE TABLE` statement that creates the named table: + +```sql +SHOW CREATE TABLE [table] +``` + +For example: + +```sql +SHOW CREATE TABLE system_metrics; +``` + +```sql ++----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Table | Create Table | ++----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| system_metrics | CREATE TABLE IF NOT EXISTS `system_metrics` ( + `host` STRING NULL, + `idc` STRING NULL, + `cpu_util` DOUBLE NULL, + `memory_util` DOUBLE NULL, + `disk_util` DOUBLE NULL, + `ts` TIMESTAMP(3) NOT NULL DEFAULT current_timestamp(), + TIME INDEX (`ts`), + PRIMARY KEY (`host`, `idc`) +) + +ENGINE=mito +WITH( + regions = 1 +) | ++----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +* `Table`: the table name. +* `Create Table`: The SQL to create the table. + +## SHOW CREATE FLOW + +Shows the `CREATE FLOW` statement that creates the flow task. + +For example: + +```sql +public=> SHOW CREATE FLOW filter_numbers; +``` + +```sql + Flow | Create Flow +----------------+------------------------------------------------------- + filter_numbers | CREATE OR REPLACE FLOW IF NOT EXISTS filter_numbers + + | SINK TO out_num_cnt + + | AS SELECT number FROM numbers_input WHERE number > 10 +(1 row) +``` + +## SHOW FLOWS + +Show all flows: + +```sql +public=> SHOW FLOWS; +``` + +```sql + Flows +---------------- + filter_numbers +(1 row) +``` +also support `LIKE` expression: +```sql +public=> show flows like "filter%"; +``` + +```sql + Flows +---------------- + filter_numbers +(1 row) +``` + +## SHOW CREATE VIEW + +To show the view's definition: + +```sql +SHOW CREATE VIEW cpu_monitor; +``` + +``` ++-------------+--------------------------------------------------------------+ +| View | Create View | ++-------------+--------------------------------------------------------------+ +| cpu_monitor | CREATE VIEW cpu_monitor AS SELECT cpu, host, ts FROM monitor | ++-------------+--------------------------------------------------------------+ +``` + +## SHOW VIEWS + +List all views: + +```sql +SHOW VIEWS; +``` + +```sql ++----------------+ +| Views | ++----------------+ +| cpu_monitor | +| memory_monitor | ++----------------+ +``` + +Of course, it supports `LIKE`: + +```sql +SHOW VIEWS LIKE 'cpu%'; +``` + +```sql ++-------------+ +| Views | ++-------------+ +| cpu_monitor | ++-------------+ +``` + +And `where`: + +```sql +SHOW VIEWS WHERE Views = 'memory_monitor'; +``` + +```sql ++----------------+ +| Views | ++----------------+ +| memory_monitor | ++----------------+ +``` + +## Extensions to SHOW Statements + +Some extensions to `SHOW` statements accompany the implementation of [`INFORMATION_SCHEMA`](/reference/sql/information-schema/overview.md) just like MySQL, they also accept a `WHERE` clause that provides more flexibility in specifying which rows to display. + +GreptimeDB supports some extensions for MySQL compatibility, it's good for tools like [Navicat for MySQL](https://www.navicat.com/en/products/navicat-for-mysql) or [dbeaver](https://dbeaver.io/) to connect GreptimeDB. + +```sql +SHOW CHARACTER SET; +``` + +Output just like the `INFORMATION_SCHEMA.CHARACTER_SETS` table: + +```sql ++---------+---------------+-------------------+--------+ +| Charset | Description | Default collation | Maxlen | ++---------+---------------+-------------------+--------+ +| utf8 | UTF-8 Unicode | utf8_bin | 4 | ++---------+---------------+-------------------+--------+ +``` + +`SHOW COLLATION` for `INFORMATION_SCHEMA.COLLATIONS` table. + +```sql +SHOW INDEX FROM monitor; +``` + +To list all indexes in a table: + +```sql ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression | ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +| monitor | 1 | PRIMARY | 1 | host | A | NULL | NULL | NULL | YES | greptime-inverted-index-v1 | | | YES | NULL | +| monitor | 1 | TIME INDEX | 1 | ts | A | NULL | NULL | NULL | NO | greptime-inverted-index-v1 | | | YES | NULL | ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +``` + +Which is the extension of `INFORMATION_SCHEMA.TABLE_CONSTRAINTS`. + +List all the columns in a table: + +```sql +SHOW COLUMNS FROM monitor; +``` + +Output just like `INFORMATION_SCHEMA.COLUMNS`: + +```sql ++--------+--------------+------+------------+---------------------+-------+----------------------+ +| Field | Type | Null | Key | Default | Extra | Greptime_type | ++--------+--------------+------+------------+---------------------+-------+----------------------+ +| cpu | double | Yes | | 0 | | Float64 | +| host | string | Yes | PRI | NULL | | String | +| memory | double | Yes | | NULL | | Float64 | +| ts | timestamp(3) | No | TIME INDEX | current_timestamp() | | TimestampMillisecond | ++--------+--------------+------+------------+---------------------+-------+----------------------+ +``` + +All these `SHOW` extensions accept `WHERE`: + +```sql +SHOW COLUMNS FROM monitor WHERE Field = 'cpu'; +``` + +```sql ++-------+--------+------+------+---------+-------+---------------+ +| Field | Type | Null | Key | Default | Extra | Greptime_type | ++-------+--------+------+------+---------+-------+---------------+ +| cpu | double | Yes | | 0 | | Float64 | ++-------+--------+------+------+---------+-------+---------------+ +``` + +Other `SHOW` statements: +* `SHOW STATUS` and `SHOW VARIABLES` are not supported, just return empty results. +* `SHOW TABLE STATUS` is the extension of `INFORMATION_SCHEMA.TABLES`. \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/sql/tql.md b/versioned_docs/version-0.11/reference/sql/tql.md new file mode 100644 index 000000000..0a1d6f4cd --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/tql.md @@ -0,0 +1,122 @@ +--- +description: Covers the TQL keyword for executing Time-Series Query Language in SQL, including EVAL, EXPLAIN, and ANALYZE commands with syntax and examples. +--- + +# TQL + +The `TQL` keyword executes TQL language in SQL. The TQL is Time-Series Query Language, which is an extension for Prometheus's [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) in GreptimeDB. + +## EVAL + +### Syntax + +```sql +TQL [EVAL | EVALUATE] (start, end, step) expr +``` + +The `start`, `end` and `step` are the query parameters just like [Prometheus Query API](https://prometheus.io/docs/prometheus/latest/querying/api/): + +- `start`: ``: Start timestamp, inclusive. +- `end`: ``: End timestamp, inclusive. +- `step`: ``: Query resolution step width in `duration` format or float number of seconds. + +The `expr` is the TQL expression query string. + +### Examples + +Return the per-second rate for all time series with the `http_requests_total` metric name, as measured over the last 5 minutes: + +```sql +TQL eval (1677057993, 1677058993, '1m') rate(prometheus_http_requests_total{job="prometheus"}[5m]); +``` + +will get a result just like other normal SQL queries. + +## EXPLAIN + +`EXPLAIN` displays both the logical plan and execution plan for a given PromQL query. The syntax is as follows: + +``` +TQL EXPLAIN expr; +``` + +For example, to explain the PromQL `sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50`, we can use + +``` +TQL EXPLAIN sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50; +``` + +Notice that since the given query won't be actually executed, the triple `(start, end, step)` is not necessary. But you can still provide it like in `TQL EVAL`: + +``` +TQL EXPLAIN (0, 100, '10s') sum by (instance) (rate(node_disk_written_bytes_total[2m])) > 50; +``` + +The result should be like the following: + +```txt ++---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| plan_type | plan | ++---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| logical_plan | Sort: node_disk_written_bytes_total.instance ASC NULLS LAST, node_disk_written_bytes_total.ts ASC NULLS LAST + Filter: SUM(prom_rate(ts_range,field,ts)) > Float64(50) + Aggregate: groupBy=[[node_disk_written_bytes_total.instance, node_disk_written_bytes_total.ts]], aggr=[[SUM(prom_rate(ts_range,field,ts))]] + Projection: node_disk_written_bytes_total.ts, prom_rate(ts_range, field, node_disk_written_bytes_total.ts) AS prom_rate(ts_range,field,ts), node_disk_written_bytes_total.instance + Filter: prom_rate(ts_range, field, node_disk_written_bytes_total.ts) IS NOT NULL + Projection: node_disk_written_bytes_total.ts, node_disk_written_bytes_total.instance, field, ts_range + PromRangeManipulate: req range=[0..0], interval=[300000], eval range=[120000], time index=[ts], values=["field"] + PromSeriesNormalize: offset=[0], time index=[ts], filter NaN: [true] + PromSeriesDivide: tags=["instance"] + Sort: node_disk_written_bytes_total.instance DESC NULLS LAST, node_disk_written_bytes_total.ts DESC NULLS LAST + TableScan: node_disk_written_bytes_total projection=[ts, instance, field], partial_filters=[ts >= TimestampMillisecond(-420000, None), ts <= TimestampMillisecond(300000, None)] | +| physical_plan | SortPreservingMergeExec: [instance@0 ASC NULLS LAST,ts@1 ASC NULLS LAST] + SortExec: expr=[instance@0 ASC NULLS LAST,ts@1 ASC NULLS LAST] + CoalesceBatchesExec: target_batch_size=8192 + FilterExec: SUM(prom_rate(ts_range,field,ts))@2 > 50 + AggregateExec: mode=FinalPartitioned, gby=[instance@0 as instance, ts@1 as ts], aggr=[SUM(prom_rate(ts_range,field,ts))] + CoalesceBatchesExec: target_batch_size=8192 + RepartitionExec: partitioning=Hash([Column { name: "instance", index: 0 }, Column { name: "ts", index: 1 }], 32), input_partitions=32 + AggregateExec: mode=Partial, gby=[instance@2 as instance, ts@0 as ts], aggr=[SUM(prom_rate(ts_range,field,ts))] + ProjectionExec: expr=[ts@0 as ts, prom_rate(ts_range@3, field@2, ts@0) as prom_rate(ts_range,field,ts), instance@1 as instance] + CoalesceBatchesExec: target_batch_size=8192 + FilterExec: prom_rate(ts_range@3, field@2, ts@0) IS NOT NULL + ProjectionExec: expr=[ts@0 as ts, instance@1 as instance, field@2 as field, ts_range@3 as ts_range] + PromInstantManipulateExec: req range=[0..0], interval=[300000], eval range=[120000], time index=[ts] + PromSeriesNormalizeExec: offset=[0], time index=[ts], filter NaN: [true] + PromSeriesDivideExec: tags=["instance"] + RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=1 + ExecutionPlan(PlaceHolder) + | ++---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +## ANALYZE + +TQL also supports `ANALYZE` keyword to analyze the given PromQL query's execution. The syntax is as follows: + +``` +TQL ANALYZE (start, end, step) expr; +``` + +For example: + +``` +TQL ANALYZE (0, 10, '5s') test; +``` + +will get a result like + +``` ++-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| plan_type | plan | ++-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Plan with Metrics | CoalescePartitionsExec, metrics=[output_rows=0, elapsed_compute=14.99µs] + PromInstantManipulateExec: range=[0..10000], lookback=[300000], interval=[5000], time index=[j], metrics=[output_rows=0, elapsed_compute=1.08µs] + PromSeriesNormalizeExec: offset=[0], time index=[j], filter NaN: [false], metrics=[output_rows=0, elapsed_compute=1.11µs] + PromSeriesDivideExec: tags=["k"], metrics=[output_rows=0, elapsed_compute=1.3µs] + RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=32, metrics=[send_time=32ns, repart_time=32ns, fetch_time=11.578016ms] + RepartitionExec: partitioning=RoundRobinBatch(32), input_partitions=1, metrics=[send_time=1ns, repart_time=1ns, fetch_time=21.07µs] + ExecutionPlan(PlaceHolder), metrics=[] + | ++-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` diff --git a/versioned_docs/version-0.11/reference/sql/truncate.md b/versioned_docs/version-0.11/reference/sql/truncate.md new file mode 100644 index 000000000..7db790e49 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/truncate.md @@ -0,0 +1,16 @@ +--- +description: Details the TRUNCATE TABLE statement in SQL, used for efficiently deleting all data from a table, with syntax and example. +--- + +# TRUNCATE + +The `TRUNCATE TABLE table` statement is used to delete all data from a table. It's much more efficient than `DELETE FROM table`. + +```sql +TRUNCATE TABLE monitor; +``` + +```sql +Query OK, 0 rows affected (0.02 sec) +``` + diff --git a/versioned_docs/version-0.11/reference/sql/where.md b/versioned_docs/version-0.11/reference/sql/where.md new file mode 100644 index 000000000..c73cf2a8c --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/where.md @@ -0,0 +1,59 @@ +--- +description: Explains the WHERE clause in SQL for filtering data based on conditions, including syntax, examples with logical and comparison operators, and list search functionalities. +--- + +# WHERE + +`WHERE` clause allows to filter the data by specifying conditions. + +## Syntax + +```sql +SELECT * +FROM table_name +WHERE condition; +``` + +If there is a `WHERE` clause, it must contain an expression with the Boolean type. This is usually +an expression with comparison and logical operators. Rows where this expression evaluates to false are +excluded from further transformations or result. + +## Examples + +### Logical operators + +Supports `AND`, `OR` as logical operators and can assemble conditions using brackets (). + +```sql +SELECT * FROM system_metrics +WHERE idc = 'idc0' AND (host = 'host1' OR host = 'host2'); +``` + +### Numeric + +Supports `=`, `!=`, `>`, `>=`, `<`, `<=` as comparison operators. + +```sql +SELECT * FROM system_metrics WHERE cpu_util = 20.0; +SELECT * FROM system_metrics WHERE cpu_util != 20.0; +SELECT * FROM system_metrics WHERE cpu_util > 20.0; +SELECT * FROM system_metrics WHERE cpu_util >= 20.0; +SELECT * FROM system_metrics WHERE cpu_util < 20.0; +SELECT * FROM system_metrics WHERE cpu_util <= 20.0; +``` + +### List search + +Evaluates match or mismatch against a list of elements. + +### List match + +```sql +SELECT * FROM system_metrics WHERE idc IN ('idc_a', 'idc_b'); +``` + +### List mismatch + +```sql +SELECT * FROM system_metrics WHERE idc NOT IN ('idc_a', 'idc_b'); +``` diff --git a/versioned_docs/version-0.11/reference/sql/with.md b/versioned_docs/version-0.11/reference/sql/with.md new file mode 100644 index 000000000..d7c7ff8f4 --- /dev/null +++ b/versioned_docs/version-0.11/reference/sql/with.md @@ -0,0 +1,88 @@ +--- +description: Describes the usage of the WITH clause to define Common Table Expressions (CTEs) in SQL, including syntax, examples of non-recursive CTEs, and notes on recursive CTEs. +--- + +# WITH + +Use `WITH` to specify a Common Table Expression. + +## What is a Common Table Expression (CTE)? + +A Common Table Expression (CTE) is a temporary result set that you can reference within a `SELECT`, `INSERT`, `UPDATE`, or `DELETE` statement. CTEs help to break down complex queries into more readable parts and can be referenced multiple times within the same query. + +## Basic syntax of CTE + +CTEs are typically defined using the `WITH` keyword. The basic syntax is as follows: + +```sql +WITH cte_name [(column1, column2, ...)] AS ( + QUERY +) +SELECT ... +FROM cte_name; +``` + +## Examples + +### Non-recursive CTE + +```sql +WITH cte AS (SELECT number FROM numbers LIMIT 2) SELECT * FROM cte t1, cte t2; +``` + +```sql ++--------+--------+ +| number | number | ++--------+--------+ +| 0 | 0 | +| 0 | 1 | +| 1 | 0 | +| 1 | 1 | ++--------+--------+ +``` + +If a parenthesized list of names follows the CTE name, those names are the column names: + +```sql +WITH cte (col1, col2) AS +( + SELECT 1, 2 + UNION ALL + SELECT 3, 4 +) +SELECT col1, col2 FROM cte; +``` + +The number of names in the list must be the same as the number of columns in the result set. + +```sql ++------+------+ +| col1 | col2 | ++------+------+ +| 1 | 2 | +| 3 | 4 | ++------+------+ +``` + +Join two CTEs: +```sql +WITH + cte1 AS (SELECT number AS a FROM NUMBERS LIMIT 2), + cte2 AS (SELECT number AS b FROM NUMBERS LIMIT 2) +SELECT * FROM cte1 JOIN cte2 +ON cte1.a = cte2.b; +``` + +```sql ++------+------+ +| a | b | ++------+------+ +| 1 | 1 | +| 0 | 0 | ++------+------+ +``` + + +### Recursive CTE + +Recursive CTE is not implemented currently. \ No newline at end of file diff --git a/versioned_docs/version-0.11/reference/telemetry.md b/versioned_docs/version-0.11/reference/telemetry.md new file mode 100644 index 000000000..1373fddcc --- /dev/null +++ b/versioned_docs/version-0.11/reference/telemetry.md @@ -0,0 +1,52 @@ +--- +description: Details on telemetry data collection in GreptimeDB, including what data is collected, how often, and how to enable or disable telemetry. +--- + +# Telemetry + +To enhance our service, GreptimeDB collects certain telemetry data. This includes information like the GreptimeDB version, the number of nodes, the operating system used, the environment's architecture, and similar technical details. However, we respect your privacy and make sure not to collect any user-specific data, which entails database names, table names, query content, and the like. + +This telemetry collection can easily be managed according to your preferences. You may choose to enable or disable it through the configurations. Your experience and privacy are our top priority. + +## What data will be collected? + +The usage details that get shared might change over time. These changes (if any) will be announced in release notes. + +When telemetry is enabled, GreptimeDB will collect the following information every 0.5 hours: + +- GreptimeDB version +- GreptimeDB build git hash +- The operating system of the machine on which GreptimeDB is running(Linux, macOS, etc.) +- Architecture of the machine on which GreptimeDB is running(x86_64, arm64, etc.) +- Mode in which GreptimeDB is running(standalone, distributed) +- A randomly generated installation ID +- The number of datanodes in the GreptimeDB cluster + +## How to disable telemetry? + +Telemetry will be enabled by default starting from v0.4.0. You can disable it by configuring the settings. + +### Standalone mode + +Set `enable_telemetry` in the standalone config file to `false`: + +```toml +# Node running mode, "standalone" or "distributed". +mode = "standalone" +# Whether to enable greptimedb telemetry, true by default. +enable_telemetry = false +``` + +Or configure it by the environment variable `GREPTIMEDB_STANDALONE__ENABLE_TELEMETRY=false` on startup. + +### Distributed mode + +Set `enable_telemetry` in the metasrv config file to `false`: + +```toml +# metasrv config file +# Whether to enable greptimedb telemetry, true by default. +enable_telemetry = false +``` + +Or set the environment variable `GREPTIMEDB_METASRV__ENABLE_TELEMETRY=false` on startup. diff --git a/versioned_docs/version-0.11/user-guide/administration/capacity-plan.md b/versioned_docs/version-0.11/user-guide/administration/capacity-plan.md new file mode 100644 index 000000000..a81dfdb5f --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/capacity-plan.md @@ -0,0 +1,71 @@ +--- +description: Provides guidelines for CPU, memory, and storage requirements for GreptimeDB based on data points processed per second, query requests per second, data volume, and data retention policy. Includes an example scenario. +--- + +# Capacity Plan + +This guide provides general advice on the CPU, memory, and storage requirements for GreptimeDB. + +GreptimeDB is designed to be lightweight upon startup, +which allows for the database to be initiated with minimal server resources. +However, when configuring your server capacity for a production environment, +there are several key considerations: + +- Data points processed per second +- Query requests per second +- Data volume +- Data retention policy +- Hardware costs + +To monitor the various metrics of GreptimeDB, please refer to [Monitoring](/user-guide/administration/monitoring/export-metrics.md). + +## CPU + +Generally, applications that handle many concurrent queries, process large amounts of data, +or perform other compute-intensive operations will require more CPU cores. + +Here are some recommendations for CPU resource usage, +but the actual number of CPUs you should use depends on your workload. + +Consider allocating 30% of your CPU resources for data ingestion, +with the remaining 70% to querying and analytics. + +A recommended guideline for resource allocation is to maintain a CPU to memory ratio of 1:4 (for instance, 8 core to 32 GB). +However, if your workload consists primarily of data ingestion with few queries, +a ratio of 1:2 (8 core to 16 GB) can also be acceptable. + +## Memory + +In general, the more memory you have, the faster your queries will run. +For basic workloads, it's recommended to have at least 8 GB of memory, and 32 GB for more advanced ones. + +## Storage + +GreptimeDB features an efficient data compaction mechanism that reduces the original data size to about 1/8 to 1/10 of its initial volume. +This allows GreptimeDB to store large amounts of data in a significantly smaller space. + +Data can be stored either in a local file system or in cloud storage, such as AWS S3. +FOr more information on storage options, +please refer to the [storage configuration](/user-guide/deployments/configuration.md#storage-options) documentation. + +Cloud storage is highly recommended for data storage due to its simplicity in managing storage. +With cloud storage, only about 200GB of local storage space is needed for query-related caches and Write-Ahead Log (WAL). + +In order to manage the storage costs effectively, +it is recommended setting a [retention policy](/user-guide/concepts/features-that-you-concern.md#can-i-set-ttl-or-retention-policy-for-different-tables-or-measurements). + +## Example + +Consider a scenario where your database handles a query rate of about 200 simple queries per second (QPS) and an ingestion rate of approximately 300k data points per second, using cloud storage for data. + +Given the high ingestion and query rates, +here's an example of how you might allocate resources: + +- CPU: 8 cores +- Memory: 32 GB +- Storage: 200 GB + +Such an allocation is designed to optimize performance, +ensuring smooth data ingestion and query processing without system overload. +However, remember these are just guidelines, +and actual requirements may vary based on specific workload characteristics and performance expectations. diff --git a/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/back-up-&-restore-data.md b/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/back-up-&-restore-data.md new file mode 100644 index 000000000..f4d8ab3f0 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/back-up-&-restore-data.md @@ -0,0 +1,150 @@ +--- +description: Describes how to use GreptimeDB's Export and Import tools for database backup and restoration, including command syntax, options, usage scenarios, best practices, troubleshooting, and performance tips. +--- + +# GreptimeDB Export & Import Tools + +This guide describes how to use GreptimeDB's Export and Import tools for database backup and restoration. + + +The Export and Import tools provide functionality for backing up and restoring GreptimeDB databases. These tools can handle both schema and data, allowing for complete or selective backup and restoration operations. + +## Export Tool + +### Command Syntax +```bash +greptime cli export [OPTIONS] +``` + +### Options +| Option | Required | Default | Description | +|--------|----------|---------|-------------| +| --addr | Yes | - | Server address to connect | +| --output-dir | Yes | - | Directory to store exported data | +| --database | No | all databasses | Name of the database to export | +| --export-jobs, -j | No | 1 | Number of parallel export jobs(multiple databases can be exported in parallel) | +| --max-retry | No | 3 | Maximum retry attempts per job | +| --target, -t | No | all | Export target (schema/data/all) | +| --start-time | No | - | Start of time range for data export | +| --end-time | No | - | End of time range for data export | +| --auth-basic | No | - | Use the `:` format | +| --timeout | No | 0 | The timeout for a single call to the DB, default is 0 which means never timeout (e.g., `30s`, `10min 20s`) | + +### Export Targets +- `schema`: Exports table schemas only (`SHOW CREATE TABLE`) +- `data`: Exports table data only (`COPY DATABASE TO`) +- `all`: Exports both schemas and data (default) + +### Output Directory Structure +``` +/ +└── greptime/ + └── / + ├── create_database.sql + ├── create_tables.sql + ├── copy_from.sql + └── +``` + +## Import Tool + +### Command Syntax +```bash +greptime cli import [OPTIONS] +``` + +### Options +| Option | Required | Default | Description | +|--------|----------|---------|-------------| +| --addr | Yes | - | Server address to connect | +| --input-dir | Yes | - | Directory containing backup data | +| --database | No | all databases | Name of the database to import | +| --import-jobs, -j | No | 1 | Number of parallel import jobs (multiple databases can be imported in parallel) | +| --max-retry | No | 3 | Maximum retry attempts per job | +| --target, -t | No | all | Import target (schema/data/all) | +| --auth-basic | No | - | Use the `:` format | + +### Import Targets +- `schema`: Imports table schemas only +- `data`: Imports table data only +- `all`: Imports both schemas and data (default) + +## Common Usage Scenarios + +### Full Databases Backup +```bash +# Export all databases backup +greptime cli export --addr localhost:4000 --output-dir /tmp/backup/greptimedb + +# Import all databases +greptime cli import --addr localhost:4000 --input-dir /tmp/backup/greptimedb +``` + +### Schema-Only Operations +```bash +# Export only schemas +greptime cli export --addr localhost:4000 --output-dir /tmp/backup/schemas --target schema + +# Import only schemas +greptime cli import --addr localhost:4000 --input-dir /tmp/backup/schemas --target schema +``` + +### Time-Range Based Backup +```bash +# Export data within specific time range +greptime cli export --addr localhost:4000 \ + --output-dir /tmp/backup/timerange \ + --start-time "2024-01-01 00:00:00" \ + --end-time "2024-01-31 23:59:59" +``` + +### Specific Database Backup +```bash +# To export a specific database +greptime cli export --addr localhost:4000 --output-dir /tmp/backup/greptimedb --database '{my_database_name}' + +# The same applies to import tool +greptime cli import --addr localhost:4000 --input-dir /tmp/backup/greptimedb --database '{my_database_name}' +``` + +## Best Practices + +1. **Parallelism Configuration** + - Adjust `--export-jobs`/`--import-jobs` based on available system resources + - Start with a lower value and increase gradually + - Monitor system performance during operations + +2. **Backup Strategy** + - Incremental data backups using time ranges + - Periodic backups for disaster recovery + +3. **Error Handling** + - Use `--max-retry` for handling transient failures + - Keep logs for troubleshooting + +## Troubleshooting + +### Common Issues + +1. **Connection Errors** + - Verify server address and port + - Check network connectivity + - Ensure authentication credentials are correct + +2. **Permission Issues** + - Verify read/write permissions on output/input directories + +3. **Resource Constraints** + - Reduce parallel jobs + - Ensure sufficient disk space + - Monitor system resources during operations + +### Performance Tips + +1. **Export Performance** + - Use time ranges for large datasets + - Adjust parallel jobs based on CPU/memory + - Consider network bandwidth limitations + +2. **Import Performance** + - Monitor database resources diff --git a/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster.md b/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster.md new file mode 100644 index 000000000..ef15a1995 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster.md @@ -0,0 +1,125 @@ +--- +description: Explains the disaster recovery (DR) solution based on cross-region deployment in a single GreptimeDB cluster, detailing various configurations for metadata and data distribution across regions to achieve high availability and reliability. +--- + +# DR Solution Based on Cross-Region Deployment in a Single Cluster + +## How disaster recovery works in GreptimeDB +GreptimeDB is well-suited for cross-region disaster recovery. You may have varying regional characteristics and business needs, and GreptimeDB offers tailored solutions to meet these diverse requirements. + +GreptimeDB resource management involves the concept of Availability Zones (AZs). An AZ is a logical unit of disaster recovery. +It can be a Data Center (DC), a compartment of a DC. This depends on your specific DC conditions and deployment design. + +In the cross region disaster recovery solutions, a GreptimeDB region is a city. When two DC are in the same region and one DC becomes unavailable, the other DC can take over the services of the unavailable DC. This is a localization strategy. + +Before understanding the details of each DR solution, it is necessary to first understand the following knowledge: +1. The DR solution for the remote wal component is also very important. Essentially, it forms the foundation of the entire DR solution. Therefore, for each DR solution of GreptimeDB, we will let the remote wal component in the diagram. Currently, GreptimeDB's default remote wal component is implemented based on Kafka, and other implementations will be provided in the future; however, there won't be significant differences in deployment. +2. The table of GreptimeDB: Each table can be divided into multiple partitions according to a certain range, and each partition may be distributed on different datanodes. When writing or querying, the specified node will be called according to the corresponding rules. A table's partitions might look like this: + +``` +Table name: T1 +Table partition count: 4 + T1-1 + T1-2 + T1-3 + T1-4 + +Table name: T2 +Table partition count: 3 + T2-1 + T2-2 + T2-3 +``` + + +### Metadata across 2 regions, data in the same region + +![DR-across-2dc-1region](/DR-across-2dc-1region.png) + +In this solution, the data is in one region (2 DCs), while the metadata across 2 regions. + +DC1 and DC2 are used together to handle read and write services, while DC3 (located in region2) is a replica used to meet the majority protocol. This architecture is also called the "2-2-1" solution. + +Both DC1 and DC2 must be able to handle all requests in extreme situations, so please ensure that sufficient resources are allocated. + +Latencies: +- 2ms latency in the same region +- 30ms latency in two regions + +Supports High Availability: +- A single AZ is unavailable with the same performance +- A single DC is unavailable with almost the same performance + + +If you want a regional-level disaster recovery solution, you can take it a step further by providing read and write services on DC3. So, the next solution is: + +### Data across 2 regions + +![DR-across-3dc-2region](/DR-across-3dc-2region.png) + +In this solution, the data across 2 regions. + +Each DC must be able to handle all requests in extreme situations, so please ensure that sufficient resources are allocated. + +Latencies: +- 2ms latency in the same region +- 30ms latency in two regions + +Supports High Availability: +- A single AZ is unavailable with the same performance +- A single DC is unavailable with degraded performance + +If you can't tolerate performance degradation from a single DC failure, consider upgrading to the five-DC and three-region solution. + +### Metadata across 3 regions, data across 2 regions + +![DR-across-5dc-2region](/DR-across-5dc-2region.png) + +In this solution, the data across 2 regions, while the metadata across 3 regions. + +Region1 and region2 are used together to handle read and write services, while region3 is a replica used to meet the majority protocol. This architecture is also called the "2-2-1" solution. + +Each of the two adjacent regions must be able to handle all requests in extreme situations, so please ensure that sufficient resources are allocated. + +Latencies: +- 2ms latency in the same region +- 7ms latency in two adjacent regions +- 30ms latency in two distant regions + +Supports High Availability: +- A single AZ is unavailable with the same performance +- A single DC is unavailable with the same performance +- A single region(city) is unavailable with slightly degraded performance + +You can take it a step further by providing read and write services on both 3 regions. So, the next solution is: +(This solution may have higher latency, so if that's unacceptable, it's not recommended.) + +### Data across 3 regions + +![DR-across-5dc-3region](/DR-across-5dc-3region.png) + +In this solution, the data across 3 regions. + +In the event of a failure in one region, the other two regions must be able to handle all requests, so please ensure sufficient resources are allocated. + +Latencies: +- 2ms latency in the same region +- 7ms latency in two adjacent regions +- 30ms latency in two distant regions + +Supports High Availability: +- A single AZ is unavailable with the same performance +- A single DC is unavailable with the same performance +- A single region(city) is unavailable with degraded performance + +## Solution Comparison +The goal of the above solutions is to meet the high requirements for availability and reliability in medium to large-scale scenarios. However, in specific implementations, the cost and effectiveness of each solution may vary. The table below compares each solution to help you choose the final plan based on your specific scenario, needs, and costs. + +Here is the content formatted into a table: + +| Solution | Latencies | High Availability | +| --- | --- | --- | +| Metadata across 2 regions, data in the same region | - 2ms latency in the same region
- 30ms latency in two regions | - A single AZ is unavailable with the same performance
- A single DC is unavailable with almost the same performance | +| Data across 2 regions | - 2ms latency in the same region
- 30ms latency in two regions | - A single AZ is unavailable with the same performance
- A single DC is unavailable with degraded performance | +| Metadata across 3 regions, data across 2 regions | - 2ms latency in the same region
- 7ms latency in two adjacent regions
- 30ms latency in two distant regions | - A single AZ is unavailable with the same performance
- A single DC is unavailable with the same performance
- A single region(city) is unavailable with slightly degraded performance | +| Data across 3 regions | - 2ms latency in the same region
- 7ms latency in two adjacent regions
- 30ms latency in two distant regions | - A single AZ is unavailable with the same performance
- A single DC is unavailable with the same performance
- A single region(city) is unavailable with degraded performance | diff --git a/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-for-standalone.md b/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-for-standalone.md new file mode 100644 index 000000000..5dda9d3c1 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/dr-solution-for-standalone.md @@ -0,0 +1 @@ +# DR solution for GreptimeDB Standalone diff --git a/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/overview.md b/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/overview.md new file mode 100644 index 000000000..0f255c27a --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/disaster-recovery/overview.md @@ -0,0 +1,129 @@ +--- +description: Overview of disaster recovery (DR) solutions in GreptimeDB, including basic concepts, component architecture, and various DR solutions such as standalone, active-active failover, cross-region deployment, and backup & restore. +--- + +# Overview + +GreptimeDB is a distributed database designed to withstand disasters. It provides different solutions for disaster recovery (DR). + +This document contains: +* Basic concepts in DR. +* The deployment architecture of GreptimeDB and Backup & Restore (BR). +* GreptimeDB provides the DR solutions. +* Compares these DR solutions. + +## Basic Concepts + +* **Recovery Time Objective (RTO)**: refers to the maximum acceptable amount of time that a business process can be down after a disaster occurs before it negatively impacts the organization. +* **Recovery Point Objective (RPO)**: refers to the maximum acceptable amount of time since the last data recovery point. This determines what is considered an acceptable loss of data between the last recovery point and the interruption of service. + +The following figure illustrates these two concepts: + +![RTO-RPO-explain](/RTO-RPO-explain.png) + +* **Write-Ahead Logging (WAL)**: persistently records every data modification to ensure data integrity and consistency. + +GreptimeDB storage engine is a typical [LSM Tree](https://en.wikipedia.org/wiki/Log-structured_merge-tree) : +![LSM-tree-explain](/LSM-tree-explain.png) + +The data written is going firstly persisted into WAL, then applied into Memtable in memory. Under specific conditions (e.g., exceeding the memory threshold), the Memtable will be flushed and persisted as an SSTable. So the DR of WAL and SSTable is key to the DR of GreptimeDB. + +* **Region**: a contiguous segment of a table, and also could be regarded as a partition in some relational databases. Read [Table Sharding](/contributor-guide/frontend/table-sharding.md#region) for more details. + +## Component architecture + +### GreptimeDB + +Before digging into the specific DR solution, let's explain the architecture of GreptimeDB components in the perspective of DR: +![Component-architecture](/Component-architecture.png) + +GreptimeDB is designed with a cloud-native architecture based on storage-compute separation： +* **Frontend**: the ingestion and query service layer, which forwards requests to Datanode and processes, and merges responses from Datanode. +* **Datanode**: the storage layer of GreptimeDB, and is an LSM storage engine. Region is the basic unit for storing and scheduling data in Datanode. A region is a table partition, a collection of data rows. The data in region is saved into Object Storage (such as AWS S3). Unflushed Memtable data is written into WAL and can be recovered in DR. +* **WAL**: persists the unflushed Memtable data in memory. It will be truncated when the Memtable is flushed into SSTable files. It can be local disk-based (local WAL) or Kafka cluster-based (remote WAL). +* **Object Storage**: persists the SSTable data and index. + +The GreptimeDB stores data in object storage such as [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/DataDurability.html) or its compatible services, which is designed to provide 99.999999999% durability and 99.99% availability of objects over a given year. And services such as S3 provide [replications in Single-Region or Cross-Region](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html), which is naturally capable of DR. + +At the same time, the WAL component is pluggable, e.g. using Kafka as the WAL service that offers a mature [DR solution](https://www.confluent.io/blog/disaster-recovery-multi-datacenter-apache-kafka-deployments/). + +### Backup and restore + +![BR-explain](/BR-explain.png) + +The Backup & Restore (BR) tool can perform a full snapshot backup of databases or tables at a specific time and supports incremental backup. +When a cluster encounters a disaster, you can restore the cluster from backup data. Generally speaking, BR is the last resort for disaster recovery. + +## Solutions introduction + +### DR solution for GreptimeDB Standalone + +If the Standalone is running on the local disk for WAL and data, then: +* RPO: depends on backup frequency. +* RTO: doesn't make sense in standalone mode, mostly depends on the size of the data to be restored, your failure response time, and the operational infrastructure. + +A good start is to deploy GreptimeDB Standalone into an IaaS platform that has a backup and recovery solution. For example, Amazon EC2 with EBS volumes provides a comprehensive [Backup and Recovery solution](https://docs.aws.amazon.com/prescriptive-guidance/latest/backup-recovery/backup-recovery-ec2-ebs.html). + +But if running the Standalone with remote WAL and object storage, there is a better DR solution: +![DR-Standalone](/DR-Standalone.png) + +Write the WAL to the Kafka cluster and store the data in object storage, so the database itself is stateless. In the event of a disaster affecting the standalone database, you can restore it using the remote WAL and object storage. This solution can achieve **RPO=0** and **RTO in minutes**. + +For more information about this solution, see [DR solution for Standalone](./dr-solution-for-standalone.md). + +### DR solution based on Active-Active Failover + +![Active-active failover](/active-active-failover.png) + +In some edge or small-to-medium scale scenarios, or if you lack the resources to deploy remote WAL or object storage, Active-Active Failover offers a better solution compared to Standalone DR. By replicating requests synchronously between two actively serving standalone nodes, high availability is ensured. The failure of any single node will not lead to data loss or a decrease in service availability even when using local disk-based WAL and data storage. + +Deploying nodes in different regions can also meet region-level DR requirements, but the scalability is limited. + +:::tip NOTE + +**Active-Active Failover is only available in GreptimeDB Enterprise.** + +::: + +For more information about this solution, see [DR solution based on Active-Active Failover](/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md). + +### DR solution based on cross-region deployment in a single cluster + +![Cross-region-single-cluster](/Cross-region-single-cluster.png) + +For medium-to-large scale scenarios requiring zero RPO, this solution is highly recommended. In this deployment architecture, the entire cluster spans across three regions, with each region capable of handling both read and write requests. Data replication is achieved using remote WAL and object storage, both of which must have cross-region DR enabled. +If Region 1 becomes completely unavailable due to a disaster, the table regions within it will be opened and recovered in the other regions. +In the event that Region 1 becomes completely unavailable due to a disaster, the table regions within it will be opened and recovered in the other regions. Region 3 serves as a replica to adhere to the majority protocol of Metasrv. + +This solution provides region-level error tolerance, scalable write capability, zero RPO, and minute-level RTO or even lower. For more information about this solution, see [DR solution based on cross-region deployment in a single cluster](./dr-solution-based-on-cross-region-deployment-in-single-cluster.md). + +### DR solution based on BR + +![/BR-DR](/BR-DR.png) + +In this architecture, GreptimeDB Cluster 1 is deployed in region 1. The BR process continuously and regularly backs up the data from Cluster 1 to region 2. If region 1 experiences a disaster rendering Cluster 1 unrecoverable, you can use the backup data to restore a new cluster (Cluster 2) in region 2 to resume services. + +The DR solution based on BR provides an RPO depending on the backup frequency and an RTO that varies with the size of the data to be restored. + +Read [Backup & restore data](./back-up-&-restore-data.md) for details, and we plan to provide a BR tool in-house for this solution. + +### Solution Comparison + +By comparing these DR solutions, you can decide on the final option based on their specific scenarios, requirements, and cost. + + +| DR solution | Error Tolerance Objective | RPO | RTO | TCO | Scenarios | Remote WAL & Object Storage | Notes | +| ------------- | ------------------------- | ----- | ----- | ----- | ---------------- | --------- | --------| +| DR solution for Standalone| Single-Region | Backup Interval | Minute or Hour level | Low | Low requirements for availability and reliability in small scenarios | Optional | | +| DR solution based on Active-Active Failover | Cross-Region | 0 | Minute level | Low | High requirements for availability and reliability in small-to-medium scenarios | Optional | Commercial feature | +| DR solution based on cross-region deployment in a single cluster| Multi-Regions | 0 | Minute level | High | High requirements for availability and reliability in medium-to-large scenarios | Required | | +| DR solution based on BR | Single-Region | Backup Interval | Minute or Hour level | Low | Acceptable requirements for availability and reliability | Optional | | + + +## References + +* [Backup & restore data](./back-up-&-restore-data.md) +* [DR solution for GreptimeDB Standalone](./dr-solution-for-standalone.md) +* [DR solution based on Active-Active Failover ](/enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover.md) +* [DR solution based on cross-region deployment in a single cluster](./dr-solution-based-on-cross-region-deployment-in-single-cluster.md) +* [S3 Replicating objects overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html) \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/administration/manage-data/basic-table-operations.md b/versioned_docs/version-0.11/user-guide/administration/manage-data/basic-table-operations.md new file mode 100644 index 000000000..33183ddbd --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/manage-data/basic-table-operations.md @@ -0,0 +1,363 @@ +--- +description: Covers basic table operations in GreptimeDB, including creating, describing, showing, altering, and dropping tables, as well as executing SQL statements through the HTTP API and understanding time zone effects. +--- + +# Basic Table Operations + +[Data Model](/user-guide/concepts/data-model.md) should be read before this guide. + +GreptimeDB provides table management functionalities via SQL. The following guide +uses [MySQL Command-Line Client](https://dev.mysql.com/doc/refman/8.0/en/mysql.html) to demonstrate it. + +For more explanations of the `SQL` syntax, please see the [SQL reference](/reference/sql/overview.md). + +## Create a database + +The default database is `public`. You can create a database manually. + +```sql +CREATE DATABASE test; +``` + +```sql +Query OK, 1 row affected (0.05 sec) +``` + +Create a database with a `TTL` (Time-To-Live) of seven days, which means all the tables in this database will inherit this option if they don't have their own `TTL` setting: + +```sql +CREATE DATABASE test with(ttl='7d'); +``` + +You can list all the existing databases. + +```sql +SHOW DATABASES; +``` + +```sql ++---------+ +| Schemas | ++---------+ +| test | +| public | ++---------+ +2 rows in set (0.00 sec) +``` + +Using `like` syntax: + +```sql +SHOW DATABASES LIKE 'p%'; +``` + +```sql ++---------+ +| Schemas | ++---------+ +| public | ++---------+ +1 row in set (0.00 sec) +``` + +Then change the database: + +```sql +USE test; +``` + +Change back to `public` database: + +```sql +USE public; +``` + +## Create a table + +:::tip NOTE +GreptimeDB offers a schemaless approach to writing data that eliminates the need to manually create tables using additional protocols. See [Automatic Schema Generation](/user-guide/ingest-data/overview.md#automatic-schema-generation). +::: + +You can still create a table manually via SQL if you have specific requirements. +Suppose we want to create a table named monitor with the following data model: + +- `host` is the hostname of the collected standalone machine, which should be a `Tag` that used to filter data when querying. +- `ts` is the time when the data is collected, which should be the `Timestamp`. It can also used as a filter when querying data with a time range. +- `cpu` and `memory` are the CPU utilization and memory utilization of the machine, which should be `Field` columns that contain the actual data and are not indexed. + +The SQL code for creating the table is shown below. In SQL, we use the primary key to specify `Tag`s and the `TIME INDEX` to specify the `Timestamp` column. The remaining columns are `Field`s. + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64 DEFAULT 0, + memory FLOAT64, + PRIMARY KEY(host)); +``` + +```sql +Query OK, 0 row affected (0.03 sec) +``` + +Create the table with a `TTL` (Time-To-Live) of seven days: + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64 DEFAULT 0, + memory FLOAT64, + PRIMARY KEY(host) +) WITH (ttl='7d'); +``` + +:::warning NOTE +GreptimeDB does not currently support changing the TIME INDEX after a table has been created. +Therefore, it is important to carefully choose your TIME INDEX column before creating tables. +::: + +### `CREATE TABLE` syntax + +- Timestamp column: GreptimeDB is a time-series database system, a timestamp column must + be explicitly specified by `TIME INDEX` keyword when creating tables. The data type of + the timestamp column must be `TIMESTAMP`type. +- Primary key: The columns in primary key are similar to tags in other other time-series systems like [InfluxDB][1]. The primary key columns with the time index column are used to uniquely define a series of data, which is similar + to time series like [InfluxDB][2]. +- Table options: when creating a table, you can specify a set of table options, click [here](/reference/sql/create.md#table-options) for more details. + +### Table name constraints + +GreptimeDB supports a limited set of special characters in table names, but they must adhere to the following constraints: +- A valid GreptimeDB table name must start with a letter (either lowercase or uppercase) or `-` / `_` / `:`. +- The rest part of table name can be alphanumeric or special characters within: `-` / `_` / `:` / `@` / `#`. +- Any table name containing special characters must be quoted with backquotes. +- Any table name containing uppercase letters must be quoted with backquotes. + +Here are some examples: +```sql +-- ✅ Ok +create table a (ts timestamp time index); + +-- ✅ Ok +create table a0 (ts timestamp time index); + +-- 🚫 Invalid table name +create table 0a (ts timestamp time index); + +-- 🚫 Invalid table name +create table -a (ts timestamp time index); + +-- ✅ Ok +create table `-a` (ts timestamp time index); + +-- ✅ Ok +create table `a@b` (ts timestamp time index); + +-- 🚫 Invalid table name +create table memory_HugePages (ts timestamp time index); + +-- ✅ Ok +create table `memory_HugePages` (ts timestamp time index); +``` + + +[1]: https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#tag-key +[2]: https://docs.influxdata.com/influxdb/v1/concepts/glossary/#series + +## Describe a table + +Show table information in detail: + +```sql +DESC TABLE monitor; +``` + +```sql ++--------+----------------------+------+------+---------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------+----------------------+------+------+---------------------+---------------+ +| host | String | PRI | YES | | TAG | +| ts | TimestampMillisecond | PRI | NO | current_timestamp() | TIMESTAMP | +| cpu | Float64 | | YES | 0 | FIELD | +| memory | Float64 | | YES | | FIELD | ++--------+----------------------+------+------+---------------------+---------------+ +4 rows in set (0.01 sec) +``` + +The Semantic Type column describes the data model of the table. The `host` is a `Tag` column, `ts` is a `Timestamp` column, and cpu and memory are `Field` columns. + +## Show Table Definition and Indexes + +Use `SHOW CREATE TABLE table_name` to get the statement when creating the table: + +```sql +SHOW CREATE TABLE monitor; +``` + +``` ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Table | Create Table | ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| monitor | CREATE TABLE IF NOT EXISTS `monitor` ( + `host` STRING NULL, + `ts` TIMESTAMP(3) NOT NULL DEFAULT current_timestamp(), + `cpu` DOUBLE NULL DEFAULT 0, + `memory` DOUBLE NULL, + TIME INDEX (`ts`), + PRIMARY KEY (`host`) +) + +ENGINE=mito + | ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +List all indexes in a table: + +```sql +SHOW INDEXES FROM monitor; +``` + + +```sql ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression | ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +| monitor | 1 | PRIMARY | 1 | host | A | NULL | NULL | NULL | YES | greptime-inverted-index-v1 | | | YES | NULL | +| monitor | 1 | TIME INDEX | 1 | ts | A | NULL | NULL | NULL | NO | greptime-inverted-index-v1 | | | YES | NULL | ++---------+------------+------------+--------------+-------------+-----------+-------------+----------+--------+------+----------------------------+---------+---------------+---------+------------+ +``` + +For more info about `SHOW` statement, please read the [SHOW reference](/reference/sql/show.md#show). + +## List Existing Tables + +You can use `show tables` statement to list existing tables + +```sql +SHOW TABLES; +``` + +```sql ++------------+ +| Tables | ++------------+ +| monitor | +| scripts | ++------------+ +3 rows in set (0.00 sec) +``` + +Notice: `scripts` table is a built-in table that holds User-Defined Functions (UDFs). +Currently only table name filtering is supported. You can filter existing tables by their names. + +```sql +SHOW TABLES LIKE monitor; +``` + +```sql ++---------+ +| Tables | ++---------+ +| monitor | ++---------+ +1 row in set (0.00 sec) +``` + +List tables in other databases: + +```sql +SHOW TABLES FROM test; +``` + +```sql ++---------+ +| Tables | ++---------+ +| monitor | ++---------+ +1 row in set (0.01 sec) +``` + +## Alter a table + +You can alter the schema of existing tables just like in MySQL database + +```sql +ALTER TABLE monitor ADD COLUMN label VARCHAR; +``` + +```sql +Query OK, 0 rows affected (0.03 sec) +``` + +```sql +ALTER TABLE monitor DROP COLUMN label; +``` + +```sql +Query OK, 0 rows affected (0.03 sec) +``` + +The `ALTER TABLE` statement also supports adding, removing, and renaming columns, as well as modifying the column datatype, etc. Please refer to the [ALTER reference](/reference/sql/alter.md) for more information. + +## Drop a table + +:::danger danger +`DROP TABLE` cannot be undone. Use it with care! +::: + +`DROP TABLE [db.]table` is used to drop the table in `db` or the current database in-use.Drop the table `test` in the current database: + +```sql +DROP TABLE monitor; +``` + +```sql +Query OK, 1 row affected (0.01 sec) +``` + +## Drop a database + +:::danger danger +`DROP DATABASE` cannot be undone. Use it with care! +::: + +You can use `DROP DATABASE` to drop a database. +For example, to drop the `test` database: + +```sql +DROP DATABASE test; +``` + +Please refer to the [DROP](/reference/sql/drop.md#drop-database) document for more details. + +## HTTP API + +You can execute the SQL statements through the HTTP API. +For example, +using the following code to create a table through POST method: + +```shell +curl -X POST \ + -H 'authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql=CREATE TABLE monitor (host STRING, ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP(), cpu FLOAT64 DEFAULT 0, memory FLOAT64, TIME INDEX (ts), PRIMARY KEY(host))' \ +http://localhost:4000/v1/sql?db=public +``` + +```json +{ "code": 0, "output": [{ "affectedrows": 1 }], "execution_time_ms": 10 } +``` + +For more information about SQL HTTP request, please refer to [API document](/user-guide/protocols/http.md#post-sql-statements). + +## Time zone + +The specified time zone in the SQL client session will affect the default timestamp value when creating or altering a table. +If you set the default value of a timestamp column to a string without a time zone, +the client's time zone information will be automatically added. + +For more information about the effect of the client time zone, please refer to the [time zone](/user-guide/ingest-data/for-iot/sql.md#time-zone) section in the write data document. + diff --git a/versioned_docs/version-0.11/user-guide/administration/manage-data/compaction.md b/versioned_docs/version-0.11/user-guide/administration/manage-data/compaction.md new file mode 100644 index 000000000..a38414102 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/manage-data/compaction.md @@ -0,0 +1,148 @@ +--- +description: Explanation of the compaction process in GreptimeDB, including concepts like SST files, time windows, sorted runs, and levels, as well as the Time Windowed Compaction Strategy (TWCS) and Strict Window Compaction Strategy (SWCS). +--- + +# Compaction + +For databases based on the LSM Tree, compaction is extremely critical. It merges overlapping fragmented SST files into a single ordered file, discards deleted data while significantly improves query performance. + +Until v0.9.1, GreptimeDB provides compaction strategies to control how SST files are compacted: Time Windowed Compaction Strategy (TWCS) and Strict Window Compaction Strategy (SWCS). + + +## Concepts + +Let us start with those core concepts of compaction in GreptimeDB. + +### SST files + +SSTs are sorted files generated when memtables are flushed to persistent storage, such as disks and object stores. + +In GreptimeDB, data rows in SST files are organized by [tags](/user-guide/concepts/data-model.md) and timestamps, as illustrated below. Each SST file covers a specific time range. When a query specifies a time range, GreptimeDB retrieves only the relevant SST files that may contain data within that range, rather than loading all persisted files. + +![SST layout](/compaction-sst-file-layout.jpg) + +Typically, the time ranges of SST files do not overlap during real-time writing workloads. However, due to factors like row deletions and out-of-order writes, SST files may have overlapping time ranges, which can affect query performance. + +### Time window + +Time-series workloads present prominent "windowed" pattern in that most recently inserted rows are more possible to be read. Thus GreptimeDB logically partitioned the time axis into different time windows and we are more interested in compacting those SST files fall into the same time window. + +Time window for some specific table is usually inferred from the most-recently flushed SST files or users may manually specify the time window if TWCS is chosen. + +GreptimeDB has a preset collection of window sizes that are: +- 1 hour +- 2 hours +- 12 hours +- 1 day +- 1 week +- 1 year +- 10 years + +If time window is not specified, GreptimeDB will infer it when the first compaction happens by selecting the minimum time window size for the above collection that can cover the whole time span of all files to be compacted. + +For example, during the first compaction, the time span for all SST files is 4 hours, then GreptimeDB will choose 12 hours as the time window for that table and persist it for later compactions. + +GreptimeDB considers the window contains most recently inserted timestamps as **active window** and those previous windows as **inactive windows**. + +### Sorted runs +Sorted runs is a collection of SST files that have sorted and non-overlapping time ranges. + +For example, a table contains 5 SSTs with following time ranges (all inclusive): `[0, 10]`, `[12, 23]`, `[22, 25]`,`[24, 30]`,`[26,33]` and we can find 2 sorted runs: + +![num-of-sorted-runs](/compaction-num-sorted-runs.jpg) + + +The number of sorted runs indicates the orderliness of SST files. More sorted runs typically lead to worse query performance. The main goal of compactions is to reduce the number of sorted runs. + +### Levels + +Databases based on LSM trees may also have levels, keys are merged level by level. GreptimeDB only has 2 levels which are 0 (uncompacted) and 1 (compacted). + +## Compaction strategies +GreptimeDB provides two compaction strategies as mentioned above, but only Time Windowed Compaction Strategy (TWCS) can be chosen when creating tables. Strict Window Compaction Strategy (SWCS) is only available when executing manual compactions. + +## Time Windowed Compaction Strategy (TWCS) + +TWCS primarily aims to reduce read/write amplification during compaction. + +It assigns files to be compacted into different time windows. For each window, TWCS identifies the sorted runs. If the number of sorted runs exceeds the maximum allowed, TWCS finds a solution to reduce them to the threshold while considering merging penalties. If the number of sorted runs does not exceed the threshold, TWCS checks for excessive file fragmentation and merges fragmented files if necessary since SST file count also impacts query performance. + +For window assignment, SST files may span multiple time windows. TWCS assigns SSTs based on their maximum timestamps to ensure they are not affected by stale data. In time-series workloads, out-of-order writes are infrequent, and even when they occur, recent data's query performance is more critical than that of stale data. + + +TWCS provides 5 parameters: +- `max_active_window_runs`: max allowed sorted runs in the active window (default: 4) +- `max_active_window_files`: max allowed files in the active window (default: 4) +- `max_inactive_window_runs`: max allowed sorted runs in inactive windows (default: 1) +- `max_inactive_window_files`: max allowed files in inactive windows (default: 1) +- `max_output_file_size`: max allowed compaction output file size (no limit by default). + +You can set different thresholds for active and inactive windows. This is important because out-of-order writes typically occur in the active window. By allowing more overlapping files in the active window, TWCS reduces write amplification during ingestion and merges all these files when the active window becomes inactive. + +Following diagrams show how files in an active window get compacted when `max_sorted_runs = 1`: +- In A, there're two SST files `[0, 3]` and `[5, 6, 9]` but there's only one sorted run since those two files have disjoint time ranges. +- In B, a new SST file `[1, 4]` is flushed therefore forms two sorted runs that exceeds the threshold. Then `[0, 3]` and `[1, 4]` are merged to `[0, 1, 3, 4]`. +- In C, a new SST file `[9, 10]` is flushed, and it will be merged with `[5, 6, 10]` to create `[5, 6, 9, 10]`. +- D is the final state, in two compacted files form one sorted run. + +![compaction-twcs-active.jpg](/compaction-twcs-active.jpg) + +### Specifying TWCS parameters +You can specify TWCS parameters mentioned above while creating tables, for example: + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64 DEFAULT 0, + memory FLOAT64, + PRIMARY KEY(host)) +WITH ( + 'compaction.type'='twcs', + 'compaction.twcs.max_active_window_runs'='4', + 'compaction.twcs.max_active_window_files'='8', + 'compaction.twcs.max_inactive_window_runs'='1', + 'compaction.twcs.max_inactive_window_files'='2', + 'compaction.twcs.max_output_file_size'='500MB' + ); +``` + +## Strict Window Compaction Strategy (SWCS) and manual compaction + +Unlike TWCS, which assigns one window per SST file based on their maximum timestamps, SWCS assigns SST files to **all** overlapping windows. Consequently, a single SST file may be included in multiple compaction outputs, as its name suggests. Due to its high read amplification during compaction, SWCS is not the default compaction strategy. However, it is useful when you need to manually trigger compaction to reorganize the layout of SST files—especially if an individual SST file spans a large time range that significantly slows down queries. GreptimeDB offers a simple SQL function for triggering compaction: + +```sql +ADMIN COMPACT_TABLE( + , + , + [] +); +``` + +The `` parameter can be either `twcs` or `swcs` (case insensitive) which refer to Time Windowed Compaction Strategy and Strict Window Compaction Strategy respectively. +For the `swcs` strategy, the `` specify the window size (in seconds) for splitting SST files. For example: + +```sql +ADMIN COMPACT_TABLE( + "monitor", + "swcs", + "3600" +); + ++--------------------------------------------------------------------+ +| ADMIN compact_table(Utf8("monitor"),Utf8("swcs"),Utf8("3600")) | ++--------------------------------------------------------------------+ +| 0 | ++--------------------------------------------------------------------+ +1 row in set (0.01 sec) +``` + +When executing this statement, GreptimeDB will split each SST file into segments with a time span of 1 hour (3600 seconds) and merge these segments into a single output, ensuring no overlapping files remain. + +The following diagram shows the process of strict window compression: + +In Figure A, there are 3 overlapping SST files: `[0, 3]` (which includes timestamps 0, 1, 2, and 3), `[3, 8]`, and `[8, 10]`. +The strict window compaction strategy will assign the file `[3, 8]` that covers windows 0, 4, and 8 to three separate windows respectively. This allows it to merge with `[0, 3]` and `[8, 10]` separately. +Figure B shows the final compaction result with three files: `[0, 3]`, `[4, 7]`, and `[8, 10]`. These files do not overlap with each other. + +![compaction-strict-window.jpg](/compaction-strict-window.jpg) \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/administration/manage-data/overview.md b/versioned_docs/version-0.11/user-guide/administration/manage-data/overview.md new file mode 100644 index 000000000..49d8ef10d --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/manage-data/overview.md @@ -0,0 +1,14 @@ +--- +description: Overview of managing data in GreptimeDB, including storage location, basic SQL table operations, data updates, TTL policies, table sharding, region migration, region failover, and compaction. +--- + +# Overview + +* [Storage Location](/user-guide/concepts/storage-location.md) +* [Basic SQL Table Operations](basic-table-operations.md): Learn how to create, alter, and drop tables +* [Update or Delete Data](/user-guide/manage-data/overview.md) +* [Expire Data by Setting TTL](/user-guide/manage-data/overview.md#manage-data-retention-with-ttl-policies) +* [Table Sharding](table-sharding.md): Partition tables by regions +* [Region Migration](region-migration.md): Migrate regions for load balancing +* [Region Failover](/user-guide/administration/manage-data/region-failover.md) +* [Compaction](compaction.md) diff --git a/versioned_docs/version-0.11/user-guide/administration/manage-data/region-failover.md b/versioned_docs/version-0.11/user-guide/administration/manage-data/region-failover.md new file mode 100644 index 000000000..e5c65c72a --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/manage-data/region-failover.md @@ -0,0 +1,85 @@ +--- +description: Covers enabling and understanding region failover in GreptimeDB, which allows for the recovery of regions from failures without data loss, and discusses the impact of read amplification on recovery time. +--- + +# Region Failover + +Region Failover provides the ability to recover regions from region failures without losing data. This is implemented via [Region Migration](/user-guide/administration/manage-data/region-migration.md). + +## Enable the Region Failover + +This feature is only available on GreptimeDB running on distributed mode and + +- Using Kafka WAL +- Using [shared storage](/user-guide/deployments/configuration.md#storage-options) (e.g., AWS S3) + +### Via configuration file +Set the `enable_region_failover=true` in [metasrv](/user-guide/deployments/configuration.md#metasrv-only-configuration) configuration file. + +### Via GreptimeDB Operator + +Set the `meta.enableRegionFailover=true`, e.g., +```bash +helm install greptimedb greptime/greptimedb-cluster \ + --set meta.enableRegionFailover=true \ + ... +``` + +## The recovery time of Region Failover + +The recovery time of Region Failover depends on: + +- number of regions per Topic. +- the Kafka cluster read throughput performance. + +### The read amplification + +In best practices, [the number of topics/partitions supported by a Kafka cluster is limited](https://docs.aws.amazon.com/msk/latest/developerguide/bestpractices.html) (exceeding this number can degrade Kafka cluster performance). +Therefore, we allow multiple regions to share a single topic as the WAL. +However, this may cause to the read amplification issue. + +The data belonging to a specific region consists of data files plus data in the WAL (typically `WAL[LastCheckpoint...Latest]`). The failover of a specific region only requires reading the region's WAL data to reconstruct the memory state, which is called region replaying. However, If multiple regions share a single topic, replaying data for a specific region from the topic requires filtering out unrelated data (i.e., data from other regions). This means replaying data for a specific region from the topic requires reading more data than the actual size of the region's data in the topic, a phenomenon known as read amplification. + +Although multiple regions share the same topic, allowing the Datanode to support more regions, the cost of this approach is read amplification during WAL replay. + +For example, configure 128 topics for [metasrv](/user-guide/deployments/configuration.md#metasrv-only-configuration), and if the whole cluster holds 1024 regions (physical regions), every 8 regions will share one topic. + +![Read Amplification](/remote-wal-read-amplification.png) + +

(Figure1: recovery Region 3 need to read redundant data 7 times larger than the actual size)

+ + +A simple model to estimate the read amplification factor (replay data size/actual data size): + +- For a single topic, if we try to replay all regions that belong to the topic, then the amplification factor would be 7+6+...+1 = 28 times. (The Region WAL data distribution is shown in the Figure 1. Replaying Region 3 will read 7 times redundant data larger than the actual size; Region 6 will read 6 times, and so on) +- When recovering 100 regions (requiring about 13 topics), the amplification factor is approximately 28 \* 13 = 364 times. + +Assuming we have 100 regions to recover, and the actual data size of all regions is 0.5GB, the following table shows the replay data size based on the number of regions per topic. + +| Number of regions per Topic | Number of topics required for 100 Regions | Single topic read amplification factor | Total reading amplification factor | Replay data size (GB) | +| --------------------------- | ----------------------------------------- | -------------------------------------- | ---------------------------------- | ---------------- | +| 1 | 100 | 0 | 0 | 0.5 | +| 2 | 50 | 1 | 50 | 25.5 | +| 4 | 25 | 6 | 150 | 75.5 | +| 8 | 13 | 28 | 364 | 182.5 | +| 16 | 7 | 120 | 840 | 420.5 | + + +The following table shows the recovery time of 100 regions under different read throughput conditions of the Kafka cluster. For example, when providing a read throughput of 300MB/s, recovering 100 regions requires approximately 10 minutes (182.5GB/0.3GB = 10m). + +| Number of regions per Topic | Replay data size (GB) | Kafka throughput 300MB/s- Recovery time (secs) | Kafka throughput 1000MB/s- Recovery time (secs) | +| --------------------------- | ---------------- | --------------------------------------------- | ---------------------------------------------- | +| 1 | 0.5 | 2 | 1 | +| 2 | 25.5 | 85 | 26 | +| 4 | 75.5 | 252 | 76 | +| 8 | 182.5 | 608 | 183 | +| 16 | 420.5 | 1402 | 421 | + + +### Suggestions for improving recovery time + +In the above example, we calculated the recovery time based on the number of Regions contained in each Topic for reference. +We have calculated the recovery time under different Number of regions per Topic configuration for reference. +In actual scenarios, the read amplification may be larger than this model. +If you are very sensitive to recovery time, we recommend that each region have its topic(i.e., Number of regions per Topic is 1). + diff --git a/versioned_docs/version-0.11/user-guide/administration/manage-data/region-migration.md b/versioned_docs/version-0.11/user-guide/administration/manage-data/region-migration.md new file mode 100644 index 000000000..08e6f93db --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/manage-data/region-migration.md @@ -0,0 +1,83 @@ +--- +description: Explanation of how to perform region migration in GreptimeDB, including querying region distribution, selecting a migration destination, executing migration requests, and querying migration states. +--- + +# Region Migration + +Region Migration allows users to move regions between the Datanode. + +:::warning Warning +This feature is only available on GreptimeDB running on distributed mode and +- Using Kafka WAL +- Using [shared storage](/user-guide/deployments/configuration.md#storage-options) (e.g., AWS S3) + +Otherwise, you can't perform a region migration. +::: + + +## Figure out the region distribution of the table. +You need to first query the region distribution of the table, i.e., find out on which Datanode the Regions in the table are located. + +```sql +select b.peer_id as datanode_id, + a.greptime_partition_id as region_id +from information_schema.partitions a left join information_schema.region_peers b +on a.greptime_partition_id = b.region_id where a.table_name='migration_target' order by datanode_id asc; +``` + +For example, have the following region distribution: + +```sql ++-------------+---------------+ +| datanode_id | region_id | ++-------------+---------------+ +| 1 | 4398046511104 | ++-------------+---------------+ +1 row in set (0.01 sec) +``` + + +For more info about the `region_peers` table, please read the [REGION-PEERS](/reference/sql/information-schema/region-peers.md). + +## Select a Datanode as the migration destination. +:::warning Warning +The region migration won't be performed if the `from_peer_id` equals the `to_peer_id`. +::: + +Remember, if you deploy the cluster via the GreptimeDB operator, the `peer_id` of Datanode always starts from 0. For example, if you have a 3 Datanode GreptimeDB cluster, the available `peer_id` will be 0,1,2. + +Finally, you can do a Region migration request via the following SQL: + +```sql +ADMIN migrate_region(4398046511104, 1, 2, 60); +``` + +The parameters of `migrate_region`： + +```sql +ADMIN migrate_region(region_id, from_peer_id, to_peer_id, replay_timeout); +``` + +| Option | Description | Required | | +| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --- | +| `region_id` | The region id. | **Required** | | +| `from_peer_id` | The peer id of the migration source(Datanode). | **Required** | | +| `to_peer_id` | The peer id of the migration destination(Datanode). | **Required** | | +| `replay_timeout` | The timeout(secs) of replay data. If the new Region fails to replay the data within the specified timeout, the migration will fail, however the data in the old Region will not be lost. | Optional | | + +## Query the migration state + +The `migrate_region` function returns the procedure id that executes the migration, queries the procedure state by it: + +```sql +ADMIN procedure_state('538b7476-9f79-4e50-aa9c-b1de90710839') +``` + +If it's done, outputs the state in JSON: + +```json + {"status":"Done"} +``` + +Of course, you can confirm the region distribution by querying from `region_peers` and `partitions` in `information_schema`. + diff --git a/versioned_docs/version-0.11/user-guide/administration/manage-data/table-sharding.md b/versioned_docs/version-0.11/user-guide/administration/manage-data/table-sharding.md new file mode 100644 index 000000000..8f14b3291 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/manage-data/table-sharding.md @@ -0,0 +1,188 @@ +--- +description: Explains table sharding in GreptimeDB, including when to shard a table, partitioning methods, creating distributed tables, inserting data, querying data, and inspecting sharded tables. +--- + +# Table Sharding + +Table sharding is a technique used to distribute a large table into multiple smaller tables. +This practice is commonly employed to enhance the performance of database systems. + +In GreptimeDB, data is logically sharded into partitions. +Since GreptimeDB uses "tables" to group data and SQL to query them, +we adopt the term "partition," a concept frequently used in OLTP databases. + +## When to shard a table + +Inside GreptimeDB, both data management and scheduling are based on the region level, +and each region is corresponding to a table partition. +Thus when you have a table that is too large to fit into a single node, +or the table is too hot to be served by a single node, +you should consider sharding it. + +A region in GreptimeDB has a relative fixed throughput capacity, +and the number of regions in a table determines the total throughput capacity of the table. +If you want to increase the throughput capacity of a table, +you can increase the number of regions in the table. +Ideally the overall throughput of a table should be proportional to the number of regions. + +As for which specific partition column to use or how many regions to create, +it depends on the data distribution and the query pattern. +A general goal is to make the data distribution among regions as even as possible. +And the query pattern should be considered when designing the partition rule set as one query can be processed in parallel among regions. +In other word the query latency is depends on the "slowest" region's latency. + +But notice that the increase of regions will bring some basic consumption and increase the complexity of the system. +You need to consider the requirement of data ingest rate, the query performance, +the data distribution on storage system. +You should shard a table only when necessary. + +For more information on the relationship between partitions and regions, refer to the [Table Sharding](/contributor-guide/frontend/table-sharding.md) section in the contributor guide. + +## Partition + +In GreptimeDB, a table can be horizontally partitioned in multiple ways and it uses the same +partitioning types (and corresponding syntax) as in MySQL. Currently, GreptimeDB supports "RANGE COLUMNS partitioning". + +Each partition includes only a portion of the data from the table, and is +grouped by some column(s) value range. For example, we can partition a table in GreptimeDB like +this: + +```sql +CREATE TABLE (...) +PARTITION ON COLUMNS () ( + +); +``` + +The syntax mainly consists of two parts: + +1. `PARTITION ON COLUMNS` followed by a comma-separated list of column names. This specifies which columns will be used for partitioning. The columns specified here must be of the Tag type (as specified by the PRIMARY KEY). Note that the ranges of all partitions must **not** overlap. + +2. `RULE LIST` is a list of multiple partition rules. Each rule is a combination of a partition name and a partition condition. The expressions here can use `=`, `!=`, `>`, `>=`, `<`, `<=`, `AND`, `OR`, column names, and literals. + +:::tip Note +Currently expressions are not supported in "PARTITION BY RANGE" syntax. +::: + +### Example + +## Create a distributed table + +You can use the MySQL CLI to [connect to GreptimeDB](/user-guide/protocols/mysql.md) and create a distributed table. +The following example creates a table and partitions it based on the `device_id` column. + +```SQL +CREATE TABLE sensor_readings ( + device_id INT16, + reading_value FLOAT64, + ts TIMESTAMP DEFAULT current_timestamp(), + PRIMARY KEY (device_id), + TIME INDEX (ts) +) +PARTITION ON COLUMNS (device_id) ( + device_id < 100, + device_id >= 100 AND device_id < 200, + device_id >= 200 +); +``` + +More partition columns can be used to create more complex partition rules: + +```sql +CREATE TABLE sensor_readings ( + device_id INT, + area STRING, + reading_value FLOAT64, + ts TIMESTAMP DEFAULT current_timestamp(), + PRIMARY KEY (device_id, area), + TIME INDEX (ts) +) +PARTITION ON COLUMNS (device_id, area) ( + device_id < 100 AND area = 'North', + device_id < 100 AND area = 'South', + device_id >= 100 AND area = 'East', + device_id >= 100 AND area = 'West' +); +``` + +The following content uses the `sensor_readings` table with two partition columns as an example. + +## Insert data into the table + +The following code inserts 3 rows into each partition of the `sensor_readings` table. + +```sql +INSERT INTO sensor_readings (device_id, area, reading_value, ts) +VALUES (1, 'North', 22.5, '2023-09-19 08:30:00'), + (10, 'North', 21.8, '2023-09-19 09:45:00'), + (50, 'North', 23.4, '2023-09-19 10:00:00'); + +INSERT INTO sensor_readings (device_id, area, reading_value, ts) +VALUES (20, 'South', 20.1, '2023-09-19 11:15:00'), + (40, 'South', 19.7, '2023-09-19 12:30:00'), + (90, 'South', 18.9, '2023-09-19 13:45:00'); + +INSERT INTO sensor_readings (device_id, area, reading_value, ts) +VALUES (110, 'East', 25.3, '2023-09-19 14:00:00'), + (120, 'East', 26.5, '2023-09-19 15:30:00'), + (130, 'East', 27.8, '2023-09-19 16:45:00'); + +INSERT INTO sensor_readings (device_id, area, reading_value, ts) +VALUES (150, 'West', 24.1, '2023-09-19 17:00:00'), + (170, 'West', 22.9, '2023-09-19 18:15:00'), + (180, 'West', 23.7, '2023-09-19 19:30:00'); +``` + +## Distributed Read + +Simply use the `SELECT` statement to query the data: + +```sql +SELECT * FROM sensor_readings order by reading_value desc LIMIT 5; +``` + +```sql ++-----------+------+---------------+---------------------+ +| device_id | area | reading_value | ts | ++-----------+------+---------------+---------------------+ +| 130 | East | 27.8 | 2023-09-19 16:45:00 | +| 120 | East | 26.5 | 2023-09-19 15:30:00 | +| 110 | East | 25.3 | 2023-09-19 14:00:00 | +| 150 | West | 24.1 | 2023-09-19 17:00:00 | +| 180 | West | 23.7 | 2023-09-19 19:30:00 | ++-----------+------+---------------+---------------------+ +5 rows in set (0.02 sec) +``` + +```sql +SELECT MAX(reading_value) AS max_reading +FROM sensor_readings; +``` + +```sql ++-------------+ +| max_reading | ++-------------+ +| 27.8 | ++-------------+ +1 row in set (0.03 sec) +``` + +```sql +SELECT * FROM sensor_readings +WHERE area = 'North' AND device_id < 50; +``` + +```sql ++-----------+-------+---------------+---------------------+ +| device_id | area | reading_value | ts | ++-----------+-------+---------------+---------------------+ +| 10 | North | 21.8 | 2023-09-19 09:45:00 | +| 1 | North | 22.5 | 2023-09-19 08:30:00 | ++-----------+-------+---------------+---------------------+ +2 rows in set (0.03 sec) +``` + +## Inspect a sharded table + +GreptimeDB provides severals system table to check DB's state. For table sharding information, you can query [`information_schema.partitions`](/reference/sql/information-schema/partitions.md) which gives the detail of partitions inside one table, and [`information_schema.region_peers`](/reference/sql/information-schema/region-peers.md) which gives the runtime distribution of regions. diff --git a/versioned_docs/version-0.11/user-guide/administration/monitoring/export-metrics.md b/versioned_docs/version-0.11/user-guide/administration/monitoring/export-metrics.md new file mode 100644 index 000000000..d0ee2743b --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/monitoring/export-metrics.md @@ -0,0 +1,162 @@ +--- +description: Guide on exporting GreptimeDB metrics to Prometheus and saving metrics to GreptimeDB itself. Includes configuration examples for standalone and distributed cluster modes, and details on various metrics. +--- + +# Export Metrics + +By monitoring metrics, you can assess the state of the database, maintain the deployment without crisis, and diagnose problems when they occur. + +For detailed metrics of GreptimeDB, please refer to the [Metrics Detail](#metrics-detail) section. + +## Start GreptimeDB + +Please refer to the [documentation](/getting-started/installation/overview.md) to learn how to start GreptimeDB. + +## Export metrics to Prometheus + +GreptimeDB supports exporting metrics to Prometheus. +Before configuring export of metrics, you need to setup Prometheus by following their official [documentation](https://prometheus.io/docs/prometheus/latest/installation/). + +To scrape metrics from GreptimeDB, write a Prometheus configuration file and save it as `prometheus.yml`: + +```yml +global: + scrape_interval: 15s + +scrape_configs: + - job_name: 'greptimedb' + static_configs: + # Assuming that GreptimeDB is running locally. + # The default HTTP port of 4000. + - targets: ['localhost:4000'] +``` + +Start Prometheus using the configuration file. +For example, bind-mount the configuration file when starting Prometheus using Docker: + +```bash +docker run \ + -p 9090:9090 \ + -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \ + prom/prometheus +``` + +:::tip NOTE +To avoid accidently exit the Docker container, you may want to run it in the "detached" mode: add the `-d` flag to +the `docker run` command. +::: + +## Save metrics to GreptimeDB itself + +You can also save metrics to GreptimeDB itself for convenient querying and analysis using SQL statements. +This section provides some configuration examples. +For more details about configuration, please refer to the [Monitor metrics options](/user-guide/deployments/configuration.md#monitor-metrics-options). + +### Standalone + +In standalone mode, you can simply use `self_import` to export metrics. +The configuration looks like this: + +```toml +[export_metrics] +enable=true +# The interval of writing metrics. +write_interval = "30s" +[export_metrics.self_import] +db = "information_schema" +``` + +The `db` option specifies the database where metrics are saved. You can change it to a different database. + +### Distributed cluster + +Configuration files need to be written for each component in the cluster. + +#### Frontend + +you can simply use `self_import` to export metrics. + +```toml +[export_metrics] +enable=true +# The interval of writing metrics. +write_interval = "30s" +[export_metrics.self_import] +db = "information_schema" +``` + +The `db` option specifies the database where metrics are saved. You can change it to a different database. + +#### Datanode and Metasrv + +To export metrics for Datanode and Metasrv, you can use the `remote_write` configuration: + +```toml +[export_metrics] +enable=true +write_interval = "30s" +[export_metrics.remote_write] +url = "http://127.0.0.1:4000/v1/prometheus/write?db=system" +``` + +GreptimeDB is compatible with the Prometheus Remote-Write protocol. For more information, please refer to the [Prometheus Remote-Write](/user-guide/ingest-data/for-observerbility/prometheus.md) documentation. + +## Metrics Detail +You can check the output of `curl http://:/metrics` by getting the latest metrics of GreptimeDB. We will add more documents of the metrics sooner. + +### Frontend + +| Key | Type | +|----------------------------------------------|---------| +| greptime_table_operator_ingest_rows | counter | +| greptime_servers_error | counter | +| greptime_servers_http_requests_total | counter | +| greptime_servers_postgres_connection_count | gauge | +| greptime_servers_mysql_connection_count | gauge | +| greptime_query_merge_scan_regions | summary | +| greptime_servers_http_sql_elapsed | summary | +| greptime_query_optimize_physicalplan_elapsed | summary | +| greptime_frontend_handle_sql_elapsed | summary | +| greptime_http_track_metrics | summary | +| greptime_query_create_physicalplan_elapsed | summary | +| greptime_servers_mysql_query_elapsed | summary | +| greptime_servers_http_requests_elapsed | summary | +| greptime_query_execute_plan_elapsed | summary | +| greptime_catalog_kv_get_remote | summary | +| greptime_grpc_region_request | summary | +| greptime_query_merge_scan_poll_elapsed | summary | +| greptime_catalog_kv_get | summary | +| greptime_table_operator_create_table | summary | + + +### Datanode + +| Key | Type | +|--------------------------------------------|---------| +| greptime_opendal_bytes_total | counter | +| greptime_servers_http_requests_total | counter | +| greptime_opendal_requests_total | counter | +| greptime_catalog_catalog_count | gauge | +| greptime_catalog_schema_count | gauge | +| greptime_opendal_requests_duration_seconds | summary | +| greptime_http_track_metrics | summary | +| greptime_servers_http_requests_elapsed | summary | + + +### Meta + +| Key | Type | +|----------------------------------------|---------| +| greptime_meta_create_schema | counter | +| greptime_servers_http_requests_total | counter | +| greptime_meta_create_catalog | counter | +| greptime_meta_heartbeat_connection_num | gauge | +| greptime_meta_txn_request | summary | +| greptime_meta_kv_request | summary | +| greptime_meta_create_schema | summary | +| greptime_meta_create_catalog | summary | +| greptime_meta_handler_execute | summary | +| greptime_servers_http_requests_elapsed | summary | +| greptime_http_track_metrics | summary | +| greptime_meta_procedure_create_table | summary | +| greptime_grpc_region_request | summary | diff --git a/versioned_docs/version-0.11/user-guide/administration/monitoring/overview.md b/versioned_docs/version-0.11/user-guide/administration/monitoring/overview.md new file mode 100644 index 000000000..d439d69e2 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/monitoring/overview.md @@ -0,0 +1,12 @@ +--- +description: Overview of monitoring methods for GreptimeDB, including exporting metrics and tracing. +--- + +# Overview + +Effective database administration relies heavily on monitoring. +You can monitor GreptimeDB using the following methods: + +- [Export Metrics](export-metrics.md) +- [Tracing](tracing.md) + diff --git a/versioned_docs/version-0.11/user-guide/administration/monitoring/tracing.md b/versioned_docs/version-0.11/user-guide/administration/monitoring/tracing.md new file mode 100644 index 000000000..68b944fec --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/monitoring/tracing.md @@ -0,0 +1,115 @@ +--- +description: Guide on using distributed tracing in GreptimeDB with Jaeger. Includes steps for deploying Jaeger, configuring GreptimeDB for tracing, obtaining trace information, and configuring tracing sampling rates. +--- + +# Tracing + +GreptimeDB supports distributed tracing. GreptimeDB exports all collected spans using the gRPC-based OTLP protocol. Users can use [Jaeger](https://www.jaegertracing.io/), [Tempo](https://grafana.com/oss/tempo/) and other OTLP protocol backends that support gRPC to collect the span instrument by GreptimeDB. + +In the [logging section](/user-guide/deployments/configuration.md#logging-options) in the configuration, there are descriptions of configuration items related to tracing, [standalone.example.toml](https://github.com/GreptimeTeam/greptimedb/blob/main/config/standalone.example.toml) provide a reference configuration in the logging section. + +## Tutorial: Use Jaeger to trace GreptimeDB + +[Jaeger](https://www.jaegertracing.io/) is an open source, end-to-end distributed tracing system, originally developed and open sourced by Uber. Its goal is to help developers monitor and debug the request flow in complex microservice architectures. + +Jaeger supports gRPC-based OTLP protocol, so GreptimeDB can export trace data to Jaeger. The following tutorial shows you how to deploy and use Jaeger to track GreptimeDB. + +### Step 1: Deploy Jaeger + +Start a Jaeger instance using the `all-in-one` docker image officially provided by jaeger: + +```bash +docker run --rm -d --name jaeger \ + -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \ + -p 6831:6831/udp \ + -p 6832:6832/udp \ + -p 5778:5778 \ + -p 16686:16686 \ + -p 4317:4317 \ + -p 4318:4318 \ + -p 14250:14250 \ + -p 14268:14268 \ + -p 14269:14269 \ + -p 9411:9411 \ + jaegertracing/all-in-one:latest +``` + +### Step 2: Deploy GreptimeDB + +Write configuration files to allow GreptimeDB to perform tracing. Save the following configuration items as the file `config.toml` + +```Toml +[logging] +enable_otlp_tracing = true +``` + +Then start GreptimeDB using standalone mode + +```bash +greptime standalone start -c config.toml +``` + +Refer to the chapter [MySQL](/user-guide/protocols/mysql.md) on how to connect to GreptimeDB. Run the following SQL statement in MySQL Client: + +```sql +CREATE TABLE host ( + ts timestamp(3) time index, + host STRING PRIMARY KEY, + val BIGINT, +); + +INSERT INTO TABLE host VALUES + (0, 'host1', 0), + (20000, 'host2', 5); + +SELECT * FROM host ORDER BY ts; + +DROP TABLE host; +``` + +### Step 3: Obtain trace information in Jaeger + +1. Go to http://127.0.0.1:16686/ and select the Search tab. +2. Select the `greptime-standalone` service in the service drop-down list. +3. Click **Find Traces** to display trace information. + +![JaegerUI](/jaegerui.png) + +![Select-tracing](/select-tracing.png) + +## Guide: How to configure tracing sampling rate + +GreptimeDB provides many protocols and interfaces for data insertion, query and other functions. You can collect the calling chains of each operation through tracing. However, for some high-frequency operations, collecting all tracing of the operation may be unnecessary and waste storage space. At this time, you can use `tracing_sample_ratio` to set the sampling rate of tracing for various operations, which can greatly reduce the number of exported tracing and facilitate system observation. + +All tracing within GreptimeDB is classified according to the protocol it is connected to and the corresponding operations of that protocol: + +| **protocol** | **request_type** | +|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| grpc | inserts / query.sql / query.logical_plan / query.prom_range / query.empty / ddl.create_database / ddl.create_table / ddl.alter / ddl.drop_table / ddl.truncate_table / ddl.empty / deletes / row_inserts / row_deletes | +| mysql | | +| postgres | | +| otlp | metrics / traces | +| opentsdb | | +| influxdb | write_v1 / write_v2 | +| prometheus | remote_read / remote_write / format_query / instant_query / range_query / labels_query / series_query / label_values_query | +| http | sql / promql + +You can configure different tracing sampling rates through `tracing_sample_ratio`. + +```toml +[logging] +enable_otlp_tracing = true +[logging.tracing_sample_ratio] +default_ratio = 0.0 +[[logging.tracing_sample_ratio.rules]] +protocol = "mysql" +ratio = 1.0 +[[logging.tracing_sample_ratio.rules]] +protocol = "grpc" +request_types = ["inserts"] +ratio = 0.3 +``` + +The above configuration formulates two sampling rules and sets a default sampling rate. GreptimeDB will start matching from the first one according to the sampling rules, and use the first matching sampling rule as the sampling rate of the tracing. If no rule matches, `default_ratio` will be used as the default sampling rate. The range of sampling rate is `[0.0, 1.0]`, `0.0` means not sampling, `1.0` means sampling all tracing. + +For example, according to the rules provided above, all calls accessed using the mysql protocol will be sampled, data inserted using grpc will be sampled 30%, and all remaining tracing will not be sampled. \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/administration/overview.md b/versioned_docs/version-0.11/user-guide/administration/overview.md new file mode 100644 index 000000000..3ed7ecc28 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/overview.md @@ -0,0 +1,18 @@ +--- +description: Overview of GreptimeDB administration strategies and practices, including installation, capacity planning, data management, configuration, disaster recovery, remote WAL setup, monitoring, performance tuning, upgrading, and runtime information. +--- + +# Overview + +This document addresses strategies and practices used in the administration of GreptimeDB. + +* [Installation](/getting-started/installation/overview.md) for GreptimeDB and the [g-t-control](/reference/gtctl.md) command line tool +* [Capacity Plan](/user-guide/administration/capacity-plan.md) for GreptimeDB based on your workload +* [Manage Data](/user-guide/administration/manage-data/overview.md) for avoiding data loss, lower cost and better performance +* Database Configuration, please read the [Configuration](/user-guide/deployments/configuration.md) reference +* GreptimeDB [Disaster Recovery](/user-guide/administration/disaster-recovery/overview.md) +* Cluster Failover for GreptimeDB by [Setting Remote WAL](./remote-wal/quick-start.md) +* [Monitoring metrics](/user-guide/administration/monitoring/export-metrics.md) and [Tracing](/user-guide/administration/monitoring/tracing.md) for GreptimeDB +* [Performance Tuning Tips](/user-guide/administration/performance-tuning-tips.md) +* [Upgrade](/user-guide/administration/upgrade.md) GreptimeDB to a new version +* Get the [runtime information](/user-guide/administration/runtime-info.md) of the cluster diff --git a/versioned_docs/version-0.11/user-guide/administration/performance-tuning-tips.md b/versioned_docs/version-0.11/user-guide/administration/performance-tuning-tips.md new file mode 100644 index 000000000..50c6534e0 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/performance-tuning-tips.md @@ -0,0 +1,187 @@ +--- +description: Tips for tuning GreptimeDB performance, including query optimization, caching, enlarging cache size, scan parallelism, and using append-only tables. Also covers metrics for diagnosing query and ingestion issues. +--- + +# Performance Tuning Tips + +A GreptimeDB instance's default configuration may not fit all use cases. It's important to tune the database configurations and usage according to the scenario. + +GreptimeDB provides various metrics to help monitor and troubleshoot performance issues. The official repository provides [Grafana dashboard templates](https://github.com/GreptimeTeam/greptimedb/tree/main/grafana) for both standalone and cluster modes. + +## Query + +### Metrics + +The following metrics help diagnose query performance issues: +| Metric | Type | Description | +|---|---|---| +| greptime_mito_read_stage_elapsed_bucket | histogram | The elapsed time of different phases of a query in the storage engine. | +| greptime_mito_cache_bytes | gauge | Size of cached contents | +| greptime_mito_cache_hit | counter | Total count of cache hit | +| greptime_mito_cache_miss | counter | Total count of cache miss | + + +### Using cache for object stores + +It's highly recommended to enable the object store read cache and the write cache in the storage engine. This could reduce query time by more than 10 times. + +> Note: Starting from v0.11, when using remote object storage services, local caching (both read and write) is enabled by default. In most cases, you only need to adjust the cache capacity according to your needs. + +The read cache stores objects or ranges on the local disk to avoid fetching the same range from the remote again. The following example shows how to enable the read cache for S3. +- The `cache_path` is the directory to store cached objects, defaults to `{data_home}/object_cache/read` since `v0.11`. +- The `cache_capacity` is the capacity of the cache, defaults to `5Gib` since `v0.11`. It's recommended to leave at least 1/10 of the total disk space for it. + +```toml +[storage] +type = "S3" +bucket = "ap-southeast-1-test-bucket" +root = "your-root" +access_key_id = "****" +secret_access_key = "****" +endpoint = "https://s3.amazonaws.com/" +region = "your-region" +cache_path = "/path/to/s3cache" +cache_capacity = "10G" +``` + +The write cache acts as a write-through cache that stores files on the local disk before uploading them to the object store. This reduces the first query latency. The following example shows how to enable the write cache. +- The `enable_experimental_write_cache` flag enables the write cache, enabled by default when configuring remote object stores since `v0.11`. +- The `experimental_write_cache_size` sets the capacity of the cache, defaults to `5Gib` since `v0.11`. +- The `experimental_write_cache_path` sets the path to store cached files, defaults to `{data_home}/object_cache/write` since `v0.11`. +- The `experimental_write_cache_ttl` sets the TTL of the cached files. + + +```toml +[[region_engine]] +[region_engine.mito] +enable_experimental_write_cache = true +experimental_write_cache_size = "10G" +experimental_write_cache_ttl = "8h" +# experimental_write_cache_path = "/path/to/write/cache" +``` + +### Enlarging cache size + +You can monitor the `greptime_mito_cache_bytes` and `greptime_mito_cache_miss` metrics to determine if you need to increase the cache size. The `type` label in these metrics indicates the type of cache. + +If the `greptime_mito_cache_miss` metric is consistently high and increasing, or if the `greptime_mito_cache_bytes` metric reaches the cache capacity, you may need to adjust the cache size configurations of the storage engine. + +Here's an example: + +```toml +[[region_engine]] +[region_engine.mito] +# Uncomment this option if using object stores. +# enable_experimental_write_cache = true +# Cache size for the write cache. The `type` label value for this cache is `file`. +experimental_write_cache_size = "10G" +# Cache size for SST metadata. The `type` label value for this cache is `sst_meta`. +sst_meta_cache_size = "128MB" +# Cache size for vectors and arrow arrays. The `type` label value for this cache is `vector`. +vector_cache_size = "512MB" +# Cache size for pages of SST row groups. The `type` label value for this cache is `page`. +page_cache_size = "512MB" +# Cache size for time series selector (e.g. `last_value()`). The `type` label value for this cache is `selector_result`. +selector_result_cache_size = "512MB" + +[region_engine.mito.index] +## The max capacity of the index staging directory. +staging_size = "10GB" +``` + +Some tips: +- 1/10 of disk space for the `experimental_write_cache_size` at least +- 1/4 of total memory for the `page_cache_size` at least if the memory usage is under 20% +- Double the cache size if the cache hit ratio is less than 50% +- If using full-text index, leave 1/10 of disk space for the `staging_size` at least + + +### Enlarging scan parallelism + +The storage engine limits the number of concurrent scan tasks to 1/4 of CPU cores for each query. Enlarging the parallelism can reduce the query latency if the machine's workload is relatively low. + +```toml +[[region_engine]] +[region_engine.mito] +scan_parallelism = 8 +``` + +### Using append-only table if possible + +In general, append-only tables have a higher scan performance as the storage engine can skip merging and deduplication. What's more, the query engine can use statistics to speed up some queries if the table is append-only. + +We recommend enabling the [append_mode](/reference/sql/create.md##create-an-append-only-table) for the table if it doesn't require deduplication or performance is prioritized over deduplication. For example, a log table should be append-only as log messages may have the same timestamp. + +## Ingestion + +### Metrics + +The following metrics help diagnose ingestion issues: + +| Metric | Type | Description | +|---|---|---| +| greptime_mito_write_stage_elapsed_bucket | histogram | The elapsed time of different phases of processing a write request in the storage engine | +| greptime_mito_write_buffer_bytes | gauge | The current estimated bytes allocated for the write buffer (memtables). | +| greptime_mito_write_rows_total | counter | The number of rows written to the storage engine | +| greptime_mito_write_stall_total | gauge | The number of rows currently stalled due to high memory pressure | +| greptime_mito_write_reject_total | counter | The number of rows rejected due to high memory pressure | +| raft_engine_sync_log_duration_seconds_bucket | histogram | The elapsed time of flushing the WAL to the disk | +| greptime_mito_flush_elapsed | histogram | The elapsed time of flushing the SST files | + + +### Batching rows + +Batching means sending multiple rows to the database over the same request. This can significantly improve ingestion throughput. A recommended starting point is 1000 rows per batch. You can enlarge the batch size if latency and resource usage are still acceptable. + +### Writing by time window +Although GreptimeDB can handle out-of-order data, it still affects performance. GreptimeDB infers a time window size from ingested data and partitions the data into multiple time windows according to their timestamps. If the written rows are not within the same time window, GreptimeDB needs to split them, which affects write performance. + +Generally, real-time data doesn't have the issues mentioned above as they always use the latest timestamp. If you need to import data with a long time range into the database, we recommend creating the table in advance and [specifying the compaction.twcs.time_window option](/reference/sql/create.md#create-a-table-with-custom-compaction-options). + + +## Schema + +### Using multiple fields + +While designing the schema, we recommend putting related metrics that can be collected together in the same table. This can also improve the write throughput and compression ratio. + + +For example, the following three tables collect the CPU usage metrics. + +```sql +CREATE TABLE IF NOT EXISTS cpu_usage_user ( + hostname STRING NULL, + usage_value BIGINT NULL, + ts TIMESTAMP(9) NOT NULL, + TIME INDEX (ts), + PRIMARY KEY (hostname) +); +CREATE TABLE IF NOT EXISTS cpu_usage_system ( + hostname STRING NULL, + usage_value BIGINT NULL, + ts TIMESTAMP(9) NOT NULL, + TIME INDEX (ts), + PRIMARY KEY (hostname) +); +CREATE TABLE IF NOT EXISTS cpu_usage_idle ( + hostname STRING NULL, + usage_value BIGINT NULL, + ts TIMESTAMP(9) NOT NULL, + TIME INDEX (ts), + PRIMARY KEY (hostname) +); +``` + +We can merge them into one table with three fields. + +```sql +CREATE TABLE IF NOT EXISTS cpu ( + hostname STRING NULL, + usage_user BIGINT NULL, + usage_system BIGINT NULL, + usage_idle BIGINT NULL, + ts TIMESTAMP(9) NOT NULL, + TIME INDEX (ts), + PRIMARY KEY (hostname) +); +``` diff --git a/versioned_docs/version-0.11/user-guide/administration/remote-wal/cluster-deployment.md b/versioned_docs/version-0.11/user-guide/administration/remote-wal/cluster-deployment.md new file mode 100644 index 000000000..c69812604 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/remote-wal/cluster-deployment.md @@ -0,0 +1,233 @@ +--- +description: Guide for deploying a GreptimeDB cluster with Remote WAL in Kubernetes. Includes steps for deploying the GreptimeDB operator, etcd cluster, Kafka cluster, and GreptimeDB cluster with remote WAL settings, as well as writing and querying data. +--- + +# Cluster Deployment + +It's highly recommended to deploy the GreptimeDB cluster in Kubernetes. There are the following prerequires: + +- Kubernetes(>=1.18) + + For testing purposes, you can use Kind or Minikube to create Kubernetes. + +- Helm v3 +- kubectl + +## Step 1: Deploy the GreptimeDB Operator + +Add the chart repository with the following commands: + +``` +helm repo add greptime https://greptimeteam.github.io/helm-charts/ +helm repo update +``` + +Create the `greptimedb-admin` namespace and deploy the GreptimeDB operator in the namespace: + +``` +kubectl create ns greptimedb-admin +helm upgrade --install greptimedb-operator greptime/greptimedb-operator -n greptimedb-admin +``` + +## Step 2: Deploy the etcd Cluster + +The GreptimeDB cluster needs the etcd cluster as the backend storage of the metasrv. We recommend using the Bitnami etcd [chart](https://github.com/bitnami/charts/blob/main/bitnami/etcd/README.md) to deploy the etcd cluster: + +``` +kubectl create ns metasrv-store +helm upgrade --install etcd oci://registry-1.docker.io/bitnamicharts/etcd \ + --set replicaCount=3 \ + --set auth.rbac.create=false \ + --set auth.rbac.token.enabled=false \ + -n metasrv-store +``` + +When the etcd cluster is ready, you can use the following command to check the cluster health: + +``` +kubectl -n metasrv-store \ + exec etcd-0 -- etcdctl \ + --endpoints etcd-0.etcd-headless.metasrv-store:2379,etcd-1.etcd-headless.metasrv-store:2379,etcd-2.etcd-headless.metasrv-store:2379 \ + endpoint status +``` + +## Step 3: Deploy the Kafka Cluster + +We recommend using [strimzi-kafka-operator](https://github.com/strimzi/strimzi-kafka-operator) to deploy the Kafka cluster in KRaft mode. + +Create the `kafka` namespace and install the strimzi-kafka-operator: + +``` +kubectl create namespace kafka +kubectl create -f 'https://strimzi.io/install/latest?namespace=kafka' -n kafka +``` + +When the operator is ready, use the following spec to create the Kafka cluster: + +``` +apiVersion: kafka.strimzi.io/v1beta2 +kind: KafkaNodePool +metadata: + name: dual-role + labels: + strimzi.io/cluster: kafka-wal +spec: + replicas: 3 + roles: + - controller + - broker + storage: + type: jbod + volumes: + - id: 0 + type: persistent-claim + size: 20Gi + deleteClaim: false +--- + +apiVersion: kafka.strimzi.io/v1beta2 +kind: Kafka +metadata: + name: kafka-wal + annotations: + strimzi.io/node-pools: enabled + strimzi.io/kraft: enabled +spec: + kafka: + version: 3.7.0 + metadataVersion: 3.7-IV4 + listeners: + - name: plain + port: 9092 + type: internal + tls: false + - name: tls + port: 9093 + type: internal + tls: true + config: + offsets.topic.replication.factor: 3 + transaction.state.log.replication.factor: 3 + transaction.state.log.min.isr: 2 + default.replication.factor: 3 + min.insync.replicas: 2 + entityOperator: + topicOperator: {} + userOperator: {} +``` + +Save the spec as `kafka-wal.yaml` and apply in the Kubernetes: + +``` +kubectl apply -f kafka-wal.yaml -n kafka +``` + +After the Kafka cluster is ready, check the status: + +``` +kubectl get kafka -n kafka +``` + +The expected output will be: + +``` +NAME DESIRED KAFKA REPLICAS DESIRED ZK REPLICAS READY METADATA STATE WARNINGS +kafka-wal True KRaft +``` + +## Step 4: Deploy the GreptimeDB Cluster with Remote WAL Settings + +Create a GreptimeDB cluster with remote WAL settings: + +``` +cat <= 5 AND n < 9, + n >= 9 +); +``` + +Write the data: + +``` +INSERT INTO dist_table(n, row_id) VALUES (1, 1); +INSERT INTO dist_table(n, row_id) VALUES (2, 2); +INSERT INTO dist_table(n, row_id) VALUES (3, 3); +INSERT INTO dist_table(n, row_id) VALUES (4, 4); +INSERT INTO dist_table(n, row_id) VALUES (5, 5); +INSERT INTO dist_table(n, row_id) VALUES (6, 6); +INSERT INTO dist_table(n, row_id) VALUES (7, 7); +INSERT INTO dist_table(n, row_id) VALUES (8, 8); +INSERT INTO dist_table(n, row_id) VALUES (9, 9); +INSERT INTO dist_table(n, row_id) VALUES (10, 10); +INSERT INTO dist_table(n, row_id) VALUES (11, 11); +INSERT INTO dist_table(n, row_id) VALUES (12, 12); +``` + +And query the data: + +``` +SELECT * from dist_table; +``` diff --git a/versioned_docs/version-0.11/user-guide/administration/remote-wal/quick-start.md b/versioned_docs/version-0.11/user-guide/administration/remote-wal/quick-start.md new file mode 100644 index 000000000..b716d2ff4 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/remote-wal/quick-start.md @@ -0,0 +1,172 @@ +--- +description: Quick start guide for setting up Remote WAL using Docker and Kafka for GreptimeDB. Includes steps for creating a Docker network, starting Kafka and GreptimeDB containers, writing and querying data, and cleaning up. +--- + +# Quick Start + +## What's Remote WAL + +[WAL](/contributor-guide/datanode/wal.md#introduction)(Write-Ahead Logging) is a crucial component in GreptimeDB that persistently records every data modification to ensure no memory-cached data loss. We implement WAL as a module in the [Datanode](/user-guide/concepts/why-greptimedb.md) service using a persistent embedded storage engine, [raft-engine](https://github.com/tikv/raft-engine). When deploying GreptimeDB in the public cloud, we can persistently store WAL data in cloud storage(AWS EBS, GCP persistent disk, etc.) to achieve 0 RPO([Recovery Point Objective](https://en.wikipedia.org/wiki/Disaster_recovery#Recovery_Point_Objective)). However, the deployment has a significant RTO([Recovery Time Objective](https://en.wikipedia.org/wiki/Disaster_recovery#Recovery_Time_Objective)) because WAL is tightly coupled with Datanode. Additionally, the rafe-engine can't support multiple log subscriptions, which makes it difficult to implement region hot standby and region migration. + +To resolve the above problems, we decided to design and implement a remote WAL. The remote WAL decouples the WAL from the Datanode to the remote service, which we chose to be [Apache Kafka](https://kafka.apache.org/). Apache Kafka is widely adopted in stream processing and exhibits excellent distributed fault tolerance and a subscription mechanism based on topics. With the release [v0.5.0](https://github.com/GreptimeTeam/greptimedb/releases/tag/v0.5.0), we introduced Apache Kafka as an optional storage engine for WAL. + +## Run Standalone GreptimeDB with Remote WAL + +It's very easy to experience remote WAL by using the Docker with the following steps. In this quick start, we will create a Kafka cluster with one broker in KRaft mode and use it as remote WAL for the standalone GreptimeDB. + +### Step 1: Create a user-defined bridge of the Docker network + +The user-defined bridge can help us create a bridge network to connect multiple containers: + +``` +docker network create greptimedb-remote-wal +``` + +### Step 2: Start the Kafka Service + +Use the KRaft mode to start the singleton Kafka service: + +``` +docker run \ + --name kafka --rm \ + --network greptimedb-remote-wal \ + -p 9092:9092 \ + -e KAFKA_CFG_NODE_ID="1" \ + -e KAFKA_CFG_PROCESS_ROLES="broker,controller" \ + -e KAFKA_CFG_CONTROLLER_QUORUM_VOTERS="1@kafka:9093" \ + -e KAFKA_CFG_ADVERTISED_LISTENERS="PLAINTEXT://kafka:9092" \ + -e KAFKA_CFG_CONTROLLER_LISTENER_NAMES="CONTROLLER" \ + -e KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP="CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT" \ + -e KAFKA_CFG_LISTENERS="PLAINTEXT://:9092,CONTROLLER://:9093" \ + -e ALLOW_PLAINTEXT_LISTENER="yes" \ + -e KAFKA_BROKER_ID="1" \ + -e KAFKA_CFG_LOG_DIRS="/bitnami/kafka/data" \ + -v $(pwd)/kafka-data:/bitnami/kafka/data \ + bitnami/kafka:3.6.0 +``` + +:::tip NOTE +To avoid accidently exit the Docker container, you may want to run it in the "detached" mode: add the `-d` flag to +the `docker run` command. +::: + +The data will be stored in `$(pwd)/kafka-data`. + +### Step 3: Start the GreptimeDB with Remote WAL Configurations + +Use the Kafka wal provider to start the standalone GreptimeDB: + +``` +docker run \ + --network greptimedb-remote-wal \ + -p 4000-4003:4000-4003 \ + -v "$(pwd)/greptimedb:/tmp/greptimedb" \ + --name greptimedb --rm \ + -e GREPTIMEDB_STANDALONE__WAL__PROVIDER="kafka" \ + -e GREPTIMEDB_STANDALONE__WAL__BROKER_ENDPOINTS="kafka:9092" \ + greptime/greptimedb standalone start \ + --http-addr 0.0.0.0:4000 \ + --rpc-addr 0.0.0.0:4001 \ + --mysql-addr 0.0.0.0:4002 \ + --postgres-addr 0.0.0.0:4003 +``` + +:::tip NOTE +To avoid accidently exit the Docker container, you may want to run it in the "detached" mode: add the `-d` flag to +the `docker run` command. +::: + +We use the [environment variables](/user-guide/deployments/configuration.md#environment-variable) to specify the provider: + +- `GREPTIMEDB_STANDALONE__WAL__PROVIDER`: Set `kafka` to use Kafka remote WAL; +- `GREPTIMEDB_STANDALONE__WAL__BROKER_ENDPOINTS`: Specify the advertised listeners for all brokers in the Kafka cluster. In this example, we will use the Kafka container name, and the bridge network will resolve it into IPv4; + +### Step 4: Write and Query Data + +There are many ways to connect to GreptimeDB, so let's choose `mysql`. + +1. **Connect the GreptimeDB** + + ``` + mysql -h 127.0.0.1 -P 4002 + ``` + + +2. **Write the testing data** + + - Create the table `system_metrics` + + ```sql + CREATE TABLE IF NOT EXISTS system_metrics ( + host STRING, + idc STRING, + cpu_util DOUBLE, + memory_util DOUBLE, + disk_util DOUBLE, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY(host, idc), + TIME INDEX(ts) + ); + ``` + + - Write the testing data + + ```sql + INSERT INTO system_metrics + VALUES + ("host1", "idc_a", 11.8, 10.3, 10.3, 1667446797450), + ("host1", "idc_a", 80.1, 70.3, 90.0, 1667446797550), + ("host1", "idc_b", 50.0, 66.7, 40.6, 1667446797650), + ("host1", "idc_b", 51.0, 66.5, 39.6, 1667446797750), + ("host1", "idc_b", 52.0, 66.9, 70.6, 1667446797850), + ("host1", "idc_b", 53.0, 63.0, 50.6, 1667446797950), + ("host1", "idc_b", 78.0, 66.7, 20.6, 1667446798050), + ("host1", "idc_b", 68.0, 63.9, 50.6, 1667446798150), + ("host1", "idc_b", 90.0, 39.9, 60.6, 1667446798250); + ``` + +3. **Query the data** + + ```sql + SELECT * FROM system_metrics; + ``` + +4. **Query the Kafka topics**: + + ``` + # List the Kafka topics. + docker exec kafka /opt/bitnami/kafka/bin/kafka-topics.sh --list --bootstrap-server localhost:9092 + ``` + + By default, all the topics start with `greptimedb_wal_topic`, for example: + + ``` + docker exec kafka /opt/bitnami/kafka/bin/kafka-topics.sh --list --bootstrap-server localhost:9092 + greptimedb_wal_topic_0 + greptimedb_wal_topic_1 + greptimedb_wal_topic_10 + ... + +### Step 5: Cleanup + +- Stop the greptimedb and Kafka + + ``` + docker stop greptimedb + docker stop kafka + ``` + +- Remove the user-defined bridge + + ``` + docker network rm greptimedb-remote-wal + ``` + +- Remove the data + + The data will be stored in the working directory that runs greptimedb: + + ``` + rm -r /greptimedb + rm -r /kafka-data + ``` diff --git a/versioned_docs/version-0.11/user-guide/administration/runtime-info.md b/versioned_docs/version-0.11/user-guide/administration/runtime-info.md new file mode 100644 index 000000000..095d3eaaa --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/runtime-info.md @@ -0,0 +1,30 @@ +--- +description: Provides access to system metadata through the INFORMATION_SCHEMA database, including cluster topology and table regions distribution. Examples of SQL queries to retrieve region IDs and distribution are included. +--- + +# Runtime Information + +The `INFORMATION_SCHEMA` database provides access to system metadata, such as the name of a database or table, the data type of a column, etc. + +* Find the topology information of the cluster though [CLUSTER_INFO](/reference/sql/information-schema/cluster-info.md) table. +* Find the table regions distribution though [PARTITIONS](/reference/sql/information-schema/partitions.md) and [REGION_PEERS](/reference/sql/information-schema/region-peers.md) tables. + +For example, find all the region id of a table: + +```sql +SELECT greptime_partition_id FROM PARTITIONS WHERE table_name = 'monitor' +``` + +Find the distribution of all regions in a table: + +```sql +SELECT b.peer_id as datanode_id, + a.greptime_partition_id as region_id +FROM information_schema.partitions a LEFT JOIN information_schema.region_peers b +ON a.greptime_partition_id = b.region_id +WHERE a.table_name='monitor' +ORDER BY datanode_id ASC +``` + +For more information about the `INFORMATION_SCHEMA` database, +Please read the [reference](/reference/sql/information-schema/overview.md). diff --git a/versioned_docs/version-0.11/user-guide/administration/upgrade.md b/versioned_docs/version-0.11/user-guide/administration/upgrade.md new file mode 100644 index 000000000..3ebab5634 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/administration/upgrade.md @@ -0,0 +1,181 @@ +--- +description: Instructions on upgrading GreptimeDB using the built-in CLI tool, including exporting and importing data and schemas, and a complete example for upgrading. +--- + +# Upgrade + +From `v0.4`, we provide a built-in utility to help upgrade your previous GreptimeDB deployment to the latest version if there are some breaking changes. +It's recommended to use this method to upgrade your GreptimeDB with different versions. + +The lowest version that can be upgraded by this tool is `v0.3.0`. + +## CLI + +This tool is in the `greptime` binary. You need to prepare the corresponding binary of target version before start. + +```shell +greptime cli export --help +``` + +And the help text is as follows: + +```shell +greptime-cli-export + +USAGE: + greptime cli export [OPTIONS] --addr --output-dir --target + +OPTIONS: + --addr + Server address to connect + + --output-dir + Directory to put the exported data. E.g.: /tmp/greptimedb-export + + --database + The name of the catalog to export + + [default: greptime-*] + + -j, --export-jobs + Parallelism of the export + + [default: 1] + + --max-retry + Max retry times for each job + + [default: 3] + + -t, --target + Things to export + + [default: all] + + Possible values: + - schema: Export all table schemas, corresponding to `SHOW CREATE TABLE` + - data: Export all table data, corresponding to `COPY DATABASE TO` + - all: Export all table schemas and data at once + + --log-dir + + + --start-time + A half-open time range: [start_time, end_time). The start of the time range (time-index column) for data export + + --end-time + A half-open time range: [start_time, end_time). The end of the time range (time-index column) for data export + + --log-level + + + --auth-basic + The basic authentication for connecting to the server + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version +``` + +Here explains the meaning of some important options + +- `--addr`: The server address of the Frontend node or Standalone process. +- `--output-dir`: The directory to put the exported data. Give a path at your current machine. The exported SQL files will be put in that directory. +- `-target`: Specifies the data to export. The `schema` option exports the `CREATE TABLE` clause for each table. The `data` option exports the data of each database along with the `COPY FROM` clause. By default, all data is exported for both `schema` and `data`. It is recommended not to specify this option that use the default value to export all data. + +For a complete upgrade, you will need to execute this tools twice with each target options. + +## Upgrade from 0.8.x + +Here is a complete example for upgrading from `v0.8.x` to `v0.9.x`. + +### Export `CREATE TABLE`s and table data at once + +Assuming the HTTP service port of the old database is `4000`. + +```shell +greptime cli export --addr '127.0.0.1:4000' --output-dir /tmp/greptimedb-export +``` + +If success, you will see something like this + +```log +2024-08-01T06:32:26.547809Z INFO cmd: Starting app: greptime-cli +2024-08-01T06:32:27.239639Z INFO cmd::cli::export: Finished exporting greptime.greptime_private with 0 table schemas to path: /tmp/greptimedb-export/greptime/greptime_private/ +2024-08-01T06:32:27.540696Z INFO cmd::cli::export: Finished exporting greptime.pg_catalog with 0 table schemas to path: /tmp/greptimedb-export/greptime/pg_catalog/ +2024-08-01T06:32:27.832018Z INFO cmd::cli::export: Finished exporting greptime.public with 0 table schemas to path: /tmp/greptimedb-export/greptime/public/ +2024-08-01T06:32:28.272054Z INFO cmd::cli::export: Finished exporting greptime.test with 1 table schemas to path: /tmp/greptimedb-export/greptime/test/ +2024-08-01T06:32:28.272166Z INFO cmd::cli::export: Success 4/4 jobs, cost: 1.724222791s +2024-08-01T06:32:28.416532Z INFO cmd::cli::export: Executing sql: COPY DATABASE "greptime"."greptime_private" TO '/tmp/greptimedb-export/greptime/greptime_private/' WITH (FORMAT='parquet'); +2024-08-01T06:32:28.556017Z INFO cmd::cli::export: Finished exporting greptime.greptime_private data into path: /tmp/greptimedb-export/greptime/greptime_private/ +2024-08-01T06:32:28.556330Z INFO cmd::cli::export: Finished exporting greptime.greptime_private copy_from.sql +2024-08-01T06:32:28.556424Z INFO cmd::cli::export: Executing sql: COPY DATABASE "greptime"."pg_catalog" TO '/tmp/greptimedb-export/greptime/pg_catalog/' WITH (FORMAT='parquet'); +2024-08-01T06:32:28.738719Z INFO cmd::cli::export: Finished exporting greptime.pg_catalog data into path: /tmp/greptimedb-export/greptime/pg_catalog/ +2024-08-01T06:32:28.738998Z INFO cmd::cli::export: Finished exporting greptime.pg_catalog copy_from.sql +2024-08-01T06:32:28.739098Z INFO cmd::cli::export: Executing sql: COPY DATABASE "greptime"."public" TO '/tmp/greptimedb-export/greptime/public/' WITH (FORMAT='parquet'); +2024-08-01T06:32:28.875600Z INFO cmd::cli::export: Finished exporting greptime.public data into path: /tmp/greptimedb-export/greptime/public/ +2024-08-01T06:32:28.875888Z INFO cmd::cli::export: Finished exporting greptime.public copy_from.sql +2024-08-01T06:32:28.876005Z INFO cmd::cli::export: Executing sql: COPY DATABASE "greptime"."test" TO '/tmp/greptimedb-export/greptime/test/' WITH (FORMAT='parquet'); +2024-08-01T06:32:29.053681Z INFO cmd::cli::export: Finished exporting greptime.test data into path: /tmp/greptimedb-export/greptime/test/ +2024-08-01T06:32:29.054104Z INFO cmd::cli::export: Finished exporting greptime.test copy_from.sql +2024-08-01T06:32:29.054162Z INFO cmd::cli::export: Success 4/4 jobs, costs: 781.98875ms +2024-08-01T06:32:29.054181Z INFO cmd: Goodbye! +``` + +And now the output directory structure is + +```plaintext +/tmp/greptimedb-export/ +├── greptime/public +│   ├── copy_from.sql +│   ├── create_tables.sql +│   ├── up.parquet +│   └── other-tables.parquet +``` + +The content includes `create_tables.sql`, `copy_from.sql`, and the parquet files for each table in the DB `greptime-public`. The `create_tables.sql` contains the create table statements for all tables in the current DB, while `copy_from.sql` includes a single `COPY DATABASE FROM` statement used to copy data files to the target DB. The remaining parquet files are the data files for each table. + +### Import table schema and data + +Then you need to execute SQL files generated by the previous step. First is `create_tables.sql`. SQL generated in previous step is in PostgreSQL dialect, we will use [PostgreSQL protocol](/user-guide/protocols/postgresql.md) in the following steps. This document assumes the client is `psql`. + +:::tip NOTICE +From this step, all the operation is done in the new version of GreptimeDB. + +The default port of PostgreSQL protocol is `4003`. +::: + +Before executing the following command, you need first to create the corresponding database in your new deployment (but in this example, the database `greptime-public` is the default one). + +This command will create all the tables in the new version of GreptimeDB. + +```shell +psql -h 127.0.0.1 -p 4003 -d public -f /tmp/greptimedb-export/greptime/public/create_tables.sql +``` + +And then import the data + +```shell +psql -h 127.0.0.1 -p 4003 -d public -f /tmp/greptimedb-export/greptime/public/copy_from.sql +``` + +### Clean up + +At this step all the data is migrated. You can check the data in the new cluster. + +After confirming that the data is correct, you can clean up the old cluster and the temporary `--output-dir`. `/tmp/greptimedb-export` at this example. + +## Recommended overall process + +This section gives a recommended overall process for upgrading GreptimeDB smoothly. You can skip this section if your environment can go offline on the upgrade progress. + +1. Create a brand new v0.9.x cluster. +2. Use the v0.9.x CLI tool to export and import `create-table`. +3. Switch the workload to the new cluster. +4. Use the v0.9.x CLI tool to export and import `database-data`. + +Caveats +- Changes to table structure between step 2 and 3 will be lost +- Old data is invisible in new cluster until step 4 is done diff --git a/versioned_docs/version-0.11/user-guide/concepts/architecture.md b/versioned_docs/version-0.11/user-guide/concepts/architecture.md new file mode 100644 index 000000000..566653edd --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/concepts/architecture.md @@ -0,0 +1,29 @@ +--- +description: Outlines the architecture of GreptimeDB, including its main components Metasrv, Frontend, and Datanodes. It explains how these components work together to form a robust database cluster and provides links to detailed documentation for each component. +--- + +# Architecture + +![architecture](/architecture-3.png) + +In order to form a robust database cluster and keep complexity at an acceptable +level, there are three main components in GreptimeDB architecture: Datanode, +Frontend and Metasrv. + +- [**Metasrv**](/contributor-guide/metasrv/overview.md) is the central command of + GreptimeDB cluster. In a typical cluster deployment, at least three nodes is required to + setup a reliable _Metasrv_ mini-cluster. _Meta_ manages database and table + information, including how data spread across the cluster and where to route + requests to. It also keeps monitoring availability and performance of \_Datanode_s, + to ensure its routing table is valid and up-to-date. +- [**Frontend**](/contributor-guide/frontend/overview.md) is a stateless + component that can scale to as many as needed. It accepts incoming requests, + authenticates them, translates them from various protocols into GreptimeDB + internal gRPC, and forwards to certain \_Datanode_s under guidance from Metasrv by table sharding. +- [**Datanodes**](/contributor-guide/datanode/overview.md) hold regions of + tables in Greptime DB cluster. It accepts read and write requests sent + from _Frontend_, executes them against its data, and returns the handle results. + +These three components will be combined in a single binary as GreptimeDB standalone mode, for local or embedded development. + +You can refer to [architecture](/contributor-guide/overview.md) in contributor guide to learn more details about how components work together. diff --git a/versioned_docs/version-0.11/user-guide/concepts/data-model.md b/versioned_docs/version-0.11/user-guide/concepts/data-model.md new file mode 100644 index 000000000..5f9f51a2d --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/concepts/data-model.md @@ -0,0 +1,102 @@ +--- +description: Describes the data model of GreptimeDB, focusing on time-series tables. It explains the organization of data into tables with tags, timestamps, and fields, and provides examples of metric and log tables. Design considerations and schema management are also discussed. +--- + +# Data Model + +## Model + +GreptimeDB uses the time-series table to guide the organization, compression, and expiration management of data. +The data model is mainly based on the table model in relational databases while considering the characteristics of metrics, logs, and events data. + +All data in GreptimeDB is organized into tables with names. Each data item in a table consists of three types of columns: `Tag`, `Timestamp`, and `Field`. + +- Table names are often the same as the indicator names, log source names, or metric names. +- `Tag` columns store metadata that is commonly queried. + The values in `Tag` columns are labels attached to the collected sources, + generally used to describe a particular characteristic of these sources. + `Tag` columns are indexed, making queries on tags performant. +- `Timestamp` is the root of a metrics, logs, and events database. + It represents the date and time when the data was generated. + Timestamps are indexed, making queries on timestamps performant. + A table can only have one timestamp column, which is called time index. +- The other columns are `Field` columns. + Fields contain the data indicators or log contents that are collected. + These fields are generally numerical values or string values, + but may also be other types of data, such as geographic locations. + Fields are not indexed by default, + and queries on field values scan all data in the table. It can be resource-intensive and underperformant. + However, the string field can turn on the [full-text index](/user-guide/logs/query-logs.md#full-text-index-for-accelerated-search) to speed up queries such as log searching. + +### Metric Table + +Suppose we have a time-series table called `system_metrics` that monitors the resource usage of a standalone device: + +```sql +CREATE TABLE IF NOT EXISTS system_metrics ( + host STRING, + idc STRING, + cpu_util DOUBLE, + memory_util DOUBLE, + disk_util DOUBLE, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY(host, idc), + TIME INDEX(ts) +); +``` + +The data model for this table is as follows: + +![time-series-table-model](/time-series-data-model.svg) + +Those are very similar to the table model everyone is familiar with. The difference lies in the `Timestamp` constraint, which is used to specify the `ts` column as the time index column of this table. + +- The table name here is `system_metrics`. +- For `Tag` columns, the `host` column represents the hostname of the collected standalone machine, + while the `idc` column shows the data center where the machine is located. + These are queried metadata and can be effectively used to filter data when querying. +- The `Timestamp` column `ts` represents the time when the data is collected. + It can be effectively used when querying data with a time range. +- The `cpu_util`, `memory_util`, `disk_util`, and `load` columns in the `Field` columns represent + the CPU utilization, memory utilization, disk utilization, and load of the machine, respectively. + These columns contain the actual data and are not indexed, but they can be efficiently computed and evaluated, such as the latest value, maximum/minimum value, average, percentage, and so on. Please avoid using `Field` columns in query conditions, + which is highly resource-intensive and underperformant. + +### Log Table +Another example is creating a log table for access logs: + +```sql +CREATE TABLE access_logs ( + access_time TIMESTAMP TIME INDEX, + remote_addr STRING, + http_status STRING, + http_method STRING, + http_refer STRING, + user_agent STRING, + request STRING FULLTEXT, + PRIMARY KEY (remote_addr, http_status, http_method, http_refer, user_agent) +) +``` + +- The time index column is `access_time`. +- `remote_addr`, `http_status`, `http_method`, `http_refer` and `user_agent` are tags. +- `request` is a field that enables full-text index by the [`FULLTEXT` column option](/reference/sql/create.md#fulltext-column-option). + +To learn how to indicate `Tag`, `Timestamp`, and `Field` columns, Please refer to [table management](/user-guide/administration/manage-data/basic-table-operations.md#create-a-table) and [CREATE statement](/reference/sql/create.md). + +Of course, you can place metrics and logs in a single table at any time, which is also a key capability provided by GreptimeDB. + +## Design Considerations + +GreptimeDB is designed on top of Table for the following reasons: + +- The Table model has a broad group of users and it's easy to learn, that we just introduced the concept of time index to the metrics, logs, and events. +- Schema is meta-data to describe data characteristics, and it's more convenient for users to manage and maintain. By introducing the concept of schema version, we can better manage data compatibility. +- Schema brings enormous benefits for optimizing storage and computing with its information like types, lengths, etc., on which we could conduct targeted optimizations. +- When we have the Table model, it's natural for us to introduce SQL and use it to process association analysis and aggregation queries between various tables, offsetting the learning and use costs for users. +- Use a multi-value model where a row of data can have multiple field columns, + instead of the single-value model adopted by OpenTSDB and Prometheus. + The multi-value model is used to model data sources, where a metric can have multiple values represented by fields. + The advantage of the multi-value model is that it can write or read multiple values to the database at once, reducing transfer traffic and simplifying queries. In contrast, the single-value model requires splitting the data into multiple records. Read the [blog](https://greptime.com/blogs/2024-05-09-prometheus) for more detailed benefits of multi-value mode. + +GreptimeDB uses SQL to manage table schema. Please refer to [table management](/user-guide/administration/manage-data/basic-table-operations.md) for more information. However, our definition of schema is not mandatory and leans towards a **schemaless** approach, similar to MongoDB. For more details, see [Automatic Schema Generation](/user-guide/ingest-data/overview.md#automatic-schema-generation). diff --git a/versioned_docs/version-0.11/user-guide/concepts/features-that-you-concern.md b/versioned_docs/version-0.11/user-guide/concepts/features-that-you-concern.md new file mode 100644 index 000000000..9e8c99576 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/concepts/features-that-you-concern.md @@ -0,0 +1,72 @@ +--- +description: Answers common questions about GreptimeDB's features, including support for logs, events, updates, deletions, TTL policies, compression rates, high cardinality, continuous aggregation, cloud storage, performance, disaster recovery, geospatial indexing, and JSON support. +--- + +# Features that You Concern + +## Does GreptimeDB support logs or events? + +Yes. Since v0.9.0, GreptimeDB treats all time series as contextual events with timestamps, and thus unifies the processing of metrics, logs, and events. It supports analyzing metrics, logs, and events with SQL, PromQL, and streaming with continuous aggregation. + +Please read the [log user guide](/user-guide/logs/overview.md). + +## Does GreptimeDB support updates? + +Sort of, Please refer to the [update data](/user-guide/manage-data/overview.md#update-data) for more information. + +## Does GreptimeDB support deletion? + +Yes, it does. Please refer to the [delete data](/user-guide/manage-data/overview.md#delete-data) for more information. + +## Can I set TTL or retention policy for different tables or measurements? + +Of course. Please refer to the document [on managing data retention with TTL policies](/user-guide/manage-data/overview.md#manage-data-retention-with-ttl-policies). + +## What are the compression rates of GreptimeDB? + +The answer is it depends. +GreptimeDB uses the columnar storage layout, and compresses time series data by best-in-class algorithms. +And it will select the most suitable compression algorithm based on the column data's statistics and distribution. +GreptimeDB will provide rollups that can compress data more compactly but lose accuracy. + +Therefore, the data compression rate of GreptimeDB may be between 2 and several hundred times, depending on the characteristics of your data and whether you can accept accuracy loss. + +## How does GreptimeDB address the high cardinality issue? + +GreptimeDB resolves this issue by: + +- **Sharding**: It distributes the data and index between different region servers. Read the [architecture](./architecture.md) of GreptimeDB. +- **Smart Indexing**: It doesn't create the inverted index for every tag mandatorily, but chooses a proper index type based on the tag column's statistics and query workload. Find more explanation in this [blog](https://greptime.com/blogs/2022-12-21-storage-engine-design#smart-indexing). +- **MPP**: Besides the indexing capability, the query engine will use the vectorize execution query engine to execute the query in parallel and distributed. + +## Does GreptimeDB support continuous aggregate or downsampling? + +Since 0.8, GreptimeDB added a new function called `Flow`, which is used for continuous aggregation. Please read the [user guide](/user-guide/continuous-aggregation/overview.md). + +## Can I store data in object storage in the cloud? + +Yes, GreptimeDB's data access layer is based on [OpenDAL](https://github.com/apache/incubator-opendal), which supports most kinds of object storage services. +The data can be stored in cost-effective cloud storage services such as AWS S3 or Azure Blob Storage, please refer to storage configuration guide [here](./../deployments/configuration.md#storage-options). + +GreptimeDB also offers a fully-managed cloud service [GreptimeCloud](https://greptime.com/product/cloud) to help you manage data in the cloud. + +## How is GreptimeDB's performance compared to other solutions? + +Please read the performance benchmark reports: + +* [GreptimeDB vs. InfluxDB](https://greptime.com/blogs/2024-08-07-performance-benchmark) +* [GreptimeDB vs. Grafana Mimir](https://greptime.com/blogs/2024-08-02-datanode-benchmark) +* [GreptimeDB vs. ClickHouse vs. ElasticSearch](https://greptime.com/blogs/2024-08-22-log-benchmark) +* [GreptimeDB vs. SQLite](https://greptime.com/blogs/2024-08-30-sqlite) + +## Does GreptimeDB have disaster recovery solutions? + +Yes. Please refer to [disaster recovery](/user-guide/administration/disaster-recovery/overview.md). + +## Does GeptimeDB has geospatial index? + +Yes. We offer [built-in functions](/reference/sql/functions/geo.md) for Geohash, H3 and S2 index. + +## Any JSON support? + +See [JSON functions](/reference/sql/functions/overview.md#json-functions). diff --git a/versioned_docs/version-0.11/user-guide/concepts/key-concepts.md b/versioned_docs/version-0.11/user-guide/concepts/key-concepts.md new file mode 100644 index 000000000..829662b84 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/concepts/key-concepts.md @@ -0,0 +1,55 @@ +--- +description: Introduces the key concepts of GreptimeDB, including databases, time-series tables, table regions, data types, indexes, views, and flows. It explains how these components work together to manage and serve data in GreptimeDB. +--- + +# Key Concepts + +To understand how GreptimeDB manages and serves its data, you need to know about +these building blocks of GreptimeDB. + +## Database + +Similar to *database* in relational databases, a database is the minimal unit of +data container, within which data can be managed and computed. Users can use the database to achieve data isolation, creating a tenant-like effect. + +## Time-Series Table + +GreptimeDB designed time-series table to be the basic unit of data storage. +It is similar to a table in a traditional relational database, but requires a timestamp column(We call it **time index**). +The table holds a set of data that shares a common schema, it's a collection of rows and columns: + +* Column: a vertical set of values in a table, GreptimeDB distinguishes columns into time index, tag and field. +* Row: a horizontal set of values in a table. + +It can be created using SQL `CREATE TABLE`, or inferred from the input data structure using the auto-schema feature. +In a distributed deployment, a table can be split into multiple partitions that sit on different datanodes. + +For more information about the data model of the time-series table, please refer to [Data Model](./data-model.md). + +## Table Region + +Each partition of distributed table is called a region. A region may contain a +sequence of continuous data, depending on the partition algorithm. Region +information is managed by Metasrv. It's completely transparent to users who send +write requests or queries. + +## Data Types + +Data in GreptimeDB is strongly typed. Auto-schema feature provides some +flexibility when creating a table. Once the table is created, data of the same +column must share common data type. + +Find all the supported data types in [Data Types](/reference/sql/data-types.md). + +## Index + +The `index` is a performance-tuning method that allows faster retrieval of records. GreptimeDB uses the [inverted index](/contributor-guide/datanode/data-persistence-indexing.md#inverted-index) to accelerate queries. + +## View + +The `view` is a virtual table that is derived from the result set of a SQL query. It contains rows and columns just like a real table, but it doesn’t store any data itself. +The data displayed in a view is retrieved dynamically from the underlying tables each time the view is queried. + +## Flow + +A `flow` in GreptimeDB refers to a [continuous aggregation](/user-guide/continuous-aggregation/overview.md) process that continuously updates and materializes aggregated data based on incoming data. diff --git a/versioned_docs/version-0.11/user-guide/concepts/overview.md b/versioned_docs/version-0.11/user-guide/concepts/overview.md new file mode 100644 index 000000000..480c6d186 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/concepts/overview.md @@ -0,0 +1,21 @@ +--- +description: Provides an overview of GreptimeDB, including its features, data model, architecture, storage locations, key concepts, and notable features. +--- + +# Overview + +- [Why GreptimeDB](./why-greptimedb.md): This document outlines the features and benefits of GreptimeDB, including its unified design for metrics, logs, and events; Cloud-Native and flexible architecture that allows for deployment in various environments, from embedded to cloud. GreptimeDB is also cost-effective, high-performance, and user-friendly. +- [Data Model](./data-model.md): This document describes the data model of GreptimeDB, including table schema, time index constraint, etc. +- [Architecture](./architecture.md): Get the cloud-native architecture of GreptimeDB. +- [Storage Location](./storage-location.md): This document describes the storage location of GreptimeDB, including local disk, HDFS, and cloud object storage such as S3, Azure Blob Storage, etc. +- [Key Concepts](./key-concepts.md): This document describes the key concepts of GreptimeDB, including table, time index, table region and data types. +- [Features that You Concern](./features-that-you-concern.md): Describes some features that may be concerned about a unified metrics, logs & events database. + +## Read More + +Get GreptimeDB roadmap and architecture design from blog posts: + +- [This Time, for Real - GreptimeDB is Now Open Source](https://greptime.com/blogs/2022-11-15-this-time-for-real) +- [Unifying Logs and Metrics](https://greptime.com/blogs/2024-06-25-logs-and-metrics) +- [GreptimeDB Internal Design — Distributed, Cloud-native, and Enhanced Analytical Ability for Time Series](https://greptime.com/blogs/2022-12-08-GreptimeDB-internal-design) +- [GreptimeDB Storage Engine Design - Catering to Time Series Scenarios](https://greptime.com/blogs/2022-12-21-storage-engine-design) diff --git a/versioned_docs/version-0.11/user-guide/concepts/storage-location.md b/versioned_docs/version-0.11/user-guide/concepts/storage-location.md new file mode 100644 index 000000000..c187dfcd6 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/concepts/storage-location.md @@ -0,0 +1,44 @@ +--- +description: Describes the storage options for GreptimeDB, including local file systems, cloud storage services like AWS S3, Azure Blob Storage, and more. It explains the local file structure and considerations for disaster recovery and multiple storage engines. +--- + +# Storage Location + +GreptimeDB supports storing data in local file system, AWS S3 and compatible services (including minio, digitalocean space, Tencent Cloud Object Storage(COS), Baidu Object Storage(BOS) and so on), Azure Blob Storage and Aliyun OSS. + +## Local File Structure + +The storage file structure of GreptimeDB includes of the following: + +```cmd +├── metadata + ├── raftlog + ├── rewrite + └── LOCK +├── data +│   ├── greptime +│   └── public +├── logs +├── index_intermediate +│   └── staging +└── wal + ├── raftlog + ├── rewrite + └── LOCK +``` + +- `metadata`: The internal metadata directory that keeps catalog, database and table info, procedure states, etc. In cluster mode, this directory does not exist, because all those states including region route info are saved in `Metasrv`. +- `data`: The files in data directory store time series data and index files of GreptimeDB. To customize this path, please refer to [Storage option](../deployments/configuration.md#storage-options). The directory is organized in a two-level structure of catalog and schema. +- `logs`: The log files contains all the logs of operations in GreptimeDB. +- `wal`: The wal directory contains the write-ahead log files. +- `index_intermediate`: the temporary intermediate data while indexing. + +## Cloud storage + +The `data` directory in the file structure can be stored in cloud storage. Please refer to [Storage option](../deployments/configuration.md#storage-options) for more details. + +Please note that only storing the data directory in object storage is not sufficient to ensure data reliability and disaster recovery. The `wal` and `metadata` also need to be considered for disaster recovery. Please refer to the [disaster recovery documentation](/user-guide/administration/disaster-recovery/overview.md). + +## Multiple storage engines + +Another powerful feature of GreptimeDB is that you can choose the storage engine for each table. For example, you can store some tables on the local disk, and some tables in Amazon S3 or Google Cloud Storage, see [create table](/reference/sql/create.md#create-table). diff --git a/versioned_docs/version-0.11/user-guide/concepts/why-greptimedb.md b/versioned_docs/version-0.11/user-guide/concepts/why-greptimedb.md new file mode 100644 index 000000000..9329e7c74 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/concepts/why-greptimedb.md @@ -0,0 +1,93 @@ +--- +description: Explains the motivations and benefits of using GreptimeDB, including its unified design for metrics, logs, and events, cloud-native architecture, cost-effectiveness, high performance, and ease of use. It highlights key features and deployment strategies. +--- + +# Why GreptimeDB + +GreptimeDB is a cloud-native, distributed and open source time series database, it's designed to process, store and analyze vast amounts of metrics, logs & events data (also Traces in plan). + +It's highly efficient at handling hybrid processing workloads which involve both time-series and real-time analysis, while providing users with great experience. + +To gain insight into the motivations that led to the development of GreptimeDB, we recommend reading our blog posts titled ["This Time, for Real"](https://greptime.com/blogs/2022-11-15-this-time-for-real) and ["Unifying Logs and Metrics"](https://greptime.com/blogs/2024-06-25-logs-and-metrics). + +In these documents, we delve into the reasons behind Greptime's high performance and some highlighted features. + +## Unified metrics, logs, and events + +Through the model design of [time series tables](./data-model), native support for SQL, and the hybrid workload brought by the storage-computation separation architecture, GreptimeDB can handle metrics, logs, and events together, enhance the correlation analysis between different time series data and simplify the architecture, deployment and APIs for users. + +Read the [SQL example](/user-guide/overview.md#sql-query-example) for detailed info. + +## Availability, Scalability, and Elasticity + +From day 0, GreptimeDB was designed following the principles of cloud-native databases, which means that it runs and takes full advantage of the cloud. Some of the benefits include: + +1. highly available, on-demand computing resources with a goal to achieve availability and uptime rate of 99.999%, resulting in approximately five minutes and 15 seconds of downtime per year. +2. Elasticity and scalability, allowing users to easily scale up or down, add or move resources according to usage. +3. Highly reliable and fault tolerant, with the system having a 99.9999% availability rate as the goal to prevent data loss. + +Together, these features ensure that GreptimeDB always provides optimal functionality. Below, we provide additional technical explanation on how these features are accomplished. + +### Resource Isolation for Elastic Scaling + +![Storage/Compute Disaggregation, Compute/Compute separation](/storage-compute-disaggregation-compute-compute-separation.png) + +The storage and compute resources are separated, allowing each to be scaled, consumed and priced independently. +This greatly increases utilization of computing resources, allows the "pay-as-you-go" pricing model and avoids waste of underutilized resources. + +Besides storage and compute isolation, different compute resources are also isolated to offer new efficiencies for real-time analytics at scale with shared real-time data by avoiding contention for tasks such as data ingestion and queries, ad-hoc queries, and data compaction or rollup. +Data can be shared among multiple applications without the need of competing for the same pool of resources which greatly improve efficiency, and unlimited concurrency scalability can be provided based on demand. + +### Flexible Architecture Supports Various Deployment Strategies + +![The architecture of GreptimeDB](/architecture-2.png) + +With flexible architecture design principles, different modules and components can be independently switched on, combined, or separated through modularization and layered design. +For example, we can merge the frontend, datanode, and metasrv modules into a standalone binary, and we can also independently enable or disable the WAL for every table. + +Flexible architecture allows GreptimeDB to meet deployment and usage requirements in scenarios from the edge to the cloud, while still using the same set of APIs and control panels. +Through well-abstracted layering and encapsulation isolation, GreptimeDB's deployment form supports various environments from embedded, standalone, and traditional clusters to cloud-native. + +## Cost-Effective + +GreptimeDB utilizes popular object storage solutions such as AWS S3 and Azure Blob Storage to store large amounts of time series data, allowing users to only pay for the amount of storage resources being used. + +GreptimeDB uses adaptive compression algorithms to reduce the amount of data based on the type and cardinality of it to meet the temporal and spatial complexity constraints. +For example, for string data type, GreptimeDB uses dictionary compression when the cardinality of a block exceeds a certain threshold; for float point numbers, GreptimeDB adopts the Chimp algorithm which enhances Gorrila's (Facebook's in-memory TSDB) algorithm by analyzing real-case time-series datasets, and offers a higher compression rate and spatial efficiency than traditional algorithms (such as zstd, Snappy, etc). + +## High Performance + +As for performance optimization, GreptimeDB utilizes different techniques such as, LSM Tree, data sharding and quorum-based WAL design, to handle large workloads of time-series data ingestion. + +The powerful and fast query engine is powered by vectorized execution and distributed parallel processing, and combined with indexing capabilities. GreptimeDB builds smart indexing and Massively Parallel Processing (MPP) to boost pruning and filtering. +We use independent index files to record statistical information, like what Apache Parquet's row group metadata does. Built-in metrics are also used to record the workloads of different queries. +Combining Cost-Based Optimization(CBO) with user-defined hints, we are able to build a smart index heuristically. + +## Easy to Use + +### Easy to Deploy and Maintain + +To simplify deployment and maintenance processes, GreptimeDB provides [K8s operator](https://github.com/GreptimeTeam/greptimedb-operator), [command-line tool](https://github.com/GreptimeTeam/gtctl), embedded [dashboard](https://github.com/GreptimeTeam/dashboard), and other useful tools for users to configure and manage their databases easily. Check [GreptimeCloud](https://greptime.com/product/cloud) on our official website for more information. + +### Easy to Integrate + +Several protocols are supported for database connectivity, including MySQL, PostgreSQL, InfluxDB, OpenTSDB, Prometheus RemoteStorage, and high-performance gRPC. +Additionally, SDKs are provided for various programming languages, such as Java, Go, Erlang, and more to come. We are continuously integrating and connecting with other open-source software in the ecosystem to enhance developer experience. +In the following paragraphs, we will elaborate on three popular languages: PromQL, SQL and Python. + +PromQL is a popular query language that allows users to select and aggregate real-time time series data provided by Prometheus. +It is much simpler to use than SQL for visualization with Grafana and creating alert rules. GreptimeDB supports PromQL natively and effectively by transforming it into a query plan, which is then optimized and executed by the query engine. + +SQL is a highly efficient tool for analyzing data that spans over a long time span or involves multiple tables, such as table joins. Additionally, it proves to be convenient for database management. + +Python is very popular among data scientists and AI experts. GreptimeDB enables Python scripts to be run directly in the database. +Developers can write UDF and DataFrame API to accelerate data processing by embedding the Python interpreter. + +### Simple Data Model with Automatic Schema + +Combining the metrics (Measurement/Tag/Field/Timestamp) model and the relational data model (Table), GreptimeDB provides a new data model called a time-series table (see below), which presents data in the form of tables consisting of rows and columns, with tags and fields of the metrics mapped to columns, and an enforced time index constraint that represents the timestamp. + +![Time-Series Table](/time-series-table.png) + +Nevertheless, our definition of a schema is not mandatory but leans more towards the schemaless approach of databases like MongoDB. +The table will be created dynamically and automatically when data is ingested, and new columns (tags and fields) will be added as they appear. diff --git a/versioned_docs/version-0.11/user-guide/continuous-aggregation/expression.md b/versioned_docs/version-0.11/user-guide/continuous-aggregation/expression.md new file mode 100644 index 000000000..2b274c907 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/continuous-aggregation/expression.md @@ -0,0 +1,27 @@ +--- +description: Lists supported aggregate and scalar functions in GreptimeDB's flow, including count, sum, avg, min, max, and various scalar functions. It provides links to detailed documentation for each function. +--- + +# Expression + +## Aggregate functions + +This part list all supported aggregate functions in flow: + +- `count(column)`: count the number of rows. +- `sum(column)`: sum the values of the column. +- `avg(column)`: calculate the average value of the column. +- `min(column)`: find the minimum value of the column. +- `max(column)`: find the maximum value of the column. + +more aggregate functions will be added in the future. + +## Scalar functions + +Flow support most scalar functions from datafusion, see the full list of supported scalar functions in [datafusion](/reference/sql/functions/df-functions.md#scalar-functions). + +And here are some of the most commonly used scalar functions in flow: + +- [`date_bin`](/reference/sql/functions/df-functions.md#date_bin): calculate time intervals and returns the start of the interval nearest to the specified timestamp. +- [`date_trunc`](/reference/sql/functions/df-functions.md#date_trunc): truncate a timestamp value to a specified precision. +- [`trunc`](/reference/sql/functions/df-functions.md#trunc): truncate a number to a whole number or truncated to the specified decimal places. diff --git a/versioned_docs/version-0.11/user-guide/continuous-aggregation/manage-flow.md b/versioned_docs/version-0.11/user-guide/continuous-aggregation/manage-flow.md new file mode 100644 index 000000000..030043f28 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/continuous-aggregation/manage-flow.md @@ -0,0 +1,236 @@ +--- +description: Describes how to manage flows in GreptimeDB, including creating, updating, and deleting flows. It explains the syntax for creating flows, the importance of sink tables, and how to use the EXPIRE AFTER clause. Examples of SQL queries for managing flows are provided. +--- + +# Manage Flows + +Each `flow` is a continuous aggregation query in GreptimeDB. +It continuously updates the aggregated data based on the incoming data. +This document describes how to create, and delete a flow. + +## Create input table + +Before creating a flow, you need to create a source table to store the raw data. Like this: +```sql +CREATE TABLE temp_sensor_data ( + sensor_id INT, + loc STRING, + temperature DOUBLE, + ts TIMESTAMP TIME INDEX, + PRIMARY KEY(sensor_id, loc) +); +``` +However, if you don't want to store the raw data, you can use a temporary table as the source table by creating table using `WITH ('ttl' = 'instant')` table option: +```sql +CREATE TABLE temp_sensor_data ( + sensor_id INT, + loc STRING, + temperature DOUBLE, + ts TIMESTAMP TIME INDEX, + PRIMARY KEY(sensor_id, loc) +) WITH ('ttl' = 'instant'); +``` +Setting `'ttl'` to `'instant'` will make the table a temporary table, which means it will automatically discard all inserted data and the table will always be empty, only sending them to flow task for computation. + +## Create a sink table + +Before creating a flow, you need a sink table to store the aggregated data generated by the flow. +While it is the same to a regular time series table, there are a few important considerations: + +- **Column order and type**: Ensure the order and type of the columns in the sink table match the query result of the flow. +- **Time index**: Specify the `TIME INDEX` for the sink table, typically using the time window column generated by the time window function. +- **Specify `update_at` as the last column of the schema**: The flow automatically writes the update time of the data to the `update_at` column. Ensure this column is the last one in the sink table schema. +- **Tags**: Use `PRIMARY KEY` to specify Tags, which together with the time index serves as a unique identifier for row data and optimizes query performance. + +For example: + +```sql +/* Create sink table */ +CREATE TABLE temp_alerts ( + sensor_id INT, + loc STRING, + max_temp DOUBLE, + time_window TIMESTAMP TIME INDEX, + update_at TIMESTAMP, + PRIMARY KEY(sensor_id, loc) +); + +CREATE FLOW temp_monitoring +SINK TO temp_alerts +AS +SELECT + sensor_id, + loc, + max(temperature) AS max_temp, + date_bin(INTERVAL '10 seconds', ts) AS time_window +FROM temp_sensor_data +GROUP BY + sensor_id, + loc, + time_window +HAVING max_temp > 100; +``` + +The sink table has the columns `sensor_id`, `loc`, `max_temp`, `time_window`, and `update_at`. + +- The first four columns correspond to the query result columns of flow: `sensor_id`, `loc`, `max(temperature)` and `date_bin(INTERVAL '10 seconds', ts)` respectively. +- The `time_window` column is specified as the `TIME INDEX` for the sink table. +- The `update_at` column is the last one in the schema to store the update time of the data. +- The `PRIMARY KEY` at the end of the schema definition specifies `sensor_id` and `loc` as the tag columns. + This means the flow will insert or update data based on the tags `sensor_id` and `loc` along with the time index `time_window`. + +## Create a flow + +The grammar to create a flow is: + + + +```sql +CREATE [ OR REPLACE ] FLOW [ IF NOT EXISTS ] +SINK TO +[ EXPIRE AFTER ] +[ COMMENT '' ] +AS +; +``` + +When `OR REPLACE` is specified, any existing flow with the same name will be updated to the new version. It's important to note that this only affects the flow task itself; the source and sink tables will remain unchanged. + +Conversely, when `IF NOT EXISTS` is specified, the command will have no effect if the flow already exists, rather than reporting an error. Additionally, please note that `OR REPLACE` cannot be used in conjunction with `IF NOT EXISTS`. + + +- `flow-name` is an unique identifier in the catalog level. +- `sink-table-name` is the table name where the materialized aggregated data is stored. + It can be an existing table or a new one. `flow` will create the sink table if it doesn't exist. + +- `EXPIRE AFTER` is an optional interval to expire the data from the Flow engine. + For more details, please refer to the [`EXPIRE AFTER`](#expire-after-clause) part. +- `COMMENT` is the description of the flow. +- `SQL` part defines the continuous aggregation query. + It defines the source tables provide data for the flow. + Each flow can have multiple source tables. + Please Refer to [Write a Query](#write-a-sql-query) for the details. + +A simple example to create a flow: + +```sql +CREATE FLOW IF NOT EXISTS my_flow +SINK TO my_sink_table +EXPIRE AFTER INTERVAL '1 hour' +COMMENT 'My first flow in GreptimeDB' +AS +SELECT + max(temperature) as max_temp, + date_bin(INTERVAL '10 seconds', ts) as time_window, +FROM temp_sensor_data +GROUP BY time_window; +``` + +The created flow will compute `max(temperature)` for every 10 seconds and store the result in `my_sink_table`. All data comes within 1 hour will be used in the flow. + +### `EXPIRE AFTER` clause + +The `EXPIRE AFTER` clause specifies the interval after which data will expire from the flow engine. +This expiration only affects the data in the flow engine and does not impact the data in the source table. + +When the flow engine processes the aggregation operation (the `update_at` time), +data with a time index older than the specified interval will expire. + +For example, if the flow engine processes the aggregation at 10:00:00 and the `INTERVAL '1 hour'` is set, +any data older than 1 hour (before 09:00:00) will expire. +Only data timestamped from 09:00:00 onwards will be used in the aggregation. + +### Write a SQL query + +The `SQL` part of the flow is similar to a standard `SELECT` clause with a few differences. The syntax of the query is as follows: + +```sql +SELECT AGGR_FUNCTION(column1, column2,..), TIME_WINDOW_FUNCTION() as time_window FROM GROUP BY time_window; +``` + +Only the following types of expressions are allowed after the `SELECT` keyword: +- Aggregate functions: Refer to the [Expression](./expression.md) documentation for details. +- Time window functions: Refer to the [define time window](#define-time-window) section for details. +- Scalar functions: Such as `col`, `to_lowercase(col)`, `col + 1`, etc. This part is the same as in a standard `SELECT` clause in GreptimeDB. + +The following points should be noted about the rest of the query syntax: +- The query must include a `FROM` clause to specify the source table. + As join clauses are currently not supported, + the query can only aggregate columns from a single table. +- `WHERE` and `HAVING` clauses are supported. + The `WHERE` clause filters data before aggregation, + while the `HAVING` clause filters data after aggregation. +- `DISTINCT` currently only works with the `SELECT DISTINCT column1 ..` syntax. + It is used to remove duplicate rows from the result set. + Support for `SELECT count(DISTINCT column1) ...` is not available yet but will be added in the future. +- The `GROUP BY` clause works the same as a standard queries, + grouping data by specified columns. + The time window column in the `GROUP BY` clause is crucial for continuous aggregation scenarios. + Other expressions in `GROUP BY` can include literals, columns, or scalar expressions. +- `ORDER BY`, `LIMIT`, and `OFFSET` are not supported. + +Refer to [Usecase Examples](./usecase-example.md) for more examples of how to use continuous aggregation in real-time analytics, monitoring, and dashboards. + +### Define time window + +A time window is a crucial attribute of your continuous aggregation query. +It determines how data is aggregated within the flow. +These time windows are left-closed and right-open intervals. + +A time window represents a specific range of time. +Data from the source table is mapped to the corresponding window based on the time index column. +The time window also defines the scope for each calculation of an aggregation expression, +resulting in one row per time window in the result table. + +You can use `date_bin()` after the `SELECT` keyword to define fixed time windows. +For example: + +```sql +SELECT + max(temperature) as max_temp, + date_bin(INTERVAL '10 seconds', ts) as time_window +FROM temp_sensor_data +GROUP BY time_window; +``` + +In this example, the `date_bin(INTERVAL '10 seconds', ts)` function creates 10-second time windows starting from UTC 00:00:00. +The `max(temperature)` function calculates the maximum temperature value within each time window. + +For more details on the behavior of the function, +please refer to [`date_bin`](/reference/sql/functions/df-functions.md#date_bin). + +:::tip NOTE +Currently, the internal state of the flow, such as the accumulator's value for incremental query results (e.g., the accumulator for `count(col)` which records the current count), is not persistently stored. To minimize data loss in case of internal state failure, it is advisable to use smaller time windows. + +This internal state loss does not affect the existing data in the sink table. +::: + +## Flush a flow + +The flow engine automatically processes aggregation operations within 1 second when new data arrives in the source table. +However, you can manually trigger the flow engine to process the aggregation operation immediately using the `ADMIN FLUSH_FLOW` command. + +```sql +ADMIN FLUSH_FLOW('') +``` + +## Delete a flow + +To delete a flow, use the following `DROP FLOW` clause: + +```sql +DROP FLOW [IF EXISTS] +``` + +For example: + +```sql +DROP FLOW IF EXISTS my_flow; +``` diff --git a/versioned_docs/version-0.11/user-guide/continuous-aggregation/overview.md b/versioned_docs/version-0.11/user-guide/continuous-aggregation/overview.md new file mode 100644 index 000000000..6b17e13e7 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/continuous-aggregation/overview.md @@ -0,0 +1,150 @@ +--- +description: Introduction to GreptimeDB's continuous aggregation feature, including real-time data aggregation, use cases, and a quick start example. +--- + +# Overview + +GreptimeDB provides a continuous aggregation feature that allows you to aggregate data in real-time. This feature is useful when you need to calculate and query the sum, average, or other aggregations on the fly. The continuous aggregation feature is provided by the Flow engine. It continuously updates the aggregated data based on the incoming data and materialize it. So you can think of it as a clever materialized views that know when to update result view table and how to update it with minimal effort. Some common use case include: + +- Downsampling the data point using i.e. average pooling to reduce amount of data for storage and analysis +- Real-time analytics that provide actionable information in near real-time + +When you insert data into the source table, the data is also sent to and stored in the Flow engine. +The Flow engine calculate the aggregation by time windows and store the result in the sink table. +The entire process is illustrated in the following image: + +![Continuous Aggregation](/flow-ani.svg) + +## Quick start with an example + +Here is a complete example of how a continuous aggregation query looks like. + +This use case is to calculate the total number of logs, the minimum size, the maximum size, the average size, and the number of packets with the size greater than 550 for each status code in a 1-minute fixed window for access logs. +First, create a source table `ngx_access_log` and a sink table `ngx_statistics` with following clauses: + +```sql +CREATE TABLE `ngx_access_log` ( + `client` STRING NULL, + `ua_platform` STRING NULL, + `referer` STRING NULL, + `method` STRING NULL, + `endpoint` STRING NULL, + `trace_id` STRING NULL FULLTEXT, + `protocol` STRING NULL, + `status` SMALLINT UNSIGNED NULL, + `size` DOUBLE NULL, + `agent` STRING NULL, + `access_time` TIMESTAMP(3) NOT NULL, + TIME INDEX (`access_time`) +) +WITH( + append_mode = 'true' +); +``` + +```sql +CREATE TABLE `ngx_statistics` ( + `status` SMALLINT UNSIGNED NULL, + `total_logs` BIGINT NULL, + `min_size` DOUBLE NULL, + `max_size` DOUBLE NULL, + `avg_size` DOUBLE NULL, + `high_size_count` BIGINT NULL, + `time_window` TIMESTAMP time index, + `update_at` TIMESTAMP NULL, + PRIMARY KEY (`status`) +); +``` + +Then create the flow `ngx_aggregation` to aggregate a series of aggregate functions, including `count`, `min`, `max`, `avg` of the `size` column, and the sum of all packets of size great than 550. The aggregation is calculated in 1-minute fixed windows of `access_time` column and also grouped by the `status` column. So you can be made aware in real time the information about packet size and action upon it, i.e. if the `high_size_count` became too high at a certain point, you can further examine if anything goes wrong, or if the `max_size` column suddenly spike in a 1 minute time window, you can then trying to locate that packet and further inspect it. + +```sql +CREATE FLOW ngx_aggregation +SINK TO ngx_statistics +AS +SELECT + status, + count(client) AS total_logs, + min(size) as min_size, + max(size) as max_size, + avg(size) as avg_size, + sum(case when `size` > 550 then 1 else 0 end) as high_size_count, + date_bin(INTERVAL '1 minutes', access_time) as time_window, +FROM ngx_access_log +GROUP BY + status, + time_window; +``` + +To observe the outcome of the continuous aggregation in the `ngx_statistics` table, insert some data into the source table `ngx_access_log`. + +```sql +INSERT INTO ngx_access_log +VALUES + ("android", "Android", "referer", "GET", "/api/v1", "trace_id", "HTTP", 200, 1000, "agent", "2021-07-01 00:00:01.000"), + ("ios", "iOS", "referer", "GET", "/api/v1", "trace_id", "HTTP", 200, 500, "agent", "2021-07-01 00:00:30.500"), + ("android", "Android", "referer", "GET", "/api/v1", "trace_id", "HTTP", 200, 600, "agent", "2021-07-01 00:01:01.000"), + ("ios", "iOS", "referer", "GET", "/api/v1", "trace_id", "HTTP", 404, 700, "agent", "2021-07-01 00:01:01.500"); +``` + +Then the sink table `ngx_statistics` will be incremental updated and contain the following data: + +```sql +SELECT * FROM ngx_statistics; +``` + +```sql + status | total_logs | min_size | max_size | avg_size | high_size_count | time_window | update_at +--------+------------+----------+----------+----------+-----------------+----------------------------+---------------------------- + 200 | 2 | 500 | 1000 | 750 | 1 | 2021-07-01 00:00:00.000000 | 2024-07-24 08:36:17.439000 + 200 | 1 | 600 | 600 | 600 | 1 | 2021-07-01 00:01:00.000000 | 2024-07-24 08:36:17.439000 + 404 | 1 | 700 | 700 | 700 | 1 | 2021-07-01 00:01:00.000000 | 2024-07-24 08:36:17.439000 +(3 rows) +``` + +Try to insert more data into the `ngx_access_log` table: + +```sql +INSERT INTO ngx_access_log +VALUES + ("android", "Android", "referer", "GET", "/api/v1", "trace_id", "HTTP", 200, 500, "agent", "2021-07-01 00:01:01.000"), + ("ios", "iOS", "referer", "GET", "/api/v1", "trace_id", "HTTP", 404, 800, "agent", "2021-07-01 00:01:01.500"); +``` + +The sink table `ngx_statistics` now have corresponding rows updated, notes how `max_size`, `avg_size` and `high_size_count` are updated: + +```sql +SELECT * FROM ngx_statistics; +``` + +```sql + status | total_logs | min_size | max_size | avg_size | high_size_count | time_window | update_at +--------+------------+----------+----------+----------+-----------------+----------------------------+---------------------------- + 200 | 2 | 500 | 1000 | 750 | 1 | 2021-07-01 00:00:00.000000 | 2024-07-24 08:36:17.439000 + 200 | 2 | 500 | 600 | 550 | 1 | 2021-07-01 00:01:00.000000 | 2024-07-24 08:36:46.495000 + 404 | 2 | 700 | 800 | 750 | 2 | 2021-07-01 00:01:00.000000 | 2024-07-24 08:36:46.495000 +(3 rows) +``` + +Here is the explanation of the columns in the `ngx_statistics` table: + +- `status`: The status code of the HTTP response. +- `total_logs`: The total number of logs with the same status code. +- `min_size`: The minimum size of the packets with the same status code. +- `max_size`: The maximum size of the packets with the same status code. +- `avg_size`: The average size of the packets with the same status code. +- `high_size_count`: The number of packets with the size greater than 550. +- `time_window`: The time window of the aggregation. +- `update_at`: The time when the aggregation is updated. + + + + +## Next Steps + +Congratulations you already have a preliminary understanding of the continuous aggregation feature. +Please refer to the following sections to learn more: + +- [Usecase Examples](./usecase-example.md) provides more examples of how to use continuous aggregation in real-time analytics, monitoring, and dashboard. +- [Manage Flows](./manage-flow.md) describes how to create and delete a flow. Each of your continuous aggregation query is a flow. +- [Expression](./expression.md) is a reference of available expressions in the continuous aggregation query. diff --git a/versioned_docs/version-0.11/user-guide/continuous-aggregation/usecase-example.md b/versioned_docs/version-0.11/user-guide/continuous-aggregation/usecase-example.md new file mode 100644 index 000000000..88b5d447b --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/continuous-aggregation/usecase-example.md @@ -0,0 +1,258 @@ +--- +description: Provides major use case examples for continuous aggregation in GreptimeDB, including real-time analytics, monitoring, and dashboards. It includes SQL queries and examples to demonstrate how to set up and use continuous aggregation for various scenarios. +--- + +# Usecase Examples +Following are three major usecase examples for continuous aggregation: + +1. **Real-time Analytics**: A real-time analytics platform that continuously aggregates data from a stream of events, delivering immediate insights while optionally downsampling the data to a lower resolution. For instance, this system can compile data from a high-frequency stream of log events (e.g., occurring every millisecond) to provide up-to-the-minute insights such as the number of requests per minute, average response times, and error rates per minute. + +2. **Real-time Monitoring**: A real-time monitoring system that continuously aggregates data from a stream of events and provides real-time alerts based on the aggregated data. For example, a system that aggregates data from a stream of sensor events and provides real-time alerts when the temperature exceeds a certain threshold. + +3. **Real-time Dashboard**: A real-time dashboard that shows the number of requests per minute, the average response time, and the number of errors per minute. This dashboard can be used to monitor the health of the system and to detect any anomalies in the system. + +In all these usecases, the continuous aggregation system continuously aggregates data from a stream of events and provides real-time insights and alerts based on the aggregated data. The system can also downsample the data to a lower resolution to reduce the amount of data stored and processed. This allows the system to provide real-time insights and alerts while keeping the data storage and processing costs low. + +## Real-time analytics example + +See [Overview](/user-guide/continuous-aggregation/overview.md#quick-start-with-an-example) for an example of real-time analytics. Which is to calculate the total number of logs, the minimum size, the maximum size, the average size, and the number of packets with the size greater than 550 for each status code in a 1-minute fixed window for access logs. + +Another example of real-time analytics is to retrieve all distinct countries from the `ngx_access_log` table. +You can use the following query to group countries by time window: + +```sql +/* input table */ +CREATE TABLE ngx_access_log ( + client STRING, + country STRING, + access_time TIMESTAMP TIME INDEX, + PRIMARY KEY(client) +); + +/* sink table */ +CREATE TABLE ngx_country ( + country STRING, + time_window TIMESTAMP TIME INDEX, + update_at TIMESTAMP, + PRIMARY KEY(country) +); + +/* create flow task to calculate the distinct country */ +CREATE FLOW calc_ngx_country +SINK TO ngx_country +AS +SELECT + DISTINCT country, + date_bin(INTERVAL '1 hour', access_time) as time_window, +FROM ngx_access_log +GROUP BY + country, + time_window; +``` + +The above query puts the data from the `ngx_access_log` table into the `ngx_country` table. +It calculates the distinct country for each time window. +The `date_bin` function is used to group the data into one-hour intervals. +The `ngx_country` table will be continuously updated with the aggregated data, +providing real-time insights into the distinct countries that are accessing the system. + +You can insert some data into the source table `ngx_access_log`: + +```sql +INSERT INTO ngx_access_log VALUES + ("client1", "US", "2022-01-01 01:00:00"), + ("client2", "US", "2022-01-01 01:00:00"), + ("client3", "UK", "2022-01-01 01:00:00"), + ("client4", "UK", "2022-01-01 02:00:00"), + ("client5", "CN", "2022-01-01 02:00:00"), + ("client6", "CN", "2022-01-01 02:00:00"), + ("client7", "JP", "2022-01-01 03:00:00"), + ("client8", "JP", "2022-01-01 03:00:00"), + ("client9", "KR", "2022-01-01 03:00:00"), + ("client10", "KR", "2022-01-01 03:00:00"); +``` + +Wait for one second for the Flow to write the result to the sink table and then query: + +```sql +select * from ngx_country; +``` + +```sql ++---------+---------------------+----------------------------+ +| country | time_window | update_at | ++---------+---------------------+----------------------------+ +| CN | 2022-01-01 02:00:00 | 2024-10-22 08:17:47.906000 | +| JP | 2022-01-01 03:00:00 | 2024-10-22 08:17:47.906000 | +| KR | 2022-01-01 03:00:00 | 2024-10-22 08:17:47.906000 | +| UK | 2022-01-01 01:00:00 | 2024-10-22 08:17:47.906000 | +| UK | 2022-01-01 02:00:00 | 2024-10-22 08:17:47.906000 | +| US | 2022-01-01 01:00:00 | 2024-10-22 08:17:47.906000 | ++---------+---------------------+----------------------------+ +``` + +## Real-time monitoring example + +Consider a usecase where you have a stream of sensor events from a network of temperature sensors that you want to monitor in real-time. The sensor events contain information such as the sensor ID, the temperature reading, the timestamp of the reading, and the location of the sensor. You want to continuously aggregate this data to provide real-time alerts when the temperature exceeds a certain threshold. Then the query for continuous aggregation would be: + +```sql +/* create input table */ +CREATE TABLE temp_sensor_data ( + sensor_id INT, + loc STRING, + temperature DOUBLE, + ts TIMESTAMP TIME INDEX, + PRIMARY KEY(sensor_id, loc) +); + +/* create sink table */ +CREATE TABLE temp_alerts ( + sensor_id INT, + loc STRING, + max_temp DOUBLE, + time_window TIMESTAMP TIME INDEX, + update_at TIMESTAMP, + PRIMARY KEY(sensor_id, loc) +); + +CREATE FLOW temp_monitoring +SINK TO temp_alerts +AS +SELECT + sensor_id, + loc, + max(temperature) as max_temp, + date_bin(INTERVAL '10 seconds', ts) as time_window, +FROM temp_sensor_data +GROUP BY + sensor_id, + loc, + time_window +HAVING max_temp > 100; +``` + +The above query continuously aggregates data from the `temp_sensor_data` table into the `temp_alerts` table. +It calculates the maximum temperature reading for each sensor and location, +filtering out data where the maximum temperature exceeds 100 degrees. +The `temp_alerts` table will be continuously updated with the aggregated data, +providing real-time alerts (in the form of new rows in the `temp_alerts` table) when the temperature exceeds the threshold. + +Now that we have created the flow task, we can insert some data into the source table `temp_sensor_data`: + +```sql + +INSERT INTO temp_sensor_data VALUES + (1, "room1", 98.5, "2022-01-01 00:00:00"), + (2, "room2", 99.5, "2022-01-01 00:00:01"); +``` +table should be empty now, but still wait at least one second for flow to update results to sink table: + +```sql +SELECT * FROM temp_alerts; +``` + +```sql +Empty set (0.00 sec) +``` + +Now insert some data that will trigger the alert: + +```sql +INSERT INTO temp_sensor_data VALUES + (1, "room1", 101.5, "2022-01-01 00:00:02"), + (2, "room2", 102.5, "2022-01-01 00:00:03"); +``` + +wait at least one second for flow to update results to sink table: + +```sql +SELECT * FROM temp_alerts; +``` + +```sql ++-----------+-------+----------+---------------------+----------------------------+ +| sensor_id | loc | max_temp | time_window | update_at | ++-----------+-------+----------+---------------------+----------------------------+ +| 1 | room1 | 101.5 | 2022-01-01 00:00:00 | 2024-10-22 09:13:07.535000 | +| 2 | room2 | 102.5 | 2022-01-01 00:00:00 | 2024-10-22 09:13:07.535000 | ++-----------+-------+----------+---------------------+----------------------------+ +``` + +## Real-time dashboard + +Consider a usecase in which you need a bar graph that show the distribution of packet sizes for each status code to monitor the health of the system. The query for continuous aggregation would be: + +```sql +/* create input table */ +CREATE TABLE ngx_access_log ( + client STRING, + stat INT, + size INT, + access_time TIMESTAMP TIME INDEX +); +/* create sink table */ +CREATE TABLE ngx_distribution ( + stat INT, + bucket_size INT, + total_logs BIGINT, + time_window TIMESTAMP TIME INDEX, + update_at TIMESTAMP, + PRIMARY KEY(stat, bucket_size) +); +/* create flow task to calculate the distribution of packet sizes for each status code */ +CREATE FLOW calc_ngx_distribution SINK TO ngx_distribution AS +SELECT + stat, + trunc(size, -1)::INT as bucket_size, + count(client) AS total_logs, + date_bin(INTERVAL '1 minutes', access_time) as time_window, +FROM + ngx_access_log +GROUP BY + stat, + time_window, + bucket_size; +``` + +The query aggregates data from the `ngx_access_log` table into the `ngx_distribution` table. +It computes the total number of logs for each status code and packet size bucket (bucket size of 10, as specified by `trunc` with a second argument of -1) within each time window. +The `date_bin` function groups the data into one-minute intervals. +Consequently, the `ngx_distribution` table is continuously updated, offering real-time insights into the distribution of packet sizes per status code. + +Now that we have created the flow task, we can insert some data into the source table `ngx_access_log`: + +```sql +INSERT INTO ngx_access_log VALUES + ("cli1", 200, 100, "2022-01-01 00:00:00"), + ("cli2", 200, 104, "2022-01-01 00:00:01"), + ("cli3", 200, 120, "2022-01-01 00:00:02"), + ("cli4", 200, 124, "2022-01-01 00:00:03"), + ("cli5", 200, 140, "2022-01-01 00:00:04"), + ("cli6", 404, 144, "2022-01-01 00:00:05"), + ("cli7", 404, 160, "2022-01-01 00:00:06"), + ("cli8", 404, 164, "2022-01-01 00:00:07"), + ("cli9", 404, 180, "2022-01-01 00:00:08"), + ("cli10", 404, 184, "2022-01-01 00:00:09"); +``` +wait at least one second for flow to update results to sink table: + +```sql +SELECT * FROM ngx_distribution; +``` + +```sql ++------+-------------+------------+---------------------+----------------------------+ +| stat | bucket_size | total_logs | time_window | update_at | ++------+-------------+------------+---------------------+----------------------------+ +| 200 | 100 | 2 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 200 | 120 | 2 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 200 | 140 | 1 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 404 | 140 | 1 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 404 | 160 | 2 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | +| 404 | 180 | 2 | 2022-01-01 00:00:00 | 2024-10-22 09:17:09.592000 | ++------+-------------+------------+---------------------+----------------------------+ +``` + +## Conclusion + +Continuous aggregation is a powerful tool for real-time analytics, monitoring, and dashboarding. It allows you to continuously aggregate data from a stream of events and provide real-time insights and alerts based on the aggregated data. By downsampling the data to a lower resolution, you can reduce the amount of data stored and processed, making it easier to provide real-time insights and alerts while keeping the data storage and processing costs low. Continuous aggregation is a key component of any real-time data processing system and can be used in a wide range of usecases to provide real-time insights and alerts based on streaming data. \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/deployments/authentication/overview.md b/versioned_docs/version-0.11/user-guide/deployments/authentication/overview.md new file mode 100644 index 000000000..f6037ca38 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/deployments/authentication/overview.md @@ -0,0 +1,14 @@ +--- +description: Overview of authentication in GreptimeDB, including static user provider and LDAP user provider for authenticating users. +--- + +# Overview + +Authentication occurs when a user attempts to connect to the database. In GreptimeDB, users are authenticated by "user +provider"s. There are various implementations of user providers in GreptimeDB: + +- [Static User Provider](./static.md): A simple built-in user provider implementation that finds users from a static + file. +- [LDAP User Provider](/enterprise/deployments/authentication.md): **Enterprise feature.** A user provider implementation that authenticates users against an external LDAP + server. + diff --git a/versioned_docs/version-0.11/user-guide/deployments/authentication/static.md b/versioned_docs/version-0.11/user-guide/deployments/authentication/static.md new file mode 100644 index 000000000..1e7fa0489 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/deployments/authentication/static.md @@ -0,0 +1,25 @@ +--- +description: Instructions for setting up static user authentication in GreptimeDB using a configuration file with user credentials. +--- + +# Static User Provider + +GreptimeDB offers a simple built-in mechanism for authentication, allowing users to configure either a fixed account for convenient usage or an account file for multiple user accounts. By passing in a file, GreptimeDB loads all users listed within it. + +GreptimeDB reads the user and password on each line using `=` as a separator, just like a command-line config. For example: + +``` +greptime_user=greptime_pwd +alice=aaa +bob=bbb +``` + +then start server with `--user-provider` parameter: + +```shell +./greptime standalone start --user-provider=static_user_provider:file: +``` + +Now, user `alice` with password `aaa` and user `bob` with password `bbb` are loaded into GreptimeDB's memory. You can create a connection to GreptimeDB using these user accounts. + +Note: The content of the file is loaded into the database while starting up. Modifying or appending the file won't take effect while the database is up and running. diff --git a/versioned_docs/version-0.11/user-guide/deployments/configuration.md b/versioned_docs/version-0.11/user-guide/deployments/configuration.md new file mode 100644 index 000000000..6537d18a4 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/deployments/configuration.md @@ -0,0 +1,846 @@ +--- +description: Detailed guide on configuring GreptimeDB, including command line options, configuration file options, environment variables, and default values for various components and features. +--- + +# Configuration + +GreptimeDB supports **layered configuration** with the following precedence order (where each item overrides the one below it): + +- Greptime command line options +- Configuration file options +- Environment variables +- Default values + +You only need to set up the configurations you require. +GreptimeDB will assign default values for any settings not configured. + +## How to set up configurations + +### Greptime command line options + +You can specify several configurations using command line arguments. +For example, to start GreptimeDB in standalone mode with a configured HTTP address: + +```shell +greptime standalone start --http-addr 127.0.0.1:4000 +``` + +For all the options supported by the Greptime command line, +refer to the [GreptimeDB Command Line Interface](/reference/command-lines.md). + +### Configuration file options + +You can specify configurations in a TOML file. +For example, create a configuration file `standalone.example.toml` as shown below: + +```toml +[storage] +type = "File" +data_home = "/tmp/greptimedb/" +``` + +Then, specify the configuration file using the command line argument `-c [file_path]`. + +```sh +greptime [standalone | frontend | datanode | metasrv] start -c config/standalone.example.toml +``` + +For example, to start in standalone mode: + +```bash +greptime standalone start -c standalone.example.toml +``` + +#### Example files + +Below are example configuration files for each GreptimeDB component, +including all available configurations. +In actual scenarios, +you only need to configure the required options and do not need to configure all options as in the sample file. + +- [standalone](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/standalone.example.toml) +- [frontend](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/frontend.example.toml) +- [datanode](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/datanode.example.toml) +- [flownode](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/flownode.example.toml) +- [metasrv](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/metasrv.example.toml) + +### Environment variable + +Every item in the configuration file can be mapped to environment variables. +For example, to set the `data_home` configuration item for the datanode using an environment variable: + +```toml +# ... +[storage] +data_home = "/data/greptimedb" +# ... +``` + +Use the following shell command to set the environment variable in the following format: + +``` +export GREPTIMEDB_DATANODE__STORAGE__DATA_HOME=/data/greptimedb +``` + +#### Environment Variable Rules + +- Each environment variable should have the component prefix, for example: + + - `GREPTIMEDB_FRONTEND` + - `GREPTIMEDB_METASRV` + - `GREPTIMEDB_DATANODE` + - `GREPTIMEDB_STANDALONE` + +- Use **double underscore `__`** separators. For example, the data structure `storage.data_home` is transformed to `STORAGE__DATA_HOME`. + +The environment variable also accepts lists that are separated by commas `,`, for example: + +``` +GREPTIMEDB_METASRV__META_CLIENT__METASRV_ADDRS=127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003 +``` + +## Options + +In this section, we will introduce some main configuration options. +For all options, refer to the [Configuration Reference](https://github.com/GreptimeTeam/greptimedb/blob/VAR::greptimedbVersion/config/config.md) on Github. + +### Protocol options + +Protocol options are valid in `frontend` and `standalone` subcommands, +specifying protocol server addresses and other protocol-related options. + +Below is an example configuration with default values. +You can change the values or disable certain protocols in your configuration file. +For example, to disable OpenTSDB protocol support, set the `enable` parameter to `false`. +Note that HTTP and gRPC protocols cannot be disabled for the database to function correctly. + +```toml +[http] +addr = "127.0.0.1:4000" +timeout = "30s" +body_limit = "64MB" + +[grpc] +addr = "127.0.0.1:4001" +runtime_size = 8 + +[mysql] +enable = true +addr = "127.0.0.1:4002" +runtime_size = 2 + +[mysql.tls] +mode = "disable" +cert_path = "" +key_path = "" +watch = false + +[postgres] +enable = true +addr = "127.0.0.1:4003" +runtime_size = 2 + +[postgres.tls] +mode = "disable" +cert_path = "" +key_path = "" +watch = false + +[opentsdb] +enable = true + +[influxdb] +enable = true + +[prom_store] +enable = true +with_metric_engine = true +``` + +The following table describes the options in detail: + +| Option | Key | Type | Description | +| ---------- | ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------- | +| http | | | HTTP server options | +| | addr | String | Server address, "127.0.0.1:4000" by default | +| | timeout | String | HTTP request timeout, "30s" by default | +| | body_limit | String | HTTP max body size, "64MB" by default | +| | is_strict_mode | Boolean | Whether to enable the strict verification mode of the protocol, which will slightly affect performance. False by default. | +| grpc | | | gRPC server options | +| | addr | String | Server address, "127.0.0.1:4001" by default | +| | runtime_size | Integer | The number of server worker threads, 8 by default | +| mysql | | | MySQL server options | +| | enable | Boolean | Whether to enable MySQL protocol, true by default | +| | addr | String | Server address, "127.0.0.1:4002" by default | +| | runtime_size | Integer | The number of server worker threads, 2 by default | +| influxdb | | | InfluxDB Protocol options | +| | enable | Boolean | Whether to enable InfluxDB protocol in HTTP API, true by default | +| opentsdb | | | OpenTSDB Protocol options | +| | enable | Boolean | Whether to enable OpenTSDB protocol in HTTP API, true by default | +| prom_store | | | Prometheus remote storage options | +| | enable | Boolean | Whether to enable Prometheus Remote Write and read in HTTP API, true by default | +| | with_metric_engine | Boolean | Whether to use the metric engine on Prometheus Remote Write, true by default | +| postgres | | | PostgresSQL server options | +| | enable | Boolean | Whether to enable PostgresSQL protocol, true by default | +| | addr | String | Server address, "127.0.0.1:4003" by default | +| | runtime_size | Integer | The number of server worker threads, 2 by default | + +For MySQL and Postgres interface, TLS can be configured to enable transport +layer security. + +| Option | Key | Type | Description | +|-------------------------------|-------------|---------|---------------------------------------------------------------| +| `mysql.tls` or `postgres.tls` | | | TLS configuration for MySQL and Postgres | +| | `mode` | String | TLS mode, options are `disable`, `prefer` and `require` | +| | `cert_path` | String | File path for TLS certificate | +| | `key_path` | String | File path for TLS private key | +| | `watch` | Boolean | Watch file system changes and reload certificate and key file | + +### Storage options + +The `storage` options are valid in datanode and standalone mode, which specify the database data directory and other storage-related options. + +GreptimeDB supports storing data in local file system, AWS S3 and compatible services (including MinIO, digitalocean space, Tencent Cloud Object Storage(COS), Baidu Object Storage(BOS) and so on), Azure Blob Storage and Aliyun OSS. + +| Option | Key | Type | Description | +| ------- | ----------------- | ------ | ------------------------------------------------------------- | +| storage | | | Storage options | +| | type | String | Storage type, supports "File", "S3" and "Oss" etc. | +| File | | | Local file storage options, valid when type="File" | +| | data_home | String | Database storage root directory, "/tmp/greptimedb" by default | +| S3 | | | AWS S3 storage options, valid when type="S3" | +| | name | String | The storage provider name, default is `S3` | +| | bucket | String | The S3 bucket name | +| | root | String | The root path in S3 bucket | +| | endpoint | String | The API endpoint of S3 | +| | region | String | The S3 region | +| | access_key_id | String | The S3 access key id | +| | secret_access_key | String | The S3 secret access key | +| Oss | | | Aliyun OSS storage options, valid when type="Oss" | +| | name | String | The storage provider name, default is `Oss` | +| | bucket | String | The OSS bucket name | +| | root | String | The root path in OSS bucket | +| | endpoint | String | The API endpoint of OSS | +| | access_key_id | String | The OSS access key id | +| | secret_access_key | String | The OSS secret access key | +| Azblob | | | Azure Blob Storage options, valid when type="Azblob" | +| | name | String | The storage provider name, default is `Azblob` | +| | container | String | The container name | +| | root | String | The root path in container | +| | endpoint | String | The API endpoint of Azure Blob Storage | +| | account_name | String | The account name of Azure Blob Storage | +| | account_key | String | The access key | +| | sas_token | String | The shared access signature | +| Gsc | | | Google Cloud Storage options, valid when type="Gsc" | +| | name | String | The storage provider name, default is `Gsc` | +| | root | String | The root path in Gsc bucket | +| | bucket | String | The Gsc bucket name | +| | scope | String | The Gsc service scope | +| | credential_path | String | The Gsc credentials path | +| | endpoint | String | The API endpoint of Gsc | + +A file storage sample configuration: + +```toml +[storage] +type = "File" +data_home = "/tmp/greptimedb/" +``` + +A S3 storage sample configuration: + +```toml +[storage] +type = "S3" +bucket = "test_greptimedb" +root = "/greptimedb" +access_key_id = "" +secret_access_key = "" +``` + +### Storage http client + +`[storage.http_client]` sets the options for the http client that is used to send requests to the storage service. + +Only applied for storage types "S3", "Oss", "Azblob" and "Gcs". + +| Key | Type | Default | Description | +|--------------------------|---------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| `pool_max_idle_per_host` | Integer | 1024 | The maximum idle connection per host allowed in the pool. | +| `connect_timeout` | String | "30s" (30 seconds) | The timeout for only the connect phase of a http client. | +| `timeout` | String | "30s" (30 seconds) | The total request timeout, applied from when the request starts connecting until the response body has finished. Also considered a total deadline. | +| `pool_idle_timeout` | String | "90s" (90 seconds) | The timeout for idle sockets being kept-alive. | + +### Storage engine provider + +`[[storage.providers]]` setups the table storage engine providers. Based on these providers, you can create a table with a specified storage, see [create table](/reference/sql/create.md#create-table): + +```toml +# Allows using multiple storages +[[storage.providers]] +name = "S3" +type = "S3" +bucket = "test_greptimedb" +root = "/greptimedb" +access_key_id = "" +secret_access_key = "" + +[[storage.providers]] +name = "Gcs" +type = "Gcs" +bucket = "test_greptimedb" +root = "/greptimedb" +credential_path = "" +``` + +All configured providers' names can be used as the `storage` option when creating tables. + +For storage from the same provider, if you want to use different S3 buckets as storage engines for different tables, you can set different `name` values and specify the `storage` option when creating the table. + +### Object storage cache + +When using remote storage services like AWS S3, Alibaba Cloud OSS, or Azure Blob Storage, fetching data during queries can be time-consuming. To address this, GreptimeDB provides a local cache mechanism to speed up repeated data access. + +Since version `v0.11`, GreptimeDB enables local file caching for remote object storage by default. The default cache directory is located at `{data_home}/object_cache`, with both read and write cache capacity set to `5GiB`. + +For versions before v0.11, you need to manually enable the read cache by configuring `cache_path` in the storage settings: + +```toml +[storage] +type = "S3" +bucket = "test_greptimedb" +root = "/greptimedb" +access_key_id = "" +secret_access_key = "" +## Enable object storage caching +cache_path = "/var/data/s3_read_cache" +cache_capacity = "5Gib" +``` + +The `cache_path` specifies the local directory for storing cache files, while `cache_capacity` determines the maximum total file size allowed in the cache directory in bytes. You can disable the read cache by setting `cache_path` to an empty string. + +For write cache in versions before v0.11, you need to enable it by setting `enable_experimental_write_cache` to `true` in the `[region_engine.mito]` section: + +```toml +[[region_engine]] +[region_engine.mito] + +enable_experimental_write_cache = true +experimental_write_cache_path = "/var/data/s3_write_cache" +experimental_write_cache_size = "5GiB" +``` + +The default value of `experimental_write_cache_path` is `{data_home}/object_cache/write`. +To disable the write cache, set `enable_experimental_write_cache` to `false`. + +Read [Performance Tuning Tips](/user-guide/administration/performance-tuning-tips) for more detailed info. + +### WAL options + +The `[wal]` section in datanode or standalone config file configures the options of Write-Ahead-Log: + +#### Local WAL + +```toml +[wal] +provider = "raft_engine" +file_size = "256MB" +purge_threshold = "4GB" +purge_interval = "10m" +read_batch_size = 128 +sync_write = false +``` + +- `dir`: is the directory where to write logs. When using `File` storage, it's `{data_home}/wal` by default. It must be configured explicitly when using other storage types such as `S3` etc. +- `file_size`: the maximum size of the WAL log file, default is `256MB`. +- `purge_threshold` and `purge_interval`: control the purging of wal files, default is `4GB`. +- `sync_write`: whether to call `fsync` when writing every log. + +#### Remote WAL + +```toml +[wal] +provider = "kafka" +broker_endpoints = ["127.0.0.1:9092"] +max_batch_bytes = "1MB" +consumer_wait_timeout = "100ms" +backoff_init = "500ms" +backoff_max = "10s" +backoff_base = 2 +backoff_deadline = "5mins" +overwrite_entry_start_id = false +``` + +- `broker_endpoints`: The Kafka broker endpoints. +- `max_batch_bytes`: The max size of a single producer batch. +- `consumer_wait_timeout`: The consumer wait timeout. +- `backoff_init`: The initial backoff delay. +- `backoff_max`: The maximum backoff delay. +- `backoff_base`: The exponential backoff rate. +- `backoff_deadline`: The deadline of retries. +- `overwrite_entry_start_id`: This option ensures that when Kafka messages are accidentally deleted, the system can still successfully replay memtable data without throwing an out-of-range error. However, enabling this option might lead to unexpected data loss, as the system will skip over missing entries instead of treating them as critical errors. + +##### Remote WAL Authentication (Optional) + +```toml +[wal.sasl] +type = "SCRAM-SHA-512" +username = "user" +password = "secret" +``` + +The SASL configuration for Kafka client, available SASL mechanisms: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`. + +##### Remote WAL TLS (Optional) + +```toml +[wal.tls] +server_ca_cert_path = "/path/to/server_cert" +client_cert_path = "/path/to/client_cert" +client_key_path = "/path/to/key" +``` + +The TLS configuration for Kafka client, support modes: TLS (using system ca certs), TLS (with specified ca certs), mTLS. + +Examples: + +**TLS (using system ca certs)** + +```toml +[wal.tls] +``` + +**TLS (with specified ca cert)** + +```toml +[wal.tls] +server_ca_cert_path = "/path/to/server_cert" +``` + +**mTLS** + +```toml +[wal.tls] +server_ca_cert_path = "/path/to/server_cert" +client_cert_path = "/path/to/client_cert" +client_key_path = "/path/to/key" +``` + +### Logging options + +`frontend`, `metasrv`, `datanode` and `standalone` can all configure log and tracing related parameters in the `[logging]` section: + +```toml +[logging] +dir = "/tmp/greptimedb/logs" +level = "info" +enable_otlp_tracing = false +otlp_endpoint = "localhost:4317" +append_stdout = true +[logging.tracing_sample_ratio] +default_ratio = 1.0 +``` + +- `dir`: log output directory. +- `level`: output log level, available log level are `info`, `debug`, `error`, `warn`, the default level is `info`. +- `enable_otlp_tracing`: whether to turn on tracing, not turned on by default. +- `otlp_endpoint`: Export the target endpoint of tracing using gRPC-based OTLP protocol, the default value is `localhost:4317`. +- `append_stdout`: Whether to append logs to stdout. Defaults to `true`. +- `tracing_sample_ratio`: This field can configure the sampling rate of tracing. How to use `tracing_sample_ratio`, please refer to [How to configure tracing sampling rate](/user-guide/administration/monitoring/tracing.md#guide-how-to-configure-tracing-sampling-rate). + +How to use distributed tracing, please reference [Tracing](/user-guide/administration/monitoring/tracing.md#tutorial-use-jaeger-to-trace-greptimedb) + +### Region engine options + +The parameters corresponding to different storage engines can be configured for `datanode` and `standalone` in the `[region_engine]` section. Currently, only options for `mito` region engine is available. + +Frequently used options: + +```toml +[[region_engine]] +[region_engine.mito] +num_workers = 8 +manifest_checkpoint_distance = 10 +max_background_jobs = 4 +auto_flush_interval = "1h" +global_write_buffer_size = "1GB" +global_write_buffer_reject_size = "2GB" +sst_meta_cache_size = "128MB" +vector_cache_size = "512MB" +page_cache_size = "512MB" +sst_write_buffer_size = "8MB" +scan_parallelism = 0 + +[region_engine.mito.inverted_index] +create_on_flush = "auto" +create_on_compaction = "auto" +apply_on_query = "auto" +mem_threshold_on_create = "64M" +intermediate_path = "" + +[region_engine.mito.memtable] +type = "time_series" +``` + +The `mito` engine provides an experimental memtable which optimizes for write performance and memory efficiency under large amounts of time-series. Its read performance might not as fast as the default `time_series` memtable. + +```toml +[region_engine.mito.memtable] +type = "partition_tree" +index_max_keys_per_shard = 8192 +data_freeze_threshold = 32768 +fork_dictionary_bytes = "1GiB" +``` + +Available options: + +| Key | Type | Default | Descriptions | +| ---------------------------------------- | ------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `num_workers` | Integer | `8` | Number of region workers. | +| `manifest_checkpoint_distance` | Integer | `10` | Number of meta action updated to trigger a new checkpoint for the manifest. | +| `max_background_jobs` | Integer | `4` | Max number of running background jobs | +| `auto_flush_interval` | String | `1h` | Interval to auto flush a region if it has not flushed yet. | +| `global_write_buffer_size` | String | `1GB` | Global write buffer size for all regions. If not set, it's default to 1/8 of OS memory with a max limitation of 1GB. | +| `global_write_buffer_reject_size` | String | `2GB` | Global write buffer size threshold to reject write requests. If not set, it's default to 2 times of `global_write_buffer_size` | +| `sst_meta_cache_size` | String | `128MB` | Cache size for SST metadata. Setting it to 0 to disable the cache.
If not set, it's default to 1/32 of OS memory with a max limitation of 128MB. | +| `vector_cache_size` | String | `512MB` | Cache size for vectors and arrow arrays. Setting it to 0 to disable the cache.
If not set, it's default to 1/16 of OS memory with a max limitation of 512MB. | +| `page_cache_size` | String | `512MB` | Cache size for pages of SST row groups. Setting it to 0 to disable the cache.
If not set, it's default to 1/8 of OS memory. | +| `selector_result_cache_size` | String | `512MB` | Cache size for time series selector (e.g. `last_value()`). Setting it to 0 to disable the cache.
If not set, it's default to 1/8 of OS memory. | +| `sst_write_buffer_size` | String | `8MB` | Buffer size for SST writing. | +| `scan_parallelism` | Integer | `0` | Parallelism to scan a region (default: 1/4 of cpu cores).
- `0`: using the default value (1/4 of cpu cores).
- `1`: scan in current thread.
- `n`: scan in parallelism n. | +| `inverted_index` | -- | -- | The options for inverted index in Mito engine. | +| `inverted_index.create_on_flush` | String | `auto` | Whether to create the index on flush.
- `auto`: automatically
- `disable`: never | +| `inverted_index.create_on_compaction` | String | `auto` | Whether to create the index on compaction.
- `auto`: automatically
- `disable`: never | +| `inverted_index.apply_on_query` | String | `auto` | Whether to apply the index on query
- `auto`: automatically
- `disable`: never | +| `inverted_index.mem_threshold_on_create` | String | `64M` | Memory threshold for performing an external sort during index creation.
Setting to empty will disable external sorting, forcing all sorting operations to happen in memory. | +| `inverted_index.intermediate_path` | String | `""` | File system path to store intermediate files for external sorting (default `{data_home}/index_intermediate`). | +| `memtable.type` | String | `time_series` | Memtable type.
- `time_series`: time-series memtable
- `partition_tree`: partition tree memtable (experimental) | +| `memtable.index_max_keys_per_shard` | Integer | `8192` | The max number of keys in one shard.
Only available for `partition_tree` memtable. | +| `memtable.data_freeze_threshold` | Integer | `32768` | The max rows of data inside the actively writing buffer in one shard.
Only available for `partition_tree` memtable. | +| `memtable.fork_dictionary_bytes` | String | `1GiB` | Max dictionary bytes.
Only available for `partition_tree` memtable. | + +### Specify meta client + +The `meta_client` options are valid in `datanode` and `frontend` mode, which specify the Metasrv client information. + +```toml +metasrv_addrs = ["127.0.0.1:3002"] +timeout = "3s" +connect_timeout = "1s" +ddl_timeout = "10s" +tcp_nodelay = true +``` + +The `meta_client` configures the Metasrv client, including: + +- `metasrv_addrs`: The Metasrv address list. +- `timeout`: operation timeout, `3s` by default. +- `connect_timeout`, connect server timeout, `1s` by default. +- `ddl_timeout`, DDL execution timeout, `10s` by default. +- `tcp_nodelay`, `TCP_NODELAY` option for accepted connections, true by default. + +### Monitor metrics options + +These options are used to save system metrics to GreptimeDB itself. +For instructions on how to use this feature, please refer to the [Monitoring](/user-guide/administration/monitoring/export-metrics.md) guide. + +```toml +[export_metrics] +# Whether to enable export_metrics +enable=true +# Export time interval +write_interval = "30s" +``` + +- `enable`: Whether to enable export_metrics, `false` by default. +- `write_interval`: Export time interval. + +#### `self_import` method + +Only `frontend` and `standalone` support exporting metrics using `self_import` method. + +```toml +[export_metrics] +# Whether to enable export_metrics +enable=true +# Export time interval +write_interval = "30s" +[export_metrics.self_import] +db = "information_schema" +``` + +- `db`: The default database used by `self_import` is `information_schema`. You can also create another database for saving system metrics. + +#### `remote_write` method + +The `remote_write` method is supported by `datanode`, `frontend`, `metasrv`, and `standalone`. +It sends metrics to a receiver compatible with the [Prometheus Remote-Write protocol](https://prometheus.io/docs/concepts/remote_write_spec/). + +```toml +[export_metrics] +# Whether to enable export_metrics +enable=true +# Export time interval +write_interval = "30s" +[export_metrics.remote_write] +# URL specified by Prometheus Remote-Write protocol +url = "http://127.0.0.1:4000/v1/prometheus/write?db=information_schema" +# Some optional HTTP parameters, such as authentication information +headers = { Authorization = "Basic Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=" } +``` + +- `url`: URL specified by Prometheus Remote-Write protocol. +- `headers`: Some optional HTTP parameters, such as authentication information. + +### Mode option + +The `mode` option is valid in `datanode`, `frontend` and `standalone`, which specify the running mode of the component. + +In the configuration files of `datanode` and `frontend` of distributed GreptimeDB, the value needs to be set as `distributed`: + +```toml +mode = "distributed" +``` + +In the configuration files of standalone GreptimeDB, the value needs to be set as `standalone`: + +```toml +mode = "standalone" +``` + +### Heartbeat configuration +Heartbeat configuration is available in `frontend` and `datanode`. +```toml +[heartbeat] +interval = "3s" +retry_interval = "3s" +``` + +| Key | Type | Default | Description | +|----------------------------|--------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| `heartbeat` | -- | -- | -- | +| `heartbeat.interval` | String | `3s` | Interval for sending heartbeat messages to the Metasrv. | +| `heartbeat.retry_interval` | String | `3s` | Interval for retrying to establish the heartbeat connection to the Metasrv. Note that this option is ignored in Datanode heartbeat implementation because the Datanode must renew its lease through heartbeat within the keep-alive mechanism's lease period. It has a special retry strategy and doesn't allow custom configuration. | + +### Default time zone configuration + +The `default_timezone` option is applicable in both `frontend` and `standalone` modes, with a default value of `UTC`. +It specifies the default client timezone for interactions with GreptimeDB. +If the time zone is [specified in the clients](/user-guide/timezone.md#specify-time-zone-in-clients), this option will be overridden for that client session. + +```toml +default_timezone = "UTC" +``` + +The `default_timezone` value can be any named time zone, such as `Europe/Berlin` or `Asia/Shanghai`. +For information on how the client time zone affects data ingestion and querying, +refer to the [Time Zone](/user-guide/timezone.md#impact-of-time-zone-on-sql-statements) guide. + +### Metasrv-only configuration + +```toml +# The working home directory. +data_home = "/tmp/metasrv/" +# The bind address of metasrv, "127.0.0.1:3002" by default. +bind_addr = "127.0.0.1:3002" +# The communication server address for frontend and datanode to connect to metasrv, "127.0.0.1:3002" by default for localhost. +server_addr = "127.0.0.1:3002" +# Store server address, "127.0.0.1:2379" by default with etcd store. +store_addr = "127.0.0.1:2379" +# Datanode selector type. +# - "lease_based" (default value). +# - "load_based" +# For details, please see "https://docs.greptime.com/contributor-guide/meta/selector". +selector = "LeaseBased" +# Store data in memory, false by default. +use_memory_store = false +## Whether to enable region failover. +## This feature is only available on GreptimeDB running on cluster mode and +## - Using Remote WAL +## - Using shared storage (e.g., s3). +enable_region_failover = false +# The datastore for metasrv. +## Available datastore: +## - "EtcdStore" (default) +## - "MemoryStore" (In memory metadata storage - only used for testing.) +## - "PostgresStore" +backend = "EtcdStore" + +## Procedure storage options. +[procedure] + +## Procedure max retry time. +max_retry_times = 12 + +## Initial retry delay of procedures, increases exponentially +retry_delay = "500ms" + +# Failure detectors options. +[failure_detector] + +## The threshold value used by the failure detector to determine failure conditions. +threshold = 8.0 + +## The minimum standard deviation of the heartbeat intervals, used to calculate acceptable variations. +min_std_deviation = "100ms" + +## The acceptable pause duration between heartbeats, used to determine if a heartbeat interval is acceptable. +acceptable_heartbeat_pause = "10000ms" + +## The initial estimate of the heartbeat interval used by the failure detector. +first_heartbeat_estimate = "1000ms" + +## Datanode options. +[datanode] + +## Datanode client options. +[datanode.client] + +## Operation timeout. +timeout = "10s" + +## Connect server timeout. +connect_timeout = "10s" + +## `TCP_NODELAY` option for accepted connections. +tcp_nodelay = true + +[wal] +# Available wal providers: +# - `raft_engine` (default): there're none raft-engine wal config since metasrv only involves in remote wal currently. +# - `kafka`: metasrv **have to be** configured with kafka wal config when using kafka wal provider in datanode. +provider = "raft_engine" + +# Kafka wal config. + +## The broker endpoints of the Kafka cluster. +broker_endpoints = ["127.0.0.1:9092"] + +## Automatically create topics for WAL. +## Set to `true` to automatically create topics for WAL. +## Otherwise, use topics named `topic_name_prefix_[0..num_topics)` +auto_create_topics = true + +## Number of topics. +num_topics = 64 + +## Topic selector type. +## Available selector types: +## - `round_robin` (default) +selector_type = "round_robin" + +## A Kafka topic is constructed by concatenating `topic_name_prefix` and `topic_id`. +topic_name_prefix = "greptimedb_wal_topic" + +## Expected number of replicas of each partition. +replication_factor = 1 + +## Above which a topic creation operation will be cancelled. +create_topic_timeout = "30s" +## The initial backoff for kafka clients. +backoff_init = "500ms" + +## The maximum backoff for kafka clients. +backoff_max = "10s" + +## Exponential backoff rate, i.e. next backoff = base * current backoff. +backoff_base = 2 + +## Stop reconnecting if the total wait time reaches the deadline. If this config is missing, the reconnecting won't terminate. +backoff_deadline = "5mins" + +# The Kafka SASL configuration. +# **It's only used when the provider is `kafka`**. +# Available SASL mechanisms: +# - `PLAIN` +# - `SCRAM-SHA-256` +# - `SCRAM-SHA-512` +# [wal.sasl] +# type = "SCRAM-SHA-512" +# username = "user_kafka" +# password = "secret" + +# The Kafka TLS configuration. +# **It's only used when the provider is `kafka`**. +# [wal.tls] +# server_ca_cert_path = "/path/to/server_cert" +# client_cert_path = "/path/to/client_cert" +# client_key_path = "/path/to/key" + +``` + +| Key | Type | Default | Descriptions | +| --------------------------------------------- | ------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data_home` | String | `/tmp/metasrv/` | The working home directory. | +| `bind_addr` | String | `127.0.0.1:3002` | The bind address of metasrv. | +| `server_addr` | String | `127.0.0.1:3002` | The communication server address for frontend and datanode to connect to metasrv, "127.0.0.1:3002" by default for localhost. | +| `store_addrs` | Array | `["127.0.0.1:2379"]` | Store server address (default to etcd) store. | +| `selector` | String | `lease_based` | Datanode selector type.
- `lease_based` (default value).
- `load_based`
For details, see [Selector](/contributor-guide/metasrv/selector.md) | +| `use_memory_store` | Bool | `false` | Store data in memory. | +| `enable_region_failover` | Bool | `false` | Whether to enable region failover.
This feature is only available on GreptimeDB running on cluster mode and
- Using Remote WAL
- Using shared storage (e.g., s3). | +| `procedure` | -- | -- | Procedure storage options. | +| `procedure.max_retry_times` | Integer | `12` | Procedure max retry time. | +| `procedure.retry_delay` | String | `500ms` | Initial retry delay of procedures, increases exponentially | +| `failure_detector` | -- | -- | -- | +| `failure_detector.threshold` | Float | `8.0` | The threshold value used by the failure detector to determine failure conditions. | +| `failure_detector.min_std_deviation` | String | `100ms` | The minimum standard deviation of the heartbeat intervals, used to calculate acceptable variations. | +| `failure_detector.acceptable_heartbeat_pause` | String | `10000ms` | The acceptable pause duration between heartbeats, used to determine if a heartbeat interval is acceptable. | +| `failure_detector.first_heartbeat_estimate` | String | `1000ms` | The initial estimate of the heartbeat interval used by the failure detector. | +| `datanode` | -- | -- | Datanode options. | +| `datanode.client` | -- | -- | Datanode client options. | +| `datanode.client.timeout` | String | `10s` | Operation timeout. | +| `datanode.client.connect_timeout` | String | `10s` | Connect server timeout. | +| `datanode.client.tcp_nodelay` | Bool | `true` | `TCP_NODELAY` option for accepted connections. | +| `wal` | -- | -- | -- | +| `wal.provider` | String | `raft_engine` | -- | +| `wal.broker_endpoints` | Array | -- | The broker endpoints of the Kafka cluster. | +| `wal.auto_create_topics` | Bool | `true` | Automatically create topics for WAL.
Set to `true` to automatically create topics for WAL.
Otherwise, use topics named `topic_name_prefix_[0..num_topics)` | +| `wal.num_topics` | Integer | `64` | Number of topics. | +| `wal.selector_type` | String | `round_robin` | Topic selector type.
Available selector types:
- `round_robin` (default) | +| `wal.topic_name_prefix` | String | `greptimedb_wal_topic` | A Kafka topic is constructed by concatenating `topic_name_prefix` and `topic_id`. | +| `wal.replication_factor` | Integer | `1` | Expected number of replicas of each partition. | +| `wal.create_topic_timeout` | String | `30s` | Above which a topic creation operation will be cancelled. | +| `wal.backoff_init` | String | `500ms` | The initial backoff for kafka clients. | +| `wal.backoff_max` | String | `10s` | The maximum backoff for kafka clients. | +| `wal.backoff_base` | Integer | `2` | Exponential backoff rate, i.e. next backoff = base \* current backoff. | +| `wal.backoff_deadline` | String | `5mins` | Stop reconnecting if the total wait time reaches the deadline. If this config is missing, the reconnecting won't terminate. | +| `wal.sasl` | String | -- | The Kafka SASL configuration. | +| `wal.sasl.type` | String | -- | The SASL mechanisms, available values: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`. | +| `wal.sasl.username` | String | -- | The SASL username. | +| `wal.sasl.password` | String | -- | The SASL password. | +| `wal.tls` | String | -- | The Kafka TLS configuration. | +| `wal.tls.server_ca_cert_path` | String | -- | The path of trusted server ca certs. | +| `wal.tls.client_cert_path` | String | -- | The path of client cert (Used for enable mTLS). | +| `wal.tls.client_key_path` | String | -- | The path of client key (Used for enable mTLS). | + +### Datanode-only configuration + +```toml +node_id = 42 +rpc_hostname = "127.0.0.1" +rpc_addr = "127.0.0.1:3001" +rpc_runtime_size = 8 +``` + +| Key | Type | Description | +| ---------------- | ------- | ------------------------------------------------------- | +| node_id | Integer | The datanode identifier, should be unique. | +| rpc_hostname | String | Hostname of this node. | +| rpc_addr | String | gRPC server address, `"127.0.0.1:3001"` by default. | +| rpc_runtime_size | Integer | The number of gRPC server worker threads, 8 by default. | + +### Frontend-only configuration + +```toml +[datanode] +[datanode.client] +connect_timeout = "1s" +tcp_nodelay = true +``` + +| Key | Type | Default | Description | +|-----------------------------------|--------|---------|------------------------------------------------| +| `datanode` | -- | -- | Datanode options. | +| `datanode.client` | -- | -- | Datanode client options. | +| `datanode.client.connect_timeout` | String | `1s` | Connect server timeout. | +| `datanode.client.tcp_nodelay` | Bool | `true` | `TCP_NODELAY` option for accepted connections. | diff --git a/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/getting-started.md b/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/getting-started.md new file mode 100644 index 000000000..c8523015a --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/getting-started.md @@ -0,0 +1,499 @@ +--- +description: Step-by-step guide to deploying a GreptimeDB cluster on Kubernetes using the GreptimeDB Operator, including prerequisites, cluster creation, installation, and verification. +--- + +# Getting Started + +In this guide, you will learn how to deploy a GreptimeDB cluster on Kubernetes using the GreptimeDB Operator. + +:::note +The following output may have minor differences depending on the versions of the Helm charts and environment. +::: + +## Prerequisites + +- [Docker](https://docs.docker.com/get-started/get-docker/) >= v23.0.0 +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) >= v1.18.0 +- [Helm](https://helm.sh/docs/intro/install/) >= v3.0.0 +- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) >= v0.20.0 + +## Create a test Kubernetes cluster + +:::warning +Using `kind` is not recommended for production environments or performance testing. For such use cases, we recommend using cloud-managed Kubernetes services such as [Amazon EKS](https://aws.amazon.com/eks/), [Google GKE](https://cloud.google.com/kubernetes-engine/), or [Azure AKS](https://azure.microsoft.com/en-us/services/kubernetes-service/), or deploying your own production-grade Kubernetes cluster. +::: + +There are many ways to create a Kubernetes cluster for testing purposes. In this guide, we will use [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) to create a local Kubernetes cluster. You can skip this step if you want to use the existing Kubernetes cluster. + +Here is an example using `kind` v0.20.0: + +```bash +kind create cluster +``` + +
+ Expected Output +```bash +Creating cluster "kind" ... + ✓ Ensuring node image (kindest/node:v1.27.3) 🖼 + ✓ Preparing nodes 📦 + ✓ Writing configuration 📜 + ✓ Starting control-plane 🕹️ + ✓ Installing CNI 🔌 + ✓ Installing StorageClass 💾 +Set kubectl context to "kind-kind" +You can now use your cluster with: + +kubectl cluster-info --context kind-kind + +Thanks for using kind! 😊 +``` +
+ +Check the status of the cluster: + +```bash +kubectl cluster-info +``` + +
+ Expected Output +```bash +Kubernetes control plane is running at https://127.0.0.1:60495 +CoreDNS is running at https://127.0.0.1:60495/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy + +To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. +``` +
+ +## Add the Greptime Helm repository + +We provide the [official Helm repository](https://github.com/GreptimeTeam/helm-charts) for the GreptimeDB Operator and GreptimeDB cluster. You can add the repository by running the following command: + +```bash +helm repo add greptime https://greptimeteam.github.io/helm-charts/ +helm repo update +``` + +Check the charts in the Greptime Helm repository: + +``` +helm search repo greptime +``` + +
+ Expected Output +```bash +NAME CHART VERSION APP VERSION DESCRIPTION +greptime/greptimedb-cluster 0.2.25 0.9.5 A Helm chart for deploying GreptimeDB cluster i... +greptime/greptimedb-operator 0.2.9 0.1.3-alpha.1 The greptimedb-operator Helm chart for Kubernetes. +greptime/greptimedb-standalone 0.1.27 0.9.5 A Helm chart for deploying standalone greptimedb +``` +
+ +## Install and verify the GreptimeDB Operator + +It's ready to use Helm to install the GreptimeDB Operator on the Kubernetes cluster. + +### Install the GreptimeDB Operator + +The [GreptimeDB Operator](https://github.com/GrepTimeTeam/greptimedb-operator) is a Kubernetes operator that manages the lifecycle of GreptimeDB cluster. + +Let's install the latest version of the GreptimeDB Operator in the `greptimedb-admin` namespace: + +```bash +helm install greptimedb-operator greptime/greptimedb-operator -n greptimedb-admin --create-namespace +``` + +
+ Expected Output +```bash +NAME: greptimedb-operator +LAST DEPLOYED: Tue Oct 29 18:40:10 2024 +NAMESPACE: greptimedb-admin +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +*********************************************************************** + Welcome to use greptimedb-operator + Chart version: 0.2.9 + GreptimeDB Operator version: 0.1.3-alpha.1 +*********************************************************************** + +Installed components: +* greptimedb-operator + +The greptimedb-operator is starting, use `kubectl get deployments greptimedb-operator -n greptimedb-admin` to check its status. +``` +
+ +:::note +There is another way to install the GreptimeDB Operator by using `kubectl` and `bundle.yaml` from the latest release: + +```bash +kubectl apply -f \ + https://github.com/GreptimeTeam/greptimedb-operator/releases/latest/download/bundle.yaml \ + --server-side +``` + +This method is only suitable for quickly deploying GreptimeDB Operator in the test environments and is not recommended for production use. +::: + +### Verify the GreptimeDB Operator installation + +Check the status of the GreptimeDB Operator: + +```bash +kubectl get pods -n greptimedb-admin -l app.kubernetes.io/instance=greptimedb-operator +``` + +
+ Expected Output +```bash +NAME READY STATUS RESTARTS AGE +greptimedb-operator-68d684c6cf-qr4q4 1/1 Running 0 4m8s +``` +
+ +You also can check the CRD installation: + +```bash +kubectl get crds | grep greptime +``` + +
+ Expected Output +```bash +greptimedbclusters.greptime.io 2024-10-28T08:46:27Z +greptimedbstandalones.greptime.io 2024-10-28T08:46:27Z +``` +
+ +The GreptimeDB Operator will use `greptimedbclusters.greptime.io` and `greptimedbstandalones.greptime.io` CRDs to manage GreptimeDB cluster and standalone resources. + +## Install the etcd cluster + +The GreptimeDB cluster requires an etcd cluster for metadata storage. Let's install an etcd cluster using Bitnami's etcd Helm [chart](https://hub.docker.com/r/bitnami/etcd). + +```bash +helm install etcd \ + oci://registry-1.docker.io/bitnamicharts/etcd \ + --version 10.2.12 \ + --set replicaCount=3 \ + --set auth.rbac.create=false \ + --set auth.rbac.token.enabled=false \ + --create-namespace \ + -n etcd-cluster +``` + +
+ Expected Output +```bash +NAME: etcd +LAST DEPLOYED: Mon Oct 28 17:01:38 2024 +NAMESPACE: etcd-cluster +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +CHART NAME: etcd +CHART VERSION: 10.2.12 +APP VERSION: 3.5.15 + +** Please be patient while the chart is being deployed ** + +etcd can be accessed via port 2379 on the following DNS name from within your cluster: + + etcd.etcd-cluster.svc.cluster.local + +To create a pod that you can use as a etcd client run the following command: + + kubectl run etcd-client --restart='Never' --image docker.io/bitnami/etcd:3.5.15-debian-12-r6 --env ETCDCTL_ENDPOINTS="etcd.etcd-cluster.svc.cluster.local:2379" --namespace etcd-cluster --command -- sleep infinity + +Then, you can set/get a key using the commands below: + + kubectl exec --namespace etcd-cluster -it etcd-client -- bash + etcdctl put /message Hello + etcdctl get /message + +To connect to your etcd server from outside the cluster execute the following commands: + + kubectl port-forward --namespace etcd-cluster svc/etcd 2379:2379 & + echo "etcd URL: http://127.0.0.1:2379" + +WARNING: There are "resources" sections in the chart not set. Using "resourcesPreset" is not recommended for production. For production installations, please set the following values according to your workload needs: +- disasterRecovery.cronjob.resources +- resources + +info https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +``` +
+ +Wait for the etcd cluster to be ready: + +```bash +kubectl get pods -n etcd-cluster -l app.kubernetes.io/instance=etcd +``` + +
+ Expected Output +```bash +NAME READY STATUS RESTARTS AGE +etcd-0 1/1 Running 0 2m8s +etcd-1 1/1 Running 0 2m8s +etcd-2 1/1 Running 0 2m8s +``` +
+ +You can test the etcd cluster by running the following command: + +```bash +kubectl -n etcd-cluster \ + exec etcd-0 -- etcdctl endpoint health \ + --endpoints=http://etcd-0.etcd-headless.etcd-cluster.svc.cluster.local:2379,http://etcd-1.etcd-headless.etcd-cluster.svc.cluster.local:2379,http://etcd-2.etcd-headless.etcd-cluster.svc.cluster.local:2379 +``` + +
+ Expected Output +```bash +http://etcd-1.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.008575ms +http://etcd-0.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.136576ms +http://etcd-2.etcd-headless.etcd-cluster.svc.cluster.local:2379 is healthy: successfully committed proposal: took = 3.147702ms +``` +
+ +## Install the GreptimeDB cluster with monitoring integration + +Now that the GreptimeDB Operator and etcd cluster are installed, you can deploy a minimum GreptimeDB cluster with monitoring integration: + +:::warning +The default configuration for the GreptimeDB cluster is not recommended for production use. +You should adjust the configuration according to your requirements. +::: + +```bash +helm install mycluster \ + --set monitoring.enabled=true \ + --set grafana.enabled=true \ + greptime/greptimedb-cluster \ + -n default +``` + +
+ Expected Output +```bash +Release "mycluster" does not exist. Installing it now. +NAME: mycluster +LAST DEPLOYED: Mon Oct 28 17:19:47 2024 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +NOTES: +*********************************************************************** + Welcome to use greptimedb-cluster + Chart version: 0.2.25 + GreptimeDB Cluster version: 0.9.5 +*********************************************************************** + +Installed components: +* greptimedb-frontend +* greptimedb-datanode +* greptimedb-meta + +The greptimedb-cluster is starting, use `kubectl get pods -n default` to check its status. +``` +
+ +When the `monitoring` option is enabled, a GreptimeDB Standalone instance named `${cluster}-monitor` will be deployed in the same namespace as the cluster to store monitoring data such as metrics and logs from the cluster. Additionally, we will deploy a [Vector](https://github.com/vectordotdev/vector) sidecar for each pod in the cluster to collect metrics and logs and send them to the GreptimeDB Standalone instance. + +When the `grafana` option is enabled, we will deploy a [Grafana](https://grafana.com/) instance and configure it to use the GreptimeDB Standalone instance as a data source (using both Prometheus and MySQL protocols), allowing us to visualize the GreptimeDB cluster's monitoring data out of the box. By default, Grafana will use `mycluster` and `default` as the cluster name and namespace to create data sources. If you want to monitor clusters with different names or namespaces, you'll need to create different data source configurations based on the cluster names and namespaces. You can create a `values.yaml` file like this: + +```yaml +grafana: + datasources: + datasources.yaml: + datasources: + - name: greptimedb-metrics + type: prometheus + url: http://${cluster}-monitor-standalone.${namespace}.svc.cluster.local:4000/v1/prometheus + access: proxy + isDefault: true + + - name: greptimedb-logs + type: mysql + url: ${cluster}-monitor-standalone.${namespace}.svc.cluster.local:4002 + access: proxy + database: public +``` + +The above configuration will create the default datasources for the GreptimeDB cluster metrics and logs in the Grafana dashboard: + +- `greptimedb-metrics`: The metrics of the cluster are stored in the standalone monitoring database and exposed in Prometheus protocol (`type: prometheus`); + +- `greptimedb-logs`: The logs of the cluster are stored in the standalone monitoring database and exposed in MySQL protocol (`type: mysql`). It uses the `public` database by default; + +Then replace `{cluster}` and `${namespace}` with your desired values and install the GreptimeDB cluster using the following command (please note that `{cluster}` and `${namespace}` in the command also need to be replaced): + +```bash +helm install {cluster} \ + --set monitoring.enabled=true \ + --set grafana.enabled=true \ + greptime/greptimedb-cluster \ + -f values.yaml \ + -n ${namespace} +``` + +When starting the cluster installation, we can check the status of the GreptimeDB cluster with the following command. If you use a different cluster name and namespace, you can replace `mycluster` and `default` with your configuration: + +```bash +kubectl -n default get greptimedbclusters.greptime.io mycluster +``` + +
+ Expected Output +```bash +NAME FRONTEND DATANODE META FLOWNODE PHASE VERSION AGE +mycluster 1 1 1 0 Running v0.9.5 5m12s +``` +
+ +The above command will show the status of the GreptimeDB cluster. When the `PHASE` is `Running`, it means the GreptimeDB cluster has been successfully started. + +You also can check the Pods status of the GreptimeDB cluster: + +```bash +kubectl -n default get pods +``` + +
+ Expected Output +```bash +NAME READY STATUS RESTARTS AGE +mycluster-datanode-0 2/2 Running 0 77s +mycluster-frontend-6ffdd549b-9s7gx 2/2 Running 0 66s +mycluster-grafana-675b64786-ktqps 1/1 Running 0 6m35s +mycluster-meta-58bc88b597-ppzvj 2/2 Running 0 86s +mycluster-monitor-standalone-0 1/1 Running 0 6m35s +``` +
+ +As you can see, we have created a minimal GreptimeDB cluster consisting of 1 frontend, 1 datanode, and 1 metasrv by default. For information about the components of a complete GreptimeDB cluster, you can refer to [architecture](/user-guide/concepts/architecture.md). Additionally, we have deployed a standalone GreptimeDB instance (`mycluster-monitor-standalone-0`) for storing monitoring data and a Grafana instance (`mycluster-grafana-675b64786-ktqps`) for visualizing the cluster's monitoring data. + +## Explore the GreptimeDB cluster + +:::warning +For production use, you should access the GreptimeDB cluster or Grafana inside the Kubernetes cluster or using the LoadBalancer type service. +::: + +### Access the GreptimeDB cluster + +You can access the GreptimeDB cluster by using `kubectl port-forward` the frontend service: + +```bash +kubectl -n default port-forward svc/mycluster-frontend 4000:4000 4001:4001 4002:4002 4003:4003 +``` + +
+ Expected Output +```bash +Forwarding from 127.0.0.1:4000 -> 4000 +Forwarding from [::1]:4000 -> 4000 +Forwarding from 127.0.0.1:4001 -> 4001 +Forwarding from [::1]:4001 -> 4001 +Forwarding from 127.0.0.1:4002 -> 4002 +Forwarding from [::1]:4002 -> 4002 +Forwarding from 127.0.0.1:4003 -> 4003 +Forwarding from [::1]:4003 -> 4003 +``` +
+ +Please note that when you use a different cluster name and namespace, you can use the following command, and replace `${cluster}` and `${namespace}` with your configuration: + +```bash +kubectl -n ${namespace} port-forward svc/${cluster}-frontend 4000:4000 4001:4001 4002:4002 4003:4003 +``` + +:::warning +If you want to expose the service to the public, you can use the `kubectl port-forward` command with the `--address` option: + +```bash +kubectl -n default port-forward --address 0.0.0.0 svc/mycluster-frontend 4000:4000 4001:4001 4002:4002 4003:4003 +``` + +Please make sure you have the proper security settings in place before exposing the service to the public. +::: + +Open the browser and navigate to `http://localhost:4000/dashboard` to access by the [GreptimeDB Dashboard](https://github.com/GrepTimeTeam/dashboard). + +If you want to use other tools like `mysql` or `psql` to connect to the GreptimeDB cluster, you can refer to the [Quick Start](/getting-started/quick-start.md). + +### Access the Grafana dashboard + +You can access the Grafana dashboard by using `kubctl port-forward` the Grafana service: + +```bash +kubectl -n default port-forward svc/mycluster-grafana 18080:80 +``` + +Please note that when you use a different cluster name and namespace, you can use the following command, and replace `${cluster}` and `${namespace}` with your configuration: + +```bash +kubectl -n ${namespace} port-forward svc/${cluster}-grafana 18080:80 +``` + +Then open your browser and navigate to `http://localhost:18080` to access the Grafana dashboard. The default username and password are `admin` and `gt-operator`: + +![Grafana Dashboard](/kubernetes-cluster-grafana-dashboard.jpg) + +There are three dashboards available: + +- **GreptimeDB Cluster Metrics**: Displays the metrics of the GreptimeDB cluster. +- **GreptimeDB Cluster Logs**: Displays the logs of the GreptimeDB cluster. +- **GreptimeDB Cluster Slow Queries**: Displays the slow queries of the GreptimeDB cluster. + +## Cleanup + +:::danger +The cleanup operation will remove the metadata and data of the GreptimeDB cluster. Please make sure you have backed up the data before proceeding. +::: + +### Stop the port-forwarding + +Stop the port-forwarding for the GreptimeDB cluster: + +```bash +pkill -f kubectl port-forward +``` + +### Uninstall the GreptimeDB cluster + +To uninstall the GreptimeDB cluster, you can use the following command: + +```bash +helm -n default uninstall mycluster +``` + +### Delete the PVCs + +The PVCs wouldn't be deleted by default for safety reasons. If you want to delete the PV data, you can use the following command: + +```bash +kubectl -n default delete pvc -l app.greptime.io/component=mycluster-datanode +kubectl -n default delete pvc -l app.greptime.io/component=mycluster-monitor-standalone +``` + +### Cleanup the etcd cluster + +You can use the following command to clean up the etcd cluster: + +```bash +kubectl -n etcd-cluster exec etcd-0 -- etcdctl del "" --from-key=true +``` + +### Destroy the Kubernetes cluster + +If you are using `kind` to create the Kubernetes cluster, you can use the following command to destroy the cluster: + +```bash +kind delete cluster +``` diff --git a/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management.md b/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management.md new file mode 100644 index 000000000..ffbe55973 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management.md @@ -0,0 +1,224 @@ +--- +description: Guide to managing the GreptimeDB Operator on Kubernetes, including installation, upgrade, configuration, and uninstallation using Helm. +--- + +# GreptimeDB Operator Management + +The GreptimeDB Operator manages the [GreptimeDB](https://github.com/GrepTimeTeam/greptimedb) resources on [Kubernetes](https://kubernetes.io/) using the [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). + +It is like an autopilot that automates the deployment, provisioning, and orchestration of the GreptimeDB cluster and standalone. + +The GreptimeDB Operator includes, but is not limited to, the following features: + +- **Automated Provisioning**: Automates the deployment of the GreptimeDB cluster and standalone on Kubernetes by providing CRD `GreptimeDBCluster` and `GreptimeDBStandalone`. + +- **Multi-Cloud Support**: Users can deploy the GreptimeDB on any Kubernetes cluster, including on-premises and cloud environments(like AWS, GCP, Aliyun, etc.). + +- **Scaling**: Scale the GreptimeDB cluster as easily as changing the `replicas` field in the `GreptimeDBCluster` CR. + +- **Monitoring Bootstrap**: Bootstrap the GreptimeDB monitoring stack for the GreptimeDB cluster by providing the `monitoring` field in the `GreptimeDBCluster` CR. + +This document will show you how to install, upgrade, configure, and uninstall the GreptimeDB Operator on Kubernetes. + +:::note +The following output may have minor differences depending on the versions of the Helm charts and environment. +::: + +## Prerequisites + +- Kubernetes >= v1.18.0 +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) >= v1.18.0 +- [Helm](https://helm.sh/docs/intro/install/) >= v3.0.0 + +## Production Deployment + +For production deployments, it's recommended to use Helm to install the GreptimeDB Operator. + +### Installation + +You can refer [Install and verify the GreptimeDB Operator](/user-guide/deployments/deploy-on-kubernetes/getting-started.md#install-and-verify-the-greptimedb-operator) for detailed instructions. + +:::note +If you are using [Argo CD](https://argo-cd.readthedocs.io/en/stable/) to deploy applications, please make sure that the `Application` has set the [`ServerSideApply=true`](https://argo-cd.readthedocs.io/en/latest/user-guide/sync-options/#server-side-apply) to enable the server-side apply (other GitOps tools may have similar settings). +::: + +### Upgrade + +We always publish the latest version of the GreptimeDB Operator as a Helm chart in our official Helm repository. + +When the new version of the GreptimeDB Operator is released, you can upgrade the GreptimeDB Operator by running the following commands. + +#### Update the Helm repository + +```bash +helm repo update greptime +``` + +
+Expected Output +```bash +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "greptime" chart repository +Update Complete. ⎈Happy Helming!⎈ +``` +
+ +You can use the following command to search the latest version of the GreptimeDB Operator: + +```bash +helm search repo greptime/greptimedb-operator +``` + +
+Expected Output +```bash +NAME CHART VERSION APP VERSION DESCRIPTION +greptime/greptimedb-operator 0.2.9 0.1.3-alpha.1 The greptimedb-operator Helm chart for Kubernetes. +``` +
+ +You also can use the following command to list all the available versions: + +```bash +helm search repo greptime/greptimedb-operator --versions +``` + +#### Upgrade the GreptimeDB Operator + +You can upgrade to the latest released version of the GreptimeDB Operator by running the following command: + +```bash +helm -n greptimedb-admin upgrade greptimedb-operator greptime/greptimedb-operator +``` + +
+Expected Output +```bash +Release "greptimedb-operator" has been upgraded. Happy Helming! +NAME: greptimedb-operator +LAST DEPLOYED: Mon Oct 28 19:30:52 2024 +NAMESPACE: greptimedb-admin +STATUS: deployed +REVISION: 2 +TEST SUITE: None +NOTES: +*********************************************************************** + Welcome to use greptimedb-operator + Chart version: 0.2.9 + GreptimeDB Operator version: 0.1.3-alpha.1 +*********************************************************************** + +Installed components: +* greptimedb-operator + +The greptimedb-operator is starting, use `kubectl get deployments greptimedb-operator -n greptimedb-admin` to check its status. +``` +
+ +If you want to upgrade to a specific version, you can use the following command: + +```bash +helm -n greptimedb-admin upgrade greptimedb-operator greptime/greptimedb-operator --version +``` + +After the upgrade is complete, you can use the following command to verify the installation: + +```bash +helm list -n greptimedb-admin +``` + +
+Expected Output +```bash +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +greptimedb-operator greptimedb-admin 1 2024-10-30 17:46:45.570975 +0800 CST deployed greptimedb-operator-0.2.9 0.1.3-alpha.1 +``` +
+ +### CRDs + +There are two kinds of CRD that are installed with the GreptimeDB Operator: `GreptimeDBCluster` and `GreptimeDBStandalone`. + +You can use the following command to verify the installation: + +```bash +kubectl get crd | grep greptime +``` + +
+ Expected Output +```bash +greptimedbclusters.greptime.io 2024-10-28T08:46:27Z +greptimedbstandalones.greptime.io 2024-10-28T08:46:27Z +``` +
+ +By default, the GreptimeDB Operator chart will manage the installation and upgrade of the CRDs and the users don't need to manage them manually. If you want to know the specific definitions of these two types of CRD, you can refer to the GreptimeDB Operator [API documentation](https://github.com/GreptimeTeam/greptimedb-operator/blob/main/docs/api-references/docs.md). + +### Configuration + +The GreptimeDB Operator chart provides a set of configuration options that allow you to customize the installation, you can refer to the [GreptimeDB Operator Helm Chart](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-operator/README.md##values) for more details. + +You can create a `values.yaml` to configure the GreptimeDB Operator chart (the complete configuration of `values.yaml` can be found in the [chart](https://github.com/GreptimeTeam/helm-charts/blob/main/charts/greptimedb-operator/values.yaml)), for example: + +```yaml +image: + # -- The image registry + registry: docker.io + # -- The image repository + repository: greptime/greptimedb-operator + # -- The image pull policy for the controller + imagePullPolicy: IfNotPresent + # -- The image tag + tag: latest + # -- The image pull secrets + pullSecrets: [] + +replicas: 1 + +resources: + limits: + cpu: 200m + memory: 256Mi + requests: + cpu: 100m + memory: 128Mi +``` + +You can use the following command to install the GreptimeDB Operator with the custom configuration: + +```bash +helm -n greptimedb-admin install greptimedb-operator greptime/greptimedb-operator -f values.yaml +``` + +If you want to upgrade the GreptimeDB Operator with the custom configuration, you can use the following command: + +```bash +helm -n greptimedb-admin upgrade greptimedb-operator greptime/greptimedb-operator -f values.yaml +``` + +You also can use one command to install or upgrade the GreptimeDB Operator with the custom configuration: + +```bash +helm -n greptimedb-admin upgrade --install greptimedb-operator greptime/greptimedb-operator -f values.yaml +``` + +### Uninstallation + +You can use the `helm` command to uninstall the GreptimeDB Operator: + +```bash +helm -n greptimedb-admin uninstall greptimedb-operator +``` + +We don't delete the CRDs by default when you uninstall the GreptimeDB Operator. + +:::danger +If you really want to delete the CRDs, you can use the following command: + +```bash +kubectl delete crd greptimedbclusters.greptime.io greptimedbstandalones.greptime.io +``` + +The related resources will be removed after you delete the CRDs. +::: diff --git a/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/overview.md b/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/overview.md new file mode 100644 index 000000000..b3623ef3e --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/deployments/deploy-on-kubernetes/overview.md @@ -0,0 +1,20 @@ +--- +description: Overview of deploying GreptimeDB on Kubernetes using the GreptimeDB Operator, including setup, provisioning, and management of clusters and standalone instances. +--- + +# Overview + +## GreptimeDB Operator + +The [GreptimeDB Operator](https://github.com/GrepTimeTeam/greptimedb-operator) uses the [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) to manage GreptimeDB on Kubernetes, automating the setup, provisioning, and management of GreptimeDB cluster and standalone instances. + This makes it easy to quickly deploy and scale GreptimeDB in any Kubernetes environment, whether on-premises or in the cloud. + +We **highly recommend** using the GreptimeDB Operator to deploy GreptimeDB on Kubernetes. + +## Manage GreptimeDB with the GreptimeDB Operator + +You can take [Getting Started](./getting-started.md) as your first guide to understand the whole picture. This guide provides the complete process of deploying the GreptimeDB cluster on Kubernetes. + +After getting started, you can refer to the following documents for more details about the production deployment. + +- [GreptimeDB Operator Management](./greptimedb-operator-management.md) diff --git a/versioned_docs/version-0.11/user-guide/deployments/overview.md b/versioned_docs/version-0.11/user-guide/deployments/overview.md new file mode 100644 index 000000000..a82de9b23 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/deployments/overview.md @@ -0,0 +1,32 @@ +--- +description: Overview of deploying GreptimeDB, including configuration, authentication, Kubernetes deployment, running on Android, capacity planning, and using GreptimeCloud. +--- + +# Overview + +## Configuration + +Before deploying GreptimeDB, you need to [configure the server](configuration.md) to meet your requirements. This includes setting up protocol options, storage options, and more. + +## Authentication + +By default, GreptimeDB does not have authentication enabled. Learn how to [configure authentication](./authentication/overview.md) for your deployment manually. + +## Deploy on Kubernetes + +The step-by-step instructions for [deploying GreptimeDB on a Kubernetes cluster](./deploy-on-kubernetes/overview.md). + +## Run on Android + +Learn how to [run GreptimeDB on Android devices](run-on-android.md). + +## Capacity plan + +Understand how to [plan for capacity](/user-guide/administration/capacity-plan.md) to ensure your GreptimeDB deployment can handle your workload. + +## GreptimeCloud + +Instead of managing your own GreptimeDB cluster, +you can use [GreptimeCloud](https://greptime.cloud) to manage GreptimeDB instances, monitor metrics, and set up alerts. +GreptimeCloud is a cloud service powered by fully-managed serverless GreptimeDB, providing a scalable and efficient solution for time-series data platforms and Prometheus backends. +For more information, see the [GreptimeCloud documentation](https://docs.greptime.com/nightly/greptimecloud/overview). diff --git a/versioned_docs/version-0.11/user-guide/deployments/run-on-android.md b/versioned_docs/version-0.11/user-guide/deployments/run-on-android.md new file mode 100644 index 000000000..91e63a697 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/deployments/run-on-android.md @@ -0,0 +1,103 @@ +--- +description: Instructions for running GreptimeDB on Android platforms, including installation of Termux, downloading the GreptimeDB binary, creating a configuration file, starting the database, and connecting to it from another device. +--- + +# Run on Android Platforms + +Since v0.4.0, GreptimeDB supports running on Android platforms with ARM64 CPU and Android API level >= 23. + +## Install terminal emulator on Android + +You can install [Termux](https://termux.dev/) from [GitHub release page](https://github.com/termux/termux-app/releases/latest). + + +## Download GreptimeDB Android binary. + +```bash +VERSION=$(curl -s -XGET "https://api.github.com/repos/GreptimeTeam/greptimedb/releases" | grep tag_name | grep -v nightly | cut -d: -f 2 | sed 's/.*"\(.*\)".*/\1/' | uniq | sort -r | head -n 1) + +curl -sOL "https://github.com/GreptimeTeam/greptimedb/releases/download/${VERSION}/greptime-android-arm64-${VERSION}.tar.gz" +tar zxvf ./greptime-android-arm64-${VERSION}.tar.gz +./greptime -V +``` + +If binary's downloaded correctly, the command is expected to print the version of downloaded binary. + +## Create GreptimeDB configuration file + +You can create a minimal configuration file that allows access from local network. + +```bash +DATA_DIR="$(pwd)/greptimedb-data" +mkdir -p ${DATA_DIR} + +cat < ./config.toml +[http] +addr = "0.0.0.0:4000" + +[grpc] +addr = "0.0.0.0:4001" + +[mysql] +addr = "0.0.0.0:4002" + +[storage] +data_home = "${DATA_DIR}" +type = "File" +EOF +``` + +## Start GreptimeDB from command line + +```bash +./greptime --log-dir=$(pwd)/logs standalone start -c ./config.toml +``` + +## Connect to GreptimeDB running on Android +> You can find the IP address of your Android device from system settings or `ifconfig`. + +You can now connect to the GreptimeDB instance running on Android from another device with MySQL client installed. + +```bash +mysql -h -P 4002 +``` + +And play like on any other platforms! +``` +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 8 +Server version: 5.1.10-alpha-msql-proxy Greptime + +Copyright (c) 2000, 2023, Oracle and/or its affiliates. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> CREATE TABLE monitor (env STRING, host STRING, ts TIMESTAMP, cpu DOUBLE DEFAULT 0, memory DOUBLE, TIME INDEX (ts), PRIMARY KEY(env,host)); +Query OK, 0 rows affected (0.14 sec) + +mysql> INSERT INTO monitor(ts, env, host, cpu, memory) VALUES + -> (1655276557000,'prod', 'host1', 66.6, 1024), + -> (1655276557000,'prod', 'host2', 66.6, 1024), + -> (1655276557000,'prod', 'host3', 66.6, 1024), + -> (1655276558000,'prod', 'host1', 77.7, 2048), + -> (1655276558000,'prod', 'host2', 77.7, 2048), + -> (1655276558000,'test', 'host3', 77.7, 2048), + -> (1655276559000,'test', 'host1', 88.8, 4096), + -> (1655276559000,'test', 'host2', 88.8, 4096), + -> (1655276559000,'test', 'host3', 88.8, 4096); +Query OK, 9 rows affected (0.14 sec) + +mysql> +mysql> select * from monitor where env='test' and host='host3'; ++------+-------+---------------------+------+--------+ +| env | host | ts | cpu | memory | ++------+-------+---------------------+------+--------+ +| test | host3 | 2022-06-15 15:02:38 | 77.7 | 2048 | +| test | host3 | 2022-06-15 15:02:39 | 88.8 | 4096 | ++------+-------+---------------------+------+--------+ +2 rows in set (0.20 sec) +``` \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/emqx.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/emqx.md new file mode 100644 index 000000000..73a2e5308 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/emqx.md @@ -0,0 +1,9 @@ +--- +description: Overview of integrating GreptimeDB with EMQX, an open-source MQTT broker for IoT and real-time messaging applications. +--- + +# EMQX + +[EMQX](https://www.emqx.io/) is an open-source, highly scalable, and feature-rich MQTT broker designed for IoT and real-time messaging applications. It supports various protocols, including MQTT (3.1, 3.1.1, and 5.0), HTTP, QUIC, and WebSocket. + +GreptimeDB can be used as a data system for EMQX. To learn how to integrate GreptimeDB with EMQX, please refer to [Ingest MQTT Data into GreptimeDB](https://docs.emqx.com/en/emqx/latest/data-integration/data-bridge-greptimedb.html). diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/go.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/go.md new file mode 100644 index 000000000..184e56e5f --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/go.md @@ -0,0 +1,285 @@ +--- +description: Guide on using the Go ingester SDK for GreptimeDB, including installation, connection, data model, and examples of low-level and high-level APIs. +--- + +import DocTemplate from './template.md' + +# Go + + + +
+ +The Go ingester SDK provided by GreptimeDB is a lightweight, +concurrent-safe library that is easy to use with the metric struct. + +
+ +
+ +To quickly get started, you can explore the [quick start demos](https://github.com/GreptimeTeam/greptimedb-ingester-go/tree/main/examples) to understand how to use the GreptimeDB Go ingester SDK. + +
+ +
+ +Use the following command to install the GreptimeDB client library for Go: + +```shell +go get -u github.com/GreptimeTeam/greptimedb-ingester-go@VAR::goSdkVersion +``` + +Import the library in your code: + +```go +import ( + greptime "github.com/GreptimeTeam/greptimedb-ingester-go" + "github.com/GreptimeTeam/greptimedb-ingester-go/table" + "github.com/GreptimeTeam/greptimedb-ingester-go/table/types" +) +``` + +
+ +
+ +```go +cfg := greptime.NewConfig("127.0.0.1"). + // change the database name to your database name + WithDatabase("public"). + // Default port 4001 + // WithPort(4001). + // Enable secure connection if your server is secured by TLS + // WithInsecure(false). + // set authentication information + // If the database doesn't require authentication, just remove the WithAuth method + WithAuth("username", "password") + +cli, _ := greptime.NewClient(cfg) +``` +
+ +
+ +```go +// Construct the table schema for CPU metrics +cpuMetric, err := table.New("cpu_metric") +if err != nil { + // Handle error appropriately +} + +// Add a 'Tag' column for host identifiers +cpuMetric.AddTagColumn("host", types.STRING) +// Add a 'Timestamp' column for recording the time of data collection +cpuMetric.AddTimestampColumn("ts", types.TIMESTAMP_MILLISECOND) +// Add 'Field' columns for user and system CPU usage measurements +cpuMetric.AddFieldColumn("cpu_user", types.FLOAT) +cpuMetric.AddFieldColumn("cpu_sys", types.FLOAT) + +// Insert example data +// NOTE: The arguments must be in the same order as the columns in the defined schema: host, ts, cpu_user, cpu_sys +err = cpuMetric.AddRow("127.0.0.1", time.Now(), 0.1, 0.12) +err = cpuMetric.AddRow("127.0.0.1", time.Now(), 0.11, 0.13) +if err != nil { + // Handle error appropriately +} + +``` + +
+ +
+ +```go +cpuMetric, err := table.New("cpu_metric") +if err != nil { + // Handle error appropriately +} +cpuMetric.AddTagColumn("host", types.STRING) +cpuMetric.AddTimestampColumn("ts", types.TIMESTAMP_MILLISECOND) +cpuMetric.AddFieldColumn("cpu_user", types.FLOAT) +cpuMetric.AddFieldColumn("cpu_sys", types.FLOAT) +err = cpuMetric.AddRow("127.0.0.1", time.Now(), 0.1, 0.12) +if err != nil { + // Handle error appropriately +} + +memMetric, err := table.New("mem_metric") +if err != nil { + // Handle error appropriately +} +memMetric.AddTagColumn("host", types.STRING) +memMetric.AddTimestampColumn("ts", types.TIMESTAMP_MILLISECOND) +memMetric.AddFieldColumn("mem_usage", types.FLOAT) +err = memMetric.AddRow("127.0.0.1", time.Now(), 112) +if err != nil { + // Handle error appropriately +} +``` + +
+ +
+ +```go +resp, err := cli.Write(context.Background(), cpuMetric, memMetric) +if err != nil { + // Handle error appropriately +} +log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) +``` + +
+ +
+ +```go +err := cli.StreamWrite(context.Background(), cpuMetric, memMetric) +if err != nil { + // Handle error appropriately +} +``` + +Close the stream writing after all data has been written. +In general, you do not need to close the stream writing when continuously writing data. + +```go +affected, err := cli.CloseStream(ctx) +``` + +
+ + +
+ +```go +type CpuMetric struct { + Host string `greptime:"tag;column:host;type:string"` + CpuUser float64 `greptime:"field;column:cpu_user;type:float64"` + CpuSys float64 `greptime:"field;column:cpu_sys;type:float64"` + Ts time.Time `greptime:"timestamp;column:ts;type:timestamp;precision:millisecond"` +} + +func (CpuMetric) TableName() string { + return "cpu_metric" +} + +cpuMetrics := []CpuMetric{ + { + Host: "127.0.0.1", + CpuUser: 0.10, + CpuSys: 0.12, + Ts: time.Now(), + } +} +``` + + + + +
+ +
+ +```go +resp, err := cli.WriteObject(context.Background(), cpuMetrics) +log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) +``` + +
+ +
+ +```go +err := cli.StreamWriteObject(context.Background(), cpuMetrics) +``` + +Close the stream writing after all data has been written. +In general, you do not need to close the stream writing when continuously writing data. + +```go +affected, err := cli.CloseStream(ctx) +``` + +
+ +
+ +In the [low-level API](#low-level-api), +you can specify the column type as `types.JSON` using the `AddFieldColumn` method to add a JSON column. +Then, use a `struct` or `map` to insert JSON data. + +```go +sensorReadings, err := table.New("sensor_readings") +// The code for creating other columns is omitted +// ... +// specify the column type as JSON +sensorReadings.AddFieldColumn("attributes", types.JSON) + +// Use struct to insert JSON data +type Attributes struct { + Location string `json:"location"` + Action string `json:"action"` +} +attributes := Attributes{ Location: "factory-1" } +sensorReadings.AddRow(... , attributes) + +// The following code for writing data is omitted +// ... +``` + +In the [high-level API](#high-level-api), you can specify the column type as JSON using the `greptime:"field;column:details;type:json"` tag. + +```go +type SensorReadings struct { + // The code for creating other columns is omitted + // ... + // specify the column type as JSON + Attributes string `greptime:"field;column:details;type:json"` + // ... +} + +// Use struct to insert JSON data +type Attributes struct { + Location string `json:"location"` + Action string `json:"action"` +} +attributes := Attributes{ Action: "running" } +sensor := SensorReadings{ + // ... + Attributes: attributes, +} + +// The following code for writing data is omitted +// ... +``` + +For the executable code for inserting JSON data, please refer to the [example](https://github.com/GreptimeTeam/greptimedb-ingester-go/tree/main/examples/jsondata) in the SDK repository. + +
+ +
+ +- [API Documentation](https://pkg.go.dev/github.com/GreptimeTeam/greptimedb-ingester-go) + +
+ + diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/java.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/java.md new file mode 100644 index 000000000..8e3c210d4 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/java.md @@ -0,0 +1,377 @@ +--- +description: Guide on using the Java ingester SDK for GreptimeDB, including installation, connection, data model, and examples of low-level and high-level APIs. +--- + +import DocTemplate from './template.md' + +# Java + + + +
+ +The Java ingester SDK provided by GreptimeDB is a lightweight library with the following features: + +- SPI-based extensible network transport layer, which provides the default implementation using the gRPC framework. +- Non-blocking, purely asynchronous API that is easy to use. +- Automatic collection of various performance metrics by default. You can then configure and write them to local files. +- Ability to take in-memory snapshots of critical objects, configure them, and write them to local files. This is helpful for troubleshooting complex issues. + +
+ +
+ +To quickly get started, you can explore the [quick start demos](https://github.com/GreptimeTeam/greptimedb-ingester-java/tree/main/ingester-example/src/main/java/io/greptime) to understand how to use the GreptimeDB Java ingester SDK. + +
+ +
+ +1. Install the Java Development Kit(JDK) + +Make sure that your system has JDK 8 or later installed. For more information on how to +check your version of Java and install the JDK, see the [Oracle Overview of JDK Installation documentation](https://www.oracle.com/java/technologies/javase-downloads.html) + +2. Add GreptiemDB Java SDK as a Dependency + +If you are using [Maven](https://maven.apache.org/), add the following to your pom.xml +dependencies list: + +```xml + + io.greptime + ingester-all + VAR::javaSdkVersion + +``` + +The latest version can be viewed [here](https://central.sonatype.com/search?q=io.greptime&name=ingester-all). + +After configuring your dependencies, make sure they are available to your project. This may require refreshing the project in your IDE or running the dependency manager. + +
+ +
+ +The following code demonstrates how to connect to GreptimeDB with the simplest configuration. +For customizing the connection options, please refer to [API Documentation](#ingester-library-reference). +Please pay attention to the accompanying comments for each option, as they provide detailed explanations of their respective roles. + +```java +// GreptimeDB has a default database named "public" in the default catalog "greptime", +// we can use it as the test database +String database = "public"; +// By default, GreptimeDB listens on port 4001 using the gRPC protocol. +// We can provide multiple endpoints that point to the same GreptimeDB cluster. +// The client will make calls to these endpoints based on a load balancing strategy. +String[] endpoints = {"127.0.0.1:4001"}; +// Sets authentication information. +AuthInfo authInfo = new AuthInfo("username", "password"); +GreptimeOptions opts = GreptimeOptions.newBuilder(endpoints, database) + // If the database does not require authentication, we can use AuthInfo.noAuthorization() as the parameter. + .authInfo(authInfo) + // Enable secure connection if your server is secured by TLS + //.tlsOptions(new TlsOptions()) + // A good start ^_^ + .build(); + +GreptimeDB client = GreptimeDB.create(opts); +``` + +For customizing the connection options, please refer to [API Documentation](#ingester-library-reference). + +
+ + +
+ +```java +// Construct the table schema for CPU metrics +TableSchema cpuMetricSchema = TableSchema.newBuilder("cpu_metric") + .addTag("host", DataType.String) // Identifier for the host + .addTimestamp("ts", DataType.TimestampMillisecond) // Timestamp in milliseconds + .addField("cpu_user", DataType.Float64) // CPU usage by user processes + .addField("cpu_sys", DataType.Float64) // CPU usage by system processes + .build(); + +// Create the table from the defined schema +Table cpuMetric = Table.from(cpuMetricSchema); + +// Example data for a single row +String host = "127.0.0.1"; // Host identifier +long ts = System.currentTimeMillis(); // Current timestamp +double cpuUser = 0.1; // CPU usage by user processes (in percentage) +double cpuSys = 0.12; // CPU usage by system processes (in percentage) + +// Insert the row into the table +// NOTE: The arguments must be in the same order as the columns in the defined schema: host, ts, cpu_user, cpu_sys +cpuMetric.addRow(host, ts, cpuUser, cpuSys); +``` + +
+ + +
+ +```java +// Creates schemas +TableSchema cpuMetricSchema = TableSchema.newBuilder("cpu_metric") + .addTag("host", DataType.String) + .addTimestamp("ts", DataType.TimestampMillisecond) + .addField("cpu_user", DataType.Float64) + .addField("cpu_sys", DataType.Float64) + .build(); + +TableSchema memMetricSchema = TableSchema.newBuilder("mem_metric") + .addTag("host", DataType.String) + .addTimestamp("ts", DataType.TimestampMillisecond) + .addField("mem_usage", DataType.Float64) + .build(); + +Table cpuMetric = Table.from(cpuMetricSchema); +Table memMetric = Table.from(memMetricSchema); + +// Adds row data items +for (int i = 0; i < 10; i++) { + String host = "127.0.0." + i; + long ts = System.currentTimeMillis(); + double cpuUser = i + 0.1; + double cpuSys = i + 0.12; + cpuMetric.addRow(host, ts, cpuUser, cpuSys); +} + +for (int i = 0; i < 10; i++) { + String host = "127.0.0." + i; + long ts = System.currentTimeMillis(); + double memUsage = i + 0.2; + memMetric.addRow(host, ts, memUsage); +} + +``` + +
+ + +
+ +```java +// Saves data + +// For performance reasons, the SDK is designed to be purely asynchronous. +// The return value is a future object. If you want to immediately obtain +// the result, you can call `future.get()`. +CompletableFuture> future = greptimeDB.write(cpuMetric, memMetric); + +Result result = future.get(); + +if (result.isOk()) { + LOG.info("Write result: {}", result.getOk()); +} else { + LOG.error("Failed to write: {}", result.getErr()); +} + +``` + +
+ + +
+ + +```java +StreamWriter writer = greptimeDB.streamWriter(); + +// write data into stream +writer.write(cpuMetric); +writer.write(memMetric); + +// You can perform operations on the stream, such as deleting the first 5 rows. +writer.write(cpuMetric.subRange(0, 5), WriteOp.Delete); +``` + +Close the stream writing after all data has been written. +In general, you do not need to close the stream writing when continuously writing data. + +```java +// complete the stream +CompletableFuture future = writer.completed(); +WriteOk result = future.get(); +LOG.info("Write result: {}", result); +``` + +
+ +
+ +GreptimeDB Java Ingester SDK allows us to use basic POJO objects for writing. This approach requires the use of Greptime's own annotations, but they are easy to use. + +```java +@Metric(name = "cpu_metric") +public class Cpu { + @Column(name = "host", tag = true, dataType = DataType.String) + private String host; + + @Column(name = "ts", timestamp = true, dataType = DataType.TimestampMillisecond) + private long ts; + + @Column(name = "cpu_user", dataType = DataType.Float64) + private double cpuUser; + @Column(name = "cpu_sys", dataType = DataType.Float64) + private double cpuSys; + + // getters and setters + // ... +} + +@Metric(name = "mem_metric") +public class Memory { + @Column(name = "host", tag = true, dataType = DataType.String) + private String host; + + @Column(name = "ts", timestamp = true, dataType = DataType.TimestampMillisecond) + private long ts; + + @Column(name = "mem_usage", dataType = DataType.Float64) + private double memUsage; + // getters and setters + // ... +} + +// Add rows +List cpus = new ArrayList<>(); +for (int i = 0; i < 10; i++) { + Cpu c = new Cpu(); + c.setHost("127.0.0." + i); + c.setTs(System.currentTimeMillis()); + c.setCpuUser(i + 0.1); + c.setCpuSys(i + 0.12); + cpus.add(c); +} + +List memories = new ArrayList<>(); +for (int i = 0; i < 10; i++) { + Memory m = new Memory(); + m.setHost("127.0.0." + i); + m.setTs(System.currentTimeMillis()); + m.setMemUsage(i + 0.2); + memories.add(m); +} +``` + +
+ + +
+ + +Write data with POJO objects: + +```java +// Saves data + +CompletableFuture> puts = greptimeDB.writeObjects(cpus, memories); + +Result result = puts.get(); + +if (result.isOk()) { + LOG.info("Write result: {}", result.getOk()); +} else { + LOG.error("Failed to write: {}", result.getErr()); +} +``` + +
+ + +
+ +```java +StreamWriter, WriteOk> writer = greptimeDB.objectsStreamWriter(); + +// write data into stream +writer.write(cpus); +writer.write(memories); + +// You can perform operations on the stream, such as deleting the first 5 rows. +writer.write(cpus.subList(0, 5), WriteOp.Delete); +``` + +Close the stream writing after all data has been written. +In general, you do not need to close the stream writing when continuously writing data. + +```java +// complete the stream +CompletableFuture future = writer.completed(); +WriteOk result = future.get(); +LOG.info("Write result: {}", result); +``` + +
+ +
+ +In the [low-level API](#low-level-api), +you can specify the column type as `DataType.Json` using the `addField` method to add a JSON column. +Then use map to insert JSON data. + +```java +// Construct the table schema for sensor_readings +TableSchema sensorReadings = TableSchema.newBuilder("sensor_readings") + // The code for creating other columns is omitted + // ... + // specify the column type as JSON + .addField("attributes", DataType.Json) + .build(); + +// ... +// Use map to insert JSON data +Map attr = new HashMap<>(); +attr.put("location", "factory-1"); +sensorReadings.addRow(... , attr); + +// The following code for writing data is omitted +// ... +``` + +In the [high-level API](#high-level-api), you can specify the column type as `DataType.Json` within the POJO object. + +```java +@Metric(name = "sensor_readings") +public class Sensor { + // The code for creating other columns is omitted + // ... + // specify the column type as JSON + @Column(name = "attributes", dataType = DataType.Json) + private Map attributes; + // ... +} + +Sensor sensor = new Sensor(); +// ... +// Use map to insert JSON data +Map attr = new HashMap<>(); +attr.put("action", "running"); +sensor.setAttributes(attr); + +// The following code for writing data is omitted +// ... +``` + +
+ +
+ +## Debug logs + +The ingester SDK provides metrics and logs for debugging. +Please refer to [Metrics & Display](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/docs/metrics-display.md) and [Magic Tools](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/docs/magic-tools.md) to learn how to enable or disable the logs. + +
+ +
+ +- [API Documentation](https://javadoc.io/doc/io.greptime/ingester-protocol/latest/index.html) + +
+ + diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/overview.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/overview.md new file mode 100644 index 000000000..9ad65e79c --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/overview.md @@ -0,0 +1,10 @@ +--- +description: Demonstrates how to use client libraries to write data in GreptimeDB, with links to guides for Go and Java. +--- + +# Overview + +This guide will demonstrate how to use client libraries to write data in GreptimeDB. + +- [Go](go.md) +- [Java](java.md) diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/template.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/template.md new file mode 100644 index 000000000..2a42ecc3c --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/grpc-sdks/template.md @@ -0,0 +1,104 @@ + +GreptimeDB offers ingester libraries for high-throughput data writing. +It utilizes the gRPC protocol, +which supports schemaless writing and eliminates the need to create tables before writing data. +For more information, refer to [Automatic Schema Generation](/user-guide/ingest-data/overview.md#automatic-schema-generation). + + + +## Quick start demos + + + +## Installation + + + +## Connect to database + +If you have set the [`--user-provider` configuration](/user-guide/deployments/authentication/overview.md) when starting GreptimeDB, +you will need to provide a username and password to connect to GreptimeDB. +The following example shows how to set the username and password when using the library to connect to GreptimeDB. + + + +## Data model + +Each row item in a table consists of three types of columns: `Tag`, `Timestamp`, and `Field`. For more information, see [Data Model](/user-guide/concepts/data-model.md). +The types of column values could be `String`, `Float`, `Int`, `Timestamp`, `JSON` etc. For more information, see [Data Types](/reference/sql/data-types.md). + +## Low-level API + +The GreptimeDB low-level API provides a straightforward method to write data to GreptimeDB +by adding rows to the table object with a predefined schema. + +### Create row objects + +This following code snippet begins by constructing a table named `cpu_metric`, +which includes columns `host`, `cpu_user`, `cpu_sys`, and `ts`. +Subsequently, it inserts a single row into the table. + +The table consists of three types of columns: + +- `Tag`: The `host` column, with values of type `String`. +- `Field`: The `cpu_user` and `cpu_sys` columns, with values of type `Float`. +- `Timestamp`: The `ts` column, with values of type `Timestamp`. + + + +To improve the efficiency of writing data, you can create multiple rows at once to write to GreptimeDB. + + + +### Insert data + +The following example shows how to insert rows to tables in GreptimeDB. + + + +### Streaming insert + +Streaming insert is useful when you want to insert a large amount of data such as importing historical data. + + + + + +## High-level API + +The high-level API uses an ORM style object to write data to GreptimeDB. +It allows you to create, insert, and update data in a more object-oriented way, +providing developers with a friendlier experience. +However, it is not as efficient as the low-level API. +This is because the ORM style object may consume more resources and time when converting the objects. + +### Create row objects + + + +### Insert data + + + +### Streaming insert + +Streaming insert is useful when you want to insert a large amount of data such as importing historical data. + + + + + +## Insert data in JSON type + +GreptimeDB supports storing complex data structures using [JSON type data](/reference/sql/data-types.md#json-type). +With this ingester library, you can insert JSON data using string values. +For instance, if you have a table named `sensor_readings` and wish to add a JSON column named `attributes`, +refer to the following code snippet. + + + + + +## Ingester library reference + + diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/influxdb-line-protocol.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/influxdb-line-protocol.md new file mode 100644 index 000000000..2fc3bf510 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/influxdb-line-protocol.md @@ -0,0 +1,206 @@ +--- +description: Guide on using InfluxDB Line Protocol to ingest data into GreptimeDB, including examples, authentication, Telegraf integration, and data model differences. +--- + +# InfluxDB Line Protocol + +GreptimeDB supports HTTP InfluxDB Line protocol. + +## Ingest data + +### Protocols + +#### Post metrics + +You can write data to GreptimeDB using the `/influxdb/write` API. +Here's an example of how to use this API: + + + + + +```shell +curl -i -XPOST "http://localhost:4000/v1/influxdb/api/v2/write?db=public&precision=ms" \ +--data-binary \ +'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 1667446797450 + monitor,host=127.0.0.2 cpu=0.2,memory=0.3 1667446798450 + monitor,host=127.0.0.1 cpu=0.5,memory=0.2 1667446798450' +``` + + + + +```shell +curl -i -XPOST "http://localhost:4000/v1/influxdb/write?db=public&precision=ms" \ +--data-binary \ +'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 1667446797450 + monitor,host=127.0.0.2 cpu=0.2,memory=0.3 1667446798450 + monitor,host=127.0.0.1 cpu=0.5,memory=0.2 1667446798450' +``` + + + + +The `/influxdb/write` supports query params including: + +* `db`: Specifies the database to write to. The default value is `public`. +* `precision`: Defines the precision of the timestamp provided in the request body. Accepted values are `ns` (nanoseconds), `us` (microseconds), `ms` (milliseconds), and `s` (seconds). The data type of timestamps written by this API is `TimestampNanosecond`, so the default precision is `ns` (nanoseconds). If you use timestamps with other precisions in the request body, you need to specify the precision using this parameter. This parameter ensures that timestamp values are accurately interpreted and stored with nanosecond precision. + +You can also omit the timestamp when sending requests. GreptimeDB will use the current system time (in UTC) of the host machine as the timestamp. For example: + + + + + +```shell +curl -i -XPOST "http://localhost:4000/v1/influxdb/api/v2/write?db=public" \ +--data-binary \ +'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 + monitor,host=127.0.0.2 cpu=0.2,memory=0.3 + monitor,host=127.0.0.1 cpu=0.5,memory=0.2' +``` + + + + +```shell +curl -i -XPOST "http://localhost:4000/v1/influxdb/write?db=public" \ +--data-binary \ +'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 + monitor,host=127.0.0.2 cpu=0.2,memory=0.3 + monitor,host=127.0.0.1 cpu=0.5,memory=0.2' +``` + + + + +#### Authentication + +GreptimeDB is compatible with InfluxDB's line protocol authentication format, both V1 and V2. +If you have [configured authentication](/user-guide/deployments/authentication/overview.md) in GreptimeDB, you need to provide the username and password in the HTTP request. + + + + + +InfluxDB's [V2 protocol](https://docs.influxdata.com/influxdb/v1.8/tools/api/?t=Auth+Enabled#apiv2query-http-endpoint) uses a format much like HTTP's standard basic authentication scheme. + +```shell +curl 'http://localhost:4000/v1/influxdb/api/v2/write?db=public' \ + -H 'authorization: token :' \ + -d 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4' +``` + + + + + +For the authentication format of InfluxDB's [V1 protocol](https://docs.influxdata.com/influxdb/v1.8/tools/api/?t=Auth+Enabled#query-string-parameters-1). Add `u` for user and `p` for password to the HTTP query string as shown below: + +```shell +curl 'http://localhost:4000/v1/influxdb/write?db=public&u=&p=' \ + -d 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4' +``` + + + + +### Telegraf + +GreptimeDB's support for the [InfluxDB line protocol](../for-iot/influxdb-line-protocol.md) ensures its compatibility with Telegraf. +To configure Telegraf, simply add GreptimeDB URL into Telegraf configurations: + + + + + +```toml +[[outputs.influxdb_v2]] + urls = ["http://:4000/v1/influxdb"] + token = ":" + bucket = "" + ## Leave empty + organization = "" +``` + + + + + +```toml +[[outputs.influxdb]] + urls = ["http://:4000/v1/influxdb"] + database = "" + username = "" + password = "" +``` + + + + + +## Data model + +While you may already be familiar with [InfluxDB key concepts](https://docs.influxdata.com/influxdb/v2/reference/key-concepts/), the [data model](/user-guide/concepts/data-model.md) of GreptimeDB is something new to explore. +Here are the similarities and differences between the data models of GreptimeDB and InfluxDB: + +- Both solutions are [schemaless](/user-guide/ingest-data/overview.md#automatic-schema-generation), eliminating the need to define a schema before writing data. +- The GreptimeDB table is automatically created with the [`merge_mode` option](/reference/sql/create.md#create-a-table-with-merge-mode) set to `last_non_null`. +That means the table merges rows with the same tags and timestamp by keeping the latest value of each field, which is the same behavior as InfluxDB. +- In InfluxDB, a point represents a single data record with a measurement, tag set, field set, and a timestamp. +In GreptimeDB, it is represented as a row of data in the time-series table, +where the table name aligns with the measurement, +and the columns are divided into three types: Tag, Field, and Timestamp. +- GreptimeDB uses `TimestampNanosecond` as the data type for timestamp data from the [InfluxDB line protocol API](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md). +- GreptimeDB uses `Float64` as the data type for numeric data from the InfluxDB line protocol API. + +Consider the following [sample data](https://docs.influxdata.com/influxdb/v2/reference/key-concepts/data-elements/#sample-data) borrowed from InfluxDB docs as an example: + +|_time|_measurement|location|scientist|_field|_value| +|---|---|---|---|---|---| +|2019-08-18T00:00:00Z|census|klamath|anderson|bees|23| +|2019-08-18T00:00:00Z|census|portland|mullen|ants|30| +|2019-08-18T00:06:00Z|census|klamath|anderson|bees|28| +|2019-08-18T00:06:00Z|census|portland|mullen|ants|32| + +The data mentioned above is formatted as follows in the InfluxDB line protocol: + + +```shell +census,location=klamath,scientist=anderson bees=23 1566086400000000000 +census,location=portland,scientist=mullen ants=30 1566086400000000000 +census,location=klamath,scientist=anderson bees=28 1566086760000000000 +census,location=portland,scientist=mullen ants=32 1566086760000000000 +``` + +In the GreptimeDB data model, the data is represented as follows in the `census` table: + +```sql ++---------------------+----------+-----------+------+------+ +| ts | location | scientist | bees | ants | ++---------------------+----------+-----------+------+------+ +| 2019-08-18 00:00:00 | klamath | anderson | 23 | NULL | +| 2019-08-18 00:06:00 | klamath | anderson | 28 | NULL | +| 2019-08-18 00:00:00 | portland | mullen | NULL | 30 | +| 2019-08-18 00:06:00 | portland | mullen | NULL | 32 | ++---------------------+----------+-----------+------+------+ +``` + +The schema of the `census` table is as follows: + +```sql ++-----------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-----------+----------------------+------+------+---------+---------------+ +| location | String | PRI | YES | | TAG | +| scientist | String | PRI | YES | | TAG | +| bees | Float64 | | YES | | FIELD | +| ts | TimestampNanosecond | PRI | NO | | TIMESTAMP | +| ants | Float64 | | YES | | FIELD | ++-----------+----------------------+------+------+---------+---------------+ +``` + +## Reference + +- [InfluxDB Line protocol](https://docs.influxdata.com/influxdb/v2.7/reference/syntax/line-protocol/) + diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/opentsdb.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/opentsdb.md new file mode 100644 index 000000000..1f4f7e688 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/opentsdb.md @@ -0,0 +1,60 @@ +--- +description: Instructions on ingesting OpenTSDB metrics into GreptimeDB via HTTP API, including examples of inserting single and multiple metric points. +--- + +# OpenTSDB + +GreptimeDB supports ingesting OpenTSDB via HTTP API. + +GreptimeDB also supports inserting OpenTSDB metrics via HTTP endpoints. We use the request and +response format described in OpenTSDB's `/api/put`. + +The HTTP endpoint in GreptimeDB for handling metrics is `/opentsdb/api/put` + +> Note: remember to prefix the path with GreptimeDB's http API version, `v1`. + +Starting GreptimeDB, the HTTP server is listening on port `4000` by default. + +Use curl to insert one metric point: + +```shell +curl -X POST http://127.0.0.1:4000/v1/opentsdb/api/put -d ' +{ + "metric": "sys.cpu.nice", + "timestamp": 1667898896, + "value": 18, + "tags": { + "host": "web01", + "dc": "hz" + } +} +' +``` + +Or insert multiple metric points: + +```shell +curl -X POST http://127.0.0.1:4000/v1/opentsdb/api/put -d ' +[ + { + "metric": "sys.cpu.nice", + "timestamp": 1667898896, + "value": 1, + "tags": { + "host": "web02", + "dc": "hz" + } + }, + { + "metric": "sys.cpu.nice", + "timestamp": 1667898897, + "value": 9, + "tags": { + "host": "web03", + "dc": "sh" + } + } +] +' +``` + diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/overview.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/overview.md new file mode 100644 index 000000000..57f7d6994 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/overview.md @@ -0,0 +1,20 @@ +--- +description: Overview of data ingestion methods in GreptimeDB for IoT, including SQL INSERT, gRPC SDK, InfluxDB Line Protocol, EMQX, and OpenTSDB. +--- + +# Overview + +The data ingestion is a critical part of the IoT data pipeline. +It is the process of collecting data from various sources, such as sensors, devices, and applications, and storing it in a central location for further processing and analysis. +The data ingestion is essential for ensuring that the data is accurate, reliable, and secure. + +GreptimeDB can handle large volumes of data, process it in real-time, and store it efficiently for future analysis. +It also supports various data formats, protocols, and interfaces, +making it easy to integrate with different IoT devices and systems. + +- [SQL INSERT](sql.md): A straightforward method for inserting data. +- [gRPC SDK](./grpc-sdks/overview.md): Offers efficient, high-performance data ingestion, particularly suited for real-time data applications and complex IoT infrastructures. +- [InfluxDB Line Protocol](influxdb-line-protocol.md): A widely-used protocol for time-series data, facilitating migration from InfluxDB to GreptimeDB. The Telegraf integration method is also introduced in this document. +- [EMQX](emqx.md): An MQTT broker supporting massive device connections, can ingest data to GreptimeDB directly. +- [OpenTSDB](opentsdb.md): Ingest data to GreptimeDB using the OpenTSDB protocol. + diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/sql.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/sql.md new file mode 100644 index 000000000..bfada58f5 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-iot/sql.md @@ -0,0 +1,120 @@ +--- +description: Guide on executing SQL statements to create tables and insert data into GreptimeDB, with examples using the `monitor` table. +--- + +# SQL + +You can execute SQL statements using [MySQL](/user-guide/protocols/mysql.md) or [PostgreSQL](/user-guide/protocols/postgresql.md) clients, +and access GreptimeDB using the MySQL or PostgreSQL protocol with any programming language of your preference, such as Java JDBC. +We will use the `monitor` table as an example to show how to write data. + +## Create a table + +Before inserting data, you need to create a table. For example, create a table named `monitor`: + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64 DEFAULT 0, + memory FLOAT64, + PRIMARY KEY(host)); +``` + +The above statement will create a table with the following schema: + +```sql ++--------+----------------------+------+------+---------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------+----------------------+------+------+---------------------+---------------+ +| host | String | PRI | YES | | TAG | +| ts | TimestampMillisecond | PRI | NO | current_timestamp() | TIMESTAMP | +| cpu | Float64 | | YES | 0 | FIELD | +| memory | Float64 | | YES | | FIELD | ++--------+----------------------+------+------+---------------------+---------------+ +4 rows in set (0.01 sec) +``` + +For more information about the `CREATE TABLE` statement, +please refer to [table management](/user-guide/administration/manage-data/basic-table-operations.md#create-a-table). + +## Insert data + +Let's insert some testing data to the `monitor` table. You can use the `INSERT INTO` SQL statements: + +```sql +INSERT INTO monitor +VALUES + ("127.0.0.1", 1702433141000, 0.5, 0.2), + ("127.0.0.2", 1702433141000, 0.3, 0.1), + ("127.0.0.1", 1702433146000, 0.3, 0.2), + ("127.0.0.2", 1702433146000, 0.2, 0.4), + ("127.0.0.1", 1702433151000, 0.4, 0.3), + ("127.0.0.2", 1702433151000, 0.2, 0.4); +``` + +```sql +Query OK, 6 rows affected (0.01 sec) +``` + +You can also insert data by specifying the column names: + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES + ("127.0.0.1", 1702433141000, 0.5, 0.2), + ("127.0.0.2", 1702433141000, 0.3, 0.1), + ("127.0.0.1", 1702433146000, 0.3, 0.2), + ("127.0.0.2", 1702433146000, 0.2, 0.4), + ("127.0.0.1", 1702433151000, 0.4, 0.3), + ("127.0.0.2", 1702433151000, 0.2, 0.4); +``` + +Through the above statement, we have inserted six rows into the `monitor` table. + +For more information about the `INSERT` statement, please refer to [`INSERT`](/reference/sql/insert.md). + +## Time zone + +The time zone specified in the SQL client will affect the timestamp with a string format that does not have time zone information. +The timestamp value will automatically have the client's time zone information added. + +For example, the following SQL set the time zone to `+8:00`: + +```sql +SET time_zone = '+8:00'; +``` + +Then insert values into the `monitor` table: + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES + ("127.0.0.1", "2024-01-01 00:00:00", 0.4, 0.1), + ("127.0.0.2", "2024-01-01 00:00:00+08:00", 0.5, 0.1); +``` + +The first timestamp value `2024-01-01 00:00:00` does not have time zone information, so it will automatically have the client's time zone information added. +After inserting, it will be equivalent to the second value `2024-01-01 00:00:00+08:00`. + +The result in the `+8:00` time zone client is as follows: + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-01-01 00:00:00 | 0.4 | 0.1 | +| 127.0.0.2 | 2024-01-01 00:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` + +The result in the `UTC` time zone client is as follows: + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2023-12-31 16:00:00 | 0.4 | 0.1 | +| 127.0.0.2 | 2023-12-31 16:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/influxdb-line-protocol.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/influxdb-line-protocol.md new file mode 100644 index 000000000..dec09f7a4 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/influxdb-line-protocol.md @@ -0,0 +1,4 @@ +# InfluxDB Line Protocol + +Please refer to the [InfluxDB Line Protocol documentation](../for-iot/influxdb-line-protocol.md) for instructions on how to write data to GreptimeDB using the InfluxDB Line Protocol. + diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/loki.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/loki.md new file mode 100644 index 000000000..12cfb52c0 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/loki.md @@ -0,0 +1,127 @@ +--- +description: Guide to integrating Loki with GreptimeDB for log storage, including API usage, example configurations, and data model mapping. +--- + +# Loki + +## Usage + +### API + +To send Logs to GreptimeDB through Raw HTTP API, use the following information: + +* URL: `http{s}:///v1/loki/api/v1/push` +* Headers: + * `X-Greptime-DB-Name`: `` + * `Authorization`: `Basic` authentication, which is a Base64 encoded string of `:`. For more information, please refer to [Authentication](https://docs.greptime.com/user-guide/deployments/authentication/static/) and [HTTP API](https://docs.greptime.com/user-guide/protocols/http#authentication). + * `X-Greptime-Log-Table-Name`: `` (optional) - The table name to store the logs. If not provided, the default table name is `loki_logs`. + + The request uses binary protobuf to encode the payload, The defined schema is the same as the [logproto.proto](https://github.com/grafana/loki/blob/main/pkg/logproto/logproto.proto). + +### Example Code + +[Grafana Alloy](https://grafana.com/docs/alloy/latest/) is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector. Alloy uniquely combines the very best OSS observability signals in the community. + +It suplies a Loki exporter that can be used to send logs to GreptimeDB. Here is an example configuration: + +```hcl +loki.source.file "greptime" { + targets = [ + {__path__ = "/tmp/foo.txt"}, + ] + forward_to = [loki.write.greptime_loki.receiver] +} + +loki.write "greptime_loki" { + endpoint { + url = "${GREPTIME_SCHEME:=http}://${GREPTIME_HOST:=greptimedb}:${GREPTIME_PORT:=4000}/v1/loki/api/v1/push" + headers = { + "x-greptime-db-name" = "${GREPTIME_DB:=public}", + "x-greptime-log-table-name" = "${GREPTIME_LOG_TABLE_NAME:=loki_demo_logs}", + } + } + external_labels = { + "job" = "greptime" + "from" = "alloy" + } +} +``` + +We listen to the file `/tmp/foo.txt` and send the logs to GreptimeDB. The logs are stored in the table `loki_demo_logs` with the external labels `job` and `from`. + +For more information, please refer to the [Grafana Alloy loki.write documentation](https://grafana.com/docs/alloy/latest/reference/components/loki/loki.write/). + +You can run the following command to check the data in the table: + +```sql +SELECT * FROM loki_demo_logs; ++----------------------------+------------------------+--------------+-------+----------+ +| greptime_timestamp | line | filename | from | job | ++----------------------------+------------------------+--------------+-------+----------+ +| 2024-11-25 11:02:31.256251 | Greptime is very cool! | /tmp/foo.txt | alloy | greptime | ++----------------------------+------------------------+--------------+-------+----------+ +1 row in set (0.01 sec) +``` + +## Data Model + +The Loki logs data model is mapped to the GreptimeDB data model according to the following rules: + +Default table schema without external labels: + +```sql +DESC loki_demo_logs; ++--------------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+---------------------+------+------+---------+---------------+ +| greptime_timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | +| line | String | | YES | | FIELD | ++--------------------+---------------------+------+------+---------+---------------+ +5 rows in set (0.00 sec) +``` + +- greptime_timestamp: The timestamp of the log. +- line: The log message. + +if you specify the external labels, we will add them as tags to the table schema. like `job` and `from` in the above example. +You can't specify tags manually, all labels are treated as tags and string type. +Please do not attempt to pre-create the table using SQL to specify tag columns, as this will cause a type mismatch and write failure. + +### Example + +The following is an example of the table schema: + +```sql +DESC loki_demo_logs; ++--------------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+---------------------+------+------+---------+---------------+ +| greptime_timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | +| line | String | | YES | | FIELD | +| filename | String | PRI | YES | | TAG | +| from | String | PRI | YES | | TAG | +| job | String | PRI | YES | | TAG | ++--------------------+---------------------+------+------+---------+---------------+ +5 rows in set (0.00 sec) +``` + +```sql +SHOW CREATE TABLE loki_demo_logs\G +*************************** 1. row *************************** + Table: loki_demo_logs +Create Table: CREATE TABLE IF NOT EXISTS `loki_demo_logs` ( + `greptime_timestamp` TIMESTAMP(9) NOT NULL, + `line` STRING NULL, + `filename` STRING NULL, + `from` STRING NULL, + `job` STRING NULL, + TIME INDEX (`greptime_timestamp`), + PRIMARY KEY (`filename`, `from`, `job`) +) + +ENGINE=mito +WITH( + append_mode = 'true' +) +1 row in set (0.00 sec) +``` \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/opentelemetry.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/opentelemetry.md new file mode 100644 index 000000000..d8805ccaa --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/opentelemetry.md @@ -0,0 +1,190 @@ +--- +description: Instructions for integrating OpenTelemetry with GreptimeDB, including metrics and logs data model mapping, example configurations, and supported protocols. +--- + +# OpenTelemetry Protocol (OTLP) + +[OpenTelemetry](https://opentelemetry.io/) is a vendor-neutral open-source observability framework for instrumenting, generating, collecting, and exporting telemetry data such as traces, metrics, logs. The OpenTelemetry Protocol (OTLP) defines the encoding, transport, and delivery mechanism of telemetry data between telemetry sources, intermediate processes such as collectors and telemetry backends. + +## Metrics + +### OTLP/HTTP + +import Includeotlpmetrycsintegration from '../../../db-cloud-shared/clients/otlp-metrics-integration.md' + + + +#### Example Code + +Here are some example codes about how to setup the request in different languages: + + + + + +```ts +const auth = Buffer.from(`${username}:${password}`).toString('base64') +const exporter = new OTLPMetricExporter({ + url: `https://${dbHost}/v1/otlp/v1/metrics`, + headers: { + Authorization: `Basic ${auth}`, + "X-Greptime-DB-Name": db, + }, + timeoutMillis: 5000, +}) +``` + + + + + +```Go +auth := base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("%s:%s", *username, *password))) +exporter, err := otlpmetrichttp.New( + context.Background(), + otlpmetrichttp.WithEndpoint(*dbHost), + otlpmetrichttp.WithURLPath("/v1/otlp/v1/metrics"), + otlpmetrichttp.WithHeaders(map[string]string{ + "X-Greptime-DB-Name": *dbName, + "Authorization": "Basic " + auth, + }), + otlpmetrichttp.WithTimeout(time.Second*5), +) +``` + + + + + +```Java +String endpoint = String.format("https://%s/v1/otlp/v1/metrics", dbHost); +String auth = username + ":" + password; +String b64Auth = new String(Base64.getEncoder().encode(auth.getBytes())); +OtlpHttpMetricExporter exporter = OtlpHttpMetricExporter.builder() + .setEndpoint(endpoint) + .addHeader("X-Greptime-DB-Name", db) + .addHeader("Authorization", String.format("Basic %s", b64Auth)) + .setTimeout(Duration.ofSeconds(5)) + .build(); +``` + + + + + +```python +auth = f"{username}:{password}" +b64_auth = base64.b64encode(auth.encode()).decode("ascii") +endpoint = f"https://{host}/v1/otlp/v1/metrics" +exporter = OTLPMetricExporter( + endpoint=endpoint, + headers={"Authorization": f"Basic {b64_auth}", "X-Greptime-DB-Name": db}, + timeout=5) +``` + + + + + +You can find executable demos on GitHub at the links: [Go](https://github.com/GreptimeCloudStarters/quick-start-go), [Java](https://github.com/GreptimeCloudStarters/quick-start-java), [Python](https://github.com/GreptimeCloudStarters/quick-start-python), and [Node.js](https://github.com/GreptimeCloudStarters/quick-start-node-js). + +:::tip NOTE +The example codes above may be outdated according to OpenTelemetry. We recommend that you refer to the official OpenTelemetry documentation for the most up-to-date information. +::: + +For more information on the example code, please refer to the official documentation for your preferred programming language. + +#### Data Model + +The OTLP metrics data model is mapped to the GreptimeDB data model according to the following rules: + +- The name of the Metric will be used as the name of the GreptimeDB table, and the table will be automatically created if it does not exist. +- All attributes, including resource attributes, scope attributes, and data point attributes, will be used as tag columns of the GreptimeDB table. +- The timestamp of the data point will be used as the timestamp index of GreptimeDB, and the column name is `greptime_timestamp`. +- The data of Gauge/Sum data types will be used as the field column of GreptimeDB, and the column name is `greptime_value`. +- Each quantile of the Summary data type will be used as a separated data column of GreptimeDB, and the column name is `greptime_pxx`, where xx is the quantile, such as 90/99, etc. +- Histogram and ExponentialHistogram are not supported yet, we may introduce the Histogram data type to natively support these two types in a later version. + +## Logs + +### OTLP/HTTP + +import Includeotlplogintegration from '../../../db-cloud-shared/clients/otlp-logs-integration.md' + + + +#### Example Code + +Here are some example codes about how to use Grafana Alloy to send OpenTelemetry logs to GreptimeDB: + +```hcl +loki.source.file "greptime" { + targets = [ + {__path__ = "/tmp/foo.txt"}, + ] + forward_to = [otelcol.receiver.loki.greptime.receiver] +} + +otelcol.receiver.loki "greptime" { + output { + logs = [otelcol.exporter.otlphttp.greptimedb_logs.input] + } +} + +otelcol.auth.basic "credentials" { + username = "${GREPTIME_USERNAME}" + password = "${GREPTIME_PASSWORD}" +} + +otelcol.exporter.otlphttp "greptimedb_logs" { + client { + endpoint = "${GREPTIME_SCHEME:=http}://${GREPTIME_HOST:=greptimedb}:${GREPTIME_PORT:=4000}/v1/otlp/" + headers = { + "X-Greptime-DB-Name" = "${GREPTIME_DB:=public}", + "X-Greptime-Log-Table-Name" = "demo_logs", + "X-Greptime-Gog-Extract-Keys" = "filename,log.file.name,loki.attribute.labels", + } + auth = otelcol.auth.basic.credentials.handler + } +} +``` + +This example listens for changes to the file and sends the latest values to GreptimeDB via the otlp protocol. + +:::tip NOTE +The example codes above may be outdated according to OpenTelemetry. We recommend that you refer to the official OpenTelemetry documentation And Grafana Alloy for the most up-to-date information. +::: + +For more information on the example code, please refer to the official documentation for your preferred programming language. + +#### Data Model + +The OTLP logs data model is mapped to the GreptimeDB data model according to the following rules: + +Default table schema: + +```sql ++-----------------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++-----------------------+---------------------+------+------+---------+---------------+ +| timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | +| trace_id | String | | YES | | FIELD | +| span_id | String | | YES | | FIELD | +| severity_text | String | | YES | | FIELD | +| severity_number | Int32 | | YES | | FIELD | +| body | String | | YES | | FIELD | +| log_attributes | Json | | YES | | FIELD | +| trace_flags | UInt32 | | YES | | FIELD | +| scope_name | String | PRI | YES | | TAG | +| scope_version | String | | YES | | FIELD | +| scope_attributes | Json | | YES | | FIELD | +| scope_schema_url | String | | YES | | FIELD | +| resource_attributes | Json | | YES | | FIELD | +| resource_schema_url | String | | YES | | FIELD | ++-----------------------+---------------------+------+------+---------+---------------+ +17 rows in set (0.00 sec) +``` + +- You can use `X-Greptime-Log-Table-Name` to specify the table name for storing the logs. If not provided, the default table name is `opentelemetry_logs`. +- All attributes, including resource attributes, scope attributes, and log attributes, will be stored as a JSON column in the GreptimeDB table. +- The timestamp of the log will be used as the timestamp index in GreptimeDB, with the column name `timestamp`. It is preferred to use `time_unix_nano` as the timestamp column. If `time_unix_nano` is not provided, `observed_time_unix_nano` will be used instead. \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/overview.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/overview.md new file mode 100644 index 000000000..e63d93d51 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/overview.md @@ -0,0 +1,15 @@ +--- +description: Overview of integrating GreptimeDB with observability tools like Prometheus, Vector, OpenTelemetry, InfluxDB, and Loki for real-time monitoring and analysis. +--- + +# Overview + +In observability scenarios, +the ability to monitor and analyze system performance in real-time is crucial. +GreptimeDB integrates seamlessly with leading observability tools to provide a comprehensive view of your system's health and performance metrics. + +- [Prometheus Remote Write](prometheus.md): Integrate GreptimeDB as remote storage for Prometheus, suitable for real-time monitoring and alerting. +- [Vector](vector.md): Use GreptimeDB as a sink for Vector, ideal for complex data pipelines and diverse data sources. +- [OpenTelemetry](opentelemetry.md): Collect and export telemetry data to GreptimeDB for detailed observability insights. +- [InfluxDB Line Protocol](influxdb-line-protocol.md): A widely-used protocol for time-series data, facilitating migration from InfluxDB to GreptimeDB. The Telegraf integration method is also introduced in this document. +- [Loki](loki.md): A widely-used log write protocol, facilitating migration from Loki to GreptimeDB. The Alloy integration method is also introduced in this document. diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/prometheus.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/prometheus.md new file mode 100644 index 000000000..6a19af047 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/prometheus.md @@ -0,0 +1,163 @@ +--- +description: Guide to integrating Prometheus with GreptimeDB for long-term storage, including configuration, data model mapping, and efficiency improvements. +--- + +# Prometheus + +GreptimeDB can serve as a long-term storage solution for Prometheus, +providing a seamless integration experience. + +## Remote write configuration + +To configure Prometheus with GreptimeDB, +update your [Prometheus configuration file](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#configuration-file) (`prometheus.yml`) as follows: + +```yaml +remote_write: +- url: http://localhost:4000/v1/prometheus/write?db=public +# Uncomment and set credentials if authentication is enabled +# basic_auth: +# username: greptime_user +# password: greptime_pwd + +remote_read: +- url: http://localhost:4000/v1/prometheus/read?db=public +# Uncomment and set credentials if authentication is enabled +# basic_auth: +# username: greptime_user +# password: greptime_pwd +``` + +- The host and port in the URL represent the GreptimeDB server. In this example, the server is running on `localhost:4000`. You can replace it with your own server address. For the HTTP protocol configuration in GreptimeDB, please refer to the [protocol options](/user-guide/deployments/configuration.md#protocol-options). +- The `db` parameter in the URL represents the database to which we want to write data. It is optional. By default, the database is set to `public`. +- `basic_auth` is the authentication configuration. Fill in the username and password if GreptimeDB authentication is enabled. Please refer to the [authentication document](/user-guide/deployments/authentication/overview.md). + +## Data Model + +In the [data model](/user-guide/concepts/data-model.md) of GreptimeDB, data is organized into tables with columns for tags, time index, and fields. +GreptimeDB can be thought of as a multi-value data model, +automatically grouping multiple Prometheus metrics into corresponding tables. +This allows for efficient data management and querying. + +![Data Model](/PromQL-multi-value-data-model.png) + +When the metrics are written into GreptimeDB by remote write endpoint, they will be transformed as +follows: + +| Sample Metrics | In GreptimeDB | GreptimeDB Data Types | +|----------------|---------------------------|-----------------------| +| Name | Table (Auto-created) Name | String | +| Value | Column (Field) | Double | +| Timestamp | Column (Time Index) | Timestamp | +| Label | Column (Tag) | String | + +For example, the following Prometheus metric: + +```txt +prometheus_remote_storage_samples_total{instance="localhost:9090", job="prometheus", +remote_name="648f0c", url="http://localhost:4000/v1/prometheus/write"} 500 +``` + +will be transformed as a row in the table `prometheus_remote_storage_samples_total`： + +| Column | Value | Column Data Type | +| :----------------- | :------------------------------------------ | :----------------- | +| instance | localhost:9090 | String | +| job | prometheus | String | +| remote_name | 648f0c | String | +| url | `http://localhost:4000/v1/prometheus/write` | String | +| greptime_value | 500 | Double | +| greptime_timestamp | The sample's unix timestamp | Timestamp | + + +## Improve efficiency by using metric engine + +The Prometheus remote writing always creates a large number of small tables. +These tables are classified as logical tables in GreptimeDB. +However, having a large number of small tables can be inefficient for both data storage and query performance. +To address this, GreptimeDB introduces the [metric engine](/contributor-guide/datanode/metric-engine.md) feature, +which stores the data represented by the logical tables in a single physical table. +This approach reduces storage overhead and improves columnar compression efficiency. + +The metric engine is enabled by default in GreptimeDB, +and you don't need to specify any additional configuration. +By default, the physical table used is `greptime_physical_table`. +If you want to use a specific physical table, you can specify the `physical_table` parameter in the remote write URL. +If the specified physical table doesn't exist, it will be automatically created. + +```yaml +remote_write: +- url: http://localhost:4000/v1/prometheus/write?db=public&physical_table=greptime_physical_table +``` + + +Data is stored in the physical table, +while queries are performed on logical tables to provide an intuitive view from a metric perspective. +For instance, when successfully writing data, you can use the following command to display the logical tables: + +```sql +show tables; +``` + +```sql ++---------------------------------------------------------------+ +| Tables | ++---------------------------------------------------------------+ +| prometheus_remote_storage_enqueue_retries_total | +| prometheus_remote_storage_exemplars_pending | +| prometheus_remote_storage_read_request_duration_seconds_count | +| prometheus_rule_group_duration_seconds | +| ...... | ++---------------------------------------------------------------+ +``` + +The physical table itself can also be queried. +It contains columns from all the logical tables, +making it convenient for multi-join analysis and computation. + +To view the schema of the physical table, use the `DESC TABLE` command: + +```sql +DESC TABLE greptime_physical_table; +``` + +The physical table includes all the columns from the logical tables: + +```sql ++--------------------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+----------------------+------+------+---------+---------------+ +| greptime_timestamp | TimestampMillisecond | PRI | NO | | TIMESTAMP | +| greptime_value | Float64 | | YES | | FIELD | +| __table_id | UInt32 | PRI | NO | | TAG | +| __tsid | UInt64 | PRI | NO | | TAG | +| device | String | PRI | YES | | TAG | +| instance | String | PRI | YES | | TAG | +| job | String | PRI | YES | | TAG | +| error | String | PRI | YES | | TAG | +... +``` + +You can use the `SELECT` statement to filter data from the physical table as needed. +For example, you can filter data based on the `device` condition from logical table A and the `job` condition from logical table B: + +```sql +SELECT * +FROM greptime_physical_table +WHERE greptime_timestamp > "2024-08-07 03:27:26.964000" + AND device = "device1" + AND job = "job1"; +``` + +## VictoriaMetrics remote write + +VictoriaMetrics slightly modified Prometheus remote write protocol for better +compression. The protocol is automatically enabled when you are using `vmagent` +to send data to a compatible backend. + +GreptimeDB has this variant supported, too. Just configure GreptimeDB's remote +write url for `vmagent`. For example, if you have GreptimeDB installed locally: + +```shell +vmagent -remoteWrite.url=http://localhost:4000/v1/prometheus/write +``` diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/vector.md b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/vector.md new file mode 100644 index 000000000..67311efce --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/for-observerbility/vector.md @@ -0,0 +1,58 @@ +--- +description: Instructions for integrating Vector with GreptimeDB, including configuration, data model mapping, and example configurations. +--- + +import DocTemplate from '../../../db-cloud-shared/clients/vector-integration.md' + + +# Vector + + + +
+ +## Integration + +A minimal configuration of when using your GreptimeDB instance can be: + +```toml +# sample.toml + +[sources.in] +type = "host_metrics" + +[sinks.my_sink_id] +inputs = ["in"] +type = "greptimedb" +endpoint = ":4001" +dbname = "" +username = "" +password = "" +new_naming = true +``` + +GreptimeDB uses gRPC to communicate with Vector, so the default port for the Vector sink is `4001`. +If you have changed the default gRPC port when starting GreptimeDB with [custom configurations](/user-guide/deployments/configuration.md#configuration-file), use your own port instead. + +
+ +
+ +## Data Model + +The following rules are used when storing Vector metrics into GreptimeDB: + +- Use `_` as the table name in GreptimeDB, for example, `host_cpu_seconds_total`; +- Use the timestamp of the metric as the time index of GreptimeDB, the column name is `ts`; +- Use the tags of the metric as GreptimeDB tags; +- For Vector metrics which have multiple subtypes: + - For Counter and Gauge metrics, the values are stored in the `val` column; + - For Set metrics, the number of data points are stored in the `val` column; + - For Distribution metrics, the values of each percentile are stored in the `pxx` column, where xx is the percentile, and the `min/max/avg/sum/count` columns are also stored; + - For AggregatedHistogram metrics, the values of each bucket are stored in the `bxx` column, where xx is the upper limit of the bucket, and the `sum/count` columns are also stored; + - For AggregatedSummary metrics, the values of each percentile are stored in the `pxx` column, where xx is the percentile, and the `sum/count` columns are also stored; + - For Sketch metrics, the values of each percentile are stored in the `pxx` column, where xx is the percentile, and the `min/max/avg/sum` columns are also stored; + +
+ + diff --git a/versioned_docs/version-0.11/user-guide/ingest-data/overview.md b/versioned_docs/version-0.11/user-guide/ingest-data/overview.md new file mode 100644 index 000000000..c3e3b1252 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/ingest-data/overview.md @@ -0,0 +1,25 @@ +--- +description: Overview of data ingestion methods in GreptimeDB, including automatic schema generation and recommended methods for different scenarios. +--- + +# Overview + +## Automatic Schema Generation + +GreptimeDB supports schemaless writing, automatically creating tables and adding necessary columns as data is ingested. +This capability ensures that you do not need to manually define schemas beforehand, making it easier to manage and integrate diverse data sources seamlessly. + +This feature is supported for all protocols and integrations, except [SQL](./for-iot/sql.md). + +## Recommended Data Ingestion Methods + +GreptimeDB supports various data ingestion methods for specific scenarios, ensuring optimal performance and integration flexibility. + +- [For Observability Scenarios](./for-observerbility/overview.md): Suitable for real-time monitoring and alerting. +- [For IoT Scenarios](./for-iot/overview.md): Suitable for real-time data and complex IoT infrastructures. + +## Next Steps + +- [Query Data](/user-guide/query-data/overview.md): Learn how to explore your data by querying your GreptimeDB database. +- [Manage Data](/user-guide/manage-data/overview.md): Learn how to update and delete data, etc., to ensure data integrity and efficient data management. + diff --git a/versioned_docs/version-0.11/user-guide/integrations/dbeaver.md b/versioned_docs/version-0.11/user-guide/integrations/dbeaver.md new file mode 100644 index 000000000..bfa55df9a --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/integrations/dbeaver.md @@ -0,0 +1,25 @@ +--- +description: Guide to connecting GreptimeDB to DBeaver using MySQL database drivers, including connection settings and verification steps. +--- + +# DBeaver + +[DBeaver](https://dbeaver.io/) is a free, open-source, and cross-platform database tool that supports all popular databases. It is a popular choice among developers and database administrators for its ease of use and extensive feature set. + +You can use DBeaver to connect to GreptimeDB via MySQL database drivers. +Click the "New Database Connection" button in the DBeaver toolbar to create a new connection to GreptimeDB. + +Select MySQL and click "Next" to configure the connection settings. +Install the MySQL driver if you haven't already. +Input the following connection details: + +- Connect by Host +- Host: `localhost` if GreptimeDB is running on your local machine +- Port: `4002` if you use the default GreptimeDB configuration +- Database: `public`, you can use any other database name you have created +- Enter the username and password if authentication is enabled on GreptimeDB; otherwise, leave them blank. + +Click "Test Connection" to verify the connection settings and click "Finish" to save the connection. + +For more information on interacting with GreptimeDB using MySQL, refer to the [MySQL protocol documentation](/user-guide/protocols/mysql.md). + diff --git a/versioned_docs/version-0.11/user-guide/integrations/emqx.md b/versioned_docs/version-0.11/user-guide/integrations/emqx.md new file mode 100644 index 000000000..3dc9ab59a --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/integrations/emqx.md @@ -0,0 +1,4 @@ +# EMQX + +GreptimeDB can be used as a data system for EMQX. +For more information, please refer to the [Ingest Data through EMQX](/user-guide/ingest-data/for-iot/emqx.md) guide. diff --git a/versioned_docs/version-0.11/user-guide/integrations/grafana.md b/versioned_docs/version-0.11/user-guide/integrations/grafana.md new file mode 100644 index 000000000..d805ee062 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/integrations/grafana.md @@ -0,0 +1,134 @@ +--- +description: Steps to configure GreptimeDB as a data source in Grafana using different plugins and data sources, including installation and connection settings. +--- + +# Grafana + +GreptimeDB can be configured as a [Grafana data source](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/). +You have the option to connect GreptimeDB with Grafana using one of three data sources: [GreptimeDB](#greptimedb-data-source-plugin), [Prometheus](#prometheus-data-source), or [MySQL](#mysql-data-source). + +## GreptimeDB data source plugin + +The GreptimeDB data source plugin is based on the Prometheus data source and adds GreptimeDB-specific features. +The plugin adapts perfectly to the GreptimeDB data model, +thus providing a better user experience. +In addition, it also solves some compatibility issues compared to using the Prometheus data source directly. + +### Installation + +The GreptimeDB Data source plugin can currently only be installed on a local Grafana instance. +Make sure Grafana is installed and running before installing the plugin. + +You can choose one of the following installation methods: +- Download the installation package and unzip it to the relevant directory: Grab the latest release from [release +page](https://github.com/GreptimeTeam/greptimedb-grafana-datasource/releases/latest/), +Unzip the file to your [grafana plugin +directory](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#plugins). +- Use grafana cli to download and install: + ```shell + grafana cli --pluginUrl https://github.com/GreptimeTeam/greptimedb-grafana-datasource/releases/latest/download/info8fcc-greptimedb-datasource.zip plugins install info8fcc + ``` + +Note that you may need to restart your grafana server after installing the plugin. + +### Quick preview using Docker + +Greptime provides a docker compose file that integrates GreptimeDB, Prometheus, Prometheus Node Exporter, Grafana, and this plugin together so you can quickly experience the GreptimeDB data source plugin. + +```shell +git clone https://github.com/GreptimeTeam/greptimedb-grafana-datasource.git +cd docker +docker compose up +``` + +You can also try out this plugin from a Grafana docker image: + +```shell +docker run -d -p 3000:3000 --name=grafana --rm \ + -e "GF_INSTALL_PLUGINS=https://github.com/GreptimeTeam/greptimedb-grafana-datasource/releases/latest/download/info8fcc-greptimedb-datasource.zip;info8fcc" \ + grafana/grafana-oss +``` + +### Connection settings + +Click the Add data source button and select GreptimeDB as the type. + +![grafana-add-greptimedb-data-source](/grafana-add-greptimedb-data-source.png) + +Fill in the following URL in the GreptimeDB server URL: + +```txt +http://:4000 +``` + +Then do the following configuration: + +- Database Name：``, leave it blank to use the default database `public` +- In the Auth section, click basic auth, and fill in the username and password for GreptimeDB in the Basic Auth Details section (not set by default, no need to fill in). + - User: `` + - Password: `` + +Then click the Save & Test button to test the connection. + +### Create a dashboard + +Create a new dashboard in Grafana by clicking the `Create your first dashboard` button. +Then click `Add visualization`, select `GreptimeDB` as the data source. + +Select a metric from the `Metric` dropdown list, then click `Run queries` to view the metric data. +When you see the data and confirm it is correct, click `Save` to save the panel. + +![grafana-create-panel-with-selecting-metric](/create-panel-with-selecting-metric-greptimedb.png) + +You can also create a panel using PromQL. +Click the `code` button on the right side of the `Query` tab to switch to the PromQL editor. +Then enter a PromQL statement, such as `system_memory_usage{state="used"}`, click `Run query` to view the metric data. + +![grafana-create-panel-with-promql](/grafana-create-panel-with-promql.png) + + +:::tip NOTE +GreptimeDB is compatible with most PromQL, but there are some limitations. Please refer to the [PromQL limitations](/user-guide/query-data/promql.md#limitations) document for more information. +::: + +## Prometheus data source + +Click the "Add data source" button and select Prometheus as the type. + +Fill in Prometheus server URL in HTTP: + +```txt +http://:4000/v1/prometheus +``` + +Click basic auth in the Auth section and fill in your GreptimeDB username and password in Basic Auth Details: + +- User: `` +- Password: `` + +Click Custom HTTP Headers and add one header: + +- Header: `x-greptime-db-name` +- Value: `` + +Then click "Save & Test" button to test the connection. + +For how to query data with PromQL, please refer to the [Prometheus Query Language](/user-guide/query-data/promql.md) document. + +## MySQL data source + +Click the "Add data source" button and select MySQL as the type. Fill in the following information in MySQL Connection: + +- Host: `:4002` +- Database: `` +- User: `` +- Password: `` +- Session timezone: `UTC` + +Then click "Save & Test" button to test the connection. + +Note that you need to use raw SQL editor for panel creation. SQL Builder is not +supported due to timestamp data type difference between GreptimeDB and vanilla +MySQL. + +For how to query data with SQL, please refer to the [Query Data with SQL](/user-guide/query-data/sql.md) document. diff --git a/versioned_docs/version-0.11/user-guide/integrations/metabase.md b/versioned_docs/version-0.11/user-guide/integrations/metabase.md new file mode 100644 index 000000000..74897ac73 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/integrations/metabase.md @@ -0,0 +1,32 @@ +--- +description: Instructions for configuring GreptimeDB as a data source in Metabase, including installation of the driver plugin and connection settings. +--- + +# Metabase + +[Metabase](https://github.com/metabase/metabase) is an open source BI tool that +written in Clojure. You can configure GreptimeDB as a metabase data source from +a community driver plugin. + +## Installation + +Download the driver plugin file `greptimedb.metabase-driver.jar` from its +[release +page](https://github.com/greptimeteam/greptimedb-metabase-driver/releases/latest/). Copy +the jar file to `plugins/` of metabase's working directory. It will be +discovered by Metabase automatically. + +## Add GreptimeDB as database + +To add GreptimeDB database, select *Settings* / *Admin Settings* / *Databases*, +click *Add Database* button and select GreptimeDB from *Database type*. + +You will be asked to provide host, port, database name and authentication +information. + +- Use Greptime's Postgres protocol port `4003` as port. If you changed the + defaults, use you own settings. +- Username and password are optional if you didn't enable + [authentication](/user-guide/deployments/authentication/overview.md). +- Use `public` as default *Database name*. When using GreptimeCloud instance, + use the database name from your instance. diff --git a/versioned_docs/version-0.11/user-guide/integrations/overview.md b/versioned_docs/version-0.11/user-guide/integrations/overview.md new file mode 100644 index 000000000..c699335e1 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/integrations/overview.md @@ -0,0 +1,15 @@ +--- +description: Provides an overview of integrating GreptimeDB with popular tools for data ingestion, querying, and visualization, including Prometheus, Vector, Grafana, Superset, Metabase, and EMQX. +--- + +# Overview + +GreptimeDB can be seamlessly integrated with popular tools for data ingestion, querying, and visualization. +The subsequent sections offer comprehensive guidance on integrating GreptimeDB with the following tools: + +- [Prometheus](./prometheus.md) +- [Vector](./vector.md) +- [Grafana](./grafana.md) +- [Superset](./superset.md) +- [Metabase](./metabase.md) +- [EMQX](./emqx.md) diff --git a/versioned_docs/version-0.11/user-guide/integrations/prometheus.md b/versioned_docs/version-0.11/user-guide/integrations/prometheus.md new file mode 100644 index 000000000..c974ea7c3 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/integrations/prometheus.md @@ -0,0 +1,17 @@ +--- +description: Describes how to use GreptimeDB as a remote storage backend for Prometheus and how to query metrics using Prometheus Query Language (PromQL). +--- + +# Prometheus + +## Remote Write + +GreptimeDB can be used as a remote storage backend for Prometheus. +For detailed information, +please refer to the [Ingest Data with Prometheus Remote Write](/user-guide/ingest-data/for-observerbility/prometheus.md) document. + +## Prometheus Query Language (PromQL) + +GreptimeDB supports the Prometheus Query Language (PromQL) for querying metrics. +For more information, +please refer to the [Query Data with Prometheus Query Language](/user-guide/query-data/promql.md) document. diff --git a/versioned_docs/version-0.11/user-guide/integrations/superset.md b/versioned_docs/version-0.11/user-guide/integrations/superset.md new file mode 100644 index 000000000..138a9ff99 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/integrations/superset.md @@ -0,0 +1,57 @@ +--- +description: Guide to configuring GreptimeDB as a database in Apache Superset, including installation steps and connection settings. +--- + +# Superset + +[Apache Superset](https://superset.apache.org) is an open source BI tool that +written in Python. To configure GreptimeDB as a database in Superset, you can +follow this guide. + +## Installation + +### Running Superset with Docker Compose + +[Docker compose](https://superset.apache.org/docs/installation/docker-compose) +is the recommended way to run Superset. To add GreptimeDB extension, create a +`requirements-local.txt` file in `docker/` of Superset codebase. + +Add GreptimeDB dependency in `requirements-local.txt`: + +```txt +greptimedb-sqlalchemy +``` + +Start Superset services: + +```bash +docker compose -f docker-compose-non-dev.yml up +``` + +### Running Superset Locally + +If you are [running Superset from +pypi](https://superset.apache.org/docs/installation/pypi), install our extension +to the same environment. + +```bash +pip install greptimedb-sqlalchemy +``` + +## Add GreptimeDB as database + +To add GreptimeDB database, select *Settings* / *Database Connections*. + +Add database and select *GreptimeDB* from list of supported databases. + +Follow the SQLAlchemy URI pattern to provide your connection information: + +``` +greptimedb://:@:/ +``` + +- Ignore `:@` if you don't have + [authentication](/user-guide/deployments/authentication/overview.md) enabled. +- Use `4003` for default port (this extension uses Postgres protocol). +- Use `public` as default `database`. When using GreptimeCloud instance, use the + database name from your instance. diff --git a/versioned_docs/version-0.11/user-guide/integrations/vector.md b/versioned_docs/version-0.11/user-guide/integrations/vector.md new file mode 100644 index 000000000..22db231e0 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/integrations/vector.md @@ -0,0 +1,3 @@ +# Vector + +Please refer to the [Ingest Data with Vector](/user-guide/ingest-data/for-observerbility/vector.md) document for instructions on how to sink data to GreptimeDB using Vector. diff --git a/versioned_docs/version-0.11/user-guide/logs/manage-pipelines.md b/versioned_docs/version-0.11/user-guide/logs/manage-pipelines.md new file mode 100644 index 000000000..919c961bf --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/logs/manage-pipelines.md @@ -0,0 +1,299 @@ +--- +description: Guides on creating, deleting, and managing pipelines in GreptimeDB for parsing and transforming log data, including built-in pipelines and debugging. +--- + +# Manage Pipelines + +In GreptimeDB, each `pipeline` is a collection of data processing units used for parsing and transforming the ingested log content. This document provides guidance on creating and deleting pipelines to efficiently manage the processing flow of log data. + + +For specific pipeline configurations, please refer to the [Pipeline Configuration](pipeline-config.md) documentation. + +## Built-in Pipelines + +GreptimeDB offers built-in pipelines for common log formats, allowing you to use them directly without creating new pipelines. + +Note that the built-in pipelines are not editable. Additionally, the "greptime_" prefix of the pipeline name is reserved. + +### `greptime_identity` + +The `greptime_identity` pipeline is designed for writing JSON logs and automatically creates columns for each field in the JSON log. + +- The first-level keys in the JSON log are used as column names. +- An error is returned if the same field has different types. +- Fields with `null` values are ignored. +- An additional column, `greptime_timestamp`, is added to the table as the time index to indicate when the log was written. + +#### Type conversion rules + +- `string` -> `string` +- `number` -> `int64` or `float64` +- `boolean` -> `bool` +- `null` -> ignore +- `array` -> `json` +- `object` -> `json` + + +For example, if we have the following json data: + +```json +[ + {"name": "Alice", "age": 20, "is_student": true, "score": 90.5,"object": {"a":1,"b":2}}, + {"age": 21, "is_student": false, "score": 85.5, "company": "A" ,"whatever": null}, + {"name": "Charlie", "age": 22, "is_student": true, "score": 95.5,"array":[1,2,3]} +] +``` + +We'll merge the schema for each row of this batch to get the final schema. The table schema will be: + +```sql +mysql> desc pipeline_logs; ++--------------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+---------------------+------+------+---------+---------------+ +| age | Int64 | | YES | | FIELD | +| is_student | Boolean | | YES | | FIELD | +| name | String | | YES | | FIELD | +| object | Json | | YES | | FIELD | +| score | Float64 | | YES | | FIELD | +| company | String | | YES | | FIELD | +| array | Json | | YES | | FIELD | +| greptime_timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | ++--------------------+---------------------+------+------+---------+---------------+ +8 rows in set (0.00 sec) +``` + +The data will be stored in the table as follows: + +```sql +mysql> select * from pipeline_logs; ++------+------------+---------+---------------+-------+---------+---------+----------------------------+ +| age | is_student | name | object | score | company | array | greptime_timestamp | ++------+------------+---------+---------------+-------+---------+---------+----------------------------+ +| 22 | 1 | Charlie | NULL | 95.5 | NULL | [1,2,3] | 2024-10-18 09:35:48.333020 | +| 21 | 0 | NULL | NULL | 85.5 | A | NULL | 2024-10-18 09:35:48.333020 | +| 20 | 1 | Alice | {"a":1,"b":2} | 90.5 | NULL | NULL | 2024-10-18 09:35:48.333020 | ++------+------------+---------+---------------+-------+---------+---------+----------------------------+ +3 rows in set (0.01 sec) +``` + +## Create a Pipeline + +GreptimeDB provides a dedicated HTTP interface for creating pipelines. +Assuming you have prepared a pipeline configuration file `pipeline.yaml`, use the following command to upload the configuration file, where `test` is the name you specify for the pipeline: + +```shell +## Upload the pipeline file. 'test' is the name of the pipeline +curl -X "POST" "http://localhost:4000/v1/events/pipelines/test?db=public" -F "file=@pipeline.yaml" +``` + +The created Pipeline is associated with a database, which can be specified with the URL parameter `db`, defaulting to `public`. +When writing log to a database, the Pipeline used must be under the same database as the table being written to. + +## Delete a Pipeline + +You can use the following HTTP interface to delete a pipeline: + +```shell +## 'test' is the name of the pipeline +curl -X "DELETE" "http://localhost:4000/v1/events/pipelines/test?db=public&version=2024-06-27%2012%3A02%3A34.257312110Z" +``` + +In the above example, we deleted a pipeline named `test` in `public` database. The `version` parameter is required to specify the version of the pipeline to be deleted. + +## Query Pipelines + +Currently, you can use SQL to query pipeline information. + +```sql +SELECT * FROM greptime_private.pipelines; +``` + +Please note that if you are using the MySQL or PostgreSQL protocol to connect to GreptimeDB, the precision of the pipeline time information may vary, and nanosecond-level precision may be lost. + +To address this issue, you can cast the `created_at` field to a timestamp to view the pipeline's creation time. For example, the following query displays `created_at` in `bigint` format: + +```sql +SELECT name, pipeline, created_at::bigint FROM greptime_private.pipelines; +``` + +The query result is as follows: + +``` + name | pipeline | greptime_private.pipelines.created_at +------+-----------------------------------+--------------------------------------- + test | processors: +| 1719489754257312110 + | - date: +| + | field: time +| + | formats: +| + | - "%Y-%m-%d %H:%M:%S%.3f"+| + | ignore_missing: true +| + | +| + | transform: +| + | - fields: +| + | - id1 +| + | - id2 +| + | type: int32 +| + | - fields: +| + | - type +| + | - logger +| + | type: string +| + | index: tag +| + | - fields: +| + | - log +| + | type: string +| + | index: fulltext +| + | - field: time +| + | type: time +| + | index: timestamp +| + | | +(1 row) +``` + +Then, you can use a program to convert the bigint type timestamp from the SQL result into a time string. + +```shell +timestamp_ns="1719489754257312110"; readable_timestamp=$(TZ=UTC date -d @$((${timestamp_ns:0:10}+0)) +"%Y-%m-%d %H:%M:%S").${timestamp_ns:10}Z; echo "Readable timestamp (UTC): $readable_timestamp" +``` + +Output: + +```shell +Readable timestamp (UTC): 2024-06-27 12:02:34.257312110Z +``` + +The output `Readable timestamp (UTC)` represents the creation time of the pipeline and also serves as the version number. + +## Debug + +First, please refer to the [Quick Start example](/user-guide/logs/quick-start.md#write-logs-by-pipeline) to see the correct execution of the Pipeline. + +### Debug creating a Pipeline + +You may encounter errors when creating a Pipeline. For example, when creating a Pipeline using the following configuration: + + +```bash +curl -X "POST" "http://localhost:4000/v1/events/pipelines/test" \ + -H 'Content-Type: application/x-yaml' \ + -d $'processors: + - date: + field: time + formats: + - "%Y-%m-%d %H:%M:%S%.3f" + ignore_missing: true + - gsub: + fields: + - message + pattern: "\\\." + replacement: + - "-" + ignore_missing: true + +transform: + - fields: + - message + type: string + - field: time + type: time + index: timestamp' +``` + +The pipeline configuration contains an error. The `gsub` Processor expects the `replacement` field to be a string, but the current configuration provides an array. As a result, the pipeline creation fails with the following error message: + + +```json +{"error":"Failed to parse pipeline: 'replacement' must be a string"} +``` + +Therefore, We need to modify the configuration of the `gsub` Processor and change the value of the `replacement` field to a string type. + +```bash +curl -X "POST" "http://localhost:4000/v1/events/pipelines/test" \ + -H 'Content-Type: application/x-yaml' \ + -d $'processors: + - date: + field: time + formats: + - "%Y-%m-%d %H:%M:%S%.3f" + ignore_missing: true + - gsub: + fields: + - message + pattern: "\\\." + replacement: "-" + ignore_missing: true + +transform: + - fields: + - message + type: string + - field: time + type: time + index: timestamp' +``` + +Now that the Pipeline has been created successfully, you can test the Pipeline using the `dryrun` interface. + +### Debug writing logs + +We can test the Pipeline using the `dryrun` interface. We will test it with erroneous log data where the value of the message field is in numeric format, causing the pipeline to fail during processing. + +**This API is only used to test the results of the Pipeline and does not write logs to GreptimeDB.** + + +```bash +curl -X "POST" "http://localhost:4000/v1/events/pipelines/dryrun?pipeline_name=test" \ + -H 'Content-Type: application/json' \ + -d $'{"message": 1998.08,"time":"2024-05-25 20:16:37.217"}' + +{"error":"Failed to execute pipeline, reason: gsub processor: expect string or array string, but got Float64(1998.08)"} +``` + +The output indicates that the pipeline processing failed because the `gsub` Processor expects a string type rather than a floating-point number type. We need to adjust the format of the log data to ensure the pipeline can process it correctly. +Let's change the value of the message field to a string type and test the pipeline again. + +```bash +curl -X "POST" "http://localhost:4000/v1/events/pipelines/dryrun?pipeline_name=test" \ + -H 'Content-Type: application/json' \ + -d $'{"message": "1998.08","time":"2024-05-25 20:16:37.217"}' +``` + +At this point, the Pipeline processing is successful, and the output is as follows: + +```json +{ + "rows": [ + [ + { + "data_type": "STRING", + "key": "message", + "semantic_type": "FIELD", + "value": "1998-08" + }, + { + "data_type": "TIMESTAMP_NANOSECOND", + "key": "time", + "semantic_type": "TIMESTAMP", + "value": "2024-05-25 20:16:37.217+0000" + } + ] + ], + "schema": [ + { + "colume_type": "FIELD", + "data_type": "STRING", + "fulltext": false, + "name": "message" + }, + { + "colume_type": "TIMESTAMP", + "data_type": "TIMESTAMP_NANOSECOND", + "fulltext": false, + "name": "time" + } + ] +} +``` + +It can be seen that the `.` in the string `1998.08` has been replaced with `-`, indicating a successful processing of the Pipeline. \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/logs/overview.md b/versioned_docs/version-0.11/user-guide/logs/overview.md new file mode 100644 index 000000000..b9854d0f6 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/logs/overview.md @@ -0,0 +1,11 @@ +--- +description: Provides links to various guides on using GreptimeDB's log service, including quick start, pipeline configuration, managing pipelines, writing logs, and querying logs. +--- + +# Overview + +- [Quick Start](./quick-start.md): Provides an introduction on how to quickly get started with GreptimeDB log service. +- [Pipeline Configuration](./pipeline-config.md): Provides in-depth information on each specific configuration of pipelines in GreptimeDB. +- [Managing Pipelines](./manage-pipelines.md): Explains how to create and delete pipelines. +- [Writing Logs with Pipelines](./write-logs.md): Provides detailed instructions on efficiently writing log data by leveraging the pipeline mechanism. +- [Query Logs](./query-logs.md): Describes how to query logs using the GreptimeDB SQL interface. diff --git a/versioned_docs/version-0.11/user-guide/logs/pipeline-config.md b/versioned_docs/version-0.11/user-guide/logs/pipeline-config.md new file mode 100644 index 000000000..d12ea016a --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/logs/pipeline-config.md @@ -0,0 +1,579 @@ +--- +description: Explains the configuration of pipelines in GreptimeDB for parsing and transforming log data, including processors and transform rules. +--- + +# Pipeline Configuration + +Pipeline is a mechanism in GreptimeDB for parsing and transforming log data. It consists of a unique name and a set of configuration rules that define how log data is formatted, split, and transformed. Currently, we support JSON (`application/json`) and plain text (`text/plain`) formats as input for log data. + +These configurations are provided in YAML format, allowing the Pipeline to process data during the log writing process according to the defined rules and store the processed data in the database for subsequent structured queries. + +## Overall structure + +Pipeline consists of two parts: Processors and Transform, both of which are in array format. A Pipeline configuration can contain multiple Processors and multiple Transforms. The data type described by Transform determines the table structure when storing log data in the database. + +- Processors are used for preprocessing log data, such as parsing time fields and replacing fields. +- Transform is used for converting data formats, such as converting string types to numeric types. + +Here is an example of a simple configuration that includes Processors and Transform: + +```yaml +processors: + - urlencoding: + fields: + - string_field_a + - string_field_b + method: decode + ignore_missing: true +transform: + - fields: + - string_field_a + - string_field_b + type: string + # The written data must include the timestamp field + - fields: + - reqTimeSec, req_time_sec + # epoch is a special field type and must specify precision + type: epoch, ms + index: timestamp +``` + +## Processor + +The Processor is used for preprocessing log data, and its configuration is located under the `processors` field in the YAML file. The Pipeline processes data by applying multiple Processors in sequential order, where each Processor depends on the result of the previous Processor. A Processor consists of a name and multiple configurations, and different types of Processors have different fields in their configuration. + +We currently provide the following built-in Processors: + +- `date`: parses formatted time string fields, such as `2024-07-12T16:18:53.048`. +- `epoch`: parses numeric timestamp fields, such as `1720772378893`. +- `dissect`: splits log data fields. +- `gsub`: replaces log data fields. +- `join`: merges array-type fields in logs. +- `letter`: converts log data fields to letters. +- `regex`: performs regular expression matching on log data fields. +- `urlencoding`: performs URL encoding/decoding on log data fields. +- `csv`: parses CSV data fields in logs. + +Most processors have `field` or `fields` fields to specify the fields that need to be processed. Most processors will overwrite the original field after processing. If you do not want to affect the corresponding field in the original data, we can output the result to another field to avoid overwriting. + +When a field name contains `,`, the target field will be renamed. For example, `reqTimeSec, req_time_sec` means renaming the `reqTimeSec` field to `req_time_sec`, and the processed data will be written to the `req_time_sec` key in the intermediate state. The original `reqTimeSec` field is not affected. If some processors do not support field renaming, the renamed field name will be ignored and noted in the documentation. + +for example + +```yaml +processors: + - letter: + fields: + - message, message_upper + method: upper + ignore_missing: true +``` + +the `message` field will be converted to uppercase and stored in the `message_upper` field. + +### `date` + +The `date` processor is used to parse time fields. Here's an example configuration: + +```yaml +processors: + - date: + fields: + - time + formats: + - '%Y-%m-%d %H:%M:%S%.3f' + ignore_missing: true + timezone: 'Asia/Shanghai' +``` + +In the above example, the configuration of the `date` processor includes the following fields: + +- `fields`: A list of time field names to be parsed. +- `formats`: Time format strings, supporting multiple format strings. Parsing is attempted in the order provided until successful. You can find reference [here](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) for formatting syntax. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. +- `timezone`: Time zone. Use the time zone identifiers from the [tz_database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to specify the time zone. Defaults to `UTC`. + +### `epoch` + +The `epoch` processor is used to parse timestamp fields. Here's an example configuration: + +```yaml +processors: + - epoch: + fields: + - reqTimeSec + resolution: millisecond + ignore_missing: true +``` + +In the above example, the configuration of the `epoch` processor includes the following fields: + +- `fields`: A list of timestamp field names to be parsed. +- `resolution`: Timestamp precision, supports `s`, `sec`, `second`, `ms`, `millisecond`, `milli`, `us`, `microsecond`, `micro`, `ns`, `nanosecond`, `nano`. Defaults to `ms`. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. + +### `dissect` + +The `dissect` processor is used to split log data fields. Here's an example configuration: + +```yaml +processors: + - dissect: + fields: + - message + patterns: + - '%{key1} %{key2}' + ignore_missing: true + append_separator: '-' +``` + +In the above example, the configuration of the `dissect` processor includes the following fields: + +- `fields`: A list of field names to be split, does not support field renaming. +- `patterns`: The dissect pattern for splitting. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. +- `append_separator`: Specifies the separator for concatenating multiple fields with same field name together. Defaults to an empty string. See `+` modifier below. + +#### Dissect pattern + +Similar to Logstash's dissect pattern, the dissect pattern consists of `%{key}`, where `%{key}` is a field name. For example: + +``` +"%{key1} %{key2} %{+key3} %{+key4/2} %{key5->} %{?key6}" +``` + +#### Dissect modifiers + +The dissect pattern supports the following modifiers: + +| Modifier | Description | Example | +| ---------- | ---------------------------------------------------- | -------------------- | +| `+` | Concatenates two or more fields together | `%{+key} %{+key}` | +| `+` and `/n` | Concatenates two or more fields in the specified order | `%{+key/2} %{+key/1}` | +| `->` | Ignores any repeating characters on the right side | `%{key1->} %{key2->}` | +| `?` | Ignores matching values | `%{?key}` | + +#### `dissect` examples + +For example, given the following log data: + +``` +"key1 key2 key3 key4 key5 key6" +``` + +Using the following Dissect pattern: + +``` +"%{key1} %{key2} %{+key3} %{+key3/2} %{key5->} %{?key6}" +``` + +The result will be: + +``` +{ + "key1": "key1", + "key2": "key2", + "key3": "key3 key4", + "key5": "key5" +} +``` + +### `gsub` + +The `gsub` processor is used to replace values in log data fields. Here's an example configuration: + +```yaml +processors: + - gsub: + fields: + - message + pattern: 'old' + replacement: 'new' + ignore_missing: true +``` + +In the above example, the configuration of the `gsub` processor includes the following fields: + +- `fields`: A list of field names to be replaced. +- `pattern`: The string to be replaced. Supports regular expressions. +- `replacement`: The string to replace with. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. + +### `join` + +The `join` processor is used to merge Array-type fields in log data. Here's an example configuration: + +```yaml +processors: + - join: + fields: + - message + separator: ',' + ignore_missing: true +``` + +In the above example, the configuration of the `join` processor includes the following fields: + +- `fields`: A list of field names to be merged. Note that all the fields mentioned are already of array type. Each field will have its own array merged separately. The content of multiple fields will not be combined. +- `separator`: The separator for the merged result. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. + +#### `join` example + +For example, given the following log data: + +```json +{ + "message": ["a", "b", "c"] +} +``` + +Using the following configuration: + +```yaml +processors: + - join: + fields: + - message + separator: ',' +``` + +The result will be: + +```json +{ + "message": "a,b,c" +} +``` + +### `letter` + +The `letter` processor is used to convert the case of characters in log data fields. Here's an example configuration: + +```yaml +processors: + - letter: + fields: + - message + method: upper + ignore_missing: true +``` + +In the above example, the configuration of the `letter` processor includes the following fields: + +- `fields`: A list of field names to be transformed. +- `method`: The transformation method, supports `upper`, `lower`, `capital`. Defaults to `lower`. Note the `capital` only changes the first letter to uppercase. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. + +### `regex` + +The `regex` processor is used to perform regular expression matching on log data fields. Here's an example configuration: + +```yaml +processors: + - regex: + fields: + - message + patterns: + - ':(?[0-9])' + ignore_missing: true +``` + +In the above example, the configuration of the `regex` processor includes the following fields: + +- `fields`: A list of field names to be matched. If you rename the field, the renamed fields will be combined with the capture groups in `patterns` to generate the result name. +- `pattern`: The regular expression pattern to match. Named capture groups are required to extract corresponding data from the respective field. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. + +#### Rules for named capture groups in regex + +The `regex` processor supports the syntax `(?...)` to define named capture groups. The data will be processed into the following format: + +```json +{ + "_": "" +} +``` + +For example, if the field name specified in the `regex` processor is `message`, and the corresponding content is `"[ERROR] error message"`, you can set the pattern as `\[(?[A-Z]+)\] (?.+)`, and the data will be processed as: + +```json +{ + "message_level": "ERROR", + "message_content": "error message" +} +``` + +### `urlencoding` + +The `urlencoding` processor is used to perform URL encoding on log data fields. Here's an example configuration: + +```yaml +processors: + - urlencoding: + fields: + - string_field_a + - string_field_b + method: decode + ignore_missing: true +``` + +In the above example, the configuration of the `urlencoding` processor includes the following fields: + +- `fields`: A list of field names to be encoded. +- `method`: The encoding method, supports `encode`, `decode`. Defaults to `encode`. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. + +### `csv` + +The `csv` processor is used to parse CSV-type fields in log data that do not have a header. Here's an example configuration: + +```yaml +processors: + - csv: + fields: + - message + separator: ',' + quote: '"' + trim: true + ignore_missing: true +``` + +In the above example, the configuration of the `csv` processor includes the following fields: + +- `fields`: A list of field names to be parsed. +- `separator`: The separator. +- `quote`: The quotation mark. +- `trim`: Whether to trim whitespace. Defaults to `false`. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. + +### `json_path` (experimental) + +Note: The `json_path` processor is currently in the experimental stage and may be subject to change. + +The `json_path` processor is used to extract fields from JSON data. Here's an example configuration: + +```yaml +processors: + - json_path: + fields: + - complex_object + json_path: "$.shop.orders[?(@.active)].id" + ignore_missing: true + result_index: 1 +``` + +In the above example, the configuration of the `json_path` processor includes the following fields: + +- `fields`: A list of field names to be extracted. +- `json_path`: The JSON path to extract. +- `ignore_missing`: Ignores the case when the field is missing. Defaults to `false`. If the field is missing and this configuration is set to `false`, an exception will be thrown. +- `result_index`: Specifies the index of the value in the extracted array to be used as the result value. By default, all values are included. The extracted value of the processor is an array containing all the values of the path. If an index is specified, the corresponding value in the extracted array will be used as the final result. + +#### JSON path syntax + +The JSON path syntax is based on the [jsonpath-rust](https://github.com/besok/jsonpath-rust) library. + +At this stage we only recommend using some simple field extraction operations to facilitate the extraction of nested fields to the top level. + +#### `json_path` example + +For example, given the following log data: + +```json +{ + "product_object": { + "hello": "world" + }, + "product_array": [ + "hello", + "world" + ], + "complex_object": { + "shop": { + "orders": [ + { + "id": 1, + "active": true + }, + { + "id": 2 + }, + { + "id": 3 + }, + { + "id": 4, + "active": true + } + ] + } + } +} +``` + +Using the following configuration: + +```yaml +processors: + - json_path: + fields: + - product_object, object_target + json_path: "$.hello" + result_index: 0 + - json_path: + fields: + - product_array, array_target + json_path: "$.[1]" + result_index: 0 + - json_path: + fields: + - complex_object, complex_target_1 + json_path: "$.shop.orders[?(@.active)].id" + - json_path: + fields: + - complex_target_1, complex_target_2 + json_path: "$.[1]" + result_index: 0 + - json_path: + fields: + - complex_object, complex_target_3 + json_path: "$.shop.orders[?(@.active)].id" + result_index: 1 +transform: + - fields: + - object_target + - array_target + type: string + - fields: + - complex_target_3 + - complex_target_2 + type: uint32 + - fields: + - complex_target_1 + type: json +``` + +The result will be: + +```json +{ + "object_target": "world", + "array_target": "world", + "complex_target_3": 4, + "complex_target_2": 4, + "complex_target_1": [1, 4] +} +``` + + +## Transform + +Transform is used to convert log data, and its configuration is located under the `transform` field in the YAML file. + +A Transform consists of one or more configurations, and each configuration contains the following fields: + +- `fields`: A list of field names to be transformed. +- `type`: The transformation type. +- `index`: Index type (optional). +- `on_failure`: Handling method for transformation failures (optional). +- `default`: Default value (optional). + +### The `fields` field + +Each field name is a string. When a field name contains `,`, the field will be renamed. For example, `reqTimeSec, req_time_sec` means renaming the `reqTimeSec` field to `req_time_sec`, and the final data will be written to the `req_time_sec` column in GreptimeDB. + +### The `type` field + +GreptimeDB currently provides the following built-in transformation types: + +- `int8`, `int16`, `int32`, `int64`: Integer types. +- `uint8`, `uint16`, `uint32`, `uint64`: Unsigned integer types. +- `float32`, `float64`: Floating-point types. +- `string`: String type. +- `time`: Time type, which will be converted to GreptimeDB `timestamp(9)` type. +- `epoch`: Timestamp type, which will be converted to GreptimeDB `timestamp(n)` type. The value of `n` depends on the precision of the epoch. When the precision is `s`, `n` is 0; when the precision is `ms`, `n` is 3; when the precision is `us`, `n` is 6; when the precision is `ns`, `n` is 9. + +If a field obtains an illegal value during the transformation process, the Pipeline will throw an exception. For example, when converting a string `abc` to an integer, an exception will be thrown because the string is not a valid integer. + +### The `index` field + +The `Pipeline` will write the processed data to the automatically created table in GreptimeDB. To improve query efficiency, GreptimeDB creates indexes for certain columns in the table. The `index` field is used to specify which fields need to be indexed. For information about GreptimeDB column types, please refer to the [Data Model](/user-guide/concepts/data-model.md) documentation. + +GreptimeDB supports the following three types of index for fields: + +- `tag`: Specifies a column as a Tag column. +- `fulltext`: Specifies a column to use the fulltext index type. The column must be of string type. +- `timestamp`: Specifies a column as a timestamp index column. + +When `index` field is not provided, GreptimeDB treats the field as a `Field` column. + +In GreptimeDB, a table must include one column of type `timestamp` as the time index column. Therefore, a Pipeline can have only one time index column. + +#### The Timestamp column + +Specify which field is the timestamp index column using `index: timestamp`. Refer to the [Transform Example](#transform-example) below for syntax. + +#### The Tag column + +Specify which field is the Tag column using `index: tag`. Refer to the [Transform Example](#transform-example) below for syntax. + +#### The Fulltext column + +Specify which field will be used for full-text search using `index: fulltext`. This index greatly improves the performance of [log search](./query-logs.md). Refer to the [Transform Example](#transform-example) below for syntax. + +### The `on_failure` field + +The `on_failure` field is used to specify the handling method when a transformation fails. It supports the following methods: + +- `ignore`: Ignore the failed field and do not write it to the database. +- `default`: Write the default value. The default value is specified by the `default` field. + +### The `default` field + +The `default` field is used to specify the default value when a transformation fails. + +### Transform Example + +For example, with the following log data: + +```json +{ + "num_field_a": "3", + "string_field_a": "john", + "string_field_b": "It was snowing when he was born.", + "time_field_a": 1625760000 +} +``` + +Using the following configuration: + +```yaml +transform: + - fields: + - string_field_a, name + type: string + index: tag + - fields: + - num_field_a, age + type: int32 + - fields: + - string_field_b, description + type: string + index: fulltext + - fields: + - time_field_a, born_time + type: epoch, s + index: timestamp +``` + +The result will be: + +``` +{ + "name": "john", + "age": 3, + "description": "It was snowing when he was born.", + "born_time": 2021-07-08 16:00:00 +} +``` \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/logs/query-logs.md b/versioned_docs/version-0.11/user-guide/logs/query-logs.md new file mode 100644 index 000000000..7b35e7430 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/logs/query-logs.md @@ -0,0 +1,144 @@ +--- +description: Provides a guide on using GreptimeDB's query language for effective searching and analysis of log data, including full-text search and query statements. +--- + +# Query Logs + +This document provides a guide on how to use GreptimeDB's query language for effective searching and analysis of log data. + +## Overview + +GreptimeDB allows for flexible querying of data using SQL statements. This section introduces specific search functions and query statements designed to enhance your log querying capabilities. + +## Full-Text Search Using the `MATCHES` Function + +In SQL statements, you can use the `MATCHES` function to perform full-text searches, which is especially useful for log analysis. The `MATCHES` function supports full-text searches on `String` type columns. Here’s an example of how it can be used: + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'error OR fail'); +``` + +The `MATCHES` function is designed for full-text search and accepts two parameters: + +- `column_name`: The column to perform the full-text search on, which should contain textual data of type `String`. The [full-text index](#full-text-index-for-accelerated-search) must be created on this column to optimize queries. +- `search_query`: A string containing query statement which you want to search for. See the [Query Statements](#query-statements) section below for more details. + +## Query Statements + +### Simple Term + +Simple term searches are straightforward: + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'Barack Obama'); +``` + +The value `Barack Obama` in the `search_query` parameter of the `MATCHES` function will be considered as two separate terms: `Barack` and `Obama`. This means the query will match all rows containing either `Barack` or `Obama`, equivalent to using `OR`: + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'Barack OR Obama'); +``` + +### Negative Term + +Prefixing a term with `-` excludes rows containing that term. For instance, to find rows containing `apple` but not `fruit`: + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'apple -fruit'); +``` + +### Must Term + +Prefixing a term with `+` specifies that it must be included in the results. For example, to query rows containing both `apple` and `fruit`: + +```sql +SELECT * FROM logs WHERE MATCHES(message, '+apple +fruit'); +``` + +### Boolean Operators + +Boolean operators can specify logical conditions for the search. For example, the `AND` operator requires all specified terms to be included, while the `OR` operator requires at least one term to be included. The `AND` operator takes precedence over `OR`, so the expression `a AND b OR c` is interpreted as `(a AND b) OR c`. For example: + +```sql +SELECT * FROM logs WHERE MATCHES(message, 'a AND b OR c'); +``` + +This matches rows containing both `a` and `b`, or rows containing `c`. Equivalent to: + +```sql +SELECT * FROM logs WHERE MATCHES(message, '(+a +b) c'); +``` + +### Phrase Term + +A phrase term is enclosed within quotes `" "` and matches the exact sequence of words. For example, to match rows containing `Barack` followed directly by `Obama`: + +```sql +SELECT * FROM logs WHERE MATCHES(message, '"Barack Obama"'); +``` + +To include quotes within a phrase, use a backslash `\` to escape them: + +```sql +SELECT * FROM logs WHERE MATCHES(message, '"He said \"hello\""'); +``` + +## Full-Text Index for Accelerated Search + +A full-text index is essential for full-text search, especially when dealing with large datasets. Without a full-text index, the search operation could be very slow, impacting the overall query performance and user experience. You can configure a full-text index either directly via SQL during table creation or through the Pipeline configuration, ensuring that search operations are performed efficiently, even with significant data volumes. + +### Creating Full-Text Index via SQL + +You can create a full-text index for a column by specifying the `FULLTEXT` option in the column definition. Below is an example of creating a table with a full-text index on the `message` column: + +```sql +CREATE TABLE `logs` ( + `message` STRING FULLTEXT, + `time` TIMESTAMP TIME INDEX, +) WITH ( + append_mode = 'true' +); +``` + +For more details, see the [Fulltext Column Option](/reference/sql/create.md#fulltext-column-option). + +### Configuring Full-Text Index via Pipeline + +In the Pipeline configuration, you can [specify a column to use a full-text index](./pipeline-config.md#the-index-field). Below is a configuration example where the `message` column is set with a full-text index: + +```yaml +processors: + - date: + field: time + formats: + - "%Y-%m-%d %H:%M:%S%.3f" + ignore_missing: true + +transform: + - field: message + type: string + index: fulltext + - field: time + type: time + index: timestamp +``` + +#### Viewing Table Schema + +After data is written, you can use an SQL statement to view the table schema and confirm that the `message` column is set for full-text indexing: + +```sql +SHOW CREATE TABLE logs\G +*************************** 1. row *************************** + Table: logs +Create Table: CREATE TABLE IF NOT EXISTS `logs` ( + `message` STRING NULL FULLTEXT WITH(analyzer = 'English', case_sensitive = 'false'), + `time` TIMESTAMP(9) NOT NULL, + TIME INDEX (`time`), +) + +ENGINE=mito +WITH( + append_mode = 'true' +) +``` diff --git a/versioned_docs/version-0.11/user-guide/logs/quick-start.md b/versioned_docs/version-0.11/user-guide/logs/quick-start.md new file mode 100644 index 000000000..806f2aefb --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/logs/quick-start.md @@ -0,0 +1,278 @@ +--- +description: Guides users through the process of quickly writing and querying logs in GreptimeDB, including direct log writing and using pipelines for structured data. +--- + +# Quick Start + +This guide will walk you through the process of quickly writing and querying logs. + +You can write logs directly or use pipeline to write logs. +Writing logs directly is simple but cannot split log text to structured data as the pipeline method does. +The following sections will help you understand the differences between these two methods. + +## Write logs directly + +This is the simplest way to write logs to GreptimeDB. + +### Create a table + +First, create a table named origin_logs to store your logs. +The `FULLTEXT` specification for the message column in the following SQL creates a full-text index to optimize queries. + +```sql +CREATE TABLE `origin_logs` ( + `message` STRING FULLTEXT, + `time` TIMESTAMP TIME INDEX +) WITH ( + append_mode = 'true' +); +``` + +### Insert logs + +#### Write logs using the SQL protocol + +Use the `INSERT` statement to insert logs into the table. + +```sql +INSERT INTO origin_logs (message, time) VALUES +('127.0.0.1 - - [25/May/2024:20:16:37 +0000] "GET /index.html HTTP/1.1" 200 612 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"', '2024-05-25 20:16:37.217'), +('192.168.1.1 - - [25/May/2024:20:17:37 +0000] "POST /api/login HTTP/1.1" 200 1784 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36"', '2024-05-25 20:17:37.217'), +('10.0.0.1 - - [25/May/2024:20:18:37 +0000] "GET /images/logo.png HTTP/1.1" 304 0 "-" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0"', '2024-05-25 20:18:37.217'), +('172.16.0.1 - - [25/May/2024:20:19:37 +0000] "GET /contact HTTP/1.1" 404 162 "-" "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1"', '2024-05-25 20:19:37.217'); +``` + +The above SQL inserts the entire log text into a single column, +and you must add an extra timestamp for each log. + +#### Write logs using the gRPC protocol + +You can also write logs using the gRPC protocol, which is a more efficient method. + +Refer to [Write Data Using gRPC](/user-guide/ingest-data/for-iot/grpc-sdks/overview.md) to learn how to write logs using the gRPC protocol. + +## Write logs by Pipeline + +Using a pipeline allows you to automatically parse and transform the log message into multiple columns, +as well as create tables automatically. + +### Write JSON logs using the built-in Pipeline + +GreptimeDB offers a built-in pipeline, `greptime_identity`, for handling JSON log formats. This pipeline simplifies the process of writing JSON logs. + +```shell +curl -X "POST" "http://localhost:4000/v1/events/logs?db=public&table=pipeline_logs&pipeline_name=greptime_identity" \ + -H 'Content-Type: application/json' \ + -d $'[ + {"name": "Alice", "age": 20, "is_student": true, "score": 90.5,"object": {"a":1,"b":2}}, + {"age": 21, "is_student": false, "score": 85.5, "company": "A" ,"whatever": null}, + {"name": "Charlie", "age": 22, "is_student": true, "score": 95.5,"array":[1,2,3]} +]' +``` + +- `pipeline_name=greptime_identity` specifies the built-in pipeline. +- `table=pipeline_logs` specifies the target table. If the table does not exist, it will be created automatically. +The `greptime_identity` pipeline will automatically create columns for each field in the JSON log. A successful command execution will return: + +```json +{"output":[{"affectedrows":3}],"execution_time_ms":9} +``` + +For more details about the `greptime_identity` pipeline, please refer to the [Manage Pipelines](manage-pipelines.md#greptime_identity) document. + +### Write logs using a custom Pipeline + +If your logs follow a specific pattern, you can create a custom pipeline to parse and transform the log messages into multiple columns, and automatically create tables. + +#### Create a Pipeline + +GreptimeDB provides a dedicated HTTP interface for creating pipelines. Here's how to do it: + +First, create a pipeline file, for example, `pipeline.yaml`. + +```yaml +processors: + - dissect: + fields: + - message + patterns: + - '%{ip_address} - - [%{timestamp}] "%{http_method} %{request_line}" %{status_code} %{response_size} "-" "%{user_agent}"' + ignore_missing: true + - date: + fields: + - timestamp + formats: + - "%d/%b/%Y:%H:%M:%S %z" + +transform: + - fields: + - ip_address + - http_method + type: string + index: tag + - fields: + - status_code + type: int32 + index: tag + - fields: + - request_line + - user_agent + type: string + index: fulltext + - fields: + - response_size + type: int32 + - fields: + - timestamp + type: time + index: timestamp +``` + +The pipeline splits the message field using the specified pattern to extract the `ip_address`, `timestamp`, `http_method`, `request_line`, `status_code`, `response_size`, and `user_agent`. +It then parses the `timestamp` field using the format` %d/%b/%Y:%H:%M:%S %z` to convert it into a proper timestamp format that the database can understand. +Finally, it converts each field to the appropriate data type and indexes it accordingly. +It is worth noting that the `request_line` and `user_agent` fields are indexed as `fulltext` to optimize full-text search queries. And there must be one time index column specified by the `timestamp`. + +Execute the following command to upload the configuration file: + +```shell +curl -X "POST" "http://localhost:4000/v1/events/pipelines/nginx_pipeline" -F "file=@pipeline.yaml" +``` + +After successfully executing this command, a pipeline named `nginx_pipeline` will be created, and the result will be returned as: + +```json +{"name":"nginx_pipeline","version":"2024-06-27 12:02:34.257312110Z"}. +``` + +You can create multiple versions for the same pipeline name. +All pipelines are stored at the `greptime_private.pipelines` table. +Please refer to [Query Pipelines](manage-pipelines.md#query-pipelines) to view the pipeline data in the table. + +#### Write logs + +The following example writes logs to the `pipeline_logs` table and uses the `nginx_pipeline` pipeline to format and transform the log messages. + +```shell +curl -X "POST" "http://localhost:4000/v1/events/logs?db=public&table=pipeline_logs&pipeline_name=nginx_pipeline" \ + -H 'Content-Type: application/json' \ + -d $'[ +{"message":"127.0.0.1 - - [25/May/2024:20:16:37 +0000] \\"GET /index.html HTTP/1.1\\" 200 612 \\"-\\" \\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\\""}, +{"message":"192.168.1.1 - - [25/May/2024:20:17:37 +0000] \\"POST /api/login HTTP/1.1\\" 200 1784 \\"-\\" \\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36\\""}, +{"message":"10.0.0.1 - - [25/May/2024:20:18:37 +0000] \\"GET /images/logo.png HTTP/1.1\\" 304 0 \\"-\\" \\"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0\\""}, +{"message":"172.16.0.1 - - [25/May/2024:20:19:37 +0000] \\"GET /contact HTTP/1.1\\" 404 162 \\"-\\" \\"Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1\\""} +]' +``` + +You will see the following output if the command is successful: + +```json +{"output":[{"affectedrows":4}],"execution_time_ms":79} +``` + +## Differences between writing logs directly and using a pipeline + +In the above examples, the table `origin_logs` is created by writing logs directly, +and the table `pipeline_logs` is automatically created by writing logs using pipeline. +Let's explore the differences between these two tables. + +```sql +DESC origin_logs; +``` + +```sql ++---------+----------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++---------+----------------------+------+------+---------+---------------+ +| message | String | | YES | | FIELD | +| time | TimestampMillisecond | PRI | NO | | TIMESTAMP | ++---------+----------------------+------+------+---------+---------------+ +``` + +```sql +DESC pipeline_logs; +``` + +```sql ++---------------+---------------------+------+------+---------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++---------------+---------------------+------+------+---------+---------------+ +| ip_address | String | PRI | YES | | TAG | +| http_method | String | PRI | YES | | TAG | +| status_code | Int32 | PRI | YES | | TAG | +| request_line | String | | YES | | FIELD | +| user_agent | String | | YES | | FIELD | +| response_size | Int32 | | YES | | FIELD | +| timestamp | TimestampNanosecond | PRI | NO | | TIMESTAMP | ++---------------+---------------------+------+------+---------+---------------+ +7 rows in set (0.00 sec) +``` + +From the table structure, you can see that the `origin_logs` table has only two columns, +with the entire log message stored in a single column. +The `pipeline_logs` table stores the log message in multiple columns. + +It is recommended to use the pipeline method to split the log message into multiple columns, which offers the advantage of explicitly querying specific values within certain columns. Tag matching query proves superior to full-text searching for several key reasons: + +- **Performance Efficiency**: Tag matching query is typically faster than full-text searching. +- **Resource Consumption**: Due to GreptimeDB's columnar storage engine, structured data is more conducive to compression. Additionally, the inverted index used for tag matching query typically consumes significantly fewer resources than a full-text index, especially in terms of storage size. +- **Maintainability**: Tag matching query is straightforward and easier to understand, write, and debug. + +Of course, if you need keyword searching within large text blocks, you must use full-text searching as it is specifically designed for that purpose. + +## Query logs + +We use the `pipeline_logs` table as an example to query logs. + +### Query logs by tags + +With the multiple tag columns in `pipeline_logs`, +you can query data by tags flexibly. +For example, query the logs with `status_code` 200 and `http_method` GET. + +```sql +SELECT * FROM pipeline_logs WHERE status_code = 200 AND http_method = 'GET'; +``` + +```sql ++------------+-------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +| ip_address | http_method | status_code | request_line | user_agent | response_size | timestamp | ++------------+-------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +| 127.0.0.1 | GET | 200 | /index.html HTTP/1.1 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 | 612 | 2024-05-25 20:16:37 | ++------------+-------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +1 row in set (0.02 sec) +``` + +### Full-Text Search + +For the text fields `request_line` and `user_agent`, you can use the `MATCHES` function to search logs. +Remember, we created the full-text index for these two columns when [creating a pipeline](#create-a-pipeline). \ +This allows for high-performance full-text searches. + +For example, query the logs with `request_line` containing `/index.html` or `/api/login`. + +```sql +SELECT * FROM pipeline_logs WHERE MATCHES(request_line, 'index.html /api/login'); +``` + +```sql ++-------------+-------------+-------------+----------------------+--------------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +| ip_address | http_method | status_code | request_line | user_agent | response_size | timestamp | ++-------------+-------------+-------------+----------------------+--------------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +| 127.0.0.1 | GET | 200 | /index.html HTTP/1.1 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 | 612 | 2024-05-25 20:16:37 | +| 192.168.1.1 | POST | 200 | /api/login HTTP/1.1 | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36 | 1784 | 2024-05-25 20:17:37 | ++-------------+-------------+-------------+----------------------+--------------------------------------------------------------------------------------------------------------------------+---------------+---------------------+ +2 rows in set (0.00 sec) +``` + +You can refer to the [Full-Text Search](query-logs.md#full-text-search-using-the-matches-function) document for detailed usage of the `MATCHES` function. + +## Next steps + +You have now experienced GreptimeDB's logging capabilities. +You can explore further by following the documentation below: + +- [Pipeline Configuration](./pipeline-config.md): Provides in-depth information on each specific configuration of pipelines in GreptimeDB. +- [Managing Pipelines](./manage-pipelines.md): Explains how to create and delete pipelines. +- [Writing Logs with Pipelines](./write-logs.md): Provides detailed instructions on efficiently writing log data by leveraging the pipeline mechanism. +- [Query Logs](./query-logs.md): Describes how to query logs using the GreptimeDB SQL interface. diff --git a/versioned_docs/version-0.11/user-guide/logs/write-logs.md b/versioned_docs/version-0.11/user-guide/logs/write-logs.md new file mode 100644 index 000000000..d5d49adcd --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/logs/write-logs.md @@ -0,0 +1,111 @@ +--- +description: Describes how to write logs to GreptimeDB using a pipeline via the HTTP interface, including supported formats and request parameters. +--- + +# Writing Logs Using a Pipeline + +This document describes how to write logs to GreptimeDB by processing them through a specified pipeline using the HTTP interface. + +Before writing logs, please read the [Pipeline Configuration](pipeline-config.md) and [Managing Pipelines](manage-pipelines.md) documents to complete the configuration setup and upload. + +## HTTP API + +You can use the following command to write logs via the HTTP interface: + +```shell +curl -X "POST" "http://localhost:4000/v1/events/logs?db=&table=&pipeline_name=&version=" \ + -H 'Content-Type: application/json' \ + -d "$" +``` + +## Request parameters + +This interface accepts the following parameters: + +- `db`: The name of the database. +- `table`: The name of the table. +- `pipeline_name`: The name of the [pipeline](./pipeline-config.md). +- `version`: The version of the pipeline. Optional, default use the latest one. + +## `Content-Type` and body format + +GreptimeDB uses `Content-Type` header to decide how to decode the payload body. Currently the following two format is supported: +- `application/json`: this includes normal JSON format and NDJSON format. +- `text/plain`: multiple log lines separated by line breaks. + +### `application/json` format + +Here is an example of JSON format body payload + +```JSON +[ + {"message":"127.0.0.1 - - [25/May/2024:20:16:37 +0000] \"GET /index.html HTTP/1.1\" 200 612 \"-\" \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\""}, + {"message":"192.168.1.1 - - [25/May/2024:20:17:37 +0000] \"POST /api/login HTTP/1.1\" 200 1784 \"-\" \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36\""}, + {"message":"10.0.0.1 - - [25/May/2024:20:18:37 +0000] \"GET /images/logo.png HTTP/1.1\" 304 0 \"-\" \"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0\""}, + {"message":"172.16.0.1 - - [25/May/2024:20:19:37 +0000] \"GET /contact HTTP/1.1\" 404 162 \"-\" \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1\""} +] +``` + +Note the whole JSON is an array (log lines). Each JSON object represents one line to be processed by Pipeline engine. + +The name of the key in JSON objects, which is `message` here, is used as field name in Pipeline processors. For example: + +```yaml +processors: + - dissect: + fields: + # `message` is the key in JSON object + - message + patterns: + - '%{ip_address} - - [%{timestamp}] "%{http_method} %{request_line}" %{status_code} %{response_size} "-" "%{user_agent}"' + ignore_missing: true + +# rest of the file is ignored +``` + +We can also rewrite the payload into NDJSON format like following: + +```JSON +{"message":"127.0.0.1 - - [25/May/2024:20:16:37 +0000] \"GET /index.html HTTP/1.1\" 200 612 \"-\" \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\""} +{"message":"192.168.1.1 - - [25/May/2024:20:17:37 +0000] \"POST /api/login HTTP/1.1\" 200 1784 \"-\" \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36\""} +{"message":"10.0.0.1 - - [25/May/2024:20:18:37 +0000] \"GET /images/logo.png HTTP/1.1\" 304 0 \"-\" \"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0\""} +{"message":"172.16.0.1 - - [25/May/2024:20:19:37 +0000] \"GET /contact HTTP/1.1\" 404 162 \"-\" \"Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1\""} +``` + +Note the outer array is eliminated, and lines are separated by line breaks instead of `,`. + +### `text/plain` format + +Log in plain text format is widely used throughout the ecosystem. GreptimeDB also supports `text/plain` format as log data input, enabling ingesting logs first hand from log producers. + +The equivalent body payload of previous example is like following: + +```plain +127.0.0.1 - - [25/May/2024:20:16:37 +0000] "GET /index.html HTTP/1.1" 200 612 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" +192.168.1.1 - - [25/May/2024:20:17:37 +0000] "POST /api/login HTTP/1.1" 200 1784 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.96 Safari/537.36" +10.0.0.1 - - [25/May/2024:20:18:37 +0000] "GET /images/logo.png HTTP/1.1" 304 0 "-" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0" +172.16.0.1 - - [25/May/2024:20:19:37 +0000] "GET /contact HTTP/1.1" 404 162 "-" "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1" +``` + +Sending log ingestion request to GreptimeDB requires only modifying the `Content-Type` header to be `text/plain`, and you are good to go! + +Please note that, unlike JSON format, where the input data already have key names as field names to be used in Pipeline processors, `text/plain` format just gives the whole line as input to the Pipeline engine. In this case we use `line` as the field name to refer to the input line, for example: + +```yaml +processors: + - dissect: + fields: + # use `line` as the field name + - line + patterns: + - '%{ip_address} - - [%{timestamp}] "%{http_method} %{request_line}" %{status_code} %{response_size} "-" "%{user_agent}"' + ignore_missing: true + +# rest of the file is ignored +``` + +It is recommended to use `dissect` or `regex` processor to split the input line into fields first and then process the fields accordingly. + +## Example + +Please refer to the "Writing Logs" section in the [Quick Start](quick-start.md#write-logs) guide for an example. \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/manage-data/overview.md b/versioned_docs/version-0.11/user-guide/manage-data/overview.md new file mode 100644 index 000000000..37504116a --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/manage-data/overview.md @@ -0,0 +1,336 @@ +--- +description: Provides an overview of managing data in GreptimeDB, including updating, deleting, truncating tables, and managing data retention with TTL policies. +--- + +# Overview + +## Update data + +### Update data with same tags and time index + +Updates can be efficiently performed by inserting new data. +If rows of data have the same tags and time index, +the old data will be replaced with the new data. +This means that you can only update columns with a field type. +To update data, simply insert new data with the same tag and time index as the existing data. + +For more information about column types, please refer to the [Data Model](../concepts/data-model.md). + +:::warning Note +Excessive updates may negatively impact query performance, even though the performance of updates is the same as insertion. +::: + +#### Update all fields in a table + +By default, when updating data, all fields will be overwritten with the new values, +except for [InfluxDB line protocol](/user-guide/protocols/influxdb-line-protocol.md), which only [updates the specified fields](#overwrite-specific-fields-in-a-table). +The following example using SQL demonstrates the behavior of overwriting all fields in a table. + +Assuming you have a table named `monitor` with the following schema. +The `host` column represents the tag and the `ts` column represents the time index. + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64, + memory FLOAT64, + PRIMARY KEY(host) +); +``` + +Insert a new row into the `monitor` table: + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.8, 0.1); +``` + +Check the data in the table: + +```sql +SELECT * FROM monitor; +``` + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:00 | 0.8 | 0.1 | ++-----------+---------------------+------+--------+ +1 row in set (0.00 sec) +``` + +To update the data, you can use the same `host` and `ts` values as the existing data and set the new `cpu` value to `0.5`: + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +-- The same tag `127.0.0.1` and the same time index 2024-07-11 20:00:00 +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.5, 0.1); +``` + +The new data will be: + +```sql +SELECT * FROM monitor; +``` + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +1 row in set (0.01 sec) +``` + +With the default merge policy, +if columns are omitted in the `INSERT INTO` statement, +they will be overwritten with the default values. + +For example: + +```sql +INSERT INTO monitor (host, ts, cpu) +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.5); +``` + +The default value of the `memory` column in the `monitor` table is `NULL`. Therefore, the new data will be: + +```sql +SELECT * FROM monitor; +``` + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:00 | 0.5 | NULL | ++-----------+---------------------+------+--------+ +1 row in set (0.01 sec) +``` + +### Update specific fields in a table + +This update policy is supported by default in the [InfluxDB line protocol](/user-guide/protocols/influxdb-line-protocol.md). +You can also enable this behavior by specifying the `merge_mode` option as `last_non_null` when creating a table using SQL. +Here's an example: + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64, + memory FLOAT64, + PRIMARY KEY(host) +) WITH ('merge_mode'='last_non_null'); +``` + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.8, 0.1); +``` + +To update specific fields in the `monitor` table, +you can insert new data with only the fields you want to update. +For example: + +```sql +INSERT INTO monitor (host, ts, cpu) +VALUES ("127.0.0.1", "2024-07-11 20:00:00", 0.5); +``` + +This will update the `cpu` field while leaving the `memory` field unchanged. +The result will be: + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` + + +Notice that the `last_non_null` merge mode cannot update the old value to `NULL`. +For example: + + +```sql +INSERT INTO monitor (host, ts, cpu, memory) +VALUES ("127.0.0.1", "2024-07-11 20:00:01", 0.8, 0.1); +``` + +```sql +INSERT INTO monitor (host, ts, cpu) +VALUES ("127.0.0.1", "2024-07-11 20:00:01", NULL); +``` + +That will not update anything: + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-07-11 20:00:01 | 0.8 | 0.1 | ++-----------+---------------------+------+--------+ +``` + +For more information about the `merge_mode` option, please refer to the [CREATE TABLE](/reference/sql/create.md##create-a-table-with-merge-mode) statement. + +### Avoid updating data by creating table with `append_mode` option + +GreptimeDB supports an `append_mode` option when creating a table, +which always inserts new data to the table. +This is especially useful when you want to keep all historical data, such as logs. + +You can only create a table with the `append_mode` option using SQL. +After successfully creating the table, +all protocols [ingest data](/user-guide/ingest-data/overview.md) to the table will always insert new data. + +For example, you can create an `app_logs` table with the `append_mode` option as follows. +The `host` and `log_level` columns represent tags, and the `ts` column represents the time index. + +```sql +CREATE TABLE app_logs ( + ts TIMESTAMP TIME INDEX, + host STRING, + api_path STRING FULLTEXT, + log_level STRING, + log STRING FULLTEXT, + PRIMARY KEY (host, log_level) +) WITH ('append_mode'='true'); +``` + +Insert a new row into the `app_logs` table: + +```sql +INSERT INTO app_logs (ts, host, api_path, log_level, log) +VALUES ('2024-07-11 20:00:10', 'host1', '/api/v1/resource', 'ERROR', 'Connection timeout'); +``` + +Check the data in the table: + +```sql +SELECT * FROM app_logs; +``` + +The output will be: + +```sql ++---------------------+-------+------------------+-----------+--------------------+ +| ts | host | api_path | log_level | log | ++---------------------+-------+------------------+-----------+--------------------+ +| 2024-07-11 20:00:10 | host1 | /api/v1/resource | ERROR | Connection timeout | ++---------------------+-------+------------------+-----------+--------------------+ +1 row in set (0.01 sec) +``` + +You can insert new data with the same tag and time index: + +```sql +INSERT INTO app_logs (ts, host, api_path, log_level, log) +-- The same tag `host1` and `ERROR`, the same time index 2024-07-11 20:00:10 +VALUES ('2024-07-11 20:00:10', 'host1', '/api/v1/resource', 'ERROR', 'Connection reset'); +``` + +Then you will find two rows in the table: + +```sql +SELECT * FROM app_logs; +``` + +```sql ++---------------------+-------+------------------+-----------+--------------------+ +| ts | host | api_path | log_level | log | ++---------------------+-------+------------------+-----------+--------------------+ +| 2024-07-11 20:00:10 | host1 | /api/v1/resource | ERROR | Connection reset | +| 2024-07-11 20:00:10 | host1 | /api/v1/resource | ERROR | Connection timeout | ++---------------------+-------+------------------+-----------+--------------------+ +2 rows in set (0.01 sec) +``` + +## Delete Data + +You can effectively delete data by specifying tags and time index. +Deleting data without specifying the tag and time index columns is not efficient, as it requires two steps: querying the data and then deleting it by tag and time index. +For more information about column types, please refer to the [Data Model](../concepts/data-model.md). + +:::warning Warning +Excessive deletions can negatively impact query performance. +::: + +You can only delete data using SQL. +For example, to delete a row from the `monitor` table with tag `host` and timestamp index `ts`: + +```sql +DELETE FROM monitor WHERE host='127.0.0.2' AND ts=1667446798450; +``` + +The output will be: + +```sql +Query OK, 1 row affected (0.00 sec) +``` + +For more information about the `DELETE` statement, please refer to the [SQL DELETE](/reference/sql/delete.md). + +## Truncate Table + +To delete all data in a table, you can use the `TRUNCATE TABLE` statement in SQL. +For example, to truncate the `monitor` table: + +```sql +TRUNCATE TABLE monitor; +``` + +For more information about the `TRUNCATE TABLE` statement, refer to the [SQL TRUNCATE TABLE](/reference/sql/truncate.md) documentation. + +## Manage data retention with TTL policies + +You can use Time to Live (TTL) policies to automatically remove stale data from your databases. TTL allows you to set policies to periodically delete data from tables. Setting TTL policies has the following benefits: + +- Decrease storage costs by cleaning out obsolete data. +- Reduce the number of rows the database has to scan for some queries, potentially increasing query performance. + +You can set TTL for every table when creating it. For example, the following SQL statement creates a table named `monitor` with a TTL policy of 7 days: + +```sql +CREATE TABLE monitor ( + host STRING, + ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP() TIME INDEX, + cpu FLOAT64, + memory FLOAT64, + PRIMARY KEY(host) +) WITH ('ttl'='7d'); +``` + +You can also create a database-level TTL policy. For example, the following SQL statement creates a database named `test` with a TTL policy of 7 days: + +```sql +CREATE DATABASE test WITH ('ttl'='7d'); +``` + +You can set TTL policies at both the table level and the database level simultaneously. +If a table has its own TTL policy, +it will take precedence over the database TTL policy. +Otherwise, the database TTL policy will be applied to the table. + +The value of `'ttl'` can be one of duration (like `1hour 12min 5s`), `instant` or `forever`. See details in [CREATE](/reference/sql/create.md#create-a-table-with-ttl) statement. + +If you want to remove the TTL policy, you can use the following SQL + +```sql +-- for table +ALTER TABLE monitor UNSET 'ttl'; +-- or for database +ALTER DATABASE test UNSET 'ttl'; +``` + +For more information about TTL policies, please refer to the [CREATE](/reference/sql/create.md) statement. + + +## More data management operations + +For more advanced data management operations, such as basic table operations, table sharding and region migration, please refer to the [Data Management](/user-guide/administration/manage-data/overview.md) in the administration section. + diff --git a/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md b/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md new file mode 100644 index 000000000..ef50ea921 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md @@ -0,0 +1,191 @@ +--- +description: Instructions on migrating from InfluxDB to GreptimeDB, including writing data using HTTP API, Telegraf, and client libraries. +--- + +import DocTemplate from '../../db-cloud-shared/migrate/migrate-from-influxdb.md' + +# Migrate from InfluxDB + + + +
+ + + + +```shell +curl -X POST 'http://:4000/v1/influxdb/api/v2/write?db=' \ + -H 'authorization: token ' \ + -d 'census,location=klamath,scientist=anderson bees=23 1566086400000000000' +``` + + + + + +```shell +curl 'http://:4000/v1/influxdb/write?db=&u=&p=' \ + -d 'census,location=klamath,scientist=anderson bees=23 1566086400000000000' +``` + + + + + +
+ +
+ +For detailed configuration instructions, please refer to the [Ingest Data via Telegraf](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md#telegraf) documentation. + +
+ + +
+ + + + +```js [Node.js] +'use strict' +/** @module write +**/ + +import { InfluxDB, Point } from '@influxdata/influxdb-client' + +/** Environment variables **/ +const url = 'http://:4000/v1/influxdb' +const token = ':' +const org = '' +const bucket = '' + +const influxDB = new InfluxDB({ url, token }) +const writeApi = influxDB.getWriteApi(org, bucket) +writeApi.useDefaultTags({ region: 'west' }) +const point1 = new Point('temperature') + .tag('sensor_id', 'TLM01') + .floatField('value', 24.0) +writeApi.writePoint(point1) + +``` + + + + + +```python +import influxdb_client +from influxdb_client.client.write_api import SYNCHRONOUS + +bucket = "" +org = "" +token = ":" +url="http://:4000/v1/influxdb" + +client = influxdb_client.InfluxDBClient( + url=url, + token=token, + org=org +) + +# Write script +write_api = client.write_api(write_options=SYNCHRONOUS) + +p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3) +write_api.write(bucket=bucket, org=org, record=p) + +``` + + + + + +```go +bucket := "" +org := "" +token := ":" +url := "http://:4000/v1/influxdb" +client := influxdb2.NewClient(url, token) +writeAPI := client.WriteAPIBlocking(org, bucket) + +p := influxdb2.NewPoint("stat", + map[string]string{"unit": "temperature"}, + map[string]interface{}{"avg": 24.5, "max": 45}, + time.Now()) +writeAPI.WritePoint(context.Background(), p) +client.Close() + +``` + + + + + +```java +private static String url = "http://:4000/v1/influxdb"; +private static String org = ""; +private static String bucket = ""; +private static char[] token = ":".toCharArray(); + +public static void main(final String[] args) { + + InfluxDBClient influxDBClient = InfluxDBClientFactory.create(url, token, org, bucket); + WriteApiBlocking writeApi = influxDBClient.getWriteApiBlocking(); + Point point = Point.measurement("temperature") + .addTag("location", "west") + .addField("value", 55D) + .time(Instant.now().toEpochMilli(), WritePrecision.MS); + + writeApi.writePoint(point); + influxDBClient.close(); +} +``` + + + + + +```php +$client = new Client([ + "url" => "http://:4000/v1/influxdb", + "token" => ":", + "bucket" => "", + "org" => "", + "precision" => InfluxDB2\Model\WritePrecision::S +]); + +$writeApi = $client->createWriteApi(); + +$dateTimeNow = new DateTime('NOW'); +$point = Point::measurement("weather") + ->addTag("location", "Denver") + ->addField("temperature", rand(0, 20)) + ->time($dateTimeNow->getTimestamp()); +$writeApi->write($point); +``` + + + + + +
+ +
+It is recommended using Grafana to visualize data in GreptimeDB. +Please refer to the [Grafana documentation](/user-guide/integrations/grafana.md) for details on configuring GreptimeDB. +
+ +
+ +```shell +for file in data.*; do + curl -i --retry 3 \ + -X POST "http://${GREPTIME_HOST}:4000/v1/influxdb/write?db=${GREPTIME_DB}&u=${GREPTIME_USERNAME}&p=${GREPTIME_PASSWORD}" \ + --data-binary @${file} + sleep 1 +done +``` + +
+ + diff --git a/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-mysql.md b/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-mysql.md new file mode 100644 index 000000000..b79d8f3e9 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-mysql.md @@ -0,0 +1,100 @@ +--- +description: Step-by-step guide on migrating from MySQL to GreptimeDB, including creating databases, writing data, exporting and importing data. +--- + +# Migrate from MySQL + +This document will guide you through the migration process from MySQL to GreptimeDB. + +## Before you start the migration + +Please be aware that though GreptimeDB supports the wire protocol of MySQL, it does not mean GreptimeDB implements all +MySQL's features. You may refer to the "[ANSI Compatibility](/reference/sql/compatibility.md)" to see the +constraints regarding using SQL in GreptimeDB. + +## Migration steps + +### Create the databases and tables in GreptimeDB + +Before migrating the data from MySQL, you first need to create the corresponding databases and tables in GreptimeDB. +GreptimeDB has its own SQL syntax for creating tables, so you cannot directly reuse the table creation SQLs that are produced +by MySQL. + +When you write the table creation SQL for GreptimeDB, it's important to understand +its "[data model](/user-guide/concepts/data-model.md)" first. Then, please take the following considerations in +your create table SQL: + +1. Since the time index column cannot be changed after the table is created, you need to choose the time index column + carefully. The time index is best set to the natural timestamp when the data is generated, as it provides the most + intuitive way to query the data, and the best query performance. For example, in the IOT scenes, you can use the + collection time of sensor data as the time index; or the occurrence time of an event in the observability scenes. +2. In this migration process, it's not recommend to create another synthetic timestamp, such as a new column created + with `DEFAULT current_timestamp()` as the time index column. It's not recommend to use the random timestamp as the + time index either. +3. It's vital to set the most fit timestamp precision for your time index column, too. Like the chosen of time index + column, the precision of it cannot be changed as well. Find the most fit timestamp type for your + data set [here](/reference/sql/data-types#data-types-compatible-with-mysql-and-postgresql). +4. Choose the most fit tag columns based on your query patterns. The tag columns store the metadata that is + commonly queried. The values in the tag columns are labels attached to the collected sources, generally used to + describe a particular characteristic of these sources. The tag columns are indexed, making queries on them + performant. + +Finally please refer to "[CREATE](/reference/sql/create.md)" SQL document for more details for choosing the +right data types and "ttl" or "compaction" options, etc. + +### Write data to both GreptimeDB and MySQL simultaneously + +Writing data to both GreptimeDB and MySQL simultaneously is a practical strategy to avoid data loss during migration. By +utilizing MySQL's client libraries (JDBC + a MySQL driver), you can set up two client instances - one for GreptimeDB +and another for MySQL. For guidance on writing data to GreptimeDB using SQL, please refer to the [Ingest Data](/user-guide/ingest-data/for-iot/sql.md) section. + +If retaining all historical data isn't necessary, you can simultaneously write data to both GreptimeDB and MySQL for a +specific period to accumulate the required recent data. Subsequently, cease writing to MySQL and continue exclusively +with GreptimeDB. If a complete migration of all historical data is needed, please proceed with the following steps. + +### Export data from MySQL + +[mysqldump](https://dev.mysql.com/doc/refman/8.4/en/mysqldump.html) is a commonly used tool to export data from MySQL. +Using it, we can export the data that can be later imported into GreptimeDB directly. For example, if we want to export +two databases, `db1` and `db2` from MySQL, we can use the following command: + +```bash +mysqldump -h127.0.0.1 -P3306 -umysql_user -p --compact -cnt --skip-extended-insert --databases db1 db2 > /path/to/output.sql +``` + +Replace the `-h`, `-P` and `-u` flags with the appropriate values for your MySQL server. The `--databases` flag is used +to specify the databases to be exported. The output will be written to the `/path/to/output.sql` file. + +The content in the `/path/to/output.sql` file should be like this: + +```plaintext +~ ❯ cat /path/to/output.sql + +USE `db1`; +INSERT INTO `foo` (`ts`, `a`, `b`) VALUES (1,'hello',1); +INSERT INTO ... + +USE `db2`; +INSERT INTO `foo` (`ts`, `a`, `b`) VALUES (2,'greptime',2); +INSERT INTO ... +``` + +### Import data into GreptimeDB + +The [MySQL Command-Line Client](https://dev.mysql.com/doc/refman/8.4/en/mysql.html) can be used to import data into +GreptimeDB. Continuing the above example, say the data is exported to file `/path/to/output.sql`, then we can use the +following command to import the data into GreptimeDB: + +```bash +mysql -h127.0.0.1 -P4002 -ugreptime_user -p -e "source /path/to/output.sql" +``` + +Replace the `-h`, `-P` and `-u` flags with the appropriate values for your GreptimeDB server. The `source` command is +used to execute the SQL commands in the `/path/to/output.sql` file. Add `-vvv` to see the detailed execution results for +debugging purpose. + +To summarize, data migration steps can be illustrate as follows: + +![migrate mysql data steps](/migration-mysql.jpg) + +After the data migration is completed, you can stop writing data to MySQL and continue using GreptimeDB exclusively! diff --git a/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-postgresql.md b/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-postgresql.md new file mode 100644 index 000000000..29b61e67d --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-postgresql.md @@ -0,0 +1,132 @@ +--- +description: Step-by-step guide on migrating from PostgreSQL to GreptimeDB, including creating databases, writing data, exporting and importing data. +--- + +# Migrate from PostgreSQL + +This document will guide you through the migration process from PostgreSQL to GreptimeDB. + +## Before you start the migration + +Please be aware that though GreptimeDB supports the wire protocol of PostgreSQL, it does not mean GreptimeDB implements +all +PostgreSQL's features. You may refer to the "[ANSI Compatibility](/reference/sql/compatibility.md)" to see the +constraints regarding using SQL in GreptimeDB. + +## Migration steps + +### Create the databases and tables in GreptimeDB + +Before migrating the data from PostgreSQL, you first need to create the corresponding databases and tables in +GreptimeDB. +GreptimeDB has its own SQL syntax for creating tables, so you cannot directly reuse the table creation SQLs that are +produced +by PostgreSQL. + +When you write the table creation SQL for GreptimeDB, it's important to understand +its "[data model](/user-guide/concepts/data-model.md)" first. Then, please take the following considerations in +your create table SQL: + +1. Since the time index column cannot be changed after the table is created, you need to choose the time index column + carefully. The time index is best set to the natural timestamp when the data is generated, as it provides the most + intuitive way to query the data, and the best query performance. For example, in the IOT scenes, you can use the + collection time of sensor data as the time index; or the occurrence time of an event in the observability scenes. +2. In this migration process, it's not recommend to create another synthetic timestamp, such as a new column created + with `DEFAULT current_timestamp()` as the time index column. It's not recommend to use the random timestamp as the + time index either. +3. It's vital to set the most fit timestamp precision for your time index column, too. Like the chosen of time index + column, the precision of it cannot be changed as well. Find the most fit timestamp type for your + data set [here](/reference/sql/data-types#data-types-compatible-with-mysql-and-postgresql). +4. Choose the most fit tag columns based on your query patterns. The tag columns store the metadata that is + commonly queried. The values in the tag columns are labels attached to the collected sources, generally used to + describe a particular characteristic of these sources. The tag columns are indexed, making queries on them + performant. + +Finally please refer to "[CREATE](/reference/sql/create.md)" SQL document for more details for choosing the +right data types and "ttl" or "compaction" options, etc. + +### Write data to both GreptimeDB and PostgreSQL simultaneously + +Writing data to both GreptimeDB and PostgreSQL simultaneously is a practical strategy to avoid data loss during +migration. By utilizing PostgreSQL's client libraries (JDBC + a PostgreSQL driver), you can set up two client +instances - one for GreptimeDB and another for PostgreSQL. For guidance on writing data to GreptimeDB using SQL, please +refer to the [Ingest Data](/user-guide/ingest-data/for-iot/sql.md) section. + +If retaining all historical data isn't necessary, you can simultaneously write data to both GreptimeDB and PostgreSQL +for a specific period to accumulate the required recent data. Subsequently, cease writing to PostgreSQL and continue +exclusively with GreptimeDB. If a complete migration of all historical data is needed, please proceed with the following +steps. + +### Export data from PostgreSQL + +[pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html) is a commonly used tool to export data from +PostgreSQL. Using it, we can export the data that can be later imported into GreptimeDB directly. For example, if we +want to export schemas whose names start with `db` in the database `postgres` from PostgreSQL, we can use the following +command: + +```bash +pg_dump -h127.0.0.1 -p5432 -Upostgres -ax --column-inserts --no-comments -n 'db*' postgres | grep -v "^SE" > /path/to/output.sql +``` + +Replace the `-h`, `-p` and `-U` flags with the appropriate values for your PostgreSQL server. The `-n` flag is used to +specify the schemas to be exported. And the database `postgres` is at the end of the `pg_dump` command line. Note that we pipe the `pg_dump` output through a special +`grep`, to remove some unnecessary `SET` or `SELECT` lines. The final output will be written to the +`/path/to/output.sql` file. + +The content in the `/path/to/output.sql` file should be like this: + +```plaintext +~ ❯ cat /path/to/output.sql + +-- +-- PostgreSQL database dump +-- + +-- Dumped from database version 16.4 (Debian 16.4-1.pgdg120+1) +-- Dumped by pg_dump version 16.4 + + +-- +-- Data for Name: foo; Type: TABLE DATA; Schema: db1; Owner: postgres +-- + +INSERT INTO db1.foo (ts, a) VALUES ('2024-10-31 00:00:00', 1); +INSERT INTO db1.foo (ts, a) VALUES ('2024-10-31 00:00:01', 2); +INSERT INTO db1.foo (ts, a) VALUES ('2024-10-31 00:00:01', 3); +INSERT INTO ... + + +-- +-- Data for Name: foo; Type: TABLE DATA; Schema: db2; Owner: postgres +-- + +INSERT INTO db2.foo (ts, b) VALUES ('2024-10-31 00:00:00', '1'); +INSERT INTO db2.foo (ts, b) VALUES ('2024-10-31 00:00:01', '2'); +INSERT INTO db2.foo (ts, b) VALUES ('2024-10-31 00:00:01', '3'); +INSERT INTO ... + + +-- +-- PostgreSQL database dump complete +-- +``` + +### Import data into GreptimeDB + +The [psql -- PostgreSQL interactive terminal](https://www.postgresql.org/docs/current/app-psql.html) can be used to +import data into GreptimeDB. Continuing the above example, say the data is exported to file `/path/to/output.sql`, then +we can use the following command to import the data into GreptimeDB: + +```bash +psql -h127.0.0.1 -p4003 -d public -f /path/to/output.sql +``` + +Replace the `-h` and `-p` flags with the appropriate values for your GreptimeDB server. The `-d` of the psql command is used to specify the database and cannot be omitted. The value `public` of `-d` is the default database used by GreptimeDB. You can also add `-a` to the end to see every +executed line, or `-s` for entering the single-step mode. + +To summarize, data migration steps can be illustrate as follows: + +![migrate postgresql data steps](/migration-postgresql.jpg) + +After the data migration is completed, you can stop writing data to PostgreSQL and continue using GreptimeDB +exclusively! diff --git a/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-prometheus.md b/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-prometheus.md new file mode 100644 index 000000000..51ecb31cc --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/migrate-to-greptimedb/migrate-from-prometheus.md @@ -0,0 +1,30 @@ +--- +description: Instructions on migrating from Prometheus to GreptimeDB, including remote write configuration, PromQL queries, and Grafana integration. +--- + +import DocTemplate from '../../db-cloud-shared/migrate/_migrate-from-prometheus.md' + +# Migrate from Prometheus + + + +
+ +For information on configuring Prometheus to write data to GreptimeDB, please refer to the [remote write](/user-guide/ingest-data/for-observerbility/prometheus.md#remote-write-configuration) documentation. + +
+ +
+ +For detailed information on querying data in GreptimeDB using Prometheus query language, please refer to the [HTTP API](/user-guide/query-data/promql.md#prometheus-http-api) section in the PromQL documentation. + +
+ +
+ +To add GreptimeDB as a Prometheus data source in Grafana, please refer to the [Grafana](/user-guide/integrations/grafana.md#prometheus-data-source) documentation. + +
+ + + diff --git a/versioned_docs/version-0.11/user-guide/overview.md b/versioned_docs/version-0.11/user-guide/overview.md new file mode 100644 index 000000000..12c62e12c --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/overview.md @@ -0,0 +1,74 @@ +--- +description: Introduction to GreptimeDB's features, including unified storage for metrics, logs, and events, SQL and multiple protocol support, and range queries. +--- + +# Overview + +Welcome to the user guide for GreptimeDB. + +GreptimeDB is the unified time series database for metrics, logs, and events, +providing real-time insights from Edge to Cloud at any scale. +This guide will help you explore each powerful feature of GreptimeDB. + +## SQL query example + +Let's start with a SQL query example. + +To monitor the performance and reliability of specific metrics, +engineers commonly analyze data over time at regular intervals using queries. +This often involves joining two data sources. +However, executing a query like the one below was previously impossible, +which is now possible with GreptimeDB. + +```sql +SELECT + host, + approx_percentile_cont(latency, 0.95) RANGE '15s' as p95_latency, + count(error) RANGE '15s' as num_errors, +FROM + metrics INNER JOIN logs on metrics.host = logs.host +WHERE + time > now() - INTERVAL '1 hour' AND + matches(path, '/api/v1/avatar') +ALIGN '5s' BY (host) FILL PREV +``` + +This query analyzes the performance and errors of a specific API path (`/api/v1/avatar`) over the past hour. +It calculates the 95th percentile latency and the number of errors in 15-second intervals and aligns the results to 5-second intervals for continuity and readability. + +Break down the query step by step: + +1. SELECT clause: + - `host`: Selects the host field. + - `approx_percentile_cont(latency, 0.95) RANGE '15s' as p95_latency`: Calculates the 95th percentile of latency within a 15-second range and labels it as p95_latency. + - `count(error) RANGE '15s' as num_errors`: Counts the number of errors within a 15-second range and labels it as num_errors. +2. FROM clause: + - `metrics INNER JOIN logs on metrics.host = logs.host`: Joins the metrics and logs tables on the host field. +3. WHERE clause: + - `time > now() - INTERVAL '1 hour'`: Filters the records to include only those from the past hour. + - `matches(path, '/api/v1/avatar')`: Filters the records to include only those matching the path `/api/v1/avatar`. +4. ALIGN clause: + - `ALIGN '5s' BY (host) FILL PREV`: Aligns the results to every 5 seconds and fills in missing values with the previous non-null value. + +Next, let's analyze the key features of GreptimeDB demonstrated by this query example: + +- **Unified Storage:** GreptimeDB is the time series database to store and analyze both metrics and [logs](/user-guide/logs/overview.md). The simplified architecture and data consistency enhances the ability to analyze and troubleshoot issues, and can lead to cost savings and improved system performance. +- **Unique Data Model:** The unique [data model](/user-guide/concepts/data-model.md) with time index and full-text index greatly improves query performance and has stood the test of large data sets. It not only supports metric [insertion](/user-guide/ingest-data/overview.md) and [query](/user-guide/query-data/overview.md), but also provides a very friendly way to [write](/user-guide/logs/write-logs.md) and [query](/user-guide/logs/query-logs.md) logs, as well as handle [vector type data](/user-guide/vectors/vector-type.md). +- **Range Queries:** GreptimeDB supports [range queries](/user-guide/query-data/sql.md#aggregate-data-by-time-window) to evaluate [expressions](/reference/sql/functions/overview.md) over time, providing insights into metric trends. You can also [continuously aggregate](/user-guide/continuous-aggregation/overview.md) data for further analysis. +- **SQL and Multiple Protocols:** GreptimeDB uses SQL as the main query language and supports [multiple protocols](/user-guide/protocols/overview.md), which greatly reduces the learning curve and development cost. You can easily migrate from Prometheus or [Influxdb to GreptimeDB](/user-guide/migrate-to-greptimedb/migrate-from-influxdb.md), or just start with GreptimeDB. +- **JOIN Operations:** The data model of GreptimeDB's time series tables enables it to support [JOIN operations](/reference/sql/join.md) on metrics and logs. + +Having understood these features, you can now go directly to exploring the features that interest you, or continue reading the next step in the sequence. + +## Next steps + +* [Concepts](./concepts/overview.md) +* [Migrate to GreptimeDB](./migrate-to-greptimedb/migrate-from-influxdb.md) +* [Ingest Data](./ingest-data/overview.md) +* [Query Data](./query-data/overview.md) +* [Manage Data](./manage-data/overview.md) +* [Integrations](./integrations/overview.md) +* [Protocols](./protocols/overview.md) +* [Continuous Aggregation](./continuous-aggregation/overview.md) +* [Operations](./administration/overview.md) + diff --git a/versioned_docs/version-0.11/user-guide/protocols/grpc.md b/versioned_docs/version-0.11/user-guide/protocols/grpc.md new file mode 100644 index 000000000..a1a0e4883 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/protocols/grpc.md @@ -0,0 +1,9 @@ +--- +description: Overview of using gRPC SDKs for efficient and high-performance data ingestion in GreptimeDB. +--- + +# gRPC + +GreptimeDB offers [gRPC SDKs](/user-guide/ingest-data/for-iot/grpc-sdks/overview.md) for efficient and high-performance data ingestion. + +If there is no SDK available for your programming language, you have the option to [create your own SDK](/contributor-guide/how-to/how-to-write-sdk.md) by following the guidelines provided in the contributor guide. diff --git a/versioned_docs/version-0.11/user-guide/protocols/http.md b/versioned_docs/version-0.11/user-guide/protocols/http.md new file mode 100644 index 000000000..d2f86a6ce --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/protocols/http.md @@ -0,0 +1,526 @@ +--- +description: Guide on using HTTP APIs to interact with GreptimeDB, including authentication, timeout settings, health checks, configuration, and SQL queries. +--- + +# HTTP API + +GreptimeDB provides HTTP APIs for interacting with the database. For a complete list of available APIs, please refer to the [HTTP Endpoint](/reference/http-endpoints.md). + +## Base URL + +The base URL of API is `http(s)://:/`. + +- For the GreptimeDB instance running on the local machine, + with default port configuration `4000`, + the base URL is `http://localhost:4000/`. + You can change the server host and port in the [configuration](/user-guide/deployments/configuration#protocol-options) file. + +- For GreptimeCloud, the base URL is `https:///`. + You can find the host in 'Connection Information' at the GreptimeCloud console. + +In the following sections, we use `http://{{API-host}}/` as the base URL to demonstrate the API usage. + +## Common headers + +### Authentication + +GreptimeDB supports the built-in `Basic` authentication scheme in the HTTP API. To set up authentication, follow these steps: + +1. Encode your username and password using the `:` format and the `Base64` algorithm. +2. Attach your encoded credentials to the HTTP request header using the `Authorization: Basic ` format. + +Here's an example. If you want to connect to GreptimeDB using the username `greptime_user` and password `greptime_pwd`, use the following command: + +```shell +curl -X POST \ +-H 'Authorization: Basic Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=' \ +-H 'Content-Type: application/x-www-form-urlencoded' \ +-d 'sql=show tables' \ +http://localhost:4000/v1/sql +``` + +In this example, `Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=` represents the Base64-encoded value of `greptime_user:greptime_pwd`. Make sure to replace it with your own configured username and password, and encode them using Base64. + +:::tip NOTE +InfluxDB uses its own authentication format, see [InfluxDB](./influxdb-line-protocol.md) for details. +::: + +### Timeout + +GreptimeDB supports the `X-Greptime-Timeout` header in HTTP requests. +It is used to specify the timeout for the request running in the database server. + +For example, the following request set `120s` timeout for the request: + +```bash +curl -X POST \ +-H 'X-Greptime-Timeout: 120s' \ +-H 'Content-Type: application/x-www-form-urlencoded' \ +-d 'sql=show tables' \ +http://localhost:4000/v1/sql +``` + +## Admin APIs + +:::tip NOTE +These endpoint cannot be used in GreptimeCloud. +::: + +### Check database health + +You can use the `/health` endpoint to check the health of the GreptimeDB server. +For more information, +please refer to [Check Database Health](/getting-started/installation/overview.md#check-database-health). + +### Check Database Status + +You can use the `/status` endpoint to check the status of the GreptimeDB server. + +```shell +curl http://{{API-host}}/status +``` + +For example: + +```shell +curl http://localhost:4000/status +``` + +The output contains the database version and source code information, +which will be similar to the following: + +```json +{ + "source_time": "2024-11-08T06:34:49Z", + "commit": "0e0c4faf0d784f25fed8f26e7000f1f869c88587", + "branch": "main", + "rustc_version": "rustc 1.84.0-nightly (e92993dbb 2024-10-18)", + "hostname": "local", + "version": "0.9.5" +} +``` + +### Get GreptimeDB server configuration + +You can use the `/config` endpoint to get the [TOML configuration](/user-guide/deployments/configuration.md#configuration-file-options) of the GreptimeDB server. + +```shell +curl http://{{API-host}}/config +``` + +For example: + +```shell +curl http://localhost:4000/config +``` + +The output contains the configuration information of the GreptimeDB server. + +```toml +mode = "standalone" +enable_telemetry = true +user_provider = "static_user_provider:file:user" +init_regions_in_background = false +init_regions_parallelism = 16 + +[http] +addr = "127.0.0.1:4000" +timeout = "30s" +body_limit = "64MiB" +is_strict_mode = false + +# ... +``` + +## POST SQL statements + +To submit a SQL query to the GreptimeDB server via HTTP API, use the following format: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authentication}}' \ + -H 'X-Greptime-Timeout: {{time precision}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql={{SQL-statement}}' \ +http://{{API-host}}/v1/sql +``` + +### Headers + +- [`Authorization`](#authentication) +- [`X-Greptime-Timeout`](#timeout) +- `Content-Type`: `application/x-www-form-urlencoded`. +- `X-Greptime-Timezone`: The time zone for the current SQL query. Optional. Please refer to [time zone](#time-zone). + +### Query string parameters + +- `db`: The database name. Optional. If not provided, the default database `public` will be used. +- `format`: The output format. Optional. + In addition to the default JSON format, the HTTP API also allows you to + customize output format by providing the `format` query parameter with following + values: + - `influxdb_v1`: [influxdb query + API](https://docs.influxdata.com/influxdb/v1/tools/api/#query-http-endpoint) + compatible format. Additional parameters: + - `epoch`: `[ns,u,µ,ms,s,m,h]`, returns epoch timestamps with the specified + precision + - `csv`: output in comma separated values + - `arrow`: [Arrow IPC + format](https://arrow.apache.org/docs/python/feather.html). Additional + parameters: + - `compression`: `zstd` or `lz4`, default: no compression + - `table`: ASCII table format for console output + +### Body + +- `sql`: The SQL statement. Required. + +### Response + +The response is a JSON object containing the following fields: + +- `output`: The SQL executed result. Please refer to the examples blow to see the details. +- `execution_time_ms`: The execution time of the statement in milliseconds. + +### Examples + +#### `INSERT` statement + +For example, to insert data into the `monitor` table of database `public`, use the following command: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql=INSERT INTO monitor VALUES ("127.0.0.1", 1667446797450, 0.1, 0.4), ("127.0.0.2", 1667446798450, 0.2, 0.3), ("127.0.0.1", 1667446798450, 0.5, 0.2)' \ + http://localhost:4000/v1/sql?db=public +``` + +The response will contain the number of affected rows: + +```shell +{"output":[{"affectedrows":3}],"execution_time_ms":11} +``` + +#### `SELECT` statement + +You can also use the HTTP API to execute other SQL statements. +For example, to retrieve data from the `monitor` table: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "sql=SELECT * FROM monitor" \ + http://localhost:4000/v1/sql?db=public +``` + +The response will contain the queried data in JSON format: + +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "host", + "data_type": "String" + }, + { + "name": "ts", + "data_type": "TimestampMillisecond" + }, + { + "name": "cpu", + "data_type": "Float64" + }, + { + "name": "memory", + "data_type": "Float64" + } + ] + }, + "rows": [ + [ + "127.0.0.1", + 1720728000000, + 0.5, + 0.1 + ] + ], + "total_rows": 1 + } + } + ], + "execution_time_ms": 7 +} +``` + +The response contains the following fields: + +- `output`: The execution result. + - `records`: The query result. + - `schema`: The schema of the result, including the schema of each column. + - `rows`: The rows of the query result, where each row is an array containing the corresponding values of the columns in the schema. +- `execution_time_ms`: The execution time of the statement in milliseconds. + +#### Time zone + +GreptimeDB supports the `X-Greptime-Timezone` header in HTTP requests. +It is used to specify the timezone for the current SQL query. + +For example, the following request uses the time zone `+1:00` for the query: + +```bash +curl -X POST \ +-H 'X-Greptime-Timezone: +1:00' \ +-H 'Content-Type: application/x-www-form-urlencoded' \ +-d 'sql=SHOW VARIABLES time_zone;' \ +http://localhost:4000/v1/sql +``` + +After the query, the result will be: + +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "TIME_ZONE", + "data_type": "String" + } + ] + }, + "rows": [ + [ + "+01:00" + ] + ] + } + } + ], + "execution_time_ms": 27 +} +``` + +For information on how the time zone affects data inserts and queries, please refer to the SQL documents in the [Ingest Data](../ingest-data/for-iot/sql.md#time-zone) and [Query Data](../query-data/sql.md#time-zone) sections. + +#### Query data with `table` format output + +You can use the `table` format in the query string parameters to get the output in ASCII table format. + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "sql=SELECT * FROM monitor" \ + http://localhost:4000/v1/sql?db=public&format=table +``` + +Output + +``` +┌─host────────┬─ts────────────┬─cpu─┬─memory─┐ +│ "127.0.0.1" │ 1667446797450 │ 0.1 │ 0.4 │ +│ "127.0.0.1" │ 1667446798450 │ 0.5 │ 0.2 │ +│ "127.0.0.2" │ 1667446798450 │ 0.2 │ 0.3 │ +└─────────────┴───────────────┴─────┴────────┘ +``` + +#### Query data with `influxdb_v1` format output + +You can use the `influxdb_v1` format in the query string parameters to get the output in InfluxDB query API compatible format. + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "sql=SELECT * FROM monitor" \ + http://localhost:4000/v1/sql?db=public&format=influxdb_v1&epoch=ms +``` + +```json +{ + "results": [ + { + "statement_id": 0, + "series": [ + { + "name": "", + "columns": [ + "host", + "cpu", + "memory", + "ts" + ], + "values": [ + [ + ["127.0.0.1", 0.1, 0.4, 1667446797450], + ["127.0.0.1", 0.5, 0.2, 1667446798450], + ["127.0.0.2", 0.2, 0.3, 1667446798450] + ] + ] + } + ] + } + ], + "execution_time_ms": 2 +} +``` + +## POST PromQL queries + +### The API returns Prometheus query result format + +GreptimeDB compatible with Prometheus query language (PromQL) and can be used to query data in GreptimeDB. +For all the compatible APIs, please refer to the [Prometheus Query Language](/user-guide/query-data/promql#prometheus-http-api) documentation. + +### The API returns GreptimeDB JSON format + +GreptimeDB also exposes an custom HTTP API for querying with PromQL, and returning +GreptimeDB's data frame output. You can find it on `/promql` path under the +current stable API version `/v1`. +The return value of this API is in GreptimeDB's JSON format, not Prometheus's format. +For example: + +```shell +curl -X GET \ + -H 'Authorization: Basic {{authorization if exists}}' \ + -G \ + --data-urlencode 'db=public' \ + --data-urlencode 'query=avg(system_metrics{idc="idc_a"})' \ + --data-urlencode 'start=1667446797' \ + --data-urlencode 'end=1667446799' \ + --data-urlencode 'step=1s' \ + http://localhost:4000/v1/promql +``` + +The input parameters are similar to the [`range_query`](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) in Prometheus' HTTP API: + +- `db=`: Required when using GreptimeDB with authorization, otherwise can be omitted if you are using the default `public` database. +- `query=`: Required. Prometheus expression query string. +- `start=`: Required. The start timestamp, which is inclusive. It is used to set the range of time in `TIME INDEX` column. +- `end=`: Required. The end timestamp, which is inclusive. It is used to set the range of time in `TIME INDEX` column. +- `step=`: Required. Query resolution step width in duration format or float number of seconds. + +Here are some examples for each type of parameter: + +- rfc3339 + - `2015-07-01T20:11:00Z` (default to seconds resolution) + - `2015-07-01T20:11:00.781Z` (with milliseconds resolution) + - `2015-07-02T04:11:00+08:00` (with timezone offset) +- unix timestamp + - `1435781460` (default to seconds resolution) + - `1435781460.781` (with milliseconds resolution) +- duration + - `1h` (1 hour) + - `5d1m` (5 days and 1 minute) + - `2` (2 seconds) + - `2s` (also 2 seconds) + +The result format is the same as `/sql` interface described in [Post SQL statements](#post-sql-statements) section. + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "ts", + "data_type": "TimestampMillisecond" + }, + { + "name": "AVG(system_metrics.cpu_util)", + "data_type": "Float64" + }, + { + "name": "AVG(system_metrics.memory_util)", + "data_type": "Float64" + }, + { + "name": "AVG(system_metrics.disk_util)", + "data_type": "Float64" + } + ] + }, + "rows": [ + [ + 1667446798000, + 80.1, + 70.3, + 90 + ], + [ + 1667446799000, + 80.1, + 70.3, + 90 + ] + ] + } + } + ], + "execution_time_ms": 5 +} +``` + +## Post Influxdb line protocol data + + + + + +```shell +curl -X POST \ + -H 'Authorization: token :' \ + -d '{{Influxdb-line-protocol-data}}' \ + http://{{API-host}}/v1/influxdb/api/v2/write?precision={{time-precision}} +``` + + + + + +```shell +curl -X POST \ + -d '{{Influxdb-line-protocol-data}}' \ + http://{{API-host}}/v1/influxdb/api/v1/write?u={{username}}&p={{password}}&precision={{time-precision}} +``` + + + + +### Headers + +- `Authorization`: **Unlike other APIs**, the InfluxDB line protocol APIs use the InfluxDB authentication format. For V2, it is `token :`. + +### Query string parameters + +- `u`: The username. Optional. It is the authentication username for V1. +- `p`: The password. Optional. It is the authentication password for V1. +- `db`: The database name. Optional. The default value is `public`. +- `precision`: Defines the precision of the timestamp provided in the request body. Please refer to [InfluxDB Line Protocol](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md) in the user guide. + +### Body + +The InfluxDB line protocol data points. Please refer to the [InfluxDB Line Protocol](https://docs.influxdata.com/influxdb/v1/write_protocols/line_protocol_tutorial/#syntax) document. + +### Examples + +Please refer to [InfluxDB Line Protocol](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md) in the user guide. + +## API for managing Pipelines + +When writing logs to GreptimeDB, +you can use HTTP APIs to manage the pipelines. +For detailed information, +please refer to the [Manage Pipelines](/user-guide/logs/manage-pipelines.md) documentation. + diff --git a/versioned_docs/version-0.11/user-guide/protocols/influxdb-line-protocol.md b/versioned_docs/version-0.11/user-guide/protocols/influxdb-line-protocol.md new file mode 100644 index 000000000..7c4fb5adc --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/protocols/influxdb-line-protocol.md @@ -0,0 +1,37 @@ +--- +description: Instructions on ingesting data to GreptimeDB using InfluxDB Line Protocol and using ping and health APIs. +--- + +# InfluxDB Line Protocol + +## Ingest data + +For how to ingest data to GreptimeDB using InfluxDB Line Protocol, +please refer to the [Ingest Data](/user-guide/ingest-data/for-iot/influxdb-line-protocol.md) document. + +## PING + +Additionally, GreptimeDB also provides support for the `ping` and `health` APIs of InfluxDB. + +Use `curl` to request `ping` API. + +```shell +curl -i "127.0.0.1:4000/v1/influxdb/ping" +``` + +```shell +HTTP/1.1 204 No Content +date: Wed, 22 Feb 2023 02:29:44 GMT +``` + +Use `curl` to request `health` API. + +```shell +curl -i "127.0.0.1:4000/v1/influxdb/health" +``` + +```shell +HTTP/1.1 200 OK +content-length: 0 +date: Wed, 22 Feb 2023 02:30:46 GMT +``` diff --git a/versioned_docs/version-0.11/user-guide/protocols/mysql.md b/versioned_docs/version-0.11/user-guide/protocols/mysql.md new file mode 100644 index 000000000..82c053784 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/protocols/mysql.md @@ -0,0 +1,81 @@ +--- +description: Guide on connecting to GreptimeDB using MySQL, managing tables, ingesting and querying data, and handling time zones. +--- + +# MySQL + +## Connect + +You can connect to GreptimeDB using MySQL via port `4002`. + +```shell +mysql -h -P 4002 -u -p +``` + +- For how to setup username and password for GreptimeDB, please refer to [Authentication](/user-guide/deployments/authentication/overview.md). +- If you want to use other ports for MySQL, please refer to [Protocol options](/user-guide/deployments/configuration.md#protocol-options) in the configuration document. + + +## Table management + +Please refer to [Table Management](/user-guide/administration/manage-data/basic-table-operations.md). + +## Ingest data + +Please refer to [SQL](/user-guide/ingest-data/for-iot/sql.md). + +## Query data + +Please refer to [SQL](/user-guide/query-data/sql.md). + +## Time zone + +GreptimeDB's MySQL protocol interface follows original MySQL on [how to +deal with time zone](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html). + +By default, MySQL uses its server time zone for timestamp. To override, you can +set `time_zone` variable for current session using SQL statement `SET time_zone = '';`. +The value of `time_zone` can be any of: + +- The server's time zone: `SYSTEM`. +- Offset to UTC such as `+08:00`. +- Any named time zone like `Europe/Berlin`. + +Some MySQL clients, such as Grafana MySQL data source, allow you to set the time zone for the current session. +You can also use the above values when setting the time zone. + +You can use `SELECT` to check the current time zone settings. For example: + +```sql +SELECT @@system_time_zone, @@time_zone; +``` + +The result shows that both the system time zone and the session time zone are set to `UTC`: + +```SQL ++--------------------+-------------+ +| @@system_time_zone | @@time_zone | ++--------------------+-------------+ +| UTC | UTC | ++--------------------+-------------+ +``` + +Change the session time zone to `+1:00`: + +```SQL +SET time_zone = '+1:00' +``` + +Then you can see the difference between the system time zone and the session time zone: + +```SQL +SELECT @@system_time_zone, @@time_zone; + ++--------------------+-------------+ +| @@system_time_zone | @@time_zone | ++--------------------+-------------+ +| UTC | +01:00 | ++--------------------+-------------+ +``` + +For information on how the time zone affects data inserts and queries, please refer to the SQL documents in the [Ingest Data](/user-guide/ingest-data/for-iot/sql.md#time-zone) and [Query Data](/user-guide/query-data/sql.md#time-zone) sections. diff --git a/versioned_docs/version-0.11/user-guide/protocols/opentelemetry.md b/versioned_docs/version-0.11/user-guide/protocols/opentelemetry.md new file mode 100644 index 000000000..033ff70ba --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/protocols/opentelemetry.md @@ -0,0 +1,4 @@ +# OpenTelemetry (OTLP) + +GreptimeDB is an observability backend to consume OpenTelemetry Metrics natively via [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) protocol. +Please refer to the [Ingest Data with OpenTelemetry](/user-guide/ingest-data/for-observerbility/opentelemetry.md) document for detailed information. diff --git a/versioned_docs/version-0.11/user-guide/protocols/opentsdb.md b/versioned_docs/version-0.11/user-guide/protocols/opentsdb.md new file mode 100644 index 000000000..d8e74e480 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/protocols/opentsdb.md @@ -0,0 +1,3 @@ +# OpenTSDB + +Please refer to [Ingest Data with OpenTSDB](/user-guide/ingest-data/for-iot/opentsdb.md) for detailed information. diff --git a/versioned_docs/version-0.11/user-guide/protocols/overview.md b/versioned_docs/version-0.11/user-guide/protocols/overview.md new file mode 100644 index 000000000..e034eaff6 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/protocols/overview.md @@ -0,0 +1,9 @@ +# Overview + +- [InfluxDB Line Protocol](./influxdb-line-protocol.md) +- [OpenTelemetry (OTLP)](./opentelemetry.md) +- [MySQL](./mysql.md) +- [PostgreSQL](./postgresql.md) +- [HTTP API](./http.md) +- [gRPC](./grpc.md) +- [OpenTSDB](./opentsdb.md) diff --git a/versioned_docs/version-0.11/user-guide/protocols/postgresql.md b/versioned_docs/version-0.11/user-guide/protocols/postgresql.md new file mode 100644 index 000000000..2f9f931d0 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/protocols/postgresql.md @@ -0,0 +1,164 @@ +--- +description: Guide on connecting to GreptimeDB using PostgreSQL, managing tables, ingesting and querying data, and handling time zones. +--- + +# PostgreSQL + +## Connect + +You can connect to GreptimeDB using PostgreSQL via port `4003`. +Simply add the `-U` argument to your command, followed by your username and password. Here's an example: + +```shell +psql -h -p 4003 -U -d public +``` + +- For how to setup username and password for GreptimeDB, please refer to [Authentication](/user-guide/deployments/authentication/overview.md). +- If you want to use other ports for PostgreSQL, please refer to [Protocol options](/user-guide/deployments/configuration.md#protocol-options) in the configuration document. + + +## Table management + +Please refer to [Table Management](/user-guide/administration/manage-data/basic-table-operations.md). + +## Ingest data + +Please refer to [SQL](/user-guide/ingest-data/for-iot/sql.md). + +## Query data + +Please refer to [SQL](/user-guide/query-data/sql.md). + +## Time zone + +GreptimeDB's PostgreSQL protocol interface follows original PostgreSQL on [datatype-timezones](https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-TIMEZONES). + +By default, PostgreSQL uses its server time zone for timestamp. To override, you can +set `time_zone` variable for current session using SQL statement `SET TIMEZONE TO '';`. +The value of `time_zone` can be any of: + +- A full time zone name, for example `America/New_York`. +- A time zone abbreviation, for example `PST`. +- Offset to UTC such as `+08:00`. + +You can use `SHOW` to check the current time zone settings. For example: + +```sql +SHOW VARIABLES time_zone; +``` + +```sql + TIME_ZONE +----------- + UTC +``` + +Change the session time zone to `+1:00`: + +```SQL +SET TIMEZONE TO '+1:00' +``` + +For information on how the time zone affects data inserts and queries, please refer to the SQL documents in the [Ingest Data](/user-guide/ingest-data/for-iot/sql.md#time-zone) and [Query Data](/user-guide/query-data/sql.md#time-zone) sections. + +## Foreign Data Wrapper + +GreptimeDB can be configured as a foreign data server for Postgres' built-in +[FDW extension](https://www.postgresql.org/docs/current/postgres-fdw.html). This +allows user to query GreptimeDB tables seamlessly from Postgres server. It's +also possible to join Postgres tables with GreptimeDB tables. + +For example, your IoT metadata, like device information, is stored in a +relational data model in Postgres. It's possible to use filter queries to find +out device IDs and join with time-series data from GreptimeDB. + +### Setup + +To setup GreptimeDB for Postgres FDW, make sure you enabled postgres protocol +support in GreptimeDB and it's accessible from your Postgres server. + +To create and configuration GreptimeDB in Postgres, first enable the +`postgres_fdw` extension. + +```sql +CREATE EXTENSION postgres_fdw; +``` + +Add GreptimeDB instance as remote server. + +```sql +CREATE SERVER greptimedb +FOREIGN DATA WRAPPER postgres_fdw +OPTIONS (host 'greptimedb_host', dbname 'public', port '4003'); +``` + +Configure user mapping for Postgres user and GreptimeDB user. This step is +required. But if you don't have authentication enabled in GreptimeDB OSS +version, just fill the credential with random data. + +```sql +CREATE USER MAPPING FOR postgres +SERVER greptimedb +OPTIONS (user 'greptime', password '...'); +``` + +Create foreign table in Postgres to map GreptimeDB's schema. Note that you will +need to use Postgres' corresponding data types for GreptimeDB's. + +For GreptimeDB's tables + +```sql +CREATE TABLE grpc_latencies ( + ts TIMESTAMP TIME INDEX, + host STRING, + method_name STRING, + latency DOUBLE, + PRIMARY KEY (host, method_name) +) with('append_mode'='true'); + +CREATE TABLE app_logs ( + ts TIMESTAMP TIME INDEX, + host STRING, + api_path STRING FULLTEXT, + log_level STRING, + log STRING FULLTEXT, + PRIMARY KEY (host, log_level) +) with('append_mode'='true'); +``` + +You will need to define them like this in Postgres. + +```sql +CREATE FOREIGN TABLE ft_grpc_latencies ( + ts TIMESTAMP, + host VARCHAR, + method_name VARCHAR, + latency DOUBLE precision +) +SERVER greptimedb +OPTIONS (table_name 'grpc_latencies'); + +CREATE FOREIGN TABLE ft_app_logs ( + ts TIMESTAMP, + host VARCHAR, + api_path VARCHAR, + log_level VARCHAR, + log VARCHAR +) +SERVER greptimedb +OPTIONS (table_name 'app_logs'); +``` + +You can now send query from Postgres. It's also possible to use functions that +are available in both Postgres and GreptimeDB, like `date_trunc`. + +```sql +SELECT * FROM ft_app_logs ORDER BY ts DESC LIMIT 100; + +SELECT + date_trunc('MINUTE', ts) as t, + host, + avg(latency), + count(latency) +FROM ft_grpc_latencies GROUP BY host, t; +``` diff --git a/versioned_docs/version-0.11/user-guide/python-scripts/api.md b/versioned_docs/version-0.11/user-guide/python-scripts/api.md new file mode 100644 index 000000000..4cae539a4 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/python-scripts/api.md @@ -0,0 +1,93 @@ +# API + +## Builtin modules and functions + +We provide a wide range of built-in functions for users to use. The following is a list of built-in functions. Simply write `import greptime` or `from greptime import *` at the beginning of your script to use them. + +## Vector functions + +| Function | Description | +| :--- | :--- | +| `pow(v0, v1)` | Raise a number `v0` to a power of `v1`. | +| `clip(v0, v1, v2)` | Clip all elements in a vector `v0` to a range between vectors `v1` and `v2`. | +| `diff(v0)` | Calculate the difference between adjacent elements in a vector `v0`. | +| `mean(v0)` | Calculate the mean of a vector `v0`. | +| `polyval(v0, v1)` | Evaluate a polynomial `v0` at points `v1`. similar to `numpy.polyval`. | +| `argmax(v0)` | Return the index of the maximum value in a vector `v0`. similar to `numpy.argmax`. | +| `argmin(v0)` | Return the index of the minimum value in a vector `v0`. similar to `numpy.argmin`. | +| `percentile` | Calculate the `q`-th percentile of a vector `v0`. similar to `numpy.percentile`. | +| `scipy_stats_norm_cdf` | Calculate the cumulative distribution function for the normal distribution. similar to `scipy.stats.norm.cdf`. | +| `scipy_stats_norm_pdf` | Calculate the probability density function for the normal distribution. similar to `scipy.stats.norm.pdf`. | + +## Math functions + +| Function | Description | +| :--- | :--- | +| `sqrt(v)` | Calculate the square root of a number `v`. | +| `sin(v)` | Calculate the sine of a number `v`. | +| `cos(v)` | Calculate the cosine of a number `v`. | +| `tan(v)` | Calculate the tangent of a number `v`. | +| `asin(v)` | Calculate the arcsine of a number `v`. | +| `acos(v)` | Calculate the arccosine of a number `v`. | +| `atan(v)` | Calculate the arctangent of a number `v`. | +| `floor(v)` | Calculate the floor of a number `v`. | +| `ceil(v)` | Calculate the ceiling of a number `v`. | +| `round(v)` | Calculate the nearest integer of a number `v`. | +| `trunc(v)` | Calculate the truncated integer of a number `v`. | +| `abs(v)` | Calculate the absolute value of a number `v`. | +| `signum(v)` | Calculate the sign(gives 1.0/-1.0) of a number `v`. | +| `exp(v)` | Calculate the exponential of a number `v`. | +| `ln(v)` | Calculate the natural logarithm of a number `v`. | +| `log2(v)` | Calculate the base-2 logarithm of a number `v`. | +| `log10(v)` | Calculate the base-10 logarithm of a number `v`. | + +## Utility functions & Aggregation functions + +These Functions are bound from `DataFusion` +| Function | Description | +| :--- | :--- | +| `random(len)` | Generate a random vector with length `len`. | +| `approx_distinct(v0)` | Calculate the approximate number of distinct values in a vector `v0`. | +| `median(v0)` | Calculate the median of a vector `v0`. | +| `approx_percentile_cont(values, percent)` | Calculate the approximate percentile of a vector `values` at a given percentage `percent`. | +| `array_agg(v0)` | Aggregate values into an array. | +| `avg(v0)` | Calculate the average of a vector `v0`. | +| `correlation(v0, v1)` | Calculate the Pearson correlation coefficient of a vector `v0` and a vector `v1`. | +| `count(v0)` | Calculate the count of a vector `v0`. | +| `covariance(v0, v1)` | Calculate the covariance of a vector `v0` and a vector `v1`. | +| `covariance_pop(v0, v1)` | Calculate the population covariance of a vector `v0` and a vector `v1`. | +| `max(v0)` | Calculate the maximum of a vector `v0`. | +| `min(v0)` | Calculate the minimum of a vector `v0`. | +| `stddev(v0)` | Calculate the sample standard deviation of a vector `v0`. | +| `stddev_pop(v0)` | Calculate the population standard deviation of a vector `v0`. | +| `sum(v0)` | Calculate the sum of a vector `v0`. | +| `variance(v0)` | Calculate the sample variance of a vector `v0`. | +| `variance_pop(v0)` | Calculate the population variance of a vector `v0`. | + +## DataFrame's methods + +| Method | Description | +| --- | --- | +| `select_columns(columns: List[str])` | select columns from DataFrame | +| `select(columns: List[Expr]])` | select columns from DataFrame using `PyExpr` | +| `filter(condition: Expr)` | filter DataFrame using `PyExpr` | +| `aggregate(group_expr: List[Expr], aggr_expr: List[Expr])` | Perform an aggregate query with optional grouping expressions. | +| `limit(skip: int, fetch: Optional[int])` |Limit the number of rows returned from this DataFrame. `skip` - Number of rows to skip before fetch any row; `fetch` - Maximum number of rows to fetch, after skipping skip rows. +| `union(other: DataFrame)` | Union two DataFrame | +| `union_distinct(other: DataFrame)` | Union two DataFrame, but remove duplicate rows | +| `distinct()` | Remove duplicate rows | +| `sort(expr: List[Expr])` | Sort DataFrame by `PyExpr`, Sort the DataFrame by the specified sorting expressions. Any expression can be turned into a sort expression by calling its sort method. | +| `join(right: DataFrame, left_cols: List[str], right_cols: List[str], filter: Optional[Expr])` | Join two DataFrame using the specified columns as join keys. Eight Join Types are supported: `inner`, `left`, `right`, `full`, `leftSemi`, `leftAnti`, `rightSemi`, `rightAnti`. | +| `intersect(other: DataFrame)` | Intersect two DataFrame | +| `except(other: DataFrame)` | Except two DataFrame | +| `collect()` | Collect DataFrame to a list of `PyVector` | + +## Expr's methods + +| Method | Description | +| --- | --- | +| `col(name: str)` | Create a `PyExpr` that represents a column | +| `lit(value: Any)` | Create a `PyExpr` that represents a literal value | +| `sort(ascending: bool, null_first: bool)` | Create a `PyExpr` that represents a sort expression | +| comparison operators: `==`, `!=`, `>`, `>=`, `<`, `<=` | Create `PyExpr` from compare two `PyExpr` | +| logical operators: `&`, `\|`, `~` | Create `PyExpr` from logical operation between two `PyExpr` | diff --git a/versioned_docs/version-0.11/user-guide/python-scripts/data-types.md b/versioned_docs/version-0.11/user-guide/python-scripts/data-types.md new file mode 100644 index 000000000..f6c437ce8 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/python-scripts/data-types.md @@ -0,0 +1,184 @@ +# Data Types + +## DataFrame + +A DataFrame represents a logical set of rows with the same named columns, similar to a [Pandas DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or [Spark DataFrame](https://spark.apache.org/docs/latest/sql-programming-guide.html). + +You can create a dataframe from `sql`: + +```python +from greptime import PyDataFrame, col +@copr(returns = ["value"]) +def query_numbers() -> vector[f64]: + df = PyDataFrame.from_sql("select number from numbers") + return df.filter(col('number') <= 5).collect()[0] +``` + +It's the same as `select number from numbers where number <=5`, but uses dataframe API. + +In fact, the coprocessor's dataframe API is a wrapper of Apache Datafusion [DataFrame API](https://arrow.apache.org/datafusion/user-guide/dataframe.html). Please refer to [API](api.md) document to get the full DataFrame API. + +## Vector + +The vector is the major data type in Coprocessor, it's a vector of values in the same type. Usually, it comes from extracting a column from the query result, but you can also construct it in the python script. + +The vector is like the array type in the programming language, `Array` in Apache [Arrow](https://arrow.apache.org/) or `NDArray` in [NumPy](https://numpy.org/doc/stable/reference/arrays.html). + +### Vector Types + +The Coprocessor Engine supports the following vector types: + +| Type | Description | +|---|---| +| `vector[str]` | The string type | +| `vector[bool]` | The boolean type | +| `vector[u8]`| The 8-bit unsigned integer type | +| `vector[u16]` | The 16-bit unsigned integer type | +| `vector[u32]`| The 32-bit unsigned integer type | +| `vector[u64]` | The 64-bit unsigned integer type | +| `vector[i8]` | The 8-bit signed integer type | +| `vector[i16]` | The 16-bit signed integer type | +| `vector[i32]` | The 32-bit signed integer type | +| `vector[i64]` | The 64-bit signed integer type | +| `vector[f32]` | The 32-bit floating point type | +| `vector[f64]` | The 64-bit floating point type | +| `vector[none]` | The any type | + +As we see in [Hello, world](./getting-started.md#hello-world-example), we can define the return vector types for the coprocessor if we want to use it as SQL UDF. Otherwise, we can ignore the return vector types declaration: + +```python +@coprocessor(returns=['msg']) +def hello() -> vector[str]: + return "hello, GreptimeDB" +``` + +The Coprocessor Engine will infer the return vector types by the result. But without the declaration, we can't call it in SQL except by HTTP API. + +### Construct a vector + +We have already seen the example that extracting vectors from the query result by executing the `sql` attribute in `@coprocessor` in [Query Data](./query-data.md). + +We can create a vector from literals: + +```python +@copr(returns=["value"]) +def answer() -> vector[i64]: + return 42 +``` + +The result `42` will be wrapped as a one-element vector of `vector[i64]`. + +```sql +mysql> select answer(); ++----------+ +| answer() | ++----------+ +| 42 | ++----------+ +1 row in set (0.01 sec) +``` + +We can create a vector from a python list: + +```python +from greptime import vector + +@copr(returns=["value"]) +def answer() -> vector[i64]: + return vector([42, 43, 44]) +``` + +The `greptime` is a built-in module, please refer to [API Document](./api.md). + +```sql +mysql> select answer(); ++----------+ +| answer() | ++----------+ +| 42 | +| 43 | +| 44 | ++----------+ +3 rows in set (0.02 sec) +``` + +In fact, the `vector` function can create a vector from any iterable object in python. But it requires all the element types must be the same, and it chooses the first element's type as its vector type. + +### Vector operations + +The vector supports a lot of operations: + +1. Basic arithmetic operators are supported, including `+`, `-`, `*`, `/`. +2. Basic logic operations are supported, including `&`, `|`, `~`. +3. Basic comparison operation including`>`, `<`, `>=`, `<=`, `==`, `!=` are supported too. + +> Note: Here we override bitwise and `&`, bitwise or `|`, bitwise not `~` logical operator because Python doesn't support logical operator override(You can't override `and` `or` `not`). [PEP335](https://peps.python.org/pep-0335/) made a proposal and was eventually rejected. But bitwise operators have higher precedence than comparison operators, so remember to use a pair of parentheses to make sure the result is what you want. +> i.e. if you want to filter a vector that's between 0 and 100, you should use `(vector[i32] >= 0) & (vector[i32] <= 100)` not `vector[i32] >= 0 & vector[i32] <= 100`. The latter one will be evaluated as `vector[i32] >= (0 & vector[i32]) <= 100`. + +For example, you can plus two vectors directly: + +```python +@copr(args=["n1", "n2"], + returns=["value"], + sql="select number as n1,number as n2 from numbers limit 5") +def add_vectors(n1, n2) -> vector[i32]: + return n1 + n2 +``` + +Or do a comparison with a bool array in a Numpy way: + +```python +from greptime import vector + +@copr(returns=["value"]) +def compare() -> vector[bool]: + # This returns a vector([False, False, True]) + return vector([1.0, 2.0, 3.0]) > 2.0 +``` + +And using the boolean array indexing: + +```python +from greptime import vector + +@copr(returns=["value"]) +def boolean_array() -> vector[f64]: + v = vector([1.0, 2.0, 3.0]) + # This returns a vector([2.0]) + return v[(v > 1) & (v< 3)] +``` + +Comparison between two vectors is also supported: + +```python +from greptime import vector + +@copr(returns=["value"]) +def compare_vectors() -> vector[bool]: + # This returns a vector([False, False, True]) + return vector([1.0, 2.0, 3.0]) > vector([1.0, 2.0, 2.0]) +``` + +Using an indexed bool array to select elements from a vector: + +```python +from greptime import vector + +@copr(returns=["value"]) +def select_elements() -> (vector[f64]): + a = vector([1.0, 2.0, 3.0]) + # This returns a vector([2.0, 3.0]) + return a[a>=2.0] +``` + +Of course, we can use list comprehension to construct a new vector: + +```python +from greptime import vector + +@copr(returns=["value"]) +def list_comprehension() -> (vector[f64]): + a = vector([1.0, 2.0, 3.0]) + # This returns a vector([3.0, 4.0]) + return [x+1 for x in a if a >= 2.0] +``` diff --git a/versioned_docs/version-0.11/user-guide/python-scripts/define-function.md b/versioned_docs/version-0.11/user-guide/python-scripts/define-function.md new file mode 100644 index 000000000..8df8c62cb --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/python-scripts/define-function.md @@ -0,0 +1,267 @@ +# Define a Function + +## Coprocessor annotation + +The `@coprocessor` annotation specifies a python function as a coprocessor in GreptimeDB and sets some attributes for it. + +The engine allows one and only one function annotated with `@coprocessor`. We can't have more than one coprocessor in one script. + +| Parameter | Description | Example | +| --- | --- | --- | +| `sql` | Optional. The SQL statement that the coprocessor function will query data from the database and assign them to input `args`. | `@copr(sql="select * from cpu", ..)` | +| `args` | Optional. The argument names that the coprocessor function will be taken as input, which are the columns in query results by `sql`. | `@copr(args=["cpu", "mem"], ..)` | +| `returns` | The column names that the coprocessor function will return. The Coprocessor Engine uses it to generate the output schema. | `@copr(returns=["add", "sub", "mul", "div"], ..)` | +| `backend` | Optional. The coprocessor function will run on available engines like `rspy` and `pyo3`, which are associated with `RustPython` Backend and `CPython` Backend respectively. The default engine is set to `rspy`. | `@copr(backend="rspy", ..)` | + +Both `sql` and `args` are optional; they must either be provided together or not at all. They are usually used in Post-Query processing. Please read below. + +The `returns` is required for every coprocessor because the output schema is necessary. + +`backend` is optional, because `RustPython` can't support C APIs and you might want to use `pyo3` backend to use third-party python libraries that only support C APIs. For example, `numpy`, `pandas` etc. + +## Input of the coprocessor function + +```python +@coprocessor(args=["number"], sql="select number from numbers limit 20", returns=["value"]) +def normalize(v) -> vector[i64]: + return [normalize0(x) for x in v] +``` + +The argument `v` is the `number` column(specified by the `args` attribute) in query results that are returned by executing the `sql`. + +Of course, you can have several arguments: + +```python +@coprocessor(args=["number", "number", "number"], + sql="select number from numbers limit 5", + returns=["value"]) +def normalize(n1, n2, n3) -> vector[i64]: + # returns [0,1,8,27,64] + return n1 * n2 * n3 +``` + +Except `args`, we can also pass user-defined parameters into the coprocessor: + +```python +@coprocessor(returns=['value']) +def add(**params) -> vector[i64]: + a = params['a'] + b = params['b'] + return int(a) + int(b) +``` + +And then pass the `a` and `b` from HTTP API: + +```sh +curl -XPOST \ + "http://localhost:4000/v1/run-script?name=add&db=public&a=42&b=99" +``` + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "value", + "data_type": "Int64" + } + ] + }, + "rows": [ + [ + 141 + ] + ] + } + } + ], + "execution_time_ms": 0 +} +``` + +We pass `a=42&b=99` as query params into HTTP API, and it returns the result `141`. + +The user-defined parameters must be defined by `**kwargs` in the coprocessor, and all their types are strings. We can pass anything we want such as SQL to run in the coprocessor. + +## Output of the coprocessor function + +As we have seen in the previous examples, the output must be vectors. + +We can return multi vectors: + +```python +from greptime import vector + +@coprocessor(returns=["a", "b", "c"]) +def return_vectors() -> (vector[i64], vector[str], vector[f64]): + a = vector([1, 2, 3]) + b = vector(["a", "b", "c"]) + c = vector([42.0, 43.0, 44.0]) + return a, b, c +``` + +The return types of function `return_vectors` is `(vector[i64], vector[str], vector[f64])`. + +But we must ensure that all these vectors returned by the function have the same length. Because when they are converted into rows, each row must have all the column values presented. + +Of course, we can return literal values, and they will be turned into vectors: + +```python +from greptime import vector + +@coprocessor(returns=["a", "b", "c"]) +def return_vectors() -> (vector[i64], vector[str], vector[i64]): + a = 1 + b = "Hello, GreptimeDB!" + c = 42 + return a, b, c +``` + +## HTTP API + +`/scripts` submits a Python script into GreptimeDB. + +Save a python script such as `test.py`: + +```python +@coprocessor(args = ["number"], + returns = [ "number" ], + sql = "select number from numbers limit 5") +def square(number) -> vector[i64]: + return number * 2 +``` + +Submits it to database: + +```shell +curl --data-binary @test.py -XPOST \ + "http://localhost:4000/v1/scripts?db=default&name=square" +``` + +```json +{"code":0} +``` + +The python script is inserted into the `scripts` table and compiled automatically: + +```shell +curl -G http://localhost:4000/v1/sql --data-urlencode "sql=select * from scripts" +``` + +```json +{ + "code": 0, + "output": [{ + "records": { + "schema": { + "column_schemas": [ + { + "name": "schema", + "data_type": "String" + }, + { + "name": "name", + "data_type": "String" + }, + { + "name": "script", + "data_type": "String" + }, + { + "name": "engine", + "data_type": "String" + }, + { + "name": "timestamp", + "data_type": "TimestampMillisecond" + }, + { + "name": "gmt_created", + "data_type": "TimestampMillisecond" + }, + { + "name": "gmt_modified", + "data_type": "TimestampMillisecond" + } + ] + }, + "rows": [ + [ + "default", + "square", + "@coprocessor(args = [\"number\"],\n returns = [ \"number\" ],\n sql = \"select number from numbers\")\ndef square(number):\n return number * 2\n", + "python", + 0, + 1676032587204, + 1676032587204 + ] + ] + } + }], + "execution_time_ms": 4 +} +``` + +You can also execute the script via `/run-script`: + +```shell +curl -XPOST -G "http://localhost:4000/v1/run-script?db=default&name=square" +``` + +```json +{ + "code": 0, + "output": [{ + "records": { + "schema": { + "column_schemas": [ + { + "name": "number", + "data_type": "Float64" + } + ] + }, + "rows": [ + [ + 0 + ], + [ + 2 + ], + [ + 4 + ], + [ + 6 + ], + [ + 8 + ] + ] + } + }], + "execution_time_ms": 8 +} +``` + +### Parameters and Result for Python scripts + +`/scripts` accepts query parameters `db` which specifies the database, and `name` which names the script. `/scripts` processes the POST method body as the script file content. + +`/run-script` runs the compiled script by `db` and `name`, then returns the output which is the same as the query result in `/sql` API. + +`/run-script` also receives other query parameters as the user params passed into the coprocessor, refer to [Input and Output](#input-of-the-coprocessor-function). + +## Edit scripts in GreptimeDB Dashboard + +[GreptimeDB Dashboard](/getting-started/installation/greptimedb-dashboard.md) provides a convenient editor for users to edit scripts. + +After starting GreptimeDB, you can access the dashboard at `http://localhost:4000/dashboard`. +Click on `Scripts` in the left sidebar to navigate to the script page. +From there, you can create a new script, edit an existing script, or run a script. + +![dashboard-scripts](/db-dashboard-scripts.png) diff --git a/versioned_docs/version-0.11/user-guide/python-scripts/getting-started.md b/versioned_docs/version-0.11/user-guide/python-scripts/getting-started.md new file mode 100644 index 000000000..c41654a5d --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/python-scripts/getting-started.md @@ -0,0 +1,191 @@ +# Getting Started + +## Installation + +### Create python environment +If you are using Greptime's docker image, no need to set up scripting again—it's ready to go. + +If you want to use the Greptime binary with the pyo3 feature, first figure out which Python version you need. Check by running `ldd greptime | grep 'libpython'` (or `otool -L greptime|grep Python.framework` on Mac), then install the corresponding Python version (e.g., `libpython3.10.so` requires Python 3.10). + +To set up a Python 3 environment using conda, a handy tool for managing Python environments, please refer to the [official documentation](https://docs.conda.io/en/latest/miniconda.html) for more information. + +```shell +conda create --name Greptime python= +conda activate Greptime +``` + +You may have to adjust the correct `LD_LIBRARY_PATH` for your Python shared library. For example, in the conda environment, set `LD_LIBRARY_PATH` (or `DYLD_LIBRARY_PATH`) to `$CONDA_PREFIX/lib`. To ensure the correct Python shared library is in this path, run `ls $CONDA_PREFIX/lib | grep 'libpython'` and verify that the version is correct. + +### Install GreptimeDB + +Please refer to [Installation](/getting-started/installation/overview.md). + +## Hello world example + +Let's begin with a hello world example: + +```python +@coprocessor(returns=['msg']) +def hello() -> vector[str]: + return "Hello, GreptimeDB" +``` + +Save it as `hello.py`, then post it by [HTTP API](./define-function.md#http-api): + +### Submit the Python Script to GreptimeDB + +```sh +curl --data-binary "@hello.py" -XPOST "http://localhost:4000/v1/scripts?name=hello&db=public" +``` + +Then call it in SQL: + +```sql +select hello(); +``` + +```sql ++-------------------+ +| hello() | ++-------------------+ +| Hello, GreptimeDB | ++-------------------+ +1 row in set (1.77 sec) +``` + +Or call it by [HTTP API](./define-function.md#http-api): + +```sh +curl -XPOST "http://localhost:4000/v1/run-script?name=hello&db=public" +``` + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "msg", + "data_type": "String" + } + ] + }, + "rows": [["Hello, GreptimeDB"]] + } + } + ], + "execution_time_ms": 1917 +} +``` + +The function `hello` is a coprocessor with an annotation `@coprocessor`. +The `returns` in `@coprocessor` specifies the return column names by the coprocessor and generates the final schema of output: + +```json + "schema": { + "column_schemas": [ + { + "name": "msg", + "data_type": "String" + } + ] + } +``` + +The `-> vector[str]` part after the argument list specifies the return types of the function. They are always vectors with concrete types. The return types are required to generate the output of the coprocessor function. + +The function body of `hello` returns a literal string: `"Hello, GreptimeDB"`.The Coprocessor engine will cast it into a vector of constant string and return it. + +A coprocessor contains three main parts in summary: + +- The `@coprocessor` annotation. +- The function input and output. +- The function body. + +We can call a coprocessor in SQL like a SQL UDF(User Defined Function) or call it by HTTP API. + +## SQL example + +Save your python code for complex analysis (like the following one which determines the load status by cpu/mem/disk usage) into a file (here its named `system_status.py`): + +```python +@coprocessor(args=["host", "idc", "cpu_util", "memory_util", "disk_util"], + returns = ["host", "idc", "status"], + sql = "SELECT * FROM system_metrics") +def system_status(hosts, idcs, cpus, memories, disks)\ + -> (vector[str], vector[str], vector[str]): + statuses = [] + for host, cpu, memory, disk in zip(hosts, cpus, memories, disks): + if cpu > 80 or memory > 80 or disk > 80: + statuses.append("red") + continue + + status = cpu * 0.4 + memory * 0.4 + disk * 0.2 + + if status > 80: + statuses.append("red") + elif status > 50: + statuses.append("yello") + else: + statuses.append("green") + + + return hosts, idcs, statuses + +``` + +The above piece of code evaluates the host status based on the cpu/memory/disk usage. Arguments come from querying data from `system_metrics` specified by parameter `sql` in `@coprocessor` annotation (here is = `"SELECT * FROM system_metrics"`). The query result is assigned to each positional argument with corresponding names in `args=[...]`, then the function returns three variables, which are converted back into three columns `returns = ["host", "idc", "status"]`. + +### Submit the Python Script to GreptimeDB + +You can submit the file to GreptimeDB with a script name so you can refer to it by this name(`system_status`) later and execute it: + +```shell +curl --data-binary "@system_status.py" \ + -XPOST "http://localhost:4000/v1/scripts?name=system_status&db=public" +``` + +Run the script: + +```shell +curl -XPOST \ + "http://localhost:4000/v1/run-script?name=system_status&db=public" +``` + +Getting the results in `json` format: + +```json +{ + "code": 0, + "output": { + "records": { + "schema": { + "column_schemas": [ + { + "name": "host", + "data_type": "String" + }, + { + "name": "idc", + "data_type": "String" + }, + { + "name": "status", + "data_type": "String" + } + ] + }, + "rows": [ + ["host1", "idc_a", "green"], + ["host1", "idc_b", "yello"], + ["host2", "idc_a", "red"] + ] + } + } +} +``` + +For more information about python coprocessor, please refer to [Function](./define-function.md#http-api) for more information. diff --git a/versioned_docs/version-0.11/user-guide/python-scripts/overview.md b/versioned_docs/version-0.11/user-guide/python-scripts/overview.md new file mode 100644 index 000000000..b6b193908 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/python-scripts/overview.md @@ -0,0 +1,29 @@ +# Overview + +GreptimeDB supports running Python script inside the database. If the business logic is too complex to express via SQL, you can use python. Python prevails in the data science and AI world. To avoid spending lots of time and effort transferring and transforming data, we provide the capability of executing Python scripts in the database. + +We think the python scripts in GreptimeDB is a perfect replacement for stored procedures in traditional RDMS, and also the user can create SQL UDFs(User Defined Function). + +* [Getting started](./getting-started.md) +* [Function](./define-function.md) +* [Query Data](./query-data.md) +* [Ingest Data](./write-data.md) +* [Data types](./data-types.md) +* [API](./api.md) + +All the examples can be found in [python-coprocessor-examples](https://github.com/GreptimeTeam/python-coprocessor-examples). + +# Note + +The Python scripts is currently in its experimental phase, and the API may undergo some changes. + +You can download [pre-built binaries](https://greptime.com/download) with PyO3 supported whose file names are postfixed by `pyo3`.You can just also use RustPython which doesn't require additional setup by download binary files without `pyo3` postfixed. + +If you have some library link issues, you must set up the correct Python shared library, which can be a bit challenging. In general, you just need to install the `python-dev` package(on most Debian-based system). However, if you are using Homebrew to install Python on macOS, you must create a proper soft link to `Library/Frameworks/Python.framework`. +The recommended way is to utilize `conda` for managing your Python environment. Firstly, create a Python environment with the same version of Python demanded by the binary you download. Alternatively, you can employ a docker container and execute the `greptime` binary within it. +A less recommended way is to manually install the exact version of Python required and set the `LD_LIBRARY_PATH` environment variable to the directory containing the `libpython.so` file. The version number of `` varies according to the version of Python being used. + +There is two backends for Python Scripts: + +1. RustPython Interpreter: this is supported without installing any Python library, but it is not as fast as CPython Backend. The Release Binary without `pyo3` in its name uses RustPython Interpreter. While you can still use Python Syntax in RustPython Interpreter, you can't use any third-parties libs. +2. CPython Interpreter: this is the most commonly used version of Python. It allows you to use all sorts of third-parties libs, but you need to install the correct Python shared library. Any Release Binary with `pyo3` in its name uses CPython Interpreter. diff --git a/versioned_docs/version-0.11/user-guide/python-scripts/query-data.md b/versioned_docs/version-0.11/user-guide/python-scripts/query-data.md new file mode 100644 index 000000000..623a276ad --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/python-scripts/query-data.md @@ -0,0 +1,117 @@ +# Query Data + +We provide two ways to easily query data from GreptimeDB in Python Coprocessor: + +* SQL: run a SQL string and return the query result. +* DataFrame API: a builtin module that describes and executes the query similar to a [Pandas DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or [Spark DataFrame](https://spark.apache.org/docs/latest/sql-programming-guide.html). + +## SQL + +Use the `greptime` module's `query` method to retrieve a query engine, then call `sql` function to execute a SQL string, for example: + +```python +@copr(returns=["value"]) +def query_numbers()->vector[f64]: + from greptime import query + return query().sql("select number from numbers limit 10")[0] +``` + +Call it via SQL client: + +```sql +SQL > select query_numbers(); ++-----------------+ +| query_numbers() | ++-----------------+ +| 0 | +| 1 | +| 2 | +| 3 | +| 4 | +| 5 | +| 6 | +| 7 | +| 8 | +| 9 | ++-----------------+ +10 rows in set (1.78 sec) +``` + +The `sql` function returns a list of columns, and each column is a vector of values. + +In the above example, `sql("select number from numbers limit 10")` returns a list of vectors. And use `[0]` to retrieve the first column vector which is the `number` column in `select` SQL. + +## Post-Query Processing + +The coprocessor is helpful when processing a query result before it returns to the user. +For example, we want to normalize the value: + +* Return zero instead of null or `NaN` if it misses, +* If it is greater than 5, return 5, +* If it is less than zero, return zero. + +Then we can create a `normalize.py`: + +```python +import math + +def normalize0(x): + if x is None or math.isnan(x): + return 0 + elif x > 5: + return 5 + elif x < 0: + return 0 + else: + return x + +@coprocessor(args=["number"], sql="select number from numbers limit 10", returns=["value"]) +def normalize(v) -> vector[i64]: + return [normalize0(x) for x in v] +``` + +The `normalize0` function behaves as described above. And the `normalize` function is the coprocessor entry point: + +* Execute the SQL `select number from numbers limit 10`, +* Extract the column `number` in the query result and use it as the argument in the `normalize` function. Then invoke the function. +* In function, use list comprehension to process the `number` vector, which processes every element by the `normalize0` function. +* Returns the result named as `value` column. + +The `-> vector[i64]` part specifies the return column types for generating the output schema. + +This example also shows how to import the stdlib and define other functions(the `normalize0`) for invoking. +The `normalize` coprocessor will be called in streaming. The query result may contain several batches, and the engine will call the coprocessor with each batch. +And we should remember that the columns extracted from the query result are all vectors. We will cover vectors in the next chapter. + +Submit and run this script will generate the output: + +```json +{ + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "value", + "data_type": "Int64" + } + ] + }, + "rows": [ + [0], + [1], + [2], + [3], + [4], + [5], + [5], + [5], + [5], + [5] + ] + } + } + ] +} +``` diff --git a/versioned_docs/version-0.11/user-guide/python-scripts/write-data.md b/versioned_docs/version-0.11/user-guide/python-scripts/write-data.md new file mode 100644 index 000000000..633d02bb1 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/python-scripts/write-data.md @@ -0,0 +1,39 @@ +# Write Data + + +## Insert data + +Of course, you can insert data by `sql` API too: + +```python +from greptime import query +@copr(returns=["affected_rows"]) +def insert() -> vector[i32]: + return query().sql("insert into monitor(host, ts, cpu, memory) values('localhost',1667446807000, 15.3, 66.6)") +``` + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "rows", + "data_type": "Int32" + } + ] + }, + "rows": [ + [ + 1 + ] + ] + } + } + ], + "execution_time_ms": 4 +} +``` diff --git a/versioned_docs/version-0.11/user-guide/query-data/cte.md b/versioned_docs/version-0.11/user-guide/query-data/cte.md new file mode 100644 index 000000000..96285e71a --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/query-data/cte.md @@ -0,0 +1,167 @@ +--- +description: Explanation of Common Table Expressions (CTEs) in GreptimeDB, including syntax, examples, and how to use CTEs to simplify complex queries. +--- + +# Common Table Expression (CTE) + +CTEs are similar to [Views](./view.md) in that they help you reduce the complexity of your queries, break down long and complex SQL statements, and improve readability and reusability. + +You already read a CTE in the [quickstart](/getting-started/quick-start.md#correlate-metrics-and-logs) document. + +## What is a Common Table Expression (CTE)? + +A Common Table Expression (CTE) is a temporary result set that you can reference within a `SELECT`, `INSERT`, `UPDATE`, or `DELETE` statement. CTEs help to break down complex queries into more readable parts and can be referenced multiple times within the same query. + +## Basic syntax of CTE + +CTEs are typically defined using the `WITH` keyword. The basic syntax is as follows: + +```sql +WITH cte_name [(column1, column2, ...)] AS ( + QUERY +) +SELECT ... +FROM cte_name; +``` + +## Example explanation + +Next, we'll go through a complete example that demonstrates how to use CTEs, including data preparation, CTE creation, and usage. + +### Step 1: Create example data + +Let's assume we have the following two tables: + +- `grpc_latencies`: Contains gRPC request latency data. +- `app_logs`: Contains application log information. + +```sql +CREATE TABLE grpc_latencies ( + ts TIMESTAMP TIME INDEX, + host VARCHAR(255), + latency FLOAT, + PRIMARY KEY(host), +); + +INSERT INTO grpc_latencies VALUES +('2023-10-01 10:00:00', 'host1', 120), +('2023-10-01 10:00:00', 'host2', 150), +('2023-10-01 10:00:05', 'host1', 130); + +CREATE TABLE app_logs ( + ts TIMESTAMP TIME INDEX, + host VARCHAR(255), + log TEXT, + log_level VARCHAR(50), + PRIMARY KEY(host, log_level), +); + +INSERT INTO app_logs VALUES +('2023-10-01 10:00:00', 'host1', 'Error on service', 'ERROR'), +('2023-10-01 10:00:00', 'host2', 'All services OK', 'INFO'), +('2023-10-01 10:00:05', 'host1', 'Error connecting to DB', 'ERROR'); +``` + +### Step 2: Define and use CTEs + +We will create two CTEs to calculate the 95th percentile latency and the number of error logs, respectively. + +```sql +WITH +metrics AS ( + SELECT + ts, + host, + approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency + FROM + grpc_latencies + ALIGN '5s' FILL PREV +), +logs AS ( + SELECT + ts, + host, + COUNT(log) RANGE '5s' AS num_errors + FROM + app_logs + WHERE + log_level = 'ERROR' + ALIGN '5s' BY (HOST) +) +SELECT + metrics.ts, + metrics.host, + metrics.p95_latency, + COALESCE(logs.num_errors, 0) AS num_errors +FROM + metrics +LEFT JOIN logs ON metrics.host = logs.host AND metrics.ts = logs.ts +ORDER BY + metrics.ts; +``` + +Output: + +```sql ++---------------------+-------+-------------+------------+ +| ts | host | p95_latency | num_errors | ++---------------------+-------+-------------+------------+ +| 2023-10-01 10:00:00 | host2 | 150 | 0 | +| 2023-10-01 10:00:00 | host1 | 120 | 1 | +| 2023-10-01 10:00:05 | host1 | 130 | 1 | ++---------------------+-------+-------------+------------+ +``` + +## Detailed explanation + +1. **Define CTEs**: + - `metrics`: + ```sql + WITH + metrics AS ( + SELECT + ts, + host, + approx_percentile_cont(latency, 0.95) RANGE '5s' AS p95_latency + FROM + grpc_latencies + ALIGN '5s' FILL PREV + ), + ``` + Here we use a [range query](/user-guide/query-data/sql.md#aggregate-data-by-time-window) to calculate the 95th percentile latency for each `host` within every 5-second window. + + - `logs`: + ```sql + logs AS ( + SELECT + ts, + host, + COUNT(log) RANGE '5s' AS num_errors + FROM + app_logs + WHERE + log_level = 'ERROR' + ALIGN '5s' BY (HOST) + ) + ``` + Similarly, we calculate the number of error logs for each `host` within every 5-second window. + +2. **Use CTEs**: + The final query part: + ```sql + SELECT + metrics.ts, + metrics.host, + metrics.p95_latency, + COALESCE(logs.num_errors, 0) AS num_errors + FROM + metrics + LEFT JOIN logs ON metrics.host = logs.host AND metrics.ts = logs.ts + ORDER BY + metrics.ts; + ``` + We perform a left join on the two CTE result sets to get a comprehensive analysis result. + +## Summary + +With CTEs, you can break down complex SQL queries into more manageable and understandable parts. In this example, we created two CTEs to calculate the 95th percentile latency and the number of error logs separately and then merged them into the final query for analysis. Read more [WITH](/reference/sql/with.md). \ No newline at end of file diff --git a/versioned_docs/version-0.11/user-guide/query-data/overview.md b/versioned_docs/version-0.11/user-guide/query-data/overview.md new file mode 100644 index 000000000..6f6db9ea5 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/query-data/overview.md @@ -0,0 +1,26 @@ +--- +description: Overview of query languages supported by GreptimeDB, including PromQL and SQL, and recommended libraries for querying data. +--- + +# Overview + +## Query languages + +- [PromQL](./promql.md) +- [SQL](./sql.md) + +Since v0.9, GreptimeDB supports view and CTE just like other databases, used to simplify queries: + +* [View](./view.md) +* [Common Table Expression (CTE)](./cte.md) + +## Recommended libraries + +Since GreptimeDB uses SQL as its main query language and supports both [MySQL](/user-guide/protocols/mysql.md) and [PostgreSQL](/user-guide/protocols/postgresql.md) protocols, +you can use mature SQL drivers that support MySQL or PostgreSQL to query data. + +For more information, please refer to the [SQL Tools](/reference/sql-tools.md) documentation. + +## Query external data + +GreptimeDB has the capability to query external data files. For more information, please refer to the [Query External Data](./query-external-data.md) documentation. diff --git a/versioned_docs/version-0.11/user-guide/query-data/promql.md b/versioned_docs/version-0.11/user-guide/query-data/promql.md new file mode 100644 index 000000000..49f24d9b3 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/query-data/promql.md @@ -0,0 +1,250 @@ +--- +description: Guide on using Prometheus Query Language (PromQL) in GreptimeDB, including HTTP API compatibility, SQL extensions, and supported features and limitations. +--- + +# Prometheus Query Language + +GreptimeDB can be used as a drop-in replacement for Prometheus in Grafana, because GreptimeDB supports PromQL (Prometheus Query Language). GreptimeDB has reimplemented PromQL natively in Rust and exposes the ability to several interfaces, including the HTTP API of Prometheus, the HTTP API of GreptimeDB, and the SQL interface. + +## Prometheus' HTTP API + + + +GreptimeDB has implemented a set of Prometheus compatible APIs under HTTP +context `/v1/prometheus/`: + +- Instant queries `/api/v1/query` +- Range queries `/api/v1/query_range` +- Series `/api/v1/series` +- Label names `/api/v1/labels` +- Label values `/api/v1/label//values` + +It shares same input and output format with original Prometheus HTTP API. You +can also use GreptimeDB as an in-place replacement of Prometheus. For example in +Grafana Prometheus data source, set `http://localhost:4000/v1/prometheus/` as +context root of Prometheus URL. + +Consult [Prometheus +documents](https://prometheus.io/docs/prometheus/latest/querying/api) for usage +of these API. + +You can use additional query parameter `db` to specify GreptimeDB database name. + +For example, the following query will return the CPU usage of the `process_cpu_seconds_total` metric in the `public` database: + +```shell +curl -X POST \ + -H 'Authorization: Basic {{authorization if exists}}' \ + --data-urlencode 'query=irate(process_cpu_seconds_total[1h])' \ + --data-urlencode 'start=2024-11-24T00:00:00Z' \ + --data-urlencode 'end=2024-11-25T00:00:00Z' \ + --data-urlencode 'step=1h' \ + --data-urlencode 'db=public' \ + http://localhost:4000/v1/prometheus/api/v1/query_range +``` +If authentication is enabled in GreptimeDB, the authentication header is required. Refer to the [authentication documentation](/user-guide/protocols/http.md#authentication) for more details. + +The query string parameters for the API are identical to those of the original [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries), with the exception of the additional `db` parameter, which specifies the GreptimeDB database name. + +The output format is compatible with the Prometheus API: + +```json +{ + "status": "success", + "data": { + "resultType": "matrix", + "result": [ + { + "metric": { + "job": "node", + "instance": "node_exporter:9100", + "__name__": "process_cpu_seconds_total" + }, + "values": [ + [ + 1732618800, + "0.0022222222222222734" + ], + [ + 1732622400, + "0.0009999999999999788" + ], + [ + 1732626000, + "0.0029999999999997585" + ], + [ + 1732629600, + "0.002222222222222175" + ] + ] + } + ] + } +} +``` + +## SQL + +GreptimeDB also extends SQL grammar to support PromQL. You can start with the `TQL` (Time-series Query Language) keyword to write parameters and queries. The grammar looks like this: + +```sql +TQL [EVAL|EVALUATE] (, , ) +``` + +`` specifies the query start range and `` specifies the end time. `` identifies the query resolution step width. All of them can either be an unquoted number (represent UNIX timestamp for `` and ``, and duration in seconds for ``), or a quoted string (represent an RFC3339 timestamp for `` and ``, and duration in string format for ``). + +For example: + +```sql +TQL EVAL (1676738180, 1676738780, '10s') sum(some_metric) +``` + +You can write the above command in all places that support SQL, including the GreptimeDB HTTP API, SDK, PostgreSQL and MySQL client etc. + +## Multiple fields + +Based on the table model, GreptimeDB supports multiple fields in a single table(or metric, in the context of Prometheus). Queries will run on every fields by default. Or you can use the special filter `__field__` to query a specific field(s): + +```promql +metric{__field__="field1"} +``` + +Exclude or regex are also supported: + +```promql +metric{__field__!="field1"} + +metric{__field__=~"field_1|field_2"} + +metric{__field__!~"field_1|field_2"} +``` + +## Limitations + +Though GreptimeDB supports a rich set of data types, the PromQL implementation is still limited to the following types: + +- timestamp: `Timestamp` +- tag: `String` +- value: `Double` + +Currently only a subset of PromQL is supported. Here attaches the compatibility list. You can also check our latest compliance report in this [tracking issue](https://github.com/GreptimeTeam/greptimedb/issues/1042). + +### Literal + +Both string and float literals are supported, with the same [rule](https://prometheus.io/docs/prometheus/latest/querying/basics/#literals) as PromQL. + +### Selector + +Both instant and range selector are supported. The only exception is the label matching on metric name, e.g.: `{__name__!="request_count}"` (but the equal-matching case is supported: `{__name__="request_count}"`). + +Time duration and offset are supported, but `@` modifier is not supported yet. + +### Timestamp precision + +The timestamp precision in PromQL is limited by its query syntax, only supporting calculations up to millisecond precision. However, GreptimeDB supports storing high-precision timestamps, such as microseconds and nanoseconds. When using PromQL for calculations, these high-precision timestamps are implicitly converted to millisecond precision. + +### Binary + +*Pure literal binary-expr like `1+1` is not supported yet.* + +- Supported: + | Operator | Example | + | :------- | :------- | + | add | `a + b` | + | sub | `a - b` | + | mul | `a * b` | + | div | `a / b` | + | mod | `a % b` | + | eqlc | `a == b` | + | neq | `a != b` | + | gtr | `a > b` | + | lss | `a < b` | + | gte | `a >= b` | + | lte | `a <= b` | + +- Unsupported: + | Operator | Progress | + | :------- | :------- | + | power | TBD | + | atan2 | TBD | + | and | TBD | + | or | TBD | + | unless | TBD | + +### Aggregators + +- Supported: + | Aggregator | Example | + | :--------- | :------------------------ | + | sum | `sum by (foo)(metric)` | + | avg | `avg by (foo)(metric)` | + | min | `min by (foo)(metric)` | + | max | `max by (foo)(metric)` | + | stddev | `stddev by (foo)(metric)` | + | stdvar | `stdvar by (foo)(metric)` | + +- Unsupported: + | Aggregator | Progress | + | :----------- | :------- | + | count | TBD | + | grouping | TBD | + | topk | TBD | + | bottomk | TBD | + | count_values | TBD | + +### Instant Functions + +- Supported: + | Function | Example | + | :----------------- | :-------------------------------- | + | abs | `abs(metric)` | + | ceil | `ceil(metric)` | + | exp | `exp(metric)` | + | ln | `ln(metric)` | + | log2 | `log2(metric)` | + | log10 | `log10(metric)` | + | sqrt | `sqrt(metric)` | + | acos | `acos(metric)` | + | asin | `asin(metric)` | + | atan | `atan(metric)` | + | sin | `sin(metric)` | + | cos | `cos(metric)` | + | tan | `tan(metric)` | + | acosh | `acosh(metric)` | + | asinh | `asinh(metric)` | + | atanh | `atanh(metric)` | + | sinh | `sinh(metric)` | + | cosh | `cosh(metric)` | + | scalar | `scalar(metric)` | + | tanh | `tanh(metric)` | + | timestamp | `timestamp()` | + | histogram_quantile | `histogram_quantile(phi, metric)` | + +- Unsupported: + | Function | Progress / Example | + | :------------------------- | :----------------- | + | absent | TBD | + | sgn | TBD | + | sort | TBD | + | sort_desc | TBD | + | deg | TBD | + | rad | TBD | + | *other multiple input fns* | TBD | + +### Range Functions + +- Supported: + | Function | Example | + | :----------------- | :----------------------------- | + | idelta | `idelta(metric[5m])` | + | \_over_time | `count_over_time(metric[5m])` | + | stddev_over_time | `stddev_over_time(metric[5m])` | + | stdvar_over_time | `stdvar_over_time(metric[5m])` | + | changes | `changes(metric[5m])` | + | delta | `delta(metric[5m])` | + | rate | `rate(metric[5m])` | + | deriv | `deriv(metric[5m])` | + | increase | `increase(metric[5m])` | + | irate | `irate(metric[5m])` | + | reset | `reset(metric[5m])` | diff --git a/versioned_docs/version-0.11/user-guide/query-data/query-external-data.md b/versioned_docs/version-0.11/user-guide/query-data/query-external-data.md new file mode 100644 index 000000000..14857a27e --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/query-data/query-external-data.md @@ -0,0 +1,123 @@ +--- +description: Instructions on querying external data files in GreptimeDB, including creating external tables and running queries on various file formats like CSV and Parquet. +--- + +# Query External Data + +## Query on a file + +Currently, we support queries on `Parquet`, `CSV`, `ORC`, and `NDJson` format file(s). + +We use the [Taxi Zone Lookup Table](https://d37ci6vzurychx.cloudfront.net/misc/taxi+_zone_lookup.csv) data as an example. + +```bash +curl "https://d37ci6vzurychx.cloudfront.net/misc/taxi+_zone_lookup.csv" -o /tmp/taxi+_zone_lookup.csv +``` + +Create an external table: + +```sql +CREATE EXTERNAL TABLE taxi_zone_lookup with (location='/tmp/taxi+_zone_lookup.csv',format='csv'); +``` + +You can check the schema of the external table like follows: + +```sql +DESC TABLE taxi_zone_lookup; +``` + +```sql ++--------------------+----------------------+------+------+--------------------------+---------------+ +| Column | Type | Key | Null | Default | Semantic Type | ++--------------------+----------------------+------+------+--------------------------+---------------+ +| LocationID | Int64 | | YES | | FIELD | +| Borough | String | | YES | | FIELD | +| Zone | String | | YES | | FIELD | +| service_zone | String | | YES | | FIELD | +| greptime_timestamp | TimestampMillisecond | PRI | NO | 1970-01-01 00:00:00+0000 | TIMESTAMP | ++--------------------+----------------------+------+------+--------------------------+---------------+ +4 rows in set (0.00 sec) +``` + +:::tip Note +Here, you may notice there is a `greptime_timestamp` column, which doesn't exist in the file. This is because when creating an external table, if we didn't specify a `TIME INDEX` column, the `greptime_timestamp` column is automatically added as the `TIME INDEX` column with a default value of `1970-01-01 00:00:00+0000`. You can find more details in the [create](/reference/sql/create.md#create-external-table) document. +::: + +Now you can query on the external table: + +```sql +SELECT `Zone`, `Borough` FROM taxi_zone_lookup LIMIT 5; +``` + +```sql ++-------------------------+---------------+ +| Zone | Borough | ++-------------------------+---------------+ +| Newark Airport | EWR | +| Jamaica Bay | Queens | +| Allerton/Pelham Gardens | Bronx | +| Alphabet City | Manhattan | +| Arden Heights | Staten Island | ++-------------------------+---------------+ +``` + +## Query on a directory + +Let's download some data: + +```bash +mkdir /tmp/external +curl "https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2022-01.parquet" -o /tmp/external/yellow_tripdata_2022-01.parquet +curl "https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2022-02.parquet" -o /tmp/external/yellow_tripdata_2022-02.parquet +``` + +Verify the download: + +```bash +ls -l /tmp/external +total 165368 +-rw-r--r-- 1 wenyxu wheel 38139949 Apr 28 14:35 yellow_tripdata_2022-01.parquet +-rw-r--r-- 1 wenyxu wheel 45616512 Apr 28 14:36 yellow_tripdata_2022-02.parquet +``` + +Create the external table: + +```sql +CREATE EXTERNAL TABLE yellow_tripdata with(location='/tmp/external/',format='parquet'); +``` + +Run queries: + +```sql +SELECT count(*) FROM yellow_tripdata; +``` + +```sql ++-----------------+ +| COUNT(UInt8(1)) | ++-----------------+ +| 5443362 | ++-----------------+ +1 row in set (0.48 sec) +``` + +```sql +SELECT * FROM yellow_tripdata LIMIT 5; +``` + +```sql ++----------+----------------------+-----------------------+-----------------+---------------+------------+--------------------+--------------+--------------+--------------+-------------+-------+---------+------------+--------------+-----------------------+--------------+----------------------+-------------+---------------------+ +| VendorID | tpep_pickup_datetime | tpep_dropoff_datetime | passenger_count | trip_distance | RatecodeID | store_and_fwd_flag | PULocationID | DOLocationID | payment_type | fare_amount | extra | mta_tax | tip_amount | tolls_amount | improvement_surcharge | total_amount | congestion_surcharge | airport_fee | greptime_timestamp | ++----------+----------------------+-----------------------+-----------------+---------------+------------+--------------------+--------------+--------------+--------------+-------------+-------+---------+------------+--------------+-----------------------+--------------+----------------------+-------------+---------------------+ +| 1 | 2022-02-01 00:06:58 | 2022-02-01 00:19:24 | 1 | 5.4 | 1 | N | 138 | 252 | 1 | 17 | 1.75 | 0.5 | 3.9 | 0 | 0.3 | 23.45 | 0 | 1.25 | 1970-01-01 00:00:00 | +| 1 | 2022-02-01 00:38:22 | 2022-02-01 00:55:55 | 1 | 6.4 | 1 | N | 138 | 41 | 2 | 21 | 1.75 | 0.5 | 0 | 6.55 | 0.3 | 30.1 | 0 | 1.25 | 1970-01-01 00:00:00 | +| 1 | 2022-02-01 00:03:20 | 2022-02-01 00:26:59 | 1 | 12.5 | 1 | N | 138 | 200 | 2 | 35.5 | 1.75 | 0.5 | 0 | 6.55 | 0.3 | 44.6 | 0 | 1.25 | 1970-01-01 00:00:00 | +| 2 | 2022-02-01 00:08:00 | 2022-02-01 00:28:05 | 1 | 9.88 | 1 | N | 239 | 200 | 2 | 28 | 0.5 | 0.5 | 0 | 3 | 0.3 | 34.8 | 2.5 | 0 | 1970-01-01 00:00:00 | +| 2 | 2022-02-01 00:06:48 | 2022-02-01 00:33:07 | 1 | 12.16 | 1 | N | 138 | 125 | 1 | 35.5 | 0.5 | 0.5 | 8.11 | 0 | 0.3 | 48.66 | 2.5 | 1.25 | 1970-01-01 00:00:00 | ++----------+----------------------+-----------------------+-----------------+---------------+------------+--------------------+--------------+--------------+--------------+-------------+-------+---------+------------+--------------+-----------------------+--------------+----------------------+-------------+---------------------+ +5 rows in set (0.11 sec) +``` + +:::tip Note +The query result includes the value of the `greptime_timestamp` column, although it does not exist in the original file. All these column values are `1970-01-01 00:00:00+0000`, because when we create an external table, the `greptime_timestamp` column is automatically added with a default value of `1970-01-01 00:00:00+0000`. You can find more details in the [create](/reference/sql/create.md#create-external-table) document. +::: diff --git a/versioned_docs/version-0.11/user-guide/query-data/sql.md b/versioned_docs/version-0.11/user-guide/query-data/sql.md new file mode 100644 index 000000000..fd89b4019 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/query-data/sql.md @@ -0,0 +1,486 @@ +--- +description: Comprehensive guide on querying data in GreptimeDB using SQL, covering basic queries, filtering, time zone handling, functions, and advanced features like range queries and aggregations. +--- + +# SQL + +GreptimeDB supports full SQL for querying data from a database. + +In this document, we will use the `monitor` table to demonstrate how to query data. +For instructions on creating the `monitor` table and inserting data into it, +Please refer to [table management](/user-guide/administration/manage-data/basic-table-operations.md#create-a-table) and [Ingest Data](/user-guide/ingest-data/for-iot/sql.md). + +## Basic query + +The query is represented by the `SELECT` statement. +For example, the following query selects all data from the `monitor` table: + +```sql +SELECT * FROM monitor; +``` + +The query result looks like the following: + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2022-11-03 03:39:57 | 0.1 | 0.4 | +| 127.0.0.1 | 2022-11-03 03:39:58 | 0.5 | 0.2 | +| 127.0.0.2 | 2022-11-03 03:39:58 | 0.2 | 0.3 | ++-----------+---------------------+------+--------+ +3 rows in set (0.00 sec) +``` + +Functions are also supported in the `SELECT` field list. +For example, you can use the `count()` function to retrieve the total number of rows in the table: + +```sql +SELECT count(*) FROM monitor; +``` + +```sql ++-----------------+ +| COUNT(UInt8(1)) | ++-----------------+ +| 3 | ++-----------------+ +``` + +The `avg()` function returns the average value of a certain field: + +```sql +SELECT avg(cpu) FROM monitor; +``` + +```sql ++---------------------+ +| AVG(monitor.cpu) | ++---------------------+ +| 0.26666666666666666 | ++---------------------+ +1 row in set (0.00 sec) +``` + +You can also select only the result of a function. +For example, you can extract the day of the year from a timestamp. +The `DOY` in the SQL statement is the abbreviation of `day of the year`: + +```sql +SELECT date_part('DOY', '2021-07-01 00:00:00'); +``` + +Output: + +```sql ++----------------------------------------------------+ +| date_part(Utf8("DOY"),Utf8("2021-07-01 00:00:00")) | ++----------------------------------------------------+ +| 182 | ++----------------------------------------------------+ +1 row in set (0.003 sec) +``` + +The parameters and results of date functions align with the SQL client's time zone. +For example, when the client's time zone is set to `+08:00`, the results of the two queries below are the same: + +```sql +select to_unixtime('2024-01-02 00:00:00'); +select to_unixtime('2024-01-02 00:00:00+08:00'); +``` + +Please refer to [SELECT](/reference/sql/select.md) and [Functions](/reference/sql/functions/overview.md) for more information. + +## Limit the number of rows returned + +Time series data is typically massive. +To save bandwidth and improve query performance, +you can use the `LIMIT` clause to restrict the number of rows returned by the `SELECT` statement. + +For example, the following query limits the number of rows returned to 10: + +```sql +SELECT * FROM monitor LIMIT 10; +``` + +## Filter data + +You can use the `WHERE` clause to filter the rows returned by the `SELECT` statement. + +Filtering data by tags or time index is efficient and common in time series scenarios. +For example, the following query filter data by tag `host`: + +```sql +SELECT * FROM monitor WHERE host='127.0.0.1'; +``` + +The following query filter data by time index `ts`, and returns the data after `2022-11-03 03:39:57`: + +```sql +SELECT * FROM monitor WHERE ts > '2022-11-03 03:39:57'; +``` + +You can also use the `AND` keyword to combine multiple constraints: + +```sql +SELECT * FROM monitor WHERE host='127.0.0.1' AND ts > '2022-11-03 03:39:57'; +``` + +### Filter by time index + +Filtering data by the time index is a crucial feature in time series databases. + +When working with Unix time values, the database treats them based on the type of the column value. +For instance, if the `ts` column in the `monitor` table has a value type of `TimestampMillisecond`, +you can use the following query to filter the data: + +The Unix time value `1667446797000` corresponds to the `TimestampMillisecond` type。 + +```sql +SELECT * FROM monitor WHERE ts > 1667446797000; +``` + +When working with a Unix time value that doesn't have the precision of the column value, +you need to use the `::` syntax to specify the type of the time value. +This ensures that the database correctly identifies the type. + +For example, `1667446797` represents a timestamp in seconds, +which is different from the default millisecond timestamp of the `ts` column. +You need to specify its type as `TimestampSecond` using the `::TimestampSecond` syntax. +This informs the database that the value `1667446797` should be treated as a timestamp in seconds. + +```sql +SELECT * FROM monitor WHERE ts > 1667446797::TimestampSecond; +``` + +For the supported time data types, please refer to [Data Types](/reference/sql/data-types.md#date-and-time-types). + +When using standard `RFC3339` or `ISO8601` string literals, +you can directly use them in the filter condition since the precision is clear. + +```sql +SELECT * FROM monitor WHERE ts > '2022-07-25 10:32:16.408'; +``` + +Time and date functions are also supported in the filter condition. +For example, use the `now()` function and the `INTERVAL` keyword to retrieve data from the last 5 minutes: + +```sql +SELECT * FROM monitor WHERE ts >= now() - INTERVAL '5 minutes'; +``` + +For date and time functions, please refer to [Functions](/reference/sql/functions/overview.md) for more information. + +### Time zone + +A string literal timestamp without time zone information will be interpreted based on the local time zone of the SQL client. For example, the following two queries are equivalent when the client time zone is `+08:00`: + +```sql +SELECT * FROM monitor WHERE ts > '2022-07-25 10:32:16.408'; +SELECT * FROM monitor WHERE ts > '2022-07-25 10:32:16.408+08:00'; +``` + +All the timestamp column values in query results are formatted based on the client time zone. +For example, the following code shows the same `ts` value formatted in the client time zones `UTC` and `+08:00` respectively. + + + + + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2023-12-31 16:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` + + + + + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2024-01-01 00:00:00 | 0.5 | 0.1 | ++-----------+---------------------+------+--------+ +``` + + + + + +### Functions + +GreptimeDB offers an extensive suite of built-in functions and aggregation +capabilities tailored to meet the demands of data analytics. Its features +include: + +- A comprehensive set of functions inherited from Apache Datafusion query + engine, featuring a selection of date/time functions that adhere to Postgres + naming conventions and behaviour. +- Logical data type operations for JSON, Geolocation, and other specialized data + types. +- Advanced full-text matching capabilities. + +See [Functions reference](/reference/sql/functions/overview.md) for more details. + +## Order By + +The order of the returned data is not guaranteed. You need to use the `ORDER BY` clause to sort the returned data. +For example, in time series scenarios, it is common to use the time index column as the sorting key to arrange the data chronologically: + +```sql +-- ascending order by ts +SELECT * FROM monitor ORDER BY ts ASC; +``` + +```sql +-- descending order by ts +SELECT * FROM monitor ORDER BY ts DESC; +``` + +## `CASE` Expression + +You can use the `CASE` statement to perform conditional logic within your queries. +For example, the following query returns the status of the CPU based on the value of the `cpu` field: + +```sql +SELECT + host, + ts, + CASE + WHEN cpu > 0.5 THEN 'high' + WHEN cpu > 0.3 THEN 'medium' + ELSE 'low' + END AS cpu_status +FROM monitor; +``` + +The result is shown below: + +```sql ++-----------+---------------------+------------+ +| host | ts | cpu_status | ++-----------+---------------------+------------+ +| 127.0.0.1 | 2022-11-03 03:39:57 | low | +| 127.0.0.1 | 2022-11-03 03:39:58 | medium | +| 127.0.0.2 | 2022-11-03 03:39:58 | low | ++-----------+---------------------+------------+ +3 rows in set (0.01 sec) +``` + +For more information, please refer to [CASE](/reference/sql/case.md). + +## Aggregate data by tag + +You can use the `GROUP BY` clause to group rows that have the same values into summary rows. +The average memory usage grouped by idc: + +```sql +SELECT host, avg(cpu) FROM monitor GROUP BY host; +``` + +```sql ++-----------+------------------+ +| host | AVG(monitor.cpu) | ++-----------+------------------+ +| 127.0.0.2 | 0.2 | +| 127.0.0.1 | 0.3 | ++-----------+------------------+ +2 rows in set (0.00 sec) +``` + +Please refer to [GROUP BY](/reference/sql/group_by.md) for more information. + +### Find the latest data of time series + +To find the latest point of each time series, you can use `DISTINCT ON` together with `ORDER BY` like in [ClickHouse](https://clickhouse.com/docs/en/sql-reference/statements/select/distinct). + +```sql +SELECT DISTINCT ON (host) * FROM monitor ORDER BY host, ts DESC; +``` + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2022-11-03 03:39:58 | 0.5 | 0.2 | +| 127.0.0.2 | 2022-11-03 03:39:58 | 0.2 | 0.3 | ++-----------+---------------------+------+--------+ +2 rows in set (0.00 sec) +``` + +## Aggregate data by time window + +GreptimeDB supports [Range Query](/reference/sql/range.md) to aggregate data by time window. + +Suppose we have the following data in the [`monitor` table](/user-guide/administration/manage-data/basic-table-operations.md#create-a-table): + +```sql ++-----------+---------------------+------+--------+ +| host | ts | cpu | memory | ++-----------+---------------------+------+--------+ +| 127.0.0.1 | 2023-12-13 02:05:41 | 0.5 | 0.2 | +| 127.0.0.1 | 2023-12-13 02:05:46 | NULL | NULL | +| 127.0.0.1 | 2023-12-13 02:05:51 | 0.4 | 0.3 | +| 127.0.0.2 | 2023-12-13 02:05:41 | 0.3 | 0.1 | +| 127.0.0.2 | 2023-12-13 02:05:46 | NULL | NULL | +| 127.0.0.2 | 2023-12-13 02:05:51 | 0.2 | 0.4 | ++-----------+---------------------+------+--------+ +``` + +The following query returns the average CPU usage in a 10-second time range and calculates it every 5 seconds: + +```sql +SELECT + ts, + host, + avg(cpu) RANGE '10s' FILL LINEAR +FROM monitor +ALIGN '5s' TO '2023-12-01T00:00:00' BY (host) ORDER BY ts ASC; +``` + +1. `avg(cpu) RANGE '10s' FILL LINEAR` is a Range expression. `RANGE '10s'` specifies that the time range of the aggregation is 10s, and `FILL LINEAR` specifies that if there is no data within a certain aggregation time, use the `LINEAR` method to fill it. +2. `ALIGN '5s'` specifies the that data statistics should be performed in steps of 5s. +3. `TO '2023-12-01T00:00:00` specifies the origin alignment time. The default value is Unix time 0. +4. `BY (host)` specifies the aggregate key. If the `BY` keyword is omitted, the primary key of the data table is used as the aggregate key by default. +5. `ORDER BY ts ASC` specifies the sorting method of the result set. If you do not specify the sorting method, the order of the results is not guaranteed. + +The Response is shown below: + +```sql ++---------------------+-----------+----------------------------------------+ +| ts | host | AVG(monitor.cpu) RANGE 10s FILL LINEAR | ++---------------------+-----------+----------------------------------------+ +| 2023-12-13 02:05:35 | 127.0.0.1 | 0.5 | +| 2023-12-13 02:05:40 | 127.0.0.1 | 0.5 | +| 2023-12-13 02:05:45 | 127.0.0.1 | 0.4 | +| 2023-12-13 02:05:50 | 127.0.0.1 | 0.4 | +| 2023-12-13 02:05:35 | 127.0.0.2 | 0.3 | +| 2023-12-13 02:05:40 | 127.0.0.2 | 0.3 | +| 2023-12-13 02:05:45 | 127.0.0.2 | 0.2 | +| 2023-12-13 02:05:50 | 127.0.0.2 | 0.2 | ++---------------------+-----------+----------------------------------------+ +``` + +### Time range window + +The origin time range window steps forward and backward in the time series to generate all time range windows. +In the example above, the origin alignment time is set to `2023-12-01T00:00:00`, which is also the end time of the origin time window. + +The `RANGE` option, along with the origin alignment time, defines the origin time range window that starts from `origin alignment timestamp` and ends at `origin alignment timestamp + range`. + +The `ALIGN` option defines the query resolution steps. +It determines the calculation steps from the origin time window to other time windows. +For example, with the origin alignment time `2023-12-01T00:00:00` and `ALIGN '5s'`, the alignment times are `2023-11-30T23:59:55`, `2023-12-01T00:00:00`, `2023-12-01T00:00:05`, `2023-12-01T00:00:10`, and so on. + +These time windows are left-closed and right-open intervals +that satisfy the condition `[alignment timestamp, alignment timestamp + range)`. + +The following images can help you understand the time range window more visually: + +When the query resolution is greater than the time range window, the metrics data will be calculated for only one time range window. + +![align > range](/align_greater_than_range.png) + +When the query resolution is less than the time range window, the metrics data will be calculated for multiple time range windows. + +![align < range](/align_less_than_range.png) + +### Align to specific timestamp + +The alignment times default based on the time zone of the current SQL client session. +You can change the origin alignment time to any timestamp you want. For example, use `NOW` to align to the current time: + +```sql +SELECT + ts, + host, + avg(cpu) RANGE '1w' +FROM monitor +ALIGN '1d' TO NOW BY (host); +``` + +Or use a `ISO 8601` timestamp to align to a specified time: + +```sql +SELECT + ts, + host, + avg(cpu) RANGE '1w' +FROM monitor +ALIGN '1d' TO '2023-12-01T00:00:00+08:00' BY (host); +``` + +### Fill null values + +The `FILL` option can be used to fill null values in the data. +In the above example, the `LINEAR` method is used to fill null values. +Other methods are also supported, such as `PREV` and a constant value `X`. +For more information, please refer to the [FILL OPTION](/reference/sql/range.md#fill-option). + +### Syntax + +Please refer to [Range Query](/reference/sql/range.md) for more information. + +## Table name constraints + +If your table name contains special characters or uppercase letters, +you must enclose the table name in backquotes. +For examples, please refer to the [Table name constraints](/user-guide/administration/manage-data/basic-table-operations.md#table-name-constraints) section in the table creation documentation. + +## HTTP API + +Use POST method to query data: + +```shell +curl -X POST \ + -H 'authorization: Basic {{authorization if exists}}' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'sql=select * from monitor' \ +http://localhost:4000/v1/sql?db=public +``` + +The result is shown below: + +```json +{ + "code": 0, + "output": [ + { + "records": { + "schema": { + "column_schemas": [ + { + "name": "host", + "data_type": "String" + }, + { + "name": "ts", + "data_type": "TimestampMillisecond" + }, + { + "name": "cpu", + "data_type": "Float64" + }, + { + "name": "memory", + "data_type": "Float64" + } + ] + }, + "rows": [ + ["127.0.0.1", 1667446797450, 0.1, 0.4], + ["127.0.0.1", 1667446798450, 0.5, 0.2], + ["127.0.0.2", 1667446798450, 0.2, 0.3] + ] + } + } + ], + "execution_time_ms": 0 +} +``` + +For more information about SQL HTTP request, please refer to [API document](/user-guide/protocols/http.md#post-sql-statements). diff --git a/versioned_docs/version-0.11/user-guide/query-data/view.md b/versioned_docs/version-0.11/user-guide/query-data/view.md new file mode 100644 index 000000000..5c35c2191 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/query-data/view.md @@ -0,0 +1,146 @@ +--- +description: Explanation of SQL views in GreptimeDB, including how to create, query, update, and manage views for simplifying complex queries and ensuring data security. +--- + +# View + +In SQL, a view is a virtual table based on the result set of an SQL statement. +It contains rows and columns just like a real table. +The query of a view is run every time the view is referenced in a query. + +In the following situations, you can use views: + +* Simplifying complex queries, avoiding the need to repeatedly write and send complex statements for every query. +* Granting read permissions to specific users while restricting access to certain columns and rows to ensure data security and isolation. + +A view is created with the `CREATE VIEW` statement. + +## View examples + +```sql +CREATE VIEW cpu_monitor AS + SELECT cpu, host, ts FROM monitor; +``` + +The view name is `cpu_monitor`, and the query statement after `AS` is the SQL statement to present the data. Query the view: + +```sql +SELECT * FROM cpu_monitor; +``` + +```sql ++------+-----------+---------------------+ +| cpu | host | ts | ++------+-----------+---------------------+ +| 0.5 | 127.0.0.1 | 2023-12-13 02:05:41 | +| 0.3 | 127.0.0.1 | 2023-12-13 02:05:46 | +| 0.4 | 127.0.0.1 | 2023-12-13 02:05:51 | +| 0.3 | 127.0.0.2 | 2023-12-13 02:05:41 | +| 0.2 | 127.0.0.2 | 2023-12-13 02:05:46 | +| 0.2 | 127.0.0.2 | 2023-12-13 02:05:51 | ++------+-----------+---------------------+ +``` + +Query view by `WHERE`: + +```sql +SELECT * FROM cpu_monitor WHERE host = '127.0.0.2'; +``` + +```sql ++------+-----------+---------------------+ +| cpu | host | ts | ++------+-----------+---------------------+ +| 0.3 | 127.0.0.2 | 2023-12-13 02:05:41 | +| 0.2 | 127.0.0.2 | 2023-12-13 02:05:46 | +| 0.2 | 127.0.0.2 | 2023-12-13 02:05:51 | ++------+-----------+---------------------+ +``` + +Create a view that queries data from two tables: + +```sql +CREATE VIEW app_cpu_monitor AS + SELECT cpu, latency, host, ts FROM monitor LEFT JOIN app_monitor + ON monitor.host = app_monitor.host AND monitor.ts = app_monitor.ts +``` + +Then query the view as if the data were coming from one single table: + +```sql +SELECT * FROM app_cpu_monitor WHERE host = 'host1' +``` + +## Update View + +`CREATE OR REPLACE VIEW` to update a view, if it doesn't exist, it will be created: + +```sql +CREATE OR REPLACE VIEW memory_monitor AS + SELECT memory, host, ts FROM monitor; +``` + +## Shows the view definition + +Shows the `CREATE VIEW` statement that creates the named view by `SHOW CREATE VIEW view_name`: + +```sql +SHOW CREATE VIEW cpu_monitor; +``` + +```sql ++-------------+--------------------------------------------------------------+ +| View | Create View | ++-------------+--------------------------------------------------------------+ +| cpu_monitor | CREATE VIEW cpu_monitor AS SELECT cpu, host, ts FROM monitor | ++-------------+--------------------------------------------------------------+ +``` + +## List Views + +`SHOW VIEWS` statement to find all the views: + +```sql +> SHOW VIEWS; + ++----------------+ +| Views | ++----------------+ +| cpu_monitor | +| memory_monitor | ++----------------+ +``` + +of course, just like `SHOW TABLES`, it supports `LIKE` and `WHERE`: + +```sql +> SHOW VIEWS like 'cpu%'; ++-------------+ +| Views | ++-------------+ +| cpu_monitor | ++-------------+ +1 row in set (0.02 sec) + +> SHOW VIEWS WHERE Views = 'memory_monitor'; ++----------------+ +| Views | ++----------------+ +| memory_monitor | ++----------------+ +``` + +## Drop View + +Use `DROP VIEW` statement to drop a view: + +```sql +DROP VIEW cpu_monitor; +``` + +To be quiet if it does not exist: + +```sql +DROP VIEW IF EXISTS test; +``` + diff --git a/versioned_docs/version-0.11/user-guide/timezone.md b/versioned_docs/version-0.11/user-guide/timezone.md new file mode 100644 index 000000000..ce09db3f4 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/timezone.md @@ -0,0 +1,49 @@ +--- +description: Guide on specifying and managing time zones in GreptimeDB client sessions, including impacts on data ingestion and querying. +--- + +# Time Zone + +You can specify the time zone in the client session to manage time data conveniently. +The specified time zone in the client session does not affect the time data stored in the GreptimeDB server, +it only applies when the client sends a request to the server. +GreptimeDB converts the time value from a string representation to a datetime according to the specified time zone during ingestion or querying, or converts it back. + +## Specify time zone in clients + +By default, all clients use [the default time zone configuration](/user-guide/deployments/configuration.md#default-time-zone-configuration), which is UTC. +You can also specify a time zone in each client session, +which will override the default time zone configuration. + +### MySQL client + +- **Command Line**: For configuring the time zone via the MySQL command line client, please refer to the [time zone section](/user-guide/protocols/mysql.md#time-zone) in the MySQL protocol documentation. +- **MySQL Driver**: If you are using MySQL Driver in Java or Go, see the [time zone section](/reference/sql-tools.md#time-zone) of the SQL tools documentation. + +### PostgreSQL client + +To configure the time zone for the PostgreSQL client, please refer to the [time zone section](/user-guide/protocols/postgresql.md#time-zone) in the PostgreSQL protocol documentation. + +### HTTP API + +When using the HTTP API, you can specify the time zone through the header parameter. For more information, please refer to the [HTTP API documentation](/user-guide/protocols/http.md#time-zone). + +### Other clients + +For other clients, you can change [the default time zone configuration](/user-guide/deployments/configuration.md#default-time-zone-configuration) of GreptimeDB. + +## Impact of time zone on SQL statements + +The client's time zone setting influences both data ingestion and querying. + +### Ingest data + +The time zone set in the client impacts the data during ingestion. +For more information, please refer to the [ingest data section](/user-guide/ingest-data/for-iot/sql.md#time-zone). +Additionally, the default timestamp values in the table schema are influenced by the client's time zone in the same manner as the ingested data. + +### Query data + +The time zone setting also affects data during querying. +For detailed information, please refer to the [query data section](/user-guide/query-data/sql.md#time-zone). + diff --git a/versioned_docs/version-0.11/user-guide/vectors/vector-type.md b/versioned_docs/version-0.11/user-guide/vectors/vector-type.md new file mode 100644 index 000000000..74c6e19b8 --- /dev/null +++ b/versioned_docs/version-0.11/user-guide/vectors/vector-type.md @@ -0,0 +1,98 @@ +--- +description: Overview of vector data type in GreptimeDB, including how to define, insert, and perform calculations with vector type columns in SQL. +--- + +# Vector Data Type + +## Overview + +In the field of artificial intelligence, vectors are an important data type used to represent features or samples within a dataset. Vectors are utilized in various machine learning and deep learning algorithms, such as recommendation systems, natural language processing, and image recognition. By introducing the vector type, GreptimeDB enables more efficient support for these AI applications, offering robust vector storage and computation capabilities. + +## Basic Introduction to Vector Type + +In GreptimeDB, a vector is represented as an array of Float32 (32-bit floating-point) with a fixed dimension. When creating a vector type column, the dimension must be specified and cannot be changed afterward. + +## Defining a Vector Type Column + +In SQL, a table with a vector type column can be defined using the following syntax. Note that the dimension `` must be a positive integer that specifies the length of the vector. + +```sql +CREATE TABLE ( + ... + VECTOR() +); +``` + +For example, to define a table with a vector type column of dimension 3: + +```sql +CREATE TABLE vecs ( + ts TIMESTAMP TIME INDEX, + vec_col VECTOR(3) +); +``` + +## Inserting Vector Data + +In GreptimeDB, you can insert vector data into the database in several ways. The simplest method is to use a string format and implicitly convert it to a vector. The string needs to be enclosed in square brackets `[]`. Below is an example of using implicit conversion in SQL: + +```sql +INSERT INTO
() VALUES +('[, , ...]'), +('[, , ...]'), +... +('[, , ...]'); +``` + +For example, to insert three 3-dimensional vectors: + +```sql +INSERT INTO vecs (ts, vec_col) VALUES +('2024-11-18 00:00:01', '[1.0, 2.0, 3.0]'), +('2024-11-18 00:00:02', '[4.0, 5.0, 6.0]'), +('2024-11-18 00:00:03', '[7.0, 8.0, 9.0]'); +``` + +If you wish to have more explicit control over data conversion, you can use the `parse_vec` function to explicitly parse a string into a vector: + +```sql +INSERT INTO vecs (ts, vec_col) VALUES +('2024-11-18 00:00:01', parse_vec('[1.0, 2.0, 3.0]')), +('2024-11-18 00:00:02', parse_vec('[4.0, 5.0, 6.0]')), +('2024-11-18 00:00:03', parse_vec('[7.0, 8.0, 9.0]')); +``` + +## Vector Calculations + +GreptimeDB supports various vector functions for calculating the similarity between vectors, including `vec_l2sq_distance`, `vec_cos_distance`, and `vec_dot_product`. These functions are used in AI applications to search for the most similar content. + +To perform vector calculations, use the following SQL format: + +```sql +SELECT (, ) FROM
; +``` + +For example, to find the vector with the smallest squared Euclidean distance to a given vector `[5.0, 5.0, 5.0]` and display the distance, you can use the following query: + +```sql +SELECT vec_to_string(vec_col), vec_l2sq_distance(vec_col, '[5.0, 5.0, 5.0]') AS distance +FROM vecs +ORDER BY distance; +``` + +Upon executing this query, you will get results similar to the following: + +``` ++-----------------------------+----------+ +| vec_to_string(vecs.vec_col) | distance | ++-----------------------------+----------+ +| [4,5,6] | 2 | +| [1,2,3] | 29 | +| [7,8,9] | 29 | ++-----------------------------+----------+ +3 rows in set (0.01 sec) +``` + +Through this approach, GreptimeDB enables you to quickly identify and locate similar data vectors, thus providing robust support for AI applications. + +For more information about vector functions, please refer to the [Vector Functions Reference](/reference/sql/functions/vector.md). diff --git a/versioned_sidebars/version-0.10-sidebars.json b/versioned_sidebars/version-0.10-sidebars.json index 064de167e..7f9de14d0 100644 --- a/versioned_sidebars/version-0.10-sidebars.json +++ b/versioned_sidebars/version-0.10-sidebars.json @@ -243,96 +243,6 @@ } ] }, - { - "type": "category", - "label": "GreptimeCloud", - "items": [ - "greptimecloud/overview", - { - "type": "category", - "label": "Getting Started", - "items": [ - "greptimecloud/getting-started/overview", - "greptimecloud/getting-started/prometheus", - "greptimecloud/getting-started/mysql", - "greptimecloud/getting-started/influxdb", - "greptimecloud/getting-started/go", - "greptimecloud/getting-started/java", - "greptimecloud/getting-started/python", - "greptimecloud/getting-started/node", - "greptimecloud/getting-started/vector" - ] - }, - { - "type": "category", - "label": "Integrations", - "items": [ - "greptimecloud/integrations/prometheus", - "greptimecloud/integrations/grafana", - "greptimecloud/integrations/mysql", - "greptimecloud/integrations/postgresql", - "greptimecloud/integrations/influxdb", - "greptimecloud/integrations/kafka", - "greptimecloud/integrations/otlp", - "greptimecloud/integrations/vector", - "greptimecloud/integrations/alloy", - "greptimecloud/integrations/emqx", - "greptimecloud/integrations/streamlit", - "greptimecloud/integrations/superset", - "greptimecloud/integrations/metabase", - "greptimecloud/integrations/mindsdb", - "greptimecloud/integrations/dbeaver", - { - "type": "category", - "label": "SDK Libraries", - "items": [ - "greptimecloud/integrations/sdk-libraries/go", - "greptimecloud/integrations/sdk-libraries/java" - ] - } - ] - }, - { - "type": "category", - "label": "Migrate to GreptimeCloud", - "items": [ - "greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb", - "greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus" - ] - }, - { - "type": "category", - "label": "Usage & Billing", - "items": [ - "greptimecloud/usage-&-billing/overview", - "greptimecloud/usage-&-billing/request-capacity-unit", - "greptimecloud/usage-&-billing/hobby", - "greptimecloud/usage-&-billing/serverless", - "greptimecloud/usage-&-billing/dedicated", - "greptimecloud/usage-&-billing/billing" - ] - }, - { - "type": "category", - "label": "Tutorials", - "items": [ - { - "type": "category", - "label": "Monitor Host Metrics", - "items": [ - "greptimecloud/tutorials/monitor-host-metrics/prometheus", - "greptimecloud/tutorials/monitor-host-metrics/mysql", - "greptimecloud/tutorials/monitor-host-metrics/influxdb", - "greptimecloud/tutorials/monitor-host-metrics/go", - "greptimecloud/tutorials/monitor-host-metrics/java", - "greptimecloud/tutorials/monitor-host-metrics/python", - "greptimecloud/tutorials/monitor-host-metrics/node-js" - ] - } - ] - } - ] - }, { "type": "category", "label": "GreptimeDB Enterprise", diff --git a/versioned_sidebars/version-0.11-sidebars.json b/versioned_sidebars/version-0.11-sidebars.json new file mode 100644 index 000000000..e88339767 --- /dev/null +++ b/versioned_sidebars/version-0.11-sidebars.json @@ -0,0 +1,545 @@ +{ + "docs": [ + { + "type": "doc", + "className": "hidden", + "id": "index" + }, + { + "type": "category", + "label": "Getting Started", + "items": [ + "getting-started/overview", + { + "type": "category", + "label": "Installation", + "items": [ + "getting-started/installation/overview", + "getting-started/installation/greptimedb-standalone", + "getting-started/installation/greptimedb-cluster", + "getting-started/installation/greptimedb-dashboard" + ] + }, + "getting-started/quick-start" + ] + }, + { + "type": "category", + "label": "User Guide", + "items": [ + "user-guide/overview", + { + "type": "category", + "label": "Concepts", + "items": [ + "user-guide/concepts/overview", + "user-guide/concepts/why-greptimedb", + "user-guide/concepts/data-model", + "user-guide/concepts/architecture", + "user-guide/concepts/storage-location", + "user-guide/concepts/key-concepts", + "user-guide/concepts/features-that-you-concern" + ] + }, + { + "type": "category", + "label": "Ingest Data", + "items": [ + "user-guide/ingest-data/overview", + { + "type": "category", + "label": "For Observerbility", + "items": [ + "user-guide/ingest-data/for-observerbility/overview", + "user-guide/ingest-data/for-observerbility/prometheus", + "user-guide/ingest-data/for-observerbility/vector", + "user-guide/ingest-data/for-observerbility/opentelemetry", + "user-guide/ingest-data/for-observerbility/influxdb-line-protocol", + "user-guide/ingest-data/for-observerbility/loki" + ] + }, + { + "type": "category", + "label": "For IoT", + "items": [ + "user-guide/ingest-data/for-iot/overview", + "user-guide/ingest-data/for-iot/sql", + { + "type": "category", + "label": "gRPC SDKs", + "items": [ + "user-guide/ingest-data/for-iot/grpc-sdks/overview", + "user-guide/ingest-data/for-iot/grpc-sdks/go", + "user-guide/ingest-data/for-iot/grpc-sdks/java" + ] + }, + "user-guide/ingest-data/for-iot/influxdb-line-protocol", + "user-guide/ingest-data/for-iot/emqx", + "user-guide/ingest-data/for-iot/opentsdb" + ] + } + ] + }, + { + "type": "category", + "label": "Query Data", + "items": [ + "user-guide/query-data/overview", + "user-guide/query-data/sql", + "user-guide/query-data/promql", + "user-guide/query-data/view", + "user-guide/query-data/cte", + "user-guide/query-data/query-external-data" + ] + }, + { + "type": "category", + "label": "Manage Data", + "items": [ + "user-guide/manage-data/overview" + ] + }, + { + "type": "category", + "label": "Integrations", + "items": [ + "user-guide/integrations/overview", + "user-guide/integrations/prometheus", + "user-guide/integrations/vector", + "user-guide/integrations/grafana", + "user-guide/integrations/superset", + "user-guide/integrations/metabase", + "user-guide/integrations/emqx", + "user-guide/integrations/dbeaver" + ] + }, + { + "type": "category", + "label": "Protocols", + "items": [ + "user-guide/protocols/overview", + "user-guide/protocols/influxdb-line-protocol", + "user-guide/protocols/opentelemetry", + "user-guide/protocols/mysql", + "user-guide/protocols/postgresql", + "user-guide/protocols/http", + "user-guide/protocols/grpc", + "user-guide/protocols/opentsdb" + ] + }, + "user-guide/timezone", + { + "type": "category", + "label": "Migrate to GreptimeDB", + "items": [ + "user-guide/migrate-to-greptimedb/migrate-from-influxdb", + "user-guide/migrate-to-greptimedb/migrate-from-mysql", + "user-guide/migrate-to-greptimedb/migrate-from-postgresql", + "user-guide/migrate-to-greptimedb/migrate-from-prometheus" + ] + }, + { + "type": "category", + "label": "Continuous Aggregation", + "items": [ + "user-guide/continuous-aggregation/overview", + "user-guide/continuous-aggregation/usecase-example", + "user-guide/continuous-aggregation/manage-flow", + "user-guide/continuous-aggregation/expression" + ] + }, + { + "type": "category", + "label": "Logs", + "items": [ + "user-guide/logs/overview", + "user-guide/logs/quick-start", + "user-guide/logs/pipeline-config", + "user-guide/logs/manage-pipelines", + "user-guide/logs/write-logs", + "user-guide/logs/query-logs" + ] + }, + { + "type": "category", + "label": "Vector Storage", + "items": [ + "user-guide/vectors/vector-type" + ] + }, + { + "type": "category", + "label": "Deployments", + "items": [ + "user-guide/deployments/overview", + { + "type": "category", + "label": "Kubernetes", + "items": [ + "user-guide/deployments/deploy-on-kubernetes/overview", + "user-guide/deployments/deploy-on-kubernetes/getting-started", + "user-guide/deployments/deploy-on-kubernetes/greptimedb-operator-management" + ] + }, + "user-guide/deployments/configuration", + { + "type": "category", + "label": "Authentication", + "items": [ + "user-guide/deployments/authentication/overview", + "user-guide/deployments/authentication/static" + ] + }, + "user-guide/deployments/run-on-android" + ] + }, + { + "type": "category", + "label": "Administration", + "items": [ + "user-guide/administration/overview", + "user-guide/administration/capacity-plan", + { + "type": "category", + "label": "Manage Data", + "items": [ + "user-guide/administration/manage-data/overview", + "user-guide/administration/manage-data/basic-table-operations", + "user-guide/administration/manage-data/table-sharding", + "user-guide/administration/manage-data/region-migration", + "user-guide/administration/manage-data/region-failover", + "user-guide/administration/manage-data/compaction" + ] + }, + { + "type": "category", + "label": "Disaster Recovery", + "items": [ + "user-guide/administration/disaster-recovery/overview", + "user-guide/administration/disaster-recovery/back-up-&-restore-data", + "user-guide/administration/disaster-recovery/dr-solution-based-on-cross-region-deployment-in-single-cluster" + ] + }, + { + "type": "category", + "label": "Remote WAL", + "items": [ + "user-guide/administration/remote-wal/quick-start", + "user-guide/administration/remote-wal/cluster-deployment" + ] + }, + { + "type": "category", + "label": "Monitoring", + "items": [ + "user-guide/administration/monitoring/overview", + "user-guide/administration/monitoring/export-metrics", + "user-guide/administration/monitoring/tracing" + ] + }, + "user-guide/administration/runtime-info", + "user-guide/administration/performance-tuning-tips", + "user-guide/administration/upgrade" + ] + } + ] + }, + { + "type": "category", + "label": "GreptimeCloud", + "items": [ + "greptimecloud/overview", + { + "type": "category", + "label": "Getting Started", + "items": [ + "greptimecloud/getting-started/overview", + "greptimecloud/getting-started/prometheus", + "greptimecloud/getting-started/mysql", + "greptimecloud/getting-started/influxdb", + "greptimecloud/getting-started/go", + "greptimecloud/getting-started/java", + "greptimecloud/getting-started/python", + "greptimecloud/getting-started/node", + "greptimecloud/getting-started/vector" + ] + }, + { + "type": "category", + "label": "Integrations", + "items": [ + "greptimecloud/integrations/prometheus", + "greptimecloud/integrations/grafana", + "greptimecloud/integrations/mysql", + "greptimecloud/integrations/postgresql", + "greptimecloud/integrations/influxdb", + "greptimecloud/integrations/kafka", + "greptimecloud/integrations/otlp", + "greptimecloud/integrations/vector", + "greptimecloud/integrations/alloy", + "greptimecloud/integrations/emqx", + "greptimecloud/integrations/streamlit", + "greptimecloud/integrations/superset", + "greptimecloud/integrations/metabase", + "greptimecloud/integrations/mindsdb", + "greptimecloud/integrations/dbeaver", + { + "type": "category", + "label": "SDK Libraries", + "items": [ + "greptimecloud/integrations/sdk-libraries/go", + "greptimecloud/integrations/sdk-libraries/java" + ] + } + ] + }, + { + "type": "category", + "label": "Migrate to GreptimeCloud", + "items": [ + "greptimecloud/migrate-to-greptimecloud/migrate-from-influxdb", + "greptimecloud/migrate-to-greptimecloud/migrate-from-prometheus" + ] + }, + { + "type": "category", + "label": "Usage & Billing", + "items": [ + "greptimecloud/usage-&-billing/overview", + "greptimecloud/usage-&-billing/request-capacity-unit", + "greptimecloud/usage-&-billing/hobby", + "greptimecloud/usage-&-billing/serverless", + "greptimecloud/usage-&-billing/dedicated", + "greptimecloud/usage-&-billing/billing" + ] + }, + { + "type": "category", + "label": "Tutorials", + "items": [ + { + "type": "category", + "label": "Monitor Host Metrics", + "items": [ + "greptimecloud/tutorials/monitor-host-metrics/prometheus", + "greptimecloud/tutorials/monitor-host-metrics/mysql", + "greptimecloud/tutorials/monitor-host-metrics/influxdb", + "greptimecloud/tutorials/monitor-host-metrics/go", + "greptimecloud/tutorials/monitor-host-metrics/java", + "greptimecloud/tutorials/monitor-host-metrics/python", + "greptimecloud/tutorials/monitor-host-metrics/node-js" + ] + } + ] + } + ] + }, + { + "type": "category", + "label": "GreptimeDB Enterprise", + "items": [ + "enterprise/overview", + { + "type": "category", + "label": "Autopilot", + "items": [ + "enterprise/autopilot/region-balancer" + ] + }, + { + "type": "category", + "label": "Deployments", + "items": [ + "enterprise/deployments/authentication", + "enterprise/deployments/audit-logging" + ] + }, + { + "type": "category", + "label": "Administration", + "items": [ + { + "type": "category", + "label": "Disaster Recovery", + "items": [ + "enterprise/administration/disaster-recovery/overview", + "enterprise/administration/disaster-recovery/dr-solution-based-on-active-active-failover" + ] + } + ] + }, + { + "type": "category", + "label": "Releases", + "items": [ + "enterprise/release-notes/release-24_11" + ] + } + ] + }, + { + "type": "category", + "label": "Reference", + "items": [ + "reference/command-lines", + "reference/sql-tools", + { + "type": "category", + "label": "SQL", + "items": [ + "reference/sql/overview", + "reference/sql/data-types", + "reference/sql/insert", + "reference/sql/case", + "reference/sql/cast", + "reference/sql/copy", + "reference/sql/drop", + "reference/sql/select", + "reference/sql/distinct", + "reference/sql/where", + "reference/sql/order_by", + "reference/sql/group_by", + "reference/sql/limit", + "reference/sql/join", + "reference/sql/range", + "reference/sql/delete", + "reference/sql/show", + "reference/sql/tql", + "reference/sql/truncate", + "reference/sql/create", + "reference/sql/describe_table", + "reference/sql/with", + "reference/sql/alter", + "reference/sql/explain", + { + "type": "category", + "label": "Functions", + "items": [ + "reference/sql/functions/overview", + "reference/sql/functions/df-functions", + "reference/sql/functions/geo", + "reference/sql/functions/json", + "reference/sql/functions/vector" + ] + }, + "reference/sql/admin", + "reference/sql/compatibility", + { + "type": "category", + "label": "Information Schema", + "items": [ + "reference/sql/information-schema/overview", + "reference/sql/information-schema/build-info", + "reference/sql/information-schema/character-sets", + "reference/sql/information-schema/collations", + "reference/sql/information-schema/collation-character-set-applicability", + "reference/sql/information-schema/columns", + "reference/sql/information-schema/engines", + "reference/sql/information-schema/key-column-usage", + "reference/sql/information-schema/partitions", + "reference/sql/information-schema/schemata", + "reference/sql/information-schema/tables", + "reference/sql/information-schema/table-constraints", + "reference/sql/information-schema/views", + "reference/sql/information-schema/flows", + "reference/sql/information-schema/region-peers", + "reference/sql/information-schema/region-statistics", + "reference/sql/information-schema/runtime-metrics", + "reference/sql/information-schema/cluster-info" + ] + } + ] + }, + "reference/http-endpoints", + "reference/telemetry", + "reference/gtctl" + ] + }, + { + "type": "category", + "label": "Contributor Guide", + "items": [ + "contributor-guide/overview", + "contributor-guide/getting-started", + { + "type": "category", + "label": "Frontend", + "items": [ + "contributor-guide/frontend/overview", + "contributor-guide/frontend/table-sharding", + "contributor-guide/frontend/distributed-querying" + ] + }, + { + "type": "category", + "label": "Datanode", + "items": [ + "contributor-guide/datanode/overview", + "contributor-guide/datanode/storage-engine", + "contributor-guide/datanode/query-engine", + "contributor-guide/datanode/data-persistence-indexing", + "contributor-guide/datanode/wal", + "contributor-guide/datanode/metric-engine" + ] + }, + { + "type": "category", + "label": "Metasrv", + "items": [ + "contributor-guide/metasrv/overview", + "contributor-guide/metasrv/admin-api", + "contributor-guide/metasrv/selector" + ] + }, + { + "type": "category", + "label": "Flownode", + "items": [ + "contributor-guide/flownode/overview", + "contributor-guide/flownode/dataflow", + "contributor-guide/flownode/arrangement" + ] + }, + { + "type": "category", + "label": "Tests", + "items": [ + "contributor-guide/tests/overview", + "contributor-guide/tests/unit-test", + "contributor-guide/tests/integration-test", + "contributor-guide/tests/sqlness-test" + ] + }, + { + "type": "category", + "label": "How To", + "items": [ + "contributor-guide/how-to/how-to-write-sdk", + "contributor-guide/how-to/how-to-use-tokio-console", + "contributor-guide/how-to/how-to-trace-greptimedb" + ] + } + ] + }, + { + "type": "category", + "label": "Release Notes", + "items": [ + "reference/about-greptimedb-version", + { + "type": "link", + "label": "Releases", + "href": "/release-notes" + } + ] + }, + { + "type": "category", + "label": "FAQ and Others", + "items": [ + "faq-and-others/overview", + "faq-and-others/faq" + ] + } + ] +} diff --git a/versions.json b/versions.json index 59c45c068..f5504ee9e 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "0.11", "0.10", "0.9", "0.8",