From 6abda20ca0fc6b44519f29cba40666cee91f012c Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 24 Jun 2025 07:20:24 -0500 Subject: [PATCH] Resolve conflicts in get-started --- content/shared/influxdb3-get-started/query.md | 98 +++++++--------- content/shared/influxdb3-get-started/setup.md | 108 +++++++++--------- content/shared/influxdb3-get-started/write.md | 20 ++-- 3 files changed, 106 insertions(+), 120 deletions(-) diff --git a/content/shared/influxdb3-get-started/query.md b/content/shared/influxdb3-get-started/query.md index a5f4729f7..86c92fd9e 100644 --- a/content/shared/influxdb3-get-started/query.md +++ b/content/shared/influxdb3-get-started/query.md @@ -1,17 +1,17 @@ -### Query data - -InfluxDB 3 supports native SQL for querying, in addition to InfluxQL, an -SQL-like language customized for time series queries. + +{{% product-name %}} supports both native SQL and InfluxQL for querying data. InfluxQL is +an SQL-like query language designed for InfluxDB v1 and customized for time +series queries. {{% show-in "core" %}} {{< product-name >}} limits -query time ranges to 72 hours (both recent and historical) to ensure query performance. -For more information about the 72-hour limitation, see the -[update on InfluxDB 3 Core’s 72-hour limitation](https://www.influxdata.com/blog/influxdb3-open-source-public-alpha-jan-27/). +query time ranges to approximately 72 hours (both recent and historical) to +ensure query performance. For more information about the 72-hour limitation, see +the [update on InfluxDB 3 Core’s 72-hour limitation](https://www.influxdata.com/blog/influxdb3-open-source-public-alpha-jan-27/). {{% /show-in %}} > [!Note] -> Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3. +> Flux, the language introduced in InfluxDB v2, is **not** supported in InfluxDB 3. @@ -34,7 +34,12 @@ To get started querying data in {{% product-name %}}, use the [`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) and provide the following: -The `query` subcommand includes options to help ensure that the right database is queried with the correct permissions. Only the `--database` option is required, but depending on your specific setup, you may need to pass other options, such as host, port, and token. +- `-H`, `--host`: The host URL of the server _(default is `http://127.0.0.1:8181`)_ +- `-d`, `--database`: _({{% req %}})_ The name of the database to query +- `-l`, `--language`: The query language of the provided query string + - `sql` _(default)_ + - `influxql` +- SQL or InfluxQL query as a string > [!Important] > If the `INFLUXDB3_AUTH_TOKEN` environment variable defined in @@ -42,62 +47,41 @@ The `query` subcommand includes options to help ensure that the right database i > isn't set in your environment, set it or provide your token using > the `-t, --token` option in your command. -#### Example: query `“SHOW TABLES”` on the `servers` database: - -```console -$ influxdb3 query --database servers "SHOW TABLES" -+---------------+--------------------+--------------+------------+ -| table_catalog | table_schema | table_name | table_type | -+---------------+--------------------+--------------+------------+ -| public | iox | cpu | BASE TABLE | -| public | information_schema | tables | VIEW | -| public | information_schema | views | VIEW | -| public | information_schema | columns | VIEW | -| public | information_schema | df_settings | VIEW | -| public | information_schema | schemata | VIEW | -+---------------+--------------------+--------------+------------+ -``` - -#### Example: query the `cpu` table, limiting to 10 rows: - -```console -$ influxdb3 query --database servers "SELECT DISTINCT usage_percent, time FROM cpu LIMIT 10" -+---------------+---------------------+ -| usage_percent | time | -+---------------+---------------------+ -| 63.4 | 2024-02-21T19:25:00 | -| 25.3 | 2024-02-21T19:06:40 | -| 26.5 | 2024-02-21T19:31:40 | -| 70.1 | 2024-02-21T19:03:20 | -| 83.7 | 2024-02-21T19:30:00 | -| 55.2 | 2024-02-21T19:00:00 | -| 80.5 | 2024-02-21T19:05:00 | -| 60.2 | 2024-02-21T19:33:20 | -| 20.5 | 2024-02-21T18:58:20 | -| 85.2 | 2024-02-21T19:28:20 | -+---------------+---------------------+ -``` - -### Query using the CLI for InfluxQL - -[InfluxQL](/influxdb3/version/reference/influxql/) is an SQL-like language developed by InfluxData with specific features tailored for leveraging and working with InfluxDB. It’s compatible with all versions of InfluxDB, making it a good choice for interoperability across different InfluxDB installations. - -To query using InfluxQL, enter the `influxdb3 query` subcommand and specify `influxql` in the language option--for example: +To query the home sensor sample data you wrote in +[Write data to {{% product-name %}}](/influxdb3/version/get-started/write/#write-data-using-the-cli), +run the following command: {{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + ```bash influxdb3 query \ --database DATABASE_NAME \ - --token AUTH_TOKEN \ - --language influxql \ - "SELECT DISTINCT usage_percent FROM cpu WHERE time >= now() - 1d" + "SELECT * FROM home ORDER BY time" ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash +influxdb3 query \ + --database DATABASE_NAME \ + --language influxql \ + "SELECT * FROM home" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + {{% /code-placeholders %}} -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to query -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}} +_Replace {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}} +with the name of the database to query._ To query from a specific time range, use the `WHERE` clause to designate the boundaries of your time range. diff --git a/content/shared/influxdb3-get-started/setup.md b/content/shared/influxdb3-get-started/setup.md index 968fc87ea..fdba4a2b3 100644 --- a/content/shared/influxdb3-get-started/setup.md +++ b/content/shared/influxdb3-get-started/setup.md @@ -27,20 +27,6 @@ Use the [`influxdb3 serve` command](/influxdb3/version/reference/cli/influxdb3/s to start {{% product-name %}}. Provide the following: -- `--object-store`: Specifies the type of object store to use. - InfluxDB supports the following: - - - `file` _(default)_: local file system - - `memory`: in memory _(no object persistence)_ - - `memory-throttled`: like `memory` but with latency and throughput that - somewhat resembles a cloud-based object store - - `s3`: AWS S3 and S3-compatible services like Ceph or Minio - - `google`: Google Cloud Storage - - `azure`: Azure Blob Storage -{{% show-in "core" %}} -- `--node-id`: A string identifier that distinguishes individual server instances. - This forms the final part of the storage path: `/`. -{{% /show-in %}} {{% show-in "enterprise" %}} - `--node-id`: A string identifier that distinguishes individual server instances within the cluster. This forms the final part of the storage path: @@ -51,11 +37,24 @@ Provide the following: The storage path follows the pattern `//`. In a multi-node setup, this ID is used to reference the entire cluster. {{% /show-in %}} +{{% show-in "core" %}} +- `--node-id`: A string identifier that distinguishes individual server instances. + This forms the final part of the storage path: `/`. +{{% /show-in %}} +- `--object-store`: Specifies the type of object store to use. + InfluxDB supports the following: + + - `file` _(default)_: local file system + - `memory`: in memory _(no object persistence)_ + - `memory-throttled`: like `memory` but with latency and throughput that + somewhat resembles a cloud-based object store + - `s3`: AWS S3 and S3-compatible services like Ceph or Minio + - `google`: Google Cloud Storage + - `azure`: Azure Blob Storage -### Configure for your object store - -Depending on the object store type, you may need to provide additional -options, such as access credentials, for your object store configuration. + > [!Note] + > Examples in this getting started guide use the `file` object + > store to persist data to your local disk. The following examples show how to start {{% product-name %}} with different object store configurations. @@ -73,10 +72,32 @@ object store configurations. > separation between clusters and individual nodes. > {{% /show-in %}} -_For this getting started guide, use the `file` object store to persist data to -your local disk._ +For this getting started guide, use the `file` object store to persist data to +your local disk. -### Object store examples +{{% show-in "enterprise" %}} +```bash +# File system object store +# Provide the filesystem directory +influxdb3 serve \ + --node-id host01 \ + --cluster-id cluster01 \ + --object-store file \ + --data-dir ~/.influxdb3 +``` +{{% /show-in %}} +{{% show-in "core" %}} +```bash +# File system object store +# Provide the file system directory +influxdb3 serve \ + --node-id host01 \ + --object-store file \ + --data-dir ~/.influxdb3 +``` +{{% /show-in %}} + +### {{% product-name %}} store examples {{< expand-wrapper >}} {{% expand "File system object store" %}} @@ -339,11 +360,16 @@ influxdb3 serve --help ## Set up licensing When you first start a new instance, {{% product-name %}} prompts you to select a -license type. InfluxDB 3 Enterprise licenses authorize the use of the -InfluxDB 3 Enterprise software and apply to a single cluster. Licenses are -primarily based on the number of CPUs InfluxDB can use, but there are other -limitations depending on the license type. The following InfluxDB 3 Enterprise -license types are available: + +license type. + +InfluxDB 3 Enterprise licenses: + +- **Authorize** usage of InfluxDB 3 Enterprise software for a single cluster. +- **Apply per cluster**, with limits based primarily on CPU cores. +- **Vary by license type**, each offering different capabilities and restrictions. + +### Available license types: - **Trial**: 30-day trial license with full access to InfluxDB 3 Enterprise capabilities. - **At-Home**: For at-home hobbyist use with limited access to InfluxDB 3 Enterprise capabilities. @@ -356,32 +382,8 @@ license types are available: > you start a new instance, provide your email address with the > `--license-email` option or the > `INFLUXDB3_LICENSE_EMAIL` environment variable to bypass the licensing -> email prompt--for example: +> email prompt--for example, in a Docker Compose file: > -> {{< code-tabs-wrapper >}} -> {{% code-tabs %}} -> [Docker CLI](#) -> [Docker Compose file](#) -> {{% /code-tabs %}} -> {{% code-tab-content %}} -> {{% code-placeholders "EMAIL_ADDRESS" %}} -> ```bash -> docker run -d --name influxdb3-enterprise \ -> -v "$PWD/data:/var/lib/influxdb3" \ -> -v "$PWD/plugins:/plugins" \ -> -p 8181:8181 \ -> quay.io/influxdb/influxdb3-enterprise:latest \ -> serve \ -> --cluster-id cluster1 \ -> --node-id node1 \ -> --plugin-dir /plugins \ -> --object-store file \ -> --data-dir /var/lib/influxdb3 -> ``` -> {{% /code-placeholders %}} -> - Replace {{% code-placeholder-key %}}`EMAIL_ADDRESS`{{% /code-placeholder-key %}} with the email you want to associate with the license. -> {{% /code-tab-content %}} -> {{% code-tab-content %}} > {{% code-placeholders "EMAIL_ADDRESS" %}} > ```yaml > # compose.yaml @@ -404,9 +406,7 @@ license types are available: > {{% /code-placeholders %}} > {{% code-placeholder-key %}}`EMAIL_ADDRESS`{{% /code-placeholder-key %}} is > the email you want to associate with the license. This example shows how -> to reference an email address set in your `.env` file. -> {{% /code-tab-content %}} -> {{< /code-tabs-wrapper >}} +> to reference a variable in your `.env` file. > > _Currently, if you use the prompt to enter your email address, a bug may > prevent the container from generating the license ._ diff --git a/content/shared/influxdb3-get-started/write.md b/content/shared/influxdb3-get-started/write.md index 1182d73de..1e2b63048 100644 --- a/content/shared/influxdb3-get-started/write.md +++ b/content/shared/influxdb3-get-started/write.md @@ -1,12 +1,16 @@ -### Write data + -InfluxDB is a schema-on-write database. You can start writing data and InfluxDB creates the logical database, tables, and their schemas on the fly. -After a schema is created, InfluxDB validates future write requests against it before accepting the data. -Subsequent requests can add new fields on-the-fly, but can't add new tags. +{{% product-name %}} is designed for high write-throughput and uses an efficient, +human-readable write syntax called _[line protocol](#line-protocol)_. InfluxDB +is a schema-on-write database, meaning you can start writing data and InfluxDB +creates the logical database, tables, and their schemas automatically, without +any required intervention. Once InfluxDB creates the schema, it validates future +write requests against the schema before accepting new data. +Both new tags and fields can be added later as your schema changes. {{% show-in "core" %}} > [!Note] -> #### Core is optimized for recent data +> #### InfluxDB 3 Core is optimized for recent data > > {{% product-name %}} is optimized for recent data but accepts writes from any time period. > The system persists data to Parquet files for historical analysis with [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/) or third-party tools. @@ -139,7 +143,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 {{% /influxdb/custom-timestamps %}} -## Write data using the CLI +## Write data using the CLI To quickly get started writing data, use the [`influxdb3 write` command](/influxdb3/version/reference/cli/influxdb3/write/). @@ -150,8 +154,6 @@ Include the following: environment variable is already set)_ - Quoted line protocol data via standard input (stdin) or a file -### Write data via standard input (stdin) - {{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} ```bash influxdb3 write \ @@ -197,7 +199,7 @@ In the code samples, replace the following placeholders with your values: ### Write data from a file -Pass the `--file` option to write line protocol you have saved to a file--for example, save the +To write line protocol you have saved to a file, pass the `--file` option--for example, save the [sample line protocol](#home-sensor-data-line-protocol) to a file named `sensor_data` and then enter the following command: