diff --git a/.context/README.md b/.context/README.md new file mode 100644 index 000000000..79b6a4459 --- /dev/null +++ b/.context/README.md @@ -0,0 +1,44 @@ +# Context Files for LLMs and AI Tools + +This directory contains plans, reports, and other context files that are: +- Used to provide context to LLMs during development +- Not committed to the repository +- May be transient or belong in other repositories + +## Directory Structure + +- `plans/` - Documentation plans and roadmaps +- `reports/` - Generated reports and analyses +- `research/` - Research notes and findings +- `templates/` - Reusable templates for Claude interactions + +## Usage + +Place files here that you want to reference--for example, using @ mentions in Claude--such as: +- Documentation planning documents +- API migration guides +- Performance reports +- Architecture decisions + +## Example Structure + +``` +.context/ +├── plans/ +│ ├── v3.2-release-plan.md +│ └── api-migration-guide.md +├── reports/ +│ ├── weekly-progress-2025-07.md +│ └── pr-summary-2025-06.md +├── research/ +│ └── competitor-analysis.md +└── templates/ + └── release-notes-template.md +``` + +## Best Practices + +1. Use descriptive filenames that indicate the content and date +2. Keep files organized in appropriate subdirectories +3. Consider using date prefixes for time-sensitive content (e.g., `2025-07-01-meeting-notes.md`) +4. Remove outdated files periodically to keep the context relevant \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 505688122..a4c0b7aaa 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,13 +1,16 @@ -# GitHub Copilot Instructions for InfluxData Documentation +# Instructions for InfluxData Documentation ## Purpose and scope -GitHub Copilot should help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting. +Help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting. ## Documentation structure - **Product version data**: `/data/products.yml` -- **Products**: +- **InfluxData products**: + - InfluxDB 3 Explorer + - Documentation source path: `/content/influxdb3/explorer` + - Published for the web: https://docs.influxdata.com/influxdb3/explorer/ - InfluxDB 3 Core - Documentation source path: `/content/influxdb3/core` - Published for the web: https://docs.influxdata.com/influxdb3/core/ @@ -92,7 +95,8 @@ GitHub Copilot should help document InfluxData products by creating clear, accur ## Markdown and shortcodes -- Include proper frontmatter for each page: +- Include proper frontmatter for Markdown pages in `content/**/*.md` (except for + shared content files in `content/shared/`): ```yaml title: # Page title (h1) @@ -180,3 +184,17 @@ Table: keys: [_start, _stop, _field, _measurement] ## Related repositories - **Internal documentation assistance requests**: https://github.com/influxdata/DAR/issues Documentation + +## Additional instruction files + +For specific workflows and content types, also refer to: + +- **InfluxDB 3 code placeholders**: `.github/instructions/influxdb3-code-placeholders.instructions.md` - Guidelines for placeholder formatting, descriptions, and shortcode usage in InfluxDB 3 documentation +- **Contributing guidelines**: `.github/instructions/contributing.instructions.md` - Detailed style guidelines, shortcode usage, frontmatter requirements, and development workflows +- **Content-specific instructions**: Check `.github/instructions/` directory for specialized guidelines covering specific documentation patterns and requirements + +## Integration with specialized instructions + +When working on InfluxDB 3 documentation (Core/Enterprise), prioritize the placeholder guidelines from `influxdb3-code-placeholders.instructions.md`. + +For general documentation structure, shortcodes, and development workflows, follow the comprehensive guidelines in `contributing.instructions.md`. diff --git a/.github/instructions/contributing.instructions.md b/.github/instructions/contributing.instructions.md index 2774f384f..b5b5fdd59 100644 --- a/.github/instructions/contributing.instructions.md +++ b/.github/instructions/contributing.instructions.md @@ -2,11 +2,11 @@ applyTo: "content/**/*.md, layouts/**/*.html" --- -# GitHub Copilot Instructions for InfluxData Documentation +# Contributing instructions for InfluxData Documentation ## Purpose and scope -GitHub Copilot should help document InfluxData products +Help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, shortcodes, and formatting. @@ -46,184 +46,8 @@ We strongly recommend letting them run, but you can skip them (and avoid installing related dependencies) by including the `--no-verify` flag with your commit--for example, enter the following command in your terminal: -```sh +sh git commit -m "" --no-verify -``` - -### Install Node.js dependencies - -To install dependencies listed in package.json: - -1. Install [Node.js](https://nodejs.org/en) for your system. -2. Install [Yarn](https://yarnpkg.com/getting-started/install) for your system. -3. Run `yarn` to install dependencies (including Hugo). -4. Install the Yarn package manager and run `yarn` to install project dependencies. - -`package.json` contains dependencies used in `/assets/js` JavaScript code and -dev dependencies used in pre-commit hooks for linting, syntax-checking, and testing. - -Dev dependencies include: - -- [Lefthook](https://github.com/evilmartians/lefthook): configures and -manages git pre-commit and pre-push hooks for linting and testing Markdown content. -- [prettier](https://prettier.io/docs/en/): formats code, including Markdown, according to style rules for consistency -- [Cypress]: e2e testing for UI elements and URLs in content - -### Install Docker - -docs-v2 includes Docker configurations (`compose.yaml` and Dockerfiles) for running the Vale style linter and tests for code blocks (Shell, Bash, and Python) in Markdown files. - -Install [Docker](https://docs.docker.com/get-docker/) for your system. - -#### Build the test dependency image - -After you have installed Docker, run the following command to build the test -dependency image, `influxdata:docs-pytest`. -The tests defined in `compose.yaml` use the dependencies and execution -environment from this image. - -```bash -docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest . -``` - -### Run the documentation locally (optional) - -To run the documentation locally, follow the instructions provided in the README. - -### Install Visual Studio Code extensions - -If you use Microsoft Visual Studio (VS) Code, you can install extensions -to help you navigate, check, and edit files. - -docs-v2 contains a `./.vscode/settings.json` that configures the following extensions: - -- Comment Anchors: recognizes tags (for example, `//SOURCE`) and makes links and filepaths clickable in comments. -- Vale: shows linter errors and suggestions in the editor. -- YAML Schemas: validates frontmatter attributes. - -### Make your changes - -Make your suggested changes being sure to follow the [style and formatting guidelines](#style--formatting) outline below. - -## Lint and test your changes - -`package.json` contains scripts for running tests and linting. - -### Automatic pre-commit checks - -docs-v2 uses Lefthook to manage Git hooks that run during pre-commit and pre-push. The hooks run the scripts defined in `package.json` to lint Markdown and test code blocks. -When you try to commit changes (`git commit`), Git runs -the commands configured in `lefthook.yml` which pass your **staged** files to Vale, -Prettier, Cypress (for UI tests and link-checking), and Pytest (for testing Python and shell code in code blocks). - -### Skip pre-commit hooks - -**We strongly recommend running linting and tests**, but you can skip them -(and avoid installing dependencies) -by including the `LEFTHOOK=0` environment variable or the `--no-verify` flag with -your commit--for example: - -```sh -git commit -m "" --no-verify -``` - -```sh -LEFTHOOK=0 git commit -``` - -### Set up test scripts and credentials - -Tests for code blocks require your InfluxDB credentials and other typical -InfluxDB configuration. - -To set up your docs-v2 instance to run tests locally, do the following: - -1. **Set executable permissions on test scripts** in `./test/src`: - - ```sh - chmod +x ./test/src/*.sh - ``` - -2. **Create credentials for tests**: - - - Create databases, buckets, and tokens for the product(s) you're testing. - - If you don't have access to a Clustered instance, you can use your -Cloud Dedicated instance for testing in most cases. To avoid conflicts when - running tests, create separate Cloud Dedicated and Clustered databases. - -1. **Create .env.test**: Copy the `./test/env.test.example` file into each - product directory to test and rename the file as `.env.test`--for example: - - ```sh - ./content/influxdb/cloud-dedicated/.env.test - ``` - -2. Inside each product's `.env.test` file, assign your InfluxDB credentials to - environment variables: - - - Include the usual `INFLUX_` environment variables - - In - `cloud-dedicated/.env.test` and `clustered/.env.test` files, also define the - following variables: - - - `ACCOUNT_ID`, `CLUSTER_ID`: You can find these values in your `influxctl` - `config.toml` configuration file. - - `MANAGEMENT_TOKEN`: Use the `influxctl management create` command to generate - a long-lived management token to authenticate Management API requests - - See the substitution - patterns in `./test/src/prepare-content.sh` for the full list of variables you may need to define in your `.env.test` files. - -3. For influxctl commands to run in tests, move or copy your `config.toml` file - to the `./test` directory. - -> [!Warning] -> -> - The database you configure in `.env.test` and any written data may -be deleted during test runs. -> - Don't add your `.env.test` files to Git. To prevent accidentally adding credentials to the docs-v2 repo, -Git is configured to ignore `.env*` files. Consider backing them up on your local machine in case of accidental deletion. - -#### Test shell and python code blocks - -[pytest-codeblocks](https://github.com/nschloe/pytest-codeblocks/tree/main) extracts code from python and shell Markdown code blocks and executes assertions for the code. -If you don't assert a value (using a Python `assert` statement), `--codeblocks` considers a non-zero exit code to be a failure. - -**Note**: `pytest --codeblocks` uses Python's `subprocess.run()` to execute shell code. - -You can use this to test CLI and interpreter commands, regardless of programming -language, as long as they return standard exit codes. - -To make the documented output of a code block testable, precede it with the -`` tag and **omit the code block language -descriptor**--for example, in your Markdown file: - -##### Example markdown - -```python -print("Hello, world!") -``` - - - -The next code block is treated as an assertion. -If successful, the output is the following: - -``` -Hello, world! -``` - -For commands, such as `influxctl` CLI commands, that require launching an -OAuth URL in a browser, wrap the command in a subshell and redirect the output -to `/shared/urls.txt` in the container--for example: - -```sh -# Test the preceding command outside of the code block. -# influxctl authentication requires TTY interaction-- -# output the auth URL to a file that the host can open. -script -c "influxctl user list " \ - /dev/null > /shared/urls.txt -``` You probably don't want to display this syntax in the docs, which unfortunately means you'd need to include the test block separately from the displayed code @@ -236,25 +60,6 @@ pytest-codeblocks will still collect and run the code block. pytest-codeblocks has features for skipping tests and marking blocks as failed. To learn more, see the pytest-codeblocks README and tests. -#### Troubleshoot tests - -### Pytest collected 0 items - -Potential reasons: - -- See the test discovery options in `pytest.ini`. -- For Python code blocks, use the following delimiter: - - ```python - # Codeblocks runs this block. - ``` - - `pytest --codeblocks` ignores code blocks that use the following: - - ```py - # Codeblocks ignores this block. - ``` - ### Vale style linting docs-v2 includes Vale writing style linter configurations to enforce documentation writing style rules, guidelines, branding, and vocabulary terms. @@ -262,97 +67,10 @@ docs-v2 includes Vale writing style linter configurations to enforce documentati To run Vale, use the Vale extension for your editor or the included Docker configuration. For example, the following command runs Vale in a container and lints `*.md` (Markdown) files in the path `./content/influxdb/cloud-dedicated/write-data/` using the specified configuration for `cloud-dedicated`: -```sh -docker compose run -T vale --config=content/influxdb/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb/cloud-dedicated/write-data/**/*.md -``` - -The output contains error-level style alerts for the Markdown content. - -**Note**: We strongly recommend running Vale, but it's not included in the -docs-v2 pre-commit hooks](#automatic-pre-commit-checks) for now. -You can include it in your own Git hooks. - -If a file contains style, spelling, or punctuation problems, -the Vale linter can raise one of the following alert levels: - -- **Error**: - - Problems that can cause content to render incorrectly - - Violations of branding guidelines or trademark guidelines - - Rejected vocabulary terms -- **Warning**: General style guide rules and best practices -- **Suggestion**: Style preferences that may require refactoring or updates to an exceptions list - -### Integrate Vale with your editor - -To integrate Vale with VSCode: - -1. Install the [Vale VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) extension. -2. In the extension settings, set the `Vale:Vale CLI:Path` value to the path of your Vale binary (`${workspaceFolder}/node_modules/.bin/vale` for Yarn-installed Vale). - -To use with an editor other than VSCode, see the [Vale integration guide](https://vale.sh/docs/integrations/guide/). - -### Configure style rules - -`/.ci/vale/styles/` contains configuration files for the custom `InfluxDataDocs` style. - -The easiest way to add accepted or rejected spellings is to enter your terms (or regular expression patterns) into the Vocabulary files at `.ci/vale/styles/config/vocabularies`. - -To add accepted/rejected terms for specific products, configure a style for the product and include a `Branding.yml` configuration. As an example, see `content/influxdb/cloud-dedicated/.vale.ini` and `.ci/vale/styles/Cloud-Dedicated/Branding.yml`. - -To learn more about configuration and rules, see [Vale configuration](https://vale.sh/docs/topics/config). - -### Submit a pull request - -Push your changes up to your forked repository, then [create a new pull request](https://help.github.com/articles/creating-a-pull-request/). - -## Style & Formatting - -### Markdown - -Most docs-v2 documentation content uses [Markdown](https://en.wikipedia.org/wiki/Markdown). - -_Some parts of the documentation, such as `./api-docs`, contain Markdown within YAML and rely on additional tooling._ - -### Semantic line feeds - -Use [semantic line feeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/). -Separating each sentence with a new line makes it easy to parse diffs with the human eye. - -**Diff without semantic line feeds:** - -```diff +diff -Data is taking off. This data is time series. You need a database that specializes in time series. You should check out InfluxDB. +Data is taking off. This data is time series. You need a database that specializes in time series. You need InfluxDB. -``` - -**Diff with semantic line feeds:** - -```diff -Data is taking off. -This data is time series. -You need a database that specializes in time series. --You should check out InfluxDB. -+You need InfluxDB. -``` - -### Article headings - -Use only h2-h6 headings in markdown content. -h1 headings act as the page title and are populated automatically from the `title` frontmatter. -h2-h6 headings act as section headings. - -### Image naming conventions - -Save images using the following naming format: `project/version-context-description.png`. -For example, `influxdb/2-0-visualizations-line-graph.png` or `influxdb/2-0-tasks-add-new.png`. -Specify a version other than 2.0 only if the image is specific to that version. - -## Page frontmatter - -Every documentation page includes frontmatter which specifies information about the page. -Frontmatter populates variables in page templates and the site's navigation menu. - -```yaml +yaml title: # Title of the page used in the page's h1 seotitle: # Page title used in the html title and used in search engine results list_title: # Title used in article lists generated using the {{< children >}} shortcode @@ -375,6 +93,9 @@ list_query_example:# Code examples included with article descriptions in childre # References to examples in data/query_examples canonical: # Path to canonical page, overrides auto-gen'd canonical URL v2: # Path to v2 equivalent page +alt_links: # Alternate pages in other products/versions for cross-product navigation + cloud-dedicated: /influxdb3/cloud-dedicated/path/to/page/ + core: /influxdb3/core/path/to/page/ prepend: # Prepend markdown content to an article (especially powerful with cascade) block: # (Optional) Wrap content in a block style (note, warn, cloud) content: # Content to prepend to article @@ -384,72 +105,12 @@ append: # Append markdown content to an article (especially powerful with cascad metadata: [] # List of metadata messages to include under the page h1 updated_in: # Product and version the referenced feature was updated in (displayed as a unique metadata) source: # Specify a file to pull page content from (typically in /content/shared/) -``` - -### Title usage - -##### `title` - -The `title` frontmatter populates each page's HTML `h1` heading tag. -It shouldn't be overly long, but should set the context for users coming from outside sources. - -##### `seotitle` - -The `seotitle` frontmatter populates each page's HTML `title` attribute. -Search engines use this in search results (not the page's h1) and therefore it should be keyword optimized. - -##### `list_title` - -The `list_title` frontmatter determines an article title when in a list generated -by the [`{{< children >}}` shortcode](#generate-a-list-of-children-articles). - -##### `menu > name` - -The `name` attribute under the `menu` frontmatter determines the text used in each page's link in the site navigation. -It should be short and assume the context of its parent if it has one. - -#### Page Weights - -To ensure pages are sorted both by weight and their depth in the directory -structure, pages should be weighted in "levels." -All top level pages are weighted 1-99. -The next level is 101-199. -Then 201-299 and so on. - -_**Note:** `_index.md` files should be weighted one level up from the other `.md` files in the same directory._ - -### Related content - -Use the `related` frontmatter to include links to specific articles at the bottom of an article. - -- If the page exists inside of this documentation, just include the path to the page. - It will automatically detect the title of the page. -- If the page exists inside of this documentation, but you want to customize the link text, - include the path to the page followed by a comma, and then the custom link text. - The path and custom text must be in that order and separated by a comma and a space. -- If the page exists outside of this documentation, include the full URL and a title for the link. - The link and title must be in that order and separated by a comma and a space. - -```yaml +yaml related: - /v2.0/write-data/quick-start - /v2.0/write-data/quick-start, This is custom text for an internal link - https://influxdata.com, This is an external link -``` - -### Canonical URLs - -Search engines use canonical URLs to accurately rank pages with similar or identical content. -The `canonical` HTML meta tag identifies which page should be used as the source of truth. - -By default, canonical URLs are automatically generated for each page in the InfluxData -documentation using the latest version of the current product and the current path. - -Use the `canonical` frontmatter to override the auto-generated canonical URL. - -_**Note:** The `canonical` frontmatter supports the [`{{< latest >}}` shortcode](#latest-links)._ - -```yaml +yaml canonical: /path/to/canonical/doc/ # OR @@ -466,6 +127,29 @@ add the following frontmatter to the 1.x page: v2: /influxdb/v2.0/get-started/ ``` +### Alternative links for cross-product navigation + +Use the `alt_links` frontmatter to specify equivalent pages in other InfluxDB products, +for example, when a page exists at a different path in a different version or if +the feature doesn't exist in that product. +This enables the product switcher to navigate users to the corresponding page when they +switch between products. If a page doesn't exist in another product (for example, an +Enterprise-only feature), point to the nearest parent page if relevant. + +```yaml +alt_links: + cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/ + cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/ + core: /influxdb3/core/reference/cli/influxdb3/update/ # Points to parent if exact page doesn't exist +``` + +Supported product keys for InfluxDB 3: +- `core` +- `enterprise` +- `cloud-serverless` +- `cloud-dedicated` +- `clustered` + ### Prepend and append content to a page Use the `prepend` and `append` frontmatter to add content to the top or bottom of a page. @@ -481,47 +165,7 @@ append: | Use this frontmatter with [cascade](#cascade) to add the same content to all children pages as well. -```yaml -cascade: - append: | - > [!Note] - > #### This is example markdown content - > This is just an example note block that gets appended to the article. -``` - -### Cascade - -To automatically apply frontmatter to a page and all of its children, use the -[`cascade` frontmatter](https://gohugo.io/content-management/front-matter/#front-matter-cascade) -built in into Hugo. - -```yaml -title: Example page -description: Example description -cascade: - layout: custom-layout -``` - -`cascade` applies the frontmatter to all children unless the child already includes -those frontmatter keys. Frontmatter defined on the page overrides frontmatter -"cascaded" from a parent. - -## Use shared content in a page - -Use the `source` frontmatter to specify a shared file to use to populate the -page content. Shared files are typically stored in the `/content/shared` directory. - -When building shared content, use the `show-in` and `hide-in` shortcodes to show -or hide blocks of content based on the current InfluxDB product/version. -For more information, see [show-in](#show-in) and [hide-in](#hide-in). - -## Shortcodes - -### Notes and warnings - -Shortcodes are available for formatting notes and warnings in each article: - -```md +md {{% note %}} Insert note markdown content here. {{% /note %}} @@ -529,148 +173,18 @@ Insert note markdown content here. {{% warn %}} Insert warning markdown content here. {{% /warn %}} -``` -### Product data - -Display the full product name and version name for the current page--for example: - -- InfluxDB 3 Core -- InfluxDB 3 Cloud Dedicated - -```md -{{% product-name %}} -``` - -Display the short version name (part of the key used in `products.yml`) from the current page URL--for example: - -- `/influxdb3/core` returns `core` - -```md -{{% product-key %}} -``` - -#### Enterprise name - -The name used to refer to InfluxData's enterprise offering is subject to change. -To facilitate easy updates in the future, use the `enterprise-name` shortcode -when referencing the enterprise product. -This shortcode accepts a `"short"` parameter which uses the "short-name". - -``` This is content that references {{< enterprise-name >}}. This is content that references {{< enterprise-name "short" >}}. -``` - -Product names are stored in `data/products.yml`. - -#### Enterprise link - -References to InfluxDB Enterprise are often accompanied with a link to a page where -visitors can get more information about the Enterprise offering. -This link is subject to change. -Use the `enterprise-link` shortcode when including links to more information about -InfluxDB Enterprise. - -``` -Find more info [here][{{< enterprise-link >}}] -``` - -### Latest patch version - -Use the `{{< latest-patch >}}` shortcode to add the latest patch version of a product. -By default, this shortcode parses the product and minor version from the URL. -To specify a specific product and minor version, use the `product` and `version` arguments. -Easier to maintain being you update the version number in the `data/products.yml` file instead of updating individual links and code examples. - -```md +md {{< latest-patch >}} {{< latest-patch product="telegraf" >}} {{< latest-patch product="chronograf" version="1.7" >}} -``` - -### Latest influx CLI version - -Use the `{{< latest-patch cli=true >}}` shortcode to add the latest version of the `influx` -CLI supported by the minor version of InfluxDB. -By default, this shortcode parses the minor version from the URL. -To specify a specific minor version, use the `version` argument. -Maintain CLI version numbers in the `data/products.yml` file instead of updating individual links and code examples. - -```md -{{< latest-patch cli=true >}} - -{{< latest-cli version="2.1" >}} -``` - -### API endpoint - -Use the `{{< api-endpoint >}}` shortcode to generate a code block that contains -a colored request method, a specified API endpoint, and an optional link to -the API reference documentation. -Provide the following arguments: - -- **method**: HTTP request method (get, post, patch, put, or delete) -- **endpoint**: API endpoint -- **api-ref**: Link the endpoint to a specific place in the API documentation -- **influxdb_host**: Specify which InfluxDB product host to use - _if the `endpoint` contains the `influxdb/host` shortcode_. - Uses the current InfluxDB product as default. - Supports the following product values: - - - oss - - cloud - - serverless - - dedicated - - clustered - -```md +md {{< api-endpoint method="get" endpoint="/api/v2/tasks" api-ref="/influxdb/cloud/api/#operation/GetTasks">}} -``` - -```md -{{< api-endpoint method="get" endpoint="{{< influxdb/host >}}/api/v2/tasks" influxdb_host="cloud">}} -``` - -### Tabbed Content - -To create "tabbed" content (content that is changed by a users' selection), use the following three shortcodes in combination: - -`{{< tabs-wrapper >}}` -This shortcode creates a wrapper or container for the tabbed content. -All UI interactions are limited to the scope of each container. -If you have more than one "group" of tabbed content in a page, each needs its own `tabs-wrapper`. -This shortcode must be closed with `{{< /tabs-wrapper >}}`. - -**Note**: The `<` and `>` characters used in this shortcode indicate that the contents should be processed as HTML. - -`{{% tabs %}}` -This shortcode creates a container for buttons that control the display of tabbed content. -It should contain simple markdown links with anonymous anchors (`#`). -The link text is used as the button text. -This shortcode must be closed with `{{% /tabs %}}`. - -**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown. - -The `{{% tabs %}}` shortcode has an optional `style` argument that lets you -assign CSS classes to the tags HTML container. The following classes are available: - -- **small**: Tab buttons are smaller and don't scale to fit the width. -- **even-wrap**: Prevents uneven tab widths when tabs are forced to wrap. - -`{{% tab-content %}}` -This shortcode creates a container for a content block. -Each content block in the tab group needs to be wrapped in this shortcode. -**The number of `tab-content` blocks must match the number of links provided in the `tabs` shortcode** -This shortcode must be closed with `{{% /tab-content %}}`. - -**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown. - -#### Example tabbed content group - -```md +md {{< tabs-wrapper >}} {{% tabs %}} @@ -687,592 +201,77 @@ Markdown content for tab 2. {{% /tab-content %}} {{< /tabs-wrapper >}} -``` - -#### Tabbed code blocks - -Shortcodes are also available for tabbed code blocks primarily used to give users -the option to choose between different languages and syntax. -The shortcode structure is the same as above, but the shortcode names are different: - -`{{< code-tabs-wrapper >}}` -`{{% code-tabs %}}` -`{{% code-tab-content %}}` - -````md -{{< code-tabs-wrapper >}} - -{{% code-tabs %}} -[Flux](#) -[InfluxQL](#) -{{% /code-tabs %}} - -{{% code-tab-content %}} - -```js -data = from(bucket: "example-bucket") - |> range(start: -15m) - |> filter(fn: (r) => - r._measurement == "mem" and - r._field == "used_percent" - ) -``` {{% /code-tab-content %}} {{% code-tab-content %}} -```sql -SELECT "used_percent" -FROM "telegraf"."autogen"."mem" -WHERE time > now() - 15m -``` - -{{% /code-tab-content %}} - -{{< /code-tabs-wrapper >}} -```` - -#### Link to tabbed content - -To link to tabbed content, click on the tab and use the URL parameter shown. -It will have the form `?t=`, plus a string. -For example: - -``` -[Windows installation](/influxdb/v2.0/install/?t=Windows) -``` - -### Required elements - -Use the `{{< req >}}` shortcode to identify required elements in documentation with -orange text and/or asterisks. By default, the shortcode outputs the text, "Required," but -you can customize the text by passing a string argument with the shortcode. - -```md +md {{< req >}} -``` - -**Output:** Required - -```md -{{< req "This is Required" >}} -``` - -**Output:** This is required - -If using other named arguments like `key` or `color`, use the `text` argument to -customize the text of the required message. - -```md -{{< req text="Required if ..." color="blue" type="key" >}} -``` - -#### Required elements in a list - -When identifying required elements in a list, use `{{< req type="key" >}}` to generate -a "\* Required" key before the list. For required elements in the list, include -{{< req "\*" >}} before the text of the list item. For example: - -```md +md {{< req type="key" >}} - {{< req "\*" >}} **This element is required** - {{< req "\*" >}} **This element is also required** - **This element is NOT required** -``` +md -#### Change color of required text - -Use the `color` argument to change the color of required text. -The following colors are available: - -- blue -- green -- magenta - -```md -{{< req color="magenta" text="This is required" >}} -``` - -### Page navigation buttons - -Use the `{{< page-nav >}}` shortcode to add page navigation buttons to a page. -These are useful for guiding users through a set of docs that should be read in sequential order. -The shortcode has the following parameters: - -- **prev:** path of the previous document _(optional)_ -- **next:** path of the next document _(optional)_ -- **prevText:** override the button text linking to the previous document _(optional)_ -- **nextText:** override the button text linking to the next document _(optional)_ -- **keepTab:** include the currently selected tab in the button link _(optional)_ - -The shortcode generates buttons that link to both the previous and next documents. -By default, the shortcode uses either the `list_title` or the `title` of the linked -document, but you can use `prevText` and `nextText` to override button text. - -```md - {{ page-nav prev="/path/to/prev/" next="/path/to/next" >}} - + {{ page-nav prev="/path/to/prev/" prevText="Previous" next="/path/to/next" nextText="Next" >}} - + {{ page-nav prev="/path/to/prev/" next="/path/to/next" keepTab=true>}} -``` - -### Keybinds - -Use the `{{< keybind >}}` shortcode to include OS-specific keybindings/hotkeys. -The following parameters are available: - -- mac -- linux -- win -- all -- other - -```md - - -{{< keybind mac="⇧⌘P" other="Ctrl+Shift+P" >}} - - - -{{< keybind all="Ctrl+Shift+P" >}} - - - -{{< keybind mac="⇧⌘P" linux="Ctrl+Shift+P" win="Ctrl+Shift+Alt+P" >}} -``` - -### Diagrams - -Use the `{{< diagram >}}` shortcode to dynamically build diagrams. -The shortcode uses [mermaid.js](https://github.com/mermaid-js/mermaid) to convert -simple text into SVG diagrams. -For information about the syntax, see the [mermaid.js documentation](https://mermaid-js.github.io/mermaid/#/). - -```md +md {{< diagram >}} flowchart TB This --> That That --> There {{< /diagram >}} -``` - -### File system diagrams - -Use the `{{< filesystem-diagram >}}` shortcode to create a styled file system -diagram using a Markdown unordered list. - -##### Example filesystem diagram shortcode - -```md -{{< filesystem-diagram >}} - -- Dir1/ -- Dir2/ - - ChildDir/ - - Child - - Child -- Dir3/ - {{< /filesystem-diagram >}} -``` - -### High-resolution images - -In many cases, screenshots included in the docs are taken from high-resolution (retina) screens. -Because of this, the actual pixel dimension is 2x larger than it needs to be and is rendered 2x bigger than it should be. -The following shortcode automatically sets a fixed width on the image using half of its actual pixel dimension. -This preserves the detail of the image and renders it at a size where there should be little to no "blur" -cause by browser image resizing. - -```html +html {{< img-hd src="/path/to/image" alt="Alternate title" />}} -``` - -###### Notes - -- This should only be used on screenshots takes from high-resolution screens. -- The `src` should be relative to the `static` directory. -- Image widths are limited to the width of the article content container and will scale accordingly, - even with the `width` explicitly set. - -### Truncated content blocks - -In some cases, it may be appropriate to shorten or truncate blocks of content. -Use cases include long examples of output data or tall images. -The following shortcode truncates blocks of content and allows users to opt into -to seeing the full content block. - -```md +md {{% truncate %}} Truncated markdown content here. {{% /truncate %}} -``` - -### Expandable accordion content blocks - -Use the `{{% expand "Item label" %}}` shortcode to create expandable, accordion-style content blocks. -Each expandable block needs a label that users can click to expand or collapse the content block. -Pass the label as a string to the shortcode. - -```md -{{% expand "Label 1" %}} -Markdown content associated with label 1. -{{% /expand %}} - -{{% expand "Label 2" %}} -Markdown content associated with label 2. -{{% /expand %}} - -{{% expand "Label 3" %}} -Markdown content associated with label 3. -{{% /expand %}} -``` Use the optional `{{< expand-wrapper >}}` shortcode around a group of `{{% expand %}}` shortcodes to ensure proper spacing around the expandable elements: -```md -{{< expand-wrapper >}} -{{% expand "Label 1" %}} -Markdown content associated with label 1. -{{% /expand %}} - -{{% expand "Label 2" %}} -Markdown content associated with label 2. -{{% /expand %}} -{{< /expand-wrapper >}} -``` - -### Captions - -Use the `{{% caption %}}` shortcode to add captions to images and code blocks. -Captions are styled with a smaller font size, italic text, slight transparency, -and appear directly under the previous image or code block. - -```md -{{% caption %}} -Markdown content for the caption. -{{% /caption %}} -``` - ### Generate a list of children articles Section landing pages often contain just a list of articles with links and descriptions for each. This can be cumbersome to maintain as content is added. To automate the listing of articles in a section, use the `{{< children >}}` shortcode. -```md -{{< children >}} -``` - -The children shortcode can also be used to list only "section" articles (those with their own children), -or only "page" articles (those with no children) using the `show` argument: - -```md -{{< children show="sections" >}} - - - -{{< children show="pages" >}} -``` - -_By default, it displays both sections and pages._ - -Use the `type` argument to specify the format of the children list. - -```md -{{< children type="functions" >}} -``` - -The following list types are available: - -- **articles:** lists article titles as headers with the description or summary - of the article as a paragraph. Article headers link to the articles. -- **list:** lists children article links in an unordered list. -- **anchored-list:** lists anchored children article links in an unordered list - meant to act as a page navigation and link to children header. -- **functions:** a special use-case designed for listing Flux functions. - -#### Include a "Read more" link - -To include a "Read more" link with each child summary, set `readmore=true`. -_Only the `articles` list type supports "Read more" links._ - -```md +md {{< children readmore=true >}} -``` - -#### Include a horizontal rule - -To include a horizontal rule after each child summary, set `hr=true`. -_Only the `articles` list type supports horizontal rules._ - -```md -{{< children hr=true >}} -``` - -#### Include a code example with a child summary - -Use the `list_code_example` frontmatter to provide a code example with an article -in an articles list. - -````yaml -list_code_example: | - ```sh - This is a code example - ``` -```` - -#### Organize and include native code examples - -To include text from a file in `/shared/text/`, use the -`{{< get-shared-text >}}` shortcode and provide the relative path and filename. - -This is useful for maintaining and referencing sample code variants in their -native file formats. - -1. Store code examples in their native formats at `/shared/text/`. - -```md +md /shared/text/example1/example.js /shared/text/example1/example.py -``` - -2. Include the files--for example, in code tabs: - - ````md - {{% code-tabs-wrapper %}} - {{% code-tabs %}} - [Javascript](#js) - [Python](#py) - {{% /code-tabs %}} - {{% code-tab-content %}} - - ```js - {{< get-shared-text "example1/example.js" >}} - ``` - - {{% /code-tab-content %}} - {{% code-tab-content %}} - - ```py - {{< get-shared-text "example1/example.py" >}} - ``` - - {{% /code-tab-content %}} - {{% /code-tabs-wrapper %}} - ```` - -#### Include specific files from the same directory - -To include the text from one file in another file in the same -directory, use the `{{< get-leaf-text >}}` shortcode. -The directory that contains both files must be a -Hugo [_Leaf Bundle_](https://gohugo.io/content-management/page-bundles/#leaf-bundles), -a directory that doesn't have any child directories. - -In the following example, `api` is a leaf bundle. `content` isn't. - -```md +md content | |--- api | query.pdmc | query.sh | \_index.md -``` - -##### query.pdmc - -```md -# Query examples -``` - -##### query.sh - -```md -curl https://localhost:8086/query -``` - -To include `query.sh` and `query.pdmc` in `api/_index.md`, use the following code: - -````md -{{< get-leaf-text "query.pdmc" >}} - -# Curl example - -```sh -{{< get-leaf-text "query.sh" >}} -``` -```` - -Avoid using the following file extensions when naming included text files since Hugo interprets these as markup languages: -`.ad`, `.adoc`, `.asciidoc`, `.htm`, `.html`, `.markdown`, `.md`, `.mdown`, `.mmark`, `.pandoc`, `.pdc`, `.org`, or `.rst`. - -#### Reference a query example in children - -To include a query example with the children in your list, update `data/query_examples.yml` -with the example code, input, and output, and use the `list_query_example` -frontmatter to reference the corresponding example. - -```yaml +yaml list_query_example: cumulative_sum -``` - -#### Children frontmatter - -Each children list `type` uses [frontmatter properties](#page-frontmatter) when generating the list of articles. -The following table shows which children types use which frontmatter properties: - -| Frontmatter | articles | list | functions | -| :------------------- | :------: | :--: | :-------: | -| `list_title` | ✓ | ✓ | ✓ | -| `description` | ✓ | | | -| `external_url` | ✓ | ✓ | | -| `list_image` | ✓ | | | -| `list_note` | | ✓ | | -| `list_code_example` | ✓ | | | -| `list_query_example` | ✓ | | | - -### Authentication token link - -Use the `{{% token-link "" "%}}` shortcode to -automatically generate links to token management documentation. The shortcode -accepts two _optional_ arguments: - -- **descriptor**: An optional token descriptor -- **link_append**: An optional path to append to the token management link path, - `///admin/tokens/`. - -```md +md {{% token-link "database" "resource/" }} - + [database token](/influxdb3/enterprise/admin/tokens/resource/) -``` -InfluxDB 3 Enterprise and InfluxDB 3 Core support different kinds of tokens. -The shortcode has a blacklist of token descriptors for each that will prevent -unsupported descriptors from appearing in the rendered output based on the -current product. - -### Inline icons - -The `icon` shortcode allows you to inject icons in paragraph text. -It's meant to clarify references to specific elements in the InfluxDB user interface. -This shortcode supports Clockface (the UI) v2 and v3. -Specify the version to use as the second argument. The default version is `v3`. - -``` {{< icon "icon-name" "v2" >}} -``` -Below is a list of available icons (some are aliases): - -- add-cell -- add-label -- alert -- calendar -- chat -- checkmark -- clone -- cloud -- cog -- config -- copy -- dashboard -- dashboards -- data-explorer -- delete -- download -- duplicate -- edit -- expand -- export -- eye -- eye-closed -- eye-open -- feedback -- fullscreen -- gear -- graph -- hide -- influx -- influx-icon -- nav-admin -- nav-config -- nav-configuration -- nav-dashboards -- nav-data-explorer -- nav-organizations -- nav-orgs -- nav-tasks -- note -- notebook -- notebooks -- org -- orgs -- pause -- pencil -- play -- plus -- refresh -- remove -- replay -- save-as -- search -- settings -- tasks -- toggle -- trash -- trashcan -- triangle -- view -- wrench -- x - -### InfluxDB UI left navigation icons - -In many cases, documentation references an item in the left nav of the InfluxDB UI. -Provide a visual example of the navigation item using the `nav-icon` shortcode. -This shortcode supports Clockface (the UI) v2 and v3. -Specify the version to use as the second argument. The default version is `v3`. - -``` {{< nav-icon "tasks" "v2" >}} -``` - -The following case insensitive values are supported: - -- admin, influx -- data-explorer, data explorer -- notebooks, books -- dashboards -- tasks -- monitor, alerts, bell -- cloud, usage -- data, load data, load-data -- settings -- feedback - -### Flexbox-formatted content blocks - -CSS Flexbox formatting lets you create columns in article content that adjust and -flow based on the viewable width. -In article content, this helps if you have narrow tables that could be displayed -side-by-side, rather than stacked vertically. -Use the `{{< flex >}}` shortcode to create the Flexbox wrapper. -Use the `{{% flex-content %}}` shortcode to identify each column content block. - -```md +md {{< flex >}} {{% flex-content %}} Column 1 @@ -1281,30 +280,6 @@ Column 1 Column 2 {{% /flex-content %}} {{< /flex >}} -``` - -`{{% flex-content %}}` has an optional width argument that determines the maximum -width of the column. - -```md -{{% flex-content "half" %}} -``` - -The following options are available: - -- half _(Default)_ -- third -- quarter - -### Tooltips - -Use the `{{< tooltip >}}` shortcode to add tooltips to text. -The **first** argument is the text shown in the tooltip. -The **second** argument is the highlighted text that triggers the tooltip. - -```md -I like {{< tooltip "Butterflies are awesome!" "butterflies" >}}. -``` The rendered output is "I like butterflies" with "butterflies" highlighted. When you hover over "butterflies," a tooltip appears with the text: "Butterflies are awesome!" @@ -1342,28 +317,7 @@ This is only recommended when showing how functions that require a time range (such as `window()`) operate on input data. Use either `includeRange` argument name or provide the boolean value as the third argument. -##### Example Flux sample data shortcodes - -```md - - -{{% flux/sample %}} - - - -{{% flux/sample set="string" includeNull=false %}} - - - -{{% flux/sample "int" true %}} - - - - -{{% flux/sample set="int" includeNull=true includeRange=true %}} -{{% flux/sample "int" true true %}} -``` - +# ### Duplicate OSS content in Cloud Docs for InfluxDB OSS and InfluxDB Cloud share a majority of content. @@ -1373,97 +327,14 @@ To prevent duplication of content between versions, use the following shortcodes - `{{% oss-only %}}` - `{{% cloud-only %}}` -#### duplicate-oss - -The `{{< duplicate-oss >}}` shortcode copies the page content of the file located -at the identical file path in the most recent InfluxDB OSS version. -The Cloud version of this markdown file should contain the frontmatter required -for all pages, but the body content should just be the `{{< duplicate-oss >}}` shortcode. - -#### oss-only - -Wrap content that should only appear in the OSS version of the doc with the `{{% oss-only %}}` shortcode. +[Similar patterns apply - see full CONTRIBUTING.md for complete examples]}` shortcode. Use the shortcode on both inline and content blocks: -```md -{{% oss-only %}}This is inline content that only renders in the InfluxDB OSS docs{{% /oss-only %}} - -{{% oss-only %}} - -This is a multi-paragraph content block that spans multiple paragraphs and will -only render in the InfluxDB OSS documentation. - -**Note:** Notice the blank newline after the opening short-code tag. -This is necessary to get the first sentence/paragraph to render correctly. - -{{% /oss-only %}} - -- {{% oss-only %}}This is a list item that will only render in InfluxDB OSS docs.{{% /oss-only %}} -- {{% oss-only %}} - - This is a multi-paragraph list item that will only render in the InfluxDB OSS docs. - - **Note:** Notice shortcode is _inside_ of the line item. - There also must be blank newline after the opening short-code tag. - This is necessary to get the first sentence/paragraph to render correctly. - - {{% /oss-only %}} - -1. Step 1 -2. {{% oss-only %}}This is a list item that will only render in InfluxDB OSS docs.{{% /oss-only %}} -3. {{% oss-only %}} - - This is a list item that contains multiple paragraphs or nested list items and will only render in the InfluxDB OSS docs. - - **Note:** Notice shortcode is _inside_ of the line item. - There also must be blank newline after the opening short-code tag. - This is necessary to get the first sentence/paragraph to render correctly. - - {{% /oss-only %}} -``` - #### cloud-only Wrap content that should only appear in the Cloud version of the doc with the `{{% cloud-only %}}` shortcode. Use the shortcode on both inline and content blocks: -```md -{{% cloud-only %}}This is inline content that only renders in the InfluxDB Cloud docs{{% /cloud-only %}} - -{{% cloud-only %}} - -This is a multi-paragraph content block that spans multiple paragraphs and will -only render in the InfluxDB Cloud documentation. - -**Note:** Notice the blank newline after the opening short-code tag. -This is necessary to get the first sentence/paragraph to render correctly. - -{{% /cloud-only %}} - -- {{% cloud-only %}}This is a list item that will only render in InfluxDB Cloud docs.{{% /cloud-only %}} -- {{% cloud-only %}} - - This is a list item that contains multiple paragraphs or nested list items and will only render in the InfluxDB Cloud docs. - - **Note:** Notice shortcode is _inside_ of the line item. - There also must be blank newline after the opening short-code tag. - This is necessary to get the first sentence/paragraph to render correctly. - - {{% /cloud-only %}} - -1. Step 1 -2. {{% cloud-only %}}This is a list item that will only render in InfluxDB Cloud docs.{{% /cloud-only %}} -3. {{% cloud-only %}} - - This is a multi-paragraph list item that will only render in the InfluxDB Cloud docs. - - **Note:** Notice shortcode is _inside_ of the line item. - There also must be blank newline after the opening short-code tag. - This is necessary to get the first sentence/paragraph to render correctly. - - {{% /cloud-only %}} -``` - ### Show or hide content blocks in shared content The `source` frontmatter lets you source page content from another file and is @@ -1485,107 +356,22 @@ The `show-in` shortcode accepts a comma-delimited string of InfluxDB "versions" to show the content block in. The version is the second level of the page path--for example: `/influxdb//...`. -```md -{{% show-in "core,enterprise" %}} - -This content will appear in pages in the InfluxDB 3 Core and InfluxDB 3 Enterprise -documentation, but not any other InfluxDB documentation this content is shared in. - -{{% /show-in %}} -``` - -#### hide-in - -The `hide-in` shortcode accepts a comma-delimited string of InfluxDB "versions" -to hide the content block in. The version is the second level of the page -path--for example: `/influxdb//...`. - -```md -{{% hide-in "core,enterprise" %}} - -This content will not appear in pages in the InfluxDB 3 Core and InfluxDB 3 -Enterprise documentation, but will in all other InfluxDB documentation this -content is shared in. - -{{% /hide-in %}} -``` - ### All-Caps Clockface v3 introduces many buttons with text formatted as all-caps. Use the `{{< caps >}}` shortcode to format text to match those buttons. -```md -Click {{< caps >}}Add Data{{< /caps >}} -``` +html -### Code callouts - -Use the `{{< code-callout >}}` shortcode to highlight and emphasize a specific -piece of code (for example, a variable, placeholder, or value) in a code block. -Provide the string to highlight in the code block. -Include a syntax for the codeblock to properly style the called out code. - -````md -{{< code-callout "03a2bbf46249a000" >}} - -```sh -http://localhost:8086/orgs/03a2bbf46249a000/... -``` - -{{< /code-callout >}} -```` - -### InfluxDB University banners - -Use the `{{< influxdbu >}}` shortcode to add an InfluxDB University banner that -points to the InfluxDB University site or a specific course. -Use the default banner template, a predefined course template, or fully customize -the content of the banner. - -```html - {{< influxdbu >}} - + {{< influxdbu "influxdb-101" >}} - + {{< influxdbu title="Course title" summary="Short course summary." action="Take the course" link="https://university.influxdata.com/" >}} -``` - -#### Course templates - -Use one of the following course templates: - -- influxdb-101 -- telegraf-102 -- flux-103 - -#### Custom banner content - -Use the following shortcode parameters to customize the content of the InfluxDB -University banner: - -- **title**: Course or banner title -- **summary**: Short description shown under the title -- **action**: Text of the button -- **link**: URL the button links to - -### Reference content - -The InfluxDB documentation is "task-based," meaning content primarily focuses on -what a user is **doing**, not what they are **using**. -However, there is a need to document tools and other things that don't necessarily -fit in the task-based style. -This is referred to as "reference content." - -Reference content is styled just as the rest of the InfluxDB documentation. -The only difference is the `menu` reference in the page's frontmatter. -When defining the menu for reference content, use the following pattern: - -```yaml +yaml # Pattern menu: ___ref: @@ -1595,168 +381,26 @@ menu: menu: influxdb_2_0_ref: # ... -``` -## InfluxDB URLs +` -When a user selects an InfluxDB product and region, example URLs in code blocks -throughout the documentation are updated to match their product and region. -InfluxDB URLs are configured in `/data/influxdb_urls.yml`. - -By default, the InfluxDB URL replaced inside of code blocks is `http://localhost:8086`. -Use this URL in all code examples that should be updated with a selected provider and region. - -For example: - -```` -```sh -# This URL will get updated -http://localhost:8086 - -# This URL will NOT get updated -http://example.com -``` -```` - -If the user selects the **US West (Oregon)** region, all occurrences of `http://localhost:8086` -in code blocks will get updated to `https://us-west-2-1.aws.cloud2.influxdata.com`. - -### Exempt URLs from getting updated - -To exempt a code block from being updated, include the `{{< keep-url >}}` shortcode -just before the code block. - -```` -{{< keep-url >}} -``` -// This URL won't get updated -http://localhost:8086 -``` -```` - -### Code examples only supported in InfluxDB Cloud - -Some functionality is only supported in InfluxDB Cloud and code examples should -only use InfluxDB Cloud URLs. In these cases, use `https://cloud2.influxdata.com` -as the placeholder in the code block. It will get updated on page load and when -users select a Cloud region in the URL select modal. - -```` -```sh -# This URL will get updated -https://cloud2.influxdata.com -``` -```` - -### Automatically populate InfluxDB host placeholder - -The InfluxDB host placeholder that gets replaced by custom domains differs -between each InfluxDB product/version. -Use the `influxdb/host` shortcode to automatically render the correct -host placeholder value for the current product. You can also pass a single -argument to specify a specific InfluxDB product to use. -Supported argument values: - -- oss -- cloud -- cloud-serverless -- cloud-dedicated -- clustered -- core -- enterprise - -``` {{< influxdb/host >}} {{< influxdb/host "serverless" >}} -``` -### User-populated placeholders - -Use the `code-placeholders` shortcode to format placeholders -as text fields that users can populate with their own values. -The shortcode takes a regular expression for matching placeholder names. -Use the `code-placeholder-key` shortcode to format the placeholder names in -text that describes the placeholder--for example: - -```markdown -{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} -```sh -curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ - --header "Authorization: Token API_TOKEN" \ - --data-binary @path/to/line-protocol.txt -``` {{% /code-placeholders %}} Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME` and `RETENTION_POLICY`{{% /code-placeholder-key %}}: the [database and retention policy mapping (DBRP)](/influxdb/v2/reference/api/influxdb-1x/dbrp/) for the InfluxDB v2 bucket that you want to write to -- {{% code-placeholder-key %}}`USERNAME`{{% /code-placeholder-key %}}: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) +- {{% code-placeholder-key %} + +[Similar patterns apply - see full CONTRIBUTING.md for complete examples]}`USERNAME`{{% /code-placeholder-key %}}: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) - {{% code-placeholder-key %}}`PASSWORD_OR_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) - {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/) -``` - -## InfluxDB API documentation - -InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full -InfluxDB API documentation when documentation is deployed. -Redoc generates HTML documentation using the InfluxDB `swagger.yml`. -For more information about generating InfluxDB API documentation, see the -[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). - -## JavaScript in the documentation UI - -The InfluxData documentation UI uses JavaScript with ES6+ syntax and -`assets/js/main.js` as the entry point to import modules from -`assets/js`. -Only `assets/js/main.js` should be imported in HTML files. - -`assets/js/main.js` registers components and initializes them on page load. - -If you're adding UI functionality that requires JavaScript, follow these steps: - -1. In your HTML file, add a `data-component` attribute to the element that - should be initialized by your JavaScript code. For example: - - ```html +html
- ``` - -2. Following the component pattern, create a single-purpose JavaScript module - (`assets/js/components/my-component.js`) - that exports a single function that receives the component element and initializes it. -3. In `assets/js/main.js`, import the module and register the component to ensure - the component is initialized on page load. - -### Debugging JavaScript - -To debug JavaScript code used in the InfluxData documentation UI, choose one of the following methods: - -- Use source maps and the Chrome DevTools debugger. -- Use debug helpers that provide breakpoints and console logging as a workaround or alternative for using source maps and the Chrome DevTools debugger. - -#### Using source maps and Chrome DevTools debugger - -1. In VS Code, select Run > Start Debugging. -2. Select the "Debug Docs (source maps)" configuration. -3. Click the play button to start the debugger. -5. Set breakpoints in the JavaScript source files--files in the - `assets/js/ns-hugo-imp:` namespace-- in the - VS Code editor or in the Chrome Developer Tools Sources panel: - - - In the VS Code Debugger panel > "Loaded Scripts" section, find the - `assets/js/ns-hugo-imp:` namespace. - - In the Chrome Developer Tools Sources panel, expand - `js/ns-hugo-imp://assets/js/`. - -#### Using debug helpers - -1. In your JavaScript module, import debug helpers from `assets/js/utils/debug-helpers.js`. - These helpers provide breakpoints and console logging as a workaround or alternative for - using source maps and the Chrome DevTools debugger. -2. Insert debug statements by calling the helper functions in your code--for example: - - ```js + js import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; const data = debugInspect(someData, 'Data'); diff --git a/.gitignore b/.gitignore index d34fa2f89..4cb5a9eae 100644 --- a/.gitignore +++ b/.gitignore @@ -15,7 +15,7 @@ node_modules !telegraf-build/templates !telegraf-build/scripts !telegraf-build/README.md -/cypress/downloads +/cypress/downloads/* /cypress/screenshots/* /cypress/videos/* test-results.xml @@ -25,4 +25,8 @@ test-results.xml .idea **/config.toml package-lock.json -tmp \ No newline at end of file +tmp + +# Context files for LLMs and AI tools +.context/* +!.context/README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..97f250d72 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,25 @@ +# Instructions for InfluxData Documentation + +## Purpose and scope + +Claude should help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting. + +## Project overview + +See @README.md + +## Available NPM commands + +@package.json + +## Instructions for contributing + +See @.github/copilot-instructions.md for style guidelines and +product-specific documentation paths and URLs managed in this project. + +See @.github/instructions/contributing.instructions.md for contributing +information including using shortcodes and running tests. + +See @.github/instructions/influxdb3-code-placeholders.instructions.md for using +placeholders in code samples and CLI commands. + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2a6bdee3..e9f5fd25c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -363,6 +363,9 @@ list_query_example:# Code examples included with article descriptions in childre # References to examples in data/query_examples canonical: # Path to canonical page, overrides auto-gen'd canonical URL v2: # Path to v2 equivalent page +alt_links: # Alternate pages in other products/versions for cross-product navigation + cloud-dedicated: /influxdb3/cloud-dedicated/path/to/page/ + core: /influxdb3/core/path/to/page/ prepend: # Prepend markdown content to an article (especially powerful with cascade) block: # (Optional) Wrap content in a block style (note, warn, cloud) content: # Content to prepend to article @@ -454,6 +457,29 @@ add the following frontmatter to the 1.x page: v2: /influxdb/v2.0/get-started/ ``` +### Alternative links for cross-product navigation + +Use the `alt_links` frontmatter to specify equivalent pages in other InfluxDB products, +for example, when a page exists at a different path in a different version or if +the feature doesn't exist in that product. +This enables the product switcher to navigate users to the corresponding page when they +switch between products. If a page doesn't exist in another product (for example, an +Enterprise-only feature), point to the nearest parent page if relevant. + +```yaml +alt_links: + cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/ + cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/ + core: /influxdb3/core/reference/cli/influxdb3/update/ # Points to parent if exact page doesn't exist +``` + +Supported product keys for InfluxDB 3: +- `core` +- `enterprise` +- `cloud-serverless` +- `cloud-dedicated` +- `clustered` + ### Prepend and append content to a page Use the `prepend` and `append` frontmatter to add content to the top or bottom of a page. diff --git a/api-docs/influxdb3/core/v3/ref.yml b/api-docs/influxdb3/core/v3/ref.yml index 3f4a738e8..e15c42f9f 100644 --- a/api-docs/influxdb3/core/v3/ref.yml +++ b/api-docs/influxdb3/core/v3/ref.yml @@ -922,9 +922,25 @@ paths: summary: Delete a database description: | Soft deletes a database. - The database is scheduled for deletion and unavailable for querying. + The database is scheduled for deletion and unavailable for querying. + Use the `hard_delete_at` parameter to schedule a hard deletion. parameters: - $ref: '#/components/parameters/db' + - name: hard_delete_at + in: query + required: false + schema: + type: string + format: date-time + description: | + Schedule the database for hard deletion at the specified time. + If not provided, the database will be soft deleted. + Use ISO 8601 date-time format (for example, "2025-12-31T23:59:59Z"). + + #### Deleting a database cannot be undone + + Deleting a database is a destructive action. + Once a database is deleted, data stored in that database cannot be recovered. responses: '200': description: Success. Database deleted. @@ -961,7 +977,13 @@ paths: summary: Delete a table description: | Soft deletes a table. - The table is scheduled for deletion and unavailable for querying. + The table is scheduled for deletion and unavailable for querying. + Use the `hard_delete_at` parameter to schedule a hard deletion. + + #### Deleting a table cannot be undone + + Deleting a table is a destructive action. + Once a table is deleted, data stored in that table cannot be recovered. parameters: - $ref: '#/components/parameters/db' - name: table @@ -969,6 +991,16 @@ paths: required: true schema: type: string + - name: hard_delete_at + in: query + required: false + schema: + type: string + format: date-time + description: | + Schedule the table for hard deletion at the specified time. + If not provided, the table will be soft deleted. + Use ISO 8601 format (for example, "2025-12-31T23:59:59Z"). responses: '200': description: Success (no content). The table has been deleted. @@ -1078,7 +1110,7 @@ paths: In `"cron:CRON_EXPRESSION"`, `CRON_EXPRESSION` uses extended 6-field cron format. The cron expression `0 0 6 * * 1-5` means the trigger will run at 6:00 AM every weekday (Monday to Friday). value: - db: DATABASE_NAME + db: mydb plugin_filename: schedule.py trigger_name: schedule_cron_trigger trigger_specification: cron:0 0 6 * * 1-5 @@ -1136,7 +1168,7 @@ paths: db: mydb plugin_filename: request.py trigger_name: hello_world_trigger - trigger_specification: path:hello-world + trigger_specification: request:hello-world cron_friday_afternoon: summary: Cron trigger for Friday afternoons description: | @@ -1365,16 +1397,16 @@ paths: description: Plugin not enabled. tags: - Processing engine - /api/v3/engine/{plugin_path}: + /api/v3/engine/{request_path}: parameters: - - name: plugin_path + - name: request_path description: | - The path configured in the request trigger specification "path:"` for the plugin. + The path configured in the request trigger specification for the plugin. For example, if you define a trigger with the following: ```json - trigger-spec: "path:hello-world" + trigger_specification: "request:hello-world" ``` then, the HTTP API exposes the following plugin endpoint: @@ -1390,7 +1422,7 @@ paths: operationId: GetProcessingEnginePluginRequest summary: On Request processing engine plugin request description: | - Executes the On Request processing engine plugin specified in ``. + Executes the On Request processing engine plugin specified in the trigger's `plugin_filename`. The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin. An On Request plugin implements the following signature: @@ -1417,7 +1449,7 @@ paths: operationId: PostProcessingEnginePluginRequest summary: On Request processing engine plugin request description: | - Executes the On Request processing engine plugin specified in ``. + Executes the On Request processing engine plugin specified in the trigger's `plugin_filename`. The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin. An On Request plugin implements the following signature: @@ -1868,7 +1900,7 @@ components: `schedule.py` or `endpoints/report.py`. The path can be absolute or relative to the `--plugins-dir` directory configured when starting InfluxDB 3. - The plugin file must implement the trigger interface associated with the trigger's specification (`trigger_spec`). + The plugin file must implement the trigger interface associated with the trigger's specification. trigger_name: type: string trigger_specification: @@ -1911,12 +1943,12 @@ components: - `table:TABLE_NAME` - Triggers on write events to a specific table ### On-demand triggers - Format: `path:ENDPOINT_NAME` + Format: `request:REQUEST_PATH` - Creates an HTTP endpoint `/api/v3/engine/ENDPOINT_NAME` for manual invocation: - - `path:hello-world` - Creates endpoint `/api/v3/engine/hello-world` - - `path:data-export` - Creates endpoint `/api/v3/engine/data-export` - pattern: ^(cron:[0-9 *,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*|path:[a-zA-Z0-9_-]+)$ + Creates an HTTP endpoint `/api/v3/engine/REQUEST_PATH` for manual invocation: + - `request:hello-world` - Creates endpoint `/api/v3/engine/hello-world` + - `request:data-export` - Creates endpoint `/api/v3/engine/data-export` + pattern: ^(cron:[0-9 *,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*|request:[a-zA-Z0-9_-]+)$ example: cron:0 0 6 * * 1-5 trigger_arguments: type: object @@ -2013,6 +2045,65 @@ components: - m - h type: string + UpdateDatabaseRequest: + type: object + properties: + retention_period: + type: string + description: | + The retention period for the database. Specifies how long data should be retained. + Use duration format (for example, "1d", "1h", "30m", "7d"). + example: "7d" + description: Request schema for updating database configuration. + UpdateTableRequest: + type: object + properties: + db: + type: string + description: The name of the database containing the table. + table: + type: string + description: The name of the table to update. + retention_period: + type: string + description: | + The retention period for the table. Specifies how long data in this table should be retained. + Use duration format (for example, "1d", "1h", "30m", "7d"). + example: "30d" + required: + - db + - table + description: Request schema for updating table configuration. + LicenseResponse: + type: object + properties: + license_type: + type: string + description: The type of license (for example, "enterprise", "trial"). + example: "enterprise" + expires_at: + type: string + format: date-time + description: The expiration date of the license in ISO 8601 format. + example: "2025-12-31T23:59:59Z" + features: + type: array + items: + type: string + description: List of features enabled by the license. + example: + - "clustering" + - "processing_engine" + - "advanced_auth" + status: + type: string + enum: + - "active" + - "expired" + - "invalid" + description: The current status of the license. + example: "active" + description: Response schema for license information. responses: Unauthorized: description: Unauthorized access. diff --git a/api-docs/influxdb3/enterprise/v3/ref.yml b/api-docs/influxdb3/enterprise/v3/ref.yml index 9f1a7fca1..b1cb43d7c 100644 --- a/api-docs/influxdb3/enterprise/v3/ref.yml +++ b/api-docs/influxdb3/enterprise/v3/ref.yml @@ -922,9 +922,25 @@ paths: summary: Delete a database description: | Soft deletes a database. - The database is scheduled for deletion and unavailable for querying. + The database is scheduled for deletion and unavailable for querying. + Use the `hard_delete_at` parameter to schedule a hard deletion. parameters: - $ref: '#/components/parameters/db' + - name: hard_delete_at + in: query + required: false + schema: + type: string + format: date-time + description: | + Schedule the database for hard deletion at the specified time. + If not provided, the database will be soft deleted. + Use ISO 8601 date-time format (for example, "2025-12-31T23:59:59Z"). + + #### Deleting a database cannot be undone + + Deleting a database is a destructive action. + Once a database is deleted, data stored in that database cannot be recovered. responses: '200': description: Success. Database deleted. @@ -961,7 +977,13 @@ paths: summary: Delete a table description: | Soft deletes a table. - The table is scheduled for deletion and unavailable for querying. + The table is scheduled for deletion and unavailable for querying. + Use the `hard_delete_at` parameter to schedule a hard deletion. + + #### Deleting a table cannot be undone + + Deleting a table is a destructive action. + Once a table is deleted, data stored in that table cannot be recovered. parameters: - $ref: '#/components/parameters/db' - name: table @@ -969,6 +991,16 @@ paths: required: true schema: type: string + - name: hard_delete_at + in: query + required: false + schema: + type: string + format: date-time + description: | + Schedule the table for hard deletion at the specified time. + If not provided, the table will be soft deleted. + Use ISO 8601 format (for example, "2025-12-31T23:59:59Z"). responses: '200': description: Success (no content). The table has been deleted. @@ -978,6 +1010,77 @@ paths: description: Table not found. tags: - Table + patch: + operationId: PatchConfigureTable + summary: Update a table + description: | + Updates table configuration, such as retention period. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTableRequest' + responses: + '200': + description: Success. The table has been updated. + '400': + description: Bad request. + '401': + $ref: '#/components/responses/Unauthorized' + '404': + description: Table not found. + tags: + - Table + /api/v3/configure/database/{db}: + patch: + operationId: PatchConfigureDatabase + summary: Update a database + description: | + Updates database configuration, such as retention period. + parameters: + - name: db + in: path + required: true + schema: + type: string + description: The name of the database to update. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateDatabaseRequest' + responses: + '200': + description: Success. The database has been updated. + '400': + description: Bad request. + '401': + $ref: '#/components/responses/Unauthorized' + '404': + description: Database not found. + tags: + - Database + /api/v3/show/license: + get: + operationId: GetShowLicense + summary: Show license information + description: | + Retrieves information about the current InfluxDB 3 Enterprise license. + responses: + '200': + description: Success. The response body contains license information. + content: + application/json: + schema: + $ref: '#/components/schemas/LicenseResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + description: Access denied. + tags: + - Server information /api/v3/configure/distinct_cache: post: operationId: PostConfigureDistinctCache @@ -1136,7 +1239,8 @@ paths: db: mydb plugin_filename: request.py trigger_name: hello_world_trigger - trigger_specification: path:hello-world + # trigger_specification: "request:hello-world" - For 3.2.1 (issue#6171) + trigger_specification: {"request_path": {"path": "hello-world"}} cron_friday_afternoon: summary: Cron trigger for Friday afternoons description: | @@ -1365,23 +1469,26 @@ paths: description: Plugin not enabled. tags: - Processing engine - /api/v3/engine/{plugin_path}: + /api/v3/engine/{request_path}: parameters: - - name: plugin_path + - name: request_path description: | - The path configured in the request trigger specification "path:"` for the plugin. + The path configured in the request trigger specification for the plugin. For example, if you define a trigger with the following: ```json - trigger-spec: "path:hello-world" + trigger_specification: {"request_path": {"path": "hello-world"}} ``` - + then, the HTTP API exposes the following plugin endpoint: ``` /api/v3/engine/hello-world ``` + + ***Note:*** Currently, due to a bug in InfluxDB 3 Enterprise, the request trigger specification is different from Core. + in: path required: true schema: @@ -1390,7 +1497,7 @@ paths: operationId: GetProcessingEnginePluginRequest summary: On Request processing engine plugin request description: | - Executes the On Request processing engine plugin specified in ``. + Executes the On Request processing engine plugin specified in the trigger's `plugin_filename`. The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin. An On Request plugin implements the following signature: @@ -1417,7 +1524,7 @@ paths: operationId: PostProcessingEnginePluginRequest summary: On Request processing engine plugin request description: | - Executes the On Request processing engine plugin specified in ``. + Executes the On Request processing engine plugin specified in the trigger's `plugin_filename`. The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin. An On Request plugin implements the following signature: @@ -1812,6 +1919,16 @@ components: properties: db: type: string + pattern: '^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$' + description: |- + The database name. Database names cannot contain underscores (_). + Names must start and end with alphanumeric characters and can contain hyphens (-) in the middle. + retention_period: + type: string + description: |- + The retention period for the database. Specifies how long data should be retained. + Use duration format (for example, "1d", "1h", "30m", "7d"). + example: "7d" required: - db CreateTableRequest: @@ -1843,6 +1960,12 @@ components: required: - name - type + retention_period: + type: string + description: |- + The retention period for the table. Specifies how long data in this table should be retained. + Use duration format (for example, "1d", "1h", "30m", "7d"). + example: "30d" required: - db - table @@ -1929,11 +2052,10 @@ components: `schedule.py` or `endpoints/report.py`. The path can be absolute or relative to the `--plugins-dir` directory configured when starting InfluxDB 3. - The plugin file must implement the trigger interface associated with the trigger's specification (`trigger_spec`). + The plugin file must implement the trigger interface associated with the trigger's specification. trigger_name: type: string trigger_specification: - type: string description: | Specifies when and how the processing engine trigger should be invoked. @@ -1972,12 +2094,25 @@ components: - `table:TABLE_NAME` - Triggers on write events to a specific table ### On-demand triggers - Format: `path:ENDPOINT_NAME` + Format: `{"request_path": {"path": "REQUEST_PATH"}}` - Creates an HTTP endpoint `/api/v3/engine/ENDPOINT_NAME` for manual invocation: - - `path:hello-world` - Creates endpoint `/api/v3/engine/hello-world` - - `path:data-export` - Creates endpoint `/api/v3/engine/data-export` - pattern: ^(cron:[0-9 *,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*|path:[a-zA-Z0-9_-]+)$ + Creates an HTTP endpoint `/api/v3/engine/REQUEST_PATH` for manual invocation: + - `{"request_path": {"path": "hello-world"}}` - Creates endpoint `/api/v3/engine/hello-world` + - `{"request_path": {"path": "data-export"}}` - Creates endpoint `/api/v3/engine/data-export` + + ***Note:*** Currently, due to a bug in InfluxDB 3 Enterprise, the request trigger specification is different from Core. Use the JSON object format shown above. + + oneOf: + - type: string + pattern: ^(cron:[0-9 *,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*)$ + - type: object + properties: + request_path: + type: object + properties: + path: + type: string + pattern: ^[a-zA-Z0-9_-]+$ example: cron:0 0 6 * * 1-5 trigger_arguments: type: object @@ -2074,6 +2209,65 @@ components: - m - h type: string + UpdateDatabaseRequest: + type: object + properties: + retention_period: + type: string + description: | + The retention period for the database. Specifies how long data should be retained. + Use duration format (for example, "1d", "1h", "30m", "7d"). + example: "7d" + description: Request schema for updating database configuration. + UpdateTableRequest: + type: object + properties: + db: + type: string + description: The name of the database containing the table. + table: + type: string + description: The name of the table to update. + retention_period: + type: string + description: | + The retention period for the table. Specifies how long data in this table should be retained. + Use duration format (for example, "1d", "1h", "30m", "7d"). + example: "30d" + required: + - db + - table + description: Request schema for updating table configuration. + LicenseResponse: + type: object + properties: + license_type: + type: string + description: The type of license (for example, "enterprise", "trial"). + example: "enterprise" + expires_at: + type: string + format: date-time + description: The expiration date of the license in ISO 8601 format. + example: "2025-12-31T23:59:59Z" + features: + type: array + items: + type: string + description: List of features enabled by the license. + example: + - "clustering" + - "processing_engine" + - "advanced_auth" + status: + type: string + enum: + - "active" + - "expired" + - "invalid" + description: The current status of the license. + example: "active" + description: Response schema for license information. responses: Unauthorized: description: Unauthorized access. diff --git a/assets/js/code-controls.js b/assets/js/code-controls.js index 17018a8e8..19ec0ef7c 100644 --- a/assets/js/code-controls.js +++ b/assets/js/code-controls.js @@ -1,4 +1,5 @@ import $ from 'jquery'; +import { context } from './page-context.js'; function initialize() { var codeBlockSelector = '.article--content pre'; @@ -68,9 +69,94 @@ function initialize() { // Trigger copy failure state lifecycle $('.copy-code').click(function () { - let text = $(this) + let codeElement = $(this) .closest('.code-controls') - .prevAll('pre:has(code)')[0].innerText; + .prevAll('pre:has(code)')[0]; + + let text = codeElement.innerText; + + // Extract additional code block information + const codeBlockInfo = extractCodeBlockInfo(codeElement); + + // Add Google Analytics event tracking + const currentUrl = new URL(window.location.href); + + // Determine which tracking parameter to add based on product context + switch (context) { + case 'cloud': + currentUrl.searchParams.set('dl', 'cloud'); + break; + case 'core': + /** Track using the same value used by www.influxdata.com pages */ + currentUrl.searchParams.set('dl', 'oss3'); + break; + case 'enterprise': + /** Track using the same value used by www.influxdata.com pages */ + currentUrl.searchParams.set('dl', 'enterprise'); + break; + case 'serverless': + currentUrl.searchParams.set('dl', 'serverless'); + break; + case 'dedicated': + currentUrl.searchParams.set('dl', 'dedicated'); + break; + case 'clustered': + currentUrl.searchParams.set('dl', 'clustered'); + break; + case 'oss/enterprise': + currentUrl.searchParams.set('dl', 'oss'); + break; + case 'other': + default: + // No tracking parameter for other/unknown products + break; + } + + // Add code block specific tracking parameters + if (codeBlockInfo.language) { + currentUrl.searchParams.set('code_lang', codeBlockInfo.language); + } + if (codeBlockInfo.lineCount) { + currentUrl.searchParams.set('code_lines', codeBlockInfo.lineCount); + } + if (codeBlockInfo.hasPlaceholders) { + currentUrl.searchParams.set('has_placeholders', 'true'); + } + if (codeBlockInfo.blockType) { + currentUrl.searchParams.set('code_type', codeBlockInfo.blockType); + } + if (codeBlockInfo.sectionTitle) { + currentUrl.searchParams.set( + 'section', + encodeURIComponent(codeBlockInfo.sectionTitle) + ); + } + if (codeBlockInfo.firstLine) { + currentUrl.searchParams.set( + 'first_line', + encodeURIComponent(codeBlockInfo.firstLine.substring(0, 100)) + ); + } + + // Update browser history without triggering page reload + if (window.history && window.history.replaceState) { + window.history.replaceState(null, '', currentUrl.toString()); + } + + // Send custom Google Analytics event if gtag is available + if (typeof window.gtag !== 'undefined') { + window.gtag('event', 'code_copy', { + language: codeBlockInfo.language, + line_count: codeBlockInfo.lineCount, + has_placeholders: codeBlockInfo.hasPlaceholders, + dl: codeBlockInfo.dl || null, + section_title: codeBlockInfo.sectionTitle, + first_line: codeBlockInfo.firstLine + ? codeBlockInfo.firstLine.substring(0, 100) + : null, + product: context, + }); + } const copyContent = async () => { try { @@ -84,6 +170,71 @@ function initialize() { copyContent(); }); + /** + * Extract contextual information about a code block + * @param {HTMLElement} codeElement - The code block element + * @returns {Object} Information about the code block + */ + function extractCodeBlockInfo(codeElement) { + const codeTag = codeElement.querySelector('code'); + const info = { + language: null, + lineCount: 0, + hasPlaceholders: false, + blockType: 'code', + dl: null, // Download script type + sectionTitle: null, + firstLine: null, + }; + + // Extract language from class attribute + if (codeTag && codeTag.className) { + const langMatch = codeTag.className.match( + /language-(\w+)|hljs-(\w+)|(\w+)/ + ); + if (langMatch) { + info.language = langMatch[1] || langMatch[2] || langMatch[3]; + } + } + + // Count lines + const text = codeElement.innerText || ''; + const lines = text.split('\n'); + info.lineCount = lines.length; + + // Get first non-empty line + info.firstLine = lines.find((line) => line.trim() !== '') || null; + + // Check for placeholders (common patterns) + info.hasPlaceholders = + /\b[A-Z_]{2,}\b|\{\{[^}]+\}\}|\$\{[^}]+\}|<[^>]+>/.test(text); + + // Determine if this is a download script + if (text.includes('https://www.influxdata.com/d/install_influxdb3.sh')) { + if (text.includes('install_influxdb3.sh enterprise')) { + info.dl = 'enterprise'; + } else { + info.dl = 'oss3'; + } + } else if (text.includes('docker pull influxdb:3-enterprise')) { + info.dl = 'enterprise'; + } else if (text.includes('docker pull influxdb3-core')) { + info.dl = 'oss3'; + } + + // Find nearest section heading + let element = codeElement; + while (element && element !== document.body) { + element = element.previousElementSibling || element.parentElement; + if (element && element.tagName && /^H[1-6]$/.test(element.tagName)) { + info.sectionTitle = element.textContent.trim(); + break; + } + } + + return info; + } + /////////////////////////////// FULL WINDOW CODE /////////////////////////////// /* diff --git a/assets/styles/layouts/article/_blocks.scss b/assets/styles/layouts/article/_blocks.scss index 62b205491..c7250749d 100644 --- a/assets/styles/layouts/article/_blocks.scss +++ b/assets/styles/layouts/article/_blocks.scss @@ -97,4 +97,4 @@ blockquote { "blocks/important", "blocks/warning", "blocks/caution", - "blocks/beta"; + "blocks/special-state"; diff --git a/assets/styles/layouts/article/blocks/_beta.scss b/assets/styles/layouts/article/blocks/_special-state.scss similarity index 98% rename from assets/styles/layouts/article/blocks/_beta.scss rename to assets/styles/layouts/article/blocks/_special-state.scss index b3ab3a70c..0717952cd 100644 --- a/assets/styles/layouts/article/blocks/_beta.scss +++ b/assets/styles/layouts/article/blocks/_special-state.scss @@ -1,10 +1,10 @@ -.block.beta { +.block.special-state { @include gradient($grad-burningDusk); padding: 4px; border: none; border-radius: 25px !important; - .beta-content { + .state-content { background: $article-bg; border-radius: 21px; padding: calc(1.65rem - 4px) calc(2rem - 4px) calc(.1rem + 4px) calc(2rem - 4px); diff --git a/build-scripts/build-copilot-instructions.js b/build-scripts/build-copilot-instructions.js index 0d089e2c1..1e537dc74 100644 --- a/build-scripts/build-copilot-instructions.js +++ b/build-scripts/build-copilot-instructions.js @@ -23,6 +23,7 @@ export { buildContributingInstructions }; /** Build instructions from CONTRIBUTING.md * This script reads CONTRIBUTING.md, formats it appropriately, * and saves it to .github/instructions/contributing.instructions.md + * Includes optimization to reduce file size for better performance */ function buildContributingInstructions() { // Paths @@ -41,16 +42,19 @@ function buildContributingInstructions() { // Read the CONTRIBUTING.md file let content = fs.readFileSync(contributingPath, 'utf8'); + // Optimize content by removing less critical sections for Copilot + content = optimizeContentForContext(content); + // Format the content for Copilot instructions with applyTo attribute content = `--- applyTo: "content/**/*.md, layouts/**/*.html" --- -# GitHub Copilot Instructions for InfluxData Documentation +# Contributing instructions for InfluxData Documentation ## Purpose and scope -GitHub Copilot should help document InfluxData products +Help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, shortcodes, and formatting. @@ -59,7 +63,17 @@ ${content}`; // Write the formatted content to the instructions file fs.writeFileSync(instructionsPath, content); - console.log(`✅ Generated Copilot instructions at ${instructionsPath}`); + const fileSize = fs.statSync(instructionsPath).size; + const sizeInKB = (fileSize / 1024).toFixed(1); + console.log( + `✅ Generated instructions at ${instructionsPath} (${sizeInKB}KB)` + ); + + if (fileSize > 40000) { + console.warn( + `⚠️ Instructions file is large (${sizeInKB}KB > 40KB) and may impact performance` + ); + } // Add the file to git if it has changed try { @@ -74,3 +88,58 @@ ${content}`; console.warn('⚠️ Could not add instructions file to git:', error.message); } } + +/** + * Optimize content for Copilot by removing or condensing less critical sections + * while preserving essential documentation guidance + */ +function optimizeContentForContext(content) { + // Remove or condense sections that are less relevant for context assistance + const sectionsToRemove = [ + // Installation and setup sections (less relevant for writing docs) + /### Install project dependencies[\s\S]*?(?=\n##|\n###|$)/g, + /### Install Node\.js dependencies[\s\S]*?(?=\n##|\n###|$)/g, + /### Install Docker[\s\S]*?(?=\n##|\n###|$)/g, + /#### Build the test dependency image[\s\S]*?(?=\n##|\n###|$)/g, + /### Install Visual Studio Code extensions[\s\S]*?(?=\n##|\n###|$)/g, + /### Run the documentation locally[\s\S]*?(?=\n##|\n###|$)/g, + + // Testing and CI/CD sections (important but can be condensed) + /### Set up test scripts and credentials[\s\S]*?(?=\n##|\n###|$)/g, + /#### Test shell and python code blocks[\s\S]*?(?=\n##|\n###|$)/g, + /#### Troubleshoot tests[\s\S]*?(?=\n##|\n###|$)/g, + /### Pytest collected 0 items[\s\S]*?(?=\n##|\n###|$)/g, + + // Long code examples that can be referenced elsewhere + /```[\s\S]{500,}?```/g, + + // Repetitive examples + /#### Example[\s\S]*?(?=\n####|\n###|\n##|$)/g, + ]; + + // Remove identified sections + sectionsToRemove.forEach((regex) => { + content = content.replace(regex, ''); + }); + + // Condense whitespace + content = content.replace(/\n{3,}/g, '\n\n'); + + // Remove HTML comments + content = content.replace(//g, ''); + + // Shorten repetitive content + content = content.replace(/(\{%[^%]+%\})[\s\S]*?\1/g, (match) => { + // If it's a long repeated pattern, show it once with a note + if (match.length > 200) { + const firstOccurrence = match.split('\n\n')[0]; + return ( + firstOccurrence + + '\n\n[Similar patterns apply - see full CONTRIBUTING.md for complete examples]' + ); + } + return match; + }); + + return content; +} diff --git a/compose.yaml b/compose.yaml index 203f853c9..52c68a41a 100644 --- a/compose.yaml +++ b/compose.yaml @@ -303,14 +303,22 @@ services: container_name: influxdb3-core image: influxdb:3-core ports: - - 8181:8181 + - 8282:8181 command: - influxdb3 - serve - - --node-id=sensors_node0 + - --node-id=node0 - --log-filter=debug - --object-store=file - - --data-dir=/var/lib/influxdb3 + - --data-dir=/var/lib/influxdb3/data + - --plugin-dir=/var/lib/influxdb3/plugins + volumes: + - type: bind + source: test/.influxdb3/core/data + target: /var/lib/influxdb3/data + - type: bind + source: test/.influxdb3/core/plugins + target: /var/lib/influxdb3/plugins influxdb3-enterprise: container_name: influxdb3-enterprise image: influxdb:3-enterprise @@ -326,16 +334,16 @@ services: - --cluster-id=cluster0 - --log-filter=debug - --object-store=file - - --data-dir=/var/lib/influxdb3 + - --data-dir=/var/lib/influxdb3/data - --plugin-dir=/var/lib/influxdb3/plugins - --license-email=${INFLUXDB3_LICENSE_EMAIL} volumes: - type: bind - source: docker/influxdb3/data - target: /var/lib/influxdb3 + source: test/.influxdb3/enterprise/data + target: /var/lib/influxdb3/data - type: bind - source: docker/influxdb3/plugins - target: /var/lib/influxdb3-plugins + source: test/.influxdb3/enterprise/plugins + target: /var/lib/influxdb3/plugins telegraf-pytest: container_name: telegraf-pytest image: influxdata/docs-pytest diff --git a/config/staging/hugo.yml b/config/staging/hugo.yml index 3a0a651c2..7d22ffb17 100644 --- a/config/staging/hugo.yml +++ b/config/staging/hugo.yml @@ -13,6 +13,7 @@ minify: params: env: staging environment: staging -server: +server: { disableLiveReload: true +} \ No newline at end of file diff --git a/content/influxdb3/cloud-dedicated/admin/databases/delete.md b/content/influxdb3/cloud-dedicated/admin/databases/delete.md index fa59968db..4ae04e121 100644 --- a/content/influxdb3/cloud-dedicated/admin/databases/delete.md +++ b/content/influxdb3/cloud-dedicated/admin/databases/delete.md @@ -33,17 +33,19 @@ or the [Management HTTP API](/influxdb3/cloud-dedicated/api/management/) to delete a database from your {{< product-name omit=" Clustered" >}} cluster. > [!Warning] -> -> #### Deleting a database cannot be undone -> -> Once a database is deleted, data stored in that database cannot be recovered. -> > #### Wait before writing to a new database with the same name > > After deleting a database from your {{% product-name omit=" Clustered" %}} > cluster, you can reuse the name to create a new database, but **wait two to > three minutes** after deleting the previous database before writing to the new > database to allow write caches to clear. +> +> #### Tokens still grant access to databases with the same name +> +> [Database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/) are associated to +> databases by name. If you create a new database with the same name, tokens +> that granted access to the deleted database will also grant access to the new +> database. {{< tabs-wrapper >}} {{% tabs %}} diff --git a/content/influxdb3/cloud-dedicated/admin/databases/rename.md b/content/influxdb3/cloud-dedicated/admin/databases/rename.md new file mode 100644 index 000000000..788ab030d --- /dev/null +++ b/content/influxdb3/cloud-dedicated/admin/databases/rename.md @@ -0,0 +1,58 @@ +--- +title: Rename a database +description: > + Use the [`influxctl database rename` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/rename/) + to rename a database in your {{< product-name omit=" Cluster" >}} cluster. +menu: + influxdb3_cloud_dedicated: + parent: Manage databases +weight: 202 +list_code_example: | + ##### CLI + ```sh + influxctl database rename + ``` +related: + - /influxdb3/cloud-dedicated/reference/cli/influxctl/database/rename/ + - /influxdb3/cloud-dedicated/admin/tokens/database/create/ +--- + +Use the [`influxctl database rename` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/rename/) +to rename a database in your {{< product-name omit=" Cluster" >}} cluster. + +> [!Note] +> Renaming a database does not change the database ID, modify data in the database, +> or update [database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/). +> After renaming a database, any existing database tokens will stop working and you +> must create new tokens with permissions for the renamed database. + +## Rename a database using the influxctl CLI + +{{% code-placeholders "DATABASE_NAME|NEW_DATABASE_NAME" %}} +```sh +influxctl database rename DATABASE_NAME NEW_DATABASE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Current name of the database to rename +- {{% code-placeholder-key %}}`NEW_DATABASE_NAME`{{% /code-placeholder-key %}}: New name for the database + +## Update database tokens after renaming + +After renaming a database, existing database tokens will no longer work because +they reference the old database name. Do the following: + +1. [Create new database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/create/) + with permissions for the renamed database. +2. Update your applications and clients to use the new tokens. +3. [Delete the old database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/delete/) + that reference the old database name. + +{{% note %}} +#### Renamed database retains its ID + +The database ID remains the same after renaming. When you list databases, +you'll see the new name associated with the original database ID. +{{% /note %}} diff --git a/content/influxdb3/cloud-dedicated/admin/databases/undelete.md b/content/influxdb3/cloud-dedicated/admin/databases/undelete.md new file mode 100644 index 000000000..093cb3f8e --- /dev/null +++ b/content/influxdb3/cloud-dedicated/admin/databases/undelete.md @@ -0,0 +1,70 @@ +--- +title: Undelete a database +description: > + Use the [`influxctl database undelete` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/undelete/) + to restore a previously deleted database in your {{< product-name omit=" Cluster" >}} cluster. +menu: + influxdb3_cloud_dedicated: + parent: Manage databases +weight: 204 +list_code_example: | + ```sh + influxctl database undelete + ``` +related: + - /influxdb3/cloud-dedicated/reference/cli/influxctl/database/undelete/ + - /influxdb3/cloud-dedicated/admin/databases/delete/ + - /influxdb3/cloud-dedicated/admin/tokens/database/create/ +--- + +Use the [`influxctl database undelete` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/undelete/) +to restore a previously deleted database in your {{< product-name omit=" Cluster" >}} cluster. + +> [!Important] +> To undelete a database: +> +> - The database name must match the name of the deleted database. +> - A new database with the same name cannot already exist. +> - You must have appropriate permissions to manage databases. + +When you undelete a database, it is restored with the same retention period, +table limits, and column limits as when it was deleted. + +> [!Warning] +> Databases can only be undeleted for +> {{% show-in "cloud-dedicated" %}}approximately 14 days{{% /show-in %}}{{% show-in "clustered" %}}a configurable "hard-delete" grace period{{% /show-in %}} +> after they are deleted. +> After this grace period, all Parquet files associated with the deleted database +> are permanently removed and the database cannot be undeleted. + +## Undelete a database using the influxctl CLI + +{{% code-placeholders "DATABASE_NAME" %}} +```sh +influxctl database undelete DATABASE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Name of the deleted database to restore + +## Recreate tokens for the database + +After successfully undeleting a database: + +1. **Verify the database was restored** by [listing all databases](/influxdb3/cloud-dedicated/admin/databases/list/). +2. **If you previously deleted tokens associated with the deleted database, create new database tokens** + - Any tokens that existed before deletion are not restored. + [Create new database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/create/) + with appropriate permissions for the restored database. +3. **Update your applications** to use the new database tokens. + +{{% note %}} +#### Undeleted databases retain their original configuration + +When a database is undeleted, it retains the same database ID, retention period, +and table/column limits it had before deletion. However, database tokens are not +restored and must be recreated. +{{% /note %}} diff --git a/content/influxdb3/cloud-dedicated/admin/tables/delete.md b/content/influxdb3/cloud-dedicated/admin/tables/delete.md new file mode 100644 index 000000000..48b2d45c1 --- /dev/null +++ b/content/influxdb3/cloud-dedicated/admin/tables/delete.md @@ -0,0 +1,53 @@ +--- +title: Delete a table +description: > + Use the Admin UI or the [`influxctl table delete` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/delete/) + to delete a table from a database in your {{< product-name omit=" Cluster" >}} cluster. +menu: + influxdb3_cloud_dedicated: + parent: Manage tables +weight: 203 +list_code_example: | + ```sh + influxctl table delete + ``` +related: + - /influxdb3/cloud-dedicated/reference/cli/influxctl/table/delete/ +--- + +Use the Admin UI or the [`influxctl table delete` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/delete/) +to delete a table from a database in your {{< product-name omit=" Cluster" >}} cluster. + +> [!Warning] +> Deleting a table is irreversible. Once a table is deleted, all data stored in +> that table is permanently removed and cannot be recovered. + +Provide the following arguments: + +- **Database name**: Name of the database that contains the table to delete +- **Table name**: Name of the table to delete + +{{% code-placeholders "DATABASE_NAME|TABLE_NAME" %}} +```sh +influxctl table delete DATABASE_NAME TABLE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Name of the database that contains the table to delete +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: Name of the table to delete + +When prompted, enter `y` to confirm the deletion. + +{{% note %}} +#### Wait before reusing a deleted table name + +After deleting a table, wait a few minutes before attempting to create a new +table with the same name to ensure the deletion process has fully completed. + +{{% product-name %}} creates tables implicitly using table names specified in +line protocol written to the databases. To prevent the deleted table from being +immediately recreated by incoming write requests, pause all write requests to +the table before deleting it. +{{% /note %}} diff --git a/content/influxdb3/cloud-dedicated/admin/tables/list.md b/content/influxdb3/cloud-dedicated/admin/tables/list.md index 5533845e0..e900c5b24 100644 --- a/content/influxdb3/cloud-dedicated/admin/tables/list.md +++ b/content/influxdb3/cloud-dedicated/admin/tables/list.md @@ -1,7 +1,8 @@ --- title: List tables description: > - Use the Admin UI, the [`SHOW TABLES` SQL statement](/influxdb3/cloud-dedicated/query-data/sql/explore-schema/#list-measurements-in-a-database), + Use the Admin UI, the [`influxctl table list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/list/), + the [`SHOW TABLES` SQL statement](/influxdb3/cloud-dedicated/query-data/sql/explore-schema/#list-measurements-in-a-database), or the [`SHOW MEASUREMENTS` InfluxQL statement](/influxdb3/cloud-dedicated/query-data/influxql/explore-schema/#list-measurements-in-a-database) to list tables in a database. menu: @@ -9,23 +10,30 @@ menu: parent: Manage tables weight: 201 list_code_example: | - ###### SQL + ##### CLI + ```sh + influxctl table list + ``` + + ##### SQL ```sql SHOW TABLES ``` - ###### InfluxQL + ##### InfluxQL ```sql SHOW MEASUREMENTS ``` related: + - /influxdb3/cloud-dedicated/reference/cli/influxctl/table/list/ - /influxdb3/cloud-dedicated/query-data/sql/explore-schema/ - /influxdb3/cloud-dedicated/query-data/influxql/explore-schema/ --- -Use the Admin UI, the [`SHOW TABLES` SQL statement](/influxdb3/cloud-dedicated/query-data/sql/explore-schema/#list-measurements-in-a-database), +Use the Admin UI, the [`influxctl table list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/list/), +the [`SHOW TABLES` SQL statement](/influxdb3/cloud-dedicated/query-data/sql/explore-schema/#list-measurements-in-a-database), or the [`SHOW MEASUREMENTS` InfluxQL statement](/influxdb3/cloud-dedicated/query-data/influxql/explore-schema/#list-measurements-in-a-database) to list tables in a database. @@ -36,9 +44,11 @@ to list tables in a database. {{% tabs %}} [Admin UI](#admin-ui) [influxctl](#influxctl) +[SQL & InfluxQL](#sql--influxql) {{% /tabs %}} {{% tab-content %}} + The InfluxDB Cloud Dedicated administrative UI includes a portal for managing tables. You can view the list of tables associated with a database and their details, including: @@ -47,48 +57,94 @@ their details, including: - Table ID - Table size (in bytes) -1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser: +1. To access the {{< product-name >}} Admin UI, visit the following URL in your browser: - 
-   https://console.influxdata.com
-
-2. Use the credentials provided by InfluxData to log into the Admin UI. - If you don't have login credentials, [contact InfluxData support](https://support.influxdata.com). + 
+    https://console.influxdata.com
+
- After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/) - and lists all clusters associated with your account. -3. In the cluster list, find the cluster that contains the database and table. You can **Search** for clusters by name or ID to filter the list and use the sort button and column headers to sort the list. -4. Click the cluster row to view the list of databases associated with the cluster. -5. In the database list, find the database that contains the table. You can **Search** for databases by name or ID to filter the list and use the sort button and column headers to sort the list. -6. Click the database row to view the list of tables associated with the database. -7. The table list displays the following table details: - - Name - - Table ID - - Table size (in bytes) -8. You can **Search** for tables by name or ID to filter the list and use the sort button and column headers to sort the list. +2. Use the credentials provided by InfluxData to log into the Admin UI. + If you don't have login credentials, [contact InfluxData support](https://support.influxdata.com). -You can **Search** for databases by name or ID to filter the list and use the sort button and column headers to sort the list. + After you log in, the Account Management portal displays [account information](/influxdb3/cloud-dedicated/admin/account/) + and lists all clusters associated with your account. +3. In the cluster list, find the cluster that contains the database and table. + You can **Search** for clusters by name or ID to filter the list and use the sort button and column headers to sort the list. +4. Click the cluster row to view the list of databases associated with the cluster. +5. In the database list, find the database that contains the table. + You can **Search** for databases by name or ID to filter the list and use + the sort button and column headers to sort the list. +6. Click the database row to view the list of tables associated with the database. +7. The table list displays the following table details: + + - Name + - Table ID + - Table size (in bytes) + +8. You can **Search** for tables by name or ID to filter the list and use the + sort button and column headers to sort the list. + +You can **Search** for databases by name or ID to filter the list and use the +sort button and column headers to sort the list. + + {{% /tab-content %}} {{% tab-content %}} - -###### SQL + + +Use the [`influxctl table list` command](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/list/) +to list all tables in a database in your {{< product-name omit=" Cluster" >}} cluster. + +{{% code-placeholders "DATABASE_NAME" %}} + +```bash +influxctl table list DATABASE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Name of the database containing the tables to list + +### Output formats + +The `influxctl table list` command supports the following output formats: + +- `table` (default): Human-readable table format +- `json`: JSON format for programmatic use + +Use the `--format` flag to specify the output format: + +{{% code-placeholders "DATABASE_NAME" %}} +```sh +influxctl table list --format json DATABASE_NAME +``` +{{% /code-placeholders %}} + + +{{% /tab-content %}} +{{% tab-content %}} + + +## List tables with the influxctl query command + +To list tables using SQL or InfluxQL, use the `influxctl query` command to pass +the appropriate statement. + +### SQL ```sql SHOW TABLES ``` -###### InfluxQL +### InfluxQL ```sql SHOW MEASUREMENTS ``` -## List tables with the influxctl CLI - -To list tables using the `influxctl` CLI, use the `influxctl query` command to pass -the `SHOW TABLES` SQL statement. - Provide the following with your command: - **Database token**: [Database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens) @@ -98,17 +154,29 @@ Provide the following with your command: - **Database name**: Name of the database to query. Uses the `database` setting from the [`influxctl` connection profile](/influxdb3/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) or the `--database` command flag. -- **SQL query**: SQL query with the `SHOW TABLES` statement. +- **SQL query**: SQL query with the `SHOW TABLES` statement or InfluxQL query with the `SHOW MEASUREMENTS` statement. {{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} -```sh +##### SQL + +```bash influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ "SHOW TABLES" ``` +##### InfluxQL + +```bash +influxctl query \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + --language influxql \ + "SHOW MEASUREMENTS" +``` + {{% /code-placeholders %}} Replace the following: @@ -118,5 +186,6 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Name of the database to query + {{% /tab-content %}} -{{< /tabs-wrapper >}} \ No newline at end of file +{{< /tabs-wrapper >}} diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/_index.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/_index.md index ee894dca1..af137db40 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/_index.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/_index.md @@ -2,34 +2,12 @@ title: influxctl database description: > The `influxctl database` command and its subcommands manage databases in an - InfluxDB Cloud Dedicated cluster. + {{% product-name omit=" Clustered" %}} cluster. menu: influxdb3_cloud_dedicated: parent: influxctl weight: 201 +source: /shared/influxctl/database/_index.md --- -The `influxctl database` command and its subcommands manage databases in an -InfluxDB Cloud Dedicated cluster. - -## Usage - -```sh -influxctl database [subcommand] [flags] -``` - -## Subcommands - -| Subcommand | Description | -| :--------------------------------------------------------------------------- | :------------------ | -| [create](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/) | Create a database | -| [delete](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/delete/) | Delete a database | -| [list](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/list/) | List databases | -| [update](/influxdb3/cloud-dedicated/reference/cli/influxctl/database/update/) | Update a database | -| help, h | Output command help | - -## Flags - -| Flag | | Description | -| :--- | :------- | :------------------ | -| `-h` | `--help` | Output command help | + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create.md index 69e573cc0..d383c5c1f 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/create.md @@ -1,8 +1,8 @@ --- title: influxctl database create description: > - The `influxctl database create` command creates a new database in an InfluxDB - Cloud Dedicated cluster. + The `influxctl database create` command creates a new database in an + {{% product-name omit=" Clustered" %}} cluster. menu: influxdb3_cloud_dedicated: parent: influxctl database @@ -10,173 +10,7 @@ weight: 301 related: - /influxdb3/cloud-dedicated/admin/custom-partitions/define-custom-partitions/ - /influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/ +source: /shared/influxctl/database/create.md --- -The `influxctl database create` command creates a new database with a specified -retention period in an {{< product-name omit=" Clustered" >}} cluster. - -The retention period defines the maximum age of data retained in the database, -based on the timestamp of the data. -The retention period value is a time duration value made up of a numeric value -plus a duration unit. For example, `30d` means 30 days. -A zero duration retention period is infinite and data will not expire. -The retention period value cannot be negative or contain whitespace. - -{{< flex >}} -{{% flex-content "half" %}} - -##### Valid durations units include - -- **m**: minute -- **h**: hour -- **d**: day -- **w**: week -- **mo**: month -- **y**: year - -{{% /flex-content %}} -{{% flex-content "half" %}} - -##### Example retention period values - -- `0d`: infinite/none -- `3d`: 3 days -- `6w`: 6 weeks -- `1mo`: 1 month (30 days) -- `1y`: 1 year -- `30d30d`: 60 days -- `2.5d`: 60 hours - -{{% /flex-content %}} -{{< /flex >}} - -#### Custom partitioning - -You can override the default partition template (`%Y-%m-%d`) of the database -with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat` -flags when you create the database. -Provide a time format using [Rust strftime](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values -into a specified number of "buckets." -Each of these can be used as part of the partition template. -Be sure to follow [partitioning best practices](/influxdb3/cloud-dedicated/admin/custom-partitions/best-practices/). - -> [!Note] -> #### Always provide a time format when using custom partitioning -> -> If defining a custom partition template for your database with any of the -> `--template-*` flags, always include the `--template-timeformat` flag with a -> time format to use in your partition template. -> Otherwise, InfluxDB omits time from the partition template and won't compact partitions. - -> [!Warning] -> #### Wait before writing to a new database with the same name as a deleted database -> -> After deleting a database from your {{% product-name omit=" Clustered" %}} -> cluster, you can reuse the name to create a new database, but **wait two to -> three minutes** after deleting the previous database before writing to the new -> database to allow write caches to clear. - -## Usage - - - - -```sh -influxctl database create [flags] -``` - -## Arguments - -| Argument | Description | -| :---------------- | :--------------------- | -| **DATABASE_NAME** | InfluxDB database name | - -## Flags - -| Flag | | Description | -| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | -| | `--retention-period` | [Database retention period ](/influxdb3/cloud-dedicated/admin/databases/#retention-periods)(default is `0s`, infinite) | -| | `--max-tables` | [Maximum tables per database](/influxdb3/cloud-dedicated/admin/databases/#table-limit) (default is 500, `0` uses default) | -| | `--max-columns` | [Maximum columns per table](/influxdb3/cloud-dedicated/admin/databases/#column-limit) (default is 250, `0` uses default) | -| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) | -| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) | -| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} - -## Examples - -- [Create a database with an infinite retention period](#create-a-database-with-an-infinite-retention-period) -- [Create a database with a 30-day retention period](#create-a-database-with-a-30-day-retention-period) -- [Create a database with non-default table and column limits](#create-a-database-with-non-default-table-and-column-limits) -- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template) - -### Create a database with an infinite retention period - - - - -```sh -influxctl database create mydb -``` - -### Create a database with a 30-day retention period - - - - -```sh -influxctl database create \ - --retention-period 30d \ - mydb -``` - -### Create a database with non-default table and column limits - - - - -```sh -influxctl database create \ - --max-tables 200 \ - --max-columns 150 \ - mydb -``` - -### Create a database with a custom partition template - -The following example creates a new `mydb` database and applies a partition -template that partitions by two tags (`room` and `sensor-type`) and by day using -the time format `%Y-%m-%d`: - - - - -```sh -influxctl database create \ - --template-tag room \ - --template-tag sensor-type \ - --template-tag-bucket customerID,1000 \ - --template-timeformat '%Y-%m-%d' \ - mydb -``` - -_For more information about custom partitioning, see -[Manage data partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/)._ - -{{% expand "View command updates" %}} - -#### v2.7.0 {date="2024-03-26"} - -- Introduce the `--template-tag-bucket` flag to group tag values into buckets - and partition by each tag bucket. - -#### v2.5.0 {date="2024-03-04"} - -- Introduce the `--template-tag` and `--template-timeformat` flags that define - a custom partition template for a database. - -{{% /expand %}} + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/delete.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/delete.md index 23c76b6dc..f12ee7ccc 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/delete.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/delete.md @@ -1,71 +1,13 @@ --- title: influxctl database delete description: > - The `influxctl database delete` command deletes a database from an InfluxDB - Cloud Dedicated cluster. + The `influxctl database delete` command deletes a database from an + {{% product-name omit=" Clustered" %}} cluster. menu: influxdb3_cloud_dedicated: parent: influxctl database weight: 301 +source: /shared/influxctl/database/delete.md --- -The `influxctl database delete` command deletes a database from an -{{< product-name omit=" Clustered" >}} cluster. - -## Usage - - - - -```sh -influxctl database delete [command options] [--force] [...] -``` - -> [!Warning] -> #### Cannot be undone -> -> Deleting a database is a destructive action that cannot be undone. -> -> #### Wait before writing to a new database with the same name -> -> After deleting a database from your {{% product-name omit=" Clustered" %}} -> cluster, you can reuse the name to create a new database, but **wait two to -> three minutes** after deleting the previous database before writing to the new -> database to allow write caches to clear. - -## Arguments - -| Argument | Description | -| :---------------- | :----------------------------- | -| **DATABASE_NAME** | Name of the database to delete | - -## Flags - -| Flag | | Description | -| :--- | :-------- | :---------------------------------------------------------- | -| | `--force` | Do not prompt for confirmation to delete (default is false) | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} - -## Examples - -##### Delete a database named "mydb" - - - - -```sh -influxctl database delete mydb -``` - -##### Delete multiple databases - - - - -```sh -influxctl database delete mydb1 mydb2 -``` + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/list.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/list.md index f3f4b3466..9a938b214 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/list.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/list.md @@ -1,34 +1,13 @@ --- title: influxctl database list description: > - The `influxctl database list` command lists all databases in an InfluxDB Cloud - Dedicated cluster. + The `influxctl database list` command lists all databases in an + {{% product-name omit=" Clustered" %}} cluster. menu: influxdb3_cloud_dedicated: parent: influxctl database weight: 301 +source: /shared/influxctl/database/list.md --- -The `influxctl database list` command lists all databases in an InfluxDB Cloud -Dedicated cluster. - -The `--format` flag lets you print the output in other formats. -The `json` format is available for programmatic parsing by other tooling. -Default: `table`. - -## Usage - -```sh -influxctl database list [--format=table|json] -``` - -## Flags - -| Flag | | Description | -| :--- | :--------- | :-------------------------------------------- | -| | `--format` | Output format (`table` _(default)_ or `json`) | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/rename.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/rename.md new file mode 100644 index 000000000..ede2644e3 --- /dev/null +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/rename.md @@ -0,0 +1,14 @@ +--- +title: influxctl database rename +description: > + The `influxctl database rename` command renames a database in an + {{% product-name omit=" Clustered" %}} cluster. +menu: + influxdb3_cloud_dedicated: + parent: influxctl database +weight: 301 +metadata: [influxctl 2.10.2+] +source: /shared/influxctl/database/rename.md +--- + + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/undelete.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/undelete.md new file mode 100644 index 000000000..7e8624d67 --- /dev/null +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/undelete.md @@ -0,0 +1,14 @@ +--- +title: influxctl database undelete +description: > + The `influxctl database undelete` command undeletes a previously deleted + database in an {{% product-name omit=" Clustered" %}} cluster. +menu: + influxdb3_cloud_dedicated: + parent: influxctl database +weight: 301 +metadata: [influxctl 2.10.2+] +source: /shared/influxctl/database/undelete.md +--- + + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/update.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/update.md index 7e127c01e..d1f48b42b 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/update.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/database/update.md @@ -7,86 +7,7 @@ menu: influxdb3_cloud_dedicated: parent: influxctl database weight: 301 +source: /shared/influxctl/database/update.md --- -The `influxctl database update` command updates a database's retention period, -table (measurement), or column limits in InfluxDB. - -## Usage - - - -```sh -influxctl database update [flags] -``` - -## Arguments - -| Argument | Description | -| :---------------- | :----------------------------- | -| **DATABASE_NAME** | Name of the database to update | - -## Flags - -| Flag | | Description | -| :--- | :------------------- | :----------------------------------------------------------- | -| | `--retention-period` | [Database retention period ](/influxdb3/cloud-dedicated/admin/databases/#retention-periods)(default is `0s` or infinite) | -| | `--max-tables` | [Maximum tables per database](/influxdb3/cloud-dedicated/admin/databases/#table-limit) (default is 500, 0 uses default) | -| | `--max-columns` | [Maximum columns per table](/influxdb3/cloud-dedicated/admin/databases/#column-limit) (default is 250, 0 uses default) | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} - -## Examples - -- [Update a database's retention period](#update-a-databases-retention-period) -- [Update a database's table limit](#update-a-databases-table-limit) -- [Update a database's column limit](#update-a-databases-column-limit) - -### Update a database's retention period - -```sh -influxctl database update --retention-period 1mo mydb -``` - -{{< flex >}} -{{% flex-content "half" %}} - -##### Valid durations units - -- `m`: minute -- `h`: hour -- `d`: day -- `w`: week -- `mo`: month -- `y`: year - -{{% /flex-content %}} -{{% flex-content "half" %}} - -##### Example retention period values - -- `0d`: infinite/none -- `3d`: 3 days -- `6w`: 6 weeks -- `1mo`: 1 month (30 days) -- `1y`: 1 year -- `30d30d`: 60 days -- `2.5d`: 60 hours - -{{% /flex-content %}} -{{< /flex >}} - -### Update a database's table limit - -```sh -influxctl database update --max-tables 300 mydb -``` - -### Update a database's column limit - -```sh -influxctl database update --max-columns 200 mydb -``` + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/_index.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/_index.md index bcab7f10b..a5761b73f 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/_index.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/_index.md @@ -9,25 +9,7 @@ menu: weight: 201 cascade: metadata: [influxctl 2.5.0+] +source: /shared/influxctl/table/_index.md --- -The `influxctl table` command and its subcommands manage tables in an -InfluxDB Cloud Dedicated cluster. - -## Usage - -```sh -influxctl table [subcommand] [flags] -``` - -## Subcommands - -| Subcommand | Description | -| :------------------------------------------------------------------------ | :------------- | -| [create](/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create/) | Create a table | - -## Flags - -| Flag | | Description | -| :--- | :------- | :------------------ | -| `-h` | `--help` | Output command help | + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create.md index 8367e4926..1476a8c43 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/create.md @@ -9,101 +9,7 @@ weight: 301 related: - /influxdb3/cloud-dedicated/admin/custom-partitions/define-custom-partitions/ - /influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/ +source: /shared/influxctl/table/create.md --- -The `influxctl table create` command creates a new table in the specified -database in an {{< product-name omit=" Clustered" >}} cluster. - -#### Custom partitioning - -You can override the default partition template (the partition template of the target database) -with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat` -flags when you create the table. -Provide a time format using [Rust strftime](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values -into a specified number of "buckets." -Each of these can be used as part of the partition template. -Be sure to follow [partitioning best practices](/influxdb3/cloud-dedicated/admin/custom-partitions/best-practices/). - -> [!Note] -> #### Always provide a time format when using custom partitioning -> -> If defining a custom partition template for your table with any of the -> `--template-*` flags, always include the `--template-timeformat` flag with a -> time format to use in your partition template. -> Otherwise, InfluxDB omits time from the partition template and won't compact partitions. - -## Usage - -```sh -influxctl table create [flags] -``` - -## Arguments - -| Argument | Description | -| :---------------- | :-------------------------- | -| **DATABASE_NAME** | Name of the target database | -| **TABLE_NAME** | Table name | - -## Flags - -| Flag | | Description | -| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | -| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) | -| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) | -| | `--template-timeformat` | Timestamp format for partition template | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} - -## Examples - -- [Create a table](#create-a-table) -- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template) - -In the following examples, replace: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: - The name of the database to create the table in. -- {{% code-placeholder-key %}}`TABLE_NAME` {{% /code-placeholder-key %}}: - The name of table to create. - -### Create a table - -{{% code-placeholders "(DATABASE|TABLE)_NAME" %}} -```sh -influxctl table create DATABASE_NAME TABLE_NAME -``` -{{% /code-placeholders %}} - -### Create a table with a custom partition template - -The following example creates a new table and applies a partition -template that partitions by two tags (`room` and `sensor-type`) and by day using -the time format `%Y-%m-%d`: - -{{% code-placeholders "(DATABASE|TABLE)_NAME" %}} -```sh -influxctl table create \ - --template-tag room \ - --template-tag sensor-type \ - --template-tag-bucket customerID,1000 \ - --template-timeformat '%Y-%m-%d' \ - DATABASE_NAME \ - TABLE_NAME -``` -{{% /code-placeholders %}} - -_For more information about custom partitioning, see -[Manage data partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/)._ - -{{% expand "View command updates" %}} - -#### v2.7.0 {date="2024-03-26"} - -- Introduce the `--template-tag-bucket` flag to group tag values into buckets - and partition by each tag bucket. - -{{% /expand %}} + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/delete.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/delete.md new file mode 100644 index 000000000..b47ace280 --- /dev/null +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/delete.md @@ -0,0 +1,15 @@ +--- +title: influxctl table delete +description: > + The `influxctl table delete` command deletes a specified table from a database. +menu: + influxdb3_cloud_dedicated: + parent: influxctl table +weight: 301 +related: + - /influxdb3/cloud-dedicated/admin/tables/delete/ +metadata: [influxctl 2.10.2+] +source: /shared/influxctl/table/delete.md +--- + + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/_index.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/_index.md new file mode 100644 index 000000000..5e9475aad --- /dev/null +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/_index.md @@ -0,0 +1,15 @@ +--- +title: influxctl table iceberg +description: > + The `influxctl table iceberg` command and its subcommands enable or disable + Iceberg-compatible exports for a table in an InfluxDB Cloud Dedicated cluster. +menu: + influxdb3_cloud_dedicated: + parent: influxctl table +weight: 301 +cascade: + metadata: [influxctl 2.10.2+] +source: /shared/influxctl/table/iceberg/_index.md +--- + + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/disable.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/disable.md new file mode 100644 index 000000000..b67192c2b --- /dev/null +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/disable.md @@ -0,0 +1,13 @@ +--- +title: influxctl table iceberg disable +description: > + The `influxctl table iceberg disable` command disables Iceberg-compatible exports + for a table in an InfluxDB Cloud Dedicated cluster. +menu: + influxdb3_cloud_dedicated: + parent: influxctl table iceberg +weight: 401 +source: /shared/influxctl/table/iceberg/disable.md +--- + + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/enable.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/enable.md new file mode 100644 index 000000000..5f02ba002 --- /dev/null +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/iceberg/enable.md @@ -0,0 +1,13 @@ +--- +title: influxctl table iceberg enable +description: > + The `influxctl table iceberg enable` command enables Iceberg-compatible exports + for a table in an InfluxDB Cloud Dedicated cluster. +menu: + influxdb3_cloud_dedicated: + parent: influxctl table iceberg +weight: 401 +source: /shared/influxctl/table/iceberg/enable.md +--- + + diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/list.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/list.md new file mode 100644 index 000000000..de83b1432 --- /dev/null +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/table/list.md @@ -0,0 +1,15 @@ +--- +title: influxctl table list +description: > + The `influxctl table list` command lists all tables in the specified database. +menu: + influxdb3_cloud_dedicated: + parent: influxctl table +weight: 301 +related: + - /influxdb3/cloud-dedicated/admin/tables/list/ +metadata: [influxctl 2.10.2+] +source: /shared/influxctl/table/list.md +--- + + diff --git a/content/influxdb3/clustered/admin/databases/delete.md b/content/influxdb3/clustered/admin/databases/delete.md index 9f39e8fd5..6b64122bf 100644 --- a/content/influxdb3/clustered/admin/databases/delete.md +++ b/content/influxdb3/clustered/admin/databases/delete.md @@ -33,16 +33,19 @@ influxctl database delete DATABASE_NAME {{% /code-placeholders %}} > [!Warning] -> #### Deleting a database cannot be undone -> -> Once a database is deleted, data stored in that database cannot be recovered. -> > #### Wait before writing to a new database with the same name > > After deleting a database from your {{% product-name omit=" Clustered" %}} > cluster, you can reuse the name to create a new database, but **wait two to > three minutes** after deleting the previous database before writing to the new > database to allow write caches to clear. +> +> #### Tokens still grant access to databases with the same name +> +> [Database tokens](/influxdb3/clustered/admin/tokens/database/) are associated to +> databases by name. If you create a new database with the same name, tokens +> that granted access to the deleted database will also grant access to the new +> database. > > #### Never directly modify the Catalog > diff --git a/content/influxdb3/clustered/admin/databases/rename.md b/content/influxdb3/clustered/admin/databases/rename.md new file mode 100644 index 000000000..e83d16cdb --- /dev/null +++ b/content/influxdb3/clustered/admin/databases/rename.md @@ -0,0 +1,58 @@ +--- +title: Rename a database +description: > + Use the [`influxctl database rename` command](/influxdb3/clustered/reference/cli/influxctl/database/rename/) + to rename a database in your {{< product-name omit=" Cluster" >}} cluster. +menu: + influxdb3_clustered: + parent: Manage databases +weight: 202 +list_code_example: | + ##### CLI + ```sh + influxctl database rename + ``` +related: + - /influxdb3/clustered/reference/cli/influxctl/database/rename/ + - /influxdb3/clustered/admin/tokens/database/create/ +--- + +Use the [`influxctl database rename` command](/influxdb3/clustered/reference/cli/influxctl/database/rename/) +to rename a database in your {{< product-name omit=" Cluster" >}} cluster. + +> [!Note] +> Renaming a database does not change the database ID, modify data in the database, +> or update [database tokens](/influxdb3/clustered/admin/tokens/database/). +> After renaming a database, any existing database tokens will stop working and you +> must create new tokens with permissions for the renamed database. + +## Rename a database using the influxctl CLI + +{{% code-placeholders "DATABASE_NAME|NEW_DATABASE_NAME" %}} +```sh +influxctl database rename DATABASE_NAME NEW_DATABASE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Current name of the database to rename +- {{% code-placeholder-key %}}`NEW_DATABASE_NAME`{{% /code-placeholder-key %}}: New name for the database + +## Update database tokens after renaming + +After renaming a database, existing database tokens will no longer work because +they reference the old database name. Do the following: + +1. [Create new database tokens](/influxdb3/clustered/admin/tokens/database/create/) + with permissions for the renamed database. +2. Update your applications and clients to use the new tokens. +3. [Delete the old database tokens](/influxdb3/clustered/admin/tokens/database/delete/) + that reference the old database name. + +{{% note %}} +#### Renamed database retains its ID + +The database ID remains the same after renaming. When you list databases, +you'll see the new name associated with the original database ID. +{{% /note %}} diff --git a/content/influxdb3/clustered/admin/databases/undelete.md b/content/influxdb3/clustered/admin/databases/undelete.md new file mode 100644 index 000000000..5b2e4562b --- /dev/null +++ b/content/influxdb3/clustered/admin/databases/undelete.md @@ -0,0 +1,70 @@ +--- +title: Undelete a database +description: > + Use the [`influxctl database undelete` command](/influxdb3/clustered/reference/cli/influxctl/database/undelete/) + to restore a previously deleted database in your {{< product-name omit=" Cluster" >}} cluster. +menu: + influxdb3_clustered: + parent: Manage databases +weight: 204 +list_code_example: | + ```sh + influxctl database undelete + ``` +related: + - /influxdb3/clustered/reference/cli/influxctl/database/undelete/ + - /influxdb3/clustered/admin/databases/delete/ + - /influxdb3/clustered/admin/tokens/database/create/ +--- + +Use the [`influxctl database undelete` command](/influxdb3/clustered/reference/cli/influxctl/database/undelete/) +to restore a previously deleted database in your {{< product-name omit=" Cluster" >}} cluster. + +> [!Important] +> To undelete a database: +> +> - The database name must match the name of the deleted database. +> - A new database with the same name cannot already exist. +> - You must have appropriate permissions to manage databases. + +When you undelete a database, it is restored with the same retention period, +table limits, and column limits as when it was deleted. + +> [!Warning] +> Databases can only be undeleted for +> {{% show-in "cloud-dedicated" %}}approximately 14 days{{% /show-in %}}{{% show-in "clustered" %}}a configurable "hard-delete" grace period{{% /show-in %}} +> after they are deleted. +> After this grace period, all Parquet files associated with the deleted database +> are permanently removed and the database cannot be undeleted. + +## Undelete a database using the influxctl CLI + +{{% code-placeholders "DATABASE_NAME" %}} +```sh +influxctl database undelete DATABASE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Name of the deleted database to restore + +## Recreate tokens for the database + +After successfully undeleting a database: + +1. **Verify the database was restored** by [listing all databases](/influxdb3/clustered/admin/databases/list/). +2. **If you previously deleted tokens associated with the deleted database, create new database tokens** + - Any tokens that existed before deletion are not restored. + [Create new database tokens](/influxdb3/clustered/admin/tokens/database/create/) + with appropriate permissions for the restored database. +3. **Update your applications** to use the new database tokens. + +{{% note %}} +#### Undeleted databases retain their original configuration + +When a database is undeleted, it retains the same database ID, retention period, +and table/column limits it had before deletion. However, database tokens are not +restored and must be recreated. +{{% /note %}} diff --git a/content/influxdb3/clustered/admin/tables/delete.md b/content/influxdb3/clustered/admin/tables/delete.md new file mode 100644 index 000000000..010fcb5e6 --- /dev/null +++ b/content/influxdb3/clustered/admin/tables/delete.md @@ -0,0 +1,52 @@ +--- +title: Delete a table +description: > + Use the Admin UI or the [`influxctl table delete` command](/influxdb3/clustered/reference/cli/influxctl/table/delete/) + to delete a table from a database in your {{< product-name omit=" Cluster" >}} cluster. +menu: + influxdb3_clustered: + parent: Manage tables +weight: 203 +list_code_example: | + ```sh + influxctl table delete + ``` +related: + - /influxdb3/clustered/reference/cli/influxctl/table/delete/ +--- + +Use the Admin UI or the [`influxctl table delete` command](/influxdb3/clustered/reference/cli/influxctl/table/delete/) +to delete a table from a database in your {{< product-name omit=" Cluster" >}} cluster. + +> [!Warning] +> Deleting a table is irreversible. Once a table is deleted, all data stored in +> that table is permanently removed and cannot be recovered. + +Provide the following arguments: + +- **Database name**: Name of the database that contains the table to delete +- **Table name**: Name of the table to delete + +{{% code-placeholders "DATABASE_NAME|TABLE_NAME" %}} +```sh +influxctl table delete DATABASE_NAME TABLE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Name of the database that contains the table to delete +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: Name of the table to delete + +When prompted, enter `y` to confirm the deletion. + +> [!Note] +> #### Wait before reusing a deleted table name +> +> After deleting a table, wait a few minutes before attempting to create a new +> table with the same name to ensure the deletion process has fully completed. +> +> {{% product-name %}} creates tables implicitly using table names specified in +> line protocol written to the databases. To prevent the deleted table from being +> immediately recreated by incoming write requests, pause all write requests to +> the table before deleting it. diff --git a/content/influxdb3/clustered/admin/tables/list.md b/content/influxdb3/clustered/admin/tables/list.md index 228155434..7f604a1a3 100644 --- a/content/influxdb3/clustered/admin/tables/list.md +++ b/content/influxdb3/clustered/admin/tables/list.md @@ -1,7 +1,8 @@ --- title: List tables description: > - Use the [`SHOW TABLES` SQL statement](/influxdb3/clustered/query-data/sql/explore-schema/#list-measurements-in-a-database) + Use the [`influxctl table list` command](/influxdb3/clustered/reference/cli/influxctl/table/list/), + the [`SHOW TABLES` SQL statement](/influxdb3/clustered/query-data/sql/explore-schema/#list-measurements-in-a-database), or the [`SHOW MEASUREMENTS` InfluxQL statement](/influxdb3/clustered/query-data/influxql/explore-schema/#list-measurements-in-a-database) to list tables in a database. menu: @@ -9,49 +10,96 @@ menu: parent: Manage tables weight: 201 list_code_example: | - ###### SQL + ##### CLI + ```sh + influxctl table list + ``` + + ##### SQL ```sql SHOW TABLES ``` - ###### InfluxQL + ##### InfluxQL ```sql SHOW MEASUREMENTS ``` related: + - /influxdb3/clustered/reference/cli/influxctl/table/list/ - /influxdb3/clustered/query-data/sql/explore-schema/ - /influxdb3/clustered/query-data/influxql/explore-schema/ --- -Use the [`SHOW TABLES` SQL statement](/influxdb3/clustered/query-data/sql/explore-schema/#list-measurements-in-a-database) +Use the [`influxctl table list` command](/influxdb3/clustered/reference/cli/influxctl/table/list/), +the [`SHOW TABLES` SQL statement](/influxdb3/clustered/query-data/sql/explore-schema/#list-measurements-in-a-database), or the [`SHOW MEASUREMENTS` InfluxQL statement](/influxdb3/clustered/query-data/influxql/explore-schema/#list-measurements-in-a-database) to list tables in a database. > [!Note] > With {{< product-name >}}, tables and measurements are synonymous. -###### SQL +{{< tabs-wrapper >}} +{{% tabs %}} +[influxctl](#influxctl) +[SQL & InfluxQL](#sql--influxql) +{{% /tabs %}} +{{% tab-content %}} + + +Use the [`influxctl table list` command](/influxdb3/clustered/reference/cli/influxctl/table/list/) +to list all tables in a database in your {{< product-name omit=" Cluster" >}}. + +{{% code-placeholders "DATABASE_NAME" %}} + +```bash +influxctl table list DATABASE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Name of the database containing the tables to list + +### Output formats + +The `influxctl table list` command supports the following output formats: + +- `table` (default): Human-readable table format +- `json`: JSON format for programmatic use + +Use the `--format` flag to specify the output format: + +{{% code-placeholders "DATABASE_NAME" %}} +```sh +influxctl table list --format json DATABASE_NAME +``` +{{% /code-placeholders %}} + + +{{% /tab-content %}} +{{% tab-content %}} + + +## List tables with the influxctl query command + +To list tables using SQL or InfluxQL, use the `influxctl query` command to pass +the appropriate statement. + +### SQL ```sql SHOW TABLES ``` -###### InfluxQL +### InfluxQL ```sql SHOW MEASUREMENTS ``` -## List tables with the influxctl CLI - -To list tables using the `influxctl` CLI, use the `influxctl query` command to pass -the `SHOW TABLES` SQL statement. - -> [!Note] -> The `influxctl query` command only supports SQL queries; not InfluxQL. - Provide the following with your command: - **Database token**: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) @@ -61,17 +109,29 @@ Provide the following with your command: - **Database name**: Name of the database to query. Uses the `database` setting from the [`influxctl` connection profile](/influxdb3/clustered/reference/cli/influxctl/#configure-connection-profiles) or the `--database` command flag. -- **SQL query**: SQL query with the `SHOW TABLES` statement. +- **SQL query**: SQL query with the `SHOW TABLES` statement or InfluxQL query with the `SHOW MEASUREMENTS` statement. {{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} -```sh +##### SQL + +```bash influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ "SHOW TABLES" ``` +##### InfluxQL + +```bash +influxctl query \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + --language influxql \ + "SHOW MEASUREMENTS" +``` + {{% /code-placeholders %}} Replace the following: @@ -81,3 +141,11 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Name of the database to query +> [!Note] +> The `influxctl query` command only supports SQL queries; not InfluxQL. +> To use InfluxQL, query InfluxDB through the API using InfluxQL request parameters. + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/database/_index.md b/content/influxdb3/clustered/reference/cli/influxctl/database/_index.md index 7ff42e7dd..3b42a31a4 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/database/_index.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/database/_index.md @@ -2,34 +2,12 @@ title: influxctl database description: > The `influxctl database` command and its subcommands manage databases in an - InfluxDB cluster. + {{% product-name omit=" Clustered" %}} cluster. menu: influxdb3_clustered: parent: influxctl weight: 201 +source: /shared/influxctl/database/_index.md --- -The `influxctl database` command and its subcommands manage databases in an -InfluxDB cluster. - -## Usage - -```sh -influxctl database [subcommand] [flags] -``` - -## Subcommands - -| Subcommand | Description | -| :--------------------------------------------------------------------------- | :------------------ | -| [create](/influxdb3/clustered/reference/cli/influxctl/database/create/) | Create a database | -| [delete](/influxdb3/clustered/reference/cli/influxctl/database/delete/) | Delete a database | -| [list](/influxdb3/clustered/reference/cli/influxctl/database/list/) | List databases | -| [update](/influxdb3/clustered/reference/cli/influxctl/database/update/) | Update a database | -| help, h | Output command help | - -## Flags - -| Flag | | Description | -| :--- | :------- | :------------------ | -| `-h` | `--help` | Output command help | + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/database/create.md b/content/influxdb3/clustered/reference/cli/influxctl/database/create.md index 7a71ec00d..7bb2031c0 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/database/create.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/database/create.md @@ -1,7 +1,8 @@ --- title: influxctl database create description: > - The `influxctl database create` command creates a new database in an InfluxDB cluster. + The `influxctl database create` command creates a new database in an + {{% product-name omit=" Clustered" %}} cluster. menu: influxdb3_clustered: parent: influxctl database @@ -9,173 +10,7 @@ weight: 301 related: - /influxdb3/clustered/admin/custom-partitions/define-custom-partitions/ - /influxdb3/clustered/admin/custom-partitions/partition-templates/ +source: /shared/influxctl/database/create.md --- -The `influxctl database create` command creates a new database with a specified -retention period in an {{< product-name omit=" Clustered" >}} cluster. - -The retention period defines the maximum age of data retained in the database, -based on the timestamp of the data. -The retention period value is a time duration value made up of a numeric value -plus a duration unit. For example, `30d` means 30 days. -A zero duration retention period is infinite and data will not expire. -The retention period value cannot be negative or contain whitespace. - -{{< flex >}} -{{% flex-content "half" %}} - -##### Valid durations units include - -- **m**: minute -- **h**: hour -- **d**: day -- **w**: week -- **mo**: month -- **y**: year - -{{% /flex-content %}} -{{% flex-content "half" %}} - -##### Example retention period values - -- `0d`: infinite/none -- `3d`: 3 days -- `6w`: 6 weeks -- `1mo`: 1 month (30 days) -- `1y`: 1 year -- `30d30d`: 60 days -- `2.5d`: 60 hours - -{{% /flex-content %}} -{{< /flex >}} - -#### Custom partitioning - -You can override the default partition template (`%Y-%m-%d`) of the database -with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat` -flags when you create the database. -Provide a time format using [Rust strftime](/influxdb3/clustered/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values -into a specified number of "buckets." -Each of these can be used as part of the partition template. -Be sure to follow [partitioning best practices](/influxdb3/clustered/admin/custom-partitions/best-practices/). - -> [!Note] -> #### Always provide a time format when using custom partitioning -> -> If defining a custom partition template for your database with any of the -> `--template-*` flags, always include the `--template-timeformat` flag with a -> time format to use in your partition template. -> Otherwise, InfluxDB omits time from the partition template and won't compact partitions. - -> [!Warning] -> #### Wait before writing to a new database with the same name as a deleted database -> -> After deleting a database from your {{% product-name omit=" Clustered" %}} -> cluster, you can reuse the name to create a new database, but **wait two to -> three minutes** after deleting the previous database before writing to the new -> database to allow write caches to clear. - -## Usage - - - - -```sh -influxctl database create [flags] -``` - -## Arguments - -| Argument | Description | -| :---------------- | :--------------------- | -| **DATABASE_NAME** | InfluxDB database name | - -## Flags - -| Flag | | Description | -| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | -| | `--retention-period` | [Database retention period ](/influxdb3/clustered/admin/databases/#retention-periods)(default is `0s`, infinite) | -| | `--max-tables` | [Maximum tables per database](/influxdb3/clustered/admin/databases/#table-limit) (default is 500, `0` uses default) | -| | `--max-columns` | [Maximum columns per table](/influxdb3/clustered/admin/databases/#column-limit) (default is 250, `0` uses default) | -| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) | -| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) | -| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/clustered/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} - -## Examples - -- [Create a database with an infinite retention period](#create-a-database-with-an-infinite-retention-period) -- [Create a database with a 30-day retention period](#create-a-database-with-a-30-day-retention-period) -- [Create a database with non-default table and column limits](#create-a-database-with-non-default-table-and-column-limits) -- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template) - -### Create a database with an infinite retention period - - - - -```sh -influxctl database create mydb -``` - -### Create a database with a 30-day retention period - - - - -```sh -influxctl database create \ - --retention-period 30d \ - mydb -``` - -### Create a database with non-default table and column limits - - - - -```sh -influxctl database create \ - --max-tables 200 \ - --max-columns 150 \ - mydb -``` - -### Create a database with a custom partition template - -The following example creates a new `mydb` database and applies a partition -template that partitions by two tags (`room` and `sensor-type`) and by day using -the time format `%Y-%m-%d`: - - - - -```sh -influxctl database create \ - --template-tag room \ - --template-tag sensor-type \ - --template-tag-bucket customerID,1000 \ - --template-timeformat '%Y-%m-%d' \ - mydb -``` - -_For more information about custom partitioning, see -[Manage data partitioning](/influxdb3/clustered/admin/custom-partitions/)._ - -{{% expand "View command updates" %}} - -#### v2.7.0 {date="2024-03-26"} - -- Introduce the `--template-tag-bucket` flag to group tag values into buckets - and partition by each tag bucket. - -#### v2.5.0 {date="2024-03-04"} - -- Introduce the `--template-tag` and `--template-timeformat` flags that define - a custom partition template for a database. - -{{% /expand %}} + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/database/delete.md b/content/influxdb3/clustered/reference/cli/influxctl/database/delete.md index 990a0b662..70bd0e33e 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/database/delete.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/database/delete.md @@ -7,65 +7,7 @@ menu: influxdb3_clustered: parent: influxctl database weight: 301 +source: /shared/influxctl/database/delete.md --- -The `influxctl database delete` command deletes a database from an -{{< product-name omit=" Clustered" >}} cluster. - -## Usage - - - - -```sh -influxctl database delete [command options] [--force] [...] -``` - -> [!Warning] -> #### Cannot be undone -> -> Deleting a database is a destructive action that cannot be undone. -> -> #### Wait before writing to a new database with the same name -> -> After deleting a database from your {{% product-name omit=" Clustered" %}} -> cluster, you can reuse the name to create a new database, but **wait two to -> three minutes** after deleting the previous database before writing to the new -> database to allow write caches to clear. - -## Arguments - -| Argument | Description | -| :---------------- | :----------------------------- | -| **DATABASE_NAME** | Name of the database to delete | - -## Flags - -| Flag | | Description | -| :--- | :-------- | :---------------------------------------------------------- | -| | `--force` | Do not prompt for confirmation to delete (default is false) | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/clustered/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} - -## Examples - -##### Delete a database named "mydb" - - - - -```sh -influxctl database delete mydb -``` - -##### Delete multiple databases - - - - -```sh -influxctl database delete mydb1 mydb2 -``` + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/database/list.md b/content/influxdb3/clustered/reference/cli/influxctl/database/list.md index 1bb620217..d8c7241d4 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/database/list.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/database/list.md @@ -1,34 +1,13 @@ --- title: influxctl database list description: > - The `influxctl database list` command lists all databases in an InfluxDB Cloud - Dedicated cluster. + The `influxctl database list` command lists all databases in an + {{% product-name omit=" Clustered" %}} cluster. menu: influxdb3_clustered: parent: influxctl database weight: 301 +source: /shared/influxctl/database/list.md --- -The `influxctl database list` command lists all databases in an InfluxDB Cloud -Dedicated cluster. - -The `--format` flag lets you print the output in other formats. -The `json` format is available for programmatic parsing by other tooling. -Default: `table`. - -## Usage - -```sh -influxctl database list [--format=table|json] -``` - -## Flags - -| Flag | | Description | -| :--- | :--------- | :-------------------------------------------- | -| | `--format` | Output format (`table` _(default)_ or `json`) | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/clustered/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/database/rename.md b/content/influxdb3/clustered/reference/cli/influxctl/database/rename.md new file mode 100644 index 000000000..36f21f978 --- /dev/null +++ b/content/influxdb3/clustered/reference/cli/influxctl/database/rename.md @@ -0,0 +1,14 @@ +--- +title: influxctl database rename +description: > + The `influxctl database rename` command renames a database in an + {{% product-name omit=" Clustered" %}} cluster. +menu: + influxdb3_clustered: + parent: influxctl database +weight: 301 +metadata: [influxctl 2.10.2+] +source: /shared/influxctl/database/rename.md +--- + + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/database/undelete.md b/content/influxdb3/clustered/reference/cli/influxctl/database/undelete.md new file mode 100644 index 000000000..3ac70ed62 --- /dev/null +++ b/content/influxdb3/clustered/reference/cli/influxctl/database/undelete.md @@ -0,0 +1,14 @@ +--- +title: influxctl database undelete +description: > + The `influxctl database undelete` command undeletes a previously deleted + database in an {{% product-name omit=" Clustered" %}} cluster. +menu: + influxdb3_clustered: + parent: influxctl database +weight: 301 +metadata: [influxctl 2.10.2+] +source: /shared/influxctl/database/undelete.md +--- + + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/database/update.md b/content/influxdb3/clustered/reference/cli/influxctl/database/update.md index 13f2884d6..2a04432ce 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/database/update.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/database/update.md @@ -7,86 +7,7 @@ menu: influxdb3_clustered: parent: influxctl database weight: 301 +source: /shared/influxctl/database/update.md --- -The `influxctl database update` command updates a database's retention period, -table (measurement), or column limits in InfluxDB. - -## Usage - - - -```sh -influxctl database update [flags] -``` - -## Arguments - -| Argument | Description | -| :---------------- | :----------------------------- | -| **DATABASE_NAME** | Name of the database to update | - -## Flags - -| Flag | | Description | -| :--- | :------------------- | :----------------------------------------------------------- | -| | `--retention-period` | [Database retention period ](/influxdb3/clustered/admin/databases/#retention-periods)(default is `0s` or infinite) | -| | `--max-tables` | [Maximum tables per database](/influxdb3/clustered/admin/databases/#table-limit) (default is 500, `0` uses default) | -| | `--max-columns` | [Maximum columns per table](/influxdb3/clustered/admin/databases/#column-limit) (default is 250, `0` uses default) | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/clustered/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} - -## Examples - -- [Update a database's retention period](#update-a-databases-retention-period) -- [Update a database's table limit](#update-a-databases-table-limit) -- [Update a database's column limit](#update-a-databases-column-limit) - -### Update a database's retention period - -```sh -influxctl database update --retention-period 1mo mydb -``` - -{{< flex >}} -{{% flex-content "half" %}} - -##### Valid durations units - -- `m`: minute -- `h`: hour -- `d`: day -- `w`: week -- `mo`: month -- `y`: year - -{{% /flex-content %}} -{{% flex-content "half" %}} - -##### Example retention period values - -- `0d`: infinite/none -- `3d`: 3 days -- `6w`: 6 weeks -- `1mo`: 1 month (30 days) -- `1y`: 1 year -- `30d30d`: 60 days -- `2.5d`: 60 hours - -{{% /flex-content %}} -{{< /flex >}} - -### Update a database's table limit - -```sh -influxctl database update --max-tables 300 mydb -``` - -### Update a database's column limit - -```sh -influxctl database update --max-columns 200 mydb -``` + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/table/_index.md b/content/influxdb3/clustered/reference/cli/influxctl/table/_index.md index 359ded2ad..8490436ed 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/table/_index.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/table/_index.md @@ -1,31 +1,15 @@ --- title: influxctl table description: > - The `influxctl table` command and its subcommands manage tables in an InfluxDB cluster. + The `influxctl table` command and its subcommands manage tables in an + {{% product-name omit=" Clustered" %}} cluster. menu: influxdb3_clustered: parent: influxctl weight: 201 cascade: metadata: [influxctl 2.5.0+] +source: /shared/influxctl/table/_index.md --- -The `influxctl table` command and its subcommands manage tables in an InfluxDB cluster. - -## Usage - -```sh -influxctl table [subcommand] [flags] -``` - -## Subcommands - -| Subcommand | Description | -| :------------------------------------------------------------------ | :------------- | -| [create](/influxdb3/clustered/reference/cli/influxctl/table/create/) | Create a table | - -## Flags - -| Flag | | Description | -| :--- | :------- | :------------------ | -| `-h` | `--help` | Output command help | + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/table/create.md b/content/influxdb3/clustered/reference/cli/influxctl/table/create.md index 31bc72495..e70e01ff8 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/table/create.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/table/create.md @@ -9,101 +9,7 @@ weight: 301 related: - /influxdb3/clustered/admin/custom-partitions/define-custom-partitions/ - /influxdb3/clustered/admin/custom-partitions/partition-templates/ +source: /shared/influxctl/table/create.md --- -The `influxctl table create` command creates a new table in the specified -database in an {{< product-name omit=" Clustered" >}} cluster. - -#### Custom partitioning - -You can override the default partition template (the partition template of the target database) -with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat` -flags when you create the table. -Provide a time format using [Rust strftime](/influxdb3/clustered/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values -into a specified number of "buckets." -Each of these can be used as part of the partition template. -Be sure to follow [partitioning best practices](/influxdb3/clustered/admin/custom-partitions/best-practices/). - -> [!Note] -> #### Always provide a time format when using custom partitioning -> -> If defining a custom partition template for your table with any of the -> `--template-*` flags, always include the `--template-timeformat` flag with a -> time format to use in your partition template. -> Otherwise, InfluxDB omits time from the partition template and won't compact partitions. - -## Usage - -```sh -influxctl table create [flags] -``` - -## Arguments - -| Argument | Description | -| :---------------- | :-------------------------- | -| **DATABASE_NAME** | Name of the target database | -| **TABLE_NAME** | Table name | - -## Flags - -| Flag | | Description | -| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | -| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) | -| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) | -| | `--template-timeformat` | Timestamp format for partition template | -| `-h` | `--help` | Output command help | - -{{% caption %}} -_Also see [`influxctl` global flags](/influxdb3/clustered/reference/cli/influxctl/#global-flags)._ -{{% /caption %}} - -## Examples - -- [Create a table](#create-a-table) -- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template) - -In the following examples, replace: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: - The name of the database to create the table in. -- {{% code-placeholder-key %}}`TABLE_NAME` {{% /code-placeholder-key %}}: - The name of table to create. - -### Create a table - -{{% code-placeholders "(DATABASE|TABLE)_NAME" %}} -```sh -influxctl table create DATABASE_NAME TABLE_NAME -``` -{{% /code-placeholders %}} - -### Create a table with a custom partition template - -The following example creates a new table and applies a partition -template that partitions by two tags (`room` and `sensor-type`) and by day using -the time format `%Y-%m-%d`: - -{{% code-placeholders "(DATABASE|TABLE)_NAME" %}} -```sh -influxctl table create \ - --template-tag room \ - --template-tag sensor-type \ - --template-tag-bucket customerID,1000 \ - --template-timeformat '%Y-%m-%d' \ - DATABASE_NAME \ - TABLE_NAME -``` -{{% /code-placeholders %}} - -_For more information about custom partitioning, see -[Manage data partitioning](/influxdb3/clustered/admin/custom-partitions/)._ - -{{% expand "View command updates" %}} - -#### v2.7.0 {date="2024-03-26"} - -- Introduce the `--template-tag-bucket` flag to group tag values into buckets - and partition by each tag bucket. - -{{% /expand %}} + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/table/delete.md b/content/influxdb3/clustered/reference/cli/influxctl/table/delete.md new file mode 100644 index 000000000..be2858639 --- /dev/null +++ b/content/influxdb3/clustered/reference/cli/influxctl/table/delete.md @@ -0,0 +1,15 @@ +--- +title: influxctl table delete +description: > + The `influxctl table delete` command deletes a specified table from a database. +menu: + influxdb3_clustered: + parent: influxctl table +weight: 301 +related: + - /influxdb3/clustered/admin/tables/delete/ +metadata: [influxctl 2.10.2+] +source: /shared/influxctl/table/delete.md +--- + + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/_index.md b/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/_index.md new file mode 100644 index 000000000..905c30a40 --- /dev/null +++ b/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/_index.md @@ -0,0 +1,15 @@ +--- +title: influxctl table iceberg +description: > + The `influxctl table iceberg` command and its subcommands enable or disable + Iceberg-compatible exports for a table in an InfluxDB Cloud Dedicated cluster. +menu: + influxdb3_clustered: + parent: influxctl table +weight: 301 +cascade: + metadata: [influxctl 2.10.2+] +source: /shared/influxctl/table/iceberg/_index.md +--- + + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/disable.md b/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/disable.md new file mode 100644 index 000000000..1d2f7664e --- /dev/null +++ b/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/disable.md @@ -0,0 +1,13 @@ +--- +title: influxctl table iceberg disable +description: > + The `influxctl table iceberg disable` command disables Iceberg-compatible exports + for a table in an InfluxDB Cloud Dedicated cluster. +menu: + influxdb3_clustered: + parent: influxctl table iceberg +weight: 401 +source: /shared/influxctl/table/iceberg/disable.md +--- + + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/enable.md b/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/enable.md new file mode 100644 index 000000000..e7ce6c021 --- /dev/null +++ b/content/influxdb3/clustered/reference/cli/influxctl/table/iceberg/enable.md @@ -0,0 +1,13 @@ +--- +title: influxctl table iceberg enable +description: > + The `influxctl table iceberg enable` command enables Iceberg-compatible exports + for a table in an InfluxDB Cloud Dedicated cluster. +menu: + influxdb3_clustered: + parent: influxctl table iceberg +weight: 401 +source: /shared/influxctl/table/iceberg/enable.md +--- + + diff --git a/content/influxdb3/clustered/reference/cli/influxctl/table/list.md b/content/influxdb3/clustered/reference/cli/influxctl/table/list.md new file mode 100644 index 000000000..59484772f --- /dev/null +++ b/content/influxdb3/clustered/reference/cli/influxctl/table/list.md @@ -0,0 +1,15 @@ +--- +title: influxctl table list +description: > + The `influxctl table list` command lists all tables in the specified database. +menu: + influxdb3_clustered: + parent: influxctl table +weight: 301 +related: + - /influxdb3/clustered/admin/tables/list/ +metadata: [influxctl 2.10.2+] +source: /shared/influxctl/table/list.md +--- + + diff --git a/content/influxdb3/clustered/reference/release-notes/clustered.md b/content/influxdb3/clustered/reference/release-notes/clustered.md index 1390bd9b0..b7d3c3973 100644 --- a/content/influxdb3/clustered/reference/release-notes/clustered.md +++ b/content/influxdb3/clustered/reference/release-notes/clustered.md @@ -250,8 +250,8 @@ spec: #### Release artifacts -- [app-instance-schema.json](/downloads/clustered-release-artifacts/20241022-1346953/app-instance-schema.json) -- [example-customer.yml](/downloads/clustered-release-artifacts/20241022-1346953/example-customer.yml) +- [app-instance-schema.json](/downloads/clustered-release-artifacts/20241024-1354148/app-instance-schema.json) +- [example-customer.yml](/downloads/clustered-release-artifacts/20241024-1354148/example-customer.yml) - [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt) ### Known Bugs @@ -804,13 +804,13 @@ version of `influxctl` prior to v2.8.0. ```yaml spec: package: - image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240325-920726 + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240326-922145 ``` #### Release artifacts -- [app-instance-schema.json](/downloads/clustered-release-artifacts/20240325-920726/app-instance-schema.json) -- [example-customer.yml](/downloads/clustered-release-artifacts/20240325-920726/example-customer.yml) +- [app-instance-schema.json](/downloads/clustered-release-artifacts/20240326-922145/app-instance-schema.json) +- [example-customer.yml](/downloads/clustered-release-artifacts/20240326-922145/example-customer.yml) - [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt) ### Highlights @@ -1424,12 +1424,6 @@ spec: image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230915-630658 ``` -#### Release artifacts - -- [app-instance-schema.json](/downloads/clustered-release-artifacts/20230915-630658/app-instance-schema.json) -- [example-customer.yml](/downloads/clustered-release-artifacts/20230915-630658/example-customer.yml) -- [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt) - ### Highlights #### Persistent volume fixes @@ -1456,12 +1450,6 @@ spec: image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230914-628600 ``` -#### Release artifacts - -- [app-instance-schema.json](/downloads/clustered-release-artifacts/20230914-628600/app-instance-schema.json) -- [example-customer.yml](/downloads/clustered-release-artifacts/20230914-628600/example-customer.yml) -- [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt) - ### Highlights #### Updated Azure AD documentation @@ -1497,12 +1485,6 @@ spec: image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230912-619813 ``` -#### Release artifacts - -- [app-instance-schema.json](/downloads/clustered-release-artifacts/20230912-619813/app-instance-schema.json) -- [example-customer.yml](/downloads/clustered-release-artifacts/20230912-619813/example-customer.yml) -- [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt) - ### Highlights #### Custom CA certificates {note="(Optional)"} @@ -1573,12 +1555,6 @@ spec: image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230911-604209 ``` -#### Release artifacts - -- [app-instance-schema.json](/downloads/clustered-release-artifacts/20230911-604209/app-instance-schema.json) -- [example-customer.yml](/downloads/clustered-release-artifacts/20230911-604209/example-customer.yml) -- [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt) - ### Highlights This release contains a breaking change to the monitoring subsystem that @@ -1628,12 +1604,6 @@ spec: image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230908-600131 ``` -#### Release artifacts - -- [app-instance-schema.json](/downloads/clustered-release-artifacts/20230908-600131/app-instance-schema.json) -- [example-customer.yml](/downloads/clustered-release-artifacts/20230908-600131/example-customer.yml) -- [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt) - ### Highlights #### Default storage class @@ -1661,12 +1631,6 @@ spec: image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230907-597343 ``` -#### Release artifacts - -- [app-instance-schema.json](/downloads/clustered-release-artifacts/20230907-597343/app-instance-schema.json) -- [example-customer.yml](/downloads/clustered-release-artifacts/20230907-597343/example-customer.yml) -- [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt) - ### Upgrade Notes This release requires a new configuration block: diff --git a/content/influxdb3/core/admin/databases/_index.md b/content/influxdb3/core/admin/databases/_index.md index ddbfb0a16..c46711854 100644 --- a/content/influxdb3/core/admin/databases/_index.md +++ b/content/influxdb3/core/admin/databases/_index.md @@ -12,6 +12,7 @@ influxdb3/core/tags: [databases] related: - /influxdb3/core/write-data/best-practices/schema-design/ - /influxdb3/core/reference/cli/influxdb3/ + - /influxdb3/explorer/manage-databases/ alt_links: cloud: /influxdb/cloud/admin/buckets/ cloud_dedicated: /influxdb3/cloud-dedicated/admin/databases/ diff --git a/content/influxdb3/core/admin/databases/create.md b/content/influxdb3/core/admin/databases/create.md index a05fe548f..99ccd12c5 100644 --- a/content/influxdb3/core/admin/databases/create.md +++ b/content/influxdb3/core/admin/databases/create.md @@ -17,6 +17,7 @@ list_code_example: | {{% /code-placeholders %}} related: - /influxdb3/core/reference/cli/influxdb3/create/database/ + - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/create.md --- diff --git a/content/influxdb3/core/admin/databases/delete.md b/content/influxdb3/core/admin/databases/delete.md index 96750c65e..69bb8aaea 100644 --- a/content/influxdb3/core/admin/databases/delete.md +++ b/content/influxdb3/core/admin/databases/delete.md @@ -16,6 +16,7 @@ list_code_example: | {{% /code-placeholders %}} related: - /influxdb3/core/reference/cli/influxdb3/delete/database/ + - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/delete.md --- diff --git a/content/influxdb3/core/admin/databases/list.md b/content/influxdb3/core/admin/databases/list.md index e416c267b..4be161e41 100644 --- a/content/influxdb3/core/admin/databases/list.md +++ b/content/influxdb3/core/admin/databases/list.md @@ -13,6 +13,7 @@ list_code_example: | ``` related: - /influxdb3/core/reference/cli/influxdb3/show/databases/ + - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/list.md --- diff --git a/content/influxdb3/core/get-started/process.md b/content/influxdb3/core/get-started/process.md new file mode 100644 index 000000000..5fb233f0e --- /dev/null +++ b/content/influxdb3/core/get-started/process.md @@ -0,0 +1,27 @@ +--- +title: Process data in {{% product-name %}} +seotitle: Process data | Get started with {{% product-name %}} +description: > + Learn how to use the {{% product-name %}} Processing Engine to process data and + perform various tasks like downsampling, alerting, forecasting, data + normalization, and more. +menu: + influxdb3_core: + name: Process data + identifier: gs-process-data + parent: Get started +weight: 104 +aliases: + - /influxdb3/core/get-started/process-data/ + - /influxdb3/core/get-started/processing-engine/ +related: + - /influxdb3/core/plugins/ + - /influxdb3/core/reference/cli/influxdb3/create/plugin/ + - /influxdb3/core/reference/cli/influxdb3/create/trigger/ +source: /shared/influxdb3-get-started/processing-engine.md +--- + + diff --git a/content/influxdb3/core/get-started/query.md b/content/influxdb3/core/get-started/query.md new file mode 100644 index 000000000..87c56ad48 --- /dev/null +++ b/content/influxdb3/core/get-started/query.md @@ -0,0 +1,24 @@ +--- +title: Query data in {{% product-name %}} +seotitle: Query data | Get started with {{% product-name %}} +description: > + Learn how to get started querying data in {{% product-name %}} using native + SQL or InfluxQL with the `influxdb3` CLI and other tools. +menu: + influxdb3_core: + name: Query data + identifier: gs-query-data + parent: Get started +weight: 103 +related: + - /influxdb3/core/query-data/ + - /influxdb3/core/reference/sql/ + - https://datafusion.apache.org/user-guide/sql/index.html, Apache DataFusion SQL reference + - /influxdb3/core/reference/influxql/ +source: /shared/influxdb3-get-started/query.md +--- + + diff --git a/content/influxdb3/core/get-started/setup.md b/content/influxdb3/core/get-started/setup.md new file mode 100644 index 000000000..6b4b1a395 --- /dev/null +++ b/content/influxdb3/core/get-started/setup.md @@ -0,0 +1,21 @@ +--- +title: Set up {{% product-name %}} +seotitle: Set up InfluxDB | Get started with {{% product-name %}} +description: > + Install, configure, and set up authorization for {{% product-name %}}. +menu: + influxdb3_core: + name: Set up Core + parent: Get started +weight: 3 +related: + - /influxdb3/core/install/ + - /influxdb3/core/admin/tokens/ + - /influxdb3/core/reference/config-options/ +source: /shared/influxdb3-get-started/setup.md +--- + + diff --git a/content/influxdb3/core/get-started/write.md b/content/influxdb3/core/get-started/write.md new file mode 100644 index 000000000..5133b17fe --- /dev/null +++ b/content/influxdb3/core/get-started/write.md @@ -0,0 +1,22 @@ +--- +title: Write data to {{% product-name %}} +seotitle: Write data | Get started with {{% product-name %}} +description: > + Learn how to write time series data to {{% product-name %}} using the + `influxdb3` CLI and _line protocol_, an efficient, human-readable write syntax. +menu: + influxdb3_core: + name: Write data + identifier: gs-write-data + parent: Get started +weight: 102 +related: + - /influxdb3/core/write-data/ + - /influxdb3/core/reference/line-protocol/ +source: /shared/influxdb3-get-started/write.md +--- + + diff --git a/content/influxdb3/core/reference/cli/influxdb3/_index.md b/content/influxdb3/core/reference/cli/influxdb3/_index.md index 221e4e654..831597dc6 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/_index.md +++ b/content/influxdb3/core/reference/cli/influxdb3/_index.md @@ -32,6 +32,7 @@ influxdb3 [GLOBAL-OPTIONS] [COMMAND] | [serve](/influxdb3/core/reference/cli/influxdb3/serve/) | Run the {{% product-name %}} server | | [show](/influxdb3/core/reference/cli/influxdb3/show/) | List resources | | [test](/influxdb3/core/reference/cli/influxdb3/test/) | Test plugins | +| [update](/influxdb3/core/reference/cli/influxdb3/update/) | Update resources | | [write](/influxdb3/core/reference/cli/influxdb3/write/) | Write to {{% product-name %}} | ## Global options diff --git a/content/influxdb3/core/reference/cli/influxdb3/create/file_index.md b/content/influxdb3/core/reference/cli/influxdb3/create/file_index.md deleted file mode 100644 index a24aaebbc..000000000 --- a/content/influxdb3/core/reference/cli/influxdb3/create/file_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: influxdb3 create file_index -description: > - The `influxdb3 create file_index` command creates a new file index for a - database or table. -menu: - influxdb3_core: - parent: influxdb3 create - name: influxdb3 create file_index -weight: 400 -source: /shared/influxdb3-cli/create/file_index.md ---- - - diff --git a/content/influxdb3/core/reference/cli/influxdb3/delete/file_index.md b/content/influxdb3/core/reference/cli/influxdb3/delete/file_index.md deleted file mode 100644 index c60fb90f1..000000000 --- a/content/influxdb3/core/reference/cli/influxdb3/delete/file_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: influxdb3 delete file_index -description: > - The `influxdb3 delete file_index` command deletes a file index for a - database or table. -menu: - influxdb3_core: - parent: influxdb3 delete - name: influxdb3 delete file_index -weight: 400 -source: /shared/influxdb3-cli/delete/file_index.md ---- - - diff --git a/content/influxdb3/core/reference/cli/influxdb3/serve.md b/content/influxdb3/core/reference/cli/influxdb3/serve.md index a769cb652..c6001d47b 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/core/reference/cli/influxdb3/serve.md @@ -24,8 +24,8 @@ influxdb3 serve [OPTIONS] --node-id ## Required parameters - **node-id**: A unique identifier for your server instance. Must be unique for any hosts sharing the same object store. -- **object-store**: Determines where time series data is stored. _Default is `memory`_. -- **data-dir**: Path for local file storage (required when using `--object-store file`). +- **object-store**: Determines where time series data is stored. +- Other object store parameters depending on the selected `object-store` type. > [!NOTE] > `--node-id` supports alphanumeric strings with optional hyphens. diff --git a/content/influxdb3/core/reference/cli/influxdb3/update/_index.md b/content/influxdb3/core/reference/cli/influxdb3/update/_index.md new file mode 100644 index 000000000..0cc4e0846 --- /dev/null +++ b/content/influxdb3/core/reference/cli/influxdb3/update/_index.md @@ -0,0 +1,15 @@ +--- +title: influxdb3 update +description: > + The `influxdb3 update` command updates resources such as databases. +menu: + influxdb3_core: + parent: influxdb3 + name: influxdb3 update +weight: 300 +source: /shared/influxdb3-cli/update/_index.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/core/reference/cli/influxdb3/update/database.md b/content/influxdb3/core/reference/cli/influxdb3/update/database.md new file mode 100644 index 000000000..754f70d38 --- /dev/null +++ b/content/influxdb3/core/reference/cli/influxdb3/update/database.md @@ -0,0 +1,15 @@ +--- +title: influxdb3 update database +description: > + The `influxdb3 update database` command updates an existing database. +menu: + influxdb3_core: + parent: influxdb3 update + name: influxdb3 update database +weight: 400 +source: /shared/influxdb3-cli/update/database/_index.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/core/reference/config-options.md b/content/influxdb3/core/reference/config-options.md index 7dfee8828..7e3f92bfc 100644 --- a/content/influxdb3/core/reference/config-options.md +++ b/content/influxdb3/core/reference/config-options.md @@ -144,7 +144,7 @@ influxdb3 serve Specifies which object storage to use to store Parquet files. This option supports the following values: -- `memory` _(default)_ +- `memory` - `memory-throttled` - `file` - `s3` @@ -171,7 +171,7 @@ Required when using the `file` [object store](#object-store). #### node-id Specifies the node identifier used as a prefix in all object store file paths. -This should be unique for any hosts sharing the same object store +Use a unique node identifier for each host sharing the same object store configuration--for example, the same bucket. | influxdb3 serve option | Environment variable | @@ -186,7 +186,7 @@ Limits the number of Parquet files a query can access. **Default:** `432` -With the default `432` setting and the default [`gen1-duration`](#`gen1-duration`) +With the default `432` setting and the default [`gen1-duration`](#gen1-duration) setting of 10 minutes, queries can access up to a 72 hours of data, but potentially less depending on whether all data for a given 10 minute block of time was ingested during the same period. diff --git a/content/influxdb3/core/write-data/api-client-libraries.md b/content/influxdb3/core/write-data/client-libraries.md similarity index 52% rename from content/influxdb3/core/write-data/api-client-libraries.md rename to content/influxdb3/core/write-data/client-libraries.md index fc44f2e06..2dcd72f32 100644 --- a/content/influxdb3/core/write-data/api-client-libraries.md +++ b/content/influxdb3/core/write-data/client-libraries.md @@ -1,21 +1,21 @@ --- -title: Use the HTTP API and client libraries to write data +title: Use InfluxDB client libraries to write data description: > - Use the `/api/v3/write_lp` HTTP API endpoint and InfluxDB API clients to write points as line protocol data to {{% product-name %}}. + Use InfluxDB API clients to write points as line protocol data to {{% product-name %}}. menu: influxdb3_core: - name: Use the API and client libraries + name: Use client libraries parent: Write data - identifier: write-api-client-libs + identifier: write-client-libs weight: 100 aliases: - - /influxdb3/core/write-data/client-libraries/ + - /influxdb3/core/write-data/api-client-libraries/ related: - /influxdb3/core/reference/syntax/line-protocol/ - /influxdb3/core/get-started/write/ - /influxdb3/core/reference/client-libraries/v3/ - /influxdb3/core/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint -source: /shared/influxdb3-write-guides/api-client-libraries.md +source: /shared/influxdb3-write-guides/client-libraries.md --- diff --git a/content/influxdb3/core/write-data/compatibility-apis.md b/content/influxdb3/core/write-data/http-api/compatibility-apis.md similarity index 75% rename from content/influxdb3/core/write-data/compatibility-apis.md rename to content/influxdb3/core/write-data/http-api/compatibility-apis.md index bf3631118..901d0f900 100644 --- a/content/influxdb3/core/write-data/compatibility-apis.md +++ b/content/influxdb3/core/write-data/http-api/compatibility-apis.md @@ -6,21 +6,21 @@ description: > menu: influxdb3_core: name: Use v1 and v2 compatibility APIs - parent: Write data - identifier: write-compatibility-client-libs -weight: 101 + parent: write-http-api +weight: 202 aliases: - /influxdb3/core/write-data/client-libraries/ + - /influxdb3/core/write-data/compatibility-apis/ related: - /influxdb3/core/reference/syntax/line-protocol/ - /influxdb3/core/get-started/write/ - /influxdb3/core/reference/client-libraries/v2/ - /influxdb3/core/api/v3/#operation/PostV2Write, /api/v2/write (v2-compatible) endpoint - /influxdb3/core/api/v3/#operation/PostV1Write, /write (v1-compatible) endpoint -source: /shared/influxdb3-write-guides/compatibility-apis.md +source: /shared/influxdb3-write-guides/http-api/compatibility-apis.md --- \ No newline at end of file diff --git a/content/influxdb3/core/write-data/http-api/v3-write-lp.md b/content/influxdb3/core/write-data/http-api/v3-write-lp.md new file mode 100644 index 000000000..fd7fa11c1 --- /dev/null +++ b/content/influxdb3/core/write-data/http-api/v3-write-lp.md @@ -0,0 +1,20 @@ +--- +title: Use the v3 write API to write data +description: > + Use the `/api/v3/write_lp` HTTP API endpoint to write data to {{% product-name %}}. +menu: + influxdb3_core: + name: Use the v3 write API + parent: write-http-api +weight: 201 +related: + - /influxdb3/core/reference/syntax/line-protocol/ + - /influxdb3/core/get-started/write/ + - /influxdb3/core/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint +source: /shared/influxdb3-write-guides/http-api/v3-write-lp.md +--- + + diff --git a/content/influxdb3/enterprise/admin/databases/_index.md b/content/influxdb3/enterprise/admin/databases/_index.md index f5165023b..c93183766 100644 --- a/content/influxdb3/enterprise/admin/databases/_index.md +++ b/content/influxdb3/enterprise/admin/databases/_index.md @@ -12,6 +12,7 @@ influxdb3/enterprise/tags: [databases] related: - /influxdb3/enterprise/write-data/best-practices/schema-design/ - /influxdb3/enterprise/reference/cli/influxdb3/ + - /influxdb3/explorer/manage-databases/ alt_links: cloud: /influxdb/cloud/admin/buckets/ cloud_dedicated: /influxdb3/cloud-dedicated/admin/databases/ diff --git a/content/influxdb3/enterprise/admin/databases/create.md b/content/influxdb3/enterprise/admin/databases/create.md index bccfacff2..14f56c821 100644 --- a/content/influxdb3/enterprise/admin/databases/create.md +++ b/content/influxdb3/enterprise/admin/databases/create.md @@ -17,6 +17,7 @@ list_code_example: | {{% /code-placeholders %}} related: - /influxdb3/enterprise/reference/cli/influxdb3/create/database/ + - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/create.md --- diff --git a/content/influxdb3/enterprise/admin/databases/delete.md b/content/influxdb3/enterprise/admin/databases/delete.md index 395ab611a..9ae9b963e 100644 --- a/content/influxdb3/enterprise/admin/databases/delete.md +++ b/content/influxdb3/enterprise/admin/databases/delete.md @@ -16,6 +16,7 @@ list_code_example: | {{% /code-placeholders %}} related: - /influxdb3/enterprise/reference/cli/influxdb3/delete/database/ + - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/delete.md --- diff --git a/content/influxdb3/enterprise/admin/databases/list.md b/content/influxdb3/enterprise/admin/databases/list.md index c579a9816..e9d5cd374 100644 --- a/content/influxdb3/enterprise/admin/databases/list.md +++ b/content/influxdb3/enterprise/admin/databases/list.md @@ -13,6 +13,7 @@ list_code_example: | ``` related: - /influxdb3/enterprise/reference/cli/influxdb3/show/databases/ + - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/list.md --- diff --git a/content/influxdb3/enterprise/admin/file-index/_index.md b/content/influxdb3/enterprise/admin/file-index/_index.md new file mode 100644 index 000000000..65c94c642 --- /dev/null +++ b/content/influxdb3/enterprise/admin/file-index/_index.md @@ -0,0 +1,51 @@ +--- +title: Manage file indexes +seotitle: Manage file indexes in {{< product-name >}} +description: > + Customize the indexing strategy of a database or table in {{% product-name %}} + to optimize the performance of single-series queries. +menu: + influxdb3_enterprise: + parent: Administer InfluxDB +weight: 106 +influxdb3/enterprise/tags: [indexing] +--- + +{{% product-name %}} lets you customize how your data is indexed to help +optimize query performance for your specific workload, especially workloads that +include single-series queries. Indexes help the InfluxDB query engine quickly +identify the physical location of files that contain the queried data. + +By default, InfluxDB indexes on the primary key—`time` and tag columns. However, +if your schema includes tags that you don't specifically use when querying, you +can define a custom indexing strategy to only index on `time` and columns +important to your query workload. + +For example, if your schema includes the following columns: + +- country +- state_province +- county +- city +- postal_code + +And in your query workload, you only query based on country, state or province, +and city, you can create a custom file indexing strategy that only indexes on +`time` and these specific columns. This makes your index more efficient and +improves the performance of your single-series queries. + +> [!Note] +> File indexes can use any string column, including both tags and fields. + +- [Indexing life cycle](#indexing-life-cycle) +- [Create a custom file index](#create-a-custom-file-index) +- [Delete a custom file index](#delete-a-custom-file-index) + +## Indexing life cycle + +{{% product-name %}} builds indexes as it compacts data. Compaction is the +process that organizes and optimizes Parquet files in storage and occurs in +multiple phases or generations. Generation 1 (gen1) data is un-compacted and +is not indexed. Generation 2 (gen2) data and beyond is all indexed. + +{{< children hlevel="h2" >}} diff --git a/content/influxdb3/enterprise/admin/file-index/create.md b/content/influxdb3/enterprise/admin/file-index/create.md new file mode 100644 index 000000000..ea6891f2b --- /dev/null +++ b/content/influxdb3/enterprise/admin/file-index/create.md @@ -0,0 +1,62 @@ +--- +title: Create a custom file index +seotitle: Create a custom file index in {{< product-name >}} +description: > + Use the [`influxdb3 create file_index` command](/influxdb3/enterprise/reference/cli/influxdb3/create/file_index/) + to create a custom file indexing strategy for a database or a table. +menu: + influxdb3_enterprise: + parent: Manage file indexes +weight: 106 +influxdb3/enterprise/tags: [indexing] +related: + - /influxdb3/enterprise/reference/cli/influxdb3/create/file_index/ +list_code_example: | + + ```bash + influxdb3 create file_index \ + --database example-db \ + --token 00xoXX0xXXx0000XxxxXx0Xx0xx0 \ + --table wind_data \ + country,city + ``` +--- + +Use the [`influxdb3 create file_index` command](/influxdb3/enterprise/reference/cli/influxdb3/create/file_index/) +to create a custom file indexing strategy for a database or table. + +Provide the following: + +- **Token** (`--token`): _({{< req >}})_ Your {{% token-link "admin" %}}. + You can also use the `INFLUXDB3_AUTH_TOKEN` environment variable to specify + the token. +- **Database** (`-d`, `--database`): _({{< req >}})_ The name of the database to + apply the index to. You can also use the `INFLUXDB3_DATABASE_NAME` + environment variable to specify the database. +- **Table** (`-t`, `--table`): The name of the table to apply the index to. + If no table is specified, the indexing strategy applies to all tables in the + specified database. +- **Columns**: _({{< req >}})_ A comma-separated list of string columns to + index on. These are typically tag columns but can also be string fields. + +{{% code-placeholders "AUTH_TOKEN|DATABASE|TABLE|COLUMNS" %}} + +```bash +influxdb3 create file_index \ + --token AUTH_TOKEN \ + --database DATABASE_NAME \ + --table TABLE_NAME \ + COLUMNS +``` +{{% /code-placeholders %}} + +Replace the following placeholders with your values: + +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your {{% token-link "admin" %}} +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of the database to create the file index in +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: + the name of the table to create the file index in +- {{% code-placeholder-key %}}`COLUMNS`{{% /code-placeholder-key %}}: + a comma-separated list of columns to index on--for example: `host,application` diff --git a/content/influxdb3/enterprise/admin/file-index/delete.md b/content/influxdb3/enterprise/admin/file-index/delete.md new file mode 100644 index 000000000..98bfe4bfa --- /dev/null +++ b/content/influxdb3/enterprise/admin/file-index/delete.md @@ -0,0 +1,58 @@ +--- +title: Delete a custom file index +seotitle: Delete a custom file index in {{< product-name >}} +description: > + Use the [`influxdb3 delete file_index` command](/influxdb3/enterprise/reference/cli/influxdb3/delete/file_index/) + to delete a custom file indexing strategy from a database or a table and revert + to the default indexing strategy. +menu: + influxdb3_enterprise: + parent: Manage file indexes +weight: 106 +influxdb3/enterprise/tags: [indexing] +related: + - /influxdb3/enterprise/reference/cli/influxdb3/delete/file_index/ +list_code_example: | + + ```bash + influxdb3 delete file_index \ + --database example-db \ + --token 00xoXX0xXXx0000XxxxXx0Xx0xx0 \ + --table wind_data + ``` +--- + +Use the [`influxdb3 delete file_index` command](/influxdb3/enterprise/reference/cli/influxdb3/delete/file_index/) +to delete a custom file indexing strategy from a database or a table and revert +to the default indexing strategy. + +Provide the following: + +- **Token** (`--token`): _({{< req >}})_ Your {{% token-link "admin" %}}. + You can also use the `INFLUXDB3_AUTH_TOKEN` environment variable to specify + the token. +- **Database** (`-d`, `--database`): _({{< req >}})_ The name of the database to + apply remove the custom index from. You can also use the `INFLUXDB3_DATABASE_NAME` + environment variable to specify the database. +- **Table** (`-t`, `--table`): The name of the table to remove the custom index from. + If no table is specified, the custom indexing strategy is removed from all + tables in the specified database. + +{{% code-placeholders "AUTH_TOKEN|DATABASE|TABLE|COLUMNS" %}} + +```bash +influxdb3 delete file_index \ + --host http://localhost:8585 \ + --database DATABASE_NAME \ + --table TABLE_NAME \ +``` +{{% /code-placeholders %}} + +Replace the following placeholders with your values: + +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your {{% token-link "admin" %}} +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of the database to remove the custom file index from +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: + the name of the table to remove the custom file index from diff --git a/content/influxdb3/enterprise/admin/license.md b/content/influxdb3/enterprise/admin/license.md index 11d5b3471..62727201e 100644 --- a/content/influxdb3/enterprise/admin/license.md +++ b/content/influxdb3/enterprise/admin/license.md @@ -101,7 +101,7 @@ The license file is a JWT file that contains the license information. > use one of the methods to [skip the email prompt](#skip-the-email-prompt). > This ensures that the container can generate the license file after you > verify your email address. -> See the [Docker Compose example](?t=Docker+compose#activate-a-trial-or-home-license-with-docker). +> See the [Docker Compose example](?t=Docker+compose#start-with-license-email-and-compose). #### Skip the email prompt @@ -186,7 +186,7 @@ existing license if it's still valid. {{% code-tabs %}} [influxdb3 options](#) [Environment variables](#) -[Docker compose](#example-activate-trial-or-home-with-compose) +[Docker compose](#start-with-license-email-and-compose) {{% /code-tabs %}} {{% code-tab-content %}} @@ -215,6 +215,7 @@ influxdb3 serve \ {{% /code-tab-content %}} {{% code-tab-content %}} +{{% code-placeholders "${EMAIL_ADDRESS}" %}} ```yaml # compose.yaml name: data-crunching-stack @@ -235,7 +236,8 @@ services: - --object-store=file - --data-dir=/var/lib/influxdb3 - --plugin-dir=/var/lib/influxdb3/plugins - - --license-email=INFLUXDB3_LICENSE_EMAIL + environment: + - INFLUXDB3_LICENSE_EMAIL=${EMAIL_ADDRESS} volumes: - type: bind source: ~/.influxdb3/data @@ -244,6 +246,9 @@ services: source: ~/.influxdb3/plugins target: /var/lib/influxdb3/plugins ``` +{{% /code-placeholders %}} +Replace {{% code-placeholder-key %}}`${EMAIL_ADDRESS}`{{% /code-placeholder-key %}} with your email address +or a variable from your Compose `.env` file. {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} diff --git a/content/influxdb3/enterprise/admin/tokens/_index.md b/content/influxdb3/enterprise/admin/tokens/_index.md index 6c9a079ea..6eb899717 100644 --- a/content/influxdb3/enterprise/admin/tokens/_index.md +++ b/content/influxdb3/enterprise/admin/tokens/_index.md @@ -6,6 +6,8 @@ menu: influxdb3_enterprise: parent: Administer InfluxDB weight: 202 +related: + - /influxdb3/explorer/manage-tokens/ source: /shared/influxdb3-admin/tokens/_index.md --- diff --git a/content/influxdb3/enterprise/admin/tokens/admin/_index.md b/content/influxdb3/enterprise/admin/tokens/admin/_index.md index d870c5e91..b0745f541 100644 --- a/content/influxdb3/enterprise/admin/tokens/admin/_index.md +++ b/content/influxdb3/enterprise/admin/tokens/admin/_index.md @@ -10,6 +10,9 @@ menu: parent: Manage tokens name: Admin tokens weight: 101 +cascade: + related: + - /influxdb3/explorer/manage-tokens/ influxdb3/enterprise/tags: [tokens] source: /shared/influxdb3-admin/tokens/admin/_index.md --- diff --git a/content/influxdb3/enterprise/get-started/multi-server.md b/content/influxdb3/enterprise/get-started/multi-server.md new file mode 100644 index 000000000..56da9360d --- /dev/null +++ b/content/influxdb3/enterprise/get-started/multi-server.md @@ -0,0 +1,528 @@ +--- +title: Create a multi-node cluster +seotitle: Create a multi-node InfluxDB 3 Enterprise cluster +description: > + Create a multi-node InfluxDB 3 Enterprise cluster for high availability, + performance, read replicas, and more to meet the specific needs of your use case. +menu: + influxdb3_enterprise: + name: Create a multi-node cluster + parent: Get started + identifier: gs-multi-node-cluster +weight: 102 +influxdb3/enterprise/tags: [cluster, multi-node, multi-server] +--- + +Create a multi-node {{% product-name %}} cluster for high availability, performance, and workload isolation. +Configure nodes with specific _modes_ (ingest, query, process, compact) to optimize for your use case. + +## Prerequisites + +- Shared object store +- Network connectivity between nodes + +## Basic multi-node setup + + +```bash +## NODE 1 compacts stored data + +# Example variables +# node-id: 'host01' +# cluster-id: 'cluster01' +# bucket: 'influxdb-3-enterprise-storage' + +influxdb3 serve \ + --node-id host01 \ + --cluster-id cluster01 \ + --mode ingest,query,compact \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind {{< influxdb/host >}} \ + --aws-access-key-id \ + --aws-secret-access-key +``` + + +```bash +## NODE 2 handles writes and queries + +# Example variables +# node-id: 'host02' +# cluster-id: 'cluster01' +# bucket: 'influxdb-3-enterprise-storage' + +influxdb3 serve \ + --node-id host02 \ + --cluster-id cluster01 \ + --mode ingest,query \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind localhost:8282 \ + --aws-access-key-id AWS_ACCESS_KEY_ID \ + --aws-secret-access-key AWS_SECRET_ACCESS_KEY +``` + +Learn how to set up a multi-node cluster for different use cases, including high availability, read replicas, processing data, and workload isolation. + +- [Create an object store](#create-an-object-store) +- [Connect to your object store](#connect-to-your-object-store) +- [Server modes](#server-modes) +- [Cluster configuration examples](#cluster-configuration-examples) +- [Writing and querying in multi-node clusters](#writing-and-querying-in-multi-node-clusters) + +## Create an object store + +With the {{% product-name %}} diskless architecture, all data is stored in a common object store. +In a multi-node cluster, you connect all nodes to the same object store. + +Enterprise supports the following object stores: + +- AWS S3 (or S3-compatible) +- Azure Blob Storage +- Google Cloud Storage + +> [!Note] +> Refer to your object storage provider's documentation for +> setting up an object store. + +## Connect to your object store + +When starting your {{% product-name %}} node, include provider-specific options for connecting to your object store--for example: + +{{< tabs-wrapper >}} +{{% tabs %}} +[S3 or S3-compatible](#) +[Azure Blob Storage](#) +[Google Cloud Storage](#) +{{% /tabs %}} +{{% tab-content %}} + + +To use an AWS S3 or S3-compatible object store, provide the following options +with your `influxdb3 serve` command: + +- `--object-store`: `s3` +- `--bucket`: Your AWS S3 bucket name +- `--aws-access-key-id`: Your AWS access key ID + _(can also be defined using the `AWS_ACCESS_KEY_ID` environment variable)_ +- `--aws-secret-access-key`: Your AWS secret access key + _(can also be defined using the `AWS_SECRET_ACCESS_KEY` environment variable)_ + +{{% code-placeholders "AWS_(BUCKET_NAME|ACCESS_KEY_ID|SECRET_ACCESS_KEY)" %}} + +```bash +influxdb3 serve \ + # ... + --object-store s3 \ + --bucket AWS_BUCKET_NAME \ + --aws-access-key-id AWS_ACCESS_KEY_ID \ + --aws-secret-access-key AWS_SECRET_ACCESS_KEY +``` +{{% /code-placeholders %}} + +_For information about other S3-specific settings, see +[Configuration options - AWS](/influxdb3/enterprise/reference/config-options/#aws)._ + + +{{% /tab-content %}} +{{% tab-content %}} + + +To use Azure Blob Storage as your object store, provide the following options +with your `influxdb3 serve` command: + +- `--object-store`: `azure` +- `--bucket`: Your Azure Blob Storage container name +- `--azure-storage-account`: Your Azure Blob Storage storage account name + _(can also be defined using the `AZURE_STORAGE_ACCOUNT` environment variable)_ +- `--aws-secret-access-key`: Your Azure Blob Storage access key + _(can also be defined using the `AZURE_STORAGE_ACCESS_KEY` environment variable)_ + +{{% code-placeholders "AZURE_(CONTAINER_NAME|STORAGE_ACCOUNT|STORAGE_ACCESS_KEY)" %}} + +```bash +influxdb3 serve \ + # ... + --object-store azure \ + --bucket AZURE_CONTAINER_NAME \ + --azure-storage-account AZURE_STORAGE_ACCOUNT \ + --azure-storage-access-key AZURE_STORAGE_ACCESS_KEY +``` +{{% /code-placeholders %}} + + +{{% /tab-content %}} +{{% tab-content %}} + + +To use Google Cloud Storage as your object store, provide the following options +with your `influxdb3 serve` command: + +- `--object-store`: `google` +- `--bucket`: Your Google Cloud Storage bucket name +- `--google-service-account`: The path to to your Google credentials JSON file + _(can also be defined using the `GOOGLE_SERVICE_ACCOUNT` environment variable)_ + +{{% code-placeholders "GOOGLE_(BUCKET_NAME|SERVICE_ACCOUNT)" %}} + +```bash +influxdb3 serve \ + # ... + --object-store google \ + --bucket GOOGLE_BUCKET_NAME \ + --google-service-account GOOGLE_SERVICE_ACCOUNT +``` +{{% /code-placeholders %}} + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +## Server modes + +{{% product-name %}} _modes_ determine what subprocesses the Enterprise node runs. +These subprocesses fulfill required tasks including data ingestion, query +processing, compaction, and running the processing engine. + +The `influxdb3 serve --mode` option defines what subprocesses a node runs. +Each node can run in one _or more_ of the following modes: + +- **all** _(default)_: Runs all necessary subprocesses. +- **ingest**: Runs the data ingestion subprocess to handle writes. +- **query**: Runs the query processing subprocess to handle queries. +- **process**: Runs the processing engine subprocess to trigger and execute plugins. +- **compact**: Runs the compactor subprocess to optimize data in object storage. + + > [!Important] + > Only _one_ node in your cluster can run in `compact` mode. + +### Server mode examples + +#### Configure a node to only handle write requests + +```bash +influxdb3 serve \ + # ... + --mode ingest +``` + +#### Configure a node to only run the Compactor + +```bash +influxdb3 serve \ + # ... + --mode compact +``` + +#### Configure a node to handle queries and run the processing engine + +```bash +influxdb3 serve \ + # ... + --mode query,process +``` + +## Cluster configuration examples + +- [High availability cluster](#high-availability-cluster) +- [High availability with a dedicated Compactor](#high-availability-with-a-dedicated-compactor) +- [High availability with read replicas and a dedicated Compactor](#high-availability-with-read-replicas-and-a-dedicated-compactor) + +### High availability cluster + +A minimum of two nodes are required for basic high availability (HA), with both +nodes reading and writing data. + +{{< img-hd src="/img/influxdb/influxdb-3-enterprise-high-availability.png" alt="Basic high availability setup" />}} + +In a basic HA setup: + +- Two nodes both write data to the same object store and both handle queries +- Node 1 and Node 2 are _read replicas_ that read from each other’s object store directories +- One of the nodes is designated as the Compactor node + +> [!Note] +> Only one node can be designated as the Compactor. +> Compacted data is meant for a single writer, and many readers. + +The following examples show how to configure and start two nodes for a basic HA +setup. + +- _Node 1_ is for compaction +- _Node 2_ is for ingest and query + + +```bash +## NODE 1 + +# Example variables +# node-id: 'host01' +# cluster-id: 'cluster01' +# bucket: 'influxdb-3-enterprise-storage' + +influxdb3 serve \ + --node-id host01 \ + --cluster-id cluster01 \ + --mode ingest,query,compact \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind {{< influxdb/host >}} \ + --aws-access-key-id \ + --aws-secret-access-key +``` + + +```bash +## NODE 2 + +# Example variables +# node-id: 'host02' +# cluster-id: 'cluster01' +# bucket: 'influxdb-3-enterprise-storage' + +influxdb3 serve \ + --node-id host02 \ + --cluster-id cluster01 \ + --mode ingest,query \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind localhost:8282 \ + --aws-access-key-id AWS_ACCESS_KEY_ID \ + --aws-secret-access-key AWS_SECRET_ACCESS_KEY +``` + +After the nodes have started, querying either node returns data for both nodes, +and _NODE 1_ runs compaction. +To add nodes to this setup, start more read replicas with the same cluster ID. + +### High availability with a dedicated Compactor + +Data compaction in {{% product-name %}} is one of the more computationally +demanding operations. +To ensure stable performance in ingest and query nodes, set up a +compactor-only node to isolate the compaction workload. + +{{< img-hd src="/img/influxdb/influxdb-3-enterprise-dedicated-compactor.png" alt="Dedicated Compactor setup" />}} + +The following examples sets up high availability with a dedicated Compactor node: + +1. Start two read-write nodes as read replicas, similar to the previous example. + + + ```bash + ## NODE 1 — Writer/Reader Node #1 + + # Example variables + # node-id: 'host01' + # cluster-id: 'cluster01' + # bucket: 'influxdb-3-enterprise-storage' + + influxdb3 serve \ + --node-id host01 \ + --cluster-id cluster01 \ + --mode ingest,query \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind {{< influxdb/host >}} \ + --aws-access-key-id \ + --aws-secret-access-key + ``` + + + ```bash + ## NODE 2 — Writer/Reader Node #2 + + # Example variables + # node-id: 'host02' + # cluster-id: 'cluster01' + # bucket: 'influxdb-3-enterprise-storage' + + influxdb3 serve \ + --node-id host02 \ + --cluster-id cluster01 \ + --mode ingest,query \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind localhost:8282 \ + --aws-access-key-id \ + --aws-secret-access-key + ``` + +2. Start the dedicated compactor node with the `--mode=compact` option to ensure the node **only** runs compaction. + + ```bash + ## NODE 3 — Compactor Node + + # Example variables + # node-id: 'host03' + # cluster-id: 'cluster01' + # bucket: 'influxdb-3-enterprise-storage' + + influxdb3 serve \ + --node-id host03 \ + --cluster-id cluster01 \ + --mode compact \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --aws-access-key-id \ + --aws-secret-access-key + ``` + +### High availability with read replicas and a dedicated Compactor + +For a robust and effective setup for managing time-series data, you can run +ingest nodes alongside query nodes and a dedicated Compactor node. + +{{< img-hd src="/img/influxdb/influxdb-3-enterprise-workload-isolation.png" alt="Workload Isolation Setup" />}} + +1. Start ingest nodes with the **`ingest`** mode. + + > [!Note] + > Send all write requests to only your ingest nodes. + + ```bash + ## NODE 1 — Writer Node #1 + + # Example variables + # node-id: 'host01' + # cluster-id: 'cluster01' + # bucket: 'influxdb-3-enterprise-storage' + + influxdb3 serve \ + --node-id host01 \ + --cluster-id cluster01 \ + --mode ingest \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind {{< influxdb/host >}} \ + --aws-access-key-id \ + --aws-secret-access-key + ``` + + + + ```bash + ## NODE 2 — Writer Node #2 + + # Example variables + # node-id: 'host02' + # cluster-id: 'cluster01' + # bucket: 'influxdb-3-enterprise-storage' + + influxdb3 serve \ + --node-id host02 \ + --cluster-id cluster01 \ + --mode ingest \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind localhost:8282 \ + --aws-access-key-id \ + --aws-secret-access-key + ``` + +2. Start the dedicated Compactor node with the `compact` mode. + + ```bash + ## NODE 3 — Compactor Node + + # Example variables + # node-id: 'host03' + # cluster-id: 'cluster01' + # bucket: 'influxdb-3-enterprise-storage' + + influxdb3 serve \ + --node-id host03 \ + --cluster-id cluster01 \ + --mode compact \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --aws-access-key-id \ + + ``` + +3. Finally, start the query nodes using the `query` mode. + + > [!Note] + > Send all query requests to only your query nodes. + + ```bash + ## NODE 4 — Read Node #1 + + # Example variables + # node-id: 'host04' + # cluster-id: 'cluster01' + # bucket: 'influxdb-3-enterprise-storage' + + influxdb3 serve \ + --node-id host04 \ + --cluster-id cluster01 \ + --mode query \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind localhost:8383 \ + --aws-access-key-id \ + --aws-secret-access-key + ``` + + ```bash + ## NODE 5 — Read Node #2 + + # Example variables + # node-id: 'host05' + # cluster-id: 'cluster01' + # bucket: 'influxdb-3-enterprise-storage' + + influxdb3 serve \ + --node-id host05 \ + --cluster-id cluster01 \ + --mode query \ + --object-store s3 \ + --bucket influxdb-3-enterprise-storage \ + --http-bind localhost:8484 \ + --aws-access-key-id \ + + ``` + +## Writing and querying in multi-node clusters + +You can use the default port `8181` for any write or query request without +changing any of the commands. + +> [!Note] +> #### Specify hosts for write and query requests +> +> To benefit from this multi-node, isolated architecture: +> +> - Send write requests to a node that you have designated as an ingester. +> - Send query requests to a node that you have designated as a querier. +> +> When running multiple local instances for testing or separate nodes in +> production, specifying the host ensures writes and queries are routed to the +> correct instance. + +{{% code-placeholders "(http://localhost:8585)|AUTH_TOKEN|DATABASE_NAME|QUERY" %}} +```bash +# Example querying a specific host +# HTTP-bound Port: 8585 +influxdb3 query \ + --host http://localhost:8585 + --token AUTH_TOKEN \ + --database DATABASE_NAME \ + "QUERY" +``` +{{% /code-placeholders %}} + +Replace the following placeholders with your values: + +- {{% code-placeholder-key %}}`http://localhost:8585`{{% /code-placeholder-key %}}: the host and port of the node 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 %}} +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to query +- {{% code-placeholder-key %}}`QUERY`{{% /code-placeholder-key %}}: the SQL or InfluxQL query to run against the database + +{{% page-nav + prev="/influxdb3/enterprise/get-started/setup/" + prevText="Set up InfluxDB" + next="/influxdb3/enterprise/get-started/write/" + nextText="Write data" +%}} \ No newline at end of file diff --git a/content/influxdb3/enterprise/get-started/process.md b/content/influxdb3/enterprise/get-started/process.md new file mode 100644 index 000000000..5e9622388 --- /dev/null +++ b/content/influxdb3/enterprise/get-started/process.md @@ -0,0 +1,27 @@ +--- +title: Process data in {{% product-name %}} +seotitle: Process data | Get started with {{% product-name %}} +description: > + Learn how to use the {{% product-name %}} Processing Engine to process data and + perform various tasks like downsampling, alerting, forecasting, data + normalization, and more. +menu: + influxdb3_enterprise: + name: Process data + identifier: gs-process-data + parent: Get started +weight: 105 +aliases: + - /influxdb3/enterprise/get-started/process-data/ + - /influxdb3/enterprise/get-started/processing-engine/ +related: + - /influxdb3/enterprise/plugins/ + - /influxdb3/enterprise/reference/cli/influxdb3/create/plugin/ + - /influxdb3/enterprise/reference/cli/influxdb3/create/trigger/ +source: /shared/influxdb3-get-started/processing-engine.md +--- + + diff --git a/content/influxdb3/enterprise/get-started/query.md b/content/influxdb3/enterprise/get-started/query.md new file mode 100644 index 000000000..79446ee3d --- /dev/null +++ b/content/influxdb3/enterprise/get-started/query.md @@ -0,0 +1,24 @@ +--- +title: Query data in {{% product-name %}} +seotitle: Query data | Get started with {{% product-name %}} +description: > + Learn how to get started querying data in {{% product-name %}} using native + SQL or InfluxQL with the `influxdb3` CLI and other tools. +menu: + influxdb3_enterprise: + name: Query data + identifier: gs-query-data + parent: Get started +weight: 104 +related: + - /influxdb3/enterprise/query-data/ + - /influxdb3/enterprise/reference/sql/ + - https://datafusion.apache.org/user-guide/sql/index.html, Apache DataFusion SQL reference + - /influxdb3/enterprise/reference/influxql/ +source: /shared/influxdb3-get-started/query.md +--- + + diff --git a/content/influxdb3/enterprise/get-started/setup.md b/content/influxdb3/enterprise/get-started/setup.md new file mode 100644 index 000000000..489b29a5c --- /dev/null +++ b/content/influxdb3/enterprise/get-started/setup.md @@ -0,0 +1,21 @@ +--- +title: Set up {{% product-name %}} +seotitle: Set up InfluxDB | Get started with {{% product-name %}} +description: > + Install, configure, and set up authorization for {{% product-name %}}. +menu: + influxdb3_enterprise: + name: Set up Enterprise + parent: Get started +weight: 101 +related: + - /influxdb3/enterprise/install/ + - /influxdb3/enterprise/admin/tokens/ + - /influxdb3/enterprise/reference/config-options/ +source: /shared/influxdb3-get-started/setup.md +--- + + diff --git a/content/influxdb3/enterprise/get-started/write.md b/content/influxdb3/enterprise/get-started/write.md new file mode 100644 index 000000000..255c0a07e --- /dev/null +++ b/content/influxdb3/enterprise/get-started/write.md @@ -0,0 +1,22 @@ +--- +title: Write data to {{% product-name %}} +seotitle: Write data | Get started with {{% product-name %}} +description: > + Learn how to write time series data to {{% product-name %}} using the + `influxdb3` CLI and _line protocol_, an efficient, human-readable write syntax. +menu: + influxdb3_enterprise: + name: Write data + identifier: gs-write-data + parent: Get started +weight: 103 +related: + - /influxdb3/enterprise/write-data/ + - /influxdb3/enterprise/reference/line-protocol/ +source: /shared/influxdb3-get-started/write.md +--- + + diff --git a/content/influxdb3/enterprise/install.md b/content/influxdb3/enterprise/install/_index.md similarity index 100% rename from content/influxdb3/enterprise/install.md rename to content/influxdb3/enterprise/install/_index.md diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/_index.md b/content/influxdb3/enterprise/reference/cli/influxdb3/_index.md index db57936cb..863318111 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/_index.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/_index.md @@ -32,6 +32,7 @@ influxdb3 [GLOBAL-OPTIONS] [COMMAND] | [serve](/influxdb3/enterprise/reference/cli/influxdb3/serve/) | Run the {{% product-name %}} server | | [show](/influxdb3/enterprise/reference/cli/influxdb3/show/) | List resources | | [test](/influxdb3/enterprise/reference/cli/influxdb3/test/) | Test plugins | +| [update](/influxdb3/enterprise/reference/cli/influxdb3/update/) | Update resources | | [write](/influxdb3/enterprise/reference/cli/influxdb3/write/) | Write to {{% product-name %}} | ## Global options diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md index 1411c22bf..5e40829e9 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/_index.md @@ -4,7 +4,7 @@ description: > The `influxdb3 create token` command creates an admin token or a scoped resource token for authenticating and authorizing actions in an {{% product-name %}} instance. menu: influxdb3_enterprise: - parent: influxdb3 + parent: influxdb3 create name: influxdb3 create token weight: 300 source: /shared/influxdb3-cli/create/token/_index.md diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md b/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md index 2b0e70db2..90f3f93c0 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md @@ -27,8 +27,8 @@ influxdb3 serve [OPTIONS] \ - **node-id**: A unique identifier for your server instance. Must be unique for any hosts sharing the same object store. - **cluster-id**: A unique identifier for your cluster. Must be different from any node-id in your cluster. -- **object-store**: Determines where time series data is stored. _Default is `memory`_. -- **data-dir**: Path for local file storage (required when using `--object-store file`). +- **object-store**: Determines where time series data is stored. +- Other object store parameters depending on the selected `object-store` type. > [!NOTE] > `--node-id` and `--cluster-id` support alphanumeric strings with optional hyphens. diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/show/license.md b/content/influxdb3/enterprise/reference/cli/influxdb3/show/license.md new file mode 100644 index 000000000..579cfb8e5 --- /dev/null +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/show/license.md @@ -0,0 +1,88 @@ +--- +title: influxdb3 show license +description: > + The `influxdb3 show license` command displays license information for your + InfluxDB 3 Enterprise server. +menu: + influxdb3_enterprise: + parent: influxdb3 show + name: influxdb3 show license +weight: 300 +--- + +The `influxdb3 show license` command displays license information for your {{< product-name >}} instance. + + +## Usage + + + +```bash +influxdb3 show license [OPTIONS] +``` + +## Options + +| Option | | Description | +| :----- | :----------- | :--------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| | `--cluster-id` | _({{< req >}})_ Cluster identifier | +| | `--node-id` | _({{< req >}})_ Node identifier | +| | `--object-store` | _({{< req >}})_ Object store type (file, memory, s3, gcs, azure) | +| | `--token` | Authentication token | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | + +> [!Note] +> **CLI help documentation bug in v3.2.0** +> +> The `influxdb3 show license --help` output in v3.2.0 does not display the required `--object-store`, `--cluster-id`, and `--node-id` options and related object store configuration options. +> This command requires object store configuration and cluster/node identification to function properly. + +### Additional object store options + +Depending on the `--object-store` type specified, additional configuration options may be required: + +- **S3**: AWS credentials and bucket configuration +- **GCS**: Google Cloud credentials and bucket configuration +- **Azure**: Azure credentials and container configuration +- **File**: Local file system path configuration + +### Option environment variables + +You can use the following environment variables to set command options: + +| Environment Variable | Option | +| :------------------------ | :----------- | +| `INFLUXDB3_HOST_URL` | `--host` | +| `INFLUXDB3_AUTH_TOKEN` | `--token` | + +## Examples + +### Display license information with file object store + +{{% code-placeholders "AUTH_TOKEN|CLUSTER_ID|NODE_ID" %}} + + + +```bash +influxdb3 show license \ + --cluster-id CLUSTER_ID \ + --node-id NODE_ID \ + --object-store file \ + --token AUTH_TOKEN +``` + +{{% /code-placeholders %}} + +In the example above, replace the following: + +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + Authentication token +- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: + Your cluster identifier +- {{% code-placeholder-key %}}`NODE_ID`{{% /code-placeholder-key %}}: + Your node identifier + +The command displays information about your Enterprise license, including license type, expiration date, and usage limits. \ No newline at end of file diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/update/_index.md b/content/influxdb3/enterprise/reference/cli/influxdb3/update/_index.md new file mode 100644 index 000000000..8166b3bbb --- /dev/null +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/update/_index.md @@ -0,0 +1,15 @@ +--- +title: influxdb3 update +description: > + The `influxdb3 update` command updates resources such as databases and tables. +menu: + influxdb3_enterprise: + parent: influxdb3 + name: influxdb3 update +weight: 300 +source: /shared/influxdb3-cli/update/_index.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/update/database.md b/content/influxdb3/enterprise/reference/cli/influxdb3/update/database.md new file mode 100644 index 000000000..0a8130a62 --- /dev/null +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/update/database.md @@ -0,0 +1,15 @@ +--- +title: influxdb3 update database +description: > + The `influxdb3 update database` command updates an existing database. +menu: + influxdb3_enterprise: + parent: influxdb3 update + name: influxdb3 update database +weight: 400 +source: /shared/influxdb3-cli/update/database/_index.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/update/table.md b/content/influxdb3/enterprise/reference/cli/influxdb3/update/table.md new file mode 100644 index 000000000..d1a2b0bf2 --- /dev/null +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/update/table.md @@ -0,0 +1,17 @@ +--- +title: influxdb3 update table +description: > + The `influxdb3 update table` command updates an existing table. +menu: + influxdb3_enterprise: + parent: influxdb3 update + name: influxdb3 update table +weight: 400 +source: /shared/influxdb3-cli/update/table/_index.md +alt_links: + core: /influxdb3/core/reference/cli/influxdb3/update/ +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/reference/config-options.md b/content/influxdb3/enterprise/reference/config-options.md index 473eb7a77..e1d4ef469 100644 --- a/content/influxdb3/enterprise/reference/config-options.md +++ b/content/influxdb3/enterprise/reference/config-options.md @@ -254,6 +254,8 @@ export DATABASE_NODE=node0 && influxdb3 serve \ --cluster-id cluster0 \ --object-store file \ --data-dir ~/.influxdb3/data +``` + --- #### object-store @@ -261,7 +263,7 @@ export DATABASE_NODE=node0 && influxdb3 serve \ Specifies which object storage to use to store Parquet files. This option supports the following values: -- `memory` _(default)_: Effectively no object persistence +- `memory`: Effectively no object persistence - `memory-throttled`: Like `memory` but with latency and throughput that somewhat resembles a cloud object store - `file`: Stores objects in the local filesystem (must also set `--data-dir`) - `s3`: Amazon S3 (must also set `--bucket`, `--aws-access-key-id`, `--aws-secret-access-key`, and possibly `--aws-default-region`) @@ -318,7 +320,6 @@ The server processes all requests without requiring tokens or authentication. Optionally disable authz by passing in a comma separated list of resources. Valid values are `health`, `ping`, and `metrics`. - --- ### AWS diff --git a/content/influxdb3/enterprise/write-data/api-client-libraries.md b/content/influxdb3/enterprise/write-data/client-libraries.md similarity index 53% rename from content/influxdb3/enterprise/write-data/api-client-libraries.md rename to content/influxdb3/enterprise/write-data/client-libraries.md index 5e51607b5..6b32cc7cb 100644 --- a/content/influxdb3/enterprise/write-data/api-client-libraries.md +++ b/content/influxdb3/enterprise/write-data/client-libraries.md @@ -1,24 +1,24 @@ --- -title: Use the HTTP API and client libraries to write data +title: Use InfluxDB client libraries to write data description: > - Use the `/api/v3/write_lp` HTTP API endpoint and InfluxDB API clients to write points as line protocol data to {{% product-name %}}. + Use InfluxDB API clients to write points as line protocol data to {{% product-name %}}. menu: influxdb3_enterprise: - name: Use the API and client libraries + name: Use client libraries parent: Write data - identifier: write-api-client-libs + identifier: write-client-libs weight: 100 aliases: - - /influxdb3/enterprise/write-data/client-libraries/ + - /influxdb3/enterprise/write-data/api-client-libraries/ related: - /influxdb3/enterprise/reference/syntax/line-protocol/ - /influxdb3/enterprise/get-started/write/ - /influxdb3/enterprise/reference/client-libraries/v3/ - /influxdb3/enterprise/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint -source: /shared/influxdb3-write-guides/api-client-libraries.md +source: /shared/influxdb3-write-guides/client-libraries.md --- +--> \ No newline at end of file diff --git a/content/influxdb3/enterprise/write-data/compatibility-apis.md b/content/influxdb3/enterprise/write-data/compatibility-apis.md index 40b25bde7..b811d24c0 100644 --- a/content/influxdb3/enterprise/write-data/compatibility-apis.md +++ b/content/influxdb3/enterprise/write-data/compatibility-apis.md @@ -17,10 +17,10 @@ related: - /influxdb3/enterprise/reference/client-libraries/v2/ - /influxdb3/enterprise/api/v3/#operation/PostV2Write, /api/v2/write (v2-compatible) endpoint - /influxdb3/enterprise/api/v3/#operation/PostV1Write, /write (v1-compatible) endpoint -source: /shared/influxdb3-write-guides/compatibility-apis.md +source: /shared/influxdb3-write-guides/http-api/compatibility-apis.md --- \ No newline at end of file diff --git a/content/influxdb3/enterprise/write-data/http-api/_index.md b/content/influxdb3/enterprise/write-data/http-api/_index.md new file mode 100644 index 000000000..da321e75f --- /dev/null +++ b/content/influxdb3/enterprise/write-data/http-api/_index.md @@ -0,0 +1,22 @@ +--- +title: Use the InfluxDB HTTP API to write data +description: > + Use the `/api/v3/write_lp`, `/api/v2/write`, or `/write` HTTP API endpoints + to write data to {{% product-name %}}. +menu: + influxdb3_enterprise: + name: Use the HTTP API + parent: Write data + identifier: write-http-api +weight: 100 +related: + - /influxdb3/enterprise/reference/syntax/line-protocol/ + - /influxdb3/enterprise/get-started/write/ + - /influxdb3/enterprise/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint +source: /shared/influxdb3-write-guides/http-api/_index.md +--- + + diff --git a/content/influxdb3/enterprise/write-data/http-api/compatibility-apis.md b/content/influxdb3/enterprise/write-data/http-api/compatibility-apis.md new file mode 100644 index 000000000..47f645856 --- /dev/null +++ b/content/influxdb3/enterprise/write-data/http-api/compatibility-apis.md @@ -0,0 +1,26 @@ +--- +title: Use compatibility APIs and client libraries to write data +description: > + Use HTTP API endpoints compatible with InfluxDB v2 and v1 clients to write + points as line protocol data to {{% product-name %}}. +menu: + influxdb3_enterprise: + name: Use v1 and v2 compatibility APIs + parent: write-http-api +weight: 202 +aliases: + - /influxdb3/enterprise/write-data/client-libraries/ + - /influxdb3/enterprise/write-data/compatibility-apis/ +related: + - /influxdb3/enterprise/reference/syntax/line-protocol/ + - /influxdb3/enterprise/get-started/write/ + - /influxdb3/enterprise/reference/client-libraries/v2/ + - /influxdb3/enterprise/api/v3/#operation/PostV2Write, /api/v2/write (v2-compatible) endpoint + - /influxdb3/enterprise/api/v3/#operation/PostV1Write, /write (v1-compatible) endpoint +source: /shared/influxdb3-write-guides/http-api/compatibility-apis.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/write-data/http-api/v3-write-lp.md b/content/influxdb3/enterprise/write-data/http-api/v3-write-lp.md new file mode 100644 index 000000000..1feec9880 --- /dev/null +++ b/content/influxdb3/enterprise/write-data/http-api/v3-write-lp.md @@ -0,0 +1,20 @@ +--- +title: Use the v3 write API to write data +description: > + Use the `/api/v3/write_lp` HTTP API endpoint to write data to {{% product-name %}}. +menu: + influxdb3_enterprise: + name: Use the v3 write API + parent: write-http-api +weight: 201 +related: + - /influxdb3/enterprise/reference/syntax/line-protocol/ + - /influxdb3/enterprise/get-started/write/ + - /influxdb3/enterprise/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint +source: /shared/influxdb3-write-guides/http-api/v3-write-lp.md +--- + + diff --git a/content/influxdb3/explorer/_index.md b/content/influxdb3/explorer/_index.md index 5078f75bb..a0827d43e 100644 --- a/content/influxdb3/explorer/_index.md +++ b/content/influxdb3/explorer/_index.md @@ -33,14 +33,14 @@ Run the Docker image to start InfluxDB 3 Explorer: ```sh # Pull the Docker image -docker pull quay.io/influxdb/influxdb3-explorer:latest +docker pull influxdata/influxdb3-ui:{{% latest-patch %}} # Run the Docker container docker run --detach \ --name influxdb3-explorer \ --publish 8888:80 \ --publish 8889:8888 \ - quay.io/influxdb/influxdb3-explorer:latest \ + influxdata/influxdb3-ui:{{% latest-patch %}} \ --mode=admin ``` diff --git a/content/influxdb3/explorer/get-started.md b/content/influxdb3/explorer/get-started.md new file mode 100644 index 000000000..244191130 --- /dev/null +++ b/content/influxdb3/explorer/get-started.md @@ -0,0 +1,132 @@ +--- +title: Get started with InfluxDB 3 Explorer +description: > + Learn how to use InfluxDB 3 Explorer to connect to InfluxDB 3, write data, and + query data. +menu: + influxdb3_explorer: + name: Get started +weight: 3 +--- + +Get started with {{% product-name %}} by connecting it to an InfluxDB 3 instance, +writing data to InfluxDB, and then querying that data. This guide walks you +through each of those steps. + +1. [Connect to an InfluxDB 3 server](#connect-to-an-influxdb-3-server) +2. [Write data to InfluxDB](#write-data-to-influxdb) +3. [Query data from InfluxDB](#query-data-from-influxdb) + +> [!Note] +> This guide assumes you have already [installed {{% product-name %}}](/influxdb3/explorer/install/). + +## Connect to an InfluxDB 3 server + +InfluxDB 3 Explorer supports the following InfluxDB 3 products: + +- [InfluxDB 3 Core](/influxdb3/core/) +- [InfluxDB 3 Enterprise](/influxdb3/enterprise/) + +1. Navigate to **Configure** > **Servers**. +2. Click **+ Connect Your First Server**. +3. Provide the following InfluxDB 3 server information: + + - **Server name**: A name to identify the InfluxDB 3 server you're connecting to. + - **Server URL**: The URL used to connect to your InfluxDB 3 server. + - Select the protocol to use (http or https). + - Provide the host and, if necessary, the port. + - **Token**: The authorization token to use to connect to your InfluxDB 3 server. + We recommend using an InfluxDB 3 _admin_ token. + + > [!Important] + > #### Token permissions may limit Explorer functionality + > + > The permissions associated with the provided token determine what + > databases you can access using this server configuration. InfluxDB 3 + > tokens with limited permissions may not be able to use some Explorer + > functionality. + +4. Click **Add Server**. + +InfluxDB 3 Explorer attempts to verify the connection. If successful, Explorer +saves the server configuration and selects it as the active server. + +> [!Note] +> If you already have data in your InfluxDB 3 instance, skip to +> [Query data from InfluxDB](#query-data-from-influxdb). + +## Write data to InfluxDB + +{{% product-name %}} lets you write data to InfluxDB 3 and provides multiple +options. For this getting started guide, use Explorer to write one of the +sample data sets to InfluxDB: + +1. Navigate to **Write Data** > **Sample/Dev Data**. +2. Select any of the available sample data sets. +3. Click **Write Sample Data**. + +{{% product-name %}} creates a new database and then writes the sample data to +the database. + +### Other write methods + +{{% product-name %}} provides other ways to write data to InfluxDB, including +the following: + +- Line protocol +- CSV or JSON +- InfluxDB 3 client libraries +- Telegraf + +## Query data from InfluxDB + +To use {{% product-name %}} to query data from InfluxDB 3, navigate to +**Query Data** > **Data Explorer**. + +The _Data Explorer_ lets you explore the +schema of your database and automatically builds SQL queries by either +selecting columns in the _Schema Browser_ or by using _Natural Language_ with +the {{% product-name %}} OpenAI integration. + +For this getting started guide, use the Schema Browser to build a SQL query +that returns data from the newly written sample data set. + +1. On the **Data Explorer** in the **Schema** column, select the database you + want to query from the database dropdown menu. + Once selected, all tables in the database appear. +2. Click the name of the table you want to query to expand and view all the + columns in that table. +3. Select each column you want to query. + As you select columns in the Schema Browser, Explorer generates and updates + an SQL query in the _Query pane_. +4. Use the time range dropdown menu above the Query pane to select a time range + to query. You can select one of the predefined relative time ranges, or you + can select _Custom Range_ to define an absolute time range to query. +5. With columns and a time range selected, click **Run Query**. + +{{% product-name %}} runs the query and returns the results in the _Results pane_. +The Results pane provides three view options: + +- **Table** _(default)_: Displays raw query results in paginated table format. +- **Line**: Displays query results in a line graph. +- **Bar**: Displays query results in a bar graph. + +> [!Tip] +> SQL query results may not be ordered by `time` and Line and Bar graph +> visualizations may behave unexpectedly. To order results by time: +> +> - Ensure that you query the `time` column +> - Update the query to include an `ORDER BY time` clause. + +Congratulations! You have successfully used {{% product-name %}} to connect to, +write data to, and query data from an InfluxDB 3 instance. + +## Video walkthrough + +{{< youtube "zW2Hi1Ki4Eo" >}} + + diff --git a/content/influxdb3/explorer/get-started/_index.md b/content/influxdb3/explorer/get-started/_index.md deleted file mode 100644 index e15e4a3c4..000000000 --- a/content/influxdb3/explorer/get-started/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Get started using InfluxDB 3 Explorer -description: Follow steps to get started using InfluxDB 3 Explorer. -menu: - influxdb3_explorer: - name: Get started -weight: 3 ---- - -Follow steps to get started using InfluxDB 3 Explorer. - -{{< youtube "zW2Hi1Ki4Eo" >}} - - diff --git a/content/influxdb3/explorer/get-started/connect.md b/content/influxdb3/explorer/get-started/connect.md deleted file mode 100644 index 7d717c024..000000000 --- a/content/influxdb3/explorer/get-started/connect.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Connect to a server -description: - Use InfluxDB 3 Explorer to connect to an InfluxDB 3 server. -menu: - influxdb3_explorer: - parent: Get started -weight: 101 -draft: true ---- - -Use InfluxDB 3 Explorer to connect to an InfluxDB 3 server. \ No newline at end of file diff --git a/content/influxdb3/explorer/install.md b/content/influxdb3/explorer/install.md index a1858d2a2..9478137ec 100644 --- a/content/influxdb3/explorer/install.md +++ b/content/influxdb3/explorer/install.md @@ -33,7 +33,7 @@ Use [Docker](https://docker.com) to install and run **InfluxDB 3 Explorer**. 2. **Pull the {{% product-name %}} Docker image** ```bash - docker pull quay.io/influxdb/influxdb3-explorer:latest + influxdata/influxdb3-ui:{{% latest-patch %}} ``` 3. **Create local directories** _(optional)_ @@ -73,7 +73,11 @@ Use [Docker](https://docker.com) to install and run **InfluxDB 3 Explorer**. - `$(pwd)/db:/db:rw` - `$(pwd)/config:/app-root/config:ro` - `$(pwd)/ssl:/etc/nginx/ssl:ro` - - Any of the available [environment variables](#environment-variables) + - Any of the available [environment variables](#environment-variables) + + > [!Note] + > To persist sessions across container restarts, see the detailed instructions + > on setting the [`SESSION_SECRET_KEY` environment variable](#session_secret_key). ```bash docker run --detach \ @@ -83,7 +87,7 @@ Use [Docker](https://docker.com) to install and run **InfluxDB 3 Explorer**. --volume $(pwd)/config:/app-root/config:ro \ --volume $(pwd)/db:/db:rw \ --volume $(pwd)/ssl:/etc/nginx/ssl:ro \ - quay.io/influxdb/influxdb3-explorer:latest \ + influxdata/influxdb3-ui:{{% latest-patch %}} \ --mode=admin ``` @@ -114,6 +118,13 @@ To enable TLS/SSL, mount valid certificate and key files into the container: The nginx web server automatically uses certificate files when they are present in the mounted path. +> [!Note] +> You can use a custom location for certificate and key files. +> Use the [`SSL_CERT_PATH`](#ssl_cert_path) and [`SSL_KEY_PATH`](#ssl_key_path) +> environment variables to identify the custom location. +> Also update the SSL directory volume mount path inside the container. + + --- ## Pre-configure InfluxDB connection settings @@ -191,11 +202,91 @@ If `--mode` is not set, the container defaults to query mode. Use the following environment variables to customize {{% product-name %}} settings in your container. -| Variable | Description | Default | -|----------------|--------------------------------------------------|----------------------| -| `DATABASE_URL` | Path to SQLite DB inside container | `/db/sqlite.db` | +- [DATABASE_URL](#database_url) +- [SESSION_SECRET_KEY](#session_secret_key) +- [SSL_CERT_PATH](#ssl_cert_path) +- [SSL_KEY_PATH](#ssl_key_path) ---- +### DATABASE_URL + +Path to SQLite DB inside container. The default is `/db/sqlite.db`. + +{{< expand-wrapper >}} +{{% expand "View `DATABASE_URL` example" %}} + + +```bash +docker run --detach \ + # ... + --volume $(pwd)/db:/custom/db-path:rw \ + --env DATABASE_URL=/custom/db-path/sqlite.db \ + influxdata/influxdb3-ui:{{% latest-patch %}} +``` +{{% /expand %}} +{{< /expand-wrapper >}} + +### SESSION_SECRET_KEY + +Specifies the secret key for session management. If none is provided, Explorer +uses a random 32-byte hex string as the session secret key. + +{{< expand-wrapper >}} +{{% expand "View `SESSION_SECRET_KEY` example" %}} + + +```bash +docker run --detach \ + # ... + --env SESSION_SECRET_KEY=xxX0Xx000xX0XxxxX0Xx000xX0XxX00x \ + influxdata/influxdb3-ui:{{% latest-patch %}} +``` +{{% /expand %}} +{{< /expand-wrapper >}} + +> [!Important] +> #### Always set SESSION_SECRET_KEY in production +> +> When you restart the container, {{% product-name %}} generates a new key if +> not explicitly set. For production use cases, always set the `SESSION_SECRET_KEY` +> environment variable to persist sessions across restarts. + +### SSL_CERT_PATH + +Defines the path to the SSL certificate file inside the container. +Default is `/etc/nginx/ssl/cert.pem`. + +{{< expand-wrapper >}} +{{% expand "View `SSL_CERT_PATH` example" %}} + + +```bash +docker run --detach \ + # ... + --volume $(pwd)/ssl:/custom/ssl:ro \ + --env SSL_CERT_PATH=/custom/ssl/cert.pem \ + influxdata/influxdb3-ui:{{% latest-patch %}} +``` +{{% /expand %}} +{{< /expand-wrapper >}} + +### SSL_KEY_PATH + +Defines the path to the SSL private key file inside the container. +Default is `/etc/nginx/ssl/key.pem`. + +{{< expand-wrapper >}} +{{% expand "View `SSL_KEY_PATH` example" %}} + + +```bash +docker run --detach \ + # ... + --volume $(pwd)/ssl:/custom/ssl:ro \ + --env SSL_KEY_PATH=/custom/ssl/key.pem \ + influxdata/influxdb3-ui:{{% latest-patch %}} +``` +{{% /expand %}} +{{< /expand-wrapper >}} ## Volume Reference @@ -205,8 +296,6 @@ in your container. | `/app-root/config` | JSON config for defaults | `./config` | | `/etc/nginx/ssl` | SSL certs for HTTPS | `./ssl` | ---- - ## Exposed Ports | Port | Protocol | Purpose | diff --git a/content/influxdb3/explorer/manage-databases.md b/content/influxdb3/explorer/manage-databases.md new file mode 100644 index 000000000..08a7c5be5 --- /dev/null +++ b/content/influxdb3/explorer/manage-databases.md @@ -0,0 +1,53 @@ +--- +title: Manage databases with InfluxDB 3 Explorer +seotitle: Manage InfluxDB databases with InfluxDB 3 Explorer +description: > + Use InfluxDB 3 Explorer to manage databases in an InfluxDB 3 instance. +menu: + influxdb3_explorer: + name: Manage databases +weight: 4 +related: + - /influxdb3/core/admin/databases/, Manage databases in InfluxDB 3 Core + - /influxdb3/enterprise/admin/databases/, Manage databases in InfluxDB 3 Enterprise +--- + +{{% product-name %}} lets you manage databases in your InfluxDB 3 Core instance +or InfluxDB 3 Enterprise cluster. + +> [!Important] +> Using {{% product-name %}} to manage a database in InfluxDB 3 requires that +> Explorer is running in [admin mode](/influxdb3/explorer/install/#run-in-query-or-admin-mode) +> and that the token used in the InfluxDB 3 server configuration is an +> [admin token](/influxdb3/enterprise/admin/tokens/admin/). + +To manage databases, navigate to **Manage Databases** in Explorer. +This page provides a list of databases in the connected InfluxDB 3 server that +contains the database name, retention period, and number of tables +(which includes system tables). + +## Create a database + +1. On the **Manage Databases** page, click **+ Create New**. +2. Provide a **Database name**. + _For information about naming restrictions, see + [InfluxDB 3 naming restrictions](/influxdb3/enterprise/admin/databases/create/#database-naming-restrictions)._ +3. _(Optional)_ Specify a **Retention Period** for the database. + This determines how long InfluxDB retains data (based on timestamp) in the + database before expiring and removing the data. If no retention period is + specified, InfluxDB does not expire data in the database. + + Set the following: + + - **Retention Period**: The number of time units to retain data. + - **Unit**: The unit of time to use in the retention period definition. + +4. Click **{{< icon "check" >}} Create Database**. + +## Delete a database + +1. On the **Manage Databases** page, click **{{< icon "trash" >}}**. +2. Confirm that you want to delete the database. + +> [!Caution] +> Deleting a database is a destructive action and cannot be undone. diff --git a/content/influxdb3/explorer/manage-plugins/_index.md b/content/influxdb3/explorer/manage-plugins/_index.md new file mode 100644 index 000000000..4c0fad8c4 --- /dev/null +++ b/content/influxdb3/explorer/manage-plugins/_index.md @@ -0,0 +1,93 @@ +--- +title: Manage InfluxDB 3 plugins with InfluxDB 3 Explorer +description: > + Use InfluxDB 3 Explorer to manage InfluxDB 3 processing engine plugins. +menu: + influxdb3_explorer: + name: Manage InfluxDB plugins +weight: 5 +cascade: + related: + - /influxdb3/core/plugins/, InfluxDB 3 Core Processing engine plugins + - /influxdb3/enterprise/plugins/, InfluxDB 3 Enterprise Processing engine plugins +cascade: + draft: true + prepend: | + > [!Warning] + > #### {{% product-name %}} plugin management is currently in beta + > + > The {{% product-name %}} plugin management tools and the Plugin Library are + > currently in **beta**. +--- + +{{% product-name %}} lets you manage plugins in your InfluxDB 3 instance or cluster. +[InfluxDB 3 Processing engine plugins](/influxdb3/enterprise/plugins/) let you +extend your database with custom Python code. +Use {{% product-name %}} to manage plugins in your InfluxDB 3 instance and +install prebuilt plugins from the _Plugin Library_. + +Each plugin can define one or more _triggers_—rules that +specify when the plugin should execute. Triggers are typically based on +conditions such as data arriving in a specific table or matching certain +criteria. + +- **Data writes** - Process and transform data as it enters the database +- **Scheduled events** - Run code at defined intervals or specific times +- **HTTP requests** - Expose custom API endpoints that execute your code + +When a trigger condition is met, InfluxDB 3 automatically runs the associated +plugin code. This enables real-time data processing, enrichment, or alerting +without manual intervention. +Use the InfluxDB 3 Explorer UI to enable, disable, or configure triggers for each plugin. + + + +- [View installed plugins](#view-installed-plugins) + - [Filter installed plugins](#filter-installed-plugins) +- [Enable or disable a plugin](#enable-or-disable-a-plugin) +- [ View Plugin Logs](#view-plugin-logs) +- [Delete a plugin](#delete-a-plugin) +- [Use the Plugin Library](#use-the-plugin-library) + + + +## View installed plugins + +To view plugins installed in your InfluxDB 3 server, navigate to +**Manage Plugins** > **Overview**. + +1. Navigate to the **Manage Plugins** > **Overview** section in the left sidebar. +2. All installed plugins are listed under the _All Plugins_ tab. + +### Filter installed plugins + +To filter installed plugins by state, use the top tabs to filter by: + +- **All Plugins** +- **Running** +- **Stopped** +- **Errors** + +You can also use the **search bar** to filter by plugin name. + +## Enable or disable a plugin + +1. In the plugin list, locate the desired plugin. + + - **If the plugin is currently running (enabled)**, click {{< icon "pause" >}} to disable the plugin. + - **If the plugin is currently stopped (disabled)**, click the {{< icon "play" >}} button to enable the plugin. + +## View plugin logs + +1. In the plugin list, locate the desired plugin. +2. Click **Logs** to view the most recent logs output by the plugin. +3. To view more log entries, click **View More**. +4. To export the logs, click **Export**. + +## Delete a plugin + +1. In the plugin list, locate the desired plugin. +2. Click the **{{< icon "trash" >}} button** to delete the plugin. +3. Confirm that you want to delete the plugin. + +{{< children hlevel="h2" >}} diff --git a/content/influxdb3/explorer/manage-plugins/plugin-library.md b/content/influxdb3/explorer/manage-plugins/plugin-library.md new file mode 100644 index 000000000..e7894a69e --- /dev/null +++ b/content/influxdb3/explorer/manage-plugins/plugin-library.md @@ -0,0 +1,74 @@ +--- +title: Use the Plugin Library +description: > + Use InfluxDB 3 Explorer Plugin Library to view and install pre-built InfluxDB + 3 processing engine plugins. +menu: + influxdb3_explorer: + name: Plugin Library + parent: Manage InfluxDB plugins +weight: 101 +--- + +The _InfluxDB Plugin Library_ is a collection of pre-built InfluxDB 3 plugins that +you can install in your InfluxDB 3 server. To view the Plugin library, navigate +to **Manage Plugins** > **Plugin Library** in the left sidebar. + +## Search the Plugin Library + +To search for plugins in the Plugin library, submit a search term in the search bar. + +## Install a plugin + +1. In the **Plugin Library**, locate the plugin you want to install. +2. Click on the plugin card to open its details. +3. To install a plugin from {{% product-name %}} select **Install Plugin**: +4. Provide the following: + + - **Database**: The name of the InfluxDB 3 database to associate the + plugin with. + - **Trigger Name**: A unique name for the plugin and trigger combination. + - **Trigger Type**: The trigger type. What trigger types are available + depend on the plugin. + + _For more information about InfluxDB 3 plugin triggers, see + [Understand trigger types](/influxdb3/enterprise/plugins/#understand-trigger-types)._ + + Depending on the selected trigger type, provide the following: + + - **Data Writes (All Tables)**: _no additional configuration options_. + - **Data Writes (Single Table)**: + - **Table Name**: The name of the table that, when written to, triggers the plugin to run. + - **Schedule**: + - **Frequency**: When to run the plugin using one of the following patterns: + - `every:`: Run at specified intervals--for example: + `every:15m`. + - `cron:`: Run on a cron schedule--for + example: `cron:0 */12 * * *`. + - **HTTP Endpoint**: + - **API Endpoint**: The API endpoint name to use to trigger the plugin--for + example: `downsample`. To trigger the plugin, you would then send + a request to the `/api/v3/engine/downsample` endpoint of your InfluxDB + server to trigger the plugin. + + - **Advanced Settings** + - **Run Asynchronously**: Execute the plugin asynchronously and do not + wait for a response. + - **Error Behavior**: Specify the action you want the plugin to take + when it encounters an error: + - **Log**: Log the error to your InfluxDB server's logs. + - **Retry**: Retry the plugin execution. + - **Disable**: Disable the plugin. + + - **Arguments**: Specific arguments to pass to the Plugin. + Plugins can have both required and optional arguments. + +5. Click **Deploy** to install the plugin. + +### Other plugin installation options + +{{% product-name %}} also lets you do the following: + +- **Download Code**: Download the plugin code to view it or modify it for your own use. +- **Copy Install Command**: Copy the `influxdb3` CLI command you can use to + manually install the plugin on your InfluxDB 3 server. diff --git a/content/influxdb3/explorer/manage-tokens.md b/content/influxdb3/explorer/manage-tokens.md new file mode 100644 index 000000000..492f21fe0 --- /dev/null +++ b/content/influxdb3/explorer/manage-tokens.md @@ -0,0 +1,104 @@ +--- +title: Manage tokens with InfluxDB 3 Explorer +seotitle: Manage InfluxDB tokens with InfluxDB 3 Explorer +description: > + Use InfluxDB 3 Explorer to manage authorization tokens for an InfluxDB 3 instance. +menu: + influxdb3_explorer: + name: Manage tokens +weight: 4 +related: + - /influxdb3/core/admin/tokens/, Manage tokens in InfluxDB 3 Core + - /influxdb3/enterprise/admin/tokens/, Manage tokens in InfluxDB 3 Enterprise +--- + +{{% product-name %}} lets you manage authorization tokens for your InfluxDB 3 +Core instance or InfluxDB 3 Enterprise cluster. + +> [!Important] +> Using {{% product-name %}} to manage authorization tokens in InfluxDB 3 requires that +> Explorer is running in [admin mode](/influxdb3/explorer/install/#run-in-query-or-admin-mode) +> and that the token used in the InfluxDB 3 server configuration is an +> [admin token](/influxdb3/enterprise/admin/tokens/admin/). + +To manage InfluxDB authorization tokens, navigate to **Manage Tokens** in Explorer. +This page provides a list of databases in the connected InfluxDB 3 server that +contains the database name, retention period, and number of tables +(which includes system tables). + +## Create a token + +Use {{% product-name %}} to create an admin token or a resource token +_(Enterprise only)_ for your InfluxDB 3 instance or cluster. + +For more information about InfluxDB tokens, see: + +- [Manage tokens in InfluxDB 3 Core](/influxdb3/core/admin/tokens/) +- [Manage tokens in InfluxDB 3 Enterprise](/influxdb3/enterprise/admin/tokens/) + +{{< tabs-wrapper >}} +{{% tabs %}} +[Admin Token](#) +[Resource Token _(Enterprise only)_](#) +{{% /tabs %}} +{{% tab-content %}} + + + +To create an _admin_ token: + +1. On the **Manage Databases** page, click **+ Create New**. +2. Select **Admin Token** to create an admin token. +3. Provide a **Token Name**. +4. Click **Create Admin Token**. +5. Copy the generated token string and store it in a secure place. + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +To create a _resource_ token with read or write permissions for specific databases: + +1. On the **Manage Databases** page, click **+ Create New**. +2. Select **Database Token** to create a resource token _(InfluxDB 3 Enterprise only)_. +3. Provide a **Token Name**. +4. _(Optional)_ Select a **Token Expiry**. +5. Select **Database Permissions** to assign to the token. + + To grant the token read or write permissions on all databases, select the + _Read_ and _Write_ column headings. + To grant permissions for specific databases, select the checkboxes next + to each respective database name. + +6. Copy the generated token string and store it in a secure place. + + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +> [!Note] +> #### Store tokens in a secure secret store +> +> This is the _only_ time you are able to view and copy the raw token string. +> We recommend storing tokens in a **secure secret store**. + + +## Delete a token + +On the **Manage Databases** page, click the **{{< icon "trash" >}}** button +on the row of the token you want to delete. + +> [!Caution] +> Deleting a token is a destructive action and cannot be undone. +> Any clients using the deleted token will no longer be able to access your +> InfluxDB 3 instance. + +> [!Note] +> #### You cannot delete the _admin token +> +> When using InfluxDB 3 Enterprise, the first token created in the cluster is +> named `_admin`. This functions as the "operator" token and cannot be deleted. diff --git a/content/kapacitor/v1/reference/about_the_project/release-notes.md b/content/kapacitor/v1/reference/about_the_project/release-notes.md index beb05a02a..567d00928 100644 --- a/content/kapacitor/v1/reference/about_the_project/release-notes.md +++ b/content/kapacitor/v1/reference/about_the_project/release-notes.md @@ -9,6 +9,19 @@ aliases: - /kapacitor/v1/about_the_project/releasenotes-changelog/ --- +## v1.8.0 {date="2025-06-26"} + +> [!Warning] +> +> Python 2-based UDFs are deprecated as of Kapacitor 1.7.7 and are removed in this release. If you are using Python 2 +> with your User-Defined Functions (UDFs), upgrade them to be Python 3-compatible **before** installing this version of Kapacitor. +> This required change aligns with modern security practices and ensures your custom functions will continue to work after upgrading. + +### Dependency updates + +- Upgrade Go to 1.23.9. +- Upgrade go-lang `JWT library` to 4.5.2 + ## v1.7.7 {date="2025-05-27"} > [!Warning] diff --git a/content/shared/influxctl/database/_index.md b/content/shared/influxctl/database/_index.md new file mode 100644 index 000000000..6008bfe4f --- /dev/null +++ b/content/shared/influxctl/database/_index.md @@ -0,0 +1,27 @@ + +The `influxctl database` command and its subcommands manage databases in an +{{% product-name omit=" Clustered" %}} cluster. + +## Usage + +```sh +influxctl database [subcommand] [flags] +``` + +## Subcommands + +| Subcommand | Description | +| :------------------------------------------------------------------------ | :------------------ | +| [create](/influxdb3/version/reference/cli/influxctl/database/create/) | Create a database | +| [delete](/influxdb3/version/reference/cli/influxctl/database/delete/) | Delete a database | +| [list](/influxdb3/version/reference/cli/influxctl/database/list/) | List databases | +| [rename](/influxdb3/version/reference/cli/influxctl/database/rename/) | Rename a database | +| [undelete](/influxdb3/version/reference/cli/influxctl/database/undelete/) | Undelete a database | +| [update](/influxdb3/version/reference/cli/influxctl/database/update/) | Update a database | +| help, h | Output command help | + +## Flags + +| Flag | | Description | +| :--- | :------- | :------------------ | +| `-h` | `--help` | Output command help | diff --git a/content/shared/influxctl/database/create.md b/content/shared/influxctl/database/create.md new file mode 100644 index 000000000..ef1563a7b --- /dev/null +++ b/content/shared/influxctl/database/create.md @@ -0,0 +1,169 @@ + +The `influxctl database create` command creates a new database with a specified +retention period in an {{< product-name omit=" Clustered" >}} cluster. + +The retention period defines the maximum age of data retained in the database, +based on the timestamp of the data. +The retention period value is a time duration value made up of a numeric value +plus a duration unit. For example, `30d` means 30 days. +A zero duration retention period is infinite and data will not expire. +The retention period value cannot be negative or contain whitespace. + +{{< flex >}} +{{% flex-content "half" %}} + +##### Valid durations units include + +- **m**: minute +- **h**: hour +- **d**: day +- **w**: week +- **mo**: month +- **y**: year + +{{% /flex-content %}} +{{% flex-content "half" %}} + +##### Example retention period values + +- `0d`: infinite/none +- `3d`: 3 days +- `6w`: 6 weeks +- `1mo`: 1 month (30 days) +- `1y`: 1 year +- `30d30d`: 60 days +- `2.5d`: 60 hours + +{{% /flex-content %}} +{{< /flex >}} + +#### Custom partitioning + +You can override the default partition template (`%Y-%m-%d`) of the database +with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat` +flags when you create the database. +Provide a time format using [Rust strftime](/influxdb3/version/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values +into a specified number of "buckets." +Each of these can be used as part of the partition template. +Be sure to follow [partitioning best practices](/influxdb3/version/admin/custom-partitions/best-practices/). + +> [!Note] +> #### Always provide a time format when using custom partitioning +> +> If defining a custom partition template for your database with any of the +> `--template-*` flags, always include the `--template-timeformat` flag with a +> time format to use in your partition template. +> Otherwise, InfluxDB omits time from the partition template and won't compact partitions. + +> [!Warning] +> #### Wait before writing to a new database with the same name as a deleted database +> +> After deleting a database from your {{% product-name omit=" Clustered" %}} +> cluster, you can reuse the name to create a new database, but **wait two to +> three minutes** after deleting the previous database before writing to the new +> database to allow write caches to clear. + +## Usage + + + + +```sh +influxctl database create [flags] +``` + +## Arguments + +| Argument | Description | +| :---------------- | :--------------------- | +| **DATABASE_NAME** | InfluxDB database name | + +## Flags + +| Flag | | Description | +| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | +| | `--retention-period` | [Database retention period ](/influxdb3/version/admin/databases/#retention-periods)(default is `0s`, infinite) | +| | `--max-tables` | [Maximum tables per database](/influxdb3/version/admin/databases/#table-limit) (default is 500, `0` uses default) | +| | `--max-columns` | [Maximum columns per table](/influxdb3/version/admin/databases/#column-limit) (default is 250, `0` uses default) | +| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) | +| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) | +| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} + +## Examples + +- [Create a database with an infinite retention period](#create-a-database-with-an-infinite-retention-period) +- [Create a database with a 30-day retention period](#create-a-database-with-a-30-day-retention-period) +- [Create a database with non-default table and column limits](#create-a-database-with-non-default-table-and-column-limits) +- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template) + +### Create a database with an infinite retention period + + + + +```sh +influxctl database create mydb +``` + +### Create a database with a 30-day retention period + + + + +```sh +influxctl database create \ + --retention-period 30d \ + mydb +``` + +### Create a database with non-default table and column limits + + + + +```sh +influxctl database create \ + --max-tables 200 \ + --max-columns 150 \ + mydb +``` + +### Create a database with a custom partition template + +The following example creates a new `mydb` database and applies a partition +template that partitions by two tags (`room` and `sensor-type`) and by day using +the time format `%Y-%m-%d`: + + + + +```sh +influxctl database create \ + --template-tag room \ + --template-tag sensor-type \ + --template-tag-bucket customerID,1000 \ + --template-timeformat '%Y-%m-%d' \ + mydb +``` + +_For more information about custom partitioning, see +[Manage data partitioning](/influxdb3/version/admin/custom-partitions/)._ + +{{% expand "View command updates" %}} + +#### v2.7.0 {date="2024-03-26"} + +- Introduce the `--template-tag-bucket` flag to group tag values into buckets + and partition by each tag bucket. + +#### v2.5.0 {date="2024-03-04"} + +- Introduce the `--template-tag` and `--template-timeformat` flags that define + a custom partition template for a database. + +{{% /expand %}} diff --git a/content/shared/influxctl/database/delete.md b/content/shared/influxctl/database/delete.md new file mode 100644 index 000000000..bd9936066 --- /dev/null +++ b/content/shared/influxctl/database/delete.md @@ -0,0 +1,68 @@ + +The `influxctl database delete` command deletes a database from an +{{< product-name omit=" Clustered" >}} cluster. + +## Usage + + + + +```sh +influxctl database delete [command options] [--force] [...] +``` + +> [!Warning] +> #### Cannot be undone +> +> Deleting a database is a destructive action that cannot be undone. +> +> #### Wait before writing to a new database with the same name +> +> After deleting a database from your {{% product-name omit=" Clustered" %}} +> cluster, you can reuse the name to create a new database, but **wait two to +> three minutes** after deleting the previous database before writing to the new +> database to allow write caches to clear. +> +> #### Tokens still grant access to databases with the same name +> +> [Database tokens](/influxdb3/version/admin/tokens/database/) are associated to +> databases by name. If you create a new database with the same name, tokens +> that granted access to the deleted database will also grant access to the new +> database. + +## Arguments + +| Argument | Description | +| :---------------- | :----------------------------- | +| **DATABASE_NAME** | Name of the database to delete | + +## Flags + +| Flag | | Description | +| :--- | :-------- | :---------------------------------------------------------- | +| | `--force` | Do not prompt for confirmation to delete (default is false) | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} + +## Examples + +##### Delete a database named "mydb" + + + + +```sh +influxctl database delete mydb +``` + +##### Delete multiple databases + + + + +```sh +influxctl database delete mydb1 mydb2 +``` diff --git a/content/shared/influxctl/database/list.md b/content/shared/influxctl/database/list.md new file mode 100644 index 000000000..6315497d5 --- /dev/null +++ b/content/shared/influxctl/database/list.md @@ -0,0 +1,24 @@ + +The `influxctl database list` command lists all databases in an {{% product-name omit=" Clustered" %}} +cluster. + +The `--format` flag lets you print the output in other formats. +The `json` format is available for programmatic parsing by other tooling. +Default: `table`. + +## Usage + +```sh +influxctl database list [--format=table|json] +``` + +## Flags + +| Flag | | Description | +| :--- | :--------- | :-------------------------------------------- | +| | `--format` | Output format (`table` _(default)_ or `json`) | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxctl/database/rename.md b/content/shared/influxctl/database/rename.md new file mode 100644 index 000000000..834ac7207 --- /dev/null +++ b/content/shared/influxctl/database/rename.md @@ -0,0 +1,37 @@ + +The `influxctl database rename` command renames a database in an +{{% product-name omit=" Clustered" %}} cluster. +This command does _not_ change the database ID, database properties, or the +data stored in the database. + +> [!Warning] +> #### Renaming a database requires new tokens +> +> [Database tokens](/influxdb3/version/admin/tokens/database/) are associated to +> databases by name. After renaming a database, tokens referencing the old name +> no longer function. You must generate tokens for the new database name. + +## Usage + + + +```bash +influxctl database rename [flags] +``` + +## Arguments + +| Argument | Description | +| :------------------ | :--------------------------- | +| **CURRENT_DB_NAME** | Current name of the database | +| **NEW_DB_NAME** | New name for the database | + +## Flags + +| Flag | | Description | +| :--- | :--------- | :-------------------------------------------- | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxctl/database/undelete.md b/content/shared/influxctl/database/undelete.md new file mode 100644 index 000000000..ca539419e --- /dev/null +++ b/content/shared/influxctl/database/undelete.md @@ -0,0 +1,33 @@ + +The `influxctl database undelete` command undeletes a previously deleted +database in an {{% product-name omit=" Clustered" %}} cluster and restores the +database with the same retention period, table, and column limits as when it was +deleted. + +> [!Important] +> The database name must match the name of the deleted database and +> **a new database with the same name cannot exist**. + +## Usage + + + +```bash +influxctl database undelete [flags] +``` + +## Arguments + +| Argument | Description | +| :---------------- | :----------------------------------- | +| **DATABASE_NAME** | The name of the database to undelete | + +## Flags + +| Flag | | Description | +| :--- | :--------- | :-------------------------------------------- | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxctl/database/update.md b/content/shared/influxctl/database/update.md new file mode 100644 index 000000000..0612d6341 --- /dev/null +++ b/content/shared/influxctl/database/update.md @@ -0,0 +1,82 @@ + +The `influxctl database update` command updates a database's retention period, +table (measurement), or column limits in InfluxDB. + +## Usage + + + +```sh +influxctl database update [flags] +``` + +## Arguments + +| Argument | Description | +| :---------------- | :----------------------------- | +| **DATABASE_NAME** | Name of the database to update | + +## Flags + +| Flag | | Description | +| :--- | :------------------- | :--------------------------------------------------------------------------------------------------------------- | +| | `--retention-period` | [Database retention period ](/influxdb3/version/admin/databases/#retention-periods)(default is `0s` or infinite) | +| | `--max-tables` | [Maximum tables per database](/influxdb3/version/admin/databases/#table-limit) (default is 500, 0 uses default) | +| | `--max-columns` | [Maximum columns per table](/influxdb3/version/admin/databases/#column-limit) (default is 250, 0 uses default) | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} + +## Examples + +- [Update a database's retention period](#update-a-databases-retention-period) +- [Update a database's table limit](#update-a-databases-table-limit) +- [Update a database's column limit](#update-a-databases-column-limit) + +### Update a database's retention period + +```sh +influxctl database update --retention-period 1mo mydb +``` + +{{< flex >}} +{{% flex-content "half" %}} + +##### Valid durations units + +- `m`: minute +- `h`: hour +- `d`: day +- `w`: week +- `mo`: month +- `y`: year + +{{% /flex-content %}} +{{% flex-content "half" %}} + +##### Example retention period values + +- `0d`: infinite/none +- `3d`: 3 days +- `6w`: 6 weeks +- `1mo`: 1 month (30 days) +- `1y`: 1 year +- `30d30d`: 60 days +- `2.5d`: 60 hours + +{{% /flex-content %}} +{{< /flex >}} + +### Update a database's table limit + +```sh +influxctl database update --max-tables 300 mydb +``` + +### Update a database's column limit + +```sh +influxctl database update --max-columns 200 mydb +``` diff --git a/content/shared/influxctl/release-notes.md b/content/shared/influxctl/release-notes.md index 4e35c655a..288f6b6b9 100644 --- a/content/shared/influxctl/release-notes.md +++ b/content/shared/influxctl/release-notes.md @@ -1,3 +1,35 @@ +## v2.10.2 {date="2025-06-30"} + +### Features + +- Add new table management commands: + - [`influxctl table list`](/influxdb3/version/reference/cli/influxctl/table/list/) + - [`influxctl table delete`](/influxdb3/version/reference/cli/influxctl/table/delete/) + - [`influxctl table iceberg`](/influxdb3/version/reference/cli/influxctl/table/iceberg/) + - [`influxctl table iceberg enable`](/influxdb3/version/reference/cli/influxctl/table/iceberg/enable/) + - [`influxctl table iceberg disable`](/influxdb3/version/reference/cli/influxctl/table/iceberg/disable/) +- Add new database management commands: + - [`influxctl database rename`](/influxdb3/version/reference/cli/influxctl/database/rename/) + - [`influxctl database undelete`](/influxdb3/version/reference/cli/influxctl/database/undelete/) + +### Bug fixes + +- Ensure the `INFLUXCTL_PROFILE` environment variable overrides the default + connection profile file path. + +### Dependency updates + +- Update `github.com/apache/arrow-go/v18` from 18.3.0 to 18.3.1. +- Update `github.com/go-git/go-git/v5` from 5.16.0 to 5.16.2. +- Update `github.com/google/go-containerregistry` from 0.20.5 to 0.20.6. +- Update `github.com/urfave/cli/v2` from 2.27.6 to 2.27.7. +- Update `golang.org/x/mod` from 0.24.0 to 0.25.0. +- Update `google.golang.org/grpc` from 1.72.1 to 1.73.0. +- Update Go to 1.24.4. +- Update protobuf files. + +--- + ## v2.10.1 {date="2025-05-30"} ### Features diff --git a/content/shared/influxctl/table/_index.md b/content/shared/influxctl/table/_index.md new file mode 100644 index 000000000..1aa201434 --- /dev/null +++ b/content/shared/influxctl/table/_index.md @@ -0,0 +1,29 @@ + +The `influxctl table` command and its subcommands manage tables in an +{{% product-name omit=" Clustered" %}} cluster. + +## Usage + +```sh +influxctl table [subcommand] [flags] +``` + +## Subcommands + +| Subcommand | Description | +| :------------------------------------------------------------------- | :--------------------------------- | +| [create](/influxdb3/version/reference/cli/influxctl/table/create/) | Create a table | +| [delete](/influxdb3/version/reference/cli/influxctl/table/delete/) | Delete a table | +| [iceberg](/influxdb3/version/reference/cli/influxctl/table/iceberg/) | Manage iceberg exports for a table | +| [list](/influxdb3/version/reference/cli/influxctl/table/list/) | List tables | +| help, h | Output command help | + +## Flags + +| Flag | | Description | +| :--- | :------- | :------------------ | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxctl/table/create.md b/content/shared/influxctl/table/create.md new file mode 100644 index 000000000..0278d52d1 --- /dev/null +++ b/content/shared/influxctl/table/create.md @@ -0,0 +1,101 @@ + +The `influxctl table create` command creates a new table in the specified +database in an {{< product-name omit=" Clustered" >}} cluster. + +#### Custom partitioning + +You can override the default partition template (the partition template of the target database) +with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat` +flags when you create the table. +Provide a time format using [Rust strftime](/influxdb3/version/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values +into a specified number of "buckets." +Each of these can be used as part of the partition template. +Be sure to follow [partitioning best practices](/influxdb3/version/admin/custom-partitions/best-practices/). + +> [!Note] +> #### Always provide a time format when using custom partitioning +> +> If defining a custom partition template for your table with any of the +> `--template-*` flags, always include the `--template-timeformat` flag with a +> time format to use in your partition template. +> Otherwise, InfluxDB omits time from the partition template and won't compact partitions. + +## Usage + +```sh +influxctl table create [flags] +``` + +## Arguments + +| Argument | Description | +| :---------------- | :-------------------------- | +| **DATABASE_NAME** | Name of the target database | +| **TABLE_NAME** | Table name | + +## Flags + +| Flag | | Description | +| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | +| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) | +| | `--template-tag-bucket` | Tag and number of buckets to partition tag values into separated by a comma--for example: `tag1,100` (can include multiple of this flag) | +| | `--template-timeformat` | Timestamp format for partition template | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} + +## Examples + +- [Create a table](#create-a-table) +- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template) + +In the following examples, replace: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + The name of the database to create the table in. +- {{% code-placeholder-key %}}`TABLE_NAME` {{% /code-placeholder-key %}}: + The name of table to create. + +### Create a table + +{{% code-placeholders "(DATABASE|TABLE)_NAME" %}} +```sh +influxctl table create DATABASE_NAME TABLE_NAME +``` +{{% /code-placeholders %}} + +### Create a table with a custom partition template + +The following example creates a new table and applies a partition +template that partitions by two tags (`room` and `sensor-type`) and by day using +the time format `%Y-%m-%d`: + +{{% code-placeholders "(DATABASE|TABLE)_NAME" %}} +```sh +influxctl table create \ + --template-tag room \ + --template-tag sensor-type \ + --template-tag-bucket customerID,1000 \ + --template-timeformat '%Y-%m-%d' \ + DATABASE_NAME \ + TABLE_NAME +``` +{{% /code-placeholders %}} + +_For more information about custom partitioning, see +[Manage data partitioning](/influxdb3/version/admin/custom-partitions/)._ + +{{% expand "View command updates" %}} + +#### v2.7.0 {date="2024-03-26"} + +- Introduce the `--template-tag-bucket` flag to group tag values into buckets + and partition by each tag bucket. + +{{% /expand %}} + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxctl/table/delete.md b/content/shared/influxctl/table/delete.md new file mode 100644 index 000000000..b57532a49 --- /dev/null +++ b/content/shared/influxctl/table/delete.md @@ -0,0 +1,42 @@ + +The `influxctl table delete` command deletes a specified table from a database. + +## Usage + +```sh +influxctl table delete [flags] +``` + +## Arguments + +| Argument | Description | +| :---------------- | :---------------------- | +| **DATABASE_NAME** | Name of the database | +| **TABLE_NAME** | Name of table to delete | + +## Flags + +| Flag | | Description | +| :--- | :------- | :------------------ | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} + +## Examples + + + +{{% code-placeholders "(DATABASE|TABLE)_NAME" %}} +```bash +influxctl table delete DATABASE_NAME TABLE_NAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of the database to delete the table from +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: + the name of the table to delete diff --git a/content/shared/influxctl/table/iceberg/_index.md b/content/shared/influxctl/table/iceberg/_index.md new file mode 100644 index 000000000..b4d38aeb8 --- /dev/null +++ b/content/shared/influxctl/table/iceberg/_index.md @@ -0,0 +1,36 @@ + +The `influxctl table iceberg` command and its subcommands enable or disable +Iceberg-compatible exports for a table in an InfluxDB Cloud Dedicated cluster. + +{{% show-in "clustered" %}} +> [!Warning] +> #### Only available with InfluxDB Cloud Dedicated +> +> Iceberg-compatible exports are currently only available with InfluxDB Cloud +> Dedicated, not InfluxDB Clustered. `influxctl table iceberg` command and its +> subcommands can only be used with InfluxDB Cloud Dedicated. +{{% /show-in %}} + +## Usage + +```sh +influxctl table iceberg [subcommand] [flags] +``` + +## Subcommands + +| Subcommand | Description | +| :--------------------------------------------------------------------------- | :---------------------------------- | +| [enable](/influxdb3/version/reference/cli/influxctl/table/iceberg/enable/) | Enable Iceberg exports for a table | +| [disable](/influxdb3/version/reference/cli/influxctl/table/iceberg/disable/) | Disable Iceberg exports for a table | +| help, h | Output command help | + +## Flags + +| Flag | | Description | +| :--- | :------- | :------------------ | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxctl/table/iceberg/disable.md b/content/shared/influxctl/table/iceberg/disable.md new file mode 100644 index 000000000..a17cd81e4 --- /dev/null +++ b/content/shared/influxctl/table/iceberg/disable.md @@ -0,0 +1,35 @@ + +The `influxctl table iceberg disable` command disables Iceberg-compatible exports +for a table in an InfluxDB Cloud Dedicated cluster. + +{{% show-in "clustered" %}} +> [!Warning] +> #### Only available with InfluxDB Cloud Dedicated +> +> Iceberg-compatible exports are currently only available with InfluxDB Cloud +> Dedicated, not InfluxDB Clustered. The `influxctl table iceberg` command and +> its subcommands can only be used with InfluxDB Cloud Dedicated. +{{% /show-in %}} + +## Usage + +```sh +influxctl table iceberg disable [flags] +``` + +## Arguments + +| Argument | Description | +| :---------------- | :------------------------------------------ | +| **DATABASE_NAME** | Name of the target database | +| **TABLE_NAME** | Name of table to disable Iceberg exports on | + +## Flags + +| Flag | | Description | +| :--- | :------- | :------------------ | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxctl/table/iceberg/enable.md b/content/shared/influxctl/table/iceberg/enable.md new file mode 100644 index 000000000..baf4c6b46 --- /dev/null +++ b/content/shared/influxctl/table/iceberg/enable.md @@ -0,0 +1,35 @@ + +The `influxctl table iceberg enable` command enables Iceberg-compatible exports +for a table in an InfluxDB Cloud Dedicated cluster. + +{{% show-in "clustered" %}} +> [!Warning] +> #### Only available with InfluxDB Cloud Dedicated +> +> Iceberg-compatible exports are currently only available with InfluxDB Cloud +> Dedicated, not InfluxDB Clustered. The `influxctl table iceberg` command and +> its subcommands can only be used with InfluxDB Cloud Dedicated. +{{% /show-in %}} + +## Usage + +```sh +influxctl table iceberg enable [flags] +``` + +## Arguments + +| Argument | Description | +| :---------------- | :----------------------------------------- | +| **DATABASE_NAME** | Name of the target database | +| **TABLE_NAME** | Name of table to enable Iceberg exports on | + +## Flags + +| Flag | | Description | +| :--- | :------- | :------------------ | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxctl/table/list.md b/content/shared/influxctl/table/list.md new file mode 100644 index 000000000..b839ebfb8 --- /dev/null +++ b/content/shared/influxctl/table/list.md @@ -0,0 +1,26 @@ + +The `influxctl table list` command lists all tables in the specified database in +an {{< product-name omit=" Clustered" >}} cluster. + +## Usage + +```sh +influxctl table list [flags] +``` + +## Arguments + +| Argument | Description | +| :---------------- | :-------------------------- | +| **DATABASE_NAME** | Name of the target database | + +## Flags + +| Flag | | Description | +| :--- | :--------- | :-------------------------------------------- | +| | `--format` | Output format (`table` _(default)_ or `json`) | +| `-h` | `--help` | Output command help | + +{{% caption %}} +_Also see [`influxctl` global flags](/influxdb3/version/reference/cli/influxctl/#global-flags)._ +{{% /caption %}} diff --git a/content/shared/influxdb3-admin/databases/create.md b/content/shared/influxdb3-admin/databases/create.md index a8cd0f8fe..76f6cc699 100644 --- a/content/shared/influxdb3-admin/databases/create.md +++ b/content/shared/influxdb3-admin/databases/create.md @@ -4,10 +4,7 @@ to create a database in {{< product-name >}}. Provide the following: - Database name _(see [Database naming restrictions](#database-naming-restrictions))_ -- {{< product-name >}} authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. +- {{< product-name >}} {{% token-link "admin" "admin" %}} diff --git a/content/shared/influxdb3-admin/databases/delete.md b/content/shared/influxdb3-admin/databases/delete.md index 9e3354967..80190b2c1 100644 --- a/content/shared/influxdb3-admin/databases/delete.md +++ b/content/shared/influxdb3-admin/databases/delete.md @@ -11,10 +11,7 @@ to delete a database from {{< product-name >}}. Provide the following: - Name of the database to delete -- {{< product-name >}} authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. +- - {{< product-name >}} {{% token-link "admin" "admin" %}} {{% code-placeholders "DATABASE_NAME" %}} ```sh diff --git a/content/shared/influxdb3-admin/databases/list.md b/content/shared/influxdb3-admin/databases/list.md index 109f09d94..1954dcb48 100644 --- a/content/shared/influxdb3-admin/databases/list.md +++ b/content/shared/influxdb3-admin/databases/list.md @@ -6,10 +6,7 @@ Provide the following: - _(Optional)_ [Output format](#output-formats) with the `--format` option - _(Optional)_ [Show deleted databases](list-deleted-databasese) with the `--show-deleted` option - - {{< product-name >}} authorization token with the `-t`, `--token` option - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. + - {{< product-name >}} {{% token-link "admin" "admin" %}} with the `-t`, `--token` option ```sh influxdb3 show databases diff --git a/content/shared/influxdb3-admin/query-system-data/_index.md b/content/shared/influxdb3-admin/query-system-data/_index.md index 508cdc34b..c3ef83994 100644 --- a/content/shared/influxdb3-admin/query-system-data/_index.md +++ b/content/shared/influxdb3-admin/query-system-data/_index.md @@ -93,7 +93,7 @@ that surround field names._ ```bash curl "http://localhost:8181/api/v3/query_sql" \ - --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "mydb", "q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'", @@ -120,7 +120,7 @@ To view recently executed queries, query the `queries` system table: ```bash curl "http://localhost:8181/api/v3/query_sql" \ - --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" --json '{ "db": "mydb", "q": "SELECT * FROM system.queries LIMIT 2", diff --git a/content/shared/influxdb3-admin/tokens/_index.md b/content/shared/influxdb3-admin/tokens/_index.md index 2ab0675ae..b2591ef98 100644 --- a/content/shared/influxdb3-admin/tokens/_index.md +++ b/content/shared/influxdb3-admin/tokens/_index.md @@ -12,7 +12,7 @@ The mechanism for providing your token depends on the client you use to interact {{< tabs-wrapper >}} {{% tabs %}} [influxdb3 CLI](#influxdb3-cli-auth) -[cURL](#curl-auth) +[HTTP API](#http-api-auth) {{% /tabs %}} {{% tab-content %}} @@ -49,6 +49,12 @@ authorization token to all `influxdb3` commands. {{% /tab-content %}} {{% tab-content %}} +To authenticate directly to the HTTP API, you can include your authorization token in the HTTP Authorization header of your request. +The `Authorization: Bearer AUTH_TOKEN` scheme works with all HTTP API endpoints that require authentication. + +The following examples use `curl` to show to authenticate to the HTTP API. + + {{% code-placeholders "YOUR_AUTH_TOKEN" %}} ```bash # Add your token to the HTTP Authorization header @@ -57,14 +63,46 @@ curl "http://{{< influxdb/host >}}/api/v3/query_sql" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM 'DATABASE_NAME' WHERE time > now() - INTERVAL '10 minutes'" ``` -{{% /code-placeholders %}} +### Authenticate using v1 and v2 compatibility + +```bash +# Token scheme with v2 /api/v2/write +curl http://localhost:8181/api/v2/write\?bucket\=DATABASE_NAME \ + --header "Authorization: Token YOUR_AUTH_TOKEN" \ + --data-raw "home,room=Kitchen temp=23.5 1622547800" +``` + +```bash +# Basic scheme with v1 /write +# Username is ignored, but required for the request +# Password is your auth token encoded in base64 +curl "http://localhost:8181/write?db=DATABASE_NAME" \ + --user "admin:YOUR_AUTH_TOKEN" \ + --data-raw "home,room=Kitchen temp=23.5 1622547800" +``` + +```bash +# URL auth parameters with v1 /write +# Username is ignored, but required for the request +curl "http://localhost:8181/write?db=DATABASE_NAME&u=admin&p=YOUR_AUTH_TOKEN" \ + --data-raw "home,room=Kitchen temp=23.5 1622547800" +``` +{{% /code-placeholders %}} {{% /tab-content %}} {{< /tabs-wrapper >}} Replace the following with your values: - {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link %}} -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database you want to query +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases) you want to query + +To use tokens with other clients for {{< product-name >}}, +see the client-specific documentation: + +- [InfluxDB 3 Explorer](/influxdb3/explorer/) +- [InfluxDB client libraries](/influxdb3/version/reference/client-libraries/) +- [Telegraf](/telegraf/v1/) +- [Grafana](/influxdb3/version/visualize-data/grafana/) {{< children hlevel="h2" readmore=true hr=true >}} diff --git a/content/shared/influxdb3-cli/create/_index.md b/content/shared/influxdb3-cli/create/_index.md index 3c9fa9ae2..a01afe2a7 100644 --- a/content/shared/influxdb3-cli/create/_index.md +++ b/content/shared/influxdb3-cli/create/_index.md @@ -12,6 +12,7 @@ influxdb3 create ## Subcommands +{{% show-in "enterprise" %}} | Subcommand | Description | | :---------------------------------------------------------------------------------- | :---------------------------------------------- | | [database](/influxdb3/version/reference/cli/influxdb3/create/database/) | Create a new database | @@ -22,6 +23,19 @@ influxdb3 create | [token](/influxdb3/version/reference/cli/influxdb3/create/token/) | Create a new authentication token | | [trigger](/influxdb3/version/reference/cli/influxdb3/create/trigger/) | Create a new trigger for the processing engine | | help | Print command help or the help of a subcommand | +{{% /show-in %}} + +{{% show-in "core" %}} +| Subcommand | Description | +| :---------------------------------------------------------------------------------- | :---------------------------------------------- | +| [database](/influxdb3/version/reference/cli/influxdb3/create/database/) | Create a new database | +| [last_cache](/influxdb3/version/reference/cli/influxdb3/create/last_cache/) | Create a new last value cache | +| [distinct_cache](/influxdb3/version/reference/cli/influxdb3/create/distinct_cache/) | Create a new distinct value cache | +| [table](/influxdb3/version/reference/cli/influxdb3/create/table/) | Create a new table in a database | +| [token](/influxdb3/version/reference/cli/influxdb3/create/token/) | Create a new authentication token | +| [trigger](/influxdb3/version/reference/cli/influxdb3/create/trigger/) | Create a new trigger for the processing engine | +| help | Print command help or the help of a subcommand | +{{% /show-in %}} ## Options diff --git a/content/shared/influxdb3-cli/create/database.md b/content/shared/influxdb3-cli/create/database.md index 630546c14..30c9c78eb 100644 --- a/content/shared/influxdb3-cli/create/database.md +++ b/content/shared/influxdb3-cli/create/database.md @@ -19,13 +19,14 @@ You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environme ## Options -| Option | | Description | -| :----- | :----------- | :--------------------------------------------------------------------------------------- | -| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | -| | `--token` | Authentication token | -| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | -| `-h` | `--help` | Print help information | -| | `--help-all` | Print detailed help information | +| Option | | Description | +| :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| | `--retention-period` | Database [retention period](/influxdb3/version/reference/glossary/#retention-period) ([duration](/influxdb3/version/reference/glossary/#duration) value, for example: `30d`, `24h`, `1h`) | +| | `--token` | Authentication token | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | ### Option environment variables @@ -69,4 +70,14 @@ Flags override their associated environment variables. influxdb3 create database --token AUTH_TOKEN DATABASE_NAME ``` +### Create a database with a retention period + +Creates a database with a specific retention period. + + + +```bash +influxdb3 create database --retention-period 30d DATABASE_NAME +``` + {{% /code-placeholders %}} diff --git a/content/shared/influxdb3-cli/create/table.md b/content/shared/influxdb3-cli/create/table.md index e3b858970..79c4e9ce9 100644 --- a/content/shared/influxdb3-cli/create/table.md +++ b/content/shared/influxdb3-cli/create/table.md @@ -24,6 +24,7 @@ influxdb3 create table [OPTIONS] \ ## Options +{{% hide-in "enterprise" %}} | Option | | Description | | :----- | :----------- | :--------------------------------------------------------------------------------------- | | `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | @@ -34,6 +35,22 @@ influxdb3 create table [OPTIONS] \ | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | +{{% /hide-in %}} + + +{{% show-in "enterprise" %}} +| Option | | Description | +| :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| `-d` | `--database` | _({{< req >}})_ Name of the database to operate on | +| | `--retention-period` | [Retention period](/influxdb3/version/reference/glossary/#retention-period) ([duration](/influxdb3/version/reference/glossary/#duration) value, for example: `30d`, `24h`, `1h`) for data in the table| +| | `--token` | _({{< req >}})_ Authentication token | +| | `--tags` | _({{< req >}})_ Comma-separated list of tag columns to include in the table | +| | `--fields` | Comma-separated list of field columns and their types to include in the table | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | +{{% /show-in %}} > [!Important] > @@ -90,6 +107,22 @@ influxdb3 create table \ TABLE_NAME ``` +{{% show-in "enterprise" %}} +### Create a table with a retention period + + + +```bash +influxdb3 create table \ + --tags room,sensor_id \ + --fields temp:float64,hum:float64 \ + --retention-period 7d \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + TABLE_NAME +``` +{{% /show-in %}} + ### Verification Use the `SHOW TABLES` query to verify that the table was created successfully: @@ -114,7 +147,7 @@ Example output: +---------------+--------------------+----------------------------+------------+ ``` ->[!Note] +> [!Note] > `SHOW TABLES` is an SQL query. It isn't supported in InfluxQL. {{% /code-placeholders %}} diff --git a/content/shared/influxdb3-cli/create/trigger.md b/content/shared/influxdb3-cli/create/trigger.md index dbb223128..baaadd91c 100644 --- a/content/shared/influxdb3-cli/create/trigger.md +++ b/content/shared/influxdb3-cli/create/trigger.md @@ -27,7 +27,7 @@ influxdb3 create trigger [OPTIONS] \ | `-d` | `--database` | _({{< req >}})_ Name of the database to operate on | | | `--token` | _({{< req >}})_ Authentication token | | | `--plugin-filename` | _({{< req >}})_ Name of the file, stored in the server's `plugin-dir`, that contains the Python plugin code to run | -| | `--trigger-spec` | Trigger specification--for example `table:` or `all_tables` | +| | `--trigger-spec` | Trigger specification: `table:`, `all_tables`, `every:`, `cron:`, or `request:` | | | `--disabled` | Create the trigger in disabled state | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | `-h` | `--help` | Print help information | @@ -113,3 +113,15 @@ influxdb3 create trigger \ Creating a trigger in a disabled state prevents it from running immediately. You can enable it later when you're ready to activate it. {{% /code-placeholders %}} + +{{% show-in "enterprise" %}} +> [!Warning] +> #### Request trigger specification format differs between CLI and API +> +> Due to a bug in InfluxDB 3 Enterprise, the request trigger specification format differs: +> +> - **CLI**: `request:` (same as Core CLI and API) +> - **Enterprise API**: `{"request_path": {"path": ""}}` +> +> See the [API reference](/influxdb3/enterprise/api/#operation/PostConfigureProcessingEngineTrigger) for examples. Use `influxdb3 show summary` to verify the actual trigger specification. +{{% /show-in %}} diff --git a/content/shared/influxdb3-cli/delete/_index.md b/content/shared/influxdb3-cli/delete/_index.md index 569b87904..81a47ffc6 100644 --- a/content/shared/influxdb3-cli/delete/_index.md +++ b/content/shared/influxdb3-cli/delete/_index.md @@ -11,16 +11,28 @@ influxdb3 delete ## Subcommands -| Subcommand | Description | -| :----------------------------------------------------------------------------- | :--------------------------------------------- | -| [database](/influxdb3/version/reference/cli/influxdb3/delete/database/) | Delete a database | -| [file_index](/influxdb3/version/reference/cli/influxdb3/delete/file_index/) | Delete a file index for a database or table | -| [last_cache](/influxdb3/version/reference/cli/influxdb3/delete/last_cache/) | Delete a last value cache | +{{% show-in "enterprise" %}} +| Subcommand | Description | +| :---------------------------------------------------------------------------------- | :--------------------------------------------- | +| [database](/influxdb3/version/reference/cli/influxdb3/delete/database/) | Delete a database | +| [file_index](/influxdb3/version/reference/cli/influxdb3/delete/file_index/) | Delete a file index for a database or table | +| [last_cache](/influxdb3/version/reference/cli/influxdb3/delete/last_cache/) | Delete a last value cache | | [distinct_cache](/influxdb3/version/reference/cli/influxdb3/delete/distinct_cache/) | Delete a metadata cache | -| [plugin](/influxdb3/version/reference/cli/influxdb3/delete/plugin/) | Delete a processing engine plugin | -| [table](/influxdb3/version/reference/cli/influxdb3/delete/table/) | Delete a table from a database | -| [trigger](/influxdb3/version/reference/cli/influxdb3/delete/trigger/) | Delete a trigger for the processing engine | -| help | Print command help or the help of a subcommand | +| [table](/influxdb3/version/reference/cli/influxdb3/delete/table/) | Delete a table from a database | +| [trigger](/influxdb3/version/reference/cli/influxdb3/delete/trigger/) | Delete a trigger for the processing engine | +| help | Print command help or the help of a subcommand | +{{% /show-in %}} + +{{% show-in "core" %}} +| Subcommand | Description | +| :---------------------------------------------------------------------------------- | :--------------------------------------------- | +| [database](/influxdb3/version/reference/cli/influxdb3/delete/database/) | Delete a database | +| [last_cache](/influxdb3/version/reference/cli/influxdb3/delete/last_cache/) | Delete a last value cache | +| [distinct_cache](/influxdb3/version/reference/cli/influxdb3/delete/distinct_cache/) | Delete a metadata cache | +| [table](/influxdb3/version/reference/cli/influxdb3/delete/table/) | Delete a table from a database | +| [trigger](/influxdb3/version/reference/cli/influxdb3/delete/trigger/) | Delete a trigger for the processing engine | +| help | Print command help or the help of a subcommand | +{{% /show-in %}} ## Options diff --git a/content/shared/influxdb3-cli/delete/database.md b/content/shared/influxdb3-cli/delete/database.md index 6d675b414..14e1d4817 100644 --- a/content/shared/influxdb3-cli/delete/database.md +++ b/content/shared/influxdb3-cli/delete/database.md @@ -17,13 +17,14 @@ influxdb3 delete database [OPTIONS] ## Options -| Option | | Description | -| :----- | :----------- | :--------------------------------------------------------------------------------------- | -| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | -| | `--token` | Authentication token | -| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | -| `-h` | `--help` | Print help information | -| | `--help-all` | Print detailed help information | +| Option | | Description | +| :----- | :------------ | :--------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| | `--hard-delete` | When to hard delete data (never/now/default/timestamp). Default behavior is a soft delete that allows recovery | +| | `--token` | Authentication token | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | ### Option environment variables @@ -36,8 +37,10 @@ You can use the following environment variables to set command options: ## Examples -- [Delete a database](#delete-a-new-database) -- [Delete a database while specifying the token inline](#delete-a-new-database-while-specifying-the-token-inline) +- [Delete a database](#delete-a-database) +- [Delete a database while specifying the token inline](#delete-a-database-while-specifying-the-token-inline) +- [Hard delete a database immediately](#hard-delete-a-database-immediately) +- [Hard delete a database at a specific time](#hard-delete-a-database-at-a-specific-time) In the examples below, replace the following: @@ -64,4 +67,24 @@ influxdb3 delete database DATABASE_NAME influxdb3 delete database --token AUTH_TOKEN DATABASE_NAME ``` +### Hard delete a database immediately + +Permanently delete a database and all its data immediately without the ability to recover. + + + +```bash +influxdb3 delete database --hard-delete now DATABASE_NAME +``` + +### Hard delete a database at a specific time + +Schedule a database for permanent deletion at a specific timestamp. + + + +```bash +influxdb3 delete database --hard-delete "2024-01-01T00:00:00Z" DATABASE_NAME +``` + {{% /code-placeholders %}} diff --git a/content/shared/influxdb3-cli/delete/table.md b/content/shared/influxdb3-cli/delete/table.md index c15674071..c96178345 100644 --- a/content/shared/influxdb3-cli/delete/table.md +++ b/content/shared/influxdb3-cli/delete/table.md @@ -15,14 +15,15 @@ influxdb3 delete table [OPTIONS] --database ## Options -| Option | | Description | -| :----- | :----------- | :--------------------------------------------------------------------------------------- | -| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | -| `-d` | `--database` | _({{< req >}})_ Name of the database to operate on | -| | `--token` | _({{< req >}})_ Authentication token | -| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | -| `-h` | `--help` | Print help information | -| | `--help-all` | Print detailed help information | +| Option | | Description | +| :----- | :------------ | :--------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| `-d` | `--database` | _({{< req >}})_ Name of the database to operate on | +| | `--hard-delete` | When to hard delete data (never/now/default/timestamp). Default behavior is a soft delete that allows recovery | +| | `--token` | _({{< req >}})_ Authentication token | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | ### Option environment variables @@ -49,9 +50,23 @@ influxdb3 delete table \ TABLE_NAME ``` +### Hard delete a table immediately + +Permanently delete a table and all its data immediately without the ability to recover. + + + +```bash +influxdb3 delete table \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + --hard-delete now \ + TABLE_NAME +``` + {{% /code-placeholders %}} -In the example above, replace the following: +Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Database name diff --git a/content/shared/influxdb3-cli/show/_index.md b/content/shared/influxdb3-cli/show/_index.md index 4a5bbf935..eea02dcf0 100644 --- a/content/shared/influxdb3-cli/show/_index.md +++ b/content/shared/influxdb3-cli/show/_index.md @@ -14,6 +14,7 @@ influxdb3 show | Subcommand | Description | | :---------------------------------------------------------------------- | :--------------------------------------------- | | [databases](/influxdb3/version/reference/cli/influxdb3/show/databases/) | List database | +{{% show-in "enterprise" %}}| [license](/influxdb3/version/reference/cli/influxdb3/show/license/) | Display license information |{{% /show-in %}} | [system](/influxdb3/version/reference/cli/influxdb3/show/system/) | Display system table data | | [tokens](/influxdb3/version/reference/cli/influxdb3/show/tokens/) | List authentication tokens | | help | Print command help or the help of a subcommand | diff --git a/content/shared/influxdb3-cli/update/_index.md b/content/shared/influxdb3-cli/update/_index.md new file mode 100644 index 000000000..afe2a22db --- /dev/null +++ b/content/shared/influxdb3-cli/update/_index.md @@ -0,0 +1,33 @@ +The `influxdb3 update` command updates resources such as databases and tables. + +## Usage + + + +```bash +influxdb3 update +``` + +## Subcommands + +{{% show-in "enterprise" %}} +| Subcommand | Description | +| :----------------------------------------------------------------- | :--------------------- | +| [database](/influxdb3/version/reference/cli/influxdb3/update/database/) | Update a database | +| [table](/influxdb3/version/reference/cli/influxdb3/update/table/) | Update a table | +| help | Print command help or the help of a subcommand | +{{% /show-in %}} + +{{% show-in "core" %}} +| Subcommand | Description | +| :----------------------------------------------------------------- | :--------------------- | +| [database](/influxdb3/version/reference/cli/influxdb3/update/database/) | Update a database | +| help | Print command help or the help of a subcommand | +{{% /show-in %}} + +## Options + +| Option | | Description | +| :----- | :----------- | :------------------------------ | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | \ No newline at end of file diff --git a/content/shared/influxdb3-cli/update/database/_index.md b/content/shared/influxdb3-cli/update/database/_index.md new file mode 100644 index 000000000..a292283a4 --- /dev/null +++ b/content/shared/influxdb3-cli/update/database/_index.md @@ -0,0 +1,84 @@ +The `influxdb3 update database` command updates an existing database in your {{< product-name >}} instance. + +Use this command to update a database's retention period. + +## Usage + + + +```bash +influxdb3 update database [OPTIONS] --database +``` + +## Arguments + +- **`DATABASE_NAME`**: (Required) The name of the database to update. + +You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environment variable. + +## Options + +| Option | | Description | +| :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| `-d` | `--database` | The name of the database to update | +| | `--token` | Authentication token | +| `-r` | `--retention-period` | The retention period as a [duration](/influxdb3/version/reference/glossary/#duration) value (for example: `30d`, `24h`) or `none` to clear | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | + +### Option environment variables + +You can use the following environment variables instead of providing CLI options directly: + +| Environment Variable | Option | +| :------------------------ | :----------- | +| `INFLUXDB3_HOST_URL` | `--host` | +| `INFLUXDB3_DATABASE_NAME` | `--database` | +| `INFLUXDB3_AUTH_TOKEN` | `--token` | +| `INFLUXDB3_TLS_CA` | `--tls-ca` | + +## Examples + +The following examples show how to update a database. + +In your commands replace the following: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Database name +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + Authentication token + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} + +### Update a database retention period + +Updates a database retention period to 30 days. + + + +```bash +influxdb3 update database --retention-period 30d DATABASE_NAME +``` + +### Clear a database retention period + +Removes the retention period from a database by setting it to `none`. + + + +```bash +influxdb3 update database --retention-period none DATABASE_NAME +``` + +### Update a database with authentication + +Updates a database using an authentication token. + + + +```bash +influxdb3 update database --token AUTH_TOKEN --retention-period 7d DATABASE_NAME +``` + +{{% /code-placeholders %}} \ No newline at end of file diff --git a/content/shared/influxdb3-cli/update/table/_index.md b/content/shared/influxdb3-cli/update/table/_index.md new file mode 100644 index 000000000..928ca8573 --- /dev/null +++ b/content/shared/influxdb3-cli/update/table/_index.md @@ -0,0 +1,74 @@ +The `influxdb3 update table` command updates an existing table in a database in your {{< product-name >}} instance. + +Use this command to update a table's retention period. + +## Usage + + + +```bash +influxdb3 update table [OPTIONS] --database +``` + +## Arguments + +- **`TABLE_NAME`**: (Required) The name of the table to update + +## Options + +| Option | | Description | +| :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| `-d` | `--database` | The name of the database containing the table | +| | `--token` | Authentication token | +| `-r` | `--retention-period` | The retention period as a [duration](/influxdb3/version/reference/glossary/#duration) value (for example: `30d`, `24h`) or `none` to clear | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | + +### Option environment variables + +You can use the following environment variables instead of providing CLI options directly: + +| Environment Variable | Option | +| :------------------------ | :----------- | +| `INFLUXDB3_HOST_URL` | `--host` | +| `INFLUXDB3_DATABASE_NAME` | `--database` | +| `INFLUXDB3_AUTH_TOKEN` | `--token` | +| `INFLUXDB3_TLS_CA` | `--tls-ca` | + +## Examples + +The following examples show how to update a table. + +In your commands replace the following: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Database name +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: + Table name +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + Authentication token + +{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}} + +### Update a table retention period + +Updates a table retention period to 30 days. + + + +```bash +influxdb3 update table --database DATABASE_NAME --token AUTH_TOKEN --retention-period 30d TABLE_NAME +``` + +### Clear a table retention period + +Removes the retention period from a table by setting it to `none`. + + + +```bash +influxdb3 update table --database DATABASE_NAME --retention-period none TABLE_NAME +``` + +{{% /code-placeholders %}} \ No newline at end of file diff --git a/content/shared/influxdb3-get-started/_index.md b/content/shared/influxdb3-get-started/_index.md index f53da9c7d..c5a7f60dc 100644 --- a/content/shared/influxdb3-get-started/_index.md +++ b/content/shared/influxdb3-get-started/_index.md @@ -1,26 +1,8 @@ +This guide walks through the basic steps of getting started with {{% product-name %}}, +including the following: -### What's in this guide - -{{% show-in "enterprise" %}} -This guide covers Enterprise as well as InfluxDB 3 Core, including the following topics: -{{% /show-in %}} -{{% show-in "core" %}} -This guide covers InfluxDB 3 Core (the open source release), including the following topics: -{{% /show-in %}} - -- [Install and startup](#install-and-startup) -- [Authentication and authorization](#authentication-and-authorization) -- [Data Model](#data-model) -- [Tools to use](#tools-to-use) -- [Write data](#write-data) -- [Query data](#query-data) -- [Last values cache](#last-values-cache) -- [Distinct values cache](#distinct-values-cache) -- [Python plugins and the processing engine](#python-plugins-and-the-processing-engine) -{{% show-in "enterprise" %}} -- [Multi-server setups](#multi-server-setup) -{{% /show-in %}} +{{< children type="ordered-list" >}} > [!Tip] > #### Find support for {{% product-name %}} @@ -28,1686 +10,64 @@ This guide covers InfluxDB 3 Core (the open source release), including the follo > The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for {{% product-name %}}. > For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options. -### Install and startup - -{{% product-name %}} runs on **Linux**, **macOS**, and **Windows**. - -{{% show-in "enterprise" %}} -{{% tabs-wrapper %}} -{{% tabs %}} -[Linux or macOS](#linux-or-macos) -[Windows](#windows) -[Docker](#docker) -{{% /tabs %}} -{{% tab-content %}} - -To get started quickly, download and run the install script--for example, using [curl](https://curl.se/download.html): - - -```bash -curl -O https://www.influxdata.com/d/install_influxdb3.sh \ -&& sh install_influxdb3.sh enterprise -``` - -Or, download and install [build artifacts](/influxdb3/enterprise/install/#download-influxdb-3-enterprise-binaries): - -- [Linux | AMD64 (x86_64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz) - • - [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz.sha256) -- [Linux | ARM64 (AArch64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz) - • - [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz.sha256) -- [macOS | Silicon (ARM64)](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz) - • - [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz.sha256) - -> [!Note] -> macOS Intel builds are coming soon. - - -{{% /tab-content %}} -{{% tab-content %}} - -Download and install the {{% product-name %}} [Windows (AMD64, x86_64) binary](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip) - • -[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip.sha256) - -{{% /tab-content %}} -{{% tab-content %}} - - -The [`influxdb:3-enterprise` image](https://hub.docker.com/_/influxdb/tags?tag=3-core&name=3-enterprise) -is available for x86_64 (AMD64) and ARM64 architectures. - -Pull the image: - - -```bash -docker pull influxdb:3-enterprise -``` - - -{{% /tab-content %}} -{{% /tabs-wrapper %}} -{{% /show-in %}} - -{{% show-in "core" %}} -{{% tabs-wrapper %}} -{{% tabs %}} -[Linux or macOS](#linux-or-macos) -[Windows](#windows) -[Docker](#docker) -{{% /tabs %}} -{{% tab-content %}} - -To get started quickly, download and run the install script--for example, using [curl](https://curl.se/download.html): - - -```bash -curl -O https://www.influxdata.com/d/install_influxdb3.sh \ -&& sh install_influxdb3.sh -``` -Or, download and install [build artifacts](/influxdb3/core/install/#download-influxdb-3-core-binaries): - -- [Linux | AMD64 (x86_64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz) - • - [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz.sha256) -- [Linux | ARM64 (AArch64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz) - • - [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz.sha256) -- [macOS | Silicon (ARM64)](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz) - • - [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz.sha256) - -> [!Note] -> macOS Intel builds are coming soon. - - -{{% /tab-content %}} -{{% tab-content %}} - -Download and install the {{% product-name %}} [Windows (AMD64, x86_64) binary](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip) - • -[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip.sha256) - -{{% /tab-content %}} -{{% tab-content %}} - -The [`influxdb:3-core` image](https://hub.docker.com/_/influxdb/tags?tag=3-core&name=3-core) -is available for x86_64 (AMD64) and ARM64 architectures. - -Pull the image: - - -```bash -docker pull influxdb:3-core -``` - - -{{% /tab-content %}} -{{% /tabs-wrapper %}} -{{% /show-in %}} - -_Build artifacts and images update with every merge into the {{% product-name %}} `main` branch._ - -#### Verify the install - -After you have installed {{% product-name %}}, enter the following command to verify that it completed successfully: - -```bash -influxdb3 --version -``` - -If your system doesn't locate `influxdb3`, then `source` the configuration file (for example, .bashrc, .zshrc) for your shell--for example: - - -```zsh -source ~/.zshrc -``` - - -#### Start InfluxDB - -To start your InfluxDB instance, use the `influxdb3 serve` command and provide the following: - -- `--object-store`: Specifies the type of object store to use. - InfluxDB supports the following: local file system (`file`), `memory`, - S3 (and compatible services like Ceph or Minio) (`s3`), - Google Cloud Storage (`google`), and Azure Blob Storage (`azure`). - The default is `file`. - Depending on the object store type, you may need to provide additional options - for your object store configuration. -{{% 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: `//`. In a multi-node setup, this ID is used to reference specific nodes. -- `--cluster-id`: A string identifier that determines part of the storage path hierarchy. All nodes within the same cluster share this identifier. 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 %}} - -The following examples show how to start {{% product-name %}} with different object store configurations. - -> [!Note] -> #### Diskless architecture -> -> InfluxDB 3 supports a diskless architecture that can operate with object -> storage alone, eliminating the need for locally attached disks. -> {{% product-name %}} can also work with only local disk storage when needed. - -{{% show-in "enterprise" %}} -> [!Note] -> The combined path structure `//` ensures proper organization of data in your object store, allowing for clean separation between clusters and individual nodes. -{{% /show-in %}} - -##### Filesystem object store - -Store data in a specified directory on the local filesystem. -This is the default object store type. - -Replace the following with your values: - -{{% show-in "enterprise" %}} -```bash -# Filesystem 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 %}} - -To run the [Docker image](/influxdb3/version/install/#docker-image) and persist data to the file system, mount a volume for the object store-for example, pass the following options: - -- `-v /path/on/host:/path/in/container`: Mounts a directory from your file system to the container -- `--object-store file --data-dir /path/in/container`: Uses the mount for server storage - - -{{% show-in "enterprise" %}} - -```bash -# File system object store with Docker -# Create a mount -# Provide the mount path -docker run -it \ - -v /path/on/host:/path/in/container \ - influxdb:3-enterprise influxdb3 serve \ - --node-id my_host \ - --cluster-id my_cluster \ - --object-store file \ - --data-dir /path/in/container -``` -{{% /show-in %}} -{{% show-in "core" %}} - -```bash -# File system object store with Docker -# Create a mount -# Provide the mount path -docker run -it \ - -v /path/on/host:/path/in/container \ - influxdb:3-core influxdb3 serve \ - --node-id my_host \ - --object-store file \ - --data-dir /path/in/container -``` -{{% /show-in %}} - -> [!Note] -> -> The {{% product-name %}} Docker image exposes port `8181`, the `influxdb3` server default for HTTP connections. -> To map the exposed port to a different port when running a container, see the Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/). - -##### S3 object store - -Store data in an S3-compatible object store. -This is useful for production deployments that require high availability and durability. -Provide your bucket name and credentials to access the S3 object store. - -{{% show-in "enterprise" %}} -```bash -# S3 object store (default is the us-east-1 region) -# Specify the object store type and associated options -influxdb3 serve \ - --node-id host01 \ - --cluster-id cluster01 \ - --object-store s3 \ - --bucket OBJECT_STORE_BUCKET \ - --aws-access-key AWS_ACCESS_KEY_ID \ - --aws-secret-access-key AWS_SECRET_ACCESS_KEY -``` - - -```bash -# Minio or other open source object store -# (using the AWS S3 API with additional parameters) -# Specify the object store type and associated options -influxdb3 serve \ - --node-id host01 \ - --cluster-id cluster01 \ - --object-store s3 \ - --bucket OBJECT_STORE_BUCKET \ - --aws-access-key-id AWS_ACCESS_KEY_ID \ - --aws-secret-access-key AWS_SECRET_ACCESS_KEY \ - --aws-endpoint ENDPOINT \ - --aws-allow-http -``` -{{% /show-in %}} -{{% show-in "core" %}} -```bash -# S3 object store (default is the us-east-1 region) -# Specify the object store type and associated options -influxdb3 serve \ - --node-id host01 \ - --object-store s3 \ - --bucket OBJECT_STORE_BUCKET \ - --aws-access-key AWS_ACCESS_KEY_ID \ - --aws-secret-access-key AWS_SECRET_ACCESS_KEY -``` - -```bash -# Minio or other open source object store -# (using the AWS S3 API with additional parameters) -# Specify the object store type and associated options -influxdb3 serve \ - --node-id host01 \ - --object-store s3 \ - --bucket OBJECT_STORE_BUCKET \ - --aws-access-key-id AWS_ACCESS_KEY_ID \ - --aws-secret-access-key AWS_SECRET_ACCESS_KEY \ - --aws-endpoint ENDPOINT \ - --aws-allow-http -``` -{{% /show-in %}} - -#### Memory object store - -Store data in RAM without persisting it on shutdown. -It's useful for rapid testing and development. - -{{% show-in "enterprise" %}} -```bash -# Memory object store -# Stores data in RAM; doesn't persist data -influxdb3 serve \ ---node-id host01 \ ---cluster-id cluster01 \ ---object-store memory -``` -{{% /show-in %}} -{{% show-in "core" %}} -```bash -# Memory object store -# Stores data in RAM; doesn't persist data -influxdb3 serve \ ---node-id host01 \ ---object-store memory -``` -{{% /show-in %}} - -For more information about server options, use the CLI help or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/influxdb3/serve/): - -```bash -influxdb3 serve --help -``` - -> [!Tip] -> #### Run the InfluxDB 3 Explorer query interface (beta) -> -> InfluxDB 3 Explorer (currently in beta) is the web-based query and -> administrative interface for InfluxDB 3. -> It provides visual management of databases and tokens and an easy way to query your time series data. -> -> For more information, see the [InfluxDB 3 Explorer documentation](/influxdb3/explorer/). - -{{% show-in "enterprise" %}} -#### Licensing - -When first starting 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: - -- **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. -- **Commercial**: Commercial license with full access to InfluxDB 3 Enterprise capabilities. - -For more information, see how to [Manage your license](/influxdb3/enterprise/admin/license/). -{{% /show-in %}} - -### Authentication and authorization - -{{% product-name %}} uses token-based authentication and authorization, which is enabled by default when you start the server. - -With authentication enabled, you must provide a token with `influxdb3` CLI commands and HTTP API requests. - -{{% show-in "enterprise" %}} -{{% product-name %}} supports the following types of tokens: - -- **admin token**: Grants access to all CLI actions and API endpoints. A server can have one admin token. -- **resource tokens**: Tokens that grant read and write access to specific resources (databases and system information endpoints) on the server. - - - A database token grants access to write and query data in a - database - - A system token grants read access to system information endpoints and - metrics for the server -{{% /show-in %}} -{{% show-in "core" %}} -{{% product-name %}} supports _admin_ tokens, which grant access to all CLI actions and API endpoints. -{{% /show-in %}} - -For more information about tokens and authorization, see [Manage tokens](/influxdb3/version/admin/tokens/). - -#### Create an operator token - -After you start the server, create your first admin token. -The first admin token you create is the _operator_ token for the server. - -Use the `influxdb3` CLI or the HTTP API to create your operator token. - -> [!Important] -> **Store your token securely** -> -> InfluxDB displays the token string only when you create it. -> Store your token securely—you cannot retrieve it from the database later. - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[CLI](#) -[Docker](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - -```bash -influxdb3 create token --admin -``` - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-placeholders "CONTAINER_NAME" %}} -```bash -# With Docker — in a new terminal: -docker exec -it CONTAINER_NAME influxdb3 create token --admin -``` -{{% /code-placeholders %}} - -Replace {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}} with the name of your running Docker container. - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -The command returns a token string for authenticating CLI commands and API requests. -Store your token securely—you cannot retrieve it from the database later. - -#### Set your token for authentication - -Use your operator token to authenticate server actions in {{% product-name %}}, -such as creating additional tokens, performing administrative tasks, and writing and querying data. - -Use one of the following methods to provide your token and authenticate `influxdb3` CLI commands. - -In your command, replace {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}} with your token string (for example, the [operator token](#create-an-operator-token) from the previous step). - -{{< tabs-wrapper >}} -{{% tabs %}} -[Environment variable (recommended)](#) -[Command option](#) -{{% /tabs %}} -{{% tab-content %}} - -Set the `INFLUXDB3_AUTH_TOKEN` environment variable to have the CLI use your token automatically: - -{{% code-placeholders "YOUR_AUTH_TOKEN" %}} -```bash -export INFLUXDB3_AUTH_TOKEN=YOUR_AUTH_TOKEN -``` -{{% /code-placeholders %}} - -{{% /tab-content %}} -{{% tab-content %}} - -Include the `--token` option with CLI commands: - -{{% code-placeholders "YOUR_AUTH_TOKEN" %}} -```bash -influxdb3 show databases --token AUTH_TOKEN -``` -{{% /code-placeholders %}} - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - -For HTTP API requests, include your token in the `Authorization` header--for example: - -{{% code-placeholders "AUTH_TOKEN" %}} -```bash -curl "http://{{< influxdb/host >}}/api/v3/configure/database" \ - --header "Authorization: Bearer AUTH_TOKEN" -``` -{{% /code-placeholders %}} - -#### Learn more about tokens and permissions - -- [Manage admin tokens](/influxdb3/version/admin/tokens/admin/) - Understand and manage operator and named admin tokens -{{% show-in "enterprise" %}} -- [Manage resource tokens](/influxdb3/version/admin/tokens/resource/) - Create, list, and delete resource tokens -{{% /show-in %}} -- [Authentication](/influxdb3/version/reference/internals/authentication/) - Understand authentication, authorizations, and permissions in {{% product-name %}} - -### Data model - -The database server contains logical databases, which have tables, which have columns. Compared to previous versions of InfluxDB you can think of a database as a `bucket` in v2 or as a `db/retention_policy` in v1. A `table` is equivalent to a `measurement`, which has columns that can be of type `tag` (a string dictionary), `int64`, `float64`, `uint64`, `bool`, or `string` and finally every table has a `time` column that is a nanosecond precision timestamp. - -In InfluxDB 3, every table has a primary key--the ordered set of tags and the time--for its data. -This is the sort order used for all Parquet files that get created. When you create a table, either through an explicit call or by writing data into a table for the first time, it sets the primary key to the tags in the order they arrived. This is immutable. Although InfluxDB is still a _schema-on-write_ database, the tag column definitions for a table are immutable. - -Tags should hold unique identifying information like `sensor_id`, or `building_id` or `trace_id`. All other data should be kept in fields. You will be able to add fast last N value and distinct value lookups later for any column, whether it is a field or a tag. - -### Tools to use +## Data model + +The {{% product-name %}} server contains logical databases; databases contain +tables; and tables are comprised of columns. + +Compared to previous versions of InfluxDB, you can think of a database as an +InfluxDB v2 `bucket` in v2 or an InfluxDB v1 `db/retention_policy`. +A `table` is equivalent to an InfluxDB v1 and v2 `measurement`. + +Columns in a table represent time, tags, and fields. Columns can be one of the +following types: + +- String dictionary (tag) +- `int64` (field) +- `float64` (field) +- `uint64` (field) +- `bool` (field) +- `string` (field) +- `time` (time with nanosecond precision) + +In {{% product-name %}}, every table has a primary key--the ordered set of tags and the time--for its data. +The primary key uniquely identifies each and determines the sort order for all +Parquet files related to the table. When you create a table, either through an +explicit call or by writing data into a table for the first time, it sets the +primary key to the tags in the order they arrived. +Although InfluxDB is still a _schema-on-write_ database, the tag column +definitions for a table are immutable. + +Tags should hold unique identifying information like `sensor_id`, `building_id`, +or `trace_id`. All other data should be stored as fields. + +## Tools to use The following table compares tools that you can use to interact with {{% product-name %}}. This tutorial covers many of the recommended tools. -| Tool | Administration | Write | Query | -| :------------------------------------------------------------------------------------------------ | :----------------------: | :----------------------: | :----------------------: | -| **`influxdb3` CLI** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| **InfluxDB HTTP API** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| **InfluxDB 3 Explorer** {{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | - | **{{< icon "check" >}}** | -| [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| [InfluxDB v2 client libraries](/influxdb3/version/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - | -| [InfluxDB v1 client libraries](/influxdb3/version/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| [InfluxDB 3 processing engine](#python-plugins-and-the-processing-engine){{< req text="\* " color="magenta" >}} | | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| [Telegraf](/telegraf/v1/) | - | **{{< icon "check" >}}** | - | -| [Chronograf](/chronograf/v1/) | - | - | - | -| `influx` CLI | - | - | - | -| `influxctl` CLI | - | - | - | -| InfluxDB v2.x user interface | - | - | - | -| **Third-party tools** | | | | -| Flight SQL clients | - | - | **{{< icon "check" >}}** | -| [Grafana](/influxdb3/version/visualize-data/grafana/) | - | - | **{{< icon "check" >}}** | - -{{< caption >}} -{{< req type="key" text="Covered in this guide" color="magenta" >}} -{{< /caption >}} - -### 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. - -{{% show-in "core" %}} -> [!Note] -> #### 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. -> For extended historical queries and optimized data organization, consider using [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/). -{{% /show-in %}} - -#### Write data in line protocol syntax - -{{% product-name %}} accepts data in [line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax. -The following code block is an example of time series data in [line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax: - -- `cpu`: the table name. -- `host`, `region`, `applications`: the tags. A tag set is an ordered, comma-separated list of key/value pairs where the values are strings. -- `val`, `usage_percent`, `status`: the fields. A field set is a comma-separated list of key/value pairs. -- timestamp: If you don't specify a timestamp, InfluxData uses the time when data is written. - The default precision is a nanosecond epoch. - To specify a different precision, pass the `precision` parameter in your CLI command or API request. - -``` -cpu,host=Alpha,region=us-west,application=webserver val=1i,usage_percent=20.5,status="OK" -cpu,host=Bravo,region=us-east,application=database val=2i,usage_percent=55.2,status="OK" -cpu,host=Charlie,region=us-west,application=cache val=3i,usage_percent=65.4,status="OK" -cpu,host=Bravo,region=us-east,application=database val=4i,usage_percent=70.1,status="Warn" -cpu,host=Bravo,region=us-central,application=database val=5i,usage_percent=80.5,status="OK" -cpu,host=Alpha,region=us-west,application=webserver val=6i,usage_percent=25.3,status="Warn" -``` - -### Write data using the CLI - -To quickly get started writing data, you can use the `influxdb3` CLI. - -> [!Note] -> For batching and higher-volume write workloads, we recommend using the [HTTP API](#write-data-using-the-http-api). -> -> #### Write data using InfluxDB API client libraries -> -> InfluxDB provides supported client libraries that integrate with your code -> to construct data as time series points and write the data as line protocol to your {{% product-name %}} database. -> For more information, see how to [use InfluxDB client libraries to write data](/influxdb3/version/write-data/api-client-libraries/). - -##### Example: write data using the influxdb3 CLI - -Use the `influxdb3 write` command to write data to a database. - -In the code samples, replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases/) to write to. -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to write to the specified database{{% /show-in %}} - -##### Write data via stdin - -Pass data as quoted line protocol via standard input (stdin)--for example: - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} -```bash -influxdb3 write \ - --database DATABASE_NAME \ - --token AUTH_TOKEN \ - --precision ns \ - --accept-partial \ -'cpu,host=Alpha,region=us-west,application=webserver val=1i,usage_percent=20.5,status="OK" -cpu,host=Bravo,region=us-east,application=database val=2i,usage_percent=55.2,status="OK" -cpu,host=Charlie,region=us-west,application=cache val=3i,usage_percent=65.4,status="OK" -cpu,host=Bravo,region=us-east,application=database val=4i,usage_percent=70.1,status="Warn" -cpu,host=Bravo,region=us-central,application=database val=5i,usage_percent=80.5,status="OK" -cpu,host=Alpha,region=us-west,application=webserver val=6i,usage_percent=25.3,status="Warn"' -``` -{{% /code-placeholders %}} - -##### Write data from a file - -Pass the `--file` option to write line protocol you have saved to a file--for example, save the -[sample line protocol](#write-data-in-line-protocol-syntax) to a file named `server_data` -and then enter the following command: - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} -```bash -influxdb3 write \ - --database DATABASE_NAME \ - --token AUTH_TOKEN \ - --precision ns \ - --accept-partial \ - --file path/to/server_data -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases/) to write to. -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to write to the specified database{{% /show-in %}} - -### Write data using the HTTP API - -{{% product-name %}} provides three write API endpoints that respond to HTTP `POST` requests. -The `/api/v3/write_lp` endpoint is the recommended endpoint for writing data and -provides additional options for controlling write behavior. - -If you need to write data using InfluxDB v1.x or v2.x tools, use the compatibility API endpoints. -Compatibility APIs work with [Telegraf](/telegraf/v1/), InfluxDB v2.x and v1.x [API client libraries](/influxdb3/version/reference/client-libraries), and other tools that support the v1.x or v2.x APIs. - -{{% tabs-wrapper %}} -{{% tabs %}} -[/api/v3/write_lp](#) -[v2 compatibility](#) -[v1 compatibility](#) -{{% /tabs %}} -{{% tab-content %}} - -{{% product-name %}} adds the `/api/v3/write_lp` endpoint. - -{{}} - -This endpoint accepts the same line protocol syntax as previous versions, -and supports the following parameters: - -- `?accept_partial=`: Accept or reject partial writes (default is `true`). -- `?no_sync=`: Control when writes are acknowledged: - - `no_sync=true`: Acknowledges writes before WAL persistence completes. - - `no_sync=false`: Acknowledges writes after WAL persistence completes (default). -- `?precision=`: Specify the precision of the timestamp. The default is nanosecond precision. -- request body: The line protocol data to write. - -For more information about the parameters, see [Write data](/influxdb3/version/write-data/). - -##### Example: write data using the /api/v3 HTTP API - -The following examples show how to write data using `curl` and the `/api/3/write_lp` HTTP endpoint. -To show the difference between accepting and rejecting partial writes, line `2` in the example contains a `string` value (`"hi"`) for a `float` field (`temp`). - -###### Partial write of line protocol occurred - -With `accept_partial=true` (default): - -```bash -curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \ - --header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \ - --data-raw 'home,room=Sunroom temp=96 -home,room=Sunroom temp="hi"' -``` - -The response is the following: - -``` -< HTTP/1.1 400 Bad Request -... -{ - "error": "partial write of line protocol occurred", - "data": [ - { - "original_line": "home,room=Sunroom temp=hi", - "line_number": 2, - "error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string" - } - ] -} -``` - -Line `1` is written and queryable. -The response is an HTTP error (`400`) status, and the response body contains the error message `partial write of line protocol occurred` with details about the problem line. - -###### Parsing failed for write_lp endpoint - -With `accept_partial=false`: - -```bash -curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&accept_partial=false" \ - --header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \ - --data-raw 'home,room=Sunroom temp=96 -home,room=Sunroom temp="hi"' -``` - -The response is the following: - -``` -< HTTP/1.1 400 Bad Request -... -{ - "error": "parsing failed for write_lp endpoint", - "data": { - "original_line": "home,room=Sunroom temp=hi", - "line_number": 2, - "error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string" - } -} -``` - -InfluxDB rejects all points in the batch. -The response is an HTTP error (`400`) status, and the response body contains `parsing failed for write_lp endpoint` and details about the problem line. - -For more information about the ingest path and data flow, see [Data durability](/influxdb3/version/reference/internals/durability/). - -{{% /tab-content %}} -{{% tab-content %}} - -The `/api/v2/write` InfluxDB v2 compatibility endpoint provides backwards compatibility with clients (such as [Telegraf's InfluxDB v2 output plugin](/telegraf/v1/plugins/#output-influxdb_v2) and [InfluxDB v2 API client libraries](/influxdb3/version/reference/client-libraries/v2/)) that can write data to InfluxDB OSS v2.x and Cloud 2 (TSM). - -{{}} - -{{% /tab-content %}} - -{{% tab-content %}} - -The `/write` InfluxDB v1 compatibility endpoint provides backwards compatibility for clients that can write data to InfluxDB v1.x. - -{{}} - - -{{% /tab-content %}} -{{% /tabs-wrapper %}} - -> [!Note] -> #### Compatibility APIs differ from native APIs -> -> Keep in mind that the compatibility APIs differ from the v1 and v2 APIs in previous versions in the following ways: -> -> - Tags in a table (measurement) are _immutable_ -> - A tag and a field can't have the same name within a table. - -#### Write responses - -By default, InfluxDB acknowledges writes after flushing the WAL file to the object store (occurring every second). -For high write throughput, you can send multiple concurrent write requests. - -#### Use no_sync for immediate write responses - -To reduce the latency of writes, use the `no_sync` write option, which acknowledges writes _before_ WAL persistence completes. -When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, and then immediately responds to the client, without waiting for persistence to the object store. - -Using `no_sync=true` is best when prioritizing high-throughput writes over absolute durability. - -- Default behavior (`no_sync=false`): Waits for data to be written to the object store before acknowledging the write. Reduces the risk of data loss, but increases the latency of the response. -- With `no_sync=true`: Reduces write latency, but increases the risk of data loss in case of a crash before WAL persistence. - -##### Immediate write using the HTTP API - -The `no_sync` parameter controls when writes are acknowledged--for example: - -```bash -curl "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&no_sync=true" \ - --header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \ - --data-raw "home,room=Sunroom temp=96" -``` - -### Create a database or table - -To create a database without writing data, use the `create` subcommand--for example: - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} -```bash -influxdb3 create database DATABASE_NAME \ - --token AUTH_TOKEN -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server - -To learn more about a subcommand, use the `-h, --help` flag or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/influxdb3/create): - -```bash -influxdb3 create -h -``` - -### Query data - -InfluxDB 3 supports native SQL for querying, in addition to InfluxQL, an -SQL-like language 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/). -{{% /show-in %}} - -> [!Note] -> Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3. - -The quickest way to get started querying is to use the `influxdb3` CLI (which uses the Flight SQL API over HTTP2). - -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. - -| Option | Description | Required | -|---------|-------------|--------------| -| `--host` | The host URL of the server [default: `http://127.0.0.1:8181`] to query | No | -| `--database` | The name of the database to operate on | Yes | -| `--token` | The authentication token for the {{% product-name %}} server | No | -| `--language` | The query language of the provided query string [default: `sql`] [possible values: `sql`, `influxql`] | No | -| `--format` | The format in which to output the query [default: `pretty`] [possible values: `pretty`, `json`, `jsonl`, `csv`, `parquet`] | No | -| `--output` | The path to output data to | No | - -#### 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: - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} -```bash -influxdb3 query \ - --database DATABASE_NAME \ - --token \ - --language influxql \ - "SELECT DISTINCT usage_percent FROM cpu WHERE time >= now() - 1d" -``` -{{% /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 %}} - -### Query using the API - -InfluxDB 3 supports Flight (gRPC) APIs and an HTTP API. -To query your database using the HTTP API, send a request to the `/api/v3/query_sql` or `/api/v3/query_influxql` endpoints. -In the request, specify the database name in the `db` parameter -and a query in the `q` parameter. -You can pass parameters in the query string or inside a JSON object. - -Use the `format` parameter to specify the response format: `pretty`, `jsonl`, `parquet`, `csv`, and `json`. Default is `json`. - -##### Example: Query passing URL-encoded parameters - -The following example sends an HTTP `GET` request with a URL-encoded SQL query: - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} -```bash -curl -G "http://{{< influxdb/host >}}/api/v3/query_sql" \ - --header 'Authorization: Bearer AUTH_TOKEN' \ - --data-urlencode "db=DATABASE_NAME" \ - --data-urlencode "q=select * from cpu limit 5" -``` -{{% /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 %}} - -##### Example: Query passing JSON parameters - -The following example sends an HTTP `POST` request with parameters in a JSON payload: - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} -```bash -curl http://{{< influxdb/host >}}/api/v3/query_sql \ - --data '{"db": "DATABASE_NAME", "q": "select * from cpu limit 5"}' -``` -{{% /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 %}} - -### Query using the Python client - -Use the InfluxDB 3 Python library to interact with the database and integrate with your application. -We recommend installing the required packages in a Python virtual environment for your specific project. - -To get started, install the `influxdb3-python` package. - -```bash -pip install influxdb3-python -``` - -From here, you can connect to your database with the client library using just the **host** and **database name: - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} -```python -from influxdb_client_3 import InfluxDBClient3 - -client = InfluxDBClient3( - token='AUTH_TOKEN', - host='http://{{< influxdb/host >}}', - database='DATABASE_NAME' -) -``` -{{% /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 %}} - -The following example shows how to query using SQL, and then -use PyArrow to explore the schema and process results. -To authorize the query, the example retrieves the {{% token-link "database" %}} -from the `INFLUXDB3_AUTH_TOKEN` environment variable. - -```python -from influxdb_client_3 import InfluxDBClient3 -import os - -client = InfluxDBClient3( - token=os.environ.get('INFLUXDB3_AUTH_TOKEN'), - host='http://{{< influxdb/host >}}', - database='servers' -) - -# Execute the query and return an Arrow table -table = client.query( - query="SELECT * FROM cpu LIMIT 10", - language="sql" -) - -print("\n#### View Schema information\n") -print(table.schema) - -print("\n#### Use PyArrow to read the specified columns\n") -print(table.column('usage_active')) -print(table.select(['host', 'usage_active'])) -print(table.select(['time', 'host', 'usage_active'])) - -print("\n#### Use PyArrow compute functions to aggregate data\n") -print(table.group_by('host').aggregate([])) -print(table.group_by('cpu').aggregate([('time_system', 'mean')])) -``` - -For more information about the Python client library, see the [`influxdb3-python` repository](https://github.com/InfluxCommunity/influxdb3-python) in GitHub. - -### Query using InfluxDB 3 Explorer (Beta) - -You can use the InfluxDB 3 Explorer web-based interface to query and visualize data, -and administer your {{% product-name %}} instance. -For more information, see how to [install InfluxDB 3 Explorer (Beta)](/influxdb3/explorer/install/) using Docker -and get started querying your data. - -### Last values cache - -{{% product-name %}} supports a **last-n values cache** which stores the last N values in a series or column hierarchy in memory. This gives the database the ability to answer these kinds of queries in under 10 milliseconds. - -You can use the `influxdb3` CLI to [create a last value cache](/influxdb3/version/reference/cli/influxdb3/create/last_cache/). - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}} -```bash -influxdb3 create last_cache \ - --token AUTH_TOKEN - --database DATABASE_NAME \ - --table TABLE_NAME \ - CACHE_NAME -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the last values cache in -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} -- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create the last values cache in -- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: Optionally, a name for the new cache - -Consider the following `cpu` sample table: - -| host | application | time | usage\_percent | status | -| ----- | ----- | ----- | ----- | ----- | -| Bravo | database | 2024-12-11T10:00:00 | 55.2 | OK | -| Charlie | cache | 2024-12-11T10:00:00 | 65.4 | OK | -| Bravo | database | 2024-12-11T10:01:00 | 70.1 | Warn | -| Bravo | database | 2024-12-11T10:01:00 | 80.5 | OK | -| Alpha | webserver | 2024-12-11T10:02:00 | 25.3 | Warn | - -The following command creates a last value cache named `cpuCache`: - -```bash -influxdb3 create last_cache \ - --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ - --database servers \ - --table cpu \ - --key-columns host,application \ - --value-columns usage_percent,status \ - --count 5 cpuCache -``` - -_You can create a last values cache per time series, but be mindful of high cardinality tables that could take excessive memory._ - -#### Query a last values cache - -To query data from the LVC, use the [`last_cache()`](/influxdb3/version/reference/sql/functions/cache/#last_cache) function in your query--for example: - -```bash -influxdb3 query \ - --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ - --database servers \ - "SELECT * FROM last_cache('cpu', 'cpuCache') WHERE host = 'Bravo';" -``` - -> [!Note] -> #### Only works with SQL -> -> The last values cache only works with SQL, not InfluxQL; SQL is the default language. - -#### Delete a last values cache - -Use the `influxdb3` CLI to [delete a last values cache](/influxdb3/version/reference/cli/influxdb3/delete/last_cache/) - -{{% code-placeholders "DATABASE_NAME|TABLE_NAME|CACHE_NAME" %}} -```bash -influxdb3 delete last_cache \ - --token AUTH_TOKEN \ - --database DATABASE_NAME \ - --table TABLE \ - --cache-name CACHE_NAME -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to delete the last values cache from -- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to delete the last values cache from -- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: the name of the last values cache to delete - -### Distinct values cache - -Similar to the [last values cache](#last-values-cache), the database can cache in RAM the distinct values for a single column in a table or a hierarchy of columns. -This is useful for fast metadata lookups, which can return in under 30 milliseconds. -Many of the options are similar to the last value cache. - -You can use the `influxdb3` CLI to [create a distinct values cache](/influxdb3/version/reference/cli/influxdb3/create/distinct_cache/). - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TABLE_NAME|CACHE_NAME" %}} -```bash -influxdb3 create distinct_cache \ - --token AUTH_TOKEN \ - --database DATABASE_NAME \ - --table TABLE \ - --columns COLUMNS \ - CACHE_NAME -``` -{{% /code-placeholders %}} -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the last values cache in -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} -- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create the distinct values cache in -- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: Optionally, a name for the new cache - -Consider the following `cpu` sample table: - -| host | application | time | usage\_percent | status | -| ----- | ----- | ----- | ----- | ----- | -| Bravo | database | 2024-12-11T10:00:00 | 55.2 | OK | -| Charlie | cache | 2024-12-11T10:00:00 | 65.4 | OK | -| Bravo | database | 2024-12-11T10:01:00 | 70.1 | Warn | -| Bravo | database | 2024-12-11T10:01:00 | 80.5 | OK | -| Alpha | webserver | 2024-12-11T10:02:00 | 25.3 | Warn | - -The following command creates a distinct values cache named `cpuDistinctCache`: - -```bash -influxdb3 create distinct_cache \ - --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ - --database servers \ - --table cpu \ - --columns host,application \ - cpuDistinctCache -``` - -#### Query a distinct values cache - -To query data from the distinct values cache, use the [`distinct_cache()`](/influxdb3/version/reference/sql/functions/cache/#distinct_cache) function in your query--for example: - -```bash -influxdb3 query \ - --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ - --database servers \ - "SELECT * FROM distinct_cache('cpu', 'cpuDistinctCache')" -``` - -> [!Note] -> #### Only works with SQL -> -> The distinct cache only works with SQL, not InfluxQL; SQL is the default language. - -#### Delete a distinct values cache - -Use the `influxdb3` CLI to [delete a distinct values cache](/influxdb3/version/reference/cli/influxdb3/delete/distinct_cache/) - -{{% code-placeholders "DATABASE_NAME|TABLE_NAME|CACHE_NAME" %}} -```bash -influxdb3 delete distinct_cache \ - --token AUTH_TOKEN \ - --database DATABASE_NAME \ - --table TABLE \ - --cache-name CACHE_NAME -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to delete the distinct values cache from -- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to delete the distinct values cache from -- {{% code-placeholder-key %}}`CACHE_NAME`{{% /code-placeholder-key %}}: the name of the distinct values cache to delete - -### Python plugins and the processing engine - -The InfluxDB 3 processing engine is an embedded Python VM for running code inside the database to process and transform data. - -To activate the processing engine, pass the `--plugin-dir ` option when starting the {{% product-name %}} server. -`PLUGIN_DIR` is your filesystem location for storing [plugin](#plugin) files for the processing engine to run. - -#### Plugin - -A plugin is a Python function that has a signature compatible with a Processing engine [trigger](#trigger). - -#### Trigger - -When you create a trigger, you specify a [plugin](#plugin), a database, optional arguments, -and a _trigger-spec_, which defines when the plugin is executed and what data it receives. - -##### Trigger types - -InfluxDB 3 provides the following types of triggers, each with specific trigger-specs: - -- **On WAL flush**: Sends a batch of written data (for a specific table or all tables) to a plugin (by default, every second). -- **On Schedule**: Executes a plugin on a user-configured schedule (using a crontab or a duration); useful for data collection and deadman monitoring. -- **On Request**: Binds a plugin to a custom HTTP API endpoint at `/api/v3/engine/`. - The plugin receives the HTTP request headers and content, and can then parse, process, and send the data into the database or to third-party services. - -### Test, create, and trigger plugin code - -##### Example: Python plugin for WAL rows - -```python -# This is the basic structure for Python plugin code that runs in the -# InfluxDB 3 Processing engine. - -# When creating a trigger, you can provide runtime arguments to your plugin, -# allowing you to write generic code that uses variables such as monitoring -thresholds, environment variables, and host names. -# -# Use the following exact signature to define a function for the WAL flush -# trigger. -# When you create a trigger for a WAL flush plugin, you specify the database -# and tables that the plugin receives written data from on every WAL flush -# (default is once per second). -def process_writes(influxdb3_local, table_batches, args=None): - # here you can see logging. for now this won't do anything, but soon - # we'll capture this so you can query it from system tables - if args and "arg1" in args: - influxdb3_local.info("arg1: " + args["arg1"]) - - # here we're using arguments provided at the time the trigger was set up - # to feed into paramters that we'll put into a query - query_params = {"host": "foo"} - # here's an example of executing a parameterized query. Only SQL is supported. - # It will query the database that the trigger is attached to by default. We'll - # soon have support for querying other DBs. - query_result = influxdb3_local.query("SELECT * FROM cpu where host = '$host'", query_params) - # the result is a list of Dict that have the column name as key and value as - # value. If you run the WAL test plugin with your plugin against a DB that - # you've written data into, you'll be able to see some results - influxdb3_local.info("query result: " + str(query_result)) - - # this is the data that is sent when the WAL is flushed of writes the server - # received for the DB or table of interest. One batch for each table (will - # only be one if triggered on a single table) - for table_batch in table_batches: - # here you can see that the table_name is available. - influxdb3_local.info("table: " + table_batch["table_name"]) - - # example to skip the table we're later writing data into - if table_batch["table_name"] == "some_table": - continue - - # and then the individual rows, which are Dict with keys of the column names and values - for row in table_batch["rows"]: - influxdb3_local.info("row: " + str(row)) - - # this shows building a line of LP to write back to the database. tags must go first and - # their order is important and must always be the same for each individual table. Then - # fields and lastly an optional time, which you can see in the next example below - line = LineBuilder("some_table")\ - .tag("tag1", "tag1_value")\ - .tag("tag2", "tag2_value")\ - .int64_field("field1", 1)\ - .float64_field("field2", 2.0)\ - .string_field("field3", "number three") - - # this writes it back (it actually just buffers it until the completion of this function - # at which point it will write everything back that you put in) - influxdb3_local.write(line) - - # here's another example, but with us setting a nanosecond timestamp at the end - other_line = LineBuilder("other_table") - other_line.int64_field("other_field", 1) - other_line.float64_field("other_field2", 3.14) - other_line.time_ns(1302) - - # and you can see that we can write to any DB in the server - influxdb3_local.write_to_db("mytestdb", other_line) - - # just some log output as an example - influxdb3_local.info("done") -``` - -##### Test a plugin on the server - -Test your InfluxDB 3 plugin safely without affecting written data. During a plugin test: - -- A query executed by the plugin queries against the server you send the request to. -- Writes aren't sent to the server but are returned to you. - -To test a plugin, do the following: - -1. Create a _plugin directory_--for example, `/path/to/.influxdb/plugins` -2. [Start the InfluxDB server](#start-influxdb) and include the `--plugin-dir ` option. -3. Save the [example plugin code](#example-python-plugin-for-wal-rows) to a plugin file inside of the plugin directory. If you haven't yet written data to the table in the example, comment out the lines where it queries. -4. To run the test, enter the following command with the following options: - - - `--lp` or `--file`: The line protocol to test - - Optional: `--input-arguments`: A comma-delimited list of `=` arguments for your plugin code - -{{% code-placeholders "INPUT_LINE_PROTOCOL|INPUT_ARGS|DATABASE_NAME|AUTH_TOKEN|PLUGIN_FILENAME" %}} -```bash -influxdb3 test wal_plugin \ ---lp INPUT_LINE_PROTOCOL \ ---input-arguments INPUT_ARGS \ ---database DATABASE_NAME \ ---token AUTH_TOKEN \ -PLUGIN_FILENAME -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`INPUT_LINE_PROTOCOL`{{% /code-placeholder-key %}}: the line protocol to test -- Optional: {{% code-placeholder-key %}}`INPUT_ARGS`{{% /code-placeholder-key %}}: a comma-delimited list of `=` arguments for your plugin code--for example, `arg1=hello,arg2=world` -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to test against -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server -- {{% code-placeholder-key %}}`PLUGIN_FILENAME`{{% /code-placeholder-key %}}: the name of the plugin file to test - -The command runs the plugin code with the test data, yields the data to the plugin code, and then responds with the plugin result. -You can quickly see how the plugin behaves, what data it would have written to the database, and any errors. -You can then edit your Python code in the plugins directory, and rerun the test. -The server reloads the file for every request to the `test` API. - -For more information, see [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/) or run `influxdb3 test wal_plugin -h`. - -With the plugin code inside the server plugin directory, and a successful test, -you're ready to create a plugin and a trigger to run on the server. - -##### Example: Test, create, and run a plugin - -The following example shows how to test a plugin, and then create the plugin and -trigger: - -```bash -# Test and create a plugin -# Requires: -# - A database named `mydb` with a table named `foo` -# - A Python plugin file named `test.py` -# Test a plugin -influxdb3 test wal_plugin \ - --lp "my_measure,tag1=asdf f1=1.0 123" \ - --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ - --database sensors \ - --input-arguments "arg1=hello,arg2=world" \ - test.py -``` - -```bash -# Create a trigger that runs the plugin -influxdb3 create trigger \ - --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ - --database sensors \ - --plugin test_plugin \ - --trigger-spec "table:foo" \ - --trigger-arguments "arg1=hello,arg2=world" \ - trigger1 -``` - -After you have created a plugin and trigger, enter the following command to -enable the trigger and have it run the plugin as you write data: - -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TRIGGER_NAME" %}} -```bash -influxdb3 enable trigger \ - --token AUTH_TOKEN \ - --database DATABASE_NAME \ - TRIGGER_NAME -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to enable the trigger in -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} -- {{% code-placeholder-key %}}`TRIGGER_NAME`{{% /code-placeholder-key %}}: the name of the trigger to enable - -For example, to enable the trigger named `trigger1` in the `sensors` database: - -```bash -influxdb3 enable trigger \ - --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ - --database sensors - trigger1 -``` - -For more information, see [Python plugins and the Processing engine](/influxdb3/version/plugins/). - -{{% show-in "enterprise" %}} -### Multi-server setup - -{{% product-name %}} is built to support multi-node setups for high availability, read replicas, and flexible implementations depending on use case. - -### High availability - -Enterprise is architecturally flexible, giving you options on how to configure multiple servers that work together for high availability (HA) and high performance. -Built on top of the diskless engine and leveraging the Object store, an HA setup ensures that if a node fails, you can still continue reading from, and writing to, a secondary node. - -A two-node setup is the minimum for basic high availability, with both nodes having read-write permissions. - -{{< img-hd src="/img/influxdb/influxdb-3-enterprise-high-availability.png" alt="Basic high availability setup" />}} - -In a basic HA setup: - -- Two nodes both write data to the same Object store and both handle queries -- Node 1 and Node 2 are _read replicas_ that read from each other’s Object store directories -- One of the nodes is designated as the Compactor node - -> [!Note] -> Only one node can be designated as the Compactor. -> Compacted data is meant for a single writer, and many readers. - -The following examples show how to configure and start two nodes -for a basic HA setup. - -- _Node 1_ is for compaction (passes `compact` in `--mode`) -- _Node 2_ is for ingest and query - -```bash -## NODE 1 - -# Example variables -# node-id: 'host01' -# cluster-id: 'cluster01' -# bucket: 'influxdb-3-enterprise-storage' - -influxdb3 serve \ - --node-id host01 \ - --cluster-id cluster01 \ - --mode ingest,query,compact \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --http-bind {{< influxdb/host >}} \ - --aws-access-key-id \ - --aws-secret-access-key -``` - -```bash -## NODE 2 - -# Example variables -# node-id: 'host02' -# cluster-id: 'cluster01' -# bucket: 'influxdb-3-enterprise-storage' - -influxdb3 serve \ - --node-id host02 \ - --cluster-id cluster01 \ - --mode ingest,query \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --http-bind localhost:8282 \ - --aws-access-key-id AWS_ACCESS_KEY_ID \ - --aws-secret-access-key AWS_SECRET_ACCESS_KEY -``` - -After the nodes have started, querying either node returns data for both nodes, and _NODE 1_ runs compaction. -To add nodes to this setup, start more read replicas with the same cluster ID. - -### High availability with a dedicated Compactor - -Data compaction in InfluxDB 3 is one of the more computationally expensive operations. -To ensure that your read-write nodes don't slow down due to compaction work, set up a compactor-only node for consistent and high performance across all nodes. - -{{< img-hd src="/img/influxdb/influxdb-3-enterprise-dedicated-compactor.png" alt="Dedicated Compactor setup" />}} - -The following examples show how to set up high availability with a dedicated Compactor node: - -1. Start two read-write nodes as read replicas, similar to the previous example. - - ```bash - ## NODE 1 — Writer/Reader Node #1 - - # Example variables - # node-id: 'host01' - # cluster-id: 'cluster01' - # bucket: 'influxdb-3-enterprise-storage' - - influxdb3 serve \ - --node-id host01 \ - --cluster-id cluster01 \ - --mode ingest,query \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --http-bind {{< influxdb/host >}} \ - --aws-access-key-id \ - --aws-secret-access-key - ``` - - ```bash - ## NODE 2 — Writer/Reader Node #2 - - # Example variables - # node-id: 'host02' - # cluster-id: 'cluster01' - # bucket: 'influxdb-3-enterprise-storage' - - influxdb3 serve \ - --node-id host02 \ - --cluster-id cluster01 \ - --mode ingest,query \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --http-bind localhost:8282 \ - --aws-access-key-id \ - --aws-secret-access-key - ``` - -2. Start the dedicated compactor node with the `--mode=compact` option to ensure the node **only** runs compaction. - - ```bash - ## NODE 3 — Compactor Node - - # Example variables - # node-id: 'host03' - # cluster-id: 'cluster01' - # bucket: 'influxdb-3-enterprise-storage' - - influxdb3 serve \ - --node-id host03 \ - --cluster-id cluster01 \ - --mode compact \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --aws-access-key-id \ - --aws-secret-access-key - ``` - -### High availability with read replicas and a dedicated Compactor - -For a robust and effective setup for managing time-series data, you can run ingest nodes alongside read-only nodes and a dedicated Compactor node. - -{{< img-hd src="/img/influxdb/influxdb-3-enterprise-workload-isolation.png" alt="Workload Isolation Setup" />}} - -1. Start ingest nodes by assigning them the **`ingest`** mode. - To achieve the benefits of workload isolation, you'll send _only write requests_ to these ingest nodes. Later, you'll configure the _read-only_ nodes. - - ```bash - ## NODE 1 — Writer Node #1 - - # Example variables - # node-id: 'host01' - # cluster-id: 'cluster01' - # bucket: 'influxdb-3-enterprise-storage' - - influxdb3 serve \ - --node-id host01 \ - --cluster-id cluster01 \ - --mode ingest \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --http-bind {{< influxdb/host >}} \ - --aws-access-key-id \ - --aws-secret-access-key - ``` - - - - ```bash - ## NODE 2 — Writer Node #2 - - # Example variables - # node-id: 'host02' - # cluster-id: 'cluster01' - # bucket: 'influxdb-3-enterprise-storage' - - influxdb3 serve \ - --node-id host02 \ - --cluster-id cluster01 \ - --mode ingest \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --http-bind localhost:8282 \ - --aws-access-key-id \ - --aws-secret-access-key - ``` - -2. Start the dedicated Compactor node with ` compact`. - - ```bash - ## NODE 3 — Compactor Node - - # Example variables - # node-id: 'host03' - # cluster-id: 'cluster01' - # bucket: 'influxdb-3-enterprise-storage' - - influxdb3 serve \ - --node-id host03 \ - --cluster-id cluster01 \ - --mode compact \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --aws-access-key-id \ - - ``` - -3. Finally, start the query nodes as _read-only_ with `--mode query`. - - ```bash - ## NODE 4 — Read Node #1 - - # Example variables - # node-id: 'host04' - # cluster-id: 'cluster01' - # bucket: 'influxdb-3-enterprise-storage' - - influxdb3 serve \ - --node-id host04 \ - --cluster-id cluster01 \ - --mode query \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --http-bind localhost:8383 \ - --aws-access-key-id \ - --aws-secret-access-key - ``` - - ```bash - ## NODE 5 — Read Node #2 - - # Example variables - # node-id: 'host05' - # cluster-id: 'cluster01' - # bucket: 'influxdb-3-enterprise-storage' - - influxdb3 serve \ - --node-id host05 \ - --cluster-id cluster01 \ - --mode query \ - --object-store s3 \ - --bucket influxdb-3-enterprise-storage \ - --http-bind localhost:8484 \ - --aws-access-key-id \ - - ``` - -Congratulations, you have a robust setup for workload isolation using {{% product-name %}}. - -### Writing and querying for multi-node setups - -You can use the default port `8181` for any write or query, without changing any of the commands. - -> [!Note] -> #### Specify hosts for writes and queries -> -> To benefit from this multi-node, isolated architecture, specify hosts: -> -> - In write requests, specify a host that you have designated as _write-only_. -> - In query requests, specify a host that you have designated as _read-only_. -> -> When running multiple local instances for testing or separate nodes in production, specifying the host ensures writes and queries are routed to the correct instance. - -{{% code-placeholders "(http://localhost:8585)|AUTH_TOKEN|DATABASE_NAME|QUERY" %}} -```bash -# Example querying a specific host -# HTTP-bound Port: 8585 -influxdb3 query \ - --host http://localhost:8585 - --token AUTH_TOKEN \ - --database DATABASE_NAME "QUERY" -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`http://localhost:8585`{{% /code-placeholder-key %}}: the host and port of the node 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 %}} -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to query -- {{% code-placeholder-key %}}`QUERY`{{% /code-placeholder-key %}}: the SQL or InfluxQL query to run against the database - -### File index settings - -To accelerate performance on specific queries, you can define non-primary keys to index on, which helps improve performance for single-series queries. -This feature is only available in {{% product-name %}} and is not available in Core. - -#### Create a file index - -{{% code-placeholders "AUTH_TOKEN|DATABASE|TABLE|COLUMNS" %}} - -```bash -# Example variables on a query -# HTTP-bound Port: 8585 - -influxdb3 create file_index \ - --host http://localhost:8585 \ - --token AUTH_TOKEN \ - --database DATABASE_NAME \ - --table TABLE_NAME \ - COLUMNS -``` - -#### Delete a file index - -```bash -influxdb3 delete file_index \ - --host http://localhost:8585 \ - --database DATABASE_NAME \ - --table TABLE_NAME \ -``` -{{% /code-placeholders %}} - -Replace the following placeholders with your values: - -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the file index in -- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create the file index in -- {{% code-placeholder-key %}}`COLUMNS`{{% /code-placeholder-key %}}: a comma-separated list of columns to index on, for example, `host,application` -{{% /show-in %}} +| Tool | Administration | Write | Query | +| :-------------------------------------------------------------------------------- | :----------------------: | :----------------------: | :----------------------: | +| **[`influxdb3` CLI](/influxdb3/version/reference/cli/influxdb3/)** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| **[InfluxDB HTTP API](/influxdb3/version/reference/api/)** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| **[InfluxDB 3 Explorer](/influxdb3/explorer/)** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| [InfluxDB v2 client libraries](/influxdb3/version/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - | +| [InfluxDB v1 client libraries](/influxdb3/version/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| [InfluxDB 3 processing engine](/influxdb3/version/plugins/) | | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| [Telegraf](/telegraf/v1/) | - | **{{< icon "check" >}}** | - | +| [Chronograf](/chronograf/v1/) | - | - | - | +| `influx` CLI | - | - | - | +| `influxctl` CLI | - | - | - | +| InfluxDB v2.x user interface | - | - | - | +| **Third-party tools** | | | | +| Flight SQL clients | - | - | **{{< icon "check" >}}** | +| [Grafana](/influxdb3/version/visualize-data/grafana/) | - | - | **{{< icon "check" >}}** | + +{{< show-in "core" >}} +{{< page-nav next="/influxdb3/core/get-started/setup/" nextText="Set up InfluxDB 3 Core" >}} +{{< /show-in >}} + +{{< show-in "enterprise" >}} +{{< page-nav next="/influxdb3/enterprise/get-started/setup/" nextText="Set up InfluxDB 3 Enterprise" >}} +{{< /show-in >}} diff --git a/content/shared/influxdb3-get-started/processing-engine.md b/content/shared/influxdb3-get-started/processing-engine.md new file mode 100644 index 000000000..61f3399f1 --- /dev/null +++ b/content/shared/influxdb3-get-started/processing-engine.md @@ -0,0 +1,273 @@ +The {{% product-name %}} processing engine is an embedded Python virtual machine +(VM) that runs code inside the database to process and transform data. +Create processing engine [plugins](#plugin) that run when [triggered](#trigger) +by specific events. + +- [Processing engine terminology](#processing-engine-terminology) + - [Plugin](#plugin) + - [Trigger](#trigger) + - [Trigger types](#trigger-types) +- [Activate the processing engine](#activate-the-processing-engine) +- [Create a plugin](#create-a-plugin) +- [Test a plugin on the server](#test-a-plugin-on-the-server) +- [Create a trigger](#create-a-trigger) +- [Enable the trigger](#enable-the-trigger) + +## Processing engine terminology + +### Plugin + +A plugin is a Python function that has a signature compatible with a processing +engine [trigger](#trigger). + +### Trigger + +When you create a trigger, you specify a [plugin](#plugin), a database, optional +arguments, and a trigger specification, which defines when the plugin is executed and +what data it receives. + +#### Trigger types + +InfluxDB 3 provides the following types of triggers, each with specific +specifications: + +- **Data write** (`table:` or `all_tables`): Sends a batch of written data (for a specific table or all + tables) to a plugin when the database flushes data to the Write-Ahead Log (by default, every second). +- **Scheduled** (`every:` or `cron:`): Executes a plugin on a user-configured schedule (using a + crontab or a duration). This trigger type is useful for data collection and + deadman monitoring. +- **HTTP request** (`request:`): Binds a plugin to a custom HTTP API endpoint at + `/api/v3/engine/`. + The plugin receives the HTTP request headers and content, and can parse, + process, and send the data into the database or to third-party services. + +{{% show-in "enterprise" %}} +> [!Warning] +> #### Request trigger specification format differs between CLI and API +> +> Due to a bug in InfluxDB 3 Enterprise, the request trigger specification format differs: +> +> - **CLI**: `request:` (same as Core CLI and API) +> - **Enterprise API**: `{"request_path": {"path": ""}}` +> +> See the [API reference](/influxdb3/enterprise/api/#operation/PostConfigureProcessingEngineTrigger) for examples. Use `influxdb3 show summary` to verify the actual trigger specification. +{{% /show-in %}} + +## Activate the processing engine + +To activate the processing engine, include the `--plugin-dir ` option +when starting the {{% product-name %}} server. +`PLUGIN_DIR` is your file system location for storing [plugin](#plugin) files for +the processing engine to run. + +{{% code-placeholders "PLUGIN_DIR" %}} + +```bash +influxdb3 serve \ + # ... + --plugin-dir PLUGIN_DIR +``` +{{% /code-placeholders %}} + +Replace {{% code-placeholder-key %}}`PLUGIN_DIR`{{% /code-placeholder-key %}} +with the path to your plugin directory. This path can be absolute or relative +to the current working directory of the `influxdb3` server. + +## Create a plugin + +To create a plugin, write and store a Python file in your configured `PLUGIN_DIR`. +The following example is a data write plugin that processes data before it gets +persisted to the object store. + +##### Example Python plugin for data writes + +```python +# This is the basic structure for Python plugin code that runs in the +# InfluxDB 3 Processing engine. + +# When creating a trigger, you can provide runtime arguments to your plugin, +# allowing you to write generic code that uses variables such as monitoring +# thresholds, environment variables, and host names. +# +# Use the following exact signature to define a function for the data write +# trigger. +# When you create a trigger for a data write plugin, you specify the database +# and tables that the plugin receives written data from on every WAL flush +# (default is once per second). +def process_writes(influxdb3_local, table_batches, args=None): + # here you can see logging. for now this won't do anything, but soon + # we'll capture this so you can query it from system tables + if args and "arg1" in args: + influxdb3_local.info("arg1: " + args["arg1"]) + + # here we're using arguments provided at the time the trigger was set up + # to feed into parameters that we'll put into a query + query_params = {"room": "Kitchen"} + # The following example shows how to execute a parameterized query. Only SQL is supported. + # It queries the database that the trigger is configured for. + query_result = influxdb3_local.query("SELECT * FROM home where room = '$room'", query_params) + # The result is a list of Dict that have the column name as key and value as + # value. + influxdb3_local.info("query result: " + str(query_result)) + + # this is the data that is sent when data is written to the database and flushed to the WAL. + # One batch for each table (will only be one if triggered on a single table) + for table_batch in table_batches: + # here you can see that the table_name is available. + influxdb3_local.info("table: " + table_batch["table_name"]) + + # example to skip the table we're later writing data into + if table_batch["table_name"] == "some_table": + continue + + # and then the individual rows, which are Dict with keys of the column names and values + for row in table_batch["rows"]: + influxdb3_local.info("row: " + str(row)) + + # this shows building a line of LP to write back to the database. tags must go first and + # their order is important and must always be the same for each individual table. Then + # fields and lastly an optional time, which you can see in the next example below + line = LineBuilder("some_table")\ + .tag("tag1", "tag1_value")\ + .tag("tag2", "tag2_value")\ + .int64_field("field1", 1)\ + .float64_field("field2", 2.0)\ + .string_field("field3", "number three") + + # this writes it back (it actually just buffers it until the completion of this function + # at which point it will write everything back that you put in) + influxdb3_local.write(line) + + # here's another example, but with us setting a nanosecond timestamp at the end + other_line = LineBuilder("other_table") + other_line.int64_field("other_field", 1) + other_line.float64_field("other_field2", 3.14) + other_line.time_ns(1302) + + # and you can see that we can write to any DB in the server + influxdb3_local.write_to_db("mytestdb", other_line) + + # just some log output as an example + influxdb3_local.info("done") +``` + +## Test a plugin on the server + +Use the [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/) +CLI command to test your processing engine plugin safely without +affecting actual data. During a plugin test: + +- A query executed by the plugin queries against the server you send the request to. +- Writes aren't sent to the server but are returned to you. + +To test a plugin: + +1. Save the [example plugin code](#example-python-plugin-for-data-writes) to a + plugin file inside of the plugin directory. If you haven't yet written data + to the table in the example, comment out the lines where it queries. +2. To run the test, enter the following command with the following options: + + - `--lp` or `--file`: The line protocol to test + - Optional: `--input-arguments`: A comma-delimited list of `=` arguments for your plugin code + +{{% code-placeholders "INPUT_LINE_PROTOCOL|INPUT_ARGS|DATABASE_NAME|AUTH_TOKEN|PLUGIN_FILENAME" %}} +```bash +influxdb3 test wal_plugin \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + --lp INPUT_LINE_PROTOCOL \ + --input-arguments INPUT_ARGS \ + PLUGIN_FILENAME +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`INPUT_LINE_PROTOCOL`{{% /code-placeholder-key %}}: the line protocol to test +- Optional: {{% code-placeholder-key %}}`INPUT_ARGS`{{% /code-placeholder-key %}}: a comma-delimited list of `=` arguments for your plugin code--for example, `arg1=hello,arg2=world` +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to test against +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server +- {{% code-placeholder-key %}}`PLUGIN_FILENAME`{{% /code-placeholder-key %}}: the name of the plugin file to test + +### Example: Test a plugin + +```bash +# Test a plugin +# Requires: +# - A database named `mydb` with a table named `foo` +# - A Python plugin file named `test.py` +# Test a plugin +influxdb3 test wal_plugin \ + --lp "my_measure,tag1=asdf f1=1.0 123" \ + --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ + --database sensors \ + --input-arguments "arg1=hello,arg2=world" \ + test.py +``` + +The command runs the plugin code with the test data, yields the data to the +plugin code, and then responds with the plugin result. +You can quickly see how the plugin behaves, what data it would have written to +the database, and any errors. +You can then edit your Python code in the plugins directory, and rerun the test. +The server reloads the file for every request to the `test` API. + +For more information, see [`influxdb3 test wal_plugin`](/influxdb3/version/reference/cli/influxdb3/test/wal_plugin/) +or run `influxdb3 test wal_plugin -h`. + +## Create a trigger + +With the plugin code inside the server plugin directory, and a successful test, +you're ready to create a trigger to run the plugin. Use the +[`influxdb3 create trigger` command](/influxdb3/version/reference/cli/influxdb3/create/trigger/) +to create a trigger. + +```bash +# Create a trigger that runs the plugin +influxdb3 create trigger \ + --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ + --database sensors \ + --plugin test_plugin \ + --trigger-spec "table:foo" \ + --trigger-arguments "arg1=hello,arg2=world" \ + trigger1 +``` + +## Enable the trigger + +After you have created a plugin and trigger, enter the following command to +enable the trigger and have it run the plugin as you write data: + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TRIGGER_NAME" %}} +```bash +influxdb3 enable trigger \ + --token AUTH_TOKEN \ + --database DATABASE_NAME \ + TRIGGER_NAME +``` +{{% /code-placeholders %}} + +Replace the following placeholders with your values: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to enable the trigger in +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} +- {{% code-placeholder-key %}}`TRIGGER_NAME`{{% /code-placeholder-key %}}: the name of the trigger to enable + +For example, to enable the trigger named `trigger1` in the `sensors` database: + +```bash +influxdb3 enable trigger \ + --token apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0== \ + --database sensors + trigger1 +``` + +## Next steps + +If you've completed this Get Started guide for {{% product-name %}}, +learn more about tools and options for: + +- [Writing data](/influxdb3/version/write-data/) +- [Querying data](/influxdb3/version/query-data/) +- [Processing data with plugins](/influxdb3/version/plugins/) +- [Visualizing data](/influxdb3/version/visualize-data/) diff --git a/content/shared/influxdb3-get-started/query.md b/content/shared/influxdb3-get-started/query.md new file mode 100644 index 000000000..86c92fd9e --- /dev/null +++ b/content/shared/influxdb3-get-started/query.md @@ -0,0 +1,503 @@ + +{{% 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 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 v2, is **not** supported in InfluxDB 3. + + + +- [Query data with the influxdb3 CLI](#query-data-with-the-influxdb3-cli) + - [Example queries](#example-queries) +- [Other tools for executing queries](#other-tools-for-executing-queries) +- [SQL vs InfluxQL](#sql-vs-influxql) + - [SQL](#sql) + - [InfluxQL](#influxql) +- [Optimize queries](#optimize-queries) + - [Last values cache](#last-values-cache) + - [Distinct values cache](#distinct-values-cache) + {{% show-in "enterprise" %}}- [File indexes](#file-indexes){{% /show-in %}} + + + +## Query data with the influxdb3 CLI + +To get started querying data in {{% product-name %}}, use the +[`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) +and provide the following: + +- `-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 +> [Set up {{% product-name %}}](/influxdb3/version/get-started/setup/#set-your-token-for-authorization) +> isn't set in your environment, set it or provide your token using +> the `-t, --token` option in your command. + +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 \ + "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 {{% 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. + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +influxdb3 query \ + --database DATABASE_NAME \ + "SELECT * FROM home WHERE time >= now() - INTERVAL '7 days' ORDER BY time" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash +influxdb3 query \ + --database DATABASE_NAME \ + --language influxql \ + "SELECT * FROM home WHERE time >= now() - 7d" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-placeholders %}} + +### Example queries + +{{< expand-wrapper >}} +{{% expand "List tables in a database" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SHOW TABLES +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SHOW MEASUREMENTS +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{% expand "Return the average temperature of all rooms" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT avg(temp) AS avg_temp FROM home +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT MEAN(temp) AS avg_temp FROM home +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{% expand "Return the average temperature of the kitchen" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT avg(temp) AS avg_temp FROM home WHERE room = 'Kitchen' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT MEAN(temp) AS avg_temp FROM home WHERE room = 'Kitchen' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{% expand "Query data from an absolute time range" %}} + +{{% influxdb/custom-timestamps %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + * +FROM + home +WHERE + time >= '2022-01-01T12:00:00Z' + AND time <= '2022-01-01T18:00:00Z' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + * +FROM + home +WHERE + time >= '2022-01-01T12:00:00Z' + AND time <= '2022-01-01T18:00:00Z' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{% expand "Query data from a relative time range" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + * +FROM + home +WHERE + time >= now() - INTERVAL '7 days' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + * +FROM + home +WHERE + time >= now() - 7d +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{% expand "Calculate average humidity in 3-hour windows per room" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + date_bin(INTERVAL '3 hours', time) AS time, + room, + avg(hum) AS avg_hum +FROM + home +GROUP BY + 1, + room +ORDER BY + room, + 1 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + MEAN(hum) AS avg_hum +FROM + home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY + time(3h), + room +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Other tools for executing queries + +Other tools are available for querying data in {{% product-name %}}, including +the following: + +{{< expand-wrapper >}} +{{% expand "Query using the API" %}} +#### Query using the API + +InfluxDB 3 supports Flight (gRPC) APIs and an HTTP API. +To query your database using the HTTP API, send a request to the `/api/v3/query_sql` or `/api/v3/query_influxql` endpoints. +In the request, specify the database name in the `db` parameter +and a query in the `q` parameter. +You can pass parameters in the query string or inside a JSON object. + +Use the `format` parameter to specify the response format: `pretty`, `jsonl`, `parquet`, `csv`, and `json`. Default is `json`. + +##### Example: Query passing URL-encoded parameters + +The following example sends an HTTP `GET` request with a URL-encoded SQL query: + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```bash +curl -G "http://{{< influxdb/host >}}/api/v3/query_sql" \ + --header 'Authorization: Bearer AUTH_TOKEN' \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=select * from cpu limit 5" +``` +{{% /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 %}} + +##### Example: Query passing JSON parameters + +The following example sends an HTTP `POST` request with parameters in a JSON payload: + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```bash +curl http://{{< influxdb/host >}}/api/v3/query_sql \ + --data '{"db": "DATABASE_NAME", "q": "select * from cpu limit 5"}' +``` +{{% /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 %}} + +{{% /expand %}} + +{{% expand "Query using the Python client" %}} + +#### Query using the Python client + +Use the InfluxDB 3 Python library to interact with the database and integrate with your application. +We recommend installing the required packages in a Python virtual environment for your specific project. + +To get started, install the `influxdb3-python` package. + +```bash +pip install influxdb3-python +``` + +From here, you can connect to your database with the client library using just the **host** and **database name: + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```python +from influxdb_client_3 import InfluxDBClient3 + +client = InfluxDBClient3( + token='AUTH_TOKEN', + host='http://{{< influxdb/host >}}', + database='DATABASE_NAME' +) +``` +{{% /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 %}} + +The following example shows how to query using SQL, and then +use PyArrow to explore the schema and process results. +To authorize the query, the example retrieves the {{% token-link "database" %}} +from the `INFLUXDB3_AUTH_TOKEN` environment variable. + +```python +from influxdb_client_3 import InfluxDBClient3 +import os + +client = InfluxDBClient3( + token=os.environ.get('INFLUXDB3_AUTH_TOKEN'), + host='http://{{< influxdb/host >}}', + database='servers' +) + +# Execute the query and return an Arrow table +table = client.query( + query="SELECT * FROM cpu LIMIT 10", + language="sql" +) + +print("\n#### View Schema information\n") +print(table.schema) + +print("\n#### Use PyArrow to read the specified columns\n") +print(table.column('usage_active')) +print(table.select(['host', 'usage_active'])) +print(table.select(['time', 'host', 'usage_active'])) + +print("\n#### Use PyArrow compute functions to aggregate data\n") +print(table.group_by('host').aggregate([])) +print(table.group_by('cpu').aggregate([('time_system', 'mean')])) +``` + +For more information about the Python client library, see the +[`influxdb3-python` repository](https://github.com/InfluxCommunity/influxdb3-python) +in GitHub. + +{{% /expand %}} + +{{% expand "Query using InfluxDB 3 Explorer" %}} + +#### Query using InfluxDB 3 Explorer + +You can use the InfluxDB 3 Explorer web-based interface to query and visualize data, +and administer your {{% product-name %}} instance. +For more information, see how to [install InfluxDB 3 Explorer](/influxdb3/explorer/install/) +using Docker and get started querying your data. + +{{% /expand %}} +{{< /expand-wrapper >}} + +## SQL vs InfluxQL + +{{% product-name %}} supports two query languages--SQL and InfluxQL. +While these two query languages are similar, there are important differences to +consider. + +### SQL + +The InfluxDB 3 SQL implementation provides a full-featured SQL query engine +powered by [Apache DataFusion](https://datafusion.apache.org/). InfluxDB extends +DataFusion with additional time series-specific functionality and supports the +complex SQL queries, including queries that use joins, unions, window functions, +and more. + +- [SQL query guides](/influxdb3/version/query-data/sql/) +- [SQL reference](/influxdb3/version/reference/sql/) +- [Apache DataFusion SQL reference](https://datafusion.apache.org/user-guide/sql/index.html) + +### InfluxQL + +InfluxQL is a SQL-like query language built for InfluxDB v1 and supported in +{{% product-name %}}. Its syntax and functionality is similar SQL, but specifically +designed for querying time series data. InfluxQL does not offer the full range +of query functionality that SQL does. + +If you are migrating from previous versions of InfluxDB, you can continue to use +InfluxQL and the established InfluxQL-related APIs you have been using. + +- [InfluxQL query guides](/influxdb3/version/query-data/influxql/) +- [InfluxQL reference](/influxdb3/version/reference/influxql/) +- [InfluxQL feature support](/influxdb3/version/reference/influxql/feature-support/) + +## Optimize queries + +{{% product-name %}} provides the following optimization options to improve +specific kinds of queries: + +- [Last values cache](#last-values-cache) +- [Distinct values cache](#distinct-values-cache) +{{% show-in "enterprise" %}}- [File indexes](#file-indexes){{% /show-in %}} + +### Last values cache + +The {{% product-name %}} last values cache (LVC) stores the last N values in a +series or column hierarchy in memory. This gives the database the ability to +answer these kinds of queries in under 10 milliseconds. +For information about configuring and using the LVC, see: + +- [Manage a last values cache](/influxdb3/version/admin/last-value-cache/) +- [Query the last values cache](/influxdb3/version/admin/last-value-cache/query/) + +### Distinct values cache + +The {{% product-name %}} distinct values cache (DVC) stores distinct values for +specified columns in a series or column hierarchy in memory. +This is useful for fast metadata lookups, which can return in under 30 milliseconds. +For information about configuring and using the DVC, see: + +- [Manage a distinct values cache](/influxdb3/version/admin/distinct-value-cache/) +- [Query the distinct values cache](/influxdb3/version/admin/distinct-value-cache/query/) + +{{% show-in "enterprise" %}} +### File indexes + +{{% product-name %}} lets you customize how your data is indexed to help +optimize query performance for your specific workload, especially workloads that +include single-series queries. Define custom indexing strategies for databases +or specific tables. For more information, see +[Manage file indexes](/influxdb3/enterprise/admin/file-index/). + +{{% /show-in %}} + +{{% page-nav + prev="/influxdb3/version/get-started/write/" + prevText="Write data" + next="/influxdb3/version/get-started/process/" + nextText="Processing engine" +%}} diff --git a/content/shared/influxdb3-get-started/setup.md b/content/shared/influxdb3-get-started/setup.md new file mode 100644 index 000000000..e8a3aa83f --- /dev/null +++ b/content/shared/influxdb3-get-started/setup.md @@ -0,0 +1,541 @@ + +- [Prerequisites](#prerequisites) +- [Start InfluxDB](#start-influxdb) + - [Object store examples](#object-store-examples) +{{% show-in "enterprise" %}} +- [Set up licensing](#set-up-licensing) + - [Available license types](#available-license-types) +{{% /show-in %}} +- [Set up authorization](#set-up-authorization) + - [Create an operator token](#create-an-operator-token) + - [Set your token for authorization](#set-your-token-for-authorization) + + + +## Prerequisites + +To get started, you'll need: + +- **{{% product-name %}}**: [Install and verify the latest version](/influxdb3/version/install/) on your system. +- If you want to persist data, have access to one of the following: + - A directory on your local disk where you can persist data (used by examples in this guide) + - S3-compatible object store and credentials + +## Start InfluxDB + +Use the [`influxdb3 serve` command](/influxdb3/version/reference/cli/influxdb3/serve/) +to start {{% product-name %}}. +Provide the following: + +{{% 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: + `//`. + In a multi-node setup, this ID is used to reference specific nodes. +- `--cluster-id`: A string identifier that determines part of the storage path + hierarchy. All nodes within the same cluster share this identifier. + 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`: 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 + +- Other object store parameters depending on the selected `object-store` type. + For example, if you use `s3`, you must provide the bucket name and credentials. + +> [!Note] +> #### Diskless architecture +> +> InfluxDB 3 supports a diskless architecture that can operate with object +> storage alone, eliminating the need for locally attached disks. +> {{% product-name %}} can also work with only local disk storage when needed. +> +> {{% show-in "enterprise" %}} +> The combined path structure `//` ensures +> proper organization of data in your object store, allowing for clean +> 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. + +{{% 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 %}} + +### Object store examples + +{{< expand-wrapper >}} +{{% expand "File system object store" %}} + +Store data in a specified directory on the local filesystem. +This is the default object store type. + +Replace the following with your values: + +{{% show-in "enterprise" %}} +```bash +# Filesystem 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 %}} + +{{% /expand %}} +{{% expand "Docker with a mounted file system object store" %}} + +To run the [Docker image](/influxdb3/version/install/#docker-image) and persist +data to the local file system, mount a volume for the object store--for example, +provide the following options with your `docker run` command: + +- `--volume /path/on/host:/path/in/container`: Mounts a directory from your file system to the container +- `--object-store file --data-dir /path/in/container`: Use the volume mount for object storage + +{{% show-in "enterprise" %}} + +```bash +# File system object store with Docker +# Create a mount +# Provide the mount path +docker run -it \ + --volume /path/on/host:/path/in/container \ + influxdb:3-enterprise influxdb3 serve \ + --node-id my_host \ + --cluster-id my_cluster \ + --object-store file \ + --data-dir /path/in/container +``` +{{% /show-in %}} +{{% show-in "core" %}} + +```bash +# File system object store with Docker +# Create a mount +# Provide the mount path +docker run -it \ + --volume /path/on/host:/path/in/container \ + influxdb:3-core influxdb3 serve \ + --node-id my_host \ + --object-store file \ + --data-dir /path/in/container +``` +{{% /show-in %}} + +> [!Note] +> +> The {{% product-name %}} Docker image exposes port `8181`, the `influxdb3` +> server default for HTTP connections. +> To map the exposed port to a different port when running a container, see the +> Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/). + +{{% /expand %}} +{{% expand "Docker compose with a mounted file system object store" %}} +{{% show-in "enterprise" %}} +1. Open `compose.yaml` for editing and add a `services` entry for {{% product-name %}}. + --for example: + + ```yaml + # compose.yaml + services: + influxdb3-{{< product-key >}}: + container_name: influxdb3-{{< product-key >}} + image: influxdb:3-{{< product-key >}} + ports: + - 8181:8181 + command: + - influxdb3 + - serve + - --node-id=node0 + - --cluster-id=cluster0 + - --object-store=file + - --data-dir=/var/lib/influxdb3 + - --plugin-dir=/var/lib/influxdb3-plugins + environment: + - INFLUXDB3_LICENSE_EMAIL=EMAIL_ADDRESS + ``` + _Replace `EMAIL_ADDRESS` with your email address to bypass the email prompt + when generating a trial or at-home license. For more information, see [Manage your + {{% product-name %}} license](/influxdb3/version/admin/license/)_. +{{% /show-in %}} +{{% show-in "core" %}} +1. Open `compose.yaml` for editing and add a `services` entry for {{% product-name %}}--for example: + + ```yaml + # compose.yaml + services: + influxdb3-{{< product-key >}}: + container_name: influxdb3-{{< product-key >}} + image: influxdb:3-{{< product-key >}} + ports: + - 8181:8181 + command: + - influxdb3 + - serve + - --node-id=node0 + - --object-store=file + - --data-dir=/var/lib/influxdb3 + - --plugin-dir=/var/lib/influxdb3-plugins + ``` +{{% /show-in %}} + +2. Use the Docker Compose CLI to start the server. + + Optional: to make sure you have the latest version of the image before you + start the server, run `docker compose pull`. + + + ```bash + docker compose pull && docker compose run influxdb3-{{< product-key >}} + ``` + +InfluxDB 3 starts in a container with host port `8181` mapped to container port +`8181`, the `influxdb3` server default for HTTP connections. + +> [!Tip] +> #### Custom port mapping +> +> To customize your `influxdb3` server hostname and port, specify the +> [`--http-bind` option or the `INFLUXDB3_HTTP_BIND_ADDR` environment variable](/influxdb3/version/reference/config-options/#http-bind). +> +> For more information about mapping your container port to a specific host port, see the +> Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/). + +> [!Note] +> #### Stopping an InfluxDB 3 container +> +> To stop a running InfluxDB 3 container, find and terminate the process or container--for example: +> +> +> ```bash +> docker container ls --filter "name=influxdb3" +> docker kill +> ``` +> +> _Currently, a bug prevents using {{< keybind all="Ctrl+c" >}} in the terminal to stop an InfluxDB 3 container._ +{{% /expand %}} +{{% expand "S3 object storage" %}} + +Store data in an S3-compatible object store. +This is useful for production deployments that require high availability and durability. +Provide your bucket name and credentials to access the S3 object store. + +{{% show-in "enterprise" %}} +```bash +# S3 object store (default is the us-east-1 region) +# Specify the object store type and associated options +influxdb3 serve \ + --node-id host01 \ + --cluster-id cluster01 \ + --object-store s3 \ + --bucket OBJECT_STORE_BUCKET \ + --aws-access-key AWS_ACCESS_KEY_ID \ + --aws-secret-access-key AWS_SECRET_ACCESS_KEY +``` + +```bash +# Minio or other open source object store +# (using the AWS S3 API with additional parameters) +# Specify the object store type and associated options +influxdb3 serve \ + --node-id host01 \ + --cluster-id cluster01 \ + --object-store s3 \ + --bucket OBJECT_STORE_BUCKET \ + --aws-access-key-id AWS_ACCESS_KEY_ID \ + --aws-secret-access-key AWS_SECRET_ACCESS_KEY \ + --aws-endpoint ENDPOINT \ + --aws-allow-http +``` +{{% /show-in %}} +{{% show-in "core" %}} +```bash +# S3 object store (default is the us-east-1 region) +# Specify the object store type and associated options +influxdb3 serve \ + --node-id host01 \ + --object-store s3 \ + --bucket OBJECT_STORE_BUCKET \ + --aws-access-key AWS_ACCESS_KEY_ID \ + --aws-secret-access-key AWS_SECRET_ACCESS_KEY +``` + +```bash +# Minio or other open source object store +# (using the AWS S3 API with additional parameters) +# Specify the object store type and associated options +influxdb3 serve \ + --node-id host01 \ + --object-store s3 \ + --bucket OBJECT_STORE_BUCKET \ + --aws-access-key-id AWS_ACCESS_KEY_ID \ + --aws-secret-access-key AWS_SECRET_ACCESS_KEY \ + --aws-endpoint ENDPOINT \ + --aws-allow-http +``` +{{% /show-in %}} + +{{% /expand %}} +{{% expand "Memory-based object store" %}} + +Store data in RAM without persisting it on shutdown. +It's useful for rapid testing and development. + +{{% show-in "enterprise" %}} +```bash +# Memory object store +# Stores data in RAM; doesn't persist data +influxdb3 serve \ + --node-id host01 \ + --cluster-id cluster01 \ + --object-store memory +``` +{{% /show-in %}} +{{% show-in "core" %}} +```bash +# Memory object store +# Stores data in RAM; doesn't persist data +influxdb3 serve \ + --node-id host01 \ + --object-store memory +``` +{{% /show-in %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +For more information about server options, use the CLI help or view the +[InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/influxdb3/serve/): + +```bash +influxdb3 serve --help +``` + +{{% show-in "enterprise" %}} +## Set up licensing + +When you first start a new instance, {{% product-name %}} prompts you to select a +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. +- **Commercial**: Commercial license with full access to InfluxDB 3 Enterprise capabilities. + +> [!Important] +> #### Trial and at-home licenses with Docker +> +> To generate the trial or home license in Docker, bypass the email prompt. +> The first time you start a new instance, provide your email address with the +> `--license-email` option or the `INFLUXDB3_LICENSE_EMAIL` environment variable. +> +> _Currently, if you use Docker and enter your email address in the prompt, a bug may +> prevent the container from generating the license ._ +> +> For more information, see [the Docker Compose example](/influxdb3/enterprise/admin/license/?t=Docker+compose#start-the-server-with-your-license-email). +{{% /show-in %}} + +> [!Tip] +> #### Use the InfluxDB 3 Explorer query interface (beta) +> +> You can complete the remaining steps in this guide using InfluxDB 3 Explorer +> (currently in beta), the web-based query and administrative interface for InfluxDB 3. +> Explorer provides visual management of databases and tokens and an +> easy way to write and query your time series data. +> +> For more information, see the [InfluxDB 3 Explorer documentation](/influxdb3/explorer/). + +## Set up authorization + +{{% product-name %}} uses token-based authorization to authorize actions in the +database. Authorization is enabled by default when you start the server. +With authorization enabled, you must provide a token with `influxdb3` CLI +commands and HTTP API requests. + +{{% show-in "enterprise" %}} +{{% product-name %}} supports the following types of tokens: + +- **admin token**: Grants access to all CLI actions and API endpoints. +- **resource tokens**: Tokens that grant read and write access to specific + resources (databases and system information endpoints) on the server. + + - A database token grants access to write and query data in a + database + - A system token grants read access to system information endpoints and + metrics for the server +{{% /show-in %}} +{{% show-in "core" %}} +{{% product-name %}} supports _admin_ tokens, which grant access to all CLI actions and API endpoints. +{{% /show-in %}} + +For more information about tokens and authorization, see [Manage tokens](/influxdb3/version/admin/tokens/). + +### Create an operator token + +After you start the server, create your first admin token. +The first admin token you create is the _operator_ token for the server. + +Use the [`influxdb3 create token` command](/influxdb3/version/reference/cli/influxdb3/create/token/) +with the `--admin` option to create your operator token: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[CLI](#) +[Docker](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash +influxdb3 create token --admin +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-placeholders "CONTAINER_NAME" %}} +```bash +# With Docker — in a new terminal: +docker exec -it CONTAINER_NAME influxdb3 create token --admin +``` +{{% /code-placeholders %}} + +Replace {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}} with the name of your running Docker container. + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +The command returns a token string for authenticating CLI commands and API requests. + +> [!Important] +> #### Store your token securely +> +> InfluxDB displays the token string only when you create it. +> Store your token securely—you cannot retrieve it from the database later. + +### Set your token for authorization + +Use your operator token to authenticate server actions in {{% product-name %}}, +such as {{% show-in "enterprise" %}}creating additional tokens, {{% /show-in %}} +performing administrative tasks{{% show-in "enterprise" %}},{{% /show-in %}} +and writing and querying data. + +Use one of the following methods to provide your token and authenticate `influxdb3` CLI commands. + +In your command, replace {{% code-placeholder-key %}}`YOUR_AUTH_TOKEN`{{% /code-placeholder-key %}} with your token string (for example, the [operator token](#create-an-operator-token) from the previous step). + +{{< tabs-wrapper >}} +{{% tabs %}} +[Environment variable (recommended)](#) +[Command option](#) +{{% /tabs %}} +{{% tab-content %}} + +Set the `INFLUXDB3_AUTH_TOKEN` environment variable to have the CLI use your +token automatically: + +{{% code-placeholders "YOUR_AUTH_TOKEN" %}} +```bash +export INFLUXDB3_AUTH_TOKEN=YOUR_AUTH_TOKEN +``` +{{% /code-placeholders %}} + +{{% /tab-content %}} +{{% tab-content %}} + +Include the `--token` option with CLI commands: + +{{% code-placeholders "YOUR_AUTH_TOKEN" %}} +```bash +influxdb3 show databases --token YOUR_AUTH_TOKEN +``` +{{% /code-placeholders %}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +For HTTP API requests, include your token in the `Authorization` header--for example: + +{{% code-placeholders "YOUR_AUTH_TOKEN" %}} +```bash +curl "http://{{< influxdb/host >}}/api/v3/configure/database" \ + --header "Authorization: Bearer YOUR_AUTH_TOKEN" +``` +{{% /code-placeholders %}} + +#### Learn more about tokens and permissions + +- [Manage admin tokens](/influxdb3/version/admin/tokens/admin/) - Understand and + manage operator and named admin tokens +{{% show-in "enterprise" %}} +- [Manage resource tokens](/influxdb3/version/admin/tokens/resource/) - Create, + list, and delete resource tokens +{{% /show-in %}} +- [Authentication](/influxdb3/version/reference/internals/authentication/) - + Understand authentication, authorizations, and permissions in {{% product-name %}} + +{{% show-in "core" %}} +{{% page-nav + prev="/influxdb3/version/get-started/" + prevText="Get started" + next="/influxdb3/version/get-started/write/" + nextText="Write data" +%}} +{{% /show-in %}} +{{% show-in "enterprise" %}} +{{% page-nav + prev="/influxdb3/version/get-started/" + prevText="Get started" + next="/influxdb3/version/get-started/multi-server/" + nextText="Create a multi-node cluster" +%}} +{{% /show-in %}} diff --git a/content/shared/influxdb3-get-started/write.md b/content/shared/influxdb3-get-started/write.md new file mode 100644 index 000000000..0f5d775f2 --- /dev/null +++ b/content/shared/influxdb3-get-started/write.md @@ -0,0 +1,252 @@ + + +{{% 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] +> #### 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. +> For extended historical queries and optimized data organization, consider using [InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/). +{{% /show-in %}} + + + +- [Line protocol](#line-protocol) +- [Construct line protocol](#construct-line-protocol) +- [Write data using the CLI](#write-data-using-the-cli) +- [Other tools for writing data](#other-tools-for-writing-data) + + + +## Line protocol + +{{% product-name %}} accepts data in +[line protocol](/influxdb3/version/reference/syntax/line-protocol/) syntax. +Line protocol consists of the following elements: + + + +{{< req type="key" >}} + +- {{< req "\*" >}} **table**: A string that identifies the + [table](/influxdb3/version/reference/glossary/#table) to store the data in. +- **tag set**: Comma-delimited list of key value pairs, each representing a tag. + Tag keys and values are unquoted strings. _Spaces, commas, and equal characters + must be escaped._ +- {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each + representing a field. + Field keys are unquoted strings. _Spaces and commas must be escaped._ + Field values can be one of the following types: + + - [strings](/influxdb3/clustered/reference/syntax/line-protocol/#string) (quoted) + - [floats](/influxdb3/clustered/reference/syntax/line-protocol/#float) + - [integers](/influxdb3/clustered/reference/syntax/line-protocol/#integer) + - [unsigned integers](/influxdb3/clustered/reference/syntax/line-protocol/#uinteger) + - [booleans](/influxdb3/clustered/reference/syntax/line-protocol/#boolean) + +- **timestamp**: [Unix timestamp](/influxdb3/clustered/reference/syntax/line-protocol/#unix-timestamp) +associated with the data. InfluxDB supports up to nanosecond precision. + + +{{< expand-wrapper >}} +{{% expand "How are InfluxDB line protocol elements parsed?" %}} + + + +- **table**: Everything before the _first unescaped comma before the first + whitespace_. +- **tag set**: Key-value pairs between the _first unescaped comma_ and the _first + unescaped whitespace_. +- **field set**: Key-value pairs between the _first and second unescaped whitespaces_. +- **timestamp**: Integer value after the _second unescaped whitespace_. +- Lines are separated by the newline character (`\n`). Line protocol is +whitespace sensitive. + + +{{% /expand %}} +{{< /expand-wrapper >}} + +_For schema design recommendations, see +[InfluxDB schema design recomendations](/influxdb3/version/write-data/best-practices/schema-design/)._ + +--- + +{{< influxdb/line-protocol version="v3" >}} + +--- + +## Construct line protocol + + + +With a basic understanding of line protocol, you can now construct line protocol +and write data to {{% product-name %}}. +Consider a use case where you collect data from sensors in your home. +Each sensor collects temperature, humidity, and carbon monoxide readings. +To collect this data, use the following schema: + +- **table**: `home` + - **tags** + - `room`: Living Room or Kitchen + - **fields** + - `temp`: temperature in °C (float) + - `hum`: percent humidity (float) + - `co`: carbon monoxide in parts per million (integer) + - **timestamp**: Unix timestamp in _second_ precision + + +The following line protocol sample represents data collected hourly beginning at +{{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}. +_These timestamps are dynamic and can be updated by clicking the {{% icon "clock" %}} +icon in the bottom right corner._ + +{{% influxdb/custom-timestamps %}} + +##### Home sensor data line protocol + +```text +home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 +home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 +home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 +home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 +home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 +home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 +home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 +home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 +home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 +home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 +home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 +home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 +home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 +home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 +home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 +``` + +{{% /influxdb/custom-timestamps %}} + +## Write data using the CLI + +To quickly get started writing data, use the +[`influxdb3 write` command](/influxdb3/version/reference/cli/influxdb3/write/). +Include the following: + +- `--database` option that identifies the target database +- `--token` option that specifies the token to use _(unless the `INFLUXDB3_AUTH_TOKEN` + environment variable is already set)_ +- Quoted line protocol data via standard input (stdin) + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```bash +influxdb3 write \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + --precision s \ +'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 +home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 +home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 +home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 +home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 +home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 +home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 +home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 +home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 +home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 +home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 +home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 +home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 +home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 +home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200' +``` +{{% /code-placeholders %}} + +In the code samples, replace the following placeholders with your values: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of the [database](/influxdb3/version/admin/databases/) to write to +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission + to write to the specified database{{% /show-in %}} + +### Write data from a file + +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: + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```bash +influxdb3 write \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + --precision s \ + --accept-partial \ + --file path/to/sensor_data +``` +{{% /code-placeholders %}} + +Replace the following placeholders with your values: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/version/admin/databases/) to write to. +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to write to the specified database{{% /show-in %}} + +## Other tools for writing data + +There are many ways to write data to your {{% product-name %}} database, including: + +- [InfluxDB HTTP API](/influxdb3/version/write-data/http-api/): Recommended for + batching and higher-volume write workloads. +- [InfluxDB client libraries](/influxdb3/version/write-data/client-libraries/): + Client libraries that integrate with your code to construct data as time + series points and write the data as line protocol to your + {{% product-name %}} database. +- [Telegraf](/telegraf/v1/): A data collection agent with over 300 plugins for + collecting, processing, and writing data. + +For more information, see [Write data to {{% product-name %}}](/influxdb3/version/write-data/). + +{{% show-in "enterprise" %}} +{{% page-nav + prev="/influxdb3/version/get-started/multi-server/" + prevText="Create a multi-node cluster" + next="/influxdb3/version/get-started/query/" + nextText="Query data" +%}} +{{% /show-in %}} + +{{% show-in "core" %}} +{{% page-nav + prev="/influxdb3/version/get-started/setup/" + prevText="Set up InfluxDB" + next="/influxdb3/version/get-started/query/" + nextText="Query data" +%}} +{{% /show-in %}} diff --git a/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md b/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md index e0a296c5b..810c075ae 100644 --- a/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md +++ b/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md @@ -21,12 +21,6 @@ Provide the following with your request: - **Headers:** - **Authorization:** `Bearer AUTH_TOKEN` - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization - > token. You can either omit this header or include it with an arbitrary - > token string. - - **Query parameters:** - **db**: the database to query - **rp**: Optional: the retention policy to query @@ -44,9 +38,9 @@ curl --get https://{{< influxdb/host >}}/query \ Replace the following configuration values: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: - the name of the database to query + the name of the [database](/influxdb3/version/admin/databases/) to query - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your authorization token + your {{< product-name >}} {{% token-link %}}{{% show-in "enterprise" %}} with read access to the database{{% /show-in %}} ## Return results as JSON or CSV @@ -57,7 +51,7 @@ with the `application/csv` or `text/csv` MIME type: {{% code-placeholders "(DATABASE|AUTH)_(NAME|TOKEN)" %}} ```sh curl --get https://{{< influxdb/host >}}/query \ - --header "Authorization: BEARER AUTH_TOKEN" \ + --header "Authorization: Bearer AUTH_TOKEN" \ --header "Accept: application/csv" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM home" diff --git a/content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md b/content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md index a8ab9d018..ef8f0c6a1 100644 --- a/content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md +++ b/content/shared/influxdb3-query-guides/execute-queries/influxdb3-api.md @@ -35,7 +35,8 @@ Include the following parameters: The following example sends an HTTP `GET` request with a URL-encoded SQL query: ```bash -curl -v "http://{{< influxdb/host >}}/api/v3/query_sql?db=servers&q=select+*+from+cpu+limit+5" +curl "http://{{< influxdb/host >}}/api/v3/query_sql?db=servers&q=select+*+from+cpu+limit+5" \ + --header "Authorization: Bearer AUTH_TOKEN" ``` ### Example: Query passing JSON parameters @@ -44,7 +45,8 @@ The following example sends an HTTP `POST` request with parameters in a JSON pay ```bash curl http://{{< influxdb/host >}}/api/v3/query_sql \ - --data '{"db": "server", "q": "select * from cpu limit 5"}' + --header "Authorization: Bearer AUTH_TOKEN" + --json '{"db": "server", "q": "select * from cpu limit 5"}' ``` ### Query system information @@ -71,7 +73,8 @@ tables (`"table_schema":"iox"`), system tables, and information schema tables for a database: ```bash -curl "http://{{< influxdb/host >}}/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables" +curl "http://{{< influxdb/host >}}/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables" \ + --header "Authorization: Bearer AUTH_TOKEN" ``` The response body contains the following JSONL: @@ -117,7 +120,7 @@ that surround field names._ ```bash curl "http://localhost:8181/api/v3/query_sql" \ - --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "mydb", "q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'", @@ -144,7 +147,7 @@ To view recently executed queries, query the `queries` system table: ```bash curl "http://localhost:8181/api/v3/query_sql" \ - --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ --json '{ "db": "mydb", "q": "SELECT * FROM system.queries LIMIT 2", @@ -180,7 +183,8 @@ Include the following parameters: The following example sends an HTTP `GET` request with a URL-encoded InfluxQL query: ```bash -curl -v "http://{{< influxdb/host >}}/api/v3/query_influxql?db=servers&q=select+*+from+cpu+limit+5" +curl "http://{{< influxdb/host >}}/api/v3/query_influxql?db=servers&q=select+*+from+cpu+limit+5" \ + --header "Authorization: Bearer AUTH_TOKEN" ``` ### Example: Query passing JSON parameters @@ -189,5 +193,6 @@ The following example sends an HTTP `POST` request with parameters in a JSON pay ```bash curl http://{{< influxdb/host >}}/api/v3/query_influxql \ - --data '{"db": "server", "q": "select * from cpu limit 5"}' + --header "Authorization: Bearer AUTH_TOKEN" \ + --json '{"db": "server", "q": "select * from cpu limit 5"}' ``` \ No newline at end of file diff --git a/content/shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md b/content/shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md index 49468f277..23edcb6c1 100644 --- a/content/shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md +++ b/content/shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md @@ -4,12 +4,12 @@ to query data in {{< product-name >}} with SQL or InfluxQL. Provide the following with your command: - + - `INFLUXDB3_AUTH_TOKEN` environment variable - **Database name**: The name of the database to query. Provide this using one of the following: @@ -53,6 +53,7 @@ Provide the following with your command: ```bash influxdb3 query \ + --token AUTH_TOKEN \ --database DATABASE_NAME \ "SELECT * FROM home" ``` @@ -62,6 +63,7 @@ influxdb3 query \ ```bash influxdb3 query \ + --token AUTH_TOKEN \ --database DATABASE_NAME \ --file ./query.sql ``` @@ -70,7 +72,7 @@ influxdb3 query \ ```bash -cat ./query.sql | influxdb3 query --database DATABASE_NAME +cat ./query.sql | influxdb3 query --token AUTH_TOKEN --database DATABASE_NAME ``` {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} @@ -94,6 +96,7 @@ cat ./query.sql | influxdb3 query --database DATABASE_NAME ```bash influxdb3 query \ + --token AUTH_TOKEN \ --language influxql \ --database DATABASE_NAME \ "SELECT * FROM home" @@ -104,8 +107,8 @@ influxdb3 query \ ```bash influxdb3 query \ + --token AUTH_TOKEN \ --language influxql \ - --database DATABASE_NAME \ --file ./query.influxql ``` {{% /code-tab-content %}} @@ -114,6 +117,7 @@ influxdb3 query \ ```bash cat ./query.influxql | influxdb3 query \ + --token AUTH_TOKEN \ --language influxql \ --database DATABASE_NAME ``` @@ -150,6 +154,7 @@ Use the `--format` flag to specify the output format: {{% influxdb/custom-timestamps %}} ```sh influxdb3 query \ + --token AUTH_TOKEN \ --database DATABASE_NAME \ --format json \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" @@ -217,6 +222,7 @@ the `influxdb3 query` command: {{% influxdb/custom-timestamps %}} ```sh influxdb3 query \ + --token AUTH_TOKEN \ --database DATABASE_NAME \ --format parquet \ --output path/to/results.parquet \ diff --git a/content/shared/influxdb3-sample-data/sample-data.md b/content/shared/influxdb3-sample-data/sample-data.md index 885a1f081..213806595 100644 --- a/content/shared/influxdb3-sample-data/sample-data.md +++ b/content/shared/influxdb3-sample-data/sample-data.md @@ -216,21 +216,16 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 Replace the following in the sample script: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: - the name of database to write to + the name of [database](/influxdb3/version/admin/databases/) to write to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > You can either omit the CLI `--token` option or the HTTP `Authorization` header or - > you can provide an arbitrary token string. + your {{< product-name >}} {{% token-link %}} {{% /expand %}} {{< /expand-wrapper >}} ## Home sensor actions data -Includes hypothetical actions triggered by data in the [Get started home sensor data](#get-started-home-sensor-data) +Includes hypothetical actions triggered by data in the [home sensor data](#home-sensor-data) and is a companion dataset to that sample dataset. To customize timestamps in the dataset, use the {{< icon "clock" >}} button in the lower right corner of the page. @@ -371,12 +366,7 @@ Replace the following in the sample script: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of database to write to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > You can either omit the CLI `--token` option or the HTTP `Authorization` header or - > you can provide an arbitrary token string. + your {{< product-name >}} {{% token-link %}} {{% /expand %}} {{< /expand-wrapper >}} @@ -478,12 +468,7 @@ Replace the following in the sample script: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of database to write to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > You can either omit the CLI `--token` option or the HTTP `Authorization` header or - > you can provide an arbitrary token string. + your {{< product-name >}} {{% token-link %}} {{% /expand %}} {{< /expand-wrapper >}} @@ -575,12 +560,7 @@ Replace the following in the sample script: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of database to write to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > You can either omit the CLI `--token` option or the HTTP `Authorization` header or - > you can provide an arbitrary token string. + your {{< product-name >}} {{% token-link %}} {{% /expand %}} {{< /expand-wrapper >}} @@ -674,12 +654,7 @@ Replace the following in the sample script: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of database to write to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > You can either omit the CLI `--token` option or the HTTP `Authorization` header or - > you can provide an arbitrary token string. + your {{< product-name >}} {{% token-link %}} {{% /expand %}} {{< /expand-wrapper >}} diff --git a/content/shared/influxdb3-visualize/grafana.md b/content/shared/influxdb3-visualize/grafana.md index 785e4676f..06dbf82bc 100644 --- a/content/shared/influxdb3-visualize/grafana.md +++ b/content/shared/influxdb3-visualize/grafana.md @@ -69,13 +69,6 @@ When creating an InfluxDB data source that uses SQL to query data: - **Database**: Provide a default database name to query. - **Token**: Provide an arbitrary, non-empty string. - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > However, if you included a `--token` option or defined the - > `INFLUXDB3_AUTH_TOKEN` environment variable when starting your - > {{< product-name >}} server, provide that token. - - **Insecure Connection**: If _not_ using HTTPS, enable this option. 3. Click **Save & test**. @@ -103,11 +96,6 @@ When creating an InfluxDB data source that uses InfluxQL to query data: - **User**: Provide an arbitrary string. _This credential is ignored when querying {{% product-name %}}, but it cannot be empty._ - **Password**: Provide an arbitrary string. - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization - > token, but the **Password** field does require a value. - - **HTTP Method**: Choose one of the available HTTP request methods to use when querying data: - **POST** ({{< req text="Recommended" >}}) diff --git a/content/shared/influxdb3-visualize/superset.md b/content/shared/influxdb3-visualize/superset.md index 5513fbc22..dbe0baaa2 100644 --- a/content/shared/influxdb3-visualize/superset.md +++ b/content/shared/influxdb3-visualize/superset.md @@ -211,11 +211,8 @@ a database connection. **Query parameters** - - **`?database`**: URL-encoded InfluxDB database name - - **`?token`**: InfluxDB authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. + - **`?database`**: URL-encoded [database](/influxdb3/version/admin/databases/) name + - **`?token`**: {{< product-name >}} {{% token-link %}} {{< code-callout "<(domain|port|database-name|token)>" >}} {{< code-callout "localhost|8181|example-database|example-token" >}} diff --git a/content/shared/influxdb3-visualize/tableau.md b/content/shared/influxdb3-visualize/tableau.md index 27973cdcc..d3a2a80af 100644 --- a/content/shared/influxdb3-visualize/tableau.md +++ b/content/shared/influxdb3-visualize/tableau.md @@ -67,10 +67,6 @@ the **Flight SQL JDBC driver**. - **Dialect**: PostgreSQL - **Username**: _Leave empty_ - **Password**: _Leave empty_ - - > [!Note] - > While in beta, {{< product-name >}} does not require authorization tokens. - - **Properties File**: _Leave empty_ 4. Click **Sign In**. diff --git a/content/shared/influxdb3-write-guides/_index.md b/content/shared/influxdb3-write-guides/_index.md index f95c94b7a..eb743e572 100644 --- a/content/shared/influxdb3-write-guides/_index.md +++ b/content/shared/influxdb3-write-guides/_index.md @@ -15,8 +15,9 @@ to line protocol. > > #### Choose the write endpoint for your workload > -> When creating new write workloads, use the HTTP API -> [`/api/v3/write_lp` endpoint with client libraries](/influxdb3/version/write-data/api-client-libraries/). +> When creating new write workloads, use the +> [InfluxDB HTTP API `/api/v3/write_lp` endpoint](influxdb3/version/write-data/http-api/v3-write-lp/) +> and [client libraries](/influxdb3/version/write-data/client-libraries/). > > When bringing existing v1 write workloads, use the {{% product-name %}} > HTTP API [`/write` endpoint](/influxdb3/core/api/v3/#operation/PostV1Write). diff --git a/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md b/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md index 6abfdd5c7..2441b414e 100644 --- a/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md +++ b/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md @@ -162,14 +162,9 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}} _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > You can either omit the `Authorization` header or you can provide an - > arbitrary token string. - {{% /tab-content %}} {{< /tabs-wrapper >}} @@ -248,13 +243,9 @@ EOF - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}} _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an empty or arbitrary token string. - 2. To test the input and processor, enter the following command: @@ -361,12 +352,9 @@ EOF - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}} _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an empty or arbitrary token string. 3. To test the input and processor, enter the following command: @@ -463,12 +451,9 @@ table, tag set, and timestamp), and then merges points in each series: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}} _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an empty or arbitrary token string. 3. To test the input and aggregator, enter the following command: @@ -566,12 +551,9 @@ field values, and then write the data to InfluxDB: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}} _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an empty or arbitrary token string. 3. To test the input and processor, enter the following command: @@ -805,12 +787,9 @@ EOF - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}} _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an empty or arbitrary token string. 5. To test the input and processor, enter the following command: diff --git a/content/shared/influxdb3-write-guides/api-client-libraries.md b/content/shared/influxdb3-write-guides/client-libraries.md similarity index 57% rename from content/shared/influxdb3-write-guides/api-client-libraries.md rename to content/shared/influxdb3-write-guides/client-libraries.md index 5be1f203a..e33d59122 100644 --- a/content/shared/influxdb3-write-guides/api-client-libraries.md +++ b/content/shared/influxdb3-write-guides/client-libraries.md @@ -1,193 +1,42 @@ - Use the `/api/v3/write_lp` HTTP API endpoint and InfluxDB v3 API clients to write points as line protocol data to {{% product-name %}}. - -- [Use the /api/v3/write\_lp endpoint](#use-the-apiv3write_lp-endpoint) - - [Example: write data using the /api/v3 HTTP API](#example-write-data-using-the-apiv3-http-api) - - [Write responses](#write-responses) - - [Use no\_sync for immediate write responses](#use-no_sync-for-immediate-write-responses) -- [Use API client libraries](#use-api-client-libraries) - - [Construct line protocol](#construct-line-protocol) - - [Set up your project](#set-up-your-project) - -## Use the /api/v3/write_lp endpoint - -{{% product-name %}} adds the `/api/v3/write_lp` endpoint. - -{{}} - -This endpoint accepts the same line protocol syntax as [previous versions](/influxdb3/version/write-data/compatibility-apis/), -and supports the following parameters: - -- `?accept_partial=`: Accept or reject partial writes (default is `true`). -- `?no_sync=`: Control when writes are acknowledged: - - `no_sync=true`: Acknowledge writes before WAL persistence completes. - - `no_sync=false`: Acknowledges writes after WAL persistence completes (default). -- `?precision=`: Specify the precision of the timestamp. The default is nanosecond precision. - -For more information about the parameters, see [Write data](/influxdb3/version/write-data/). - -InfluxData provides supported InfluxDB 3 client libraries that you can integrate with your code -to construct data as time series points, and then write them as line protocol to an {{% product-name %}} database. -For more information, see how to [use InfluxDB client libraries to write data](/influxdb3/version/write-data/client-libraries/). - -### Example: write data using the /api/v3 HTTP API - -The following examples show how to write data using `curl` and the `/api/3/write_lp` HTTP endpoint. -To show the difference between accepting and rejecting partial writes, line `2` in the example contains a string value (`"hi"`) for a float field (`temp`). - -#### Partial write of line protocol occurred - -With `accept_partial=true` (default): - -```bash -curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \ - --data-raw 'home,room=Sunroom temp=96 -home,room=Sunroom temp="hi"' -``` - -The response is the following: - -``` -< HTTP/1.1 400 Bad Request -... -{ - "error": "partial write of line protocol occurred", - "data": [ - { - "original_line": "home,room=Sunroom temp=hi", - "line_number": 2, - "error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string" - } - ] -} -``` - -Line `1` is written and queryable. -Line `2` is rejected. -The response is an HTTP error (`400`) status, and the response body contains the error message `partial write of line protocol occurred` with details about the problem line. - -#### Parsing failed for write_lp endpoint - -With `accept_partial=false`: - -```bash -curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&accept_partial=false" \ - --data-raw 'home,room=Sunroom temp=96 -home,room=Sunroom temp="hi"' -``` - -The response is the following: - -``` -< HTTP/1.1 400 Bad Request -... -{ - "error": "parsing failed for write_lp endpoint", - "data": { - "original_line": "home,room=Sunroom temp=hi", - "line_number": 2, - "error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string" - } -} -``` - -InfluxDB rejects all points in the batch. -The response is an HTTP error (`400`) status, and the response body contains `parsing failed for write_lp endpoint` and details about the problem line. - -For more information about the ingest path and data flow, see [Data durability](/influxdb3/version/reference/internals/durability/). - -### Write responses - -By default, InfluxDB acknowledges writes after flushing the WAL file to the Object store (occurring every second). -For high write throughput, you can send multiple concurrent write requests. - -### Use no_sync for immediate write responses - -To reduce the latency of writes, use the `no_sync` write option, which acknowledges writes _before_ WAL persistence completes. -When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, and then immediately responds to the client, without waiting for persistence to the Object store. - -Using `no_sync=true` is best when prioritizing high-throughput writes over absolute durability. - -- Default behavior (`no_sync=false`): Waits for data to be written to the Object store before acknowledging the write. Reduces the risk of data loss, but increases the latency of the response. -- With `no_sync=true`: Reduces write latency, but increases the risk of data loss in case of a crash before WAL persistence. - -#### Immediate write using the HTTP API - -The `no_sync` parameter controls when writes are acknowledged--for example: - -```bash -curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto&no_sync=true" \ - --data-raw "home,room=Sunroom temp=96" -``` - -## Use API client libraries - Use InfluxDB 3 client libraries that integrate with your code to construct data -as time series points, and -then write them as line protocol to an {{% product-name %}} database. +as time series points, and then write them as line protocol to an +{{% product-name %}} database. +- [Set up your project](#set-up-your-project) + - [Initialize a project directory](#initialize-a-project-directory) + - [Install the client library](#install-the-client-library) - [Construct line protocol](#construct-line-protocol) - [Example home schema](#example-home-schema) -- [Set up your project](#set-up-your-project) -- [Construct points and write line protocol](#construct-points-and-write-line-protocol) -### Construct line protocol +## Set up your project -With a [basic understanding of line protocol](/influxdb3/version/write-data/#line-protocol), -you can construct line protocol data and write it to {{% product-name %}}. +Set up your {{< product-name >}} project and credentials +to write data using the InfluxDB 3 client library for your programming language +of choice. -All InfluxDB client libraries write data in line protocol format to InfluxDB. -Client library `write` methods let you provide data as raw line protocol or as -`Point` objects that the client library converts to line protocol. If your -program creates the data you write to InfluxDB, use the client library `Point` -interface to take advantage of type safety in your program. - -#### Example home schema - -Consider a use case where you collect data from sensors in your home. Each -sensor collects temperature, humidity, and carbon monoxide readings. - -To collect this data, use the following schema: - - - -- **table**: `home` - - **tags** - - `room`: Living Room or Kitchen - - **fields** - - `temp`: temperature in °C (float) - - `hum`: percent humidity (float) - - `co`: carbon monoxide in parts per million (integer) - - **timestamp**: Unix timestamp in _second_ precision - - - -The following example shows how to construct and write points that follow the -`home` schema. - -### Set up your project +1. [Install {{< product-name >}}](/influxdb3/version/install/) +2. [Set up {{< product-name >}}](/influxdb3/version/get-started/setup/) +3. Create a project directory and store your + {{< product-name >}} credentials as environment variables or in a project + configuration file, such as a `.env` ("dotenv") file. After setting up {{< product-name >}} and your project, you should have the following: - {{< product-name >}} credentials: - [Database](/influxdb3/version/admin/databases/) - - Authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - + - [Authorization token](/influxdb3/version/admin/tokens/) - {{% product-name %}} URL - A directory for your project. - - Credentials stored as environment variables or in a project configuration file--for example, a `.env` ("dotenv") file. -- Client libraries installed for writing data to {{< product-name >}}. +### Initialize a project directory -The following examples use InfluxDB 3 client libraries to show how to construct -`Point` objects that follow the [example `home` schema](#example-home-schema), -and then write the data as line protocol to an {{% product-name %}} database. +Create a project directory and initialize it for your programming language. + + {{< tabs-wrapper >}} {{% tabs %}} @@ -196,86 +45,61 @@ and then write the data as line protocol to an {{% product-name %}} database. [Python](#) {{% /tabs %}} {{% tab-content %}} - -The following steps set up a Go project using the -[InfluxDB 3 Go client](https://github.com/InfluxCommunity/influxdb3-go/): - 1. Install [Go 1.13 or later](https://golang.org/doc/install). -1. Create a directory for your Go module and change to the directory--for +2. Create a directory for your Go module and change to the directory--for example: ```sh mkdir iot-starter-go && cd $_ ``` -1. Initialize a Go module--for example: +3. Initialize a Go module--for example: ```sh go mod init iot-starter ``` -1. Install [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go/), - which provides the InfluxDB `influxdb3` Go client library module. - - ```sh - go get github.com/InfluxCommunity/influxdb3-go/v2 - ``` - -{{% /tab-content %}} {{% tab-content %}} - - - -The following steps set up a JavaScript project using the -[InfluxDB 3 JavaScript client](https://github.com/InfluxCommunity/influxdb3-js/). +{{% /tab-content %}} +{{% tab-content %}} + 1. Install [Node.js](https://nodejs.org/en/download/). -1. Create a directory for your JavaScript project and change to the +2. Create a directory for your JavaScript project and change to the directory--for example: ```sh mkdir -p iot-starter-js && cd $_ ``` -1. Initialize a project--for example, using `npm`: +3. Initialize a project--for example, using `npm`: ```sh npm init ``` + -1. Install the `@influxdata/influxdb3-client` InfluxDB 3 JavaScript client - library. - - ```sh - npm install @influxdata/influxdb3-client - ``` - - - -{{% /tab-content %}} {{% tab-content %}} +{{% /tab-content %}} +{{% tab-content %}} - -The following steps set up a Python project using the -[InfluxDB 3 Python client](https://github.com/InfluxCommunity/influxdb3-python/): - 1. Install [Python](https://www.python.org/downloads/) -1. Inside of your project directory, create a directory for your Python module +2. Inside of your project directory, create a directory for your Python module and change to the module directory--for example: ```sh mkdir -p iot-starter-py && cd $_ ``` -1. **Optional, but recommended**: Use +3. **Optional, but recommended**: Use [`venv`](https://docs.python.org/3/library/venv.html) or [`conda`](https://docs.continuum.io/anaconda/install/) to activate a virtual environment for installing and executing code--for example, enter the @@ -285,29 +109,134 @@ The following steps set up a Python project using the ```bash python3 -m venv envs/iot-starter && source ./envs/iot-starter/bin/activate ``` - -1. Install - [`influxdb3-python`](https://github.com/InfluxCommunity/influxdb3-python), - which provides the InfluxDB `influxdb_client_3` Python client library module - and also installs the - [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for - working with Arrow data. - - ```sh - pip install influxdb3-python - ``` - {{% /tab-content %}} {{< /tabs-wrapper >}} -#### Construct points and write line protocol +### Install the client library + +Install the InfluxDB 3 client library for your programming language of choice. + +{{< tabs-wrapper >}} +{{% tabs %}} +[C#](#) +[Go](#) +[Java](#) +[Node.js](#) +[Python](#) +{{% /tabs %}} +{{% tab-content %}} + +Add the [InfluxDB 3 C# client library](https://github.com/InfluxCommunity/influxdb3-csharp) to your project using the +[`dotnet` CLI](https://docs.microsoft.com/dotnet/core/tools/dotnet) or +by adding the package to your project file--for example: + +```bash +dotnet add package InfluxDB3.Client +``` + +{{% /tab-content %}} +{{% tab-content %}} + +Add the +[InfluxDB 3 Go client library](https://github.com/InfluxCommunity/influxdb3-go) +to your project using the +[`go get` command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)--for example: + +```bash +go mod init path/to/project/dir && cd $_ +go get github.com/InfluxCommunity/influxdb3-go/v2/influxdb3 +``` + +{{% /tab-content %}} +{{% tab-content %}} + +Add the [InfluxDB 3 Java client library](https://github.com/InfluxCommunity/influxdb3-java) to your project dependencies using +the [Maven](https://maven.apache.org/) +[Gradle](https://gradle.org/) build tools. + +For example, to add the library to a Maven project, add the following dependency +to your `pom.xml` file: + +```xml + + com.influxdb + influxdb3-java + 1.1.0 + +``` + +To add the library to a Gradle project, add the following dependency to your `build.gradle` file: + +```groovy +dependencies { + implementation 'com.influxdb:influxdb3-java:1.1.0' +} +``` + +{{% /tab-content %}} +{{% tab-content %}} + +For a Node.js project, use `@influxdata/influxdb3-client`, which provides main (CommonJS), +module (ESM), and browser (UMD) exports. +Add the [InfluxDB 3 JavaScript client library](https://github.com/InfluxCommunity/influxdb3-js) using your preferred package manager--for example, using [`npm`](https://www.npmjs.com/): + +```bash +npm install --save @influxdata/influxdb3-client +``` + +{{% /tab-content %}} +{{% tab-content %}} + +Install the [InfluxDB 3 Python client library](https://github.com/InfluxCommunity/influxdb3-python) using +[`pip`](https://pypi.org/project/pip/). +To use Pandas features, such as `to_pandas()`, provided by the Python +client library, you must also install the +[`pandas` package](https://pandas.pydata.org/). + +```bash +pip install influxdb3-python pandas +``` + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +## Construct line protocol + +With a [basic understanding of line protocol](/influxdb3/version/write-data/#line-protocol), +you can construct line protocol data and write it to {{% product-name %}}. + +Use client library write methods to provide data as raw line protocol +or as `Point` objects that the client library converts to line protocol. +If your program creates the data you write to InfluxDB, the `Point` +interface to take advantage of type safety in your program. Client libraries provide one or more `Point` constructor methods. Some libraries support language-native data structures, such as Go's `struct`, for creating points. +Examples in this guide show how to construct `Point` objects that follow the [example `home` schema](#example-home-schema), +and then write the points as line protocol data to an {{% product-name %}} database. + +### Example home schema + +Consider a use case where you collect data from sensors in your home. Each +sensor collects temperature, humidity, and carbon monoxide readings. + +To collect this data, use the following schema: + + + +- **table**: `home` + - **tags** + - `room`: Living Room or Kitchen + - **fields** + - `temp`: temperature in °C (float) + - `hum`: percent humidity (float) + - `co`: carbon monoxide in parts per million (integer) + - **timestamp**: Unix timestamp in _second_ precision + {{< tabs-wrapper >}} {{% tabs %}} [Go](#) diff --git a/content/shared/influxdb3-write-guides/http-api/_index.md b/content/shared/influxdb3-write-guides/http-api/_index.md new file mode 100644 index 000000000..6122cf589 --- /dev/null +++ b/content/shared/influxdb3-write-guides/http-api/_index.md @@ -0,0 +1,4 @@ +Use the InfluxDB HTTP API to write data to {{< product-name >}}. +There are different APIs you can use depending on your integration method. + +{{< children >}} diff --git a/content/shared/influxdb3-write-guides/compatibility-apis.md b/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md similarity index 81% rename from content/shared/influxdb3-write-guides/compatibility-apis.md rename to content/shared/influxdb3-write-guides/http-api/compatibility-apis.md index eec64c67a..41dc335aa 100644 --- a/content/shared/influxdb3-write-guides/compatibility-apis.md +++ b/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md @@ -15,14 +15,15 @@ to write points as line protocol data to {{% product-name %}}. ## InfluxDB v2 compatibility -The `/api/v2/write` InfluxDB v2 compatibility endpoint provides backwards compatibility with clients that can write data to InfluxDB OSS v2.x and Cloud 2 (TSM). +The `/api/v2/write` InfluxDB v2 compatibility endpoint provides backwards +compatibility with clients that can write data to InfluxDB OSS v2.x and Cloud 2 (TSM). -{{}} +{{}} ## InfluxDB v1 compatibility The `/write` InfluxDB v1 compatibility endpoint provides backwards compatibility with clients that can write data to InfluxDB v1.x. -{{}} +{{}} diff --git a/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md b/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md new file mode 100644 index 000000000..ec00bb4c2 --- /dev/null +++ b/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md @@ -0,0 +1,162 @@ +Use the `/api/v3/write_lp` endpoint to write data to {{% product-name %}}. + +This endpoint accepts the same [line protocol](/influxdb3/version/reference/line-protocol/) +syntax as previous versions of InfluxDB, and supports the following: + +##### Query parameters + +- `?accept_partial=`: Accept or reject partial writes (default is `true`). +- `?no_sync=`: Control when writes are acknowledged: + - `no_sync=true`: Acknowledge writes before WAL persistence completes. + - `no_sync=false`: Acknowledges writes after WAL persistence completes (default). +- `?precision=`: Specify the precision of the timestamp. + The default is `ns` (nanosecond) precision. + You can also use `auto` to let InfluxDB automatically determine the timestamp + precision by identifying which precisions resolves most closely to _now_. + +##### Request body + +- Line protocol + +{{}} + +_The following example uses [cURL](https://curl.se/) to send a write request using +the {{< influxdb3/home-sample-link >}}, but you can use any HTTP client._ + +{{% influxdb/custom-timestamps %}} +```bash +curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \ + --data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1735549200 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1735549200 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1735552800 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1735552800 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1735556400 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1735556400 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1735560000 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1735560000 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1735563600 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1735563600 +home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1735567200 +home,room=Kitchen temp=22.8,hum=36.3,co=1i 1735567200 +home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1735570800 +home,room=Kitchen temp=22.7,hum=36.2,co=3i 1735570800 +home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1735574400 +home,room=Kitchen temp=22.4,hum=36.0,co=7i 1735574400 +home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1735578000 +home,room=Kitchen temp=22.7,hum=36.0,co=9i 1735578000 +home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1735581600 +home,room=Kitchen temp=23.3,hum=36.9,co=18i 1735581600 +home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1735585200 +home,room=Kitchen temp=23.1,hum=36.6,co=22i 1735585200 +home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1735588800 +home,room=Kitchen temp=22.7,hum=36.5,co=26i 1735588800" +``` +{{% /influxdb/custom-timestamps %}} + +- [Partial writes](#partial-writes) + - [Accept partial writes](#accept-partial-writes) + - [Do not accept partial writes](#do-not-accept-partial-writes) +- [Write responses](#write-responses) + - [Use no_sync for immediate write responses](#use-no_sync-for-immediate-write-responses) + +> [!Note] +> #### InfluxDB client libraries +> +> InfluxData provides supported InfluxDB 3 client libraries that you can +> integrate with your code to construct data as time series points, and then +> write them as line protocol to an {{% product-name %}} database. +> For more information, see how to [use InfluxDB client libraries to write data](/influxdb3/version/write-data/client-libraries/). + +## Partial writes + +The `/api/v3/write_lp` endpoint lets you accept or reject partial writes using +the `accept_partial` parameter. This parameter changes the behavior of the API +when the write request contains invalid line protocol or schema conflicts. + +For example, the following line protocol contains two points, each using a +different datatype for the `temp` field, which causes a schema conflict: + +``` +home,room=Sunroom temp=96 1735545600 +home,room=Sunroom temp="hi" 1735549200 +``` + +### Accept partial writes + +With `accept_partial=true` (default), InfluxDB: + +- Accepts and writes line `1` +- Rejects line `2` +- Returns a `400 Bad Request` status code and the following response body: + +``` +< HTTP/1.1 400 Bad Request +... +{ + "error": "partial write of line protocol occurred", + "data": [ + { + "original_line": "home,room=Sunroom temp=hi 1735549200", + "line_number": 2, + "error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string" + } + ] +} +``` + +### Do not accept partial writes + +With `accept_partial=false`, InfluxDB: + +- Rejects _all_ points in the batch +- Returns a `400 Bad Request` status code and the following response body: + +``` +< HTTP/1.1 400 Bad Request +... +{ + "error": "parsing failed for write_lp endpoint", + "data": { + "original_line": "home,room=Sunroom temp=hi 1735549200", + "line_number": 2, + "error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string" + } +} +``` + +_For more information about the ingest path and data flow, see +[Data durability](/influxdb3/version/reference/internals/durability/)._ + +## Write responses + +By default, {{% product-name %}} acknowledges writes after flushing the WAL file +to the Object store (occurring every second). +For high write throughput, you can send multiple concurrent write requests. + +### Use no_sync for immediate write responses + +To reduce the latency of writes, use the `no_sync` write option, which +acknowledges writes _before_ WAL persistence completes. +When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, +and then immediately responds to the client, without waiting for persistence to +the Object store. + +> [!Tip] +> Using `no_sync=true` is best when prioritizing high-throughput writes over +> absolute durability. + +- Default behavior (`no_sync=false`): Waits for data to be written to the Object + store before acknowledging the write. Reduces the risk of data loss, but + increases the latency of the response. +- With `no_sync=true`: Reduces write latency, but increases the risk of data + loss in case of a crash before WAL persistence. + +The following example immediately returns a response without waiting for WAL +persistence: + +```bash +curl "http://localhost:8181/api/v3/write_lp?db=sensors&no_sync=true" \ + --data-raw "home,room=Sunroom temp=96" +``` diff --git a/content/shared/influxdb3-write-guides/influxdb3-cli.md b/content/shared/influxdb3-write-guides/influxdb3-cli.md index 6e95dc048..11aa37b35 100644 --- a/content/shared/influxdb3-write-guides/influxdb3-cli.md +++ b/content/shared/influxdb3-write-guides/influxdb3-cli.md @@ -9,8 +9,9 @@ to write line protocol data to {{< product-name >}}. > #### Use the API for batching and higher-volume writes > > The `influxdb3` CLI lets you quickly get started writing data to {{< product-name >}}. -> For batching and higher-volume write workloads, use -> [API client libraries](/influxdb3/version/write-data/api/#use-api-client-libraries) +> For batching and higher-volume write workloads, use the +> [InfluxDB HTTP API](/influxdb3/version/write-data/http-api), +> [API client libraries](/influxdb3/version/write-data/client-libraries/) > or [Telegraf](/influxdb3/version/write-data/use-telegraf/). ## Construct line protocol @@ -63,7 +64,7 @@ Provide the following: - The [database](/influxdb3/version/admin/databases/) name using the `--database` option -- Your {{< product-name >}} authorization token using the `-t`, `--token` option +- Your {{< product-name >}} {{% token-link %}} using the `-t`, `--token` option - [Line protocol](#construct-line-protocol). Provide the line protocol in one of the following ways: @@ -195,7 +196,4 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token - - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. + your {{< product-name >}} {{% token-link %}} diff --git a/content/shared/influxdb3-write-guides/troubleshoot.md b/content/shared/influxdb3-write-guides/troubleshoot.md index 3d9691d2d..2f7d04d10 100644 --- a/content/shared/influxdb3-write-guides/troubleshoot.md +++ b/content/shared/influxdb3-write-guides/troubleshoot.md @@ -41,7 +41,7 @@ Write requests return the following status codes: | :-------------------------------| :--------------------------------------------------------------- | :------------- | | `204 "Success"` | | If InfluxDB ingested the data | | `400 "Bad request"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections | If some or all request data isn't allowed (for example, if it is malformed or falls outside of the bucket's retention period)--the response body indicates whether a partial write has occurred or if all data has been rejected | -| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb3/version/admin/tokens/) doesn't have [permission](/influxdb3/version/reference/cli/influxctl/token/create/#examples) to write to the database. See [examples using credentials](/influxdb3/version/write-data/api-client-libraries/) in write requests. | +| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb3/version/admin/tokens/) doesn't have permission to write to the database. See [write API examples](/influxdb3/enterprise/write-data/http-api/) using credentials. | | `404 "Not found"` | requested **resource type** (for example, "organization" or "database"), and **resource name** | If a requested resource (for example, organization or database) wasn't found | | `500 "Internal server error"` | | Default status for an error | | `503` "Service unavailable" | | If the server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again. diff --git a/content/shared/influxdb3-write-guides/use-telegraf/_index.md b/content/shared/influxdb3-write-guides/use-telegraf/_index.md index ba5b643f3..1bc78340e 100644 --- a/content/shared/influxdb3-write-guides/use-telegraf/_index.md +++ b/content/shared/influxdb3-write-guides/use-telegraf/_index.md @@ -46,13 +46,9 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}}. _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an arbitrary, non-empty token string. - _See how to [Configure Telegraf to write to {{% product-name %}}](/influxdb3/version/write-data/use-telegraf/configure/)._ ## Use Telegraf with InfluxDB diff --git a/content/shared/influxdb3-write-guides/use-telegraf/configure.md b/content/shared/influxdb3-write-guides/use-telegraf/configure.md index 1fa5fabd0..0e04adaac 100644 --- a/content/shared/influxdb3-write-guides/use-telegraf/configure.md +++ b/content/shared/influxdb3-write-guides/use-telegraf/configure.md @@ -65,13 +65,9 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}}. _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an arbitrary, non-empty token string. - The InfluxDB output plugin configuration contains the following options: #### urls @@ -87,10 +83,6 @@ To write to {{% product-name %}}, include your {{% product-name %}} URL: Your {{% product-name %}} authorization token. -> [!Note] -> While in beta, {{< product-name >}} does not require an authorization token. -> For the `token` option, provide an arbitrary, non-empty token string. - > [!Tip] > > ##### Store your authorization token as an environment variable diff --git a/content/shared/influxdb3-write-guides/use-telegraf/csv.md b/content/shared/influxdb3-write-guides/use-telegraf/csv.md index b3e9941fc..41967996a 100644 --- a/content/shared/influxdb3-write-guides/use-telegraf/csv.md +++ b/content/shared/influxdb3-write-guides/use-telegraf/csv.md @@ -95,13 +95,9 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write data to - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: - your {{< product-name >}} authorization token. + your {{< product-name >}} {{% token-link %}}. _Store this in a secret store or environment variable to avoid exposing the raw token string._ - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an arbitrary, non-empty token string. - > [!Tip] > > ##### Store your authorization token as an environment variable diff --git a/content/shared/influxdb3-write-guides/use-telegraf/dual-write.md b/content/shared/influxdb3-write-guides/use-telegraf/dual-write.md index f557781a0..71f3fa52d 100644 --- a/content/shared/influxdb3-write-guides/use-telegraf/dual-write.md +++ b/content/shared/influxdb3-write-guides/use-telegraf/dual-write.md @@ -5,7 +5,7 @@ to a separate instance or for migrating from other versions of InfluxDB to {{< product-name >}}. The following example configures Telegraf for dual writing to {{% product-name %}} and an InfluxDB v2 OSS instance. - +Specifically, it uses the following: - The [InfluxDB v2 output plugin](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2) twice--the first pointing to {{< product-name >}} and the other to an @@ -14,11 +14,6 @@ The following example configures Telegraf for dual writing to {{% product-name % Configure both tokens as environment variables and use string interpolation in your Telegraf configuration file to reference each environment variable. - > [!Note] - > While in beta, {{< product-name >}} does not require an authorization token. - > For the `token` option, provide an arbitrary, non-empty token string. - - ## Sample configuration ```toml diff --git a/content/shared/influxdb3/_index.md b/content/shared/influxdb3/_index.md index 505e32a12..f5e59e89c 100644 --- a/content/shared/influxdb3/_index.md +++ b/content/shared/influxdb3/_index.md @@ -28,7 +28,7 @@ Core's feature highlights include: - Compatibility with InfluxDB 1.x and 2.x write APIs {{% show-in "core" %}} -[Get started with Core](/influxdb3/version/get-started/) +Get started with {{% product-name %}} {{% /show-in %}} The Enterprise version adds the following features to Core: @@ -41,5 +41,8 @@ The Enterprise version adds the following features to Core: - Integrated admin UI (coming soon) {{% show-in "core" %}} -For more information, see how to [get started with Enterprise](/influxdb3/enterprise/get-started/). +For more information, see how to [get started with InfluxDB 3 Enterprise](/influxdb3/enterprise/get-started/). +{{% /show-in %}} +{{% show-in "enterprise" %}} +Get started with {{% product-name %}} {{% /show-in %}} \ No newline at end of file diff --git a/content/shared/influxdb3/install.md b/content/shared/influxdb3/install.md index a833376d6..6523e8a47 100644 --- a/content/shared/influxdb3/install.md +++ b/content/shared/influxdb3/install.md @@ -1,8 +1,16 @@ - [System Requirements](#system-requirements) -- [Quick install](#quick-install) -- [Download {{% product-name %}} binaries](#download-influxdb-3-{{< product-key >}}-binaries) -- [Docker image](#docker-image) +- [Install](#install) + - [Quick install for Linux and macOS](#quick-install-for-linux-and-macos) + - [Download and install the latest build artifacts](#download-and-install-the-latest-build-artifacts) + - [Pull the Docker image](#pull-the-docker-image) + - [Verify the installation](#verify-the-installation) + +{{% show-in "enterprise" %}} +> [!Note] +> For information about setting up a multi-node {{% product-name %}} cluster, +> see [Create a multi-node cluster](/influxdb3/enterprise/get-started/multi-server/) in the Get started guide. +{{% /show-in %}} ## System Requirements @@ -21,119 +29,69 @@ Azure Blob Storage, and Google Cloud Storage. You can also use many local object storage implementations that provide an S3-compatible API, such as [Minio](https://min.io/). -## Quick install +## Install -Use the InfluxDB 3 quick install script to install {{< product-name >}} on -**Linux** and **macOS**. +{{% product-name %}} runs on **Linux**, **macOS**, and **Windows**. -> [!Important] -> If using Windows, [download the {{% product-name %}} Windows binary](?t=Windows#download-influxdb-3-{{< product-key >}}-binaries). +Choose one of the following methods to install {{% product-name %}}: -1. Use the following command to download and install the appropriate - {{< product-name >}} package on your local machine: -{{% show-in "enterprise" %}} - - ```bash - curl -O https://www.influxdata.com/d/install_influxdb3.sh \ - && sh install_influxdb3.sh {{% product-key %}} - ``` -{{% /show-in %}} -{{% show-in "core" %}} - - ```bash - curl -O https://www.influxdata.com/d/install_influxdb3.sh \ - && sh install_influxdb3.sh - ``` -{{% /show-in %}} +- [Quick install for Linux and macOS](#quick-install-for-linux-and-macos) +- [Download and install the latest build artifacts](#download-and-install-the-latest-build-artifacts) +- [Pull the Docker image](#pull-the-docker-image) -2. Verify that installation completed successfully: +### Quick install for Linux and macOS - ```bash - influxdb3 --version - ``` +To install {{% product-name %}} on **Linux** or **macOS**, download and run the quick +installer script for {{% product-name %}}--for example, using [`curl`](https://curl.se/) +to download the script: -> [!Note] -> -> #### influxdb3 not found -> -> If your system can't locate your `influxdb3` binary, `source` your -> current shell configuration file (`.bashrc`, `.zshrc`, etc.). -> -> {{< code-tabs-wrapper >}} -{{% code-tabs %}} -[.bashrc](#) -[.zshrc](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```bash -source ~/.bashrc -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} ```bash -source ~/.zshrc +curl -O https://www.influxdata.com/d/install_influxdb3.sh \ +&& sh install_influxdb3.sh {{% show-in "enterprise" %}}enterprise{{% /show-in %}} ``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} -## Download {{% product-name %}} binaries +> [!Note] +> The quick installer script is updated with each {{% product-name %}} release, +> so it always installs the latest version. -{{< tabs-wrapper >}} -{{% tabs %}} -[Linux](#) -[macOS](#) -[Windows](#) -{{% /tabs %}} -{{% tab-content %}} +### Download and install the latest build artifacts - +You can also download and install [{{% product-name %}} build artifacts](/influxdb3/enterprise/install/#download-influxdb-3-enterprise-binaries) directly: -- [{{< product-name >}} • Linux (AMD64, x86_64) • GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz) +{{< expand-wrapper >}} +{{% expand "Linux binaries" %}} + +- [Linux | AMD64 (x86_64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz) • [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz.sha256) - -- [{{< product-name >}} • Linux (ARM64, AArch64) • GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz) +- [Linux | ARM64 (AArch64) | GNU](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz) • [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_arm64.tar.gz.sha256) - +{{% /expand %}} +{{% expand "macOS binaries" %}} -{{% /tab-content %}} -{{% tab-content %}} - - - -- [{{< product-name >}} • macOS (Silicon, ARM64)](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz) +- [macOS | Silicon (ARM64)](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz) • [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_darwin_arm64.tar.gz.sha256) > [!Note] > macOS Intel builds are coming soon. - +{{% /expand %}} +{{% expand "Windows binaries" %}} -{{% /tab-content %}} -{{% tab-content %}} +- [Windows (AMD64, x86_64) binary](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip) + • +[sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip.sha256) - +{{% /expand %}} +{{< /expand-wrapper >}} -- [{{< product-name >}} • Windows (AMD64, x86_64)](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip) - • - [sha256](https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip.sha256) +### Pull the Docker image - - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - -## Docker image - -Use the `influxdb:3-{{< product-key >}}` Docker image to deploy {{< product-name >}} in a -Docker container. -The image is available for x86_64 (AMD64) and ARM64 architectures. - -### Use Docker CLI +Run the following command to pull the [`influxdb:3-{{< product-key >}}` image](https://hub.docker.com/_/influxdb/tags?tag=3-{{< product-key >}}&name=3-{{< product-key >}}), available for x86_64 (AMD64) and ARM64 architectures: ```bash @@ -142,6 +100,8 @@ docker pull influxdb:3-{{< product-key >}} Docker automatically pulls the appropriate image for your system architecture. +{{< expand-wrapper >}} +{{% expand "Pull for a specific system architecture" %}} To specify the system architecture, use platform-specific tags--for example: ```bash @@ -157,79 +117,31 @@ docker pull \ --platform linux/arm64 \ influxdb:3-{{< product-key >}} ``` +{{% /expand %}} +{{< /expand-wrapper >}} -> [!Note] -> The {{% product-name %}} Docker image exposes port `8181`, the `influxdb3` server default for HTTP connections. -> To map the exposed port to a different port when running a container, see the Docker guide for [Publishing and exposing ports](https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/). -### Use Docker Compose +### Verify the installation + +After installing {{% product-name %}}, enter the following command to verify +that it installed successfully: + +```bash +influxdb3 --version +``` + +If your system doesn't locate `influxdb3`, then `source` the configuration file (for example, .bashrc, .zshrc) for your shell--for example: + + +```zsh +source ~/.zshrc +``` {{% show-in "enterprise" %}} -1. Open `compose.yaml` for editing and add a `services` entry for {{% product-name %}}. - To generate a trial or at-home license for {{% product-name %}} when using Docker, you must pass the `--license-email` option or the `INFLUXDB3_LICENSE_EMAIL` environment variable the first time you start the server--for example: - - ```yaml - # compose.yaml - services: - influxdb3-{{< product-key >}}: - container_name: influxdb3-{{< product-key >}} - image: influxdb:3-{{< product-key >}} - ports: - - 8181:8181 - command: - - influxdb3 - - serve - - --node-id=node0 - - --cluster-id=cluster0 - - --object-store=file - - --data-dir=/var/lib/influxdb3 - - --plugins-dir=/var/lib/influxdb3-plugins - - --license-email=${INFLUXDB3_LICENSE_EMAIL} - ``` -{{% /show-in %}} -{{% show-in "core" %}} -1. Open `compose.yaml` for editing and add a `services` entry for {{% product-name %}}--for example: - - ```yaml - # compose.yaml - services: - influxdb3-{{< product-key >}}: - container_name: influxdb3-{{< product-key >}} - image: influxdb:3-{{< product-key >}} - ports: - - 8181:8181 - command: - - influxdb3 - - serve - - --node-id=node0 - - --object-store=file - - --data-dir=/var/lib/influxdb3 - - --plugins-dir=/var/lib/influxdb3-plugins - ``` -{{% /show-in %}} - -2. Use the Docker Compose CLI to start the server. - - Optional: to make sure you have the latest version of the image before you - start the server, run `docker compose pull`. - - - ```bash - docker compose pull && docker compose run influxdb3-{{< product-key >}} - ``` - > [!Note] -> #### Stopping an InfluxDB 3 container -> -> To stop a running InfluxDB 3 container, find and terminate the process or container--for example: -> -> -> ```bash -> docker container ls --filter "name=influxdb3" -> docker kill -> ``` -> -> Currently, a bug prevents using {{< keybind all="Ctrl+c" >}} in the terminal to stop an InfluxDB 3 container. +> For information about setting up a multi-node {{% product-name %}} cluster, +> see [Create a multi-node cluster](/influxdb3/enterprise/get-started/multi-server/) in the Get started guide. +{{% /show-in %}} {{% show-in "enterprise" %}} {{< page-nav next="/influxdb3/enterprise/get-started/" nextText="Get started with InfluxDB 3 Enterprise" >}} diff --git a/content/shared/v3-core-enterprise-release-notes/_index.md b/content/shared/v3-core-enterprise-release-notes/_index.md index ff46e3d03..fa11b397f 100644 --- a/content/shared/v3-core-enterprise-release-notes/_index.md +++ b/content/shared/v3-core-enterprise-release-notes/_index.md @@ -5,6 +5,57 @@ > All updates to Core are automatically included in Enterprise. > The Enterprise sections below only list updates exclusive to Enterprise. +## v3.2.0 {date="2025-06-25"} + +**Core**: revision 1ca3168bee +**Enterprise**: revision 1ca3168bee + +### Core + +#### Features + +- **Hard delete for databases and tables**: Permanently delete databases and tables, enabling complete removal of data structures for compliance and storage management ([#26553](https://github.com/influxdata/influxdb/pull/26553)) +- **AWS credentials auto-reload**: Support dynamic reloading of ephemeral AWS credentials from files, improving security and reliability when using AWS services ([#26537](https://github.com/influxdata/influxdb/pull/26537)) +- **Database retention period support**: Add retention period support for databases via CLI commands (`create database` and `update database` commands) and HTTP APIs ([#26520](https://github.com/influxdata/influxdb/pull/26520)): + - New CLI command: `update database --retention-period` +- **Configurable lookback duration**: Users can specify lookback duration for PersistedFiles buffer, providing better control over query performance ([#26528](https://github.com/influxdata/influxdb/pull/26528)) +- **WAL replay concurrency control**: Add concurrency limits for WAL (Write-Ahead Log) replay to improve startup performance and resource management ([#26483](https://github.com/influxdata/influxdb/pull/26483)) +- **Enhanced write path**: Separate write path executor with unbounded memory for improved write performance ([#26455](https://github.com/influxdata/influxdb/pull/26455)) + +#### Bug Fixes + +- **WAL corruption handling**: Handle corrupt WAL files during replay without panic, improving data recovery and system resilience ([#26556](https://github.com/influxdata/influxdb/pull/26556)) +- **Database naming validation**: Disallow underscores in database names when created via API to ensure consistency ([#26507](https://github.com/influxdata/influxdb/pull/26507)) +- **Object store cleanup**: Automatic intermediate directory cleanup for file object store, preventing storage bloat ([#26480](https://github.com/influxdata/influxdb/pull/26480)) + +#### Additional Updates + +- Track generation 1 duration in catalog for better performance monitoring ([#26508](https://github.com/influxdata/influxdb/pull/26508)) +- Add retention period support to the catalog ([#26479](https://github.com/influxdata/influxdb/pull/26479)) +- Update help text for improved user experience ([#26509](https://github.com/influxdata/influxdb/pull/26509)) + +### Enterprise + +All Core updates are included in Enterprise. Additional Enterprise-specific features and fixes: + +#### Features + +- **License management improvements**: + - New `influxdb3 show license` command to display current license information +- **Table-level retention period support**: Add retention period support for individual tables in addition to database-level retention, providing granular data lifecycle management + - New CLI commands: `create table --retention-period` and `update table --retention-period` + - Set or clear table-specific retention policies independent of database settings +- **Compaction improvements**: + - Address compactor restart issues for better reliability + - Track compacted generation durations in catalog for monitoring + - Disable parquet cache for ingest mode to optimize memory usage + +#### Bug Fixes + +- **Query optimization**: Correctly partition query chunks into generations for improved performance +- **Data integrity**: Don't delete generation 1 files as part of compaction process +- **License handling**: Trim whitespace from license file contents after reading to prevent validation issues + ## v3.1.0 {date="2025-05-29"} **Core**: revision 482dd8aac580c04f37e8713a8fffae89ae8bc264 diff --git a/content/shared/v3-core-plugins/_index.md b/content/shared/v3-core-plugins/_index.md index 4e4c1a762..f225fdb27 100644 --- a/content/shared/v3-core-plugins/_index.md +++ b/content/shared/v3-core-plugins/_index.md @@ -22,20 +22,11 @@ Ensure you have: Once you have all the prerequisites in place, follow these steps to implement the Processing Engine for your data automation needs. -1. [Set up the Processing Engine](#set-up-the-processing-engine) -2. [Add a Processing Engine plugin](#add-a-processing-engine-plugin) - - [Use example plugins](#use-example-plugins) - - [Create a custom plugin](#create-a-custom-plugin) -3. [Set up a trigger](#set-up-a-trigger) - - [Understand trigger types](#understand-trigger-types) - - [Use the create trigger command](#use-the-create-trigger-command) - - [Trigger specification examples](#trigger-specification-examples) -4. [Advanced trigger configuration](#advanced-trigger-configuration) - - [Access community plugins from GitHub](#access-community-plugins-from-github) - - [Pass arguments to plugins](#pass-arguments-to-plugins) - - [Control trigger execution](#control-trigger-execution) - - [Configure error handling for a trigger](#configure-error-handling-for-a-trigger) - - [Install Python dependencies](#install-python-dependencies) +- [Set up the Processing Engine](#set-up-the-processing-engine) +- [Add a Processing Engine plugin](#add-a-processing-engine-plugin) +- [Set up a trigger](#set-up-a-trigger) +- [Advanced trigger configuration](#advanced-trigger-configuration) +- [Distributed cluster considerations](#distributed-cluster-considerations) ## Set up the Processing Engine @@ -75,6 +66,8 @@ When running {{% product-name %}} in a distributed setup, follow these steps to > > Configure your plugin directory on the same system as the nodes that run the triggers and plugins. +For more information about configuring distributed environments, see the [Distributed cluster considerations](#distributed-cluster-considerations) section. + ## Add a Processing Engine plugin A plugin is a Python script that defines a specific function signature for a trigger (_trigger spec_). When the specified event occurs, InfluxDB runs the plugin. @@ -168,11 +161,11 @@ Before you begin, make sure: Choose a plugin type based on your automation goals: -| Plugin Type | Best For | Trigger Type | -| ---------------- | ------------------------------------------- | ------------------------ | -| **Data write** | Processing data as it arrives | `table:` or `all_tables` | -| **Scheduled** | Running code at specific intervals or times | `every:` or `cron:` | -| **HTTP request** | Running code on demand via API endpoints | `path:` | +| Plugin Type | Best For | +| ---------------- | ------------------------------------------- | +| **Data write** | Processing data as it arrives | +| **Scheduled** | Running code at specific intervals or times | +| **HTTP request** | Running code on demand via API endpoints | #### Create your plugin file @@ -184,7 +177,7 @@ After writing your plugin, [create a trigger](#use-the-create-trigger-command) t #### Create a data write plugin -Use a data write plugin to process data as it's written to the database. Ideal use cases include: +Use a data write plugin to process data as it's written to the database. These plugins use [`table:` or `all_tables:`](#trigger-on-data-writes) trigger specifications. Ideal use cases include: - Data transformation and enrichment - Alerting on incoming values @@ -209,7 +202,7 @@ def process_writes(influxdb3_local, table_batches, args=None): #### Create a scheduled plugin -Scheduled plugins run at defined intervals. Use them for: +Scheduled plugins run at defined intervals using [`every:` or `cron:`](#trigger-on-a-schedule) trigger specifications. Use them for: - Periodic data aggregation - Report generation @@ -231,7 +224,7 @@ def process_scheduled_call(influxdb3_local, call_time, args=None): #### Create an HTTP request plugin -HTTP request plugins respond to API calls. Use them for: +HTTP request plugins respond to API calls using [`request:`](#trigger-on-http-requests) trigger specifications{{% show-in "enterprise" %}} (CLI) or `{"request_path": {"path": "..."}}` (HTTP API){{% /show-in %}}. Use them for: - Creating custom API endpoints - Webhooks for external integrations @@ -270,7 +263,7 @@ After writing your plugin: |------------|----------------------|-----------------| | Data write | `table:` or `all_tables` | When data is written to tables | | Scheduled | `every:` or `cron:` | At specified time intervals | -| HTTP request | `path:` | When HTTP requests are received | +| HTTP request | `request:`{{% show-in "enterprise" %}} (CLI) or `{"request_path": {"path": ""}}` (HTTP API){{% /show-in %}} | When HTTP requests are received | ### Use the create trigger command @@ -302,7 +295,7 @@ In the example above, replace the following: ### Trigger specification examples -#### Data write example +#### Trigger on data writes ```bash # Trigger on writes to a specific table @@ -325,13 +318,13 @@ The trigger runs when the database flushes ingested data for the specified table The plugin receives the written data and table information. -#### Scheduled events example +#### Trigger on a schedule ```bash # Run every 5 minutes influxdb3 create trigger \ --trigger-spec "every:5m" \ - --plugin-filename "hourly_check.py" \ + --plugin-filename "periodic_check.py" \ --database my_database \ regular_check @@ -346,7 +339,7 @@ influxdb3 create trigger \ The plugin receives the scheduled call time. -#### HTTP requests example +#### Trigger on HTTP requests ```bash # Create an endpoint at /api/v3/engine/webhook @@ -357,7 +350,9 @@ influxdb3 create trigger \ webhook_processor ``` -Access your endpoint available at `/api/v3/engine/`. +Access your endpoint at `/api/v3/engine/{REQUEST_PATH}` (in this example, `/api/v3/engine/webhook`). +The trigger is enabled by default and runs when an HTTP request is received at the specified path. + To run the plugin, send a `GET` or `POST` request to the endpoint--for example: ```bash @@ -366,6 +361,24 @@ curl http://{{% influxdb/host %}}/api/v3/engine/webhook The plugin receives the HTTP request object with methods, headers, and body. +To view triggers associated with a database, use the `influxdb3 show summary` command: + +```bash +influxdb3 show summary --database my_database --token AUTH_TOKEN +``` + +{{% show-in "enterprise" %}} +> [!Warning] +> #### Request trigger specification format differs between CLI and API +> +> Due to a bug in InfluxDB 3 Enterprise, the request trigger specification format differs: +> +> - **CLI**: `request:` (same as Core CLI and API) +> - **Enterprise API**: `{"request_path": {"path": ""}}` +> +> See the [API reference](/influxdb3/enterprise/api/#operation/PostConfigureProcessingEngineTrigger) for examples. Use `influxdb3 show summary` to verify the actual trigger specification. +{{% /show-in %}} + ### Pass arguments to plugins Use trigger arguments to pass configuration from a trigger to the plugin it runs. You can use this for: @@ -587,7 +600,19 @@ Each plugin must run on a node that supports its trigger type: |--------------------|--------------------------|-----------------------------| | Data write | `table:` or `all_tables` | Ingester nodes | | Scheduled | `every:` or `cron:` | Any node with scheduler | -| HTTP request | `path:` | Nodes that serve API traffic| +| HTTP request | `request:`{{% show-in "enterprise" %}} (CLI) or `{"request_path": {"path": "..."}}` (HTTP API){{% /show-in %}} | Nodes that serve API traffic| + +{{% show-in "enterprise" %}} +> [!Note] +> #### Request trigger specification format differs between CLI and API +> +> Due to a bug in InfluxDB 3 Enterprise, the request trigger specification format differs: +> +> - **CLI**: `request:` (same as Core CLI and API) +> - **Enterprise API**: `{"request_path": {"path": ""}}` +> +> See the [API reference](/influxdb3/enterprise/api/#operation/PostConfigureProcessingEngineTrigger) for examples. +{{% /show-in %}} For example: - Run write-ahead log (WAL) plugins on ingester nodes. diff --git a/cypress/downloads/downloads.html b/cypress/downloads/downloads.html deleted file mode 100644 index 523cdaa3e..000000000 Binary files a/cypress/downloads/downloads.html and /dev/null differ diff --git a/data/notifications.yaml b/data/notifications.yaml index ef9fa720b..2c7012a3a 100644 --- a/data/notifications.yaml +++ b/data/notifications.yaml @@ -40,26 +40,23 @@ # - [The plan for InfluxDB 3.0 Open Source](https://influxdata.com/blog/the-plan-for-influxdb-3-0-open-source) # - [InfluxDB 3.0 benchmarks](https://influxdata.com/blog/influxdb-3-0-is-2.5x-45x-faster-compared-to-influxdb-open-source/) -- id: influxdb3-ga - level: ga-announcement +- id: influxdb3.2-explorer-ga + level: note scope: - / - title_tag: Now Generally Available - title: InfluxDB 3 Core and Enterprise + title: New in InfluxDB 3.2 slug: | - Start fast. Scale faster. + Key enhancements in InfluxDB 3.2 and the InfluxDB 3 Explorer UI is now generally available. - Get the Updates + See the Blog Post message: | - InfluxDB 3 Core is an open source, high-speed, recent-data engine that collects - and processes data in real-time and persists it to local disk or object storage. - InfluxDB 3 Enterprise builds on Core’s foundation, adding high availability, - read replicas, enhanced security, and data compaction for faster queries and - optimized storage. A free tier of InfluxDB 3 Enterprise is available for - non-commercial at-home or hobbyist use. + InfluxDB 3.2 is now available for both Core and Enterprise, bringing the + general availability of InfluxDB 3 Explorer, a new UI that simplifies how + you query, explore, and visualize data. On top of that, InfluxDB 3.2 includes + a wide range of performance improvements, feature updates, and bug fixes + including automated data retention and more. For more information, check out: - - [Announcement blog from Paul Dix](https://www.influxdata.com/blog/influxdb-3-OSS-GA/) - - [Get Started with InfluxDB 3 Core](https://docs.influxdata.com/influxdb3/core/get-started/) - - [Get Started with InfluxDB 3 Enterprise](https://docs.influxdata.com/influxdb3/enterprise/get-started/) + - [InfluxDB 3.2 blog from Paul Dix](http://influxdata.com/blog/influxdb-3-2) + - [Get Started with InfluxDB 3 Explorer](/influxdb3/explorer/get-started/) diff --git a/data/products.yml b/data/products.yml index 793a5e70c..f92229b2e 100644 --- a/data/products.yml +++ b/data/products.yml @@ -6,7 +6,7 @@ influxdb3_core: versions: [core] list_order: 2 latest: core - latest_patch: 3.1.0 + latest_patch: 3.2.0 placeholder_host: localhost:8181 ai_sample_questions: - How do I install and run InfluxDB 3 Core? @@ -21,7 +21,7 @@ influxdb3_enterprise: versions: [enterprise] list_order: 2 latest: enterprise - latest_patch: 3.1.0 + latest_patch: 3.2.0 placeholder_host: localhost:8181 ai_sample_questions: - How do I install and run InfluxDB 3 Enterprise? @@ -64,7 +64,7 @@ influxdb3_cloud_dedicated: list_order: 3 latest: cloud-dedicated link: "https://www.influxdata.com/contact-sales-cloud-dedicated/" - latest_cli: 2.10.1 + latest_cli: 2.10.2 placeholder_host: cluster-id.a.influxdb.io ai_sample_questions: - How do I migrate from InfluxDB v1 to InfluxDB Cloud Dedicated? @@ -128,9 +128,8 @@ explorer: menu_category: other list_order: 4 versions: [v1] - latest: v1.0 - latest_patches: - v1: 1.0.0 + latest: explorer + latest_patch: 1.0.0 ai_sample_questions: - How do I use InfluxDB 3 Explorer to visualize data? - How do I create a dashboard in InfluxDB 3 Explorer? @@ -170,9 +169,9 @@ kapacitor: menu_category: other list_order: 7 versions: [v1] - latest: v1.7 + latest: v1.8 latest_patches: - v1: 1.7.7 + v1: 1.8.0 ai_sample_questions: - How do I configure Kapacitor for InfluxDB v1? - How do I write a custom Kapacitor task? diff --git a/helper-scripts/generate-release-notes.sh b/helper-scripts/generate-release-notes.sh new file mode 100755 index 000000000..d47ae5592 --- /dev/null +++ b/helper-scripts/generate-release-notes.sh @@ -0,0 +1,354 @@ +#!/bin/bash + +# Script to generate release notes for InfluxDB v3.x releases +# Usage: ./generate-release-notes.sh [--no-fetch] [--pull] [additional_repo_paths...] +# +# Options: +# --no-fetch Skip fetching latest commits from remote +# --pull Pull latest changes (implies fetch) - use with caution as it may change your working directory +# +# Example: ./generate-release-notes.sh v3.1.0 v3.2.0 /path/to/influxdb /path/to/influxdb_pro /path/to/influxdb_iox +# Example: ./generate-release-notes.sh --no-fetch v3.1.0 v3.2.0 /path/to/influxdb +# Example: ./generate-release-notes.sh --pull v3.1.0 v3.2.0 /path/to/influxdb /path/to/influxdb_pro + +set -e + +# Parse command line options +FETCH_COMMITS=true +PULL_COMMITS=false + +while [[ $# -gt 0 ]]; do + case $1 in + --no-fetch) + FETCH_COMMITS=false + shift + ;; + --pull) + PULL_COMMITS=true + FETCH_COMMITS=true + shift + ;; + -*) + echo "Unknown option $1" + exit 1 + ;; + *) + break + ;; + esac +done + +# Parse remaining arguments +FROM_VERSION="${1:-v3.1.0}" +TO_VERSION="${2:-v3.2.0}" +PRIMARY_REPO="${3:-/Users/ja/Documents/github/influxdb}" + +# Collect additional repositories (all arguments after the third) +ADDITIONAL_REPOS=() +shift 3 2>/dev/null || true +while [ $# -gt 0 ]; do + ADDITIONAL_REPOS+=("$1") + shift +done + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[0;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +echo -e "${BLUE}Generating release notes for ${TO_VERSION}${NC}" +echo -e "Primary Repository: ${PRIMARY_REPO}" +if [ ${#ADDITIONAL_REPOS[@]} -gt 0 ]; then + echo -e "Additional Repositories:" + for repo in "${ADDITIONAL_REPOS[@]}"; do + echo -e " - ${repo}" + done +fi +echo -e "From: ${FROM_VERSION} To: ${TO_VERSION}\n" + +# Function to extract PR number from commit message +extract_pr_number() { + echo "$1" | grep -oE '#[0-9]+' | head -1 | sed 's/#//' +} + +# Function to get commits from a repository +get_commits_from_repo() { + local repo_path="$1" + local pattern="$2" + local format="${3:-%h %s}" + + if [ -d "$repo_path" ]; then + git -C "$repo_path" log --format="$format" "${FROM_VERSION}..${TO_VERSION}" 2>/dev/null | grep -E "$pattern" || true + fi +} + +# Function to analyze API-related commits +analyze_api_changes() { + local repo_path="$1" + local repo_name="$2" + + if [ ! -d "$repo_path" ]; then + return + fi + + # Look for API-related file changes + local api_files=$(git -C "$repo_path" diff --name-only "${FROM_VERSION}..${TO_VERSION}" 2>/dev/null | grep -E "(api|handler|endpoint|route)" | head -10 || true) + + # Look for specific API endpoint patterns in commit messages and diffs + local api_commits=$(git -C "$repo_path" log --format="%h %s" "${FROM_VERSION}..${TO_VERSION}" 2>/dev/null | \ + grep -iE "(api|endpoint|/write|/query|/ping|/health|/metrics|v1|v2|v3)" || true) + + if [ -n "$api_files" ] || [ -n "$api_commits" ]; then + echo " Repository: $repo_name" + if [ -n "$api_files" ]; then + echo " Modified API files:" + echo "$api_files" | while read -r file; do + echo " - $file" + done + fi + if [ -n "$api_commits" ]; then + echo " API-related commits:" + echo "$api_commits" | while read -r commit; do + echo " - $commit" + done + fi + echo + fi +} + +# Get the release date +RELEASE_DATE=$(git -C "$PRIMARY_REPO" log -1 --format=%ai "$TO_VERSION" | cut -d' ' -f1) +echo -e "${GREEN}Release Date: ${RELEASE_DATE}${NC}\n" + +# Create array of all repositories +ALL_REPOS=("$PRIMARY_REPO") +for repo in "${ADDITIONAL_REPOS[@]}"; do + ALL_REPOS+=("$repo") +done + +# Fetch latest commits from all repositories (if enabled) +if [ "$FETCH_COMMITS" = true ]; then + if [ "$PULL_COMMITS" = true ]; then + echo -e "${YELLOW}Pulling latest changes from all repositories...${NC}" + echo -e "${RED}Warning: This will modify your working directories!${NC}" + else + echo -e "${YELLOW}Fetching latest commits from all repositories...${NC}" + fi + + for repo in "${ALL_REPOS[@]}"; do + if [ -d "$repo" ]; then + repo_name=$(basename "$repo") + + if [ "$PULL_COMMITS" = true ]; then + echo -e " Pulling changes in $repo_name..." + if git -C "$repo" pull origin 2>/dev/null; then + echo -e " ${GREEN}✓${NC} Successfully pulled changes in $repo_name" + else + echo -e " ${RED}✗${NC} Failed to pull changes in $repo_name (trying fetch only)" + if git -C "$repo" fetch origin 2>/dev/null; then + echo -e " ${GREEN}✓${NC} Successfully fetched from $repo_name" + else + echo -e " ${RED}✗${NC} Failed to fetch from $repo_name (continuing with local commits)" + fi + fi + else + echo -e " Fetching from $repo_name..." + if git -C "$repo" fetch origin 2>/dev/null; then + echo -e " ${GREEN}✓${NC} Successfully fetched from $repo_name" + else + echo -e " ${RED}✗${NC} Failed to fetch from $repo_name (continuing with local commits)" + fi + fi + else + echo -e " ${RED}✗${NC} Repository not found: $repo" + fi + done +else + echo -e "${YELLOW}Skipping fetch (using local commits only)${NC}" +fi + +# Collect commits by category from all repositories +echo -e "\n${YELLOW}Analyzing commits across all repositories...${NC}" + +# Initialize variables +FEATURES="" +FIXES="" +BREAKING="" +PERF="" +API_CHANGES="" + +# Collect commits from all repositories +for repo in "${ALL_REPOS[@]}"; do + if [ -d "$repo" ]; then + repo_name=$(basename "$repo") + echo -e " Analyzing $repo_name..." + + # Features + repo_features=$(get_commits_from_repo "$repo" "^[a-f0-9]+ feat:" | sed "s/^[a-f0-9]* feat: /- [$repo_name] /") + if [ -n "$repo_features" ]; then + FEATURES="$FEATURES$repo_features"$'\n' + fi + + # Fixes + repo_fixes=$(get_commits_from_repo "$repo" "^[a-f0-9]+ fix:" | sed "s/^[a-f0-9]* fix: /- [$repo_name] /") + if [ -n "$repo_fixes" ]; then + FIXES="$FIXES$repo_fixes"$'\n' + fi + + # Breaking changes + repo_breaking=$(get_commits_from_repo "$repo" "^[a-f0-9]+ .*(BREAKING|breaking change)" | sed "s/^[a-f0-9]* /- [$repo_name] /") + if [ -n "$repo_breaking" ]; then + BREAKING="$BREAKING$repo_breaking"$'\n' + fi + + # Performance improvements + repo_perf=$(get_commits_from_repo "$repo" "^[a-f0-9]+ perf:" | sed "s/^[a-f0-9]* perf: /- [$repo_name] /") + if [ -n "$repo_perf" ]; then + PERF="$PERF$repo_perf"$'\n' + fi + + # API changes + repo_api=$(get_commits_from_repo "$repo" "(api|endpoint|/write|/query|/ping|/health|/metrics|v1|v2|v3)" | sed "s/^[a-f0-9]* /- [$repo_name] /") + if [ -n "$repo_api" ]; then + API_CHANGES="$API_CHANGES$repo_api"$'\n' + fi + fi +done + +# Analyze API changes in detail +echo -e "\n${YELLOW}Analyzing HTTP API changes...${NC}" +for repo in "${ALL_REPOS[@]}"; do + repo_name=$(basename "$repo") + analyze_api_changes "$repo" "$repo_name" +done + +# Generate markdown output +OUTPUT_FILE="release-notes-${TO_VERSION}.md" +cat > "$OUTPUT_FILE" << EOF +## ${TO_VERSION} {date="${RELEASE_DATE}"} + +### Features + +EOF + +# Add features +if [ -n "$FEATURES" ]; then + echo "$FEATURES" | while IFS= read -r line; do + if [ -n "$line" ]; then + PR=$(extract_pr_number "$line") + # Clean up the commit message + CLEAN_LINE=$(echo "$line" | sed -E 's/ \(#[0-9]+\)$//') + if [ -n "$PR" ]; then + echo "$CLEAN_LINE ([#$PR](https://github.com/influxdata/influxdb/pull/$PR))" >> "$OUTPUT_FILE" + else + echo "$CLEAN_LINE" >> "$OUTPUT_FILE" + fi + fi + done +else + echo "- No new features in this release" >> "$OUTPUT_FILE" +fi + +# Add bug fixes +cat >> "$OUTPUT_FILE" << EOF + +### Bug Fixes + +EOF + +if [ -n "$FIXES" ]; then + echo "$FIXES" | while IFS= read -r line; do + if [ -n "$line" ]; then + PR=$(extract_pr_number "$line") + CLEAN_LINE=$(echo "$line" | sed -E 's/ \(#[0-9]+\)$//') + if [ -n "$PR" ]; then + echo "$CLEAN_LINE ([#$PR](https://github.com/influxdata/influxdb/pull/$PR))" >> "$OUTPUT_FILE" + else + echo "$CLEAN_LINE" >> "$OUTPUT_FILE" + fi + fi + done +else + echo "- No bug fixes in this release" >> "$OUTPUT_FILE" +fi + +# Add breaking changes if any +if [ -n "$BREAKING" ]; then + cat >> "$OUTPUT_FILE" << EOF + +### Breaking Changes + +EOF + echo "$BREAKING" | while IFS= read -r line; do + if [ -n "$line" ]; then + PR=$(extract_pr_number "$line") + CLEAN_LINE=$(echo "$line" | sed -E 's/ \(#[0-9]+\)$//') + if [ -n "$PR" ]; then + echo "$CLEAN_LINE ([#$PR](https://github.com/influxdata/influxdb/pull/$PR))" >> "$OUTPUT_FILE" + else + echo "$CLEAN_LINE" >> "$OUTPUT_FILE" + fi + fi + done +fi + +# Add performance improvements if any +if [ -n "$PERF" ]; then + cat >> "$OUTPUT_FILE" << EOF + +### Performance Improvements + +EOF + echo "$PERF" | while IFS= read -r line; do + if [ -n "$line" ]; then + PR=$(extract_pr_number "$line") + CLEAN_LINE=$(echo "$line" | sed -E 's/ \(#[0-9]+\)$//') + if [ -n "$PR" ]; then + echo "$CLEAN_LINE ([#$PR](https://github.com/influxdata/influxdb/pull/$PR))" >> "$OUTPUT_FILE" + else + echo "$CLEAN_LINE" >> "$OUTPUT_FILE" + fi + fi + done +fi + +# Add HTTP API changes if any +if [ -n "$API_CHANGES" ]; then + cat >> "$OUTPUT_FILE" << EOF + +### HTTP API Changes + +EOF + echo "$API_CHANGES" | while IFS= read -r line; do + if [ -n "$line" ]; then + PR=$(extract_pr_number "$line") + CLEAN_LINE=$(echo "$line" | sed -E 's/ \(#[0-9]+\)$//') + if [ -n "$PR" ]; then + echo "$CLEAN_LINE ([#$PR](https://github.com/influxdata/influxdb/pull/$PR))" >> "$OUTPUT_FILE" + else + echo "$CLEAN_LINE" >> "$OUTPUT_FILE" + fi + fi + done +fi + +# Add API analysis summary +cat >> "$OUTPUT_FILE" << EOF + +### API Analysis Summary + +The following endpoints may have been affected in this release: +- v1 API endpoints: \`/write\`, \`/query\`, \`/ping\` +- v2 API endpoints: \`/api/v2/write\`, \`/api/v2/query\` +- v3 API endpoints: \`/api/v3/*\` +- System endpoints: \`/health\`, \`/metrics\` + +Please review the commit details above and consult the API documentation for specific changes. + +EOF + +echo -e "\n${GREEN}Release notes generated in: ${OUTPUT_FILE}${NC}" +echo -e "${YELLOW}Please review and edit the generated notes before adding to documentation.${NC}" +echo -e "${BLUE}API changes have been automatically detected and included.${NC}" \ No newline at end of file diff --git a/layouts/index.html b/layouts/index.html index 6bbd51ab6..81859367a 100644 --- a/layouts/index.html +++ b/layouts/index.html @@ -111,7 +111,7 @@
-

InfluxDB 3 Explorer

+

InfluxDB 3 Explorer

A standalone UI designed for visualizing, querying, and managing data in InfluxDB 3 Core and Enterprise.

    diff --git a/layouts/partials/article.html b/layouts/partials/article.html index bbe22ed84..e6becbb1f 100644 --- a/layouts/partials/article.html +++ b/layouts/partials/article.html @@ -5,7 +5,7 @@ {{ partial "article/supported-versions.html" . }} {{ partial "article/page-meta.html" . }}
- {{ partial "article/beta.html" . }} + {{ partial "article/special-state.html" . }} {{ partial "article/stable-version.html" . }} {{ partial "article/flux-experimental.html" . }} {{ partial "article/flux-contrib.html" . }} diff --git a/layouts/partials/article/beta.html b/layouts/partials/article/special-state.html similarity index 70% rename from layouts/partials/article/beta.html rename to layouts/partials/article/special-state.html index d2288dd53..6a89cd7d4 100644 --- a/layouts/partials/article/beta.html +++ b/layouts/partials/article/special-state.html @@ -8,19 +8,23 @@ {{ $earlyAccessList := slice "influxdb3/explorer" }} {{ if in $earlyAccessList (print $product "/" $version )}} -
-
-

{{ $displayName }} is in Public Beta

+
+
+

{{ $displayName }} is Generally Available

- {{ $displayName }} is in public beta and available for testing and feedback, - but is not meant for production use yet. - Both the product and this documentation are works in progress. - We welcome and encourage your input about your experience with the beta and + {{ $displayName }} is generally available and is ready for production use. + We welcome and encourage your input about your experience with Explorer and invite you to join our public channels for updates and to share feedback.

+

+ The {{ $displayName}} documentation is a work in progress, and we are actively + working to improve it. If you have any questions or suggestions, please + submit an issue. + We welcome any and all contributions. +

-
+

Join our public channels

diff --git a/layouts/partials/header.html b/layouts/partials/header.html index 7960d5ed8..419f86196 100644 --- a/layouts/partials/header.html +++ b/layouts/partials/header.html @@ -5,7 +5,7 @@ - {{ if not hugo.IsServer }}{{ partial "header/google-analytics-head.html" }}{{ end }} + {{ partial "header/google-analytics-head.html" }} diff --git a/layouts/partials/header/google-analytics-head.html b/layouts/partials/header/google-analytics-head.html index 42d1a516b..0880fb083 100644 --- a/layouts/partials/header/google-analytics-head.html +++ b/layouts/partials/header/google-analytics-head.html @@ -1,7 +1,28 @@ - - - +{{ if and hugo.IsServer (not (eq .Site.Params.environment "staging")) }} + + + +{{ else }} + + + +{{ end }} diff --git a/layouts/partials/topnav/product-selector.html b/layouts/partials/topnav/product-selector.html index 249ab01bc..0a9e29fb9 100644 --- a/layouts/partials/topnav/product-selector.html +++ b/layouts/partials/topnav/product-selector.html @@ -60,7 +60,7 @@ Identify products by their product path. Dictionary schema:
  • {{ template "productLink" (merge (dict "productPath" "influxdb3/cloud-dedicated") $templateDefaults) }}
      • -
    • {{ template "productLink" (merge (dict "productPath" "influxdb3/explorer" "state" "beta") $templateDefaults) }}
      • +
    • {{ template "productLink" (merge (dict "productPath" "influxdb3/explorer" "state" "New") $templateDefaults) }}
    diff --git a/plans/cli-docs-sync/plan.md b/plans/cli-docs-sync/plan.md new file mode 100644 index 000000000..ca1d3afb9 --- /dev/null +++ b/plans/cli-docs-sync/plan.md @@ -0,0 +1,79 @@ +# Plan: Update InfluxDB 3 CLI Reference Documentation + +## Automation and Process Improvements + +### Immediate Improvements: +1. **Create CLI documentation sync script:** + ```bash + # Script: /Users/ja/Documents/github/docs-v2/scripts/sync-cli-docs.sh + # - Extract help text from influxdb3 CLI at /Users/ja/.influxdb//influxdb3 + # - Compare with existing docs + # - Generate report of differences + # - Auto-update basic command syntax + # - Real-time CLI verification capability established + ``` + +2. **Establish documentation standards:** + - Standardize frontmatter across CLI docs + - Create templates for command documentation + - Define Enterprise vs Core content patterns using Hugo shortcodes + +### Long-term Automation Strategy: +1. **CI/CD Integration:** + - Add GitHub Actions workflow to detect CLI changes + - Auto-generate CLI help extraction on new releases + - Create pull requests for documentation updates + +2. **Release Process Integration:** + - Include CLI documentation review in release checklist + - Link release notes to specific CLI documentation updates + - Automated cross-referencing between release notes and CLI docs + +3. **Content Management Improvements:** + - Use Hugo shortcodes for Enterprise-specific content + - Implement version-aware documentation + - Create shared content templates for common CLI patterns + +## Phase 4: Validation and Testing + +### Content accuracy verification: +- ✅ **CLI Access Available**: Direct verification via `influxdb3 --help` commands +- ✅ **Real-time Validation**: All commands and options verified against actual CLI output +- **Process**: Use `influxdb3 [command] --help` to validate documentation accuracy +- **Verification**: Cross-reference documented options with actual CLI behavior + +### Documentation completeness check: +- Ensure all v3.2.0 features are documented +- Verify examples and use cases +- Check internal links and cross-references + +## Suggested Recurring Process + +### Pre-release (during development): +- Monitor CLI changes in pull requests +- Update documentation as features are added +- Maintain CLI help extraction automation + +### At release (when tagging versions): +- Run automated CLI documentation sync +- Review and approve auto-generated updates +- Publish updated documentation + +### Post-release (after release): +- Validate documentation accuracy +- Gather user feedback on CLI documentation +- Plan improvements for next cycle + +## Related Documentation Paths + +### InfluxDB 3 Product Documentation (affects CLI usage examples): +- `/content/influxdb3/core/write-data/influxdb3-cli.md` +- `/content/influxdb3/enterprise/write-data/influxdb3-cli.md` +- `/content/shared/influxdb3-write-guides/influxdb3-cli.md` + +### Admin Documentation (affects retention and license features): +- `/content/influxdb3/core/admin/` +- `/content/influxdb3/enterprise/admin/` +- `/content/influxdb3/enterprise/admin/license.md` + +This plan ensures comprehensive documentation updates for v3.2.0 while establishing sustainable processes for future releases. \ No newline at end of file diff --git a/test/.gitignore b/test/.gitignore index 726e3ff57..ec06da563 100644 --- a/test/.gitignore +++ b/test/.gitignore @@ -2,6 +2,7 @@ /Cargo.lock config.toml content +influxdb3/**/data _*_pid node_modules shared @@ -9,5 +10,6 @@ tmp .config* .env* **/.env.test +.influxdb3 .pytest_cache .test-run.txt diff --git a/test/influxdb3-plugins/request.py b/test/influxdb3-plugins/request.py deleted file mode 100644 index 254d50569..000000000 --- a/test/influxdb3-plugins/request.py +++ /dev/null @@ -1,24 +0,0 @@ -def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None): - """ - Process an HTTP request to a custom endpoint in the InfluxDB 3 processing engine. - Args: - influxdb3_local: Local InfluxDB API client - query_parameters: Query parameters from the HTTP request - request_headers: Headers from the HTTP request - request_body: Body of the HTTP request - args: Optional arguments passed from the trigger configuration - """ - influxdb3_local.info("Processing HTTP request to custom endpoint") - # Handle HTTP requests to a custom endpoint - - # Log the request parameters - influxdb3_local.info(f"Received request with parameters: {query_parameters}") - - # Process the request body - if request_body: - import json - data = json.loads(request_body) - influxdb3_local.info(f"Request data: {data}") - - # Return a response (automatically converted to JSON) - return {"status": "success", "message": "Request processed"} diff --git a/test/influxdb3-plugins/schedule.py b/test/influxdb3-plugins/schedule.py deleted file mode 100644 index f5cbd9d7f..000000000 --- a/test/influxdb3-plugins/schedule.py +++ /dev/null @@ -1,12 +0,0 @@ -def process_scheduled_call(influxdb3_local, call_time, args=None): - """ - Process a scheduled call from the InfluxDB 3 processing engine. - - Args: - influxdb3_local: Local InfluxDB API client - call_time: Time when the trigger was called - args: Optional arguments passed from the trigger configuration - """ - influxdb3_local.info(f"Processing scheduled call at {call_time}") - if args: - influxdb3_local.info(f"With arguments: {args}") \ No newline at end of file diff --git a/test/influxdb3-plugins/wal_table.py b/test/influxdb3-plugins/wal_table.py deleted file mode 100644 index 05d967500..000000000 --- a/test/influxdb3-plugins/wal_table.py +++ /dev/null @@ -1,18 +0,0 @@ -def process_writes(influxdb3_local, table_batches, args=None): - """ - Process writes to the InfluxDB 3 processing engine, handling - data persisted to the object store. - """ - # Process data as it's written to the database - for table_batch in table_batches: - table_name = table_batch["table_name"] - rows = table_batch["rows"] - - # Log information about the write - influxdb3_local.info(f"Processing {len(rows)} rows from {table_name}") - - # Write derived data back to the database - line = LineBuilder("processed_data") - line.tag("source_table", table_name) - line.int64_field("row_count", len(rows)) - influxdb3_local.write(line) \ No newline at end of file diff --git a/test/influxdb3/engine.test.sh b/test/influxdb3/engine.test.sh new file mode 100644 index 000000000..7c884129a --- /dev/null +++ b/test/influxdb3/engine.test.sh @@ -0,0 +1,20 @@ +# Create a processing engine request trigger +# // SECTION - influxdb3-core +curl -v -X POST "http://localhost:8181/api/v3/configure/processingengine/trigger" \ + --header "Authorization: Bearer ${INFLUXDB3_CORE_ADMIN_TOKEN}" \ + --json '{ + "db": "sensors", + "plugin_filename": "request.py", + "trigger_name": "Process request trigger", + "trigger_specification": "request:process-request" +}' + +# // SECTION - influxdb3-enterprise +curl -v -X POST "http://localhost:8181/api/v3/configure/processingengine/trigger" \ + --header "Authorization: Bearer ${INFLUXDB3_ENTERPRISE_ADMIN_TOKEN}" \ + --json '{ + "db": "sensors", + "plugin_filename": "request.py", + "trigger_name": "Process request trigger", + "trigger_specification": {"request_path": {"path": "process-request"}} +}' \ No newline at end of file diff --git a/test/pytest/requirements.txt b/test/pytest/requirements.txt index 788173c44..c71bcd445 100644 --- a/test/pytest/requirements.txt +++ b/test/pytest/requirements.txt @@ -1,5 +1,5 @@ ## Test dependencies -pytest>=7.4.1 +pytest>=8.4.1 pytest-cov>=2.12.1 pytest-codeblocks>=0.16.1 python-dotenv>=1.0.0