Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'master' into docs/add-dynamic-date-filtering-examples

pull/6278/head
Jason Stirnaman 2025-09-12 11:01:38 -05:00 committed by GitHub
parent 71436aede2 ac22c06d1d
commit 6eaa5e1eec
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
250 changed files with 12305 additions and 5750 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
.ci/link-checker/default.lycherc.toml Normal file
View File

@ -0,0 +1,74 @@
# Lychee link checker configuration
# Generated by link-checker
[lychee]
# Performance settings
# Maximum number of retries for failed checks
max_retries = 3
# Timeout for each link check (in seconds)
timeout = 30
# Maximum number of concurrent checks
max_concurrency = 128
skip_code_blocks = false
# HTTP settings
# Identify the tool to external services
user_agent = "Mozilla/5.0 (compatible; link-checker)"
# Accept these HTTP status codes as valid
accept = [200, 201, 202, 203, 204, 206, 301, 302, 303, 304,
307, 308]
# Skip these URL schemes
scheme = ["file", "mailto", "tel"]
# Exclude patterns (regex supported)
exclude = [
# Localhost URLs
"^https?://localhost",
"^https?://127\\.0\\.0\\.1",
# Common CI/CD environments
"^https?://.*\\.local",
# Example domains used in documentation
"^https?://example\\.(com|org|net)",
# Placeholder URLs from code block filtering
"https://example.com/REMOVED_FROM_CODE_BLOCK",
"example.com/INLINE_CODE_URL",
# URLs that require authentication
"^https?://.*\\.slack\\.com",
"^https?://.*\\.atlassian\\.net",
# GitHub URLs (often fail due to rate limiting and bot
# detection)
"^https?://github\\.com",
# StackExchange network URLs (often block automated requests)
"^https?://.*\\.stackexchange\\.com",
"^https?://stackoverflow\\.com",
"^https?://.*\\.stackoverflow\\.com",
# Docker Hub URLs (rate limiting and bot detection)
"^https?://hub\\.docker\\.com",
# Common documentation placeholders
"YOUR_.*",
"REPLACE_.*",
"<.*>",
]
# Request headers
[headers]
# Add custom headers here if needed
# "Authorization" = "Bearer $GITHUB_TOKEN"
# Cache settings
cache = true
max_cache_age = "1d"

125
.ci/link-checker/production.lycherc.toml Normal file
View File

@ -0,0 +1,125 @@
# Production Link Checker Configuration for InfluxData docs-v2
# Optimized for performance, reliability, and reduced false positives
[lychee]
# Performance settings
# Maximum number of retries for failed checks
max_retries = 3
# Timeout for each link check (in seconds)
timeout = 30
# Maximum number of concurrent checks
max_concurrency = 128
skip_code_blocks = false
# HTTP settings
# Identify the tool to external services
"User-Agent" = "Mozilla/5.0 (compatible; influxdata-link-checker/1.0; +https://github.com/influxdata/docs-v2)"
accept = [200, 201, 202, 203, 204, 206, 301, 302, 303, 304, 307, 308]
# Skip these URL schemes
scheme = ["mailto", "tel"]
# Performance optimizations
cache = true
max_cache_age = "1h"
# Retry configuration for reliability
include_verbatim = false
# Exclusion patterns for docs-v2 (regex supported)
exclude = [
# Localhost URLs
"^https?://localhost",
"^https?://127\\.0\\.0\\.1",
# Common CI/CD environments
"^https?://.*\\.local",
# Example domains used in documentation
"^https?://example\\.(com|org|net)",
# Placeholder URLs from code block filtering
"https://example.com/REMOVED_FROM_CODE_BLOCK",
"example.com/INLINE_CODE_URL",
# URLs that require authentication
"^https?://.*\\.slack\\.com",
"^https?://.*\\.atlassian\\.net",
# GitHub URLs (often fail due to rate limiting and bot
# detection)
"^https?://github\\.com",
# Social media URLs (often block bots)
"^https?://reddit\\.com",
"^https?://.*\\.reddit\\.com",
# StackExchange network URLs (often block automated requests)
"^https?://.*\\.stackexchange\\.com",
"^https?://stackoverflow\\.com",
"^https?://.*\\.stackoverflow\\.com",
# Docker Hub URLs (rate limiting and bot detection)
"^https?://hub\\.docker\\.com",
# InfluxData support URLs (certificate/SSL issues in CI)
"^https?://support\\.influxdata\\.com",
# AI platforms (often block automated requests)
"^https?://claude\\.ai",
"^https?://.*\\.claude\\.ai",
# Production site URLs (when testing locally, these should be relative)
# This excludes canonical URLs and other absolute production URLs
# TODO: Remove after fixing canonical URL generation or link-checker domain replacement
"^https://docs\\.influxdata\\.com/",
# Common documentation placeholders
"YOUR_.*",
"REPLACE_.*",
"<.*>",
]
# Request headers
[headers]
# Add custom headers here if needed
# "Authorization" = "Bearer $GITHUB_TOKEN"
"Accept" = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
"Accept-Language" = "en-US,en;q=0.5"
"Accept-Encoding" = "gzip, deflate"
"DNT" = "1"
"Connection" = "keep-alive"
"Upgrade-Insecure-Requests" = "1"
[ci]
# CI-specific settings
[ci.github_actions]
output_format = "json"
create_annotations = true
fail_fast = false
max_annotations = 50 # Limit to avoid overwhelming PR comments
[ci.performance]
# Performance tuning for CI environment
parallel_requests = 32
connection_timeout = 10
read_timeout = 30
# Resource limits
max_memory_mb = 512
max_execution_time_minutes = 10
[reporting]
# Report configuration
include_fragments = false
verbose = false
no_progress = true # Disable progress bar in CI
# Summary settings
show_success_count = true
show_skipped_count = true

103
.github/actions/report-broken-links/action.yml vendored
View File

@ -1,103 +0,0 @@
name: 'Report Broken Links'
description: 'Downloads broken link reports, generates PR comment, and posts results'
inputs:
github-token:
description: 'GitHub token for posting comments'
required: false
default: ${{ github.token }}
max-links-per-file:
description: 'Maximum links to show per file in comment'
required: false
default: '20'
include-success-message:
description: 'Include success message when no broken links found'
required: false
default: 'true'
outputs:
has-broken-links:
description: 'Whether broken links were found (true/false)'
value: ${{ steps.generate-comment.outputs.has-broken-links }}
broken-link-count:
description: 'Number of broken links found'
value: ${{ steps.generate-comment.outputs.broken-link-count }}
runs:
using: 'composite'
steps:
- name: Download broken link reports
uses: actions/download-artifact@v4
with:
path: reports
continue-on-error: true
- name: Generate PR comment
id: generate-comment
run: |
# Generate comment using our script
node .github/scripts/comment-generator.js \
--max-links ${{ inputs.max-links-per-file }} \
${{ inputs.include-success-message == 'false' && '--no-success' || '' }} \
--output-file comment.md \
reports/ || echo "No reports found or errors occurred"
# Check if comment file was created and has content
if [[ -f comment.md && -s comment.md ]]; then
echo "comment-generated=true" >> $GITHUB_OUTPUT
# Count broken links by parsing the comment
broken_count=$(grep -o "Found [0-9]* broken link" comment.md | grep -o "[0-9]*" || echo "0")
echo "broken-link-count=$broken_count" >> $GITHUB_OUTPUT
# Check if there are actually broken links (not just a success comment)
if [[ "$broken_count" -gt 0 ]]; then
echo "has-broken-links=true" >> $GITHUB_OUTPUT
else
echo "has-broken-links=false" >> $GITHUB_OUTPUT
fi
else
echo "has-broken-links=false" >> $GITHUB_OUTPUT
echo "broken-link-count=0" >> $GITHUB_OUTPUT
echo "comment-generated=false" >> $GITHUB_OUTPUT
fi
shell: bash
- name: Post PR comment
if: steps.generate-comment.outputs.comment-generated == 'true'
uses: actions/github-script@v7
with:
github-token: ${{ inputs.github-token }}
script: |
const fs = require('fs');
if (fs.existsSync('comment.md')) {
const comment = fs.readFileSync('comment.md', 'utf8');
if (comment.trim()) {
await github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
});
}
}
- name: Report validation results
run: |
has_broken_links="${{ steps.generate-comment.outputs.has-broken-links }}"
broken_count="${{ steps.generate-comment.outputs.broken-link-count }}"
if [ "$has_broken_links" = "true" ]; then
echo "::error::❌ Link validation failed: Found $broken_count broken link(s)"
echo "Check the PR comment for detailed broken link information"
exit 1
else
echo "::notice::✅ Link validation passed successfully"
echo "All links in the changed files are valid"
if [ "${{ steps.generate-comment.outputs.comment-generated }}" = "true" ]; then
echo "PR comment posted with validation summary and cache statistics"
fi
fi
shell: bash

106
.github/actions/validate-links/action.yml vendored
View File

@ -1,106 +0,0 @@
name: 'Validate Links'
description: 'Runs e2e browser-based link validation tests against Hugo site using Cypress'
inputs:
files:
description: 'Space-separated list of files to validate'
required: true
product-name:
description: 'Product name for reporting (optional)'
required: false
default: ''
cache-enabled:
description: 'Enable link validation caching'
required: false
default: 'true'
cache-key:
description: 'Cache key prefix for this validation run'
required: false
default: 'link-validation'
timeout:
description: 'Test timeout in seconds'
required: false
default: '900'
outputs:
failed:
description: 'Whether validation failed (true/false)'
value: ${{ steps.validate.outputs.failed }}
runs:
using: 'composite'
steps:
- name: Restore link validation cache
if: inputs.cache-enabled == 'true'
uses: actions/cache@v4
with:
path: .cache/link-validation
key: ${{ inputs.cache-key }}-${{ runner.os }}-${{ hashFiles('content/**/*.md', 'content/**/*.html') }}
restore-keys: |
${{ inputs.cache-key }}-${{ runner.os }}-
${{ inputs.cache-key }}-
- name: Run link validation
shell: bash
run: |
# Set CI-specific environment variables
export CI=true
export GITHUB_ACTIONS=true
export NODE_OPTIONS="--max-old-space-size=4096"
# Set test runner timeout for Hugo shutdown
export HUGO_SHUTDOWN_TIMEOUT=5000
# Add timeout to prevent hanging (timeout command syntax: timeout DURATION COMMAND)
timeout ${{ inputs.timeout }}s node cypress/support/run-e2e-specs.js ${{ inputs.files }} \
--spec cypress/e2e/content/article-links.cy.js || {
exit_code=$?
# Handle timeout specifically
if [ $exit_code -eq 124 ]; then
echo "::error::Link validation timed out after ${{ inputs.timeout }} seconds"
echo "::notice::This may indicate Hugo server startup issues or very slow link validation"
else
echo "::error::Link validation failed with exit code $exit_code"
fi
# Check for specific error patterns and logs (but don't dump full content)
if [ -f /tmp/hugo_server.log ]; then
echo "Hugo server log available for debugging"
fi
if [ -f hugo.log ]; then
echo "Additional Hugo log available for debugging"
fi
if [ -f /tmp/broken_links_report.json ]; then
# Only show summary, not full report (full report is uploaded as artifact)
broken_count=$(grep -o '"url":' /tmp/broken_links_report.json | wc -l || echo "0")
echo "Broken links report contains $broken_count entries"
fi
exit $exit_code
}
# Report success if we get here
echo "::notice::✅ Link validation completed successfully"
echo "No broken links detected in the tested files"
- name: Upload logs on failure
if: failure()
uses: actions/upload-artifact@v4
with:
name: validation-logs-${{ inputs.product-name && inputs.product-name || 'default' }}
path: |
hugo.log
/tmp/hugo_server.log
if-no-files-found: ignore
- name: Upload broken links report
if: always()
uses: actions/upload-artifact@v4
with:
name: broken-links-report${{ inputs.product-name && format('-{0}', inputs.product-name) || '' }}
path: /tmp/broken_links_report.json
if-no-files-found: ignore

442
.github/copilot-instructions.md vendored
View File

@ -1,134 +1,282 @@
# Instructions for InfluxData Documentation
# InfluxData Documentation Repository (docs-v2)
## Purpose and scope
Always follow these instructions first and fallback to additional search and context gathering only when the information provided here is incomplete or found to be in error.
Help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting.
## Working Effectively
## Documentation structure
### Collaboration approach
Be a critical thinking partner, provide honest feedback, and identify potential issues.
### Bootstrap, Build, and Test the Repository
Execute these commands in order to set up a complete working environment:
1. **Install Node.js dependencies** (takes ~4 seconds):
```bash
# Skip Cypress binary download due to network restrictions in CI environments
CYPRESS_INSTALL_BINARY=0 yarn install
```
2. **Build the static site** (takes ~75 seconds, NEVER CANCEL - set timeout to 180+ seconds):
```bash
npx hugo --quiet
```
3. **Start the development server** (builds in ~92 seconds, NEVER CANCEL - set timeout to 150+ seconds):
```bash
npx hugo server --bind 0.0.0.0 --port 1313
```
- Access at: http://localhost:1313/
- Serves 5,359+ pages and 441 static files
- Auto-rebuilds on file changes
4. **Alternative Docker development setup** (use if local Hugo fails):
```bash
docker compose up local-dev
```
**Note**: May fail in restricted network environments due to Alpine package manager issues.
### Testing (CRITICAL: NEVER CANCEL long-running tests)
#### Code Block Testing (takes 5-15 minutes per product, NEVER CANCEL - set timeout to 30+ minutes):
```bash
# Build test environment first (takes ~30 seconds, may fail due to network restrictions)
docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest .
# Test all products (takes 15-45 minutes total)
yarn test:codeblocks:all
# Test specific products
yarn test:codeblocks:cloud
yarn test:codeblocks:v2
yarn test:codeblocks:telegraf
```
#### Link Validation (takes 1-5 minutes):
Runs automatically on pull requests.
Requires the **link-checker** binary from the repo release artifacts.
```bash
# Test specific files/products (faster)
# JSON format is required for accurate reporting
link-checker map content/influxdb3/core/**/*.md \
| link-checker check \
--config .ci/link-checker/production.lycherc.toml
--format json
```
#### Style Linting (takes 30-60 seconds):
```bash
# Basic Vale linting
docker compose run -T vale content/**/*.md
# Product-specific linting with custom configurations
docker compose run -T vale --config=content/influxdb3/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb3/cloud-dedicated/**/*.md
```
#### JavaScript and CSS Linting (takes 5-10 seconds):
```bash
yarn eslint assets/js/**/*.js
yarn prettier --check "**/*.{css,js,ts,jsx,tsx}"
```
### Pre-commit Hooks (automatically run, can be skipped if needed):
```bash
# Run all pre-commit checks manually
yarn lint
# Skip pre-commit hooks if necessary (not recommended)
git commit -m "message" --no-verify
```
## Validation Scenarios
Always test these scenarios after making changes to ensure full functionality:
### 1. Documentation Rendering Test
```bash
# Start Hugo server
npx hugo server --bind 0.0.0.0 --port 1313
# Verify key pages load correctly (200 status)
curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb3/core/
curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb/v2/
curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/telegraf/v1/
# Verify content contains expected elements
curl -s http://localhost:1313/influxdb3/core/ | grep -i "influxdb"
```
### 2. Build Output Validation
```bash
# Verify build completes successfully
npx hugo --quiet
# Check build output exists and has reasonable size (~529MB)
ls -la public/
du -sh public/
# Verify key files exist
file public/index.html
file public/influxdb3/core/index.html
```
### 3. Shortcode and Formatting Test
```bash
# Test shortcode examples page
yarn test:links content/example.md
```
## Repository Structure and Key Locations
### Content Organization
- **InfluxDB 3**: `/content/influxdb3/` (core, enterprise, cloud-dedicated, cloud-serverless, clustered, explorer)
- **InfluxDB v2**: `/content/influxdb/` (v2, cloud, enterprise_influxdb, v1)
- **Telegraf**: `/content/telegraf/v1/`
- **Other tools**: `/content/kapacitor/`, `/content/chronograf/`, `/content/flux/`
- **Shared content**: `/content/shared/`
- **Examples**: `/content/example.md` (comprehensive shortcode reference)
### Configuration Files
- **Hugo config**: `/config/_default/`
- **Package management**: `package.json`, `yarn.lock`
- **Docker**: `compose.yaml`, `Dockerfile.pytest`
- **Git hooks**: `lefthook.yml`
- **Testing**: `cypress.config.js`, `pytest.ini` (in test directories)
- **Linting**: `.vale.ini`, `.prettierrc.yaml`, `eslint.config.js`
### Build and Development
- **Hugo binary**: Available via `npx hugo` (version 0.148.2+)
- **Static assets**: `/assets/` (JavaScript, CSS, images)
- **Build output**: `/public/` (generated, ~529MB)
- **Layouts**: `/layouts/` (Hugo templates)
- **Data files**: `/data/` (YAML/JSON data for templates)
## Technology Stack
- **Static Site Generator**: Hugo (0.148.2+ extended)
- **Package Manager**: Yarn (1.22.22+) with Node.js (20.19.4+)
- **Testing Framework**:
- Pytest with pytest-codeblocks (for code examples)
- Cypress (for E2E tests)
- influxdata/docs-link-checker (for link validation)
- Vale (for style and writing guidelines)
- **Containerization**: Docker with Docker Compose
- **Linting**: ESLint, Prettier, Vale
- **Git Hooks**: Lefthook
## Common Tasks and Build Times
### Network Connectivity Issues
In restricted environments, these commands may fail due to external dependency downloads:
- `docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest .` (InfluxData repositories, HashiCorp repos)
- `docker compose up local-dev` (Alpine package manager)
- Cypress binary installation (use `CYPRESS_INSTALL_BINARY=0`)
Document these limitations but proceed with available functionality.
### Validation Commands for CI
Always run these before committing changes:
```bash
# Format and lint code
yarn prettier --write "**/*.{css,js,ts,jsx,tsx}"
yarn eslint assets/js/**/*.js
# Test Hugo build
npx hugo --quiet
# Test development server startup
timeout 150 npx hugo server --bind 0.0.0.0 --port 1313 &
sleep 120
curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/
pkill hugo
```
## Key Projects in This Codebase
1. **InfluxDB 3 Documentation** (Core, Enterprise, Clustered, Cloud Dedicated, Cloud Serverless, and InfluxDB 3 plugins for Core and Enterprise)
2. **InfluxDB 3 Explorer** (UI)
3. **InfluxDB v2 Documentation** (OSS and Cloud)
3. **InfuxDB v1 Documentation** (OSS and Enterprise)
4. **Telegraf Documentation** (agent and plugins)
5. **Supporting Tools Documentation** (Kapacitor, Chronograf, Flux)
6. **API Reference Documentation** (`/api-docs/`)
7. **Shared Documentation Components** (`/content/shared/`)
## Important Locations for Frequent Tasks
- **Shortcode reference**: `/content/example.md`
- **Contributing guide**: `CONTRIBUTING.md`
- **Testing guide**: `TESTING.md`
- **Product configurations**: `/data/products.yml`
- **Vale style rules**: `/.ci/vale/styles/`
- **GitHub workflows**: `/.github/workflows/`
- **Test scripts**: `/test/scripts/`
- **Hugo layouts and shortcodes**: `/layouts/`
- **CSS/JS assets**: `/assets/`
## Content Guidelines and Style
### Documentation Structure
- **Product version data**: `/data/products.yml`
- **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/
- Code repositories: https://github.com/influxdata/influxdb, https://github.com/influxdata/influxdb3_core
- InfluxDB 3 Enterprise
- Documentation source path: `/content/influxdb3/enterprise`
- Published for the web: https://docs.influxdata.com/influxdb3/enterprise/
- Code repositories: https://github.com/influxdata/influxdb, https://github.com/influxdata/influxdb3_enterprise
- InfluxDB Cloud Dedicated
- Documentation source path: `/content/influxdb3/cloud-dedicated`
- Published for the web: https://docs.influxdata.com/influxdb3/cloud-dedicated/
- Code repository: https://github.com/influxdata/influxdb
- InfluxDB Cloud Serverless
- Documentation source path: `/content/influxdb3/cloud-serverless`
- Published for the web: https://docs.influxdata.com/influxdb3/cloud-serverless/
- Code repository: https://github.com/influxdata/idpe
- InfluxDB Cloud v2 (TSM)
- Documentation source path: `/content/influxdb/cloud`
- Published for the web: https://docs.influxdata.com/influxdb/cloud/
- Code repository: https://github.com/influxdata/idpe
- InfluxDB Clustered
- Documentation source path: `/content/influxdb3/clustered`
- Published for the web: https://docs.influxdata.com/influxdb3/clustered/
- Code repository: https://github.com/influxdata/influxdb
- InfluxDB Enterprise v1 (1.x)
- Documentation source path: `/content/influxdb/enterprise_influxdb`
- Published for the web: https://docs.influxdata.com/enterprise_influxdb/v1/
- Code repository: https://github.com/influxdata/influxdb
- InfluxDB OSS 1.x
- Documentation source path: `/content/influxdb/v1`
- Published for the web: https://docs.influxdata.com/influxdb/v1/
- Code repository: https://github.com/influxdata/influxdb
- InfluxDB OSS 2.x
- Documentation source path: `/content/influxdb/v2`
- Published for the web: https://docs.influxdata.com/influxdb/v2/
- Code repository: https://github.com/influxdata/influxdb
- Telegraf
- Documentation source path: `/content/telegraf/v1`
- Published for the web: https://docs.influxdata.com/telegraf/v1/
- Code repository: https://github.com/influxdata/telegraf
- Kapacitor
- Documentation source path: `/content/kapacitor/v1`
- Published for the web: https://docs.influxdata.com/kapacitor/v1/
- Code repository: https://github.com/influxdata/kapacitor
- Chronograf
- Documentation source path: `/content/chronograf/v1`
- Published for the web: https://docs.influxdata.com/chronograf/v1/
- Code repository: https://github.com/influxdata/chronograf
- Flux
- Documentation source path: `/content/flux/v0`
- Published for the web: https://docs.influxdata.com/flux/v0/
- Code repository: https://github.com/influxdata/flux
- **InfluxData-supported tools**:
- InfluxDB API client libraries
- Code repositories: https://github.com/InfluxCommunity
- InfluxDB 3 processing engine plugins
- Code repository: https://github.com/influxdata/influxdb3_plugins
- **Query Languages**: SQL, InfluxQL, Flux (use appropriate language per product version)
- **Documentation Site**: https://docs.influxdata.com
- **Repository**: https://github.com/influxdata/docs-v2
- **Framework**: Hugo static site generator
## Abbreviations and shortcuts
- `gdd`: Google Developer Documentation style
- `3core`: InfluxDB 3 Core
- `3ent`: InfluxDB 3 Enterprise
## Style guidelines
### Style Guidelines
- Follow Google Developer Documentation style guidelines
- For API references, follow YouTube Data API style
- Use semantic line feeds (one sentence per line)
- Format code examples to fit within 80 characters
- Command line examples:
- Should be formatted as code blocks
- Should use long options (e.g., `--option` instead of `-o`)
- Use cURL for API examples
- Format to fit within 80 characters
- Should use `--data-urlencode` for query parameters
- Should use `--header` for headers
- Use only h2-h6 headings in content (h1 comes from frontmatter title properties)
- Use sentence case for headings
- Use GitHub callout syntax
- Use long options in command line examples (`--option` instead of `-o`)
- Use GitHub callout syntax for notes and warnings
- Image naming: `project/version-context-description.png`
- Use appropriate product names and versions consistently
- Follow InfluxData vocabulary guidelines
## Markdown and shortcodes
### Markdown and Shortcodes
- Include proper frontmatter for Markdown pages in `content/**/*.md` (except for
shared content files in `content/shared/`):
Include proper frontmatter for all content pages:
```yaml
title: # Page title (h1)
seotitle: # SEO title
list_title: # Title for article lists
description: # SEO description
menu:
product_version:
weight: # Page order (1-99, 101-199, etc.)
```
- Follow the shortcode examples in `content/example.md` and the documentation
for docs-v2 contributors in `CONTRIBUTING.md`
- Use provided shortcodes correctly:
- Notes/warnings: `{{% note %}}`, `{{% warn %}}`
- Product-specific: `{{% enterprise %}}`, `{{% cloud %}}`
- Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}`
- Tabbed content for code examples (without additional text): `{{< code-tabs-wrapper >}}`, `{{% code-tabs %}}`, `{{% code-tab-content %}}`
- Version links: `{{< latest >}}`, `{{< latest-patch >}}`
- API endpoints: `{{< api-endpoint >}}`
- Required elements: `{{< req >}}`
- Navigation: `{{< page-nav >}}`
- Diagrams: `{{< diagram >}}`, `{{< filesystem-diagram >}}`
```yaml
title: # Page title (h1)
seotitle: # SEO title
description: # SEO description
menu:
product_version:
weight: # Page order (1-99, 101-199, etc.)
```
## Code examples and testing
Key shortcodes (see `/content/example.md` for full reference):
- Provide complete, working examples with proper testing annotations:
- Notes/warnings (GitHub syntax): `> [!Note]`, `> [!Warning]`
- Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}`
- Code examples: `{{< code-tabs-wrapper >}}`, `{{% code-tabs %}}`, `{{% code-tab-content %}}`
- Required elements: `{{< req >}}`
- API endpoints: `{{< api-endpoint >}}`
### Code Examples and Testing
Provide complete, working examples with pytest annotations:
```python
print("Hello, world!")
@ -140,67 +288,21 @@ print("Hello, world!")
Hello, world!
```
- CLI command example:
## Troubleshooting Common Issues
```sh
influx query 'from(bucket:"example") |> range(start:-1h)'
```
1. **"Pytest collected 0 items"**: Use `python` (not `py`) for code block language identifiers
2. **Hugo build errors**: Check `/config/_default/` for configuration issues
3. **Docker build failures**: Expected in restricted networks - document and continue with local Hugo
4. **Cypress installation failures**: Use `CYPRESS_INSTALL_BINARY=0 yarn install`
5. **Link validation slow**: Use file-specific testing: `yarn test:links content/specific-file.md`
6. **Vale linting errors**: Check `.ci/vale/styles/config/vocabularies` for accepted/rejected terms
<!--pytest-codeblocks:expected-output-->
```
Table: keys: [_start, _stop, _field, _measurement]
_start:time _stop:time _field:string _measurement:string _time:time _value:float
------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ----------------------------
```
- Include necessary environment variables
- Show proper credential handling for authenticated commands
## API documentation
- `/api-docs` contains OpenAPI spec files used for API reference documentation
- Follow OpenAPI specification patterns
- Match REST API examples to current implementation
- Include complete request/response examples
- Document required headers and authentication
## Versioning and product differentiation
- Clearly distinguish between different InfluxDB versions (1.x, 2.x, 3.x)
- Use correct terminology for each product variant
- Apply appropriate UI descriptions and screenshots
- Reference appropriate query language per version
## Development tools
- Vale.sh linter for style checking
- Configuration file: `.vale.ini`
- Docker for local development and testing
- pytest and pytest-codeblocks for validating code examples
- Use cypress for testing documentation UI and links
- Prettier for code formatting
- ESLint for JavaScript and TypeScript linting
- Lefthook (NPM package) for managing pre-commit hooks for quality assurance
## Code style
- Use modern JavaScript (ES6+) syntax
## Related repositories
- **Internal documentation assistance requests**: https://github.com/influxdata/DAR/issues Documentation
## Additional instruction files
## 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
- **InfluxDB 3 code placeholders**: `.github/instructions/influxdb3-code-placeholders.instructions.md`
- **Contributing guidelines**: `.github/instructions/contributing.instructions.md`
- **Content-specific instructions**: Check `.github/instructions/` directory
## 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`.
Remember: This is a large documentation site with complex build processes. Patience with build times is essential, and NEVER CANCEL long-running operations.

241
.github/workflows/pr-link-check.yml vendored Normal file
View File

@ -0,0 +1,241 @@
name: Link Check PR Changes
on:
pull_request:
paths:
- 'content/**/*.md'
- 'data/**/*.yml'
- 'layouts/**/*.html'
types: [opened, synchronize, reopened]
jobs:
link-check:
name: Check links in affected files
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Detect content changes
id: detect
run: |
echo "🔍 Detecting changes between ${{ github.base_ref }} and ${{ github.sha }}"
# For PRs, use the GitHub Files API to get changed files
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
echo "Using GitHub API to detect PR changes..."
curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
"https://api.github.com/repos/${{ github.repository }}/pulls/${{ github.event.number }}/files" \
| jq -r '.[].filename' > all_changed_files.txt
else
echo "Using git diff to detect changes..."
git diff --name-only ${{ github.event.before }}..${{ github.sha }} > all_changed_files.txt
fi
# Filter for content markdown files
CHANGED_FILES=$(grep '^content/.*\.md$' all_changed_files.txt || true)
echo "📁 All changed files:"
cat all_changed_files.txt
echo ""
echo "📝 Content markdown files:"
echo "$CHANGED_FILES"
if [[ -n "$CHANGED_FILES" ]]; then
echo "✅ Found $(echo "$CHANGED_FILES" | wc -l) changed content file(s)"
echo "has-changes=true" >> $GITHUB_OUTPUT
echo "changed-content<<EOF" >> $GITHUB_OUTPUT
echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
# Check if any shared content files were modified
SHARED_CHANGES=$(echo "$CHANGED_FILES" | grep '^content/shared/' || true)
if [[ -n "$SHARED_CHANGES" ]]; then
echo "has-shared-content=true" >> $GITHUB_OUTPUT
echo "🔄 Detected shared content changes: $SHARED_CHANGES"
else
echo "has-shared-content=false" >> $GITHUB_OUTPUT
fi
else
echo "❌ No content changes detected"
echo "has-changes=false" >> $GITHUB_OUTPUT
echo "has-shared-content=false" >> $GITHUB_OUTPUT
fi
- name: Skip if no content changes
if: steps.detect.outputs.has-changes == 'false'
run: |
echo "No content changes detected in this PR - skipping link check"
echo "✅ **No content changes detected** - link check skipped" >> $GITHUB_STEP_SUMMARY
- name: Setup Node.js
if: steps.detect.outputs.has-changes == 'true'
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'yarn'
- name: Install dependencies
if: steps.detect.outputs.has-changes == 'true'
run: yarn install --frozen-lockfile
- name: Build Hugo site
if: steps.detect.outputs.has-changes == 'true'
run: npx hugo --minify
- name: Download link-checker binary
if: steps.detect.outputs.has-changes == 'true'
run: |
echo "Downloading link-checker binary from docs-v2 releases..."
# Download from docs-v2's own releases (always accessible)
curl -L -H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
-o link-checker-info.json \
"https://api.github.com/repos/influxdata/docs-v2/releases/tags/link-checker-v1.2.3"
# Extract download URL for linux binary
DOWNLOAD_URL=$(jq -r '.assets[] | select(.name | test("link-checker.*linux")) | .url' link-checker-info.json)
if [[ "$DOWNLOAD_URL" == "null" || -z "$DOWNLOAD_URL" ]]; then
echo "❌ No linux binary found in release"
echo "Available assets:"
jq -r '.assets[].name' link-checker-info.json
exit 1
fi
echo "📥 Downloading: $DOWNLOAD_URL"
curl -L -H "Accept: application/octet-stream" \
-H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
-o link-checker "$DOWNLOAD_URL"
chmod +x link-checker
./link-checker --version
- name: Verify link checker config exists
if: steps.detect.outputs.has-changes == 'true'
run: |
if [[ ! -f .ci/link-checker/production.lycherc.toml ]]; then
echo "❌ Configuration file .ci/link-checker/production.lycherc.toml not found"
echo "Please copy production.lycherc.toml from docs-tooling/link-checker/"
exit 1
fi
echo "✅ Using configuration: .ci/link-checker/production.lycherc.toml"
- name: Map changed content to public files
if: steps.detect.outputs.has-changes == 'true'
id: mapping
run: |
echo "Mapping changed content files to public HTML files..."
# Create temporary file with changed content files
echo "${{ steps.detect.outputs.changed-content }}" > changed-files.txt
# Map content files to public files
PUBLIC_FILES=$(cat changed-files.txt | xargs -r ./link-checker map --existing-only)
if [[ -n "$PUBLIC_FILES" ]]; then
echo "Found affected public files:"
echo "$PUBLIC_FILES"
echo "public-files<<EOF" >> $GITHUB_OUTPUT
echo "$PUBLIC_FILES" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
# Count files for summary
FILE_COUNT=$(echo "$PUBLIC_FILES" | wc -l)
echo "file-count=$FILE_COUNT" >> $GITHUB_OUTPUT
else
echo "No public files found to check"
echo "public-files=" >> $GITHUB_OUTPUT
echo "file-count=0" >> $GITHUB_OUTPUT
fi
- name: Run link checker
if: steps.detect.outputs.has-changes == 'true' && steps.mapping.outputs.public-files != ''
id: link-check
run: |
echo "Checking links in ${{ steps.mapping.outputs.file-count }} affected files..."
# Create temporary file with public files list
echo "${{ steps.mapping.outputs.public-files }}" > public-files.txt
# Run link checker with detailed JSON output
set +e # Don't fail immediately on error
cat public-files.txt | xargs -r ./link-checker check \
--config .ci/link-checker/production.lycherc.toml \
--format json \
--output link-check-results.json
EXIT_CODE=$?
if [[ -f link-check-results.json ]]; then
# Parse results
BROKEN_COUNT=$(jq -r '.summary.broken_count // 0' link-check-results.json)
TOTAL_COUNT=$(jq -r '.summary.total_checked // 0' link-check-results.json)
SUCCESS_RATE=$(jq -r '.summary.success_rate // 0' link-check-results.json)
echo "broken-count=$BROKEN_COUNT" >> $GITHUB_OUTPUT
echo "total-count=$TOTAL_COUNT" >> $GITHUB_OUTPUT
echo "success-rate=$SUCCESS_RATE" >> $GITHUB_OUTPUT
if [[ $BROKEN_COUNT -gt 0 ]]; then
echo "❌ Found $BROKEN_COUNT broken links out of $TOTAL_COUNT total links"
echo "check-result=failed" >> $GITHUB_OUTPUT
else
echo "✅ All $TOTAL_COUNT links are valid"
echo "check-result=passed" >> $GITHUB_OUTPUT
fi
else
echo "❌ Link check failed to generate results"
echo "check-result=error" >> $GITHUB_OUTPUT
fi
exit $EXIT_CODE
- name: Process and report results
if: always() && steps.detect.outputs.has-changes == 'true' && steps.mapping.outputs.public-files != ''
run: |
if [[ -f link-check-results.json ]]; then
# Create detailed error annotations for broken links
if [[ "${{ steps.link-check.outputs.check-result }}" == "failed" ]]; then
echo "Creating error annotations for broken links..."
jq -r '.broken_links[]? |
"::error file=\(.file // "unknown"),line=\(.line // 1)::Broken link: \(.url) - \(.error // "Unknown error")"' \
link-check-results.json || true
fi
# Generate summary comment
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
## Link Check Results
**Files Checked:** ${{ steps.mapping.outputs.file-count }}
**Total Links:** ${{ steps.link-check.outputs.total-count }}
**Broken Links:** ${{ steps.link-check.outputs.broken-count }}
**Success Rate:** ${{ steps.link-check.outputs.success-rate }}%
EOF
if [[ "${{ steps.link-check.outputs.check-result }}" == "failed" ]]; then
echo "❌ **Link check failed** - see annotations above for details" >> $GITHUB_STEP_SUMMARY
else
echo "✅ **All links are valid**" >> $GITHUB_STEP_SUMMARY
fi
else
echo "⚠️ **Link check could not complete** - no results file generated" >> $GITHUB_STEP_SUMMARY
fi
- name: Upload detailed results
if: always() && steps.detect.outputs.has-changes == 'true' && steps.mapping.outputs.public-files != ''
uses: actions/upload-artifact@v4
with:
name: link-check-results
path: |
link-check-results.json
changed-files.txt
public-files.txt
retention-days: 30

148
.github/workflows/pr-link-validation.yml vendored
View File

@ -1,148 +0,0 @@
# PR Link Validation Workflow
# Provides basic and parallel workflows
# with smart strategy selection based on change volume
name: PR Link Validation
on:
pull_request:
paths:
- 'content/**/*.md'
- 'content/**/*.html'
- 'api-docs/**/*.yml'
- 'assets/**/*.js'
- 'layouts/**/*.html'
jobs:
# TEMPORARILY DISABLED - Remove this condition to re-enable link validation
disabled-check:
if: false # Set to true to re-enable the workflow
runs-on: ubuntu-latest
steps:
- run: echo "Link validation is temporarily disabled"
setup:
name: Setup and Strategy Detection
runs-on: ubuntu-latest
if: false # TEMPORARILY DISABLED - Remove this condition to re-enable
outputs:
strategy: ${{ steps.determine-strategy.outputs.strategy }}
has-changes: ${{ steps.determine-strategy.outputs.has-changes }}
matrix: ${{ steps.determine-strategy.outputs.matrix }}
all-files: ${{ steps.changed-files.outputs.all_changed_files }}
cache-hit-rate: ${{ steps.determine-strategy.outputs.cache-hit-rate }}
cache-hits: ${{ steps.determine-strategy.outputs.cache-hits }}
cache-misses: ${{ steps.determine-strategy.outputs.cache-misses }}
original-file-count: ${{ steps.determine-strategy.outputs.original-file-count }}
validation-file-count: ${{ steps.determine-strategy.outputs.validation-file-count }}
cache-message: ${{ steps.determine-strategy.outputs.message }}
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup docs environment
uses: ./.github/actions/setup-docs-env
- name: Get changed files
id: changed-files
uses: tj-actions/changed-files@v41
with:
files: |
content/**/*.md
content/**/*.html
api-docs/**/*.yml
- name: Determine validation strategy
id: determine-strategy
run: |
if [[ "${{ steps.changed-files.outputs.any_changed }}" != "true" ]]; then
echo "No relevant files changed"
echo "strategy=none" >> $GITHUB_OUTPUT
echo "has-changes=false" >> $GITHUB_OUTPUT
echo "matrix={\"include\":[]}" >> $GITHUB_OUTPUT
echo "cache-hit-rate=100" >> $GITHUB_OUTPUT
echo "cache-hits=0" >> $GITHUB_OUTPUT
echo "cache-misses=0" >> $GITHUB_OUTPUT
exit 0
fi
# Use our matrix generator with cache awareness
files="${{ steps.changed-files.outputs.all_changed_files }}"
echo "🔍 Analyzing ${files} for cache-aware validation..."
# Generate matrix and capture outputs
result=$(node .github/scripts/matrix-generator.js \
--min-files-parallel 10 \
--max-concurrent 5 \
--output-format github \
$files)
# Parse all outputs from matrix generator
while IFS='=' read -r key value; do
case "$key" in
strategy|has-changes|cache-hit-rate|cache-hits|cache-misses|original-file-count|validation-file-count|message)
echo "$key=$value" >> $GITHUB_OUTPUT
;;
matrix)
echo "matrix=$value" >> $GITHUB_OUTPUT
;;
esac
done <<< "$result"
# Extract values for logging
strategy=$(echo "$result" | grep "^strategy=" | cut -d'=' -f2)
cache_hit_rate=$(echo "$result" | grep "^cache-hit-rate=" | cut -d'=' -f2)
cache_message=$(echo "$result" | grep "^message=" | cut -d'=' -f2-)
echo "📊 Selected strategy: $strategy"
if [[ -n "$cache_hit_rate" ]]; then
echo "📈 Cache hit rate: ${cache_hit_rate}%"
fi
if [[ -n "$cache_message" ]]; then
echo "$cache_message"
fi
validate:
name: ${{ matrix.name }}
needs: setup
if: false # TEMPORARILY DISABLED - Original condition: needs.setup.outputs.has-changes == 'true'
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix: ${{ fromJson(needs.setup.outputs.matrix) }}
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup docs environment
uses: ./.github/actions/setup-docs-env
- name: Validate links
uses: ./.github/actions/validate-links
with:
files: ${{ matrix.files || needs.setup.outputs.all-files }}
product-name: ${{ matrix.product }}
cache-enabled: ${{ matrix.cacheEnabled || 'true' }}
cache-key: link-validation-${{ hashFiles(matrix.files || needs.setup.outputs.all-files) }}
timeout: 900
report:
name: Report Results
needs: [setup, validate]
if: false # TEMPORARILY DISABLED - Original condition: always() && needs.setup.outputs.has-changes == 'true'
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup docs environment
uses: ./.github/actions/setup-docs-env
- name: Report broken links
uses: ./.github/actions/report-broken-links
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
max-links-per-file: 20

68
.github/workflows/sync-link-checker-binary.yml vendored Normal file
View File

@ -0,0 +1,68 @@
name: Sync Link Checker Binary from docs-tooling
on:
workflow_dispatch:
inputs:
version:
description: 'Link checker version to sync (e.g., v1.2.2)'
required: true
type: string
jobs:
sync-binary:
name: Sync link-checker binary from docs-tooling
runs-on: ubuntu-latest
steps:
- name: Download binary from docs-tooling release
run: |
echo "Downloading link-checker ${{ inputs.version }} from docs-tooling..."
# Download binary from docs-tooling release
curl -L -H "Accept: application/octet-stream" \
-H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
-o link-checker-linux-x86_64 \
"https://github.com/influxdata/docs-tooling/releases/download/link-checker-${{ inputs.version }}/link-checker-linux-x86_64"
# Download checksums
curl -L -H "Accept: application/octet-stream" \
-H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
-o checksums.txt \
"https://github.com/influxdata/docs-tooling/releases/download/link-checker-${{ inputs.version }}/checksums.txt"
# Verify downloads
ls -la link-checker-linux-x86_64 checksums.txt
- name: Create docs-v2 release
run: |
echo "Creating link-checker-${{ inputs.version }} release in docs-v2..."
gh release create \
--title "Link Checker Binary ${{ inputs.version }}" \
--notes "Link validation tooling binary for docs-v2 GitHub Actions workflows.
This binary is distributed from the docs-tooling repository release link-checker-${{ inputs.version }}.
### Usage in GitHub Actions
The binary is automatically downloaded by docs-v2 workflows for link validation.
### Manual Usage
\`\`\`bash
# Download and make executable
curl -L -o link-checker https://github.com/influxdata/docs-v2/releases/download/link-checker-${{ inputs.version }}/link-checker-linux-x86_64
chmod +x link-checker
# Verify installation
./link-checker --version
\`\`\`
### Changes in ${{ inputs.version }}
See the [docs-tooling release](https://github.com/influxdata/docs-tooling/releases/tag/link-checker-${{ inputs.version }}) for detailed changelog." \
link-checker-${{ inputs.version }} \
link-checker-linux-x86_64 \
checksums.txt
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

13
.gitignore vendored
View File

@ -3,11 +3,14 @@
public
.*.swp
node_modules
package-lock.json
.config*
**/.env*
*.log
/resources
.hugo_build.lock
# Content generation
/content/influxdb*/**/api/**/*.html
!api-docs/**/.config.yml
/api-docs/redoc-static.html*
@ -16,18 +19,22 @@ node_modules
!telegraf-build/templates
!telegraf-build/scripts
!telegraf-build/README.md
# CI/CD tool files
/cypress/downloads/*
/cypress/screenshots/*
/cypress/videos/*
.lycheecache
test-results.xml
/influxdb3cli-build-scripts/content
tmp
# IDE files
.vscode/*
!.vscode/launch.json
.idea
**/config.toml
package-lock.json
tmp
# Context files for LLMs and AI tools
# User context files for AI assistant tools
.context/*
!.context/README.md

16
.husky/_/pre-commit
View File

@ -33,6 +33,9 @@ call_lefthook()
then
"$dir/node_modules/lefthook/bin/index.js" "$@"
elif go tool lefthook -h >/dev/null 2>&1
then
go tool lefthook "$@"
elif bundle exec lefthook -h >/dev/null 2>&1
then
bundle exec lefthook "$@"
@ -42,12 +45,21 @@ call_lefthook()
elif pnpm lefthook -h >/dev/null 2>&1
then
pnpm lefthook "$@"
elif swift package plugin lefthook >/dev/null 2>&1
elif swift package lefthook >/dev/null 2>&1
then
swift package --disable-sandbox plugin lefthook "$@"
swift package --build-path .build/lefthook --disable-sandbox lefthook "$@"
elif command -v mint >/dev/null 2>&1
then
mint run csjones/lefthook-plugin "$@"
elif uv run lefthook -h >/dev/null 2>&1
then
uv run lefthook "$@"
elif mise exec -- lefthook -h >/dev/null 2>&1
then
mise exec -- lefthook "$@"
elif devbox run lefthook -h >/dev/null 2>&1
then
devbox run lefthook "$@"
else
echo "Can't find lefthook in PATH"
fi

16
.husky/_/pre-push
View File

@ -33,6 +33,9 @@ call_lefthook()
then
"$dir/node_modules/lefthook/bin/index.js" "$@"
elif go tool lefthook -h >/dev/null 2>&1
then
go tool lefthook "$@"
elif bundle exec lefthook -h >/dev/null 2>&1
then
bundle exec lefthook "$@"
@ -42,12 +45,21 @@ call_lefthook()
elif pnpm lefthook -h >/dev/null 2>&1
then
pnpm lefthook "$@"
elif swift package plugin lefthook >/dev/null 2>&1
elif swift package lefthook >/dev/null 2>&1
then
swift package --disable-sandbox plugin lefthook "$@"
swift package --build-path .build/lefthook --disable-sandbox lefthook "$@"
elif command -v mint >/dev/null 2>&1
then
mint run csjones/lefthook-plugin "$@"
elif uv run lefthook -h >/dev/null 2>&1
then
uv run lefthook "$@"
elif mise exec -- lefthook -h >/dev/null 2>&1
then
mise exec -- lefthook "$@"
elif devbox run lefthook -h >/dev/null 2>&1
then
devbox run lefthook "$@"
else
echo "Can't find lefthook in PATH"
fi

16
.husky/_/prepare-commit-msg
View File

@ -33,6 +33,9 @@ call_lefthook()
then
"$dir/node_modules/lefthook/bin/index.js" "$@"
elif go tool lefthook -h >/dev/null 2>&1
then
go tool lefthook "$@"
elif bundle exec lefthook -h >/dev/null 2>&1
then
bundle exec lefthook "$@"
@ -42,12 +45,21 @@ call_lefthook()
elif pnpm lefthook -h >/dev/null 2>&1
then
pnpm lefthook "$@"
elif swift package plugin lefthook >/dev/null 2>&1
elif swift package lefthook >/dev/null 2>&1
then
swift package --disable-sandbox plugin lefthook "$@"
swift package --build-path .build/lefthook --disable-sandbox lefthook "$@"
elif command -v mint >/dev/null 2>&1
then
mint run csjones/lefthook-plugin "$@"
elif uv run lefthook -h >/dev/null 2>&1
then
uv run lefthook "$@"
elif mise exec -- lefthook -h >/dev/null 2>&1
then
mise exec -- lefthook "$@"
elif devbox run lefthook -h >/dev/null 2>&1
then
devbox run lefthook "$@"
else
echo "Can't find lefthook in PATH"
fi

20
.mcp.json Normal file
View File

@ -0,0 +1,20 @@
{
"$schema": "https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/refs/heads/main/schema/2025-06-18/schema.json",
"description": "InfluxData documentation assistance via MCP server - Node.js execution",
"mcpServers": {
"influxdata": {
"comment": "Use Node to run Docs MCP. To install and setup, see https://github.com/influxdata/docs-mcp-server",
"type": "stdio",
"command": "node",
"args": [
"${DOCS_MCP_SERVER_PATH}/dist/index.js"
],
"env": {
"DOCS_API_KEY_FILE": "${DOCS_API_KEY_FILE:-$HOME/.env.docs-kapa-api-key}",
"DOCS_MODE": "external-only",
"MCP_LOG_LEVEL": "${MCP_LOG_LEVEL:-info}",
"NODE_ENV": "${NODE_ENV:-production}"
}
}
}
}

14
.vscode/settings.json vendored
View File

@ -14,18 +14,8 @@
},
"vale.valeCLI.config": "${workspaceFolder}/.vale.ini",
"vale.valeCLI.minAlertLevel": "warning",
"github.copilot.chat.codeGeneration.useInstructionFiles": true,
"github.copilot.chat.codeGeneration.instructions": [
{
"file": "${workspaceFolder}/.github/copilot-instructions.md",
}
],
"github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
{
"file": "${workspaceFolder}/.github/copilot-instructions.md",
}
],
"cSpell.words": [
"influxctl"
"influxctl",
"preconfigured"
]
}

301
TESTING.md
View File

@ -121,96 +121,251 @@ Potential causes:
# This is ignored
```
## Link Validation Testing
## Link Validation with Link-Checker
Link validation uses Cypress for e2e browser-based testing against the Hugo site to ensure all internal and external links work correctly.
Link validation uses the `link-checker` tool to validate internal and external links in documentation files.
### Basic Usage
#### Installation
**Option 1: Build from source (macOS/local development)**
For local development on macOS, build the link-checker from source:
```bash
# Test specific files
yarn test:links content/influxdb3/core/**/*.md
# Clone and build link-checker
git clone https://github.com/influxdata/docs-tooling.git
cd docs-tooling/link-checker
cargo build --release
# Test all links (may take a long time)
yarn test:links
# Test by product (may take a long time)
yarn test:links:v3
yarn test:links:v2
yarn test:links:telegraf
yarn test:links:chronograf
yarn test:links:kapacitor
# Copy binary to your PATH or use directly
cp target/release/link-checker /usr/local/bin/
# OR use directly: ./target/release/link-checker
```
### How Link Validation Works
**Option 2: Download pre-built binary (GitHub Actions/Linux)**
The tests:
1. Start a Hugo development server
2. Navigate to each page in a browser
3. Check all links for validity
4. Report broken or invalid links
The link-checker binary is distributed via docs-v2 releases for reliable access from GitHub Actions workflows:
```bash
# Download Linux binary from docs-v2 releases
curl -L -o link-checker \
https://github.com/influxdata/docs-v2/releases/download/link-checker-v1.0.0/link-checker-linux-x86_64
chmod +x link-checker
# Verify installation
./link-checker --version
```
> [!Note]
> Pre-built binaries are currently Linux x86_64 only. For macOS development, use Option 1 to build from source.
```bash
# Clone and build link-checker
git clone https://github.com/influxdata/docs-tooling.git
cd docs-tooling/link-checker
cargo build --release
# Copy binary to your PATH or use directly
cp target/release/link-checker /usr/local/bin/
```
#### Binary Release Process
**For maintainers:** To create a new link-checker release in docs-v2:
1. **Create release in docs-tooling** (builds and releases binary automatically):
```bash
cd docs-tooling
git tag link-checker-v1.2.x
git push origin link-checker-v1.2.x
```
2. **Manually distribute to docs-v2** (required due to private repository access):
```bash
# Download binary from docs-tooling release
curl -L -H "Authorization: Bearer $(gh auth token)" \
-o link-checker-linux-x86_64 \
"https://github.com/influxdata/docs-tooling/releases/download/link-checker-v1.2.x/link-checker-linux-x86_64"
curl -L -H "Authorization: Bearer $(gh auth token)" \
-o checksums.txt \
"https://github.com/influxdata/docs-tooling/releases/download/link-checker-v1.2.x/checksums.txt"
# Create docs-v2 release
gh release create \
--repo influxdata/docs-v2 \
--title "Link Checker Binary v1.2.x" \
--notes "Link validation tooling binary for docs-v2 GitHub Actions workflows." \
link-checker-v1.2.x \
link-checker-linux-x86_64 \
checksums.txt
```
3. **Update workflow reference** (if needed):
```bash
# Update .github/workflows/pr-link-check.yml line 98 to use new version
sed -i 's/link-checker-v[0-9.]*/link-checker-v1.2.x/' .github/workflows/pr-link-check.yml
```
> [!Note]
> The manual distribution is required because docs-tooling is a private repository and the default GitHub token doesn't have cross-repository access for private repos.
#### Core Commands
```bash
# Map content files to public HTML files
link-checker map content/path/to/file.md
# Check links in HTML files
link-checker check public/path/to/file.html
# Generate configuration file
link-checker config
```
### Link Resolution Behavior
The link-checker automatically handles relative link resolution based on the input type:
**Local Files → Local Resolution**
```bash
# When checking local files, relative links resolve to the local filesystem
link-checker check public/influxdb3/core/admin/scale-cluster/index.html
# Relative link /influxdb3/clustered/tags/kubernetes/ becomes:
# → /path/to/public/influxdb3/clustered/tags/kubernetes/index.html
```
**URLs → Production Resolution**
```bash
# When checking URLs, relative links resolve to the production site
link-checker check https://docs.influxdata.com/influxdb3/core/admin/scale-cluster/
# Relative link /influxdb3/clustered/tags/kubernetes/ becomes:
# → https://docs.influxdata.com/influxdb3/clustered/tags/kubernetes/
```
**Why This Matters**
- **Testing new content**: Tag pages generated locally will be found when testing local files
- **Production validation**: Production URLs validate against the live site
- **No false positives**: New content won't appear broken when testing locally before deployment
### Content Mapping Workflows
#### Scenario 1: Map and check InfluxDB 3 Core content
```bash
# Map Markdown files to HTML
link-checker map content/influxdb3/core/get-started/
# Check links in mapped HTML files
link-checker check public/influxdb3/core/get-started/
```
#### Scenario 2: Map and check shared CLI content
```bash
# Map shared content files
link-checker map content/shared/influxdb3-cli/
# Check the mapped output files
# (link-checker map outputs the HTML file paths)
link-checker map content/shared/influxdb3-cli/ | \
xargs link-checker check
```
#### Scenario 3: Direct HTML checking
```bash
# Check HTML files directly without mapping
link-checker check public/influxdb3/core/get-started/
```
#### Combined workflow for changed files
```bash
# Check only files changed in the last commit
git diff --name-only HEAD~1 HEAD | grep '\.md$' | \
xargs link-checker map | \
xargs link-checker check
```
### Configuration Options
#### Local usage (default configuration)
```bash
# Uses default settings or test.lycherc.toml if present
link-checker check public/influxdb3/core/get-started/
```
#### Production usage (GitHub Actions)
```bash
# Use production configuration with comprehensive exclusions
link-checker check \
--config .ci/link-checker/production.lycherc.toml \
public/influxdb3/core/get-started/
```
### GitHub Actions Integration
#### Composite Action
**Automated Integration (docs-v2)**
The `.github/actions/validate-links/` composite action provides reusable link validation:
The docs-v2 repository includes automated link checking for pull requests:
- **Trigger**: Runs automatically on PRs that modify content files
- **Binary distribution**: Downloads latest pre-built binary from docs-v2 releases
- **Smart detection**: Only checks files affected by PR changes
- **Production config**: Uses optimized settings with exclusions for GitHub, social media, etc.
- **Results reporting**: Broken links reported as GitHub annotations with detailed summaries
The workflow automatically:
1. Detects content changes in PRs using GitHub Files API
2. Downloads latest link-checker binary from docs-v2 releases
3. Builds Hugo site and maps changed content to public HTML files
4. Runs link checking with production configuration
5. Reports results with annotations and step summaries
**Manual Integration (other repositories)**
For other repositories, you can integrate link checking manually:
```yaml
- uses: ./.github/actions/validate-links
with:
files: "content/influxdb3/core/file.md content/influxdb/v2/file2.md"
product-name: "core"
cache-enabled: "true"
cache-key: "link-validation"
name: Link Check
on:
pull_request:
paths:
- 'content/**/*.md'
jobs:
link-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download link-checker
run: |
curl -L -o link-checker \
https://github.com/influxdata/docs-tooling/releases/latest/download/link-checker-linux-x86_64
chmod +x link-checker
cp target/release/link-checker ../../link-checker
cd ../..
- name: Build Hugo site
run: |
npm install
npx hugo --minify
- name: Check changed files
run: |
git diff --name-only origin/main HEAD | \
grep '\.md$' | \
xargs ./link-checker map | \
xargs ./link-checker check \
--config .ci/link-checker/production.lycherc.toml
```
#### Matrix Generator
The `.github/scripts/matrix-generator.js` script provides intelligent strategy selection:
- **Sequential validation**: For small changes (< 10 files) or single-product changes
- **Parallel validation**: For large changes across multiple products (up to 5 concurrent jobs)
Test locally:
```bash
node .github/scripts/matrix-generator.js content/influxdb3/core/file1.md content/influxdb/v2/file2.md
```
Configuration options:
- `--max-concurrent <n>`: Maximum parallel jobs (default: 5)
- `--force-sequential`: Force sequential execution
- `--min-files-parallel <n>`: Minimum files for parallel (default: 10)
### Caching for Link Validation
Link validation supports caching to improve performance:
- **Cache location**: `.cache/link-validation/` (local), GitHub Actions cache (CI)
- **Cache keys**: Based on content file hashes
- **TTL**: 30 days by default, configurable
#### Cache Configuration Options
```bash
# Use 7-day cache for more frequent validation
yarn test:links --cache-ttl=7 content/influxdb3/**/*.md
# Use 1-day cache via environment variable
LINK_CACHE_TTL_DAYS=1 yarn test:links content/**/*.md
# Clean up expired cache entries
node .github/scripts/incremental-validator.js --cleanup
```
#### How Caching Works
- **Cache key**: Based on file path + content hash (file changes invalidate cache immediately)
- **External links**: Cached for the TTL period since URLs rarely change
- **Internal links**: Effectively cached until file content changes
- **Automatic cleanup**: Expired entries are removed on access and via `--cleanup`
## Style Linting (Vale)
Style linting uses [Vale](https://vale.sh/) to enforce documentation writing standards, branding guidelines, and vocabulary consistency.

250
api-docs/influxdb3/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml
View File

@ -66,7 +66,22 @@ paths:
schema:
type: string
required: true
description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy.
description: |
The database to write to.
**Database targeting:** In Cloud Dedicated, databases can be named using the `database_name/retention_policy_name` convention for InfluxQL compatibility. Cloud Dedicated does not use DBRP mappings. The db and rp parameters are used to construct the target database name following this naming convention.
**Auto-creation behavior:** Cloud Dedicated requires databases to be created before writing data. The v1 `/write` API does not automatically create databases. If the specified
database does not exist, the write request will fail.
Authentication: Requires a valid API token with _write_ permissions for the target database.
### Related
- [Write data to InfluxDB Cloud Dedicated](/influxdb3/cloud-dedicated/write-data/)
- [Manage databases in InfluxDB Cloud Dedicated](/influxdb3/cloud-dedicated/admin/databases/)
- [InfluxQL DBRP naming convention](/influxdb3/cloud-dedicated/admin/databases/create/#influxql-dbrp-naming-convention)
- [InfluxQL data retention policy mapping differences](/influxdb3/cloud-serverless/guides/prototype-evaluation/#influxql-data-retention-policy-mapping-differences)
- in: query
name: rp
schema:
@ -137,6 +152,160 @@ paths:
schema:
$ref: '#/components/schemas/Error'
/query:
get:
operationId: GetQueryV1
tags:
- Query
summary: Query using the InfluxDB v1 HTTP API
parameters:
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
- $ref: '#/components/parameters/AuthPassV1'
- in: header
name: Accept
schema:
type: string
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
default: application/json
enum:
- application/json
- application/csv
- text/csv
- application/x-msgpack
- in: header
name: Accept-Encoding
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
schema:
type: string
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
- in: query
name: chunked
description: |
If true, the response is divided into chunks of size `chunk_size`.
schema:
type: boolean
default: false
- in: query
name: chunk_size
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
schema:
type: integer
default: 10000
- in: query
name: db
schema:
type: string
required: true
description: The database to query from.
- in: query
name: pretty
description: |
If true, the JSON response is formatted in a human-readable format.
schema:
type: boolean
default: false
- in: query
name: q
description: Defines the InfluxQL query to run.
required: true
schema:
type: string
- in: query
name: rp
schema:
type: string
description: |
The retention policy name for InfluxQL compatibility
Optional parameter that, when combined with the db parameter, forms the complete database name to query. In InfluxDB Cloud Dedicated, databases can be named using the
database_name/retention_policy_name convention for InfluxQL compatibility.
When a request specifies both `db` and `rp`, Cloud Dedicated combines them as `db/rp` to target the database--for example:
- If `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`
- If only `db=mydb` is provided (no `rp`), the query targets the database named `mydb`
Unlike InfluxDB v1 and Cloud Serverless, Cloud Dedicated does not use DBRP mappings or separate retention policy objects. This parameter exists solely for v1 API
compatibility and database naming conventions.
_Note: The retention policy name does not control data retention in Cloud Dedicated. Data retention is determined by the database's **retention period** setting._
### Related
- [InfluxQL DBRP naming convention](/influxdb3/cloud-dedicated/admin/databases/create/#influxql-dbrp-naming-convention)
- [InfluxQL data retention policy mapping differences](/influxdb3/cloud-serverless/guides/prototype-evaluation/#influxql-data-retention-policy-mapping-differences)
- name: epoch
description: |
Formats timestamps as unix (epoch) timestamps with the specified precision
instead of RFC3339 timestamps with nanosecond precision.
in: query
schema:
type: string
enum:
- h
- m
- s
- ms
- u
- µ
- ns
responses:
'200':
description: Query results
headers:
Content-Encoding:
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
schema:
type: string
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
Trace-Id:
description: The Trace-Id header reports the request's trace ID, if one was generated.
schema:
type: string
description: Specifies the request's trace ID.
content:
application/csv:
schema:
$ref: '#/components/schemas/InfluxQLCSVResponse'
text/csv:
schema:
$ref: '#/components/schemas/InfluxQLCSVResponse'
application/json:
schema:
$ref: '#/components/schemas/InfluxQLResponse'
examples:
influxql-chunk_size_2:
value: |
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
application/x-msgpack:
schema:
type: string
format: binary
'429':
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
headers:
Retry-After:
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
schema:
type: integer
format: int32
default:
description: Error processing query
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: PostQueryV1
tags:
@ -148,6 +317,83 @@ paths:
text/plain:
schema:
type: string
application/json:
schema:
type: object
properties:
db:
type: string
description: |
The database name for InfluxQL queries.
Required parameter that specifies the database to query.
In InfluxDB Cloud Dedicated, this can be either:
- A simple database name (for example, `mydb`)
- The database portion of a `database_name/retention_policy_name` naming convention (used together with the `rp` parameter)
When used alone, `db` specifies the complete database name to query. When used with the `rp` parameter, they combine to form the full database name as `db/rp`--for example, if `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`.
Unlike InfluxDB Cloud Serverless, Cloud Dedicated does not use DBRP mappings. The database name directly corresponds to an existing database in your Cloud Dedicated cluster.
Examples:
- `db=mydb` - queries the database named `mydb`
- `db=mydb` with `rp=autogen` - queries the database named `mydb/autogen`
_Note: The specified database must exist in your Cloud Dedicated cluster. Queries will fail if the database does not exist._
### Related
- [InfluxQL DBRP naming convention](/influxdb3/cloud-dedicated/admin/databases/create/#influxql-dbrp-naming-convention)
- [Migrate data from InfluxDB 1.x to Cloud Dedicated](/influxdb3/cloud-dedicated/guides/migrate-data/migrate-1x-to-cloud-dedicated/)
- [InfluxQL data retention policy mapping differences between InfluxDB Cloud Dedicated and Cloud Serverless](/influxdb3/cloud-serverless/guides/prototype-evaluation/#influxql-data-retention-policy-mapping-differences)
rp:
description: |
The retention policy name for InfluxQL compatibility
Optional parameter that, when combined with the db parameter, forms the complete database name to query. In InfluxDB Cloud Dedicated, databases can be named using the
database_name/retention_policy_name convention for InfluxQL compatibility.
When a request specifies both `db` and `rp`, Cloud Dedicated combines them as `db/rp` to target the database--for example:
- If `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`
- If only `db=mydb` is provided (no `rp`), the query targets the database named `mydb`
Unlike InfluxDB v1 and Cloud Serverless, Cloud Dedicated does not use DBRP mappings or separate retention policy objects. This parameter exists solely for v1 API
compatibility and database naming conventions.
_Note: The retention policy name does not control data retention in Cloud Dedicated. Data retention is determined by the database's **retention period** setting._
### Related
- [InfluxQL DBRP naming convention](/influxdb3/cloud-dedicated/admin/databases/create/#influxql-dbrp-naming-convention)
- [Migrate data from InfluxDB 1.x to Cloud Dedicated](/influxdb3/cloud-dedicated/guides/migrate-data/migrate-1x-to-cloud-dedicated/)
- [InfluxQL data retention policy mapping differences](/influxdb3/cloud-serverless/guides/prototype-evaluation/#influxql-data-retention-policy-mapping-differences)
type: string
q:
description: Defines the InfluxQL query to run.
type: string
chunked:
description: |
If true, the response is divided into chunks of size `chunk_size`.
type: boolean
chunk_size:
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
type: integer
default: 10000
epoch:
description: |
A unix timestamp precision.
type: string
enum:
- h
- m
- s
- ms
- u
- µ
- ns
parameters:
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
@ -184,7 +430,7 @@ paths:
schema:
type: string
required: true
description: Bucket to query.
description: Database to query.
- in: query
name: rp
schema:

265
api-docs/influxdb3/cloud-serverless/v1-compatibility/swaggerV1Compat.yml
View File

@ -65,7 +65,7 @@ paths:
schema:
type: string
required: true
description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy.
description: Database to write to. If none exists, InfluxDB creates a database with a default 3-day retention policy.
- in: query
name: rp
schema:
@ -136,6 +136,188 @@ paths:
schema:
$ref: '#/components/schemas/Error'
/query:
get:
operationId: GetQueryV1
tags:
- Query
summary: Query using the InfluxDB v1 HTTP API
parameters:
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
- $ref: '#/components/parameters/AuthPassV1'
- in: header
name: Accept
schema:
type: string
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
default: application/json
enum:
- application/json
- application/csv
- text/csv
- application/x-msgpack
- in: header
name: Accept-Encoding
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
schema:
type: string
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
- in: query
name: chunked
description: |
If true, the response is divided into chunks of size `chunk_size`.
schema:
type: boolean
default: false
- in: query
name: chunk_size
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
schema:
type: integer
default: 10000
- in: query
name: db
schema:
type: string
required: true
description: |
The database name for InfluxQL queries
Required parameter that specifies the database to query via DBRP (Database Retention Policy) mapping. In Cloud Serverless, this parameter is used together with DBRP
mappings to identify which bucket to query.
The `db` parameter (optionally combined with `rp`) must have an existing DBRP mapping that points to a bucket. Without a valid DBRP mapping, queries will fail with an
authorization error.
**DBRP mapping requirements:**
- A DBRP mapping must exist before querying
- Mappings can be created automatically when writing data with the v1 API (if your token has permissions)
- Mappings can be created manually using the InfluxDB CLI or API
### Examples
- `db=mydb` - uses the default DBRP mapping for `mydb`
- `db=mydb` with `rp=weekly` - uses the DBRP mapping for `mydb/weekly`
_Note: Unlike the v1 `/write` endpoint which can auto-create buckets and mappings, the `/query` endpoint requires pre-existing DBRP mappings. The actual data is stored in and
queried from the bucket that the DBRP mapping points to._
### Related
- [Use the InfluxDB v1 query API and InfluxQL in Cloud Serverless](/influxdb3/cloud-serverless/query-data/execute-queries/v1-http/)
- [Map v1 databases and retention policies to buckets in Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
- [Migrate from InfluxDB 1.x to Cloud Serverless](/influxdb3/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless/)
- in: query
name: pretty
description: |
If true, the JSON response is formatted in a human-readable format.
schema:
type: boolean
default: false
- in: query
name: q
description: Defines the InfluxQL query to run.
required: true
schema:
type: string
- in: query
name: rp
schema:
type: string
description: |
The retention policy name for InfluxQL queries
Optional parameter that specifies the retention policy to use when querying data with InfluxQL. In Cloud Serverless, this parameter works with DBRP (Database Retention
Policy) mappings to identify the target bucket.
When provided together with the `db` parameter, Cloud Serverless uses the DBRP mapping to determine which bucket to query. The combination of `db` and `rp` must have an
existing DBRP mapping that points to a bucket. If no `rp` is specified, Cloud Serverless uses the default retention policy mapping for the database.
Requirements: A DBRP mapping must exist for the db/rp combination before you can query data. DBRP mappings can be created:
- Automatically when writing data with the v1 API (if your token has sufficient permissions)
- Manually using the InfluxDB CLI or API
Example: If `db=mydb` and `rp=weekly`, the query uses the DBRP mapping for `mydb/weekly` to determine which bucket to query.
_Note: The retention policy name is used only for DBRP mapping. Actual data retention is controlled by the target bucket's retention period setting, not by the retention
policy name._
### Related
- [Use the InfluxDB v1 query API and InfluxQL in Cloud Serverless](/influxdb3/cloud-serverless/query-data/execute-queries/v1-http/)
- [Map v1 databases and retention policies to buckets in Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
- [Migrate from InfluxDB 1.x to Cloud Serverless](/influxdb3/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless/)
- name: epoch
description: |
Formats timestamps as unix (epoch) timestamps with the specified precision
instead of RFC3339 timestamps with nanosecond precision.
in: query
schema:
type: string
enum:
- h
- m
- s
- ms
- u
- µ
- ns
responses:
'200':
description: Query results
headers:
Content-Encoding:
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
schema:
type: string
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
Trace-Id:
description: The Trace-Id header reports the request's trace ID, if one was generated.
schema:
type: string
description: Specifies the request's trace ID.
content:
application/csv:
schema:
$ref: '#/components/schemas/InfluxQLCSVResponse'
text/csv:
schema:
$ref: '#/components/schemas/InfluxQLCSVResponse'
application/json:
schema:
$ref: '#/components/schemas/InfluxQLResponse'
examples:
influxql-chunk_size_2:
value: |
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
application/x-msgpack:
schema:
type: string
format: binary
'429':
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
headers:
Retry-After:
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
schema:
type: integer
format: int32
default:
description: Error processing query
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: PostQueryV1
tags:
@ -147,6 +329,87 @@ paths:
text/plain:
schema:
type: string
application/json:
schema:
type: object
properties:
db:
type: string
description: |
The database name for InfluxQL queries
Required parameter that specifies the database to query via DBRP (Database Retention Policy) mapping. In Cloud Serverless, this parameter is used together with DBRP
mappings to identify which bucket to query.
The `db` parameter (optionally combined with `rp`) must have an existing DBRP mapping that points to a bucket. Without a valid DBRP mapping, queries will fail with an
authorization error.
**DBRP mapping requirements:**
- A DBRP mapping must exist before querying
- Mappings can be created automatically when writing data with the v1 API (if your token has permissions)
- Mappings can be created manually using the InfluxDB CLI or API
### Examples
- `db=mydb` - uses the default DBRP mapping for `mydb`
- `db=mydb` with `rp=weekly` - uses the DBRP mapping for `mydb/weekly`
_Note: Unlike the v1 `/write` endpoint which can auto-create buckets and mappings, the `/query` endpoint requires pre-existing DBRP mappings. The actual data is stored in and
queried from the bucket that the DBRP mapping points to._
### Related
- [Execute InfluxQL queries using the v1 API](/influxdb3/cloud-serverless/query-data/execute-queries/influxql/api/v1-http/)
- [Map v1 databases and retention policies to buckets in Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
- [Manage DBRP mappings in Cloud Serverless](/influxdb3/cloud-serverless/admin/dbrp/)
rp:
description: |
The retention policy name for InfluxQL queries
Optional parameter that specifies the retention policy to use when querying data with InfluxQL. In Cloud Serverless, this parameter works with DBRP (Database Retention
Policy) mappings to identify the target bucket.
When provided together with the `db` parameter, Cloud Serverless uses the DBRP mapping to determine which bucket to query. The combination of `db` and `rp` must have an
existing DBRP mapping that points to a bucket. If no `rp` is specified, Cloud Serverless uses the default retention policy mapping for the database.
Requirements: A DBRP mapping must exist for the db/rp combination before you can query data. DBRP mappings can be created:
- Automatically when writing data with the v1 API (if your token has sufficient permissions)
- Manually using the InfluxDB CLI or API
Example: If `db=mydb` and `rp=weekly`, the query uses the DBRP mapping for `mydb/weekly` to determine which bucket to query.
_Note: The retention policy name is used only for DBRP mapping. Actual data retention is controlled by the target bucket's retention period setting, not by the retention policy name._
### Related
- [Execute InfluxQL queries using the v1 API](/influxdb3/cloud-serverless/query-data/execute-queries/influxql/api/v1-http/)
- [Map v1 databases and retention policies to buckets in Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
- [Manage DBRP mappings in Cloud Serverless](/influxdb3/cloud-serverless/admin/dbrp/)
type: string
q:
description: Defines the InfluxQL query to run.
type: string
chunked:
description: |
If true, the response is divided into chunks of size `chunk_size`.
type: boolean
chunk_size:
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
type: integer
default: 10000
epoch:
description: |
A unix timestamp precision.
type: string
enum:
- h
- m
- s
- ms
- u
- µ
- ns
parameters:
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'

211
api-docs/influxdb3/clustered/v1-compatibility/swaggerV1Compat.yml
View File

@ -65,7 +65,23 @@ paths:
schema:
type: string
required: true
description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy.
description: |
The database to write to.
**Database targeting:** In InfluxDB Clustered, databases can be named using the `database_name/retention_policy_name` convention for InfluxQL compatibility. InfluxDB Clustered does not use DBRP mappings. The db and rp parameters are used to construct the target database name following this naming convention.
**Auto-creation behavior:** InfluxDB Clustered requires databases to be created before writing data. The v1 `/write` API does not automatically create databases. If the specified
database does not exist, the write request will fail.
Authentication: Requires a valid API token with _write_ permissions for the target database.
### Related
- [Write data to InfluxDB Clustered](/influxdb3/clustered/write-data/)
- [Use the InfluxDB v1 API with InfluxDB Clustered](/influxdb3/clustered/guides/api-compatibility/v1/)
- [Manage databases in InfluxDB Clustered](/influxdb3/clustered/admin/databases/)
- [InfluxQL DBRP naming convention in InfluxDB Clustered](/influxdb3/clustered/admin/databases/create/#influxql-dbrp-naming-convention)
- [Migrate data from InfluxDB v1 to InfluxDB Clustered](/influxdb3/clustered/guides/migrate-data/migrate-1x-to-clustered/)
- in: query
name: rp
schema:
@ -136,6 +152,141 @@ paths:
schema:
$ref: '#/components/schemas/Error'
/query:
get:
operationId: GetQueryV1
tags:
- Query
summary: Query using the InfluxDB v1 HTTP API
parameters:
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
- $ref: '#/components/parameters/AuthPassV1'
- in: header
name: Accept
schema:
type: string
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
default: application/json
enum:
- application/json
- application/csv
- text/csv
- application/x-msgpack
- in: header
name: Accept-Encoding
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
schema:
type: string
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
- in: query
name: chunked
description: |
If true, the response is divided into chunks of size `chunk_size`.
schema:
type: boolean
default: false
- in: query
name: chunk_size
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
schema:
type: integer
default: 10000
- in: query
name: db
schema:
type: string
required: true
description: The database to query from.
- in: query
name: pretty
description: |
If true, the JSON response is formatted in a human-readable format.
schema:
type: boolean
default: false
- in: query
name: q
description: Defines the InfluxQL query to run.
required: true
schema:
type: string
- in: query
name: rp
schema:
type: string
description: Retention policy name.
- name: epoch
description: |
Formats timestamps as unix (epoch) timestamps with the specified precision
instead of RFC3339 timestamps with nanosecond precision.
in: query
schema:
type: string
enum:
- h
- m
- s
- ms
- u
- µ
- ns
responses:
'200':
description: Query results
headers:
Content-Encoding:
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
schema:
type: string
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
Trace-Id:
description: The Trace-Id header reports the request's trace ID, if one was generated.
schema:
type: string
description: Specifies the request's trace ID.
content:
application/csv:
schema:
$ref: '#/components/schemas/InfluxQLCSVResponse'
text/csv:
schema:
$ref: '#/components/schemas/InfluxQLCSVResponse'
application/json:
schema:
$ref: '#/components/schemas/InfluxQLResponse'
examples:
influxql-chunk_size_2:
value: |
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
application/x-msgpack:
schema:
type: string
format: binary
'429':
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
headers:
Retry-After:
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
schema:
type: integer
format: int32
default:
description: Error processing query
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: PostQueryV1
tags:
@ -147,6 +298,64 @@ paths:
text/plain:
schema:
type: string
application/json:
schema:
type: object
properties:
db:
type: string
description: Database to query.
rp:
description: |
The retention policy name for InfluxQL compatibility
Optional parameter that, when combined with the db parameter, forms the complete database name to query. In InfluxDB Clustered, databases can be named using the
database_name/retention_policy_name convention for InfluxQL compatibility.
When a request specifies both `db` and `rp`, InfluxDB Clustered combines them as `db/rp` to target the database--for example:
- If `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`
- If only `db=mydb` is provided (no `rp`), the query targets the database named `mydb`
Unlike InfluxDB v1 and Cloud Serverless, InfluxDB Clustered does not use DBRP mappings or separate retention policy objects. This parameter exists solely for v1 API
compatibility and database naming conventions.
Note: The retention policy name does not control data retention in InfluxDB Clustered. Data retention is determined by the database's _retention period_ setting.
### Related
- [Use the v1 query API and InfluxQL to query data in InfluxDB Clustered](/influxdb3/clustered/query-data/execute-queries/influxdb-v1-api/)
- [Use the InfluxDB v1 API with InfluxDB Clustered](/influxdb3/clustered/guides/api-compatibility/v1/)
- [Manage databases in InfluxDB Clustered](/influxdb3/clustered/admin/databases/)
- [InfluxQL DBRP naming convention in InfluxDB Clustered](/influxdb3/clustered/admin/databases/create/#influxql-dbrp-naming-convention)
- [Migrate data from InfluxDB v1 to InfluxDB Clustered](/influxdb3/clustered/guides/migrate-data/migrate-1x-to-clustered/)
type: string
q:
description: |
Defines the InfluxQL query to run.
type: string
chunked:
description: |
If true, the response is divided into chunks of size `chunk_size`.
type: boolean
chunk_size:
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
type: integer
default: 10000
epoch:
description: |
A unix timestamp precision.
type: string
enum:
- h
- m
- s
- ms
- u
- µ
- ns
parameters:
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'

18
api-docs/template.hbs
View File

@ -31,6 +31,9 @@
padding: 0;
margin: 0;
}
#kapa-widget-container {
font-family: 'Proxima Nova', sans-serif;
}
</style>
{{#unless disableGoogleFont}}<link
href="https://fonts.googleapis.com/css?family=Roboto+Mono:500,500i,700,700i|Roboto:400,400i,700,700i|Rubik:400,400i,500,500i,700,700i"
@ -41,6 +44,7 @@
<script>
// Load Kapa AI widget after DOM content is loaded
document.addEventListener('DOMContentLoaded', function() {
const fontFamily = 'Proxima Nova, sans-serif';
const askAI = document.createElement('script');
askAI.type = 'text/javascript';
askAI.async = true;
@ -53,8 +57,8 @@
askAI.setAttribute('data-project-logo', '/img/influx-logo-cubo-white.png');
askAI.setAttribute('data-modal-disclaimer', 'This AI can access [documentation for InfluxDB, clients, and related tools](https://docs.influxdata.com). Information you submit is used in accordance with our [Privacy Policy](https://www.influxdata.com/legal/privacy-policy/).');
askAI.setAttribute('data-modal-example-questions', 'How do I write and query data with the {{title}}?, How do I use client libraries for the {{title}}?');
askAI.setAttribute('data-button-height', '65px');
askAI.setAttribute('data-button-width', '65px');
askAI.setAttribute('data-button-height', '50px');
askAI.setAttribute('data-button-width', '50px');
if (window.matchMedia('(max-width: 800px)').matches) {
// For mobile devices (smaller than 600px)
askAI.setAttribute('data-button-position-bottom', '130px');
@ -62,25 +66,23 @@
// For larger screens
askAI.setAttribute('data-button-position-bottom', '20px');
}
askAI.setAttribute('data-button-text-font-family', fontFamily);
askAI.setAttribute('data-button-text-font-size', '12.8px');
askAI.setAttribute('data-button-text', 'Ask AI');
askAI.setAttribute('data-conversation-button-icons-only', 'true');
askAI.setAttribute('data-font-family', 'Proxima Nova, sans-serif');
askAI.setAttribute('data-font-family', fontFamily);
askAI.setAttribute('data-modal-example-questions-col-span', '8');
askAI.setAttribute('data-modal-full-screen-on-mobile', 'true');
askAI.setAttribute('data-modal-header-bg-color', '#d30971');
askAI.setAttribute('data-modal-header-border-bottom', 'none');
askAI.setAttribute('data-modal-header-padding', '.5rem');
askAI.setAttribute('data-modal-header-text-color', '#ffffff');
askAI.setAttribute('data-modal-x-offset', '0');
askAI.setAttribute('data-modal-size', '640px');
askAI.setAttribute('data-modal-y-offset', '0');
askAI.setAttribute('data-modal-with-overlay', 'false');
askAI.setAttribute('data-modal-inner-flex-direction', 'column');
askAI.setAttribute('data-modal-inner-justify-content', 'end');
askAI.setAttribute('data-modal-inner-max-width', '600px');
askAI.setAttribute('data-modal-inner-position-left', 'auto');
askAI.setAttribute('data-modal-inner-position-right', '50px');
askAI.setAttribute('data-modal-inner-position-bottom', 'calc(2.5rem + 25px)');
askAI.setAttribute('data-modal-size', '640px');
askAI.setAttribute('data-modal-title-color', '#fff');
askAI.setAttribute('data-modal-title-font-size', '1.25rem');
askAI.setAttribute('data-modal-lock-scroll', 'false');

2
assets/js/ask-ai.js
View File

@ -45,8 +45,6 @@ function initializeChat({ onChatLoad, chatAttributes }) {
modalOverrideOpenClassAskAi: 'ask-ai-open',
modalSize: '640px',
modalWithOverlay: 'false',
modalInnerMaxWidth: '800px',
modalXOffset: 'calc(100% - 800px - .5rem)',
modalYOffset: '10vh',
userAnalyticsFingerprintEnabled: 'true',
fontFamily: 'Proxima Nova, sans-serif',

86
assets/js/custom-timestamps.js
View File

@ -43,7 +43,7 @@ function getStartDate() {
////////////////////////////////////////////////////////////////////////////////
// If the user has not set the startDate cookie, default the startDate to yesterday
// If the user has not set the startDate cookie, default startDate to yesterday
var startDate = getStartDate() || yesterday();
// Convert a time value to a Unix timestamp (seconds)
@ -109,6 +109,49 @@ const defaultTimes = [
}, // 1641067200
];
// Helper function to update text while preserving code placeholder elements
function updateTextNode(node, times) {
if (node.nodeType === Node.TEXT_NODE) {
let text = node.textContent;
times.forEach(function (x) {
const oldDatePart = datePart(x.rfc3339.replace(/T.*$/, ''));
const newDatePart = datePart(x.rfc3339_new.replace(/T.*$/, ''));
const rfc3339Regex = new RegExp(
`${oldDatePart.year}(.*?)${oldDatePart.month}(.*?)${oldDatePart.day}`,
'g'
);
const rfc3339Repl = `${newDatePart.year}$1${newDatePart.month}$2${newDatePart.day}`;
text = text
.replaceAll(x.unix, x.unix_new)
.replace(rfc3339Regex, rfc3339Repl);
});
node.textContent = text;
}
}
// Recursively update timestamps in DOM while preserving structure
function updateTimestampsInElement(element, times) {
// Skip code placeholder elements to preserve their functionality
if (element.classList && element.classList.contains('code-placeholder')) {
return;
}
// Skip elements with data-component attribute (preserves all components)
if (element.hasAttribute && element.hasAttribute('data-component')) {
return;
}
const childNodes = Array.from(element.childNodes);
childNodes.forEach((child) => {
if (child.nodeType === Node.TEXT_NODE) {
updateTextNode(child, times);
} else if (child.nodeType === Node.ELEMENT_NODE) {
updateTimestampsInElement(child, times);
}
});
}
function updateTimestamps(newStartDate, seedTimes = defaultTimes) {
// Update the times array with replacement times
const times = seedTimes.map((x) => {
@ -129,40 +172,14 @@ function updateTimestamps(newStartDate, seedTimes = defaultTimes) {
'.custom-timestamps table',
];
// Update block elements while preserving DOM structure
$(updateBlockElWhitelist.join()).each(function () {
var wrapper = $(this)[0];
times.forEach(function (x) {
const oldDatePart = datePart(x.rfc3339.replace(/T.*$/, ''));
const newDatePart = datePart(x.rfc3339_new.replace(/T.*$/, ''));
const rfc3339Regex = new RegExp(
`${oldDatePart.year}(.*?)${oldDatePart.month}(.*?)${oldDatePart.day}`,
'g'
);
const rfc3339Repl = `${newDatePart.year}$1${newDatePart.month}$2${newDatePart.day}`;
wrapper.innerHTML = wrapper.innerHTML
.replaceAll(x.unix, x.unix_new)
.replaceAll(rfc3339Regex, rfc3339Repl);
});
updateTimestampsInElement(this, times);
});
// Update span elements
$('span.custom-timestamps').each(function () {
var wrapper = $(this)[0];
times.forEach(function (x) {
const oldDatePart = datePart(x.rfc3339.replace(/T.*$/, ''));
const newDatePart = datePart(x.rfc3339_new.replace(/T.*$/, ''));
const rfc3339Regex = new RegExp(
`${oldDatePart.year}-${oldDatePart.month}-${oldDatePart.day}`,
'g'
);
const rfc3339Repl = `${newDatePart.year}-${newDatePart.month}-${newDatePart.day}`;
wrapper.innerHTML = wrapper.innerHTML
.replaceAll(x.unix, x.unix_new)
.replaceAll(rfc3339Regex, rfc3339Repl);
});
updateTimestampsInElement(this, times);
});
// Create a new seed times array with new start time for next change
@ -196,10 +213,11 @@ function CustomTimeTrigger({ component }) {
prevArrow: '<',
});
//////////////////////////////////// ACTIONS ///////////////////////////////////
/////////////////////////////////// ACTIONS //////////////////////////////////
// Initial update to yesterdays date ON PAGE LOAD
// Conditionally set the start date cookie it startDate is equal to the default value
// Initial update to yesterday's date ON PAGE LOAD
// Conditionally set the start date cookie if startDate is equal to the
// default value
let updatedTimes = updateTimestamps(startDate, defaultTimes);
if (startDate === yesterday()) {

1
assets/js/theme.js
View File

@ -6,6 +6,7 @@ const PROPS = {
style_domain: 'docs.influxdata.com',
};
// Get the user's theme preference
function getPreferredTheme() {
return `${getPreference(PROPS.style_preference_name)}-theme`;
}

19
compose.yaml
View File

@ -307,6 +307,7 @@ services:
influxdb3-core:
container_name: influxdb3-core
image: influxdb:3-core
pull_policy: always
# Set variables (except your auth token) for Core in the .env.3core file.
env_file:
- .env.3core
@ -316,17 +317,21 @@ services:
- influxdb3
- serve
- --node-id=node0
- --log-filter=debug
- --object-store=file
- --data-dir=/var/lib/influxdb3/data
- --plugin-dir=/var/lib/influxdb3/plugins
- --log-filter=debug
- --verbose
volumes:
- type: bind
source: test/.influxdb3/core/data
target: /var/lib/influxdb3/data
- type: bind
source: test/.influxdb3/core/plugins
source: test/.influxdb3/plugins/influxdata
target: /var/lib/influxdb3/plugins
- type: bind
source: test/.influxdb3/core/plugins
target: /var/lib/influxdb3/plugins/custom
environment:
- INFLUXDB3_AUTH_TOKEN=/run/secrets/influxdb3-core-admin-token
secrets:
@ -334,6 +339,7 @@ services:
influxdb3-enterprise:
container_name: influxdb3-enterprise
image: influxdb:3-enterprise
pull_policy: always
# Set license email and other variables (except your auth token) for Enterprise in the .env.3ent file.
env_file:
- .env.3ent
@ -344,20 +350,23 @@ services:
- serve
- --node-id=node0
- --cluster-id=cluster0
- --log-filter=debug
- --object-store=file
- --data-dir=/var/lib/influxdb3/data
- --plugin-dir=/var/lib/influxdb3/plugins
- --log-filter=debug
- --verbose
environment:
- INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=${INFLUXDB3_ENTERPRISE_LICENSE_EMAIL}
- INFLUXDB3_AUTH_TOKEN=/run/secrets/influxdb3-enterprise-admin-token
volumes:
- type: bind
source: test/.influxdb3/enterprise/data
target: /var/lib/influxdb3/data
- type: bind
source: test/.influxdb3/enterprise/plugins
source: test/.influxdb3/plugins/influxdata
target: /var/lib/influxdb3/plugins
- type: bind
source: test/.influxdb3/enterprise/plugins
target: /var/lib/influxdb3/plugins/custom
secrets:
- influxdb3-enterprise-admin-token
telegraf-pytest:

2
content/chronograf/v1/_index.md
View File

@ -6,7 +6,7 @@ description: >
monitoring data and easily create alerting and automation rules.
menu:
chronograf_v1:
name: Chronograf v1.10
name: Chronograf
weight: 1
---

6
content/chronograf/v1/about_the_project/release-notes.md
View File

@ -10,6 +10,12 @@ aliases:
- /chronograf/v1/about_the_project/release-notes-changelog/
---
## v1.10.8 {date="2025-08-15"}
### Bug Fixes
- Fix missing retention policies on the Databases page.
## v1.10.7 {date="2025-04-15"}
### Bug Fixes

33
content/enterprise_influxdb/v1/about-the-project/release-notes.md
View File

@ -1,5 +1,5 @@
---
title: InfluxDB Enterprise 1.11 release notes
title: InfluxDB Enterprise v1 release notes
description: >
Important changes and what's new in each version InfluxDB Enterprise.
menu:
@ -7,9 +7,16 @@ menu:
name: Release notes
weight: 10
parent: About the project
alt_links:
v1: /influxdb/v1/about_the_project/release-notes/
---
## v1.12.1 {date="2025-06-26"}
## v1.12.x {date="TBD"}
> [!Important]
> #### Pre-release documentation
>
> This release is not yet available. [**v{{% latest-patch %}}**](#v1118) is the latest InfluxDB Enterprise v1 release.
> [!Important]
> #### Upgrade meta nodes first
@ -22,31 +29,53 @@ menu:
- Add additional log output when using
[`influx_inspect buildtsi`](/enterprise_influxdb/v1/tools/influx_inspect/#buildtsi) to
rebuild the TSI index.
<!-- TODO: Uncomment with 1.12.x release:
- Use [`influx_inspect export`](/enterprise_influxdb/v1/tools/influx_inspect/#export) with
[`-tsmfile` option](/enterprise_influxdb/v1/tools/influx_inspect/#--tsmfile-tsm_file-) to
export a single TSM file.
-->
<!-- TODO: Remove with 1.12.x release: -->
- Use [`influx_inspect export`](/enterprise_influxdb/v1/tools/influx_inspect/#export) with
`-tsmfile` option to
export a single TSM file.
- Add `-m` flag to the [`influxd-ctl show-shards` command](/enterprise_influxdb/v1/tools/influxd-ctl/show-shards/)
to output inconsistent shards.
- Allow the specification of a write window for retention policies.
- Add `fluxQueryRespBytes` metric to the `/debug/vars` metrics endpoint.
- Log whenever meta gossip times exceed expiration.
<!-- TODO: Uncomment with 1.12.x release:
- Add [`query-log-path` configuration option](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#query-log-path)
to data nodes.
- Add [`aggressive-points-per-block` configuration option](/influxdb/v1/administration/config/#aggressive-points-per-block)
to prevent TSM files from not getting fully compacted.
-->
<!-- TODO: Remove with 1.12.x release: -->
- Add `query-log-path` configuration option to data nodes.
- Add `aggressive-points-per-block` configuration option to prevent TSM files from not getting fully compacted.
- Log TLS configuration settings on startup.
- Check for TLS certificate and private key permissions.
- Add a warning if the TLS certificate is expired.
- Add authentication to the Raft portal and add the following related _data_
node configuration options:
<!-- Uncomment with 1.12.x release
- [`[meta].raft-portal-auth-required`](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#raft-portal-auth-required)
- [`[meta].raft-dialer-auth-required`](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#raft-dialer-auth-required)
-->
<!-- TODO: Remove with 1.12.x release: -->
- `[meta].raft-portal-auth-required`
- `[meta].raft-dialer-auth-required`
- Improve error handling.
- InfluxQL updates:
- Delete series by retention policy.
<!-- TODO: Uncomment with 1.12.x release:
- Allow retention policies to discard writes that fall within their range, but
outside of [`FUTURE LIMIT`](/enterprise_influxdb/v1/query_language/manage-database/#future-limit)
and [`PAST LIMIT`](/enterprise_influxdb/v1/query_language/manage-database/#past-limit).
-->
<!-- TODO: Remove with 1.12.x release: -->
- Allow retention policies to discard writes that fall within their range, but
outside of `FUTURE LIMIT` and `PAST LIMIT`.
## Bug fixes

4
content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md
View File

@ -326,7 +326,7 @@ Very useful for troubleshooting, but will log any sensitive data contained withi
Environment variable: `INFLUXDB_DATA_QUERY_LOG_ENABLED`
#### query-log-path
#### query-log-path {metadata="v1.12.0+"}
Default is `""`.
@ -352,7 +352,7 @@ The following is an example of a `logrotate` configuration:
```
Environment variable: `INFLUXDB_DATA_QUERY_LOG_PATH`
-->
#### wal-fsync-delay
Default is `"0s"`.

75
content/enterprise_influxdb/v1/administration/manage/clusters/rebalance.md
View File

@ -40,11 +40,20 @@ cluster, and they use the
[`influxd-ctl` tool](/enterprise_influxdb/v1/tools/influxd-ctl/) available on
all meta nodes.
{{% warn %}}
Before you begin, stop writing historical data to InfluxDB.
Historical data have timestamps that occur at anytime in the past.
Performing a rebalance while writing historical data can lead to data loss.
{{% /warn %}}
> [!Warning]
> #### Stop writing data before rebalancing
>
> Before you begin, stop writing historical data to InfluxDB.
> Historical data have timestamps that occur at anytime in the past.
> Performing a rebalance while writing historical data can lead to data loss.
> [!Caution]
> #### Risks of rebalancing with future data
>
> Truncating shards that contain data with future timestamps (such as forecast or prediction data)
> can lead to overlapping shards and data duplication.
> For more information, see [`truncate-shards` and future data](/enterprise_influxdb/v1/tools/influxd-ctl/truncate-shards/#understand-the-risks-with-future-data)
> or [contact InfluxData support](https://support.influxdata.com).
## Rebalance Procedure 1: Rebalance a cluster to create space
@ -61,18 +70,23 @@ data node to expand the total disk capacity of the cluster.
In the next steps, you will safely move shards from one of the two original data
nodes to the new data node.
### Step 1: Truncate Hot Shards
### Step 1: Truncate hot shards
Hot shards are shards that are currently receiving writes.
Hot shards are shards that currently receive writes.
Performing any action on a hot shard can lead to data inconsistency within the
cluster which requires manual intervention from the user.
To prevent data inconsistency, truncate hot shards before moving any shards
> [!Caution]
> #### Risks of rebalancing with future data
>
> Truncating shards that contain data with future timestamps (such as forecast or prediction data)
> can lead to overlapping shards and data duplication.
> For more information, see [`truncate-shards` and future data](/enterprise_influxdb/v1/tools/influxd-ctl/truncate-shards/#understand-the-risks-with-future-data)
> or [contact InfluxData support](https://support.influxdata.com).
To prevent data inconsistency, truncate shards before moving any shards
across data nodes.
The command below creates a new hot shard which is automatically distributed
across all data nodes in the cluster, and the system writes all new points to
that shard.
All previous writes are now stored in cold shards.
The following command truncates all hot shards and creates new shards to write data to:
```
influxd-ctl truncate-shards
@ -84,10 +98,11 @@ The expected output of this command is:
Truncated shards.
```
Once you truncate the shards, you can work on redistributing the cold shards
without the threat of data inconsistency in the cluster.
Any hot or new shards are now evenly distributed across the cluster and require
no further intervention.
New shards are automatically distributed across all data nodes, and InfluxDB writes new points to them.
Previous writes are stored in cold shards.
After truncating shards, you can redistribute cold shards without data inconsistency.
Hot and new shards are evenly distributed and require no further intervention.
### Step 2: Identify Cold Shards
@ -292,18 +307,23 @@ name duration shardGroupDuration replicaN default
autogen 0s 1h0m0s 3 #👍 true
```
### Step 2: Truncate Hot Shards
### Step 2: Truncate hot shards
Hot shards are shards that are currently receiving writes.
Hot shards are shards that currently receive writes.
Performing any action on a hot shard can lead to data inconsistency within the
cluster which requires manual intervention from the user.
To prevent data inconsistency, truncate hot shards before copying any shards
> [!Caution]
> #### Risks of rebalancing with future data
>
> Truncating shards that contain data with future timestamps (such as forecast or prediction data)
> can lead to overlapping shards and data duplication.
> For more information, see [`truncate-shards` and future data](/enterprise_influxdb/v1/tools/influxd-ctl/truncate-shards/#understand-the-risks-with-future-data)
> or [contact InfluxData support](https://support.influxdata.com).
To prevent data inconsistency, truncate shards before copying any shards
to the new data node.
The command below creates a new hot shard which is automatically distributed
across the three data nodes in the cluster, and the system writes all new points
to that shard.
All previous writes are now stored in cold shards.
The following command truncates all hot shards and creates new shards to write data to:
```
influxd-ctl truncate-shards
@ -315,10 +335,11 @@ The expected output of this command is:
Truncated shards.
```
Once you truncate the shards, you can work on distributing the cold shards
without the threat of data inconsistency in the cluster.
Any hot or new shards are now automatically distributed across the cluster and
require no further intervention.
New shards are automatically distributed across all data nodes, and InfluxDB writes new points to them.
Previous writes are stored in cold shards.
After truncating shards, you can redistribute cold shards without data inconsistency.
Hot and new shards are evenly distributed and require no further intervention.
### Step 3: Identify Cold Shards

33
content/enterprise_influxdb/v1/concepts/schema_and_data_layout.md
View File

@ -16,6 +16,7 @@ We recommend the following design guidelines for most use cases:
- [Where to store data (tag or field)](#where-to-store-data-tag-or-field)
- [Avoid too many series](#avoid-too-many-series)
- [Use recommended naming conventions](#use-recommended-naming-conventions)
- [Writing data with future timestamps](#writing-data-with-future-timestamps)
- [Shard Group Duration Management](#shard-group-duration-management)
## Where to store data (tag or field)
@ -209,6 +210,38 @@ from(bucket:"<database>/<retention_policy>")
> SELECT mean("temp") FROM "weather_sensor" WHERE region = 'north'
```
## Writing data with future timestamps
When designing schemas for applications that write data with future timestamps--such as forecast data from machine learning models, predictions, or scheduled events--consider the following implications for InfluxDB Enterprise v1 cluster operations and data integrity.
### Understanding future data behavior
InfluxDB Enterprise v1 creates shards based on time ranges.
When you write data with future timestamps, InfluxDB creates shards that cover future time periods.
> [!Caution]
> #### Risks of rebalancing with future data
>
> Truncating shards that contain data with future timestamps (such as forecast or prediction data)
> can lead to overlapping shards and data duplication.
> For more information, see [`truncate-shards` and future data](/enterprise_influxdb/v1/tools/influxd-ctl/truncate-shards/#understand-the-risks-with-future-data)
> or [contact InfluxData support](https://support.influxdata.com).
### Use separate databases for future data
When planning for data that contains future timestamps, consider isolating it in dedicated databases to:
- Minimize impact on real-time data operations
- Allow targeted maintenance operations on current vs. future data
- Simplify backup and recovery strategies for different data types
```sql
# Example: Separate databases for different data types
CREATE DATABASE "realtime_metrics"
CREATE DATABASE "ml_forecasts"
CREATE DATABASE "scheduled_predictions"
```
## Shard group duration management
### Shard group duration overview

2
content/enterprise_influxdb/v1/features/_index.md
View File

@ -29,7 +29,7 @@ Certain configurations (e.g., 3 meta and 2 data node) provide high-availability
while making certain tradeoffs in query performance when compared to a single node.
Further increasing the number of nodes can improve performance in both respects.
For example, a cluster with 4 data nodes and a [replication factor](https://docs.influxdata.com/enterprise_influxdb/v1/concepts/glossary/#replication-factor)
For example, a cluster with 4 data nodes and a [replication factor](/enterprise_influxdb/v1/concepts/glossary/#replication-factor)
of 2 can support a higher volume of write traffic than a single node could.
It can also support a higher *query* workload, as the data is replicated
in two locations. Performance of the queries may be on par with a single

2
content/enterprise_influxdb/v1/flux/guides/scalar-values.md
View File

@ -217,7 +217,7 @@ The temperature was ${string(v: lastReported._value)}°F."
The following sample data set represents fictional temperature metrics collected
from three locations.
It's formatted in [annotated CSV](https://v2.docs.influxdata.com/v2.0/reference/syntax/annotated-csv/) and imported
It's formatted in [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) and imported
into the Flux query using the [`csv.from()` function](/flux/v0/stdlib/csv/from/).
Place the following at the beginning of your query to use the sample data:

2
content/enterprise_influxdb/v1/guides/hardware_sizing.md
View File

@ -18,7 +18,7 @@ Review configuration and hardware guidelines for InfluxDB Enterprise:
* [Recommended cluster configurations](#recommended-cluster-configurations)
* [Storage: type, amount, and configuration](#storage-type-amount-and-configuration)
For InfluxDB OSS instances, see [OSS hardware sizing guidelines](https://docs.influxdata.com/influxdb/v1/guides/hardware_sizing/).
For InfluxDB OSS instances, see [OSS hardware sizing guidelines](/influxdb/v1/guides/hardware_sizing/).
> **Disclaimer:** Your numbers may vary from recommended guidelines. Guidelines provide estimated benchmarks for implementing the most performant system for your business.

4
content/enterprise_influxdb/v1/query_language/manage-database.md
View File

@ -306,7 +306,7 @@ See
[Shard group duration management](/enterprise_influxdb/v1/concepts/schema_and_data_layout/#shard-group-duration-management)
for recommended configurations.
##### `PAST LIMIT`
##### `PAST LIMIT` {metadata="v1.12.0+"}
The `PAST LIMIT` clause defines a time boundary before and relative to _now_
in which points written to the retention policy are accepted. If a point has a
@ -317,7 +317,7 @@ For example, if a write request tries to write data to a retention policy with a
`PAST LIMIT 6h` and there are points in the request with timestamps older than
6 hours, those points are rejected.
##### `FUTURE LIMIT`
##### `FUTURE LIMIT` {metadata="v1.12.0+"}
The `FUTURE LIMIT` clause defines a time boundary after and relative to _now_
in which points written to the retention policy are accepted. If a point has a

4
content/enterprise_influxdb/v1/tools/influx_inspect.md
View File

@ -453,7 +453,7 @@ Default value is `$HOME/.influxdb/wal`.
See the [file system layout](/enterprise_influxdb/v1/concepts/file-system-layout/#file-system-layout)
for InfluxDB on your system.
##### [ `-tsmfile <tsm_file>` ]
##### [ `-tsmfile <tsm_file>` ] {metadata="v1.12.0+"}
Path to a single tsm file to export. This requires both `-database` and
`-retention` to be specified.
@ -472,7 +472,7 @@ influx_inspect export -compress
influx_inspect export -database DATABASE_NAME -retention RETENTION_POLICY
```
##### Export data from a single TSM file
##### Export data from a single TSM file {metadata="v1.12.0+"}
```bash
influx_inspect export \

6
content/enterprise_influxdb/v1/tools/influxd-ctl/show-shards.md
View File

@ -44,6 +44,8 @@ ID Database Retention Policy Desired Replicas Shard Group Start
{{% /expand %}}
{{< /expand-wrapper >}}
#### Show inconsistent shards {metadata="v1.12.0+"}
You can also use the `-m` flag to output "inconsistent" shards which are shards
that are either in metadata but not on disk or on disk but not in metadata.
@ -52,10 +54,8 @@ that are either in metadata but not on disk or on disk but not in metadata.
| Flag | Description |
| :--- | :-------------------------------- |
| `-v` | Return detailed shard information |
| `-m` | Return inconsistent shards |
| `-m` | Return inconsistent shards |
{{% caption %}}
_Also see [`influxd-ctl` global flags](/enterprise_influxdb/v1/tools/influxd-ctl/#influxd-ctl-global-flags)._
{{% /caption %}}
## Examples

39
content/enterprise_influxdb/v1/tools/influxd-ctl/truncate-shards.md
View File

@ -17,6 +17,14 @@ The `influxd-ctl truncate-shards` command truncates all shards that are currentl
being written to (also known as "hot" shards) and creates new shards to write
new data to.
> [!Caution]
> #### Overlapping shards with forecast and future data
>
> Running `truncate-shards` on shards containing future timestamps can create
> overlapping shards with duplicate data points.
>
> [Understand the risks with future data](#understand-the-risks-with-future-data).
## Usage
```sh
@ -40,3 +48,34 @@ _Also see [`influxd-ctl` global flags](/enterprise_influxdb/v1/tools/influxd-ctl
```bash
influxd-ctl truncate-shards -delay 3m
```
## Understand the risks with future data
> [!Important]
> If you need to rebalance shards that contain future data, contact [InfluxData support](https://www.influxdata.com/contact/) for assistance.
When you write data points with timestamps in the future (for example, forecast data from machine learning models),
the `truncate-shards` command behaves differently and can cause data duplication issues.
### How truncate-shards normally works
For shards containing current data:
1. The command creates an artificial stop point in the shard at the truncation timestamp
2. Creates a new shard starting from the truncation point
3. Example: A one-week shard (Sunday to Saturday) becomes:
- Shard A: Sunday to truncation point (Wednesday 2pm)
- Shard B: Truncation point (Wednesday 2pm) to Saturday
This works correctly because the meta nodes understand the boundaries and route queries appropriately.
### The problem with future data
For shards containing future timestamps:
1. The truncation doesn't cleanly split the shard at a point in time
2. Instead, it creates overlapping shards that cover the same time period
3. Example: If you're writing September forecast data in August:
- Original shard: September 1-7
- After truncation:
- Shard A: September 1-7 (with data up to truncation)
- Shard B: September 1-7 (for new data after truncation)
- **Result**: Duplicate data points for the same timestamps

2
content/influxdb/cloud/account-management/billing.md
View File

@ -103,7 +103,7 @@ If you exceed your plan's [adjustable quotas or limits](/influxdb/cloud/account-
If you exceed the series cardinality limit, InfluxDB adds a rate limit event warning on the **Usage** page, and begins to reject write requests with new series. To start processing write requests again, do the following as needed:
- **Series cardinality limits**: If you exceed the series cardinality limit, see how to [resolve high series cardinality](https://docs.influxdata.com/influxdb/v2/write-data/best-practices/resolve-high-cardinality/).
- **Series cardinality limits**: If you exceed the series cardinality limit, see how to [resolve high series cardinality](/influxdb/v2/write-data/best-practices/resolve-high-cardinality/).
- **Free plan**: To raise rate limits, [upgrade to a Usage-based Plan](#upgrade-to-usage-based-plan).
#### Write and query limits (HTTP response code)

2
content/influxdb/cloud/write-data/replication/replicate-data.md
View File

@ -16,4 +16,4 @@ source: /shared/influxdb-v2/write-data/replication/replicate-data.md
---
<!-- The content of this file is at
// SOURCE content/shared/influxdb-v2/write-data/replication/replicate-data.md-->
// SOURCE content/shared/influxdb-v2/write-data/replication/replicate-data.md -->

25
content/influxdb/v1/about_the_project/release-notes.md
View File

@ -10,27 +10,50 @@ aliases:
- /influxdb/v1/about_the_project/releasenotes-changelog/
alt_links:
v2: /influxdb/v2/reference/release-notes/influxdb/
enterprise_v1: /enterprise_influxdb/v1/about-the-project/release-notes/
---
## v1.12.1 {date="2025-06-26"}
## v1.12.x {date="TBD"}
> [!Important]
> #### Pre-release documentation
>
> This release is not yet available. [**v{{% latest-patch %}}**](#v1118) is the latest InfluxDB v1 release.
## Features
- Add additional log output when using
[`influx_inspect buildtsi`](/influxdb/v1/tools/influx_inspect/#buildtsi) to
rebuild the TSI index.
<!-- TODO: Uncomment with 1.12.x release:
- Use [`influx_inspect export`](/influxdb/v1/tools/influx_inspect/#export) with
[`-tsmfile` option](/influxdb/v1/tools/influx_inspect/#--tsmfile-tsm_file-) to
export a single TSM file.
-->
<!-- TODO: Remove with 1.12.x release: -->
- Use [`influx_inspect export`](/influxdb/v1/tools/influx_inspect/#export) with
`-tsmfile` option to
export a single TSM file.
- Add `fluxQueryRespBytes` metric to the `/debug/vars` metrics endpoint.
<!-- TODO: Uncomment with 1.12.x release:
- Add [`aggressive-points-per-block` configuration option](/influxdb/v1/administration/config/#aggressive-points-per-block)
to prevent TSM files from not getting fully compacted.
-->
<!-- TODO: Remove with 1.12.x release: -->
- Add `aggressive-points-per-block` configuration option
to prevent TSM files from not getting fully compacted.
- Improve error handling.
- InfluxQL updates:
- Delete series by retention policy.
<!-- TODO: Uncomment with 1.12.x release:
- Allow retention policies to discard writes that fall within their range, but
outside of [`FUTURE LIMIT`](/influxdb/v1/query_language/manage-database/#future-limit)
and [`PAST LIMIT`](/influxdb/v1/query_language/manage-database/#past-limit).
-->
<!-- TODO: Remove with 1.12.x release: -->
- Allow retention policies to discard writes that fall within their range, but
outside of `FUTURE LIMIT` and `PAST LIMIT`.
## Bug fixes

68
content/influxdb/v1/administration/upgrading.md
View File

@ -6,22 +6,12 @@ menu:
name: Upgrade InfluxDB
weight: 25
parent: Administration
related:
- /enterprise_influxdb/v1/guides/migration/
- /enterprise_influxdb/v1/administration/upgrading/
---
We recommend enabling Time Series Index (TSI) (step 3 of Upgrade to InfluxDB 1.11.x). [Switch between TSM and TSI](#switch-index-types) as needed. To learn more about TSI, see:
- [Time Series Index (TSI) overview](/influxdb/v1/concepts/time-series-index/)
- [Time Series Index (TSI) details](/influxdb/v1/concepts/tsi-details/)
> **_Note:_** The default configuration continues to use TSM-based shards with in-memory indexes (as in earlier versions).
{{% note %}}
### Upgrade to InfluxDB Enterprise
To upgrade from InfluxDB OSS to InfluxDB Enterprise, [contact InfluxData Sales](https://www.influxdata.com/contact-sales/)
and see [Migrate to InfluxDB Enterprise](/enterprise_influxdb/v1/guides/migration/).
{{% /note %}}
Upgrade to the latest version of InfluxDB OSS v1.
## Upgrade to InfluxDB 1.11.x
@ -29,7 +19,27 @@ and see [Migrate to InfluxDB Enterprise](/enterprise_influxdb/v1/guides/migratio
2. Migrate configuration file customizations from your existing configuration file to the InfluxDB 1.11.x [configuration file](/influxdb/v1/administration/config/). Add or modify your environment variables as needed.
3. To enable TSI in InfluxDB 1.11.x, complete the following steps:
> [!Important]
> #### Choose your index type
> InfluxDB 1.11.x supports two index types:
>
> - **Time Series Index (TSI)** - Recommended for most users. Removes RAM-based limits on series cardinality and provides better performance for high-cardinality datasets.
> - **In-memory index (inmem)** - Default option that maintains compatibility with earlier versions but is limited by available system RAM (series cardinality is limited by available RAM).
>
> **When to use TSI:**
> - General purpose production instances.
> - Especially recommended for:
> - High-cardinality datasets (many unique tag combinations)
> - Experiencing high memory usage or out-of-memory errors
> - Large production deployments
>
> **When to use inmem:**
> - Small datasets when memory is not a constraint
> - Ephemeral deployments such as development or testing environments
>
> To learn more about TSI, see [Time Series Index overview](/influxdb/v1/concepts/time-series-index/) and [TSI details](/influxdb/v1/concepts/tsi-details/).
3. **Optional:** To enable TSI in InfluxDB 1.11.x, complete the following steps:
1. If using the InfluxDB configuration file, find the `[data]` section, uncomment `index-version = "inmem"` and change the value to `tsi1`.
@ -43,26 +53,36 @@ and see [Migrate to InfluxDB Enterprise](/enterprise_influxdb/v1/guides/migratio
```
4. Build TSI by running the [influx_inspect buildtsi](/influxdb/v1/tools/influx_inspect/#buildtsi) command.
{{% note %}}
Run the `buildtsi` command using the user account that you are going to run the database as, or ensure that the permissions match afterward.
{{% /note %}}
> [!Important]
> Run the `buildtsi` command using the user account that you are going to run the database as, or ensure that the permissions match afterward.
4. Restart the `influxdb` service.
> [!Tip]
> #### Switch index types anytime
>
> The default configuration continues to use TSM-based shards with in-memory indexes (as in earlier versions). You can [switch between TSI and inmem index types](#switch-index-types) at any time.
## Switch index types
Switch index types at any time by doing one of the following:
You can switch between index types at any time after upgrading:
- To switch from to `inmem` to `tsi1`, complete steps 3 and 4 above in [Upgrade to InfluxDB 1.11.x](#upgrade-to-influxdb-111x).
- To switch from to `tsi1` to `inmem`, change `tsi1` to `inmem` by completing steps 3a-3c and 4 above in [Upgrade to InfluxDB 1.11.x](#upgrade-to-influxdb-111x).
**Switch from inmem to TSI:**
- Complete steps 3 and 4 in [Upgrade to InfluxDB 1.11.x](#upgrade-to-influxdb-111x)
- Recommended when experiencing high memory usage or out-of-memory errors with high-cardinality data
**Switch from TSI to inmem:**
- Change `tsi1` to `inmem` by completing steps 3a-3c and 4 in [Upgrade to InfluxDB 1.11.x](#upgrade-to-influxdb-111x)
- Suitable for small datasets where memory is not a constraint
## Downgrade InfluxDB
To downgrade to an earlier version, complete the procedures above in [Upgrade to InfluxDB 1.11.x](#upgrade-to-influxdb-111x), replacing the version numbers with the version that you want to downgrade to.
After downloading the release, migrating your configuration settings, and enabling TSI or TSM, make sure to [rebuild your index](/influxdb/v1/administration/rebuild-tsi-index/).
>**Note:** Some versions of InfluxDB may have breaking changes that impact your ability to upgrade and downgrade. For example, you cannot downgrade from InfluxDB 1.3 or later to an earlier version. Please review the applicable version of release notes to check for compatibility issues between releases.
> [!Warning]
> Some versions of InfluxDB may have breaking changes that impact your ability to upgrade and downgrade. For example, you cannot downgrade from InfluxDB 1.3 or later to an earlier version. Please review the applicable version of release notes to check for compatibility issues between releases.
## Upgrade InfluxDB Enterprise clusters
## Upgrade to InfluxDB Enterprise
See [Upgrading InfluxDB Enterprise clusters](/enterprise_influxdb/v1/administration/upgrading/).
To upgrade from InfluxDB OSS to InfluxDB Enterprise, [contact InfluxData Sales](https://www.influxdata.com/contact-sales/).

2
content/influxdb/v1/flux/guides/scalar-values.md
View File

@ -232,7 +232,7 @@ The temperature was ${string(v: lastReported._value)}°F."
The following sample data set represents fictional temperature metrics collected
from three locations.
It's formatted in [annotated CSV](https://v2.docs.influxdata.com/v2.0/reference/syntax/annotated-csv/) and imported
It's formatted in [annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/) and imported
into the Flux query using the [`csv.from()` function](/flux/v0/stdlib/csv/from/).
Place the following at the beginning of your query to use the sample data:

8
content/influxdb/v1/introduction/install.md
View File

@ -75,8 +75,8 @@ For Ubuntu/Debian users, add the InfluxData repository with the following comman
# Primary key fingerprint: 24C9 75CB A61A 024E E1B6 3178 7C3D 5715 9FC2 F927
# Subkey fingerprint: 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
wget -q https://repos.influxdata.com/influxdata-archive.key
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/influxdata-archive.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
```
{{% /code-tab-content %}}
@ -86,8 +86,8 @@ echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive.gpg] https://repo
# Primary key fingerprint: 24C9 75CB A61A 024E E1B6 3178 7C3D 5715 9FC2 F927
# Subkey fingerprint: 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
curl --silent --location -O https://repos.influxdata.com/influxdata-archive.key
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/influxdata-archive.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}

4
content/influxdb/v1/query_language/manage-database.md
View File

@ -307,7 +307,7 @@ See
[Shard group duration management](/influxdb/v1/concepts/schema_and_data_layout/#shard-group-duration-management)
for recommended configurations.
##### `PAST LIMIT`
##### `PAST LIMIT` {metadata="v1.12.0+"}
The `PAST LIMIT` clause defines a time boundary before and relative to _now_
in which points written to the retention policy are accepted. If a point has a
@ -318,7 +318,7 @@ For example, if a write request tries to write data to a retention policy with a
`PAST LIMIT 6h` and there are points in the request with timestamps older than
6 hours, those points are rejected.
##### `FUTURE LIMIT`
##### `FUTURE LIMIT` {metadata="v1.12.0+"}
The `FUTURE LIMIT` clause defines a time boundary after and relative to _now_
in which points written to the retention policy are accepted. If a point has a

2
content/influxdb/v1/tools/api.md
View File

@ -20,7 +20,7 @@ Responses use standard HTTP response codes and JSON format.
To send API requests, you can use
the [InfluxDB v1 client libraries](/influxdb/v1/tools/api_client_libraries/),
the [InfluxDB v2 client libraries](/influxdb/v1/tools/api_client_libraries/),
[Telegraf](https://docs.influxdata.com/telegraf/v1/),
[Telegraf](/telegraf/v1/),
or the client of your choice.
{{% note %}}

4
content/influxdb/v1/tools/influx_inspect.md
View File

@ -449,7 +449,7 @@ Default value is `$HOME/.influxdb/wal`.
See the [file system layout](/influxdb/v1/concepts/file-system-layout/#file-system-layout)
for InfluxDB on your system.
##### [ `-tsmfile <tsm_file>` ]
##### [ `-tsmfile <tsm_file>` ] {metadata="v1.12.0+"}
Path to a single tsm file to export. This requires both `-database` and
`-retention` to be specified.
@ -468,7 +468,7 @@ influx_inspect export -compress
influx_inspect export -database DATABASE_NAME -retention RETENTION_POLICY
```
##### Export data from a single TSM file
##### Export data from a single TSM file {metadata="v1.12.0+"}
```bash
influx_inspect export \

22
content/influxdb/v2/install/_index.md
View File

@ -112,7 +112,7 @@ _If `gpg` isn't available on your system, see
The following steps guide you through using GPG to verify InfluxDB
binary releases:
1. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-system).
1. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-os-version).
2. Download and import the InfluxData public key.
`gpg --import` outputs to stderr.
@ -354,8 +354,8 @@ To install {{% product-name %}} on Linux, do one of the following:
| grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' \
&& cat influxdata-archive.key \
| gpg --dearmor \
| sudo tee /etc/apt/trusted.gpg.d/influxdata-archive.gpg > /dev/null \
&& echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \
| sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null \
&& echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \
| sudo tee /etc/apt/sources.list.d/influxdata.list
# Install influxdb
sudo apt-get update && sudo apt-get install influxdb2
@ -376,7 +376,7 @@ To install {{% product-name %}} on Linux, do one of the following:
cat <<EOF | tee /etc/yum.repos.d/influxdata.repo
[influxdata]
name = InfluxData Repository - Stable
baseurl = https://repos.influxdata.com/stable/${basearch}/main
baseurl = https://repos.influxdata.com/stable/\${basearch}/main
enabled = 1
gpgcheck = 1
gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-influxdata
@ -473,7 +473,7 @@ _If necessary, adjust the example file paths and utilities for your system._
https://download.influxdata.com/influxdb/releases/v{{< latest-patch >}}/influxdb2-{{< latest-patch >}}_linux_arm64.tar.gz
```
2. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-system).
2. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-os-version).
3. {{< req text="Recommended:" color="magenta" >}}: Verify the authenticity of the downloaded binary--for example,
enter the following command in your terminal.
@ -675,7 +675,7 @@ data isn't deleted if you delete the container._
flags for initial setup options and file system mounts.
_If you don't specify InfluxDB initial setup options, you can
[set up manually](#set-up-influxdb) later using the UI or CLI in a running
[set up manually](/influxdb/v2/get-started/setup/) later using the UI or CLI in a running
container._
{{% code-placeholders "ADMIN_(USERNAME|PASSWORD)|ORG_NAME|BUCKET_NAME" %}}
@ -731,7 +731,8 @@ and _[Operator token](/influxdb/v2/admin/tokens/#operator-token)_, and logs to s
You can view the Operator token in the `/etc/influxdb2/influx-configs` file and
use it to authorize
[creating an All Access token](#optional-create-all-access-tokens).
[creating an All Access token](#examples).
For more information, see [API token types](/influxdb/v2/admin/tokens/#api-token-types).
_To run the InfluxDB container in
[detached mode](https://docs.docker.com/engine/reference/run/#detached-vs-foreground),
@ -761,6 +762,13 @@ docker exec -it <CONTAINER_NAME> <CLI_NAME> <COMMAND>`
<!--pytest.mark.skip-->
```bash
# Create an All Access token
docker exec -it influxdb2 influx auth create \
--all-access \
--token OPERATOR_TOKEN
```
```bash
# List CLI configurations
docker exec -it influxdb2 influx config ls

2
content/influxdb/v2/reference/release-notes/influxdb.md
View File

@ -643,7 +643,7 @@ to migrate InfluxDB key-value metadata schemas to earlier 2.x versions when nece
#### Telegraf
- Add the following new [Telegraf plugins](https://docs.influxdata.com/telegraf/v1/plugins/) to the Load Data page:
- Add the following new [Telegraf plugins](/telegraf/v1/plugins/) to the Load Data page:
- Alibaba (Aliyun) CloudMonitor Service Statistics (`aliyuncms`)
- AMD ROCm System Management Interface (SMI) (`amd_rocm_smi`)
- Counter-Strike: Global Offensive (CS:GO) (`csgo`)

2
content/influxdb3/cloud-dedicated/admin/monitor-your-cluster.md
View File

@ -328,7 +328,7 @@ following levels:
- **L3**: 4 L2 files compacted together
Parquet files store data partitioned by time and optionally tags
_(see [Manage data partition](https://docs.influxdata.com/influxdb3/cloud-dedicated/admin/custom-partitions/))_.
_(see [Manage data partition](/influxdb3/cloud-dedicated/admin/custom-partitions/))_.
After four L0 files accumulate for a partition, they're eligible for compaction.
If the compactor is keeping up with the incoming write load, all compaction
events have exactly four files.

198
content/influxdb3/cloud-dedicated/process-data/visualize/grafana.md
View File

@ -9,7 +9,7 @@ menu:
influxdb3_cloud_dedicated:
name: Use Grafana
parent: Visualize data
influxdb3/cloud-dedicated/tags: [Flight client, query, visualization]
influxdb3/cloud-dedicated/tags: [query, visualization, Grafana]
aliases:
- /influxdb3/cloud-dedicated/query-data/tools/grafana/
- /influxdb3/cloud-dedicated/query-data/sql/execute-queries/grafana/
@ -20,199 +20,7 @@ alt_links:
cloud: /influxdb/cloud/tools/grafana/
core: /influxdb3/core/visualize-data/grafana/
enterprise: /influxdb3/enterprise/visualize-data/grafana/
source: /content/shared/v3-process-data/visualize/grafana.md
---
Use [Grafana](https://grafana.com/) to query and visualize data stored in
{{% product-name %}}.
> [Grafana] enables you to query, visualize, alert on, and explore your metrics,
> logs, and traces wherever they are stored.
> [Grafana] provides you with tools to turn your time-series database (TSDB)
> data into insightful graphs and visualizations.
>
> {{% cite %}}-- [Grafana documentation](https://grafana.com/docs/grafana/latest/introduction/){{% /cite %}}
<!-- TOC -->
- [Install Grafana or login to Grafana Cloud](#install-grafana-or-login-to-grafana-cloud)
- [InfluxDB data source](#influxdb-data-source)
- [Create an InfluxDB data source](#create-an-influxdb-data-source)
- [Query InfluxDB with Grafana](#query-influxdb-with-grafana)
- [Build visualizations with Grafana](#build-visualizations-with-grafana)
<!-- /TOC -->
## Install Grafana or login to Grafana Cloud
If using the open source version of **Grafana**, follow the
[Grafana installation instructions](https://grafana.com/docs/grafana/latest/setup-grafana/installation/)
to install Grafana for your operating system.
If using **Grafana Cloud**, login to your Grafana Cloud instance.
## InfluxDB data source
The InfluxDB data source plugin is included in the Grafana core distribution.
Use the plugin to query and visualize data stored in {{< product-name >}} with
both InfluxQL and SQL.
> [!Note]
> #### Grafana 10.3+
>
> The instructions below are for **Grafana 10.3+** which introduced the newest
> version of the InfluxDB core plugin.
> The updated plugin includes **SQL support** for InfluxDB 3-based products such
> as {{< product-name >}}.
## Create an InfluxDB data source
1. In your Grafana user interface (UI), navigate to **Data Sources**.
2. Click **Add new data source**.
3. Search for and select the **InfluxDB** plugin.
4. Provide a name for your data source.
5. Under **Query Language**, select either **SQL** or **InfluxQL**:
{{< tabs-wrapper >}}
{{% tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------- BEGIN SQL --------------------------------->
When creating an InfluxDB data source that uses SQL to query data:
1. Under **HTTP**:
- **URL**: Provide your {{% product-name omit=" Clustered" %}} cluster URL
using the HTTPS protocol:
```
https://{{< influxdb/host >}}
```
2. Under **InfluxDB Details**:
- **Database**: Provide a default database name to query.
- **Token**: Provide a [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens)
with read access to the databases you want to query.
3. Click **Save & test**.
{{< img-hd src="/img/influxdb3/cloud-dedicated-grafana-influxdb-data-source-sql.png" alt="Grafana InfluxDB data source for InfluxDB Cloud Serverless that uses SQL" />}}
<!---------------------------------- END SQL ---------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXQL ------------------------------>
When creating an InfluxDB data source that uses InfluxQL to query data:
1. Under **HTTP**:
- **URL**: Provide your {{% product-name %}} cluster URL
using the HTTPS protocol:
```
https://{{< influxdb/host >}}
```
2. Under **InfluxDB Details**:
- **Database**: Provide a default database name to query.
- **User**: Provide an arbitrary string.
_This credential is ignored when querying {{% product-name %}}, but it cannot be empty._
- **Password**: Provide a [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens)
with read access to the databases you want to query.
- **HTTP Method**: Choose one of the available HTTP request methods to use when querying data:
- **POST** ({{< req text="Recommended" >}})
- **GET**
3. Click **Save & test**.
{{< img-hd src="/img/influxdb3/cloud-dedicated-grafana-influxdb-data-source-influxql.png" alt="Grafana InfluxDB data source for InfluxDB Cloud Serverless using InfluxQL" />}}
<!-------------------------------- END INFLUXQL ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## Query InfluxDB with Grafana
After you [configure and save an InfluxDB datasource](#create-a-datasource),
use Grafana to build, run, and inspect queries against your InfluxDB database.
{{< tabs-wrapper >}}
{{% tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------- BEGIN SQL --------------------------------->
> [!Note]
> {{% sql/sql-schema-intro %}}
> To learn more, see [Query Data](/influxdb3/cloud-dedicated/query-data/sql/).
1. Click **Explore**.
2. In the dropdown, select the saved InfluxDB data source to query.
3. Use the SQL query form to build your query:
- **Table**: Select the measurement to query.
- **Column**: Select one or more fields and tags to return as columns in query results.
With SQL, select the `time` column to include timestamps with the data.
Grafana relies on the `time` column to correctly graph time series data.
- _**Optional:**_ Toggle **filter** to generate **WHERE** clause statements.
- **WHERE**: Configure condition expressions to include in the `WHERE` clause.
- _**Optional:**_ Toggle **group** to generate **GROUP BY** clause statements.
- **GROUP BY**: Select columns to group by.
If you include an aggregation function in the **SELECT** list,
you must group by one or more of the queried columns.
SQL returns the aggregation for each group.
- {{< req text="Recommended" color="green" >}}:
Toggle **order** to generate **ORDER BY** clause statements.
- **ORDER BY**: Select columns to sort by.
You can sort by time and multiple fields or tags.
To sort in descending order, select **DESC**.
4. {{< req text="Recommended" color="green" >}}: Change format to **Time series**.
- Use the **Format** dropdown to change the format of the query results.
For example, to visualize the query results as a time series, select **Time series**.
5. Click **Run query** to execute the query.
<!---------------------------------- END SQL ---------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXQL ------------------------------>
1. Click **Explore**.
2. In the dropdown, select the **InfluxDB** data source that you want to query.
3. Use the InfluxQL query form to build your query:
- **FROM**: Select the measurement that you want to query.
- **WHERE**: To filter the query results, enter a conditional expression.
- **SELECT**: Select fields to query and an aggregate function to apply to each.
The aggregate function is applied to each time interval defined in the
`GROUP BY` clause.
- **GROUP BY**: By default, Grafana groups data by time to downsample results
and improve query performance.
You can also add other tags to group by.
4. Click **Run query** to execute the query.
<!-------------------------------- END INFLUXQL ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
{{< youtube "rSsouoNsNDs" >}}
To learn about query management and inspection in Grafana, see the
[Grafana Explore documentation](https://grafana.com/docs/grafana/latest/explore/).
## Build visualizations with Grafana
For a comprehensive walk-through of creating visualizations with
Grafana, see the [Grafana documentation](https://grafana.com/docs/grafana/latest/).
<!-- SOURCE: /content/shared/v3-process-data/visualize/grafana.md -->

4
content/influxdb3/cloud-dedicated/reference/cli/influxctl/_index.md
View File

@ -176,8 +176,8 @@ To download the Linux `influxctl` package, do one of the following:
# Primary key fingerprint: 24C9 75CB A61A 024E E1B6 3178 7C3D 5715 9FC2 F927
# Subkey fingerprint: 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
wget -q https://repos.influxdata.com/influxdata-archive.key
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/influxdata-archive.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
sudo apt-get update && sudo apt-get install influxctl
```

73
content/influxdb3/cloud-dedicated/reference/internals/durability.md
View File

@ -1,7 +1,8 @@
---
title: InfluxDB Cloud Dedicated data durability
description: >
InfluxDB Cloud Dedicated replicates all time series data in the storage tier across
Data written to {{% product-name %}} progresses through multiple stages to ensure durability, optimized performance and storage, and efficient querying. Configuration options at each stage affect system behavior, balancing reliability and resource usage.
{{% product-name %}} replicates all time series data in the storage tier across
multiple availability zones within a cloud region and automatically creates backups
that can be used to restore data in the event of a node failure or data corruption.
weight: 102
@ -13,73 +14,7 @@ influxdb3/cloud-dedicated/tags: [backups, internals]
related:
- https://docs.aws.amazon.com/AmazonS3/latest/userguide/DataDurability.html, AWS S3 Data Durabililty
- /influxdb3/cloud-dedicated/reference/internals/storage-engine/
source: /shared/v3-distributed-internals-reference/durability.md
---
{{< product-name >}} writes data to multiple Write-Ahead-Log (WAL) files on local
storage and retains WALs until the data is persisted to Parquet files in object storage.
Parquet data files in object storage are redundantly stored on multiple devices
across a minimum of three availability zones in a cloud region.
## Data storage
In {{< product-name >}}, all measurements are stored in
[Apache Parquet](https://parquet.apache.org/) files that represent a
point-in-time snapshot of the data. The Parquet files are immutable and are
never replaced nor modified. Parquet files are stored in object storage and
referenced in the [Catalog](/influxdb3/cloud-dedicated/reference/internals/storage-engine/#catalog), which InfluxDB uses to find the appropriate Parquet files for a particular set of data.
### Data deletion
When data is deleted or expires (reaches the database's [retention period](/influxdb3/cloud-dedicated/reference/internals/data-retention/#database-retention-period)), InfluxDB performs the following steps:
1. Marks the associated Parquet files as deleted in the catalog.
2. Filters out data marked for deletion from all queries.
3. Retains Parquet files marked for deletion in object storage for approximately 30 days after the youngest data in the file ages out of retention.
## Data ingest
When data is written to {{< product-name >}}, InfluxDB first writes the data to a
Write-Ahead-Log (WAL) on locally attached storage on the [Ingester](/influxdb3/cloud-dedicated/reference/internals/storage-engine/#ingester) node before
acknowledging the write request. After acknowledging the write request, the
Ingester holds the data in memory temporarily and then writes the contents of
the WAL to Parquet files in object storage and updates the [Catalog](/influxdb3/cloud-dedicated/reference/internals/storage-engine/#catalog) to
reference the newly created Parquet files. If an Ingester node is gracefully shut
down (for example, during a new software deployment), it flushes the contents of
the WAL to the Parquet files before shutting down.
## Backups
{{< product-name >}} implements the following data backup strategies:
- **Backup of WAL file**: The WAL file is written on locally attached storage.
If an ingester process fails, the new ingester simply reads the WAL file on
startup and continues normal operation. WAL files are maintained until their
contents have been written to the Parquet files in object storage.
For added protection, ingesters can be configured for write replication, where
each measurement is written to two different WAL files before acknowledging
the write.
- **Backup of Parquet files**: Parquet files are stored in object storage where
they are redundantly stored on multiple devices across a minimum of three
availability zones in a cloud region. Parquet files associated with each
database are kept in object storage for the duration of database retention period
plus an additional time period (approximately 30 days).
- **Backup of catalog**: InfluxData keeps a transaction log of all recent updates
to the [InfluxDB catalog](/influxdb3/cloud-dedicated/reference/internals/storage-engine/#catalog) and generates a daily backup of
the catalog. Backups are preserved for at least 30 days in object storage across a minimum
of three availability zones.
## Recovery
InfluxData can perform the following recovery operations:
- **Recovery after ingester failure**: If an ingester fails, a new ingester is
started up and reads from the WAL file for the recently ingested data.
- **Recovery of Parquet files**: {{< product-name >}} uses the provided object
storage data durability to recover Parquet files.
- **Recovery of the catalog**: InfluxData can restore the [Catalog](/influxdb3/cloud-dedicated/reference/internals/storage-engine/#catalog) to
the most recent daily backup and then reapply any transactions
that occurred since the interruption.
<!--// SOURCE - content/shared/v3-distributed-internals-reference/durability.md -->

2
content/influxdb3/cloud-dedicated/reference/internals/security.md
View File

@ -67,7 +67,7 @@ by periodically creating, recording, and writing test data into test buckets.
The service periodically executes queries to ensure the data hasn't been lost or corrupted.
A separate instance of this service lives within each {{% product-name %}} cluster.
Additionally, the service creates out-of-band backups in
[line protocol](https://docs.influxdata.com/influxdb/cloud/reference/syntax/line-protocol/),
[line protocol](/influxdb/cloud/reference/syntax/line-protocol/),
and ensures the backup data matches the data on disk.
## Cloud infrastructure

2
content/influxdb3/cloud-dedicated/reference/sql/functions/_index.md
View File

@ -14,5 +14,5 @@ source: /shared/sql-reference/functions/_index.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/_index.md
// SOURCE content/shared/sql-reference/functions/_index.md
-->

2
content/influxdb3/cloud-dedicated/reference/sql/functions/aggregate.md
View File

@ -15,5 +15,5 @@ source: /shared/sql-reference/functions/aggregate.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/aggregate.md
// SOURCE content/shared/sql-reference/functions/aggregate.md
-->

17
content/influxdb3/cloud-dedicated/reference/sql/functions/array.md Normal file
View File

@ -0,0 +1,17 @@
---
title: SQL array functions
list_title: Array functions
description: >
Use array functions to create and operate on Arrow arrays or lists in SQL queries.
menu:
influxdb3_cloud_dedicated:
name: Array
parent: sql-functions
weight: 309
source: /shared/sql-reference/functions/array.md
---
<!--
// SOURCE content/shared/sql-reference/functions/array.md
-->

3
content/influxdb3/cloud-dedicated/reference/sql/functions/binary-string.md
View File

@ -14,6 +14,5 @@ source: /shared/sql-reference/functions/binary-string.md
---
<!--
The content of this page is at
// SOURCE /content/shared/sql-reference/functions/binary-string.md
// SOURCE content/shared/sql-reference/functions/binary-string.md
-->

2
content/influxdb3/cloud-dedicated/reference/sql/functions/conditional.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/conditional.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/conditional.md
// SOURCE content/shared/sql-reference/functions/conditional.md
-->

5
content/influxdb3/cloud-dedicated/reference/sql/functions/hashing.md
View File

@ -8,12 +8,11 @@ menu:
influxdb3_cloud_dedicated:
name: Hashing
parent: sql-functions
weight: 309
weight: 313
source: /shared/sql-reference/functions/hashing.md
---
<!--
The content for this page is at
// SOURCE /content/shared/sql-reference/functions/hashing.md
// SOURCE content/shared/sql-reference/functions/hashing.md
-->

17
content/influxdb3/cloud-dedicated/reference/sql/functions/map.md Normal file
View File

@ -0,0 +1,17 @@
---
title: SQL map functions
list_title: Map functions
description: >
Use map functions to create and operate on Arrow maps in SQL queries.
menu:
influxdb3_cloud_dedicated:
name: Map
parent: sql-functions
weight: 310
source: /shared/sql-reference/functions/map.md
---
<!--
// SOURCE content/shared/sql-reference/functions/map.md
-->

2
content/influxdb3/cloud-dedicated/reference/sql/functions/math.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/math.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/math.md
// SOURCE content/shared/sql-reference/functions/math.md
-->

4
content/influxdb3/cloud-dedicated/reference/sql/functions/misc.md
View File

@ -7,11 +7,11 @@ menu:
influxdb3_cloud_dedicated:
name: Miscellaneous
parent: sql-functions
weight: 310
weight: 314
source: /shared/sql-reference/functions/misc.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/misc.md
// SOURCE content/shared/sql-reference/functions/misc.md
-->

4
content/influxdb3/cloud-dedicated/reference/sql/functions/regular-expression.md
View File

@ -7,12 +7,12 @@ menu:
influxdb3_cloud_dedicated:
name: Regular expression
parent: sql-functions
weight: 308
weight: 312
influxdb3/cloud-dedicated/tags: [regular expressions, sql]
source: /shared/sql-reference/functions/regular-expression.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/regular-expression.md
// SOURCE content/shared/sql-reference/functions/regular-expression.md
-->

2
content/influxdb3/cloud-dedicated/reference/sql/functions/selector.md
View File

@ -15,5 +15,5 @@ source: /shared/sql-reference/functions/selector.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/selector.md
// SOURCE content/shared/sql-reference/functions/selector.md
-->

2
content/influxdb3/cloud-dedicated/reference/sql/functions/string.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/string.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/string.md
// SOURCE content/shared/sql-reference/functions/string.md
-->

17
content/influxdb3/cloud-dedicated/reference/sql/functions/struct.md Normal file
View File

@ -0,0 +1,17 @@
---
title: SQL struct functions
list_title: Struct functions
description: >
Use struct functions to create Arrow structs in SQL queries.
menu:
influxdb3_cloud_dedicated:
name: Struct
parent: sql-functions
weight: 311
source: /shared/sql-reference/functions/struct.md
---
<!--
// SOURCE content/shared/sql-reference/functions/struct.md
-->

2
content/influxdb3/cloud-dedicated/reference/sql/functions/time-and-date.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/time-and-date.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/time-and-date.md
// SOURCE content/shared/sql-reference/functions/time-and-date.md
-->

4
content/influxdb3/cloud-dedicated/reference/sql/functions/window.md
View File

@ -8,11 +8,11 @@ menu:
influxdb3_cloud_dedicated:
name: Window
parent: sql-functions
weight: 309
weight: 315
source: /shared/sql-reference/functions/window.md
---
<!--
The content for this page is at content/shared/sql-reference/functions/window.md
// SOURCE content/shared/sql-reference/functions/window.md
-->

16
content/influxdb3/cloud-dedicated/write-data/best-practices/optimize-writes.md
View File

@ -416,9 +416,23 @@ The following example creates sample data for two series (the combination of mea
### Avoid sending duplicate data
Use Telegraf and the [Dedup processor plugin](/telegraf/v1/plugins/#processor-dedup) to filter data whose field values are exact repetitions of previous values.
When writing duplicate points (points with the same timestamp and tag set),
InfluxDB deduplicates the data by creating a union of the duplicate points.
Deduplicating your data can reduce your write payload size and resource usage.
> [!Important]
> #### Write ordering for duplicate points
>
> InfluxDB attempts to honor write ordering for duplicate points, with the most
> recently written point taking precedence. However, when data is flushed from
> the in-memory buffer to Parquet files—typically every 15 minutes, but
> sometimes sooner—this ordering is not guaranteed if duplicate points are flushed
> at the same time. As a result, the last written duplicate point may not always
> be retained in storage.
Use Telegraf and the [Dedup processor plugin](/telegraf/v1/plugins/#processor-dedup)
to filter data whose field values are exact repetitions of previous values.
The following example shows how to use Telegraf to remove points that repeat field values, and then write the data to InfluxDB:
1. In your terminal, enter the following command to create the sample data file and calculate the number of seconds between the earliest timestamp and _now_.

208
content/influxdb3/cloud-serverless/process-data/visualize/grafana.md
View File

@ -21,211 +21,7 @@ alt_links:
cloud: /influxdb/cloud/tools/grafana/
core: /influxdb3/core/visualize-data/grafana/
enterprise: /influxdb3/enterprise/visualize-data/grafana/
source: /content/shared/v3-process-data/visualize/grafana.md
---
Use [Grafana](https://grafana.com/) to query and visualize data stored in
{{% product-name %}}.
> [Grafana] enables you to query, visualize, alert on, and explore your metrics,
> logs, and traces wherever they are stored.
> [Grafana] provides you with tools to turn your time-series database (TSDB)
> data into insightful graphs and visualizations.
>
> {{% cite %}}-- [Grafana documentation](https://grafana.com/docs/grafana/latest/introduction/){{% /cite %}}
<!-- TOC -->
- [Install Grafana or login to Grafana Cloud](#install-grafana-or-login-to-grafana-cloud)
- [InfluxDB data source](#influxdb-data-source)
- [Create an InfluxDB data source](#create-an-influxdb-data-source)
- [Query InfluxDB with Grafana](#query-influxdb-with-grafana)
- [Build visualizations with Grafana](#build-visualizations-with-grafana)
<!-- /TOC -->
## Install Grafana or login to Grafana Cloud
If using the open source version of **Grafana**, follow the
[Grafana installation instructions](https://grafana.com/docs/grafana/latest/setup-grafana/installation/)
to install Grafana for your operating system.
If using **Grafana Cloud**, login to your Grafana Cloud instance.
## InfluxDB data source
The InfluxDB data source plugin is included in the Grafana core distribution.
Use the plugin to query and visualize data stored in {{< product-name >}} with
both InfluxQL and SQL.
> [!Note]
> #### Grafana 10.3+
>
> The instructions below are for **Grafana 10.3+** which introduced the newest
> version of the InfluxDB core plugin.
> The updated plugin includes **SQL support** for InfluxDB 3-based products such
> as {{< product-name >}}.
## Create an InfluxDB data source
Which data source you create depends on which query language you want to use to
query {{% product-name %}}:
1. In your Grafana user interface (UI), navigate to **Data Sources**.
2. Click **Add new data source**.
3. Search for and select the **InfluxDB** plugin.
4. Provide a name for your data source.
5. Under **Query Language**, select either **SQL** or **InfluxQL**:
{{< tabs-wrapper >}}
{{% tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------- BEGIN SQL --------------------------------->
When creating an InfluxDB data source that uses SQL to query data:
1. Under **HTTP**:
- **URL**: Provide your [{{% product-name %}} region URL](/influxdb3/cloud-serverless/reference/regions/)
using the HTTPS protocol:
```
https://{{< influxdb/host >}}
```
2. Under **InfluxDB Details**:
- **Database**: Provide a default bucket name to query.
In {{< product-name >}}, a bucket functions as a database.
- **Token**: Provide an [API token](/influxdb3/cloud-serverless/admin/tokens/)
with read access to the buckets you want to query.
3. Click **Save & test**.
{{< img-hd src="/img/influxdb3/cloud-serverless-grafana-influxdb-data-source-sql.png" alt="Grafana InfluxDB data source for InfluxDB Cloud Serverless that uses SQL" />}}
<!---------------------------------- END SQL ---------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXQL ------------------------------>
When creating an InfluxDB data source that uses InfluxQL to query data:
> [!Note]
> #### Map databases and retention policies to buckets
>
> To query {{% product-name %}} with InfluxQL, first map database and retention policy
> (DBRP) combinations to your InfluxDB Cloud buckets. For more information, see
> [Map databases and retention policies to buckets](/influxdb3/cloud-serverless/query-data/influxql/dbrp/).
1. Under **HTTP**:
- **URL**: Provide your [{{% product-name %}} region URL](/influxdb3/cloud-serverless/reference/regions/)
using the HTTPS protocol:
```
https://{{< influxdb/host >}}
```
2. Under **InfluxDB Details**:
- **Database**: Provide a database name to query.
Use the database name that is mapped to your InfluxBD bucket.
- **User**: Provide an arbitrary string.
_This credential is ignored when querying {{% product-name %}}, but it cannot be empty._
- **Password**: Provide an [API token](/influxdb3/cloud-serverless/admin/tokens/)
with read access to the buckets you want to query.
- **HTTP Method**: Choose one of the available HTTP request methods to use when querying data:
- **POST** ({{< req text="Recommended" >}})
- **GET**
3. Click **Save & test**.
{{< img-hd src="/img/influxdb3/cloud-serverless-grafana-influxdb-data-source-influxql.png" alt="Grafana InfluxDB data source for InfluxDB Cloud Serverless using InfluxQL" />}}
<!-------------------------------- END INFLUXQL ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## Query InfluxDB with Grafana
After you [configure and save a FlightSQL or InfluxDB datasource](#create-a-datasource),
use Grafana to build, run, and inspect queries against your InfluxDB bucket.
{{< tabs-wrapper >}}
{{% tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------- BEGIN SQL --------------------------------->
> [!Note]
> {{% sql/sql-schema-intro %}}
> To learn more, see [Query Data](/influxdb3/cloud-serverless/query-data/sql/).
1. Click **Explore**.
2. In the dropdown, select the saved InfluxDB data source to query.
3. Use the SQL query form to build your query:
- **Table**: Select the measurement to query.
- **Column**: Select one or more fields and tags to return as columns in query results.
With SQL, select the `time` column to include timestamps with the data.
Grafana relies on the `time` column to correctly graph time series data.
- _**Optional:**_ Toggle **filter** to generate **WHERE** clause statements.
- **WHERE**: Configure condition expressions to include in the `WHERE` clause.
- _**Optional:**_ Toggle **group** to generate **GROUP BY** clause statements.
- **GROUP BY**: Select columns to group by.
If you include an aggregation function in the **SELECT** list,
you must group by one or more of the queried columns.
SQL returns the aggregation for each group.
- {{< req text="Recommended" color="green" >}}:
Toggle **order** to generate **ORDER BY** clause statements.
- **ORDER BY**: Select columns to sort by.
You can sort by time and multiple fields or tags.
To sort in descending order, select **DESC**.
4. {{< req text="Recommended" color="green" >}}: Change format to **Time series**.
- Use the **Format** dropdown to change the format of the query results.
For example, to visualize the query results as a time series, select **Time series**.
5. Click **Run query** to execute the query.
<!---------------------------------- END SQL ---------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXQL ------------------------------>
1. Click **Explore**.
2. In the dropdown, select the **InfluxDB** data source that you want to query.
3. Use the InfluxQL query form to build your query:
- **FROM**: Select the measurement that you want to query.
- **WHERE**: To filter the query results, enter a conditional expression.
- **SELECT**: Select fields to query and an aggregate function to apply to each.
The aggregate function is applied to each time interval defined in the
`GROUP BY` clause.
- **GROUP BY**: By default, Grafana groups data by time to downsample results
and improve query performance.
You can also add other tags to group by.
4. Click **Run query** to execute the query.
<!-------------------------------- END INFLUXQL ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
{{< youtube "rSsouoNsNDs" >}}
To learn about query management and inspection in Grafana, see the
[Grafana Explore documentation](https://grafana.com/docs/grafana/latest/explore/).
## Build visualizations with Grafana
For a comprehensive walk-through of creating visualizations with
Grafana, see the [Grafana documentation](https://grafana.com/docs/grafana/latest/).
<!-- SOURCE: /content/shared/v3-process-data/visualize/grafana.md -->

2
content/influxdb3/cloud-serverless/reference/internals/durability.md
View File

@ -27,7 +27,7 @@ point-in-time snapshot of the data. The Parquet files are immutable and are
never replaced nor modified. Parquet files are stored in object storage.
<span id="influxdb-catalog"></span>
The _InfluxDB catalog_ is a relational, PostreSQL-compatible database that
The _InfluxDB catalog_ is a relational, PostgreSQL-compatible database that
contains references to all Parquet files in object storage and is used as an
index to find the appropriate Parquet files for a particular set of data.

4
content/influxdb3/cloud-serverless/reference/sql/functions/_index.md
View File

@ -14,5 +14,5 @@ source: /shared/sql-reference/functions/_index.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/_index.md
-->
// SOURCE content/shared/sql-reference/functions/_index.md
-->

2
content/influxdb3/cloud-serverless/reference/sql/functions/aggregate.md
View File

@ -15,5 +15,5 @@ source: /shared/sql-reference/functions/aggregate.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/aggregate.md
// SOURCE content/shared/sql-reference/functions/aggregate.md
-->

17
content/influxdb3/cloud-serverless/reference/sql/functions/array.md Normal file
View File

@ -0,0 +1,17 @@
---
title: SQL array functions
list_title: Array functions
description: >
Use array functions to create and operate on Arrow arrays or lists in SQL queries.
menu:
influxdb3_cloud_serverless:
name: Array
parent: sql-functions
weight: 309
source: /shared/sql-reference/functions/array.md
---
<!--
// SOURCE content/shared/sql-reference/functions/array.md
-->

3
content/influxdb3/cloud-serverless/reference/sql/functions/binary-string.md
View File

@ -14,6 +14,5 @@ source: /shared/sql-reference/functions/binary-string.md
---
<!--
The content of this page is at
// SOURCE /content/shared/sql-reference/functions/binary-string.md
// SOURCE content/shared/sql-reference/functions/binary-string.md
-->

2
content/influxdb3/cloud-serverless/reference/sql/functions/conditional.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/conditional.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/conditional.md
// SOURCE content/shared/sql-reference/functions/conditional.md
-->

5
content/influxdb3/cloud-serverless/reference/sql/functions/hashing.md
View File

@ -8,12 +8,11 @@ menu:
influxdb3_cloud_serverless:
name: Hashing
parent: sql-functions
weight: 309
weight: 313
source: /shared/sql-reference/functions/hashing.md
---
<!--
The content for this page is at
// SOURCE /content/shared/sql-reference/functions/hashing.md
// SOURCE content/shared/sql-reference/functions/hashing.md
-->

17
content/influxdb3/cloud-serverless/reference/sql/functions/map.md Normal file
View File

@ -0,0 +1,17 @@
---
title: SQL map functions
list_title: Map functions
description: >
Use map functions to create and operate on Arrow maps in SQL queries.
menu:
influxdb3_cloud_serverless:
name: Map
parent: sql-functions
weight: 310
source: /shared/sql-reference/functions/map.md
---
<!--
// SOURCE content/shared/sql-reference/functions/map.md
-->

4
content/influxdb3/cloud-serverless/reference/sql/functions/math.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/math.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/math.md
-->
// SOURCE content/shared/sql-reference/functions/math.md
-->

6
content/influxdb3/cloud-serverless/reference/sql/functions/misc.md
View File

@ -7,11 +7,11 @@ menu:
influxdb3_cloud_serverless:
name: Miscellaneous
parent: sql-functions
weight: 310
weight: 314
source: /shared/sql-reference/functions/misc.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/misc.md
-->
// SOURCE content/shared/sql-reference/functions/misc.md
-->

6
content/influxdb3/cloud-serverless/reference/sql/functions/regular-expression.md
View File

@ -7,12 +7,12 @@ menu:
influxdb3_cloud_serverless:
name: Regular expression
parent: sql-functions
weight: 308
weight: 312
influxdb3/cloud-serverless/tags: [regular expressions, sql]
source: /shared/sql-reference/functions/regular-expression.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/regular-expression.md
-->
// SOURCE content/shared/sql-reference/functions/regular-expression.md
-->

2
content/influxdb3/cloud-serverless/reference/sql/functions/selector.md
View File

@ -15,5 +15,5 @@ source: /shared/sql-reference/functions/selector.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/selector.md
// SOURCE content/shared/sql-reference/functions/selector.md
-->

2
content/influxdb3/cloud-serverless/reference/sql/functions/string.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/string.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/string.md
// SOURCE content/shared/sql-reference/functions/string.md
-->

17
content/influxdb3/cloud-serverless/reference/sql/functions/struct.md Normal file
View File

@ -0,0 +1,17 @@
---
title: SQL struct functions
list_title: Struct functions
description: >
Use struct functions to create Arrow structs in SQL queries.
menu:
influxdb3_cloud_serverless:
name: Struct
parent: sql-functions
weight: 311
source: /shared/sql-reference/functions/struct.md
---
<!--
// SOURCE content/shared/sql-reference/functions/struct.md
-->

2
content/influxdb3/cloud-serverless/reference/sql/functions/time-and-date.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/time-and-date.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/time-and-date.md
// SOURCE content/shared/sql-reference/functions/time-and-date.md
-->

4
content/influxdb3/cloud-serverless/reference/sql/functions/window.md
View File

@ -8,11 +8,11 @@ menu:
influxdb3_cloud_serverless:
name: Window
parent: sql-functions
weight: 309
weight: 315
source: /shared/sql-reference/functions/window.md
---
<!--
The content for this page is at content/shared/sql-reference/functions/window.md
// SOURCE content/shared/sql-reference/functions/window.md
-->

16
content/influxdb3/cloud-serverless/write-data/best-practices/optimize-writes.md
View File

@ -430,9 +430,23 @@ The following example creates sample data for two series (the combination of mea
### Avoid sending duplicate data
Use Telegraf and the [Dedup processor plugin](/telegraf/v1/plugins/#processor-dedup) to filter data whose field values are exact repetitions of previous values.
When writing duplicate points (points with the same timestamp and tag set),
InfluxDB deduplicates the data by creating a union of the duplicate points.
Deduplicating your data can reduce your write payload size and resource usage.
> [!Important]
> #### Write ordering for duplicate points
>
> InfluxDB attempts to honor write ordering for duplicate points, with the most
> recently written point taking precedence. However, when data is flushed from
> the in-memory buffer to Parquet files—typically every 15 minutes, but
> sometimes sooner—this ordering is not guaranteed if duplicate points are flushed
> at the same time. As a result, the last written duplicate point may not always
> be retained in storage.
Use Telegraf and the [Dedup processor plugin](/telegraf/v1/plugins/#processor-dedup)
to filter data whose field values are exact repetitions of previous values.
The following example shows how to use Telegraf to remove points that repeat field values, and then write the data to InfluxDB:
1. In your terminal, enter the following command to create the sample data file and calculate the number of seconds between the earliest timestamp and _now_.

11
content/influxdb3/clustered/admin/scale-cluster.md
View File

@ -8,9 +8,11 @@ menu:
parent: Administer InfluxDB Clustered
name: Scale your cluster
weight: 207
influxdb3/clustered/tags: [scale]
influxdb3/clustered/tags: [scale, performance, Kubernetes]
related:
- /influxdb3/clustered/reference/internals/storage-engine/
- /influxdb3/clustered/write-data/best-practices/data-lifecycle/
- /influxdb3/clustered/query-data/troubleshoot-and-optimize/optimize-queries/
- https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits, Kubernetes resource requests and limits
---
@ -559,11 +561,14 @@ concurrency demands or reaches the hardware limits of your underlying nodes.
### Compactor
- **Recommended**: Maintain **1 Compactor pod** and use [vertical scaling](#vertical-scaling) (especially
increasing the available CPU) for the Compactor.
- **Recommended**: Maintain **1 Compactor pod** and use [vertical scaling](#vertical-scaling) for the Compactor.
Scale CPU and memory resources together, as compactor concurrency settings scale based on memory, not CPU count.
- Because compaction is a compute-heavy process, horizontal scaling increases compaction throughput, but not as
efficiently as vertical scaling.
> [!Important]
> When scaling the Compactor, scale CPU and memory resources together.
### Garbage collector
The [Garbage collector](/influxdb3/clustered/reference/internals/storage-engine/#garbage-collector) is a lightweight process that typically doesn't require

194
content/influxdb3/clustered/process-data/visualize/grafana.md
View File

@ -9,7 +9,7 @@ menu:
influxdb3_clustered:
name: Use Grafana
parent: Visualize data
influxdb3/clustered/tags: [query, visualization]
influxdb3/clustered/tags: [query, visualization, Grafana]
aliases:
- /influxdb3/clustered/query-data/tools/grafana/
- /influxdb3/clustered/query-data/sql/execute-queries/grafana/
@ -20,195 +20,7 @@ alt_links:
cloud: /influxdb/cloud/tools/grafana/
core: /influxdb3/core/visualize-data/grafana/
enterprise: /influxdb3/enterprise/visualize-data/grafana/
source: /content/shared/v3-process-data/visualize/grafana.md
---
Use [Grafana](https://grafana.com/) to query and visualize data stored in
{{% product-name %}}.
> [Grafana] enables you to query, visualize, alert on, and explore your metrics,
> logs, and traces wherever they are stored.
> [Grafana] provides you with tools to turn your time-series database (TSDB)
> data into insightful graphs and visualizations.
>
> {{% cite %}}-- [Grafana documentation](https://grafana.com/docs/grafana/latest/introduction/){{% /cite %}}
- [Install Grafana or login to Grafana Cloud](#install-grafana-or-login-to-grafana-cloud)
- [InfluxDB data source](#influxdb-data-source)
- [Create an InfluxDB data source](#create-an-influxdb-data-source)
- [Query InfluxDB with Grafana](#query-influxdb-with-grafana)
- [Build visualizations with Grafana](#build-visualizations-with-grafana)
## Install Grafana or login to Grafana Cloud
If using the open source version of **Grafana**, follow the
[Grafana installation instructions](https://grafana.com/docs/grafana/latest/setup-grafana/installation/)
to install Grafana for your operating system.
If using **Grafana Cloud**, login to your Grafana Cloud instance.
## InfluxDB data source
The InfluxDB data source plugin is included in the Grafana core distribution.
Use the plugin to query and visualize data stored in {{< product-name >}} with
both InfluxQL and SQL.
> [!Note]
> #### Grafana 10.3+
>
> The instructions below are for **Grafana 10.3+** which introduced the newest
> version of the InfluxDB core plugin.
> The updated plugin includes **SQL support** for InfluxDB 3-based products such
> as {{< product-name >}}.
## Create an InfluxDB data source
1. In your Grafana user interface (UI), navigate to **Data Sources**.
2. Click **Add new data source**.
3. Search for and select the **InfluxDB** plugin.
4. Provide a name for your data source.
5. Under **Query Language**, select either **SQL** or **InfluxQL**:
{{< tabs-wrapper >}}
{{% tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------- BEGIN SQL --------------------------------->
When creating an InfluxDB data source that uses SQL to query data:
1. Under **HTTP**:
- **URL**: Provide your {{% product-name omit=" Clustered" %}} cluster URL
using the HTTPS protocol:
```
https://{{< influxdb/host >}}
```
2. Under **InfluxDB Details**:
- **Database**: Provide a default [database](/influxdb3/clustered/admin/databases/) name to query.
- **Token**: Provide a [database token](/influxdb3/clustered/admin/tokens/#database-tokens)
with read access to the databases you want to query.
3. Click **Save & test**.
{{< img-hd src="/img/influxdb3/clustered-grafana-influxdb-data-source-sql.png" alt="Grafana InfluxDB data source for InfluxDB Cloud Serverless that uses SQL" />}}
<!---------------------------------- END SQL ---------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXQL ------------------------------>
When creating an InfluxDB data source that uses InfluxQL to query data:
1. Under **HTTP**:
- **URL**: Provide your [{{% product-name %}} region URL](/influxdb3/clustered/reference/regions/)
using the HTTPS protocol:
```
https://{{< influxdb/host >}}
```
2. Under **InfluxDB Details**:
- **Database**: Provide a default [database](/influxdb3/clustered/admin/databases/) name to query.
- **User**: Provide an arbitrary string.
_This credential is ignored when querying {{% product-name %}}, but it cannot be empty._
- **Password**: Provide a [database token](/influxdb3/clustered/admin/tokens/#database-tokens)
with read access to the databases you want to query.
- **HTTP Method**: Choose one of the available HTTP request methods to use when querying data:
- **POST** ({{< req text="Recommended" >}})
- **GET**
3. Click **Save & test**.
{{< img-hd src="/img/influxdb3/clustered-grafana-influxdb-data-source-influxql.png" alt="Grafana InfluxDB data source for InfluxDB Cloud Serverless using InfluxQL" />}}
<!-------------------------------- END INFLUXQL ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## Query InfluxDB with Grafana
After you [configure and save an InfluxDB datasource](#create-a-datasource),
use Grafana to build, run, and inspect queries against your InfluxDB database.
{{< tabs-wrapper >}}
{{% tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------- BEGIN SQL --------------------------------->
> [!Note]
> {{% sql/sql-schema-intro %}}
> To learn more, see [Query Data](/influxdb3/clustered/query-data/sql/).
1. Click **Explore**.
2. In the dropdown, select the saved InfluxDB data source to query.
3. Use the SQL query form to build your query:
- **Table**: Select the measurement to query.
- **Column**: Select one or more fields and tags to return as columns in query results.
With SQL, select the `time` column to include timestamps with the data.
Grafana relies on the `time` column to correctly graph time series data.
- _**Optional:**_ Toggle **filter** to generate **WHERE** clause statements.
- **WHERE**: Configure condition expressions to include in the `WHERE` clause.
- _**Optional:**_ Toggle **group** to generate **GROUP BY** clause statements.
- **GROUP BY**: Select columns to group by.
If you include an aggregation function in the **SELECT** list,
you must group by one or more of the queried columns.
SQL returns the aggregation for each group.
- {{< req text="Recommended" color="green" >}}:
Toggle **order** to generate **ORDER BY** clause statements.
- **ORDER BY**: Select columns to sort by.
You can sort by time and multiple fields or tags.
To sort in descending order, select **DESC**.
4. {{< req text="Recommended" color="green" >}}: Change format to **Time series**.
- Use the **Format** dropdown to change the format of the query results.
For example, to visualize the query results as a time series, select **Time series**.
5. Click **Run query** to execute the query.
<!---------------------------------- END SQL ---------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN INFLUXQL ------------------------------>
1. Click **Explore**.
2. In the dropdown, select the **InfluxDB** data source that you want to query.
3. Use the InfluxQL query form to build your query:
- **FROM**: Select the measurement that you want to query.
- **WHERE**: To filter the query results, enter a conditional expression.
- **SELECT**: Select fields to query and an aggregate function to apply to each.
The aggregate function is applied to each time interval defined in the
`GROUP BY` clause.
- **GROUP BY**: By default, Grafana groups data by time to downsample results
and improve query performance.
You can also add other tags to group by.
4. Click **Run query** to execute the query.
<!-------------------------------- END INFLUXQL ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
{{< youtube "rSsouoNsNDs" >}}
To learn about query management and inspection in Grafana, see the
[Grafana Explore documentation](https://grafana.com/docs/grafana/latest/explore/).
## Build visualizations with Grafana
For a comprehensive walk-through of creating visualizations with
Grafana, see the [Grafana documentation](https://grafana.com/docs/grafana/latest/).
<!-- SOURCE: /content/shared/v3-process-data/visualize/grafana.md -->

4
content/influxdb3/clustered/reference/cli/influxctl/_index.md
View File

@ -166,8 +166,8 @@ To download the Linux `influxctl` package, do one of the following:
# Primary key fingerprint: 24C9 75CB A61A 024E E1B6 3178 7C3D 5715 9FC2 F927
# Subkey fingerprint: 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
wget -q https://repos.influxdata.com/influxdata-archive.key
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/influxdata-archive.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
```
{{% /code-tab-content %}}

17
content/influxdb3/clustered/reference/internals/durability.md Normal file
View File

@ -0,0 +1,17 @@
---
title: InfluxDB Clustered data durability
description: >
Data written to {{% product-name %}} progresses through multiple stages to ensure durability, optimized performance and storage, and efficient querying. Configuration options at each stage affect system behavior, balancing reliability and resource usage.
weight: 102
menu:
influxdb3_clustered:
name: Data durability
parent: InfluxDB internals
influxdb3/clustered/tags: [backups, internals]
related:
- https://docs.aws.amazon.com/AmazonS3/latest/userguide/DataDurability.html, AWS S3 Data Durabililty
- /influxdb3/clustered/reference/internals/storage-engine/
source: /shared/v3-distributed-internals-reference/durability.md
---
<!--// SOURCE - content/shared/v3-distributed-internals-reference/durability.md -->

4
content/influxdb3/clustered/reference/internals/security.md
View File

@ -62,7 +62,7 @@ by periodically creating, recording, and writing test data into test buckets.
The service periodically executes queries to ensure the data hasn't been lost or corrupted.
A separate instance of this service lives within each InfluxDB cluster.
Additionally, the service creates out-of-band backups in
[line protocol](https://docs.influxdata.com/influxdb/cloud/reference/syntax/line-protocol/),
[line protocol](/influxdb/cloud/reference/syntax/line-protocol/),
and ensures the backup data matches the data on disk.
## Cloud infrastructure
@ -229,7 +229,7 @@ User accounts can be created by InfluxData on the InfluxDB Clustered system via
User accounts can create database tokens with data read and/or write permissions.
API requests from custom applications require a database token with sufficient permissions.
For more information on the types of tokens and ways to create them, see
[Manage tokens](https://docs.influxdata.com/influxdb3/clustered/admin/tokens/).
[Manage tokens](/influxdb3/clustered/admin/tokens/).
### Role-based access controls (RBAC)

75
content/influxdb3/clustered/reference/release-notes/clustered.md
View File

@ -61,6 +61,36 @@ directory. This new directory contains artifacts associated with the specified r
---
## 20250814-1819052 {date="2025-08-14"}
### Quickstart
```yaml
spec:
package:
image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20250814-1819052
```
#### Release artifacts
- [app-instance-schema.json](/downloads/clustered-release-artifacts/20250814-1819052/app-instance-schema.json)
- [example-customer.yml](/downloads/clustered-release-artifacts/20250814-1819052/example-customer.yml)
- [InfluxDB Clustered README EULA July 2024.txt](/downloads/clustered-release-artifacts/InfluxDB%20Clustered%20README%20EULA%20July%202024.txt)
### Bug Fixes
- Fix incorrect service address for tokens in Clustered auth sidecar. If you were overriding the `AUTHZ_TOKEN_SVC_ADDRESS` environment variable in your `AppInstance`, you can now remove that override.
- Remove default `fallbackScrapeProtocol` environment variable for prometheus-operator.
- Update Grafana to `12.1.1` to address CVE-2025-6023 and CVE-2025-6197.
### Changes
#### Database Engine
- Update DataFusion to v48.
- Tweak compaction to reduce write amplification and querier cache churn in some circumstances.
---
## 20250721-1796368 {date="2025-07-21"}
### Quickstart
@ -187,8 +217,8 @@ spec:
- Change the default of `INFLUXDB_IOX_CREATE_CATALOG_BACKUP_INTERVAL` from `1h`
to `4h`.
- Introduce the following environment variables to help in cases where the
object store is large enough that the the garbage collector cannot keep up
when cleaning obsolete objects:
object store is large enough that the garbage collector cannot keep up when
cleaning obsolete objects:
- `INFLUXDB_IOX_GC_PRIMARY_OBJECTSTORE_PARTITIONS`
- `INFLUXDB_IOX_GC_SECONDARY_OBJECTSTORE_PARTITIONS`
@ -360,6 +390,43 @@ spec:
# ...[remaining configuration]
```
### `clustered-auth` service routes to removed `gateway` service instead of `core` service
If you have the `clusteredAuth` feature flag enabled, the `clustered-auth` service will be deployed.
The service currently routes to the recently removed `gateway` service instead of the new `core` service.
#### Temporary workaround for service routing
Until you upgrade to release `20250805-1812019`, you need to override the `clustered-auth`
service to point to the new `core` service by adding the following `env` overrides to your `AppInstance`:
```yaml
apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
metadata:
name: influxdb
namespace: influxdb
spec:
package:
image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20241024-1354148
apiVersion: influxdata.com/v1alpha1
spec:
components:
querier:
template:
containers:
clustered-auth:
env:
AUTHZ_TOKEN_SVC_ADDRESS: 'http://core:8091/'
router:
template:
containers:
clustered-auth:
env:
AUTHZ_TOKEN_SVC_ADDRESS: 'http://core:8091/'
# ...remaining configuration...
```
### Highlights
#### AppInstance image override bug fix
@ -1211,7 +1278,7 @@ We now expose a `google` object within the `objectStore` configuration, which
enables support for using Google Cloud's GCS as a backing object store for IOx
components. This supports both
[GKE workload identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
and [IAM Service Account](https://cloud.google.com/kubernetes-engine/docs/tutorials/authenticating-to-cloud-platform#step_3_create_service_account_credentials)
and [IAM Service Account](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#kubernetes-sa-to-iam)
authentication methods.
#### Support for bypassing identity provider configuration for database/token management
@ -1394,7 +1461,7 @@ This now enables the use of Azure blob storage.
The "Install InfluxDB Clustered" instructions (formerly known as "GETTING_STARTED")
are now available on the public
[InfluxDB Clustered documentation](https://docs.influxdata.com/influxdb3/clustered/install/).
[InfluxDB Clustered documentation](/influxdb3/clustered/install/).
The `example-customer.yml` (also known as `myinfluxdb.yml`) example
configuration file still lives in the release bundle alongside the `RELEASE_NOTES`.

4
content/influxdb3/clustered/reference/sql/functions/_index.md
View File

@ -14,5 +14,5 @@ source: /shared/sql-reference/functions/_index.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/_index.md
-->
// SOURCE content/shared/sql-reference/functions/_index.md
-->

2
content/influxdb3/clustered/reference/sql/functions/aggregate.md
View File

@ -15,5 +15,5 @@ source: /shared/sql-reference/functions/aggregate.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/aggregate.md
// SOURCE content/shared/sql-reference/functions/aggregate.md
-->

17
content/influxdb3/clustered/reference/sql/functions/array.md Normal file
View File

@ -0,0 +1,17 @@
---
title: SQL array functions
list_title: Array functions
description: >
Use array functions to create and operate on Arrow arrays or lists in SQL queries.
menu:
influxdb3_clustered:
name: Array
parent: sql-functions
weight: 309
source: /shared/sql-reference/functions/array.md
---
<!--
// SOURCE content/shared/sql-reference/functions/array.md
-->

3
content/influxdb3/clustered/reference/sql/functions/binary-string.md
View File

@ -14,6 +14,5 @@ source: /shared/sql-reference/functions/binary-string.md
---
<!--
The content of this page is at
// SOURCE /content/shared/sql-reference/functions/binary-string.md
// SOURCE content/shared/sql-reference/functions/binary-string.md
-->

2
content/influxdb3/clustered/reference/sql/functions/conditional.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/conditional.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/conditional.md
// SOURCE content/shared/sql-reference/functions/conditional.md
-->

5
content/influxdb3/clustered/reference/sql/functions/hashing.md
View File

@ -8,12 +8,11 @@ menu:
influxdb3_clustered:
name: Hashing
parent: sql-functions
weight: 309
weight: 313
source: /shared/sql-reference/functions/hashing.md
---
<!--
The content for this page is at
// SOURCE /content/shared/sql-reference/functions/hashing.md
// SOURCE content/shared/sql-reference/functions/hashing.md
-->

17
content/influxdb3/clustered/reference/sql/functions/map.md Normal file
View File

@ -0,0 +1,17 @@
---
title: SQL map functions
list_title: Map functions
description: >
Use map functions to create and operate on Arrow maps in SQL queries.
menu:
influxdb3_clustered:
name: Map
parent: sql-functions
weight: 310
source: /shared/sql-reference/functions/map.md
---
<!--
// SOURCE content/shared/sql-reference/functions/map.md
-->

4
content/influxdb3/clustered/reference/sql/functions/math.md
View File

@ -13,5 +13,5 @@ source: /shared/sql-reference/functions/math.md
---
<!--
The content of this page is at /content/shared/sql-reference/functions/math.md
-->
// SOURCE content/shared/sql-reference/functions/math.md
-->

Some files were not shown because too many files have changed in this diff Show More