diff --git a/.ci/Dockerfile.remark b/.ci/Dockerfile.remark index fd4f59159..93b243157 100644 --- a/.ci/Dockerfile.remark +++ b/.ci/Dockerfile.remark @@ -1,14 +1,12 @@ FROM registry.gitlab.com/pipeline-components/remark-lint:latest - WORKDIR /app/ -# Generic #RUN apk add --no-cache COPY /.ci/remark-lint /app/ # Node -ENV PATH "$PATH:/app/node_modules/.bin/" +ENV PATH="$PATH:/app/node_modules/.bin/" RUN yarn install && yarn cache clean ENV NODE_PATH=/app/node_modules/ RUN ln -nfs /app/node_modules /node_modules @@ -23,3 +21,6 @@ LABEL \ org.label-schema.name="Remark-lint" \ org.label-schema.schema-version="1.0" \ org.label-schema.url="https://pipeline-components.gitlab.io/" + +ENTRYPOINT [ "remark" ] +CMD [ "" ] diff --git a/.ci/remark-lint/.remark-lint.js b/.ci/remark-lint/.remark-lint.js new file mode 100644 index 000000000..a53718b14 --- /dev/null +++ b/.ci/remark-lint/.remark-lint.js @@ -0,0 +1,25 @@ +import remarkPresetLintConsistent from 'remark-preset-lint-consistent'; +import remarkPresetLintRecommended from 'remark-preset-lint-recommended'; +import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide'; +import remarkFrontmatter from 'remark-frontmatter'; +import remarkFrontmatterSchema from 'remark-lint-frontmatter-schema'; +import remarkNoShellDollars from 'remark-lint-no-shell-dollars'; +import remarkToc from 'remark-toc'; + +const remarkConfig = { + settings: { + bullet: '-', + plugins: [ + remarkPresetLintConsistent, + remarkPresetLintRecommended, + remarkPresetLintMarkdownStyleGuide, + remarkFrontmatter, + remarkFrontmatterSchema, + remarkNoShellDollars, + // Generate a table of contents in `## Contents` + [remarkToc, { heading: '' }], + ], + }, +}; + +export default remarkConfig; diff --git a/.ci/remark-lint/yarn.lock b/.ci/remark-lint/yarn.lock index cff3cc08f..815edb323 100644 --- a/.ci/remark-lint/yarn.lock +++ b/.ci/remark-lint/yarn.lock @@ -435,9 +435,9 @@ concat-stream@^2.0.0: typedarray "^0.0.6" cross-spawn@^7.0.0: - version "7.0.3" - resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.3.tgz#f73a85b9d5d41d045551c177e2882d4ac85728a6" - integrity sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w== + version "7.0.6" + resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.6.tgz#8a58fe78f00dcd70c370451759dfbfaf03e8ee9f" + integrity sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA== dependencies: path-key "^3.1.0" shebang-command "^2.0.0" diff --git a/.ci/vale/styles/Google/Ordinal.yml b/.ci/vale/styles/Google/Ordinal.yml index d1ac7d27e..e777601ab 100644 --- a/.ci/vale/styles/Google/Ordinal.yml +++ b/.ci/vale/styles/Google/Ordinal.yml @@ -5,3 +5,9 @@ level: error nonword: true tokens: - \d+(?:st|nd|rd|th) + - tenth + +exceptions: + - 0th + - 50th + - 90th diff --git a/.ci/vale/styles/Google/Units.yml b/.ci/vale/styles/Google/Units.yml index 024c816e1..ed07061ce 100644 --- a/.ci/vale/styles/Google/Units.yml +++ b/.ci/vale/styles/Google/Units.yml @@ -5,5 +5,5 @@ nonword: true level: error tokens: - \b\d+(?:B|kB|MB|GB|TB) -# Ignore duration literals in code blocks. - - \b(?!\`)\d+(?:ns|ms|s|min|h|d) +# Match time units, but not duration literals inside code blocks. + - \b`(\n)?\d+(ns|ms|s|min|h|d)`\b diff --git a/.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt b/.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt index e74c2be31..85497d785 100644 --- a/.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt +++ b/.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt @@ -128,6 +128,7 @@ left level like local +locf lower match max diff --git a/.ci/vale/styles/InfluxDataDocs/WordList.yml b/.ci/vale/styles/InfluxDataDocs/WordList.yml index 5582bd6ac..bebf40b6d 100644 --- a/.ci/vale/styles/InfluxDataDocs/WordList.yml +++ b/.ci/vale/styles/InfluxDataDocs/WordList.yml @@ -55,7 +55,6 @@ swap: fewer data: less data file name: filename firewalls: firewall rules - fully qualified: fully-qualified functionality: capability|feature Google account: Google Account Google accounts: Google Accounts diff --git a/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt b/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt index dae2608d1..1ebaf7d46 100644 --- a/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt +++ b/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt @@ -68,10 +68,10 @@ influx3 influxctl influxd influxdata.com -iox +(iox|IOx) keep-url lat -locf +(locf|LOCF) logicalplan noaa|NOAA npm|NPM diff --git a/.husky/_/build b/.husky/_/build index c39a53b1a..252e82dee 100755 --- a/.husky/_/build +++ b/.husky/_/build @@ -48,9 +48,6 @@ call_lefthook() elif command -v mint >/dev/null 2>&1 then mint run csjones/lefthook-plugin "$@" - elif command -v npx >/dev/null 2>&1 - then - npx lefthook "$@" else echo "Can't find lefthook in PATH" fi diff --git a/.husky/_/pre-commit b/.husky/_/pre-commit index 3fbf5f960..4855f6124 100755 --- a/.husky/_/pre-commit +++ b/.husky/_/pre-commit @@ -48,9 +48,6 @@ call_lefthook() elif command -v mint >/dev/null 2>&1 then mint run csjones/lefthook-plugin "$@" - elif command -v npx >/dev/null 2>&1 - then - npx lefthook "$@" else echo "Can't find lefthook in PATH" fi diff --git a/.husky/_/pre-push b/.husky/_/pre-push index cf59fe1cb..a0d96ef93 100755 --- a/.husky/_/pre-push +++ b/.husky/_/pre-push @@ -48,9 +48,6 @@ call_lefthook() elif command -v mint >/dev/null 2>&1 then mint run csjones/lefthook-plugin "$@" - elif command -v npx >/dev/null 2>&1 - then - npx lefthook "$@" else echo "Can't find lefthook in PATH" fi diff --git a/.husky/_/prepare-commit-msg b/.husky/_/prepare-commit-msg index e8e8dda9d..2655902bc 100755 --- a/.husky/_/prepare-commit-msg +++ b/.husky/_/prepare-commit-msg @@ -48,9 +48,6 @@ call_lefthook() elif command -v mint >/dev/null 2>&1 then mint run csjones/lefthook-plugin "$@" - elif command -v npx >/dev/null 2>&1 - then - npx lefthook "$@" else echo "Can't find lefthook in PATH" fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 031707ba1..aad3f3e96 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,6 +57,17 @@ Install [Docker](https://docs.docker.com/get-docker/) for your system. docs-v2 includes Docker configurations (`compose.yaml` and Dockerfiles) for running the Vale style linter and tests for code blocks (Shell, Bash, and Python) in Markdown files. +#### Build the test dependency image + +After you have installed Docker, run the following command to build the test +dependency image, `influxdata:docs-pytest`. +The tests defined in `compose.yaml` use the dependencies and execution +environment from this image. + +```bash +docker build -t influxdata:docs-pytest -f Dockerfile.pytest . +``` + ### Run the documentation locally (optional) To run the documentation locally, follow the instructions provided in the README. diff --git a/Dockerfile.pytest b/Dockerfile.pytest index b47718c82..d6c9e2fd2 100644 --- a/Dockerfile.pytest +++ b/Dockerfile.pytest @@ -10,8 +10,12 @@ RUN echo '393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influ RUN echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' | tee /etc/apt/sources.list.d/influxdata.list -# Install InfluxDB clients to use in tests. +# Install depedencies for clients and tests. +# - InfluxData clients to use in tests. +# - apt-utils for verification tools +# - perl for shasum (default on MacOS) RUN apt-get update && apt-get upgrade -y && apt-get install -y \ + apt-utils \ curl \ git \ gpg \ @@ -22,6 +26,7 @@ RUN apt-get update && apt-get upgrade -y && apt-get install -y \ maven \ nodejs \ npm \ + perl \ python3 \ python3-pip \ python3-venv \ @@ -52,7 +57,7 @@ COPY ./test/pytest/pytest.ini pytest.ini # Python and Pytest dependencies. COPY ./test/pytest/requirements.txt requirements.txt # Pytest fixtures. -COPY ./test/pytest/conftest.py conftest.py +COPY ./test/pytest/conftest.py conftest.py RUN pip install -Ur requirements.txt # Activate the Python virtual environment configured in the Dockerfile. @@ -70,6 +75,7 @@ RUN service influxdb start # Copy test scripts and make them executable. COPY --chmod=755 ./test/scripts/parse_yaml.sh /usr/local/bin/parse_yaml +COPY --chmod=755 ./test/scripts/get-container-info.sh /usr/local/bin/get-container-info ENTRYPOINT [ "pytest" ] diff --git a/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml b/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml index 091885223..e13b311fe 100644 --- a/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml +++ b/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml @@ -240,6 +240,83 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /ping: + get: + description: | + Reports the InfluxQL bridge querier health and the InfluxDB version of the instance. + + The response is a HTTP `204` status code to inform you the querier is available. + + For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters. + + To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write). + + This endpoint doesn't require authentication. + operationId: GetPing + responses: + '204': + description: | + Success--the querier is available. + Headers contain InfluxDB version information. + headers: + X-Influxdb-Build: + description: | + The type of InfluxDB build. + schema: + type: string + X-Influxdb-Version: + description: | + The version of InfluxDB. + schema: + type: integer + 4xx: + description: | + #### InfluxDB Cloud + - Doesn't return this error. + security: + - {} + servers: [] + summary: Get the status of the instance + tags: + - Ping + head: + description: | + Reports the InfluxQL bridge querier health and the InfluxDB version of the instance. + + The response is a HTTP `204` status code to inform you the querier is available. + + For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters. + + To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write). + + This endpoint doesn't require authentication. + + operationId: HeadPing + responses: + '204': + description: | + Success--the querier is available. + Headers contain InfluxDB version information. + headers: + X-Influxdb-Build: + description: The type of InfluxDB build. + schema: + type: string + X-Influxdb-Version: + description: | + The version of InfluxDB. + schema: + type: integer + 4xx: + description: | + #### InfluxDB Cloud + - Doesn't return this error. + security: + - {} + servers: [] + summary: Get the status of the instance + tags: + - Ping components: parameters: TraceSpan: diff --git a/api-docs/cloud-dedicated/v2/ref.yml b/api-docs/cloud-dedicated/v2/ref.yml index ddaf7fc7e..b223b244e 100644 --- a/api-docs/cloud-dedicated/v2/ref.yml +++ b/api-docs/cloud-dedicated/v2/ref.yml @@ -149,17 +149,20 @@ paths: /ping: get: description: | - Retrieves the status and InfluxDB version of the instance. + Reports the InfluxQL bridge querier health and the InfluxDB version of the instance. + + The response is a HTTP `204` status code to inform you the querier is available. - Use this endpoint to monitor uptime for the InfluxDB instance. The response - returns a HTTP `204` status code to inform you the instance is available. + For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters. + + To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write). This endpoint doesn't require authentication. operationId: GetPing responses: '204': description: | - Success. + Success--the querier is available. Headers contain InfluxDB version information. headers: X-Influxdb-Build: @@ -184,17 +187,20 @@ paths: - Ping head: description: | - Returns the status and InfluxDB version of the instance. + Reports the InfluxQL bridge querier health and the InfluxDB version of the instance. + + The response is a HTTP `204` status code to inform you the querier is available. - Use this endpoint to monitor uptime for the InfluxDB instance. The response - returns a HTTP `204` status code to inform you the instance is available. + For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters. + + To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write). This endpoint doesn't require authentication. operationId: HeadPing responses: '204': description: | - Success. + Success--the querier is available. Headers contain InfluxDB version information. headers: X-Influxdb-Build: @@ -229,9 +235,8 @@ paths: 2. If successful, attempts to [ingest data](/influxdb/cloud-dedicated/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-dedicated/write-data/troubleshoot/#review-http-status-codes). 3. Ingests or rejects data in the batch and returns one of the following HTTP status codes: - - `204 No Content`: all data in the batch is ingested - - `201 Created` (_If the cluster is configured to allow **partial writes**_): some points in the batch are ingested and queryable, and some points are rejected - - `400 Bad Request`: all data is rejected + - `204 No Content`: All data in the batch is ingested. + - `400 Bad Request`: Some (_when **partial writes** are configured for the cluster_) or all of the data has been rejected. Data that has not been rejected is ingested and queryable. The response body contains error details about [rejected points](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. @@ -656,33 +661,29 @@ paths: description: Line protocol body required: true responses: - '201': - description: | - Success ("Created"). Some points in the batch are written and queryable, and some points are rejected. The response body contains details about the [rejected points](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. - content: - application/json: - examples: - partialWriteErrorWithRejectedPoints: - summary: Partial write rejects points with syntax errors - value: - code: invalid - line: 2 - message: 'failed to parse line protocol: errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' - schema: - $ref: '#/components/schemas/LineProtocolError' '204': description: Success ("No Content"). All data in the batch is written and queryable. '400': - description: Bad Request. All data in body was rejected and not written. + description: | + Data from the batch was rejected and not written. The response body indicates if a partial write occurred or all data was rejected. + If a partial write occurred, then some points from the batch are written and queryable. + + The response body contains details about the [rejected points](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. content: application/json: examples: - rejectsAllPoints: + rejectedAllPoints: summary: Rejected all points value: code: invalid line: 2 - message: 'failed to parse line protocol: errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' + message: 'no data written, errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' + partialWriteErrorWithRejectedPoints: + summary: Partial write rejects some points + value: + code: invalid + line: 2 + message: 'partial write has occurred, errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' schema: $ref: '#/components/schemas/LineProtocolError' '401': diff --git a/api-docs/cloud-serverless/v2/ref.yml b/api-docs/cloud-serverless/v2/ref.yml index d6047bc77..4c6c01654 100644 --- a/api-docs/cloud-serverless/v2/ref.yml +++ b/api-docs/cloud-serverless/v2/ref.yml @@ -7491,9 +7491,8 @@ paths: 2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes). 3. Ingests or rejects data in the batch and returns one of the following HTTP status codes: - - `204 No Content`: all data in the batch is ingested - - `201 Created`: some points in the batch are ingested and queryable, and some points are rejected - - `400 Bad Request`: all data is rejected + - `204 No Content`: All data in the batch is ingested. + - `400 Bad Request`: Data from the batch was rejected and not written. The response body indicates if a partial write occurred. The response body contains error details about [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. @@ -7639,27 +7638,14 @@ paths: - [Best practices for optimizing writes](/influxdb/cloud-serverless/write-data/best-practices/optimize-writes/) required: true responses: - '201': - description: | - Success ("Created"). Some points in the batch are written and queryable, and some points are rejected. The response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. - content: - application/json: - examples: - partialWriteErrorWithRejectedPoints: - summary: Partial write rejects points with syntax errors - value: - code: invalid - line: 2 - message: 'failed to parse line protocol: errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' - schema: - $ref: '#/components/schemas/LineProtocolError' '204': description: Success ("No Content"). All data in the batch is written and queryable. '400': description: | - All data in the batch was rejected and not written. + Data from the batch was rejected and not written. The response body indicates if a partial write occurred or all data was rejected. + If a partial write occurred, then some points from the batch are written and queryable. - The response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points). + The response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. content: application/json: examples: @@ -7668,7 +7654,13 @@ paths: value: code: invalid line: 2 - message: 'failed to parse line protocol: errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' + message: 'no data written, errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' + partialWriteErrorWithRejectedPoints: + summary: Partial write rejects some points + value: + code: invalid + line: 2 + message: 'partial write has occurred, errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' schema: $ref: '#/components/schemas/LineProtocolError' '401': @@ -7704,14 +7696,7 @@ paths: The request payload is too large. InfluxDB rejected the batch and did not write any data. - InfluxDB returns this error if the payload exceeds the 50MB size limit. - '422': - description: | - Unprocessable Entity. - - The request contained data outside the bucket's retention period. InfluxDB rejected the batch and wrote no data. - - The response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points). + InfluxDB returns this error if the payload exceeds the 50MB size limit or all data is outside the retention window. '429': description: | Too many requests. diff --git a/api-docs/clustered/v2/ref.yml b/api-docs/clustered/v2/ref.yml index 239859457..b617a7103 100644 --- a/api-docs/clustered/v2/ref.yml +++ b/api-docs/clustered/v2/ref.yml @@ -646,17 +646,33 @@ paths: '204': description: Write data is correctly formatted and accepted for writing to the database. '400': + description: | + Data from the batch was rejected and not written. The response body indicates if a partial write occurred or all data was rejected. + If a partial write occurred, then some points from the batch are written and queryable. + The response body contains details about the [rejected points](/influxdb/clustered/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points. content: application/json: + examples: + rejectedAllPoints: + summary: Rejected all points + value: + code: invalid + line: 2 + message: 'no data written, errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' + partialWriteErrorWithRejectedPoints: + summary: Partial write rejects some points + value: + code: invalid + line: 2 + message: 'partial write has occurred, errors encountered on line(s): error message for first rejected point error message for second rejected point error message for Nth rejected point (up to 100 rejected points)' schema: $ref: '#/components/schemas/LineProtocolError' - description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. '401': content: application/json: schema: $ref: '#/components/schemas/Error' - description: Token doesn't have sufficient permissions to write to this database or the database doesn't exist. + description: Token doesn't have sufficient permissions to write to this database or the database doesn't exist. '403': content: application/json: diff --git a/assets/js/js.cookie.js b/assets/js/js.cookie.js deleted file mode 100644 index 9a0945ed8..000000000 --- a/assets/js/js.cookie.js +++ /dev/null @@ -1,165 +0,0 @@ -/*! - * JavaScript Cookie v2.2.0 - * https://github.com/js-cookie/js-cookie - * - * Copyright 2006, 2015 Klaus Hartl & Fagner Brack - * Released under the MIT license - */ -;(function (factory) { - var registeredInModuleLoader = false; - if (typeof define === 'function' && define.amd) { - define(factory); - registeredInModuleLoader = true; - } - if (typeof exports === 'object') { - module.exports = factory(); - registeredInModuleLoader = true; - } - if (!registeredInModuleLoader) { - var OldCookies = window.Cookies; - var api = window.Cookies = factory(); - api.noConflict = function () { - window.Cookies = OldCookies; - return api; - }; - } -}(function () { - function extend () { - var i = 0; - var result = {}; - for (; i < arguments.length; i++) { - var attributes = arguments[ i ]; - for (var key in attributes) { - result[key] = attributes[key]; - } - } - return result; - } - - function init (converter) { - function api (key, value, attributes) { - var result; - if (typeof document === 'undefined') { - return; - } - - // Write - - if (arguments.length > 1) { - attributes = extend({ - path: '/' - }, api.defaults, attributes); - - if (typeof attributes.expires === 'number') { - var expires = new Date(); - expires.setMilliseconds(expires.getMilliseconds() + attributes.expires * 864e+5); - attributes.expires = expires; - } - - // We're using "expires" because "max-age" is not supported by IE - attributes.expires = attributes.expires ? attributes.expires.toUTCString() : ''; - - try { - result = JSON.stringify(value); - if (/^[\{\[]/.test(result)) { - value = result; - } - } catch (e) {} - - if (!converter.write) { - value = encodeURIComponent(String(value)) - .replace(/%(23|24|26|2B|3A|3C|3E|3D|2F|3F|40|5B|5D|5E|60|7B|7D|7C)/g, decodeURIComponent); - } else { - value = converter.write(value, key); - } - - key = encodeURIComponent(String(key)); - key = key.replace(/%(23|24|26|2B|5E|60|7C)/g, decodeURIComponent); - key = key.replace(/[\(\)]/g, escape); - - var stringifiedAttributes = ''; - - for (var attributeName in attributes) { - if (!attributes[attributeName]) { - continue; - } - stringifiedAttributes += '; ' + attributeName; - if (attributes[attributeName] === true) { - continue; - } - stringifiedAttributes += '=' + attributes[attributeName]; - } - return (document.cookie = key + '=' + value + stringifiedAttributes); - } - - // Read - - if (!key) { - result = {}; - } - - // To prevent the for loop in the first place assign an empty array - // in case there are no cookies at all. Also prevents odd result when - // calling "get()" - var cookies = document.cookie ? document.cookie.split('; ') : []; - var rdecode = /(%[0-9A-Z]{2})+/g; - var i = 0; - - for (; i < cookies.length; i++) { - var parts = cookies[i].split('='); - var cookie = parts.slice(1).join('='); - - if (!this.json && cookie.charAt(0) === '"') { - cookie = cookie.slice(1, -1); - } - - try { - var name = parts[0].replace(rdecode, decodeURIComponent); - cookie = converter.read ? - converter.read(cookie, name) : converter(cookie, name) || - cookie.replace(rdecode, decodeURIComponent); - - if (this.json) { - try { - cookie = JSON.parse(cookie); - } catch (e) {} - } - - if (key === name) { - result = cookie; - break; - } - - if (!key) { - result[name] = cookie; - } - } catch (e) {} - } - - return result; - } - - api.set = api; - api.get = function (key) { - return api.call(api, key); - }; - api.getJSON = function () { - return api.apply({ - json: true - }, [].slice.call(arguments)); - }; - api.defaults = {}; - - api.remove = function (key, attributes) { - api(key, '', extend(attributes, { - expires: -1 - })); - }; - - api.withConverter = init; - - return api; - } - - return init(function () {}); -})); diff --git a/assets/js/cookies.js b/assets/js/local-storage.js similarity index 58% rename from assets/js/cookies.js rename to assets/js/local-storage.js index 456794183..ea01f114a 100644 --- a/assets/js/cookies.js +++ b/assets/js/local-storage.js @@ -1,46 +1,41 @@ /* - This represents an API for managing cookies for the InfluxData documentation. - It uses the Cookies.js library to store data as session cookies. - This is done to comply with cookie privacy laws and limit the cookies used - to manage the user experience throughout the InfluxData documentation. - - These functions manage the following InfluxDB cookies + This represents an API for managing user and client-side settings for the + InfluxData documentation. It uses the local browser storage. + + These functions manage the following InfluxDB settings: - influxdata_docs_preferences: Docs UI/UX-related preferences (obj) - influxdata_docs_urls: User-defined InfluxDB URLs for each product (obj) - influxdata_docs_notifications: - messages: Messages (data/notifications.yaml) that have been seen (array) - callouts: Feature callouts that have been seen (array) - - influxdata_docs_ported: Temporary cookie to help port old cookies to new structure */ -// Prefix for all InfluxData docs cookies -const cookiePrefix = 'influxdata_docs_'; +// Prefix for all InfluxData docs local storage +const storagePrefix = 'influxdata_docs_'; /* - Initialize a cookie with a default value. + Initialize data in local storage with a default value. */ -initializeCookie = (cookieName, defaultValue) => { - fullCookieName = cookiePrefix + cookieName; +initializeLocalStorage = (storageKey, defaultValue) => { + fullStorageKey = storagePrefix + storageKey; - // Check if the cookie exists before initializing the cookie - if (Cookies.get(fullCookieName) === undefined) { - Cookies.set(fullCookieName, defaultValue); + // Check if the data exists before initializing the data + if (localStorage.getItem(fullStorageKey) === null) { + localStorage.setItem(fullStorageKey, defaultValue); } }; -// Initialize all InfluxData docs cookies with defaults - /* //////////////////////////////////////////////////////////////////////////////// ////////////////////////// INFLUXDATA DOCS PREFERENCES ///////////////////////// //////////////////////////////////////////////////////////////////////////////// */ -const prefCookieName = cookiePrefix + 'preferences'; +const prefStorageKey = storagePrefix + 'preferences'; // Default preferences -var defaultPref = { +var defaultPrefObj = { api_lib: null, influxdb_url: 'cloud', sidebar_state: 'open', @@ -50,35 +45,35 @@ var defaultPref = { }; /* - Retrieve a preference from the preference cookie. - If the cookie doesn't exist, initialize it with default values. + Retrieve a preference from the preference key. + If the key doesn't exist, initialize it with default values. */ getPreference = prefName => { - // Initialize the preference cookie if it doesn't already exist - if (Cookies.get(prefCookieName) === undefined) { - initializeCookie('preferences', defaultPref); + // Initialize preference data if it doesn't already exist + if (localStorage.getItem(prefStorageKey) === null) { + initializeLocalStorage('preferences', JSON.stringify(defaultPrefObj)); } - // Retrieve and parse the cookie as JSON - prefString = Cookies.get(prefCookieName); + // Retrieve and parse preferences as JSON + prefString = localStorage.getItem(prefStorageKey); prefObj = JSON.parse(prefString); // Return the value of the specified preference return prefObj[prefName]; }; -// Set a preference in the preferences cookie +// Set a preference in the preferences key setPreference = (prefID, prefValue) => { - var prefString = Cookies.get(prefCookieName); + var prefString = localStorage.getItem(prefStorageKey); let prefObj = JSON.parse(prefString); prefObj[prefID] = prefValue; - Cookies.set(prefCookieName, prefObj); + localStorage.setItem(prefStorageKey, JSON.stringify(prefObj)); }; // Return an object containing all preferences -getPreferences = () => JSON.parse(Cookies.get(prefCookieName)); +getPreferences = () => JSON.parse(localStorage.getItem(prefStorageKey)); /* //////////////////////////////////////////////////////////////////////////////// @@ -86,7 +81,7 @@ getPreferences = () => JSON.parse(Cookies.get(prefCookieName)); //////////////////////////////////////////////////////////////////////////////// */ -const urlCookieName = cookiePrefix + 'urls'; +const urlStorageKey = storagePrefix + 'urls'; // Default URLs per product var defaultUrls = { @@ -97,8 +92,8 @@ var defaultUrls = { clustered: 'cluster-host.com', }; -// Defines the default urls cookie value -var defaultUrlsCookie = { +// Defines the default urls value +var defaultUrlsObj = { oss: defaultUrls.oss, cloud: defaultUrls.cloud, serverless: defaultUrls.serverless, @@ -112,25 +107,25 @@ var defaultUrlsCookie = { custom: '', }; -// Return an object that contains all InfluxDB urls stored in the urls cookie +// Return an object that contains all InfluxDB urls stored in the urls key getInfluxDBUrls = () => { - // Initialize the urls cookie if it doesn't already exist - if (Cookies.get(urlCookieName) === undefined) { - initializeCookie('urls', defaultUrlsCookie); + // Initialize urls data if it doesn't already exist + if (localStorage.getItem(urlStorageKey) === null) { + initializeLocalStorage('urls', JSON.stringify(defaultUrlsObj)); } - return JSON.parse(Cookies.get(urlCookieName)); + return JSON.parse(localStorage.getItem(urlStorageKey)); }; // Get the current or previous URL for a specific product or a custom url getInfluxDBUrl = product => { - // Initialize the urls cookie if it doesn't already exist - if (Cookies.get(urlCookieName) === undefined) { - initializeCookie('urls', defaultUrlsCookie); + // Initialize urls data if it doesn't already exist + if (localStorage.getItem(urlStorageKey) === null) { + initializeLocalStorage('urls', JSON.stringify(defaultUrlsObj)); } - // Retrieve and parse the cookie as JSON - urlsString = Cookies.get(urlCookieName); + // Retrieve and parse the URLs as JSON + urlsString = localStorage.getItem(urlStorageKey); urlsObj = JSON.parse(urlsString); // Return the URL of the specified product @@ -138,27 +133,27 @@ getInfluxDBUrl = product => { }; /* - Set multiple product URLs in the urls cookie. + Set multiple product URLs in the urls key. Input should be an object where the key is the product and the value is the URL to set for that product. */ setInfluxDBUrls = updatedUrlsObj => { - var urlsString = Cookies.get(urlCookieName); + var urlsString = localStorage.getItem(urlStorageKey); let urlsObj = JSON.parse(urlsString); newUrlsObj = { ...urlsObj, ...updatedUrlsObj }; - Cookies.set(urlCookieName, newUrlsObj); + localStorage.setItem(urlStorageKey, JSON.stringify(newUrlsObj)); }; -// Set an InfluxDB URL to an empty string in the urls cookie +// Set an InfluxDB URL to an empty string in the urls key removeInfluxDBUrl = product => { - var urlsString = Cookies.get(urlCookieName); + var urlsString = localStorage.getItem(urlStorageKey); let urlsObj = JSON.parse(urlsString); urlsObj[product] = ''; - Cookies.set(urlCookieName, urlsObj); + localStorage.setItem(urlStorageKey, JSON.stringify(urlsObj)); }; /* @@ -167,25 +162,25 @@ removeInfluxDBUrl = product => { //////////////////////////////////////////////////////////////////////////////// */ -const notificationCookieName = cookiePrefix + 'notifications'; +const notificationStorageKey = storagePrefix + 'notifications'; // Default notifications -var defaultNotifications = { +var defaultNotificationsObj = { messages: [], callouts: [], }; getNotifications = () => { - // Initialize the notifications cookie if it doesn't already exist - if (Cookies.get(notificationCookieName) === undefined) { - initializeCookie('notifications', defaultNotifications); + // Initialize notifications data if it doesn't already exist + if (localStorage.getItem(notificationStorageKey) === null) { + initializeLocalStorage('notifications', JSON.stringify(defaultNotificationsObj)); } - // Retrieve and parse the cookie as JSON - notificationString = Cookies.get(notificationCookieName); + // Retrieve and parse the notifications data as JSON + notificationString = localStorage.getItem(notificationStorageKey); notificationObj = JSON.parse(notificationString); - // Return the value of the specified preference + // Return the notifications object return notificationObj; }; @@ -222,5 +217,5 @@ setNotificationAsRead = (notificationID, notificationType) => { readNotifications.push(notificationID); notificationsObj[notificationType + 's'] = readNotifications; - Cookies.set(notificationCookieName, notificationsObj); + localStorage.setItem(notificationStorageKey, JSON.stringify(notificationsObj)); }; diff --git a/assets/js/release-toc.js b/assets/js/release-toc.js new file mode 100644 index 000000000..42858fccc --- /dev/null +++ b/assets/js/release-toc.js @@ -0,0 +1,58 @@ +/////////////////////////// Table of Contents Script /////////////////////////// + +/* + * This script is used to generate a table of contents for the + * release notes pages. +*/ + +// Use jQuery filter to get an array of all the *release* h2 elements +const releases = $('h2').filter( + (_i, el) => !el.id.match(/checkpoint-releases/) +); + +// Extract data about each release from the array of releases +releaseData = releases.map((_i, el) => ({ + name: el.textContent, + id: el.id, + class: el.getAttribute('class'), + date: el.getAttribute('date') +})); + +// Use release data to generate a list item for each release +getReleaseItem = (releaseData) => { + var li = document.createElement("li"); + if (releaseData.class !== null) { + li.className = releaseData.class; + } + li.innerHTML = `${releaseData.name}`; + li.setAttribute('date', releaseData.date); + return li; +} + +// Use jQuery each to build the release table of contents +releaseData.each((_i, release) => { + $('#release-toc ul')[0].appendChild(getReleaseItem(release)); +}); + +/* + * This script is used to expand the release notes table of contents by the + * number specified in the `show` attribute of `ul.release-list`. + * Once all the release items are visible, the "Show More" button is hidden. +*/ +$('#release-toc .show-more').click(function () { + const itemHeight = 1.885; // Item height in rem + const releaseNum = releaseData.length; + const maxHeight = releaseNum * itemHeight; + const releaseIncrement = Number($('#release-list')[0].getAttribute('show')); + const currentHeight = Number( + $('#release-list')[0].style.height.match(/\d+\.?\d+/)[0] + ); + const potentialHeight = currentHeight + releaseIncrement * itemHeight; + const newHeight = potentialHeight > maxHeight ? maxHeight : potentialHeight; + + $('#release-list')[0].style.height = `${newHeight}rem`; + + if (newHeight >= maxHeight) { + $('#release-toc .show-more').fadeOut(100); + } +}); diff --git a/assets/js/v3-wayfinding.js b/assets/js/v3-wayfinding.js index 2d09a5146..5761fc101 100644 --- a/assets/js/v3-wayfinding.js +++ b/assets/js/v3-wayfinding.js @@ -1,5 +1,5 @@ // Store the host value for the current page -currentPageHost = window.location.href.match(/^(?:[^\/]*\/){2}[^\/]+/g)[0]; +const currentPageHost = window.location.href.match(/^(?:[^\/]*\/){2}[^\/]+/g)[0]; // Define v3-wayfinding elements var wayfindingModal = document.getElementById('v3-wayfinding-modal'); @@ -55,6 +55,9 @@ function slideUp (elem) { * - Has the user opted out of the wayfinding modal? */ function shouldOpenWayfinding () { + // Extract the protocol and hostname of referrer + const referrerMatch = document.referrer.match(/^(?:[^\/]*\/){2}[^\/]+/g); + const referrerHost = referrerMatch ? referrerMatch[0] : ''; var isExternalReferrer = !referrerWhitelist.includes(referrerHost); var wayfindingOptedOut = getPreference(wayfindingPrefCookie); diff --git a/assets/styles/layouts/_article.scss b/assets/styles/layouts/_article.scss index e2a23703c..360c3266c 100644 --- a/assets/styles/layouts/_article.scss +++ b/assets/styles/layouts/_article.scss @@ -56,6 +56,16 @@ color: $r-dreamsicle; } + &.checkpoint::before { + content: '\e93b'; + font-family: 'icomoon-v4'; + font-size: 2.25rem; + color: $br-new-magenta; + display: inline; + margin: 0 .5rem 0 0; + vertical-align: top; + } + &[metadata]::after { content: attr(metadata); margin-left: .65rem; @@ -185,9 +195,7 @@ "article/children", "article/code", "article/columns", - "article/cloud", "article/diagrams", - "article/enterprise", "article/expand", "article/feedback", "article/flex", @@ -198,11 +206,10 @@ "article/keybinding", "article/list-filters", "article/lists", - "article/note", "article/opacity", "article/pagination-btns", - "article/product-tags", "article/related", + "article/release-toc", "article/scrollbars", "article/svgs", "article/tabbed-content", @@ -211,8 +218,7 @@ "article/telegraf-plugins", "article/title", "article/truncate", - "article/video", - "article/warn"; + "article/video"; //////////////////////////////// Miscellaneous /////////////////////////////// @@ -307,6 +313,10 @@ &.magenta { color: $p-comet; } + + &.pink { + color: $br-new-magenta; + } } /////////////////////////// Getting Started Buttons ////////////////////////// diff --git a/assets/styles/layouts/_notifications.scss b/assets/styles/layouts/_notifications.scss index e549c754d..00034186a 100644 --- a/assets/styles/layouts/_notifications.scss +++ b/assets/styles/layouts/_notifications.scss @@ -139,6 +139,12 @@ code { background: transparent !important; } } + hr { + border-width: 1px 0 0 0; + border-style: dotted; + border-color: rgba($g20-white, .5); + } + &.min { .notification-title {h3 {font-size: 1.15rem;}} .notification-content { diff --git a/assets/styles/layouts/_syntax-highlighting.scss b/assets/styles/layouts/_syntax-highlighting.scss index 0e43f6b13..a1b96bfdf 100644 --- a/assets/styles/layouts/_syntax-highlighting.scss +++ b/assets/styles/layouts/_syntax-highlighting.scss @@ -183,78 +183,3 @@ pre[class*="language-"] { .mi + .n { color: $article-code-accent5; } } } - -.note { - .highlight { - color: $article-note-code; - - .gh,.go,.na,.nt,.nv,.ow - { color: $article-note-code } - .c,.ch,.cm,.cpf,.c1, .cs,.w - { color: $article-note-code-accent1; } - .gi - { background-color: $article-note-code-accent1; } - .k,.kc,.kd,.kn,.kp,.kr,.nn - { color: $article-note-code-accent2; } - .bp,.cp,.dl,.gt,.gu,.kt,.nb,.nc,.no,.sa,.sb,.sc,.sd,.se,.sh,.sx,.sr,.s1,.s2 - { color: $article-note-code-accent3 } - .err,.fm,.gr,.gd,.nd,.ne,.nf,.nl,.si - { color: $article-note-code-accent4 } - .m,.ni,.mb,.mf,.mh,.mi,.mo,.vc,.vg,.vi,.vm,.il - { color: $article-note-code-accent5 } - .gp,.o - { color: $article-note-code-accent6 } - .ss - { color: $article-note-code-accent7 } - } -} - -.warn { - .highlight { - color: $article-warn-code; - - .gh,.go,.na,.nt,.nv,.ow - { color: $article-warn-code } - .c,.ch,.cm,.cpf,.c1, .cs,.w - { color: $article-warn-code-accent1; } - .gi - { background-color: $article-warn-code-accent1; } - .k,.kc,.kd,.kn,.kp,.kr,.nn - { color: $article-warn-code-accent2; } - .bp,.cp,.dl,.gt,.gu,.kt,.nb,.nc,.no,.sa,.sb,.sc,.sd,.se,.sh,.sx,.sr,.s1,.s2 - { color: $article-warn-code-accent3 } - .err,.fm,.gr,.gd,.nd,.ne,.nf,.nl,.si - { color: $article-warn-code-accent4 } - .m,.ni,.mb,.mf,.mh,.mi,.mo,.vc,.vg,.vi,.vm,.il - { color: $article-warn-code-accent5 } - .gp,.o - { color: $article-warn-code-accent6 } - .ss - { color: $article-warn-code-accent7 } - } -} - -.cloud-msg { - .highlight { - color: $article-cloud-code; - - .gh,.go,.na,.nt,.nv,.ow - { color: $article-cloud-code } - .c,.ch,.cm,.cpf,.c1, .cs,.w - { color: $article-cloud-code-accent1; } - .gi - { background-color: $article-cloud-code-accent1; } - .k,.kc,.kd,.kn,.kp,.kr,.nn - { color: $article-cloud-code-accent2; } - .bp,.cp,.dl,.gt,.gu,.kt,.nb,.nc,.no,.sa,.sb,.sc,.sd,.se,.sh,.sx,.sr,.s1,.s2 - { color: $article-cloud-code-accent3 } - .err,.fm,.gr,.gd,.nd,.ne,.nf,.nl,.si - { color: $article-cloud-code-accent4 } - .m,.ni,.mb,.mf,.mh,.mi,.mo,.vc,.vg,.vi,.vm,.il - { color: $article-cloud-code-accent5 } - .gp,.o - { color: $article-cloud-code-accent6 } - .ss - { color: $article-cloud-code-accent7 } - } -} diff --git a/assets/styles/layouts/article/_blocks.scss b/assets/styles/layouts/article/_blocks.scss index 899835442..090ee9560 100644 --- a/assets/styles/layouts/article/_blocks.scss +++ b/assets/styles/layouts/article/_blocks.scss @@ -1,4 +1,4 @@ -////////////////// Blockquotes, Notes, Warnings, & Messages ////////////////// +///////////////////////// Blockquotes and Alert Blocks ///////////////////////// blockquote, .block, { @@ -20,8 +20,40 @@ blockquote, & > h6 { &:first-child {margin-top: 0; padding-top: 0.25em;} } + + &.note, + &.tip, + &.important, + &.warning, &.warn, + &.caution { + position: relative; + &:before { + position: absolute; + font-family: "alert-icons"; + font-size: 1em; + line-height: 1em; + padding: .3rem; + text-align: center; + top: -.5rem; + left: -.95rem; + display: block; + border-radius: 50%; + box-shadow: 1px 3px 5px rgba($article-shadow, .5); + } + } } +h2, h3, h4, h5, h6 { + & + .note, + & + .tip, + & + .important, + & + .warning, + & + .caution { + margin-top: 1.25rem; + } +} + + blockquote { padding: 1rem 1rem 1rem 1.25rem; border-color: rgba($article-text, .25); @@ -59,3 +91,9 @@ blockquote { margin: .5rem 0 1rem; } } + +@import "blocks/note", + "blocks/tip", + "blocks/important", + "blocks/warning", + "blocks/caution"; diff --git a/assets/styles/layouts/article/_buttons.scss b/assets/styles/layouts/article/_buttons.scss index 6807ed616..d05d41265 100644 --- a/assets/styles/layouts/article/_buttons.scss +++ b/assets/styles/layouts/article/_buttons.scss @@ -48,6 +48,14 @@ a.btn { font-size: 1.1rem; } + &.arrow span.CaretOutlineRight { + font-size: 1.5rem; + line-height: 0; + vertical-align: sub; + display: inline-block; + margin-right: -.65rem; + } + &.small-plus { padding: .25em; line-height: .65rem; diff --git a/assets/styles/layouts/article/_captions.scss b/assets/styles/layouts/article/_captions.scss index 20dfc3976..295550a9e 100644 --- a/assets/styles/layouts/article/_captions.scss +++ b/assets/styles/layouts/article/_captions.scss @@ -11,7 +11,7 @@ code { font-size: .9rem; } } -p, li { +p, li, ol, ul { & + .caption { padding: 0; margin: -.75rem 0 0; diff --git a/assets/styles/layouts/article/_cloud.scss b/assets/styles/layouts/article/_cloud.scss deleted file mode 100644 index 9bc8a4abe..000000000 --- a/assets/styles/layouts/article/_cloud.scss +++ /dev/null @@ -1,69 +0,0 @@ -.cloud { - border-color: $article-cloud-base; - background: rgba($article-cloud-base, .12); - h1,h2,h3,h4,h5,h6 { - color: $article-cloud-heading; - } - p,li { - color: $article-cloud-text; - } - strong { - color: inherit; - } - a { - color: $article-cloud-link; - code:after { - border-color: transparent rgba($article-cloud-code, .35) transparent transparent; - } - &:hover { - color: $article-cloud-link-hover; - code:after { - border-color: transparent $article-cloud-link-hover transparent transparent; - } - } - } - ol li:before { - color: $article-cloud-text; - } - code, pre{ - color: $article-cloud-code; - background: $article-cloud-code-bg; - } - img { - box-shadow: 1px 3px 10px $article-cloud-shadow; - } - table{ - color: $article-cloud-text; - box-shadow: 1px 3px 10px $article-cloud-shadow; - thead{ - @include gradient($article-cloud-table-header); - } - tr:nth-child(even) td { - background: $article-cloud-table-row-alt; - } - } - blockquote { - border-color: rgba($article-cloud-text, .25); - p { color: rgba($article-cloud-text, .6); } - } - .code-tabs-wrapper .code-tabs a { - background: transparent; - color: rgba($article-cloud-text, .5); - &:hover { color: rgba($article-cloud-text, 1); } - &.is-active { - color: rgba($article-cloud-text, 1); - background: $article-cloud-code-bg}; - } - - &.flex { - font-style: italic; - display: flex; - div:first-child { - position: relative; - margin: .25rem 2rem 0 0; - } - } - hr, .expand { - border-color: rgba($article-cloud-base, .4) - } -} diff --git a/assets/styles/layouts/article/_code.scss b/assets/styles/layouts/article/_code.scss index b9e9572bc..4d24a7f01 100644 --- a/assets/styles/layouts/article/_code.scss +++ b/assets/styles/layouts/article/_code.scss @@ -84,6 +84,7 @@ span.code-callout, .code-placeholder { &.green {color: $article-code-accent3;} &.magenta {color: $br-new-magenta;} &.orange {color: $r-curacao;} + &.delete, &.strike {text-decoration: line-through;} } /////////////// Styles for code placeholders that can be updated /////////////// @@ -157,7 +158,7 @@ span.code-callout, .code-placeholder { } } } -.code-placeholder-key code {color: $code-placeholder} +.code-placeholder-key code {color: $code-placeholder !important} //////////////////////////////////////////////////////////////////////////////// diff --git a/assets/styles/layouts/article/_enterprise.scss b/assets/styles/layouts/article/_enterprise.scss deleted file mode 100644 index 39d9ae5d5..000000000 --- a/assets/styles/layouts/article/_enterprise.scss +++ /dev/null @@ -1,19 +0,0 @@ -.enterprise { - border-color: $article-enterprise-base; - background: rgba($article-enterprise-base, .15); - p,li { - color: $article-enterprise-text; - } - a { - color: $article-enterprise-link; - &:hover { color: $article-enterprise-link-hover; } - } - &.flex { - font-style: italic; - display: flex; - div:first-child { - position: relative; - margin: .25rem 2rem 0 0; - } - } -} diff --git a/assets/styles/layouts/article/_note.scss b/assets/styles/layouts/article/_note.scss deleted file mode 100644 index d11522b61..000000000 --- a/assets/styles/layouts/article/_note.scss +++ /dev/null @@ -1,60 +0,0 @@ -.note { - border-color: $article-note-base; - background: rgba($article-note-base, .1); - h1,h2,h3,h4,h5,h6 { - color: $article-note-heading; - } - p, li { - color: $article-note-text; - } - strong { - color: $article-note-strong; - } - a { - color: $article-note-link; - code:after { - border-color: transparent rgba($article-note-code, .35) transparent transparent; - } - &:hover { - color: $article-note-link-hover; - code:after { - border-color: transparent $article-note-link-hover transparent transparent; - } - } - } - ol li:before { - color: $article-note-text; - } - code, pre{ - color: $article-note-code; - background: $article-note-code-bg; - } - img { - box-shadow: 1px 3px 10px $article-note-shadow; - } - table{ - color: $article-note-text; - box-shadow: 1px 3px 10px $article-note-shadow; - thead{ - @include gradient($article-note-table-header); - } - tr:nth-child(even) td { - background: $article-note-table-row-alt; - } - } - blockquote { - border-color: rgba($article-note-text, .25); - p { color: rgba($article-note-text, .6); } - } - .code-tabs-wrapper .code-tabs a { - background: transparent; - color: rgba($article-note-text, .5); - &:hover { color: rgba($article-note-text, 1); } - &.is-active { - color: rgba($article-note-text, 1); - background: $article-note-code-bg}; - } - hr, .expand { - border-color: rgba($article-note-base, .4) - } -} diff --git a/assets/styles/layouts/article/_product-tags.scss b/assets/styles/layouts/article/_product-tags.scss deleted file mode 100644 index a2f757aba..000000000 --- a/assets/styles/layouts/article/_product-tags.scss +++ /dev/null @@ -1,28 +0,0 @@ -.product-tags { - margin: -2rem 0 2.5rem; - span { - margin-right: .25rem; - padding: .2rem .65rem .25rem; - border-radius: 1rem; - font-weight: $medium; - font-style: italic; - font-size: .85rem; - border: 1px solid; - - &.oss { - color: $product-oss; - border-color: rgba($product-oss, .35); - background: rgba($product-oss, .1); - } - &.cloud { - color: $product-cloud; - border-color: rgba($product-cloud, .35); - background: rgba($product-cloud, .1); - } - &.enterprise { - color: $product-enterprise; - border-color: rgba($product-enterprise, .35); - background: rgba($product-enterprise, .1); - } - } -} diff --git a/assets/styles/layouts/article/_release-toc.scss b/assets/styles/layouts/article/_release-toc.scss new file mode 100644 index 000000000..e30c158c2 --- /dev/null +++ b/assets/styles/layouts/article/_release-toc.scss @@ -0,0 +1,68 @@ +#release-toc { + margin: 2rem 0 3rem; + + ul { + list-style: none; + overflow: hidden; + padding-left: 0; + margin-bottom: .75rem; + transition: height .2s; + + li { + line-height: 1.2em; + margin: .5rem 0; + + &::after { + content: attr(date); + font-size: 1rem; + margin-left: .5rem; + color: rgba($article-text, .5); + } + } + } + + &.clustered { + ul { + padding-left: 1.5rem; + + .checkpoint { + margin-left: -1.5rem; + + &::before { + content: '\e93b' !important; + font-family: 'icomoon-v4'; + color: $br-new-magenta; + display: inline-block; + margin: 0 .5rem 0 0; + vertical-align: top; + } + } + } + } + + .show-more { + color: $article-link; + transition: color .2s; + font-weight: $medium; + font-size: 1rem; + + &::before { + content: '\e935'; + font-family: 'icomoon-v4'; + font-size: .9rem; + color: $article-bg; + background: $article-link; + border-radius: 50%; + margin-right: .5rem; + transition: background .15s; + } + + &:hover { + cursor: pointer; + color: $article-link-hover; + &::before { + background: $article-link-hover; + } + } + } +} diff --git a/assets/styles/layouts/article/_scrollbars.scss b/assets/styles/layouts/article/_scrollbars.scss index 12fd8cf0e..2a8fca07e 100644 --- a/assets/styles/layouts/article/_scrollbars.scss +++ b/assets/styles/layouts/article/_scrollbars.scss @@ -3,15 +3,3 @@ pre { @include scrollbar($article-code-bg, $article-code-scrollbar); } table { @include scrollbar($article-table-row-alt, $article-table-scrollbar);} -.note { - pre { @include scrollbar($article-note-code-bg, $article-note-code-scrollbar); } - table { @include scrollbar($article-note-table-row-alt, $article-note-table-scrollbar); } -} -.warn { - pre { @include scrollbar($article-warn-code-bg, $article-warn-code-scrollbar); } - table { @include scrollbar($article-warn-table-row-alt, $article-warn-table-scrollbar); } -} -.cloud { - pre { @include scrollbar($article-cloud-code-bg, $article-cloud-code-scrollbar); } - table { @include scrollbar($article-cloud-table-row-alt, $article-cloud-table-scrollbar); } -} diff --git a/assets/styles/layouts/article/_title.scss b/assets/styles/layouts/article/_title.scss index f6f10a252..19ef644bb 100644 --- a/assets/styles/layouts/article/_title.scss +++ b/assets/styles/layouts/article/_title.scss @@ -10,12 +10,13 @@ li { margin-bottom: 0; - padding: 0 .65em 0 .75em; + padding: .45em .75em; color: $article-heading; background: rgba($article-heading, .07); font-size: .95rem; font-weight: $medium; - border-radius: 1em; + line-height: 1.1rem; + border-radius: 1.1em; display: inline-block; &.updated-in, diff --git a/assets/styles/layouts/article/_warn.scss b/assets/styles/layouts/article/_warn.scss deleted file mode 100644 index e271cf8a8..000000000 --- a/assets/styles/layouts/article/_warn.scss +++ /dev/null @@ -1,60 +0,0 @@ -.warn { - border-color: $article-warn-base; - background: $article-warn-bg; - h1,h2,h3,h4,h5,h6 { - color: $article-warn-heading; - } - p, li { - color: $article-warn-text; - } - strong { - color: inherit; - } - a { - color: $article-warn-link !important; - code:after { - border-color: transparent rgba($article-warn-code, .35) transparent transparent; - } - &:hover { - color: $article-warn-link-hover !important; - code:after { - border-color: transparent $article-warn-link-hover transparent transparent; - } - } - } - ol li:before { - color: $article-warn-text; - } - code, pre{ - color: $article-warn-code; - background: $article-warn-code-bg; - } - img { - box-shadow: 1px 3px 10px $article-warn-shadow; - } - table{ - color: $article-warn-text; - box-shadow: 1px 3px 10px $article-warn-shadow; - thead{ - @include gradient($article-warn-table-header); - } - tr:nth-child(even) td { - background: $article-warn-table-row-alt; - } - } - blockquote { - border-color: rgba($article-warn-text, .25); - p { color: rgba($article-warn-text, .6); } - } - .code-tabs-wrapper .code-tabs a { - background: transparent; - color: rgba($article-warn-text, .5); - &:hover { color: rgba($article-warn-text, 1); } - &.is-active { - color: rgba($article-warn-text, 1); - background: $article-warn-code-bg}; - } - hr, .expand { - border-color: rgba($article-warn-base, .4) - } -} diff --git a/assets/styles/layouts/article/blocks/_caution.scss b/assets/styles/layouts/article/blocks/_caution.scss new file mode 100644 index 000000000..2c618fc2b --- /dev/null +++ b/assets/styles/layouts/article/blocks/_caution.scss @@ -0,0 +1,97 @@ + +.caution { + &:before { + content: "C"; + color: #fff; + background: $article-caution-base; + } + + border-color: $article-caution-base; + background: $article-caution-bg; + h1,h2,h3,h4,h5,h6 { + color: $article-caution-heading; + a { + color: inherit !important; + &:hover{color: inherit !important} + } + } + p, li {color: $article-caution-text;} + strong { color: $article-caution-strong; } + a { + color: $article-caution-link !important; + code:after { + border-color: transparent rgba($article-caution-code, .35) transparent transparent; + } + &:hover { + color: $article-caution-link-hover !important; + code:after { border-color: transparent $article-caution-link-hover transparent transparent;} + } + } + ol li:before { + color: $article-caution-text; + } + code, pre{ + color: $article-caution-code; + background: $article-caution-code-bg; + } + img { + box-shadow: 1px 3px 10px $article-caution-shadow; + } + table{ + color: $article-caution-text; + box-shadow: 1px 3px 10px $article-caution-shadow; + thead{@include gradient($article-caution-table-header);} + tr:nth-child(even) td {background: $article-caution-table-row-alt;} + } + blockquote { + border-color: rgba($article-caution-text, .25); + p { color: rgba($article-caution-text, .6); } + } + .code-tabs-wrapper .code-tabs a { + background: transparent; + color: rgba($article-caution-text, .5); + &:hover { color: rgba($article-caution-text, 1); } + &.is-active { + color: rgba($article-caution-text, 1); + background: $article-caution-code-bg}; + } + hr, .expand { + border-color: rgba($article-caution-base, .4) !important + } + + ///////////////////////////////// Scrollbars ///////////////////////////////// + pre { @include scrollbar($article-caution-code-bg, $article-caution-code-scrollbar); } + table { @include scrollbar($article-caution-table-row-alt, $article-caution-table-scrollbar); } + + ///////////////////////////// Syntax Highlighting //////////////////////////// + .highlight { + color: $article-caution-code; + + .gh,.go,.na,.nt,.nv,.ow + { color: $article-caution-code } + .c,.ch,.cm,.cpf,.c1, .cs,.w + { color: $article-caution-code-accent1; } + .gi + { background-color: $article-caution-code-accent1; } + .k,.kc,.kd,.kn,.kp,.kr,.nn + { color: $article-caution-code-accent2; } + .bp,.cp,.dl,.gt,.gu,.kt,.nb,.nc,.no,.sa,.sb,.sc,.sd,.se,.sh,.sx,.sr,.s1,.s2 + { color: $article-caution-code-accent3 } + .err,.fm,.gr,.gd,.nd,.ne,.nf,.nl,.si + { color: $article-caution-code-accent4 } + .m,.ni,.mb,.mf,.mh,.mi,.mo,.vc,.vg,.vi,.vm,.il + { color: $article-caution-code-accent5 } + .gp,.o + { color: $article-caution-code-accent6 } + .ss + { color: $article-caution-code-accent7 } + // Javascript / Flux specific styles (duration and time values) + .language-js { + .mi + .nx, .mf + .nx { color: $article-caution-code-accent5; } + } + // SQL / InfluxQL specific styles (duration values) + .language-sql { + .mi + .n { color: $article-caution-code-accent5; } + } + } +} diff --git a/assets/styles/layouts/article/blocks/_important.scss b/assets/styles/layouts/article/blocks/_important.scss new file mode 100644 index 000000000..c2498ebc6 --- /dev/null +++ b/assets/styles/layouts/article/blocks/_important.scss @@ -0,0 +1,110 @@ +.important { + +} + +.important { + &:before { + content: "I"; + color: #fff; + background: $article-important-base; + } + + border-color: $article-important-base; + background: rgba($article-important-base, .15); + h1,h2,h3,h4,h5,h6 { + color: $article-important-heading; + a { + color: inherit !important; + &:hover{color: inherit !important} + } + } + p, li { + color: $article-important-text; + } + strong { + color: $article-important-strong; + } + a { + color: $article-important-link; + code:after { + border-color: transparent rgba($article-important-code, .35) transparent transparent; + } + &:hover { + color: $article-important-link-hover; + code:after { + border-color: transparent $article-important-link-hover transparent transparent; + } + } + } + ol li:before { + color: $article-important-text; + } + code, pre{ + color: $article-important-code; + background: $article-important-code-bg; + } + img { + box-shadow: 1px 3px 10px $article-important-shadow; + } + table{ + color: $article-important-text; + box-shadow: 1px 3px 10px $article-important-shadow; + thead{ + @include gradient($article-important-table-header); + } + tr:nth-child(even) td { + background: $article-important-table-row-alt; + } + } + blockquote { + border-color: rgba($article-important-text, .25); + p { color: rgba($article-important-text, .6); } + } + .code-tabs-wrapper .code-tabs a { + background: transparent; + color: rgba($article-important-text, .5); + &:hover { color: rgba($article-important-text, 1); } + &.is-active { + color: rgba($article-important-text, 1); + background: $article-important-code-bg}; + } + hr, .expand { + border-color: rgba($article-important-base, .4) !important; + } + + ///////////////////////////////// Scrollbars ///////////////////////////////// + pre { @include scrollbar($article-important-code-bg, $article-important-code-scrollbar); } + table { @include scrollbar($article-important-table-row-alt, $article-important-table-scrollbar); } + + ///////////////////////////// Syntax Highlighting //////////////////////////// + .highlight { + color: $article-important-code; + + .gh,.go,.na,.nt,.nv,.ow + { color: $article-important-code } + .c,.ch,.cm,.cpf,.c1, .cs,.w + { color: $article-important-code-accent1; } + .gi + { background-color: $article-important-code-accent1; } + .k,.kc,.kd,.kn,.kp,.kr,.nn + { color: $article-important-code-accent2; } + .bp,.cp,.dl,.gt,.gu,.kt,.nb,.nc,.no,.sa,.sb,.sc,.sd,.se,.sh,.sx,.sr,.s1,.s2 + { color: $article-important-code-accent3 } + .err,.fm,.gr,.gd,.nd,.ne,.nf,.nl,.si + { color: $article-important-code-accent4 } + .m,.ni,.mb,.mf,.mh,.mi,.mo,.vc,.vg,.vi,.vm,.il + { color: $article-important-code-accent5 } + .gp,.o + { color: $article-important-code-accent6 } + .ss + { color: $article-important-code-accent7 } + // Javascript / Flux specific styles (duration and time values) + .language-js { + .mi + .nx, .mf + .nx { color: $article-important-code-accent5; } + } + // SQL / InfluxQL specific styles (duration values) + .language-sql { + .mi + .n { color: $article-important-code-accent5; } + } + } +} diff --git a/assets/styles/layouts/article/blocks/_note.scss b/assets/styles/layouts/article/blocks/_note.scss new file mode 100644 index 000000000..110695a09 --- /dev/null +++ b/assets/styles/layouts/article/blocks/_note.scss @@ -0,0 +1,108 @@ +.note { + &:before { + content: "N"; + color: #fff; + background: $article-note-base; + } +} + +.note { + border-color: $article-note-base; + background: rgba($article-note-base, .1); + h1,h2,h3,h4,h5,h6 { + color: $article-note-heading; + a { + color: inherit !important; + &:hover{color: inherit !important} + } + } + p, li { + color: $article-note-text; + } + strong { + color: $article-note-strong; + } + a { + color: $article-note-link; + code:after { + border-color: transparent rgba($article-note-code, .35) transparent transparent; + } + &:hover { + color: $article-note-link-hover; + code:after { + border-color: transparent $article-note-link-hover transparent transparent; + } + } + } + ol li:before { + color: $article-note-text; + } + code, pre{ + color: $article-note-code; + background: $article-note-code-bg; + } + img { + box-shadow: 1px 3px 10px $article-note-shadow; + } + table{ + color: $article-note-text; + box-shadow: 1px 3px 10px $article-note-shadow; + thead{ + @include gradient($article-note-table-header); + } + tr:nth-child(even) td { + background: $article-note-table-row-alt; + } + } + blockquote { + border-color: rgba($article-note-text, .25); + p { color: rgba($article-note-text, .6); } + } + .code-tabs-wrapper .code-tabs a { + background: transparent; + color: rgba($article-note-text, .5); + &:hover { color: rgba($article-note-text, 1); } + &.is-active { + color: rgba($article-note-text, 1); + background: $article-note-code-bg}; + } + hr, .expand { + border-color: rgba($article-note-base, .4) !important; + } + + ///////////////////////////////// Scrollbars ///////////////////////////////// + pre { @include scrollbar($article-note-code-bg, $article-note-code-scrollbar); } + table { @include scrollbar($article-note-table-row-alt, $article-note-table-scrollbar); } + + ///////////////////////////// Syntax Highlighting //////////////////////////// + .highlight { + color: $article-note-code; + + .gh,.go,.na,.nt,.nv,.ow + { color: $article-note-code } + .c,.ch,.cm,.cpf,.c1, .cs,.w + { color: $article-note-code-accent1; } + .gi + { background-color: $article-note-code-accent1; } + .k,.kc,.kd,.kn,.kp,.kr,.nn + { color: $article-note-code-accent2; } + .bp,.cp,.dl,.gt,.gu,.kt,.nb,.nc,.no,.sa,.sb,.sc,.sd,.se,.sh,.sx,.sr,.s1,.s2 + { color: $article-note-code-accent3 } + .err,.fm,.gr,.gd,.nd,.ne,.nf,.nl,.si + { color: $article-note-code-accent4 } + .m,.ni,.mb,.mf,.mh,.mi,.mo,.vc,.vg,.vi,.vm,.il + { color: $article-note-code-accent5 } + .gp,.o + { color: $article-note-code-accent6 } + .ss + { color: $article-note-code-accent7 } + // Javascript / Flux specific styles (duration and time values) + .language-js { + .mi + .nx, .mf + .nx { color: $article-note-code-accent5; } + } + // SQL / InfluxQL specific styles (duration values) + .language-sql { + .mi + .n { color: $article-note-code-accent5; } + } + } +} diff --git a/assets/styles/layouts/article/blocks/_tip.scss b/assets/styles/layouts/article/blocks/_tip.scss new file mode 100644 index 000000000..12348a2ad --- /dev/null +++ b/assets/styles/layouts/article/blocks/_tip.scss @@ -0,0 +1,101 @@ +.tip { + &:before { + content: "T"; + color: #fff; + background: $article-tip-base; + } + + border-color: $article-tip-base; + background: rgba($article-tip-base, .12); + h1,h2,h3,h4,h5,h6 { + color: $article-tip-heading; + a { + color: inherit !important; + &:hover{color: inherit !important} + } + } + p,li { color: $article-tip-text; } + strong {color: $article-tip-strong;} + a { + color: $article-tip-link; + code:after {border-color: transparent rgba($article-tip-code, .35) transparent transparent;} + &:hover { + color: $article-tip-link-hover; + code:after {border-color: transparent $article-tip-link-hover transparent transparent;} + } + } + ol li:before {color: $article-tip-text;} + code, pre{ + color: $article-tip-code; + background: $article-tip-code-bg; + } + img { + box-shadow: 1px 3px 10px $article-tip-shadow; + } + table{ + color: $article-tip-text; + box-shadow: 1px 3px 10px $article-tip-shadow; + thead{@include gradient($article-tip-table-header);} + tr:nth-child(even) td {background: $article-tip-table-row-alt;} + } + blockquote { + border-color: rgba($article-tip-text, .25); + p { color: rgba($article-tip-text, .6); } + } + .code-tabs-wrapper .code-tabs a { + background: transparent; + color: rgba($article-tip-text, .5); + &:hover { color: rgba($article-tip-text, 1); } + &.is-active { + color: rgba($article-tip-text, 1); + background: $article-tip-code-bg}; + } + + &.flex { + font-style: italic; + display: flex; + div:first-child { + position: relative; + margin: .25rem 2rem 0 0; + } + } + hr, .expand { + border-color: rgba($article-tip-base, .4) !important; + } + + ///////////////////////////////// Scrollbars ///////////////////////////////// + pre { @include scrollbar($article-tip-code-bg, $article-tip-code-scrollbar); } + table { @include scrollbar($article-tip-table-row-alt, $article-tip-table-scrollbar); } + + ///////////////////////////// Syntax Highlighting //////////////////////////// + .highlight { + color: $article-tip-code; + + .gh,.go,.na,.nt,.nv,.ow + { color: $article-tip-code } + .c,.ch,.cm,.cpf,.c1, .cs,.w + { color: $article-tip-code-accent1; } + .gi + { background-color: $article-tip-code-accent1; } + .k,.kc,.kd,.kn,.kp,.kr,.nn + { color: $article-tip-code-accent2; } + .bp,.cp,.dl,.gt,.gu,.kt,.nb,.nc,.no,.sa,.sb,.sc,.sd,.se,.sh,.sx,.sr,.s1,.s2 + { color: $article-tip-code-accent3 } + .err,.fm,.gr,.gd,.nd,.ne,.nf,.nl,.si + { color: $article-tip-code-accent4 } + .m,.ni,.mb,.mf,.mh,.mi,.mo,.vc,.vg,.vi,.vm,.il + { color: $article-tip-code-accent5 } + .gp,.o + { color: $article-tip-code-accent6 } + .ss + { color: $article-tip-code-accent7 } + // Javascript / Flux specific styles (duration and time values) + .language-js { + .mi + .nx, .mf + .nx { color: $article-tip-code-accent5; } + } + // SQL / InfluxQL specific styles (duration values) + .language-sql { + .mi + .n { color: $article-tip-code-accent5; } + } + } +} diff --git a/assets/styles/layouts/article/blocks/_warning.scss b/assets/styles/layouts/article/blocks/_warning.scss new file mode 100644 index 000000000..62578bb1c --- /dev/null +++ b/assets/styles/layouts/article/blocks/_warning.scss @@ -0,0 +1,97 @@ +.warn, .warning { + &:before { + content: "W"; + color: #fff; + background: $article-warning-base; + } + + border-color: $article-warning-base; + background: $article-warning-bg; + h1,h2,h3,h4,h5,h6 { + color: $article-warning-heading; + a { + color: inherit !important; + &:hover{color: inherit !important} + } + } + p, li {color: $article-warning-text;} + strong { color: $article-warning-strong; } + a { + color: $article-warning-link !important; + code:after { + border-color: transparent rgba($article-warning-code, .35) transparent transparent; + } + &:hover { + color: $article-warning-link-hover !important; + code:after { border-color: transparent $article-warning-link-hover transparent transparent;} + } + } + ol li:before { + color: $article-warning-text; + } + code, pre{ + color: $article-warning-code; + background: $article-warning-code-bg; + } + img { + box-shadow: 1px 3px 10px $article-warning-shadow; + } + table{ + color: $article-warning-text; + box-shadow: 1px 3px 10px $article-warning-shadow; + thead{@include gradient($article-warning-table-header);} + tr:nth-child(even) td {background: $article-warning-table-row-alt;} + } + blockquote { + border-color: rgba($article-warning-text, .25); + p { color: rgba($article-warning-text, .6); } + } + .code-tabs-wrapper .code-tabs a { + background: transparent; + color: rgba($article-warning-text, .5); + &:hover { color: rgba($article-warning-text, 1); } + &.is-active { + color: rgba($article-warning-text, 1); + background: $article-warning-code-bg}; + } + hr, .expand { + border-color: rgba($article-warning-base, .4) !important; + } + + ///////////////////////////////// Scrollbars ///////////////////////////////// + pre { @include scrollbar($article-warning-code-bg, $article-warning-code-scrollbar); } + table { @include scrollbar($article-warning-table-row-alt, $article-warning-table-scrollbar); } + + ///////////////////////////// Syntax Highlighting //////////////////////////// + .highlight { + color: $article-warning-code; + + .gh,.go,.na,.nt,.nv,.ow + { color: $article-warning-code } + .c,.ch,.cm,.cpf,.c1, .cs,.w + { color: $article-warning-code-accent1; } + .gi + { background-color: $article-warning-code-accent1; } + .k,.kc,.kd,.kn,.kp,.kr,.nn + { color: $article-warning-code-accent2; } + .bp,.cp,.dl,.gt,.gu,.kt,.nb,.nc,.no,.sa,.sb,.sc,.sd,.se,.sh,.sx,.sr,.s1,.s2 + { color: $article-warning-code-accent3 } + .err,.fm,.gr,.gd,.nd,.ne,.nf,.nl,.si + { color: $article-warning-code-accent4 } + .m,.ni,.mb,.mf,.mh,.mi,.mo,.vc,.vg,.vi,.vm,.il + { color: $article-warning-code-accent5 } + .gp,.o + { color: $article-warning-code-accent6 } + .ss + { color: $article-warning-code-accent7 } + // Javascript / Flux specific styles (duration and time values) + .language-js { + .mi + .nx, .mf + .nx { color: $article-warning-code-accent5; } + } + // SQL / InfluxQL specific styles (duration values) + .language-sql { + .mi + .n { color: $article-warning-code-accent5; } + } + } + +} \ No newline at end of file diff --git a/assets/styles/themes/_theme-dark.scss b/assets/styles/themes/_theme-dark.scss index 299d57869..6b7a3842f 100644 --- a/assets/styles/themes/_theme-dark.scss +++ b/assets/styles/themes/_theme-dark.scss @@ -78,18 +78,18 @@ $article-table-row-alt: $grey20; $article-table-scrollbar: $g0-obsidian; // Article Notes, Warnings, & Messages -$article-note-base: $gr-viridian; +$article-note-base: $b-pool; $article-note-heading: $g20-white; -$article-note-text: $gr-honeydew; -$article-note-strong: $gr-krypton; -$article-note-link: $gr-wasabi; -$article-note-link-hover: $g20-white; -$article-note-table-header: $grad-green-dark; -$article-note-table-row-alt: #1a3c34; -$article-note-table-scrollbar: #162627; +$article-note-text: $b-neutrino; +$article-note-strong: $g20-white; +$article-note-link: $g20-white; +$article-note-link-hover: $b-hydrogen; +$article-note-table-header: $grad-blue-dark; +$article-note-table-row-alt: #1b3a58; +$article-note-table-scrollbar: #192a3a; $article-note-shadow: $g0-obsidian; -$article-note-code: $br-galaxy; -$article-note-code-bg: #040d0e; +$article-note-code: $b-laser; +$article-note-code-bg: #0a071c; $article-note-code-accent1: #567375; $article-note-code-accent2: $b-pool; $article-note-code-accent3: $gr-viridian; @@ -97,53 +97,93 @@ $article-note-code-accent4: $r-ruby; $article-note-code-accent5: #ff6db0; $article-note-code-accent6: $b-pool; $article-note-code-accent7: #e90; -$article-note-code-scrollbar: #162627; +$article-note-code-scrollbar: #192a3a; -$article-warn-base: $r-dreamsicle; -$article-warn-bg: #ff61851a; -$article-warn-heading: $g20-white; -$article-warn-text: $r-tungsten; -$article-warn-link: $r-marmelade; -$article-warn-link-hover: $g20-white; -$article-warn-table-header: $grad-red; -$article-warn-table-row-alt: #4a2a2a; -$article-warn-table-scrollbar: #1f181b; -$article-warn-shadow: #0d0610; -$article-warn-code: #ec6e6e; -$article-warn-code-bg: #0d0610; -$article-warn-code-accent1: #844c4c; -$article-warn-code-accent2: $b-pool; -$article-warn-code-accent3: $gr-viridian; -$article-warn-code-accent4: $r-ruby; -$article-warn-code-accent5: #ffb4fb; -$article-warn-code-accent6: $b-pool; -$article-warn-code-accent7: #e90; -$article-warn-code-scrollbar: #2a2025; +$article-tip-base: $gr-viridian; +$article-tip-heading: $g20-white; +$article-tip-text: $gr-honeydew; +$article-tip-strong: $g20-white; +$article-tip-link: $gr-wasabi; +$article-tip-link-hover: $g20-white; +$article-tip-table-header: $grad-green-dark; +$article-tip-table-row-alt: #1a3c34; +$article-tip-table-scrollbar: #162627; +$article-tip-shadow: $g0-obsidian; +$article-tip-code: $br-galaxy; +$article-tip-code-bg: #040d0e; +$article-tip-code-accent1: #567375; +$article-tip-code-accent2: $b-pool; +$article-tip-code-accent3: $gr-viridian; +$article-tip-code-accent4: $r-ruby; +$article-tip-code-accent5: #ff6db0; +$article-tip-code-accent6: $b-pool; +$article-tip-code-accent7: #e90; +$article-tip-code-scrollbar: #162627; -$article-cloud-base: $b-pool; -$article-cloud-heading: $g20-white; -$article-cloud-text: $b-neutrino; -$article-cloud-link: $g20-white; -$article-cloud-link-hover: $b-hydrogen; -$article-cloud-table-header: $grad-blue-dark; -$article-cloud-table-row-alt: #1b3a58; -$article-cloud-table-scrollbar: #192a3a; -$article-cloud-shadow: $g0-obsidian; -$article-cloud-code: $b-laser; -$article-cloud-code-bg: #0a071c; -$article-cloud-code-accent1: #567375; -$article-cloud-code-accent2: $b-pool; -$article-cloud-code-accent3: $gr-viridian; -$article-cloud-code-accent4: $r-ruby; -$article-cloud-code-accent5: #ff6db0; -$article-cloud-code-accent6: $b-pool; -$article-cloud-code-accent7: #e90; -$article-cloud-code-scrollbar: #192a3a; +$article-important-base: $br-galaxy; +$article-important-heading: $g20-white; +$article-important-text: $cp-munchkin; +$article-important-strong: $g20-white; +$article-important-link: #797aff; +$article-important-link-hover: $g20-white; +$article-important-table-header: $grad-OminousFog; +$article-important-table-row-alt: #1b1b33; +$article-important-table-scrollbar: #56519e; +$article-important-shadow: #11111d; +$article-important-code: #9f92ff; +$article-important-code-bg: #0a071c; +$article-important-code-accent1: #5f51ac; +$article-important-code-accent2: $br-pulsar; +$article-important-code-accent3: #009a64; +$article-important-code-accent4: $r-ruby; +$article-important-code-accent5: #e24bbb; +$article-important-code-accent6: #00a5eb; +$article-important-code-accent7: #e90; +$article-important-code-scrollbar: #56519e; -$article-enterprise-base: $br-galaxy; -$article-enterprise-text: $cp-melrose; -$article-enterprise-link: $cp-titan; -$article-enterprise-link-hover: $g20-white; +$article-warning-base: $r-dreamsicle; +$article-warning-bg: #ff61851a; +$article-warning-heading: $g20-white; +$article-warning-text: $r-tungsten; +$article-warning-strong: $g20-white; +$article-warning-link: $r-marmelade; +$article-warning-link-hover: $g20-white; +$article-warning-table-header: $grad-red; +$article-warning-table-row-alt: #4a2a2a; +$article-warning-table-scrollbar: #1f181b; +$article-warning-shadow: #0d0610; +$article-warning-code: #ec6e6e; +$article-warning-code-bg: #0d0610; +$article-warning-code-accent1: #844c4c; +$article-warning-code-accent2: $b-pool; +$article-warning-code-accent3: $gr-viridian; +$article-warning-code-accent4: $r-ruby; +$article-warning-code-accent5: #ffb4fb; +$article-warning-code-accent6: $b-pool; +$article-warning-code-accent7: #e90; +$article-warning-code-scrollbar: #2a2025; + +$article-caution-base: $br-new-magenta; +$article-caution-bg: rgba($br-new-magenta, .12); +$article-caution-heading: $g20-white; +$article-caution-text: #fe9dbc; +$article-caution-strong: $g20-white; +$article-caution-link: #f3d5e1; +$article-caution-link-hover: $g20-white; +$article-caution-table-header: $br-new-magenta, #ff598f; +$article-caution-table-row-alt: #391b35; +$article-caution-table-scrollbar: #912a58; +$article-caution-shadow: #0f050e; +$article-caution-code: #ff679b; +$article-caution-code-bg: #0d0610; +$article-caution-code-accent1: #8f3f5a; +$article-caution-code-accent2: #3d97e5; +$article-caution-code-accent3: #947eff; +$article-caution-code-accent4: $r-ruby; +$article-caution-code-accent5: #ffa0de; +$article-caution-code-accent6: #3d97e5; +$article-caution-code-accent7: #e90; +$article-caution-code-scrollbar: #5c1b38; // Article Tabs for tabbed content $article-tab-text: $g12-forge; diff --git a/assets/styles/themes/_theme-light.scss b/assets/styles/themes/_theme-light.scss index 93e62a8fb..882c3783a 100644 --- a/assets/styles/themes/_theme-light.scss +++ b/assets/styles/themes/_theme-light.scss @@ -78,73 +78,113 @@ $article-table-header: $grad-Miyazakisky !default; $article-table-row-alt: #f6f8ff !default; $article-table-scrollbar: $g14-chromium !default; -// Article Notes & Warnings -$article-note-base: $gr-rainforest !default; -$article-note-heading: $gr-emerald !default; -$article-note-text: $gr-emerald !default; -$article-note-strong: $gr-emerald !default; -$article-note-link: $b-ocean !default; -$article-note-link-hover: $br-magenta !default; -$article-note-table-header: $grad-green-dark !default; -$article-note-table-row-alt: #d6f5e9 !default; -$article-note-table-scrollbar: #87DABE !default; -$article-note-shadow: #8CB7AB !default; -$article-note-code: #0A6F75 !default; -$article-note-code-bg: #BDF3DA !default; -$article-note-code-accent1: #6abba0 !default; -$article-note-code-accent2: #0084d6 !default; -$article-note-code-accent3: #5d52d6 !default; +// Article Alert Blocks +$article-note-base: $b-pool !default; +$article-note-heading: $b-ocean !default; +$article-note-text: $b-ocean !default; +$article-note-strong: $b-ocean !default; +$article-note-link: $p-void !default; +$article-note-link-hover: $p-star !default; +$article-note-table-header: $grad-blue !default; +$article-note-table-row-alt: $g20-white !default; +$article-note-table-scrollbar: $b-hydrogen !default; +$article-note-shadow: #6EB8E4 !default; +$article-note-code: $b-ocean !default; +$article-note-code-bg: $b-neutrino !default; +$article-note-code-accent1: #3CAAE2 !default; +$article-note-code-accent2: $br-pulsar !default; +$article-note-code-accent3: #048E66 !default; $article-note-code-accent4: $r-ruby !default; $article-note-code-accent5: #e24bbb !default; $article-note-code-accent6: #0084d6 !default; $article-note-code-accent7: #e90 !default; -$article-note-code-scrollbar: #87DABE !default; +$article-note-code-scrollbar: $b-laser !default; -$article-warn-base: $r-dreamsicle !default; -$article-warn-bg: rgba($r-dreamsicle, .08) !default; -$article-warn-heading: $r-fire !default; -$article-warn-text: $r-curacao !default; -$article-warn-link: $r-curacao !default; -$article-warn-link-hover: $br-pulsar !default; -$article-warn-table-header: $grad-red !default; -$article-warn-table-row-alt: #ffe6df !default; -$article-warn-table-scrollbar: #FFB1B1 !default; -$article-warn-shadow: #b98a7d !default; -$article-warn-code: #d0154e !default; -$article-warn-code-bg: #fde6e5 !default; -$article-warn-code-accent1: #fd99b8 !default; -$article-warn-code-accent2: #357ae8 !default; -$article-warn-code-accent3: #6c59cc !default; -$article-warn-code-accent4: $r-ruby !default; -$article-warn-code-accent5: #6a0a6f !default; -$article-warn-code-accent6: #357ae8 !default; -$article-warn-code-accent7: #e90 !default; -$article-warn-code-scrollbar: #FFB1B1 !default; +$article-tip-base: $gr-rainforest !default; +$article-tip-heading: $gr-emerald !default; +$article-tip-text: $gr-emerald !default; +$article-tip-strong: $gr-emerald !default; +$article-tip-link: $b-ocean !default; +$article-tip-link-hover: $br-magenta !default; +$article-tip-table-header: $grad-green-dark !default; +$article-tip-table-row-alt: #d6f5e9 !default; +$article-tip-table-scrollbar: #87DABE !default; +$article-tip-shadow: #8CB7AB !default; +$article-tip-code: #0A6F75 !default; +$article-tip-code-bg: #BDF3DA !default; +$article-tip-code-accent1: #6abba0 !default; +$article-tip-code-accent2: #0084d6 !default; +$article-tip-code-accent3: #5d52d6 !default; +$article-tip-code-accent4: $r-ruby !default; +$article-tip-code-accent5: #e24bbb !default; +$article-tip-code-accent6: #0084d6 !default; +$article-tip-code-accent7: #e90 !default; +$article-tip-code-scrollbar: #87DABE !default; -$article-cloud-base: $b-laser !default; -$article-cloud-heading: $b-ocean !default; -$article-cloud-text: $b-ocean !default; -$article-cloud-link: $b-ocean !default; -$article-cloud-link-hover: $br-pulsar !default; -$article-cloud-table-header: $grad-blue !default; -$article-cloud-table-row-alt: $g20-white !default; -$article-cloud-table-scrollbar: $b-hydrogen !default; -$article-cloud-shadow: #6EB8E4 !default; -$article-cloud-code: $b-ocean !default; -$article-cloud-code-bg: $b-neutrino !default; -$article-cloud-code-accent1: #3CAAE2 !default; -$article-cloud-code-accent2: $br-pulsar !default; -$article-cloud-code-accent3: #048E66 !default; -$article-cloud-code-accent4: $r-ruby !default; -$article-cloud-code-accent5: #e24bbb !default; -$article-cloud-code-accent6: #0084d6 !default; -$article-cloud-code-accent7: #e90 !default; -$article-cloud-code-scrollbar: $b-laser !default; +$article-important-base: $br-galaxy !default; +$article-important-heading: $br-pulsar !default; +$article-important-text: #5a55ad !default; +$article-important-strong: $br-pulsar !default; +$article-important-link: $b-ocean !default; +$article-important-link-hover: $br-pulsar !default; +$article-important-table-header: $grad-OminousFog !default; +$article-important-table-row-alt: $g20-white !default; +$article-important-table-scrollbar: $br-galaxy !default; +$article-important-shadow: #b0a6eb !default; +$article-important-code: $br-pulsar !default; +$article-important-code-bg: #dadbff !default; +$article-important-code-accent1: #998aeb !default; +$article-important-code-accent2: $br-pulsar !default; +$article-important-code-accent3: #026d33 !default; +$article-important-code-accent4: $r-ruby !default; +$article-important-code-accent5: #e24bbb !default; +$article-important-code-accent6: #0084d6 !default; +$article-important-code-accent7: #e90 !default; +$article-important-code-scrollbar: $br-galaxy !default; -$article-enterprise-base: $br-galaxy !default; -$article-enterprise-text: $cp-marguerite !default; -$article-enterprise-link: $cp-marguerite !default; -$article-enterprise-link-hover: $b-pool !default; +$article-warning-base: $r-dreamsicle !default; +$article-warning-bg: rgba($r-dreamsicle, .08) !default; +$article-warning-heading: $r-fire !default; +$article-warning-text: $r-curacao !default; +$article-warning-strong: $br-pulsar !default; +$article-warning-link: $r-curacao !default; +$article-warning-link-hover: $br-pulsar !default; +$article-warning-table-header: $grad-red !default; +$article-warning-table-row-alt: #ffe6df !default; +$article-warning-table-scrollbar: #FFB1B1 !default; +$article-warning-shadow: #b98a7d !default; +$article-warning-code: #d0154e !default; +$article-warning-code-bg: #fde6e5 !default; +$article-warning-code-accent1: #fd99b8 !default; +$article-warning-code-accent2: #357ae8 !default; +$article-warning-code-accent3: #6c59cc !default; +$article-warning-code-accent4: $r-ruby !default; +$article-warning-code-accent5: #6a0a6f !default; +$article-warning-code-accent6: #357ae8 !default; +$article-warning-code-accent7: #e90 !default; +$article-warning-code-scrollbar: #FFB1B1 !default; + +$article-caution-base: $br-new-magenta !default; +$article-caution-bg: rgba($br-new-magenta, .08) !default; +$article-caution-heading: $br-new-magenta !default; +$article-caution-text: #db4692 !default; +$article-caution-strong: $br-new-magenta !default; +$article-caution-link: #8709d3 !default; +$article-caution-link-hover: $b-sapphire !default; +$article-caution-table-header: $br-new-magenta, #ff598f !default; +$article-caution-table-row-alt: #fff8fc !default; +$article-caution-table-scrollbar: #faa9cd !default; +$article-caution-shadow: #f1b1cb !default; +$article-caution-code: #d01578 !default; +$article-caution-code-bg: #f3d5e1 !default; +$article-caution-code-accent1: #e683b7 !default; +$article-caution-code-accent2: #356ec8 !default; +$article-caution-code-accent3: #5845b7 !default; +$article-caution-code-accent4: $r-ruby !default; +$article-caution-code-accent5: #6a0a6f !default; +$article-caution-code-accent6: #357ae8 !default; +$article-caution-code-accent7: #e90 !default; +$article-caution-code-scrollbar: #faa9cd !default; // Article Tabs for tabbed content $article-tab-text: $g8-storm !default; diff --git a/assets/styles/tools/_fonts.scss b/assets/styles/tools/_fonts.scss index de42726c0..426c4d435 100644 --- a/assets/styles/tools/_fonts.scss +++ b/assets/styles/tools/_fonts.scss @@ -37,6 +37,7 @@ body { @import "tools/icon-fonts/icomoon-v2"; @import "tools/icon-fonts/icon-v3"; @import "tools/icon-fonts/icon-v4"; +@import "tools/icon-fonts/alert-icons"; .v3 {font-family: 'icomoon-v3'} .v4 {font-family: 'icomoon-v4'} \ No newline at end of file diff --git a/assets/styles/tools/icon-fonts/_alert-icons.scss b/assets/styles/tools/icon-fonts/_alert-icons.scss new file mode 100644 index 000000000..f9db39f07 --- /dev/null +++ b/assets/styles/tools/icon-fonts/_alert-icons.scss @@ -0,0 +1,42 @@ +@font-face { + font-family: 'alert-icons'; + src: url('fonts/alert-icons.eot?d0dznh'); + src: url('fonts/alert-icons.eot?d0dznh#iefix') format('embedded-opentype'), + url('fonts/alert-icons.ttf?d0dznh') format('truetype'), + url('fonts/alert-icons.woff?d0dznh') format('woff'), + url('fonts/alert-icons.svg?d0dznh#icomoon') format('svg'); + font-weight: normal; + font-style: normal; + font-display: block; +} + +[class^="alert-icon-"], [class*=" alert-icon-"] { + /* use !important to prevent issues with browser extensions that change fonts */ + font-family: 'alert-icons' !important; + speak: never; + font-style: normal; + font-weight: normal; + font-variant: normal; + text-transform: none; + line-height: 1; + + /* Better Font Rendering =========== */ + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +.alert-icon-caution:before { + content: "\43"; +} +.alert-icon-important:before { + content: "\49"; +} +.alert-icon-note:before { + content: "\4e"; +} +.alert-icon-tip:before { + content: "\54"; +} +.alert-icon-warning:before { + content: "\57"; +} \ No newline at end of file diff --git a/compose.yaml b/compose.yaml index 35d66f2a0..be18df40b 100644 --- a/compose.yaml +++ b/compose.yaml @@ -36,6 +36,7 @@ services: - local - lint cloud-pytest: + container_name: cloud-pytest image: influxdata/docs-pytest build: context: . @@ -85,6 +86,7 @@ services: target: /app/content working_dir: /app cloud-dedicated-pytest: + container_name: cloud-dedicated-pytest image: influxdata/docs-pytest build: context: . @@ -139,6 +141,7 @@ services: target: /app/content working_dir: /app cloud-serverless-pytest: + container_name: cloud-serverless-pytest image: influxdata/docs-pytest build: context: . @@ -188,6 +191,7 @@ services: target: /app/content working_dir: /app clustered-pytest: + container_name: clustered-pytest image: influxdata/docs-pytest build: context: . @@ -242,6 +246,7 @@ services: target: /app/content working_dir: /app telegraf-pytest: + container_name: telegraf-pytest image: influxdata/docs-pytest build: context: . @@ -290,6 +295,7 @@ services: target: /app/content working_dir: /app v2-pytest: + container_name: v2-pytest image: influxdata/docs-pytest build: context: . @@ -339,6 +345,7 @@ services: target: /app/content working_dir: /app influxdb2: + container_name: influxdb2 image: influxdb:2 ports: - 8086:8086 @@ -366,10 +373,10 @@ services: source: influxdb2-config target: /etc/influxdb2 remark-lint: + container_name: remark-lint build: context: . dockerfile: .ci/Dockerfile.remark - command: ["remark", "${CONTENT_PATH}"] profiles: - lint volumes: diff --git a/content/chronograf/v1/about_the_project/release-notes.md b/content/chronograf/v1/about_the_project/release-notes.md index 208c15b21..ed15f4b61 100644 --- a/content/chronograf/v1/about_the_project/release-notes.md +++ b/content/chronograf/v1/about_the_project/release-notes.md @@ -10,6 +10,19 @@ aliases: - /chronograf/v1/about_the_project/release-notes-changelog/ --- +## v1.10.6 {date="2024-12-16"} + +### Bug Fixes + +- Prevent dangerous InfluxQL statements from automatically executing. +- Fix Hosts page loading when there is a large number of connections. +- Support InfluxDB Enterprise when using the Flux Query Builder. +- Support metaqueries for InfluxDB Cloud Serverless environments. + +### Dependency updates + +- Upgrade Go to 1.22.7. + ## v1.10.5 {date="2024-05-31"} ### Dependency updates diff --git a/content/chronograf/v1/administration/managing-security.md b/content/chronograf/v1/administration/managing-security.md index 72900b77b..b3d694b99 100644 --- a/content/chronograf/v1/administration/managing-security.md +++ b/content/chronograf/v1/administration/managing-security.md @@ -1,7 +1,8 @@ --- title: Manage Chronograf security description: Manage Chronograf security with OAuth 2.0 providers. -aliases: /chronograf/v1/administration/security-best-practices/ +aliases: + - /chronograf/v1/administration/security-best-practices/ menu: chronograf_v1: name: Manage Chronograf security diff --git a/content/chronograf/v1/troubleshooting/frequently-asked-questions.md b/content/chronograf/v1/troubleshooting/frequently-asked-questions.md index d141303e4..343bd62de 100644 --- a/content/chronograf/v1/troubleshooting/frequently-asked-questions.md +++ b/content/chronograf/v1/troubleshooting/frequently-asked-questions.md @@ -6,6 +6,8 @@ menu: name: Frequently asked questions (FAQs) weight: 10 parent: Troubleshoot +aliases: + - /chronograf/latest/guides/transition-web-admin-interface/ --- ## How do I connect Chronograf to an InfluxDB Enterprise cluster? diff --git a/content/enterprise_influxdb/v1/about-the-project/release-notes.md b/content/enterprise_influxdb/v1/about-the-project/release-notes.md index 1595ac5f4..6edaa9e4d 100644 --- a/content/enterprise_influxdb/v1/about-the-project/release-notes.md +++ b/content/enterprise_influxdb/v1/about-the-project/release-notes.md @@ -19,6 +19,39 @@ InfluxDB Enterprise builds are available. For more information, see [FIPS-compliant InfluxDB Enterprise builds](/enterprise_influxdb/v1/introduction/installation/fips-compliant/). {{% /note %}} +## v1.11.8 {date="2024-11-15"} + +### Bug Fixes + +- Strip double quotes from measurement names in the [`/api/v2/delete` compatibility + API](/enterprise_influxdb/v1/tools/api/#apiv2delete-http-endpoint) before + string comparisons (e.g. to allow special characters in measurement names). +- Enable SHA256 for FIPS RPMs. + +## v1.11.7 {date="2024-09-19"} + +### Bug Fixes + +- Log errors when RPC calls fail for `MetaExecutor` operations like + `SHOW TAG VALUES` and `SHOW TAG KEYS`. +- Prevent `GROUP BY` queries with an offset that crossed a DST boundary from failing. +- Ensure `range()` filters correctly for all years. + +### Features + +- Run the `FIPS POST` if available and log the result. +- Add support for LDAP over SSL (LDAPS). +- Improve performance of `SHOW TAG VALUES` when using FGA by optimizing queries + to be limited to only tag values the user has permission to access. + +### Other + +- Upgrade to Go 1.22.7. +- Upgrade `jwt-go`. +- Upgrade `dvsekhvalnov/jose2go` to v1.6.0. + +--- + ## v1.11.6 {date="2024-08-02"} ### Bug Fixes diff --git a/content/enterprise_influxdb/v1/administration/backup-and-restore.md b/content/enterprise_influxdb/v1/administration/backup-and-restore.md index 1f4bc5591..613f7c679 100644 --- a/content/enterprise_influxdb/v1/administration/backup-and-restore.md +++ b/content/enterprise_influxdb/v1/administration/backup-and-restore.md @@ -11,33 +11,40 @@ menu: parent: Administration --- -- [Overview](#overview) -- [Backup and restore utilities](#backup-and-restore-utilities) -- [Exporting and importing data](#exporting-and-importing-data) +Use the InfluxDB Enterprise `backup`, `restore`, `export` and `import` utilities +to prevent unexpected data loss and preserve the ability to restore data if it +ever is lost. -## Overview - -When deploying InfluxDB Enterprise in production environments, you should have a strategy and procedures for backing up and restoring your InfluxDB Enterprise clusters to be prepared for unexpected data loss. - -The tools provided by InfluxDB Enterprise can be used to: +You can use these tools in your back up and restore procedures to: - Provide disaster recovery due to unexpected events - Migrate data to new environments or servers - Restore clusters to a consistent state -- Debugging +- Export and import data for debugging Depending on the volume of data to be protected and your application requirements, InfluxDB Enterprise offers two methods, described below, for managing backups and restoring data: -- [Backup and restore utilities](#backup-and-restore-utilities) — For most applications -- [Exporting and importing data](#exporting-and-importing-data) — For large datasets +- [Backup and restore utilities](#backup-and-restore-utilities): Use for most applications +- [Exporting and importing data](#exporting-and-importing-data): Use for very large datasets and to debug data -> **Note:** Use the [`backup` and `restore` utilities (InfluxDB OSS 1.5 and later)](/enterprise_influxdb/v1/administration/backup-and-restore/) to: +> [!Note] +> #### Back up and restore between InfluxDB Enterprise and OSS +> +> Use the `backup` and `restore` utilities in +> [InfluxDB Enterprise](#backup-and-restore-utilities) and +> [InfluxDB OSS (version 1.5 and later)](/influxdb/v1/administration/backup-and-restore/) to: > > - Restore InfluxDB Enterprise backup files to InfluxDB OSS instances. > - Back up InfluxDB OSS data that can be restored in InfluxDB Enterprise clusters. ## Backup and restore utilities +Use InfluxDB Enterprise back up and restore utilities to: + +- Back up and restore multiple databases at a time. +- Back up specific time ranges. +- Create backup files compatible with InfluxDB OSS. + InfluxDB Enterprise supports backing up and restoring data in a cluster, a single database and retention policy, and single shards. Most InfluxDB Enterprise applications can use the backup and restore utilities. @@ -46,11 +53,20 @@ Use the `backup` and `restore` utilities to back up and restore between `influxd instances with the same versions or with only minor version differences. For example, you can backup from {{< latest-patch version="1.10" >}} and restore on {{< latest-patch >}}. +- [Backup utility](#backup-utility) + - [Examples](#examples) +- [Restore utility](#restore-utility) +- [Exporting and importing data](#exporting-and-importing-data) + - [Exporting data](#exporting-data) + - [Importing data](#importing-data) + - [Example](#example) + ### Backup utility A backup creates a copy of the [metastore](/enterprise_influxdb/v1/concepts/glossary/#metastore) and [shard](/enterprise_influxdb/v1/concepts/glossary/#shard) data at that point in time and stores the copy in the specified directory. -Or, back up **only the cluster metastore** using the `-strategy only-meta` backup option. For more information, see [perform a metastore only backup](#perform-a-metastore-only-backup). +To back up **only the cluster metastore**, use the `-strategy only-meta` backup option. +For more information, see how to [perform a metastore only backup](#perform-a-metastore-only-backup). All backups include a manifest, a JSON file describing what was collected during the backup. The filenames reflect the UTC timestamp of when the backup was created, for example: @@ -62,14 +78,19 @@ The filenames reflect the UTC timestamp of when the backup was created, for exam Backups can be full, metastore only, or incremental, and they are incremental by default: - **Full backup**: Creates a copy of the metastore and shard data. -- **Incremental backup**: Creates a copy of the metastore and shard data that have changed since the last incremental backup. If there are no existing incremental backups, the system automatically performs a complete backup. +- **Incremental backup**: Creates a copy of the metastore and shard data that have changed since the last backup (the most recent backup file in the specified directory). + If no backups exist in the directory, then the system automatically performs a full backup. - **Metastore only backup**: Creates a copy of the metastore data only. Restoring different types of backups requires different syntax. To prevent issues with [restore](#restore-utility), keep full backups, metastore only backups, and incremental backups in separate directories. ->**Note:** The backup utility copies all data through the meta node that is used to -execute the backup. As a result, performance of a backup and restore is typically limited by the network IO of the meta node. Increasing the resources available to this meta node (such as resizing the EC2 instance) can significantly improve backup and restore performance. +> [!Note] +> #### Backup and restore performance +> +> The backup utility copies all data through the meta node that is used to execute the backup. +> As a result, backup and restore performance is typically limited by the network IO of the meta node. +> Increasing the resources available to this meta node (such as resizing the EC2 instance) can significantly improve backup and restore performance. #### Syntax @@ -77,7 +98,8 @@ execute the backup. As a result, performance of a backup and restore is typicall influxd-ctl [global-options] backup [backup-options] ``` -> **Note:** The `influxd-ctl backup` command exits with `0` for success and `1` for failure. If the backup fails, output can be directed to a log file to troubleshoot. +If successful, the `influxd-ctl backup` command exits with `0` status; +otherwise, error (`1`) status and a message that you can use for troubleshooting. ##### Global flags @@ -89,7 +111,7 @@ for a complete list of the global `influxd-ctl` flags. - `-db `: name of the single database to back up - `-from `: the data node TCP address to prefer when backing up - `-strategy`: select the backup strategy to apply during backup - - `incremental`: _**(Default)**_ backup only data added since the previous backup. + - `incremental`: _**(Default)**_ backup data that is new or changed since the previous backup. - `full` perform a full backup. Same as `-full` - `only-meta` perform a backup for meta data only: users, roles, databases, continuous queries, retention policies. Shards are not exported. @@ -104,38 +126,47 @@ for a complete list of the global `influxd-ctl` flags. #### Back up a database and all retention policies -Store the following incremental backups in different directories. -The first backup specifies `-db myfirstdb` and the second backup specifies -different options: `-db myfirstdb` and `-rp autogen`. +The following example stores incremental backups of the database +and all retention policies in the `./myfirstdb-allrp-backup` directory: ```bash influxd-ctl backup -db myfirstdb ./myfirstdb-allrp-backup +``` + +#### Back up a database with a specific retention policy + +The following example stores incremental backups in separate directories for the +specified database and retention policy combinations. + +```bash +influxd-ctl backup -db myfirstdb -rp oneday ./myfirstdb-oneday-backup influxd-ctl backup -db myfirstdb -rp autogen ./myfirstdb-autogen-backup ``` -#### Back up a database with a specific retention policy -Store the following incremental backups in the same directory. -Both backups specify the same `-db` flag and the same database. +The output contains the status and backup file paths--for example: -```bash -influxd-ctl backup -db myfirstdb ./myfirstdb-allrp-backup - -influxd-ctl backup -db myfirstdb ./myfirstdb-allrp-backup +```sh +backing up db=myfirstdb rp=oneday shard=8 to /myfirstdb-oneday-backup/myfirstdb.oneday.00008.00 +backing up db=myfirstdb rp=autogen shard=10 to /myfirstdb-autogen-backup/myfirstdb.autogen.00010.00 ``` + #### Back up data from a specific time range To back up data in a specific time range, use the `-start` and `-end` options: ```bash influxd-ctl backup -db myfirstdb ./myfirstdb-jandata -start 2022-01-01T012:00:00Z -end 2022-01-31T011:59:00Z - ``` + #### Perform an incremental backup -Perform an incremental backup into the current directory with the command below. -If there are any existing backups the current directory, the system performs an incremental backup. -If there aren't any existing backups in the current directory, the system performs a backup of all data in InfluxDB. +The incremental backup strategy (default, `-strategy=incremental`) checks for existing backup files in the specified directory. + +- If a backup exists, `influxd-ctl` performs an incremental backup, saving only the data that has changed since the most recent backup file. +- If no backup exists, it creates a full backup of all data in InfluxDB. + +The following example shows how to run an incremental backup stored in the current directory: ```bash # Syntax @@ -156,7 +187,7 @@ $ ls #### Perform a full backup -Perform a full backup into a specific directory with the command below. +The following example shows how to run a full backup stored in a specific directory. The directory must already exist. ```bash @@ -178,7 +209,11 @@ $ ls backup_dir #### Perform an incremental backup on a single database -Point at a remote meta server and back up only one database into a given directory (the directory must already exist): +Use the `-bind` option to specify a remote [meta node](/enterprise_influxdb/v1/concepts/glossary/#meta-node) to connect to. + +The following example shows how to connect to a remote meta server and back up +a specific database into a given directory in the local system. +The directory must already exist. ```bash # Syntax @@ -195,7 +230,8 @@ $ ls ./telegrafbackup #### Perform a metadata only backup -Perform a metadata only backup into a specific directory with the command below. +The following example shows how to create and store a metadata-only backup +in a specific directory. The directory must already exist. ```bash @@ -213,10 +249,10 @@ Backed up to backup_dir in 51.388233ms, transferred 481 bytes ### Restore utility -#### Disable anti-entropy (AE) before restoring a backup - +> [!Note] +> #### Disable anti-entropy (AE) before restoring a backup +> > Before restoring a backup, stop the anti-entropy (AE) service (if enabled) on **each data node in the cluster, one at a time**. - > > 1. Stop the `influxd` service. > 2. Set `[anti-entropy].enabled` to `false` in the influx configuration file (by default, influx.conf). @@ -469,48 +505,78 @@ for [restoring from a full backup](#restore-from-a-full-backup). ## Exporting and importing data -For most InfluxDB Enterprise applications, the [backup and restore utilities](#backup-and-restore-utilities) provide the tools you need for your backup and restore strategy. However, in some cases, the standard backup and restore utilities may not adequately handle the volumes of data in your application. +For most InfluxDB Enterprise applications, the [backup and restore utilities](#backup-and-restore-utilities) provide the tools you need for your backup and restore strategy. However, in some cases, the standard backup and restore utilities might not adequately handle the volumes of data in your application. As an alternative to the standard backup and restore utilities, use the InfluxDB `influx_inspect export` and `influx -import` commands to create backup and restore procedures for your disaster recovery and backup strategy. These commands can be executed manually or included in shell scripts that run the export and import operations at scheduled intervals (example below). +- [Exporting data](#exporting-data) +- [Importing data](#importing-data) +- [Example: export and import for disaster recovery](#example-export-and-import-for-disaster-recovery) + ### Exporting data -Use the [`influx_inspect export` command](/enterprise_influxdb/v1/tools/influx_inspect#export) to export data in line protocol format from your InfluxDB Enterprise cluster. Options include: +Use the [`influx_inspect export` command](/enterprise_influxdb/v1/tools/influx_inspect#export) to export data in line protocol format from your InfluxDB Enterprise cluster. +Options include the following: -- Exporting all, or specific, databases -- Filtering with starting and ending timestamps -- Using gzip compression for smaller files and faster exports +- `-database`: Export all or specific databases +- `-start` and `-end`: Filter with starting and ending timestamps +- `-compress`: Use GNU zip (gzip) compression for smaller files and faster exports -For details on optional settings and usage, see [`influx_inspect export` command](/enterprise_influxdb/v1/tools/influx_inspect#export). - -In the following example, the database is exported filtered to include only one day and compressed for optimal speed and file size. +The following example shows how to export data filtered to one day and compressed +for optimal speed and file size: ```bash influx_inspect export \ - -database myDB \ + -database DATABASE_NAME \ -compress \ -start 2019-05-19T00:00:00.000Z \ -end 2019-05-19T23:59:59.999Z ``` -### Importing data +The exported file contains the following: -After exporting the data in line protocol format, you can import the data using the [`influx -import` CLI command](/enterprise_influxdb/v1/tools/influx-cli/use-influx/#import-data-from-a-file-with--import). +```sh +# DDL +CREATE DATABASE WITH NAME +# DML +# CONTEXT-DATABASE: +# CONTEXT-RETENTION-POLICY: -In the following example, the compressed data file is imported into the specified database. - -```bash -influx -import -database myDB -compressed + ``` -For details on using the `influx -import` command, see [Import data from a file with -import](/enterprise_influxdb/v1/tools/influx-cli/use-influx/#import-data-from-a-file-with--import). +- `DDL`: an InfluxQL `CREATE` statement to create the target database when [importing the data](#importing-data) +- `DML`: Context metadata that specifies the target database and retention policy + for [importing the data](#importing-data) +- the line protocol data -### Example +For details on optional settings and usage, see [`influx_inspect export` command](/enterprise_influxdb/v1/tools/influx_inspect#export). + +### Importing data -For an example of using the exporting and importing data approach for disaster recovery, see the Capital One presentation from Influxdays 2019 on ["Architecting for Disaster Recovery."](https://www.youtube.com/watch?v=LyQDhSdnm4A). In this presentation, Capital One discusses the following: +To import line protocol data from a file, use the [`influx -import` CLI command](/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli/#influx-arguments). -- Exporting data every 15 minutes from an active cluster to an AWS S3 bucket. +In your import file, include the following sections: + +- _Optional_: **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/enterprise_influxdb/v1/query_language/manage-database/) for creating the relevant [database](/enterprise_influxdb/v1/concepts/glossary/#database) and managing the [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). +If your database and retention policy already exist, your file can skip this section. +- **DML (Data Manipulation Language)**: Context metadata that specifies the database and (if desired) retention policy for the import and contains the data in [line protocol](/enterprise_influxdb/v1/concepts/glossary/#influxdb-line-protocol). + +In the following example, the compressed data file (in GNU zip format) is imported into the database +specified in the file's `DML` metadata. + +```bash +influx -import -path -compressed +``` + +For details on using the `influx -import` command, see [Import data from a file](/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli/#import-data-from-a-file). + +### Example: export and import for disaster recovery + +For an example of using the exporting and importing data approach for disaster recovery, see the presentation from Influxdays 2019 on ["Architecting for Disaster Recovery."](https://www.youtube.com/watch?v=LyQDhSdnm4A). In this presentation, Capital One discusses the following: + +- Exporting data every 15 minutes from an active InfluxDB Enterprise cluster to an AWS S3 bucket. - Replicating the export file in the S3 bucket using the AWS S3 copy command. -- Importing data every 15 minutes from the AWS S3 bucket to a cluster available for disaster recovery. +- Importing data every 15 minutes from the AWS S3 bucket to an InfluxDB Enterprise cluster available for disaster recovery. - Advantages of the export-import approach over the standard backup and restore utilities for large volumes of data. - Managing users and scheduled exports and imports with a custom administration tool. diff --git a/content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md b/content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md index 9128afa92..f45460a4d 100644 --- a/content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md +++ b/content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md @@ -1650,21 +1650,25 @@ Number of queries allowed to execute concurrently. Default is `0`. #### query-initial-memory-bytes + Initial bytes of memory allocated for a query. `0` means unlimited. Default is `0`. #### query-max-memory-bytes + Maximum total bytes of memory allowed for an individual query. `0` means unlimited. Default is `0`. #### total-max-memory-bytes + Maximum total bytes of memory allowed for all running Flux queries. `0` means unlimited. Default is `0`. #### query-queue-size + Maximum number of queries allowed in execution queue. When queue limit is reached, new queries are rejected. `0` means unlimited. diff --git a/content/enterprise_influxdb/v1/administration/configure/config-meta-nodes.md b/content/enterprise_influxdb/v1/administration/configure/config-meta-nodes.md index 04b719aae..25d83327c 100644 --- a/content/enterprise_influxdb/v1/administration/configure/config-meta-nodes.md +++ b/content/enterprise_influxdb/v1/administration/configure/config-meta-nodes.md @@ -1,5 +1,5 @@ --- -title: Configure InfluxDB Enterprise meta modes +title: Configure InfluxDB Enterprise meta nodes description: > Configure InfluxDB Enterprise data node settings and environmental variables. menu: diff --git a/content/enterprise_influxdb/v1/administration/configure/security/ldap.md b/content/enterprise_influxdb/v1/administration/configure/security/ldap.md index fab8292d0..5dd63ad63 100644 --- a/content/enterprise_influxdb/v1/administration/configure/security/ldap.md +++ b/content/enterprise_influxdb/v1/administration/configure/security/ldap.md @@ -175,6 +175,21 @@ enabled = true # Finally, "none" does not use TLS. This is not recommended for # production systems. security = "starttls" + + # Client certificates to present to the LDAP server are supported with + # "client-tls-certificate" and "client-tls-private-key" configurations. + # These are paths to the X.509 client certificate and corresponding private + # key, respectively. If "client-tls-certificate" is set but + # "client-tls-private-key" is not, then "client-tls-certificate" is assumed + # to bundle both the certificate and private key. + # The LDAP server may request and require valid client certificates + # even when InfluxDB is configured with an insecure TLS mode that ignores + # LDAP server certificate errors. + # Not all LDAP servers will request a client certificate. It is not + # necessary to set "client-tls-certificate" and "client-tls-private-key" + # if the LDAP server does not require client certificates. + client-tls-certificate = "/var/run/secrets/ldapClient.pem" + client-tls-private-key = "/var/run/secrets/ldapClient.key" # Client certificates to present to the LDAP server are supported with # "client-tls-certificate" and "client-tls-private-key" configurations. diff --git a/content/enterprise_influxdb/v1/administration/manage/clusters/rebalance.md b/content/enterprise_influxdb/v1/administration/manage/clusters/rebalance.md index a412874dc..db0b48532 100644 --- a/content/enterprise_influxdb/v1/administration/manage/clusters/rebalance.md +++ b/content/enterprise_influxdb/v1/administration/manage/clusters/rebalance.md @@ -100,7 +100,7 @@ The following command lists every shard in our cluster: influxd-ctl show-shards ``` -The expected output is similar to the items in the codeblock below: +The output is similar to the following: ``` Shards @@ -134,16 +134,19 @@ Take note of the cold shard's `ID` (for example: `22`) and the TCP address of one of its owners in the `Owners` column (for example: `enterprise-data-01:8088`). -> **Note:** -> -Use the following command string to determine the size of the shards in -your cluster: -> - find /var/lib/influxdb/data/ -mindepth 3 -type d -exec du -h {} \; +> [!Note] > +> To determine the size of shards in +> your cluster, enter the following command: +> +> ```bash +> find /var/lib/influxdb/data/ -mindepth 3 -type d -exec du -h {} \; +> ``` + In general, we recommend moving larger shards to the new data node to increase the available disk space on the original data nodes. -Users should note that moving shards will impact network traffic. + +_Moving shards will impact network traffic._ ### Step 3: Copy Cold Shards diff --git a/content/enterprise_influxdb/v1/administration/monitor/_index.md b/content/enterprise_influxdb/v1/administration/monitor/_index.md index 970db3fc4..a73e84907 100644 --- a/content/enterprise_influxdb/v1/administration/monitor/_index.md +++ b/content/enterprise_influxdb/v1/administration/monitor/_index.md @@ -12,7 +12,7 @@ Monitoring is the act of observing changes in data over time. There are multiple ways to monitor your InfluxDB Enterprise cluster. See the guides below to monitor a cluster using another InfluxDB instance. -Alternatively, to view your output data occasionally (_e.g._, for auditing or diagnostics), +Alternatively, to view your output data occasionally (for example, for auditing or diagnostics), do one of the following: - [Log and trace InfluxDB Enterprise operations](/enterprise_influxdb/v1/administration/monitor/logs/) @@ -22,7 +22,7 @@ do one of the following: ### Monitor with InfluxDB Insights For InfluxDB Enterprise customers, Insights is a free service that monitors your cluster and sends metrics to a private Cloud account. This allows InfluxDB Support to monitor your cluster health and access usage statistics when assisting with support tickets that you raise. -To apply for this service, please contact the [support team](https://support.influxdata.com/s/login/). +To apply for this service, please [contact InfluxData support](https://support.influxdata.com). {{% /note %}} {{< children >}} diff --git a/content/enterprise_influxdb/v1/administration/monitor/monitor-with-cloud.md b/content/enterprise_influxdb/v1/administration/monitor/monitor-with-cloud.md index 4b0984679..cd1020b06 100644 --- a/content/enterprise_influxdb/v1/administration/monitor/monitor-with-cloud.md +++ b/content/enterprise_influxdb/v1/administration/monitor/monitor-with-cloud.md @@ -182,4 +182,4 @@ Send a notification to PagerDuty or HTTP endpoints (other webhooks) by [upgradin For InfluxDB Enterprise customers, Insights is a free service that monitors your cluster and sends metrics to a private Cloud account. This allows InfluxDB Support to monitor your cluster health and access usage statistics when assisting with support tickets that you raise. -To apply for this service, please contact the [InfluxData Support team](mailto:support@influxdata.com). +To apply for this service, please [contact InfluxData support](https://support.influxdata.com). diff --git a/content/enterprise_influxdb/v1/concepts/glossary.md b/content/enterprise_influxdb/v1/concepts/glossary.md index dfa681991..6cc1fb5a1 100644 --- a/content/enterprise_influxdb/v1/concepts/glossary.md +++ b/content/enterprise_influxdb/v1/concepts/glossary.md @@ -449,8 +449,8 @@ Related entries: [tsm](#tsm-time-structured-merge-tree) ## web console -Legacy user interface for the InfluxDB Enterprise. +Legacy user interface for InfluxDB Enterprise. This interface has been deprecated. We recommend using [Chronograf](/chronograf/v1/introduction/). -If you are transitioning from the Enterprise Web Console to Chronograf, see how to [transition from the InfluxDB Web Admin Interface](/chronograf/v1/guides/transition-web-admin-interface/). +If you are transitioning from the Enterprise Web Console to Chronograf, see how to [connect Chronograf to an InfluxDB Enterprise cluster](/chronograf/v1/troubleshooting/frequently-asked-questions/#how-do-i-connect-chronograf-to-an-influxdb-enterprise-cluster). diff --git a/content/enterprise_influxdb/v1/flux/optimize-queries.md b/content/enterprise_influxdb/v1/flux/optimize-queries.md index 12bea3df0..7adf3ee82 100644 --- a/content/enterprise_influxdb/v1/flux/optimize-queries.md +++ b/content/enterprise_influxdb/v1/flux/optimize-queries.md @@ -22,9 +22,14 @@ Optimize your Flux queries to reduce their memory and compute (CPU) requirements - [Measure query performance with Flux profilers](#measure-query-performance-with-flux-profilers) ## Start queries with pushdowns -**Pushdowns** are functions or function combinations that push data operations to the underlying data source rather than operating on data in memory. Start queries with pushdowns to improve query performance. Once a non-pushdown function runs, Flux pulls data into memory and runs all subsequent operations there. + +**Pushdowns** are functions or function combinations that push data operations +to the underlying data source rather than operating on data in memory. +Start queries with pushdowns to improve query performance. Once a non-pushdown +function runs, Flux pulls data into memory and runs all subsequent operations there. #### Pushdown functions and function combinations + The following pushdowns are supported in InfluxDB Enterprise 1.10+. | Functions | Supported | @@ -63,6 +68,7 @@ Once a non-pushdown function runs, Flux pulls data into memory and runs all subsequent operations there. ##### Pushdown functions in use + ```js from(bucket: "db/rp") |> range(start: -1h) // @@ -75,6 +81,7 @@ from(bucket: "db/rp") ``` ### Avoid processing filters inline + Avoid using mathematic operations or string manipulation inline to define data filters. Processing filter values inline prevents `filter()` from pushing its operation down to the underlying data source, so data returned by the @@ -104,12 +111,14 @@ from(bucket: "db/rp") ``` ## Avoid short window durations + Windowing (grouping data based on time intervals) is commonly used to aggregate and downsample data. Increase performance by avoiding short window durations. More windows require more compute power to evaluate which window each row should be assigned to. Reasonable window durations depend on the total time range queried. ## Use "heavy" functions sparingly + The following functions use more memory or CPU than others. Consider their necessity in your data processing before using them: @@ -120,6 +129,7 @@ Consider their necessity in your data processing before using them: - [pivot()](/influxdb/v2/reference/flux/stdlib/built-in/transformations/pivot/) ## Use set() instead of map() when possible + [`set()`](/influxdb/v2/reference/flux/stdlib/built-in/transformations/set/), [`experimental.set()`](/influxdb/v2/reference/flux/stdlib/experimental/set/), and [`map`](/influxdb/v2/reference/flux/stdlib/built-in/transformations/map/) @@ -132,6 +142,7 @@ Use the following guidelines to determine which to use: - If dynamically setting a column value using **existing row data**, use `map()`. #### Set a column value to a static value + The following queries are functionally the same, but using `set()` is more performant than using `map()`. ```js @@ -144,12 +155,14 @@ data ``` #### Dynamically set a column value using existing row data + ```js data |> map(fn: (r) => ({ r with foo: r.bar })) ``` ## Balance time range and data precision + To ensure queries are performant, balance the time range and the precision of your data. For example, if you query data stored every second and request six months worth of data, results would include ≈15.5 million points per series. @@ -160,7 +173,8 @@ Use [pushdowns](#pushdown-functions-and-function-combinations) to optimize how many points are stored in memory. ## Measure query performance with Flux profilers -Use the [Flux Profiler package](/influxdb/v2/reference/flux/stdlib/profiler/) + +Use the [Flux Profiler package](/flux/v0/stdlib/profiler/) to measure query performance and append performance metrics to your query output. The following Flux profilers are available: diff --git a/content/enterprise_influxdb/v1/guides/query_data.md b/content/enterprise_influxdb/v1/guides/query_data.md index 25585a4ac..65adedbda 100644 --- a/content/enterprise_influxdb/v1/guides/query_data.md +++ b/content/enterprise_influxdb/v1/guides/query_data.md @@ -1,14 +1,13 @@ --- title: Query data with the InfluxDB API description: Query data with Flux and InfluxQL in the InfluxDB API. -alias: - -/docs/v1.8/query_language/querying_data/ menu: enterprise_influxdb_v1: weight: 20 parent: Guides aliases: - /enterprise_influxdb/v1/guides/querying_data/ + - /docs/v1.8/query_language/querying_data/ v2: /influxdb/v2/query-data/ --- diff --git a/content/enterprise_influxdb/v1/introduction/installation/meta_node_installation.md b/content/enterprise_influxdb/v1/introduction/installation/meta_node_installation.md index 061dc38ad..36ec1fe85 100644 --- a/content/enterprise_influxdb/v1/introduction/installation/meta_node_installation.md +++ b/content/enterprise_influxdb/v1/introduction/installation/meta_node_installation.md @@ -47,11 +47,26 @@ for high availability and redundancy. We typically recommend three meta nodes. If your servers have chronic communication or reliability issues, you can try adding nodes. -{{% note %}} -Deploying multiple meta nodes on the same server is strongly discouraged -since it creates a larger point of potential failure if that particular server is unresponsive. -InfluxData recommends deploying meta nodes on relatively small footprint servers. -{{% /note %}} +> [!Note] +> +> #### Run meta nodes on separate servers +> +> Avoid deploying multiple meta nodes on the same server. +> Doing so increases the risk of failure if the server becomes unresponsive. +> InfluxData recommends deploying meta nodes on separate, low-resource servers +> to minimize risks and optimize performance. +> +> #### Using a single meta node for non-production environments +> +> Installing and running InfluxDB Enterprise on a single server, or node, is an +alternative to using [InfluxDB OSS 1.x](/influxdb/v1). +> To start a {{% product-name %}} cluster with a single meta node, +> pass the `-single-server flag` when starting the node. +> +> _A cluster with only one meta node is **not** recommended for +> production environments._ +> +> For more information, see how to [install InfluxDB Enterprise on a single server](/enterprise_influxdb/v1/introduction/installation/single-server/). _See [Clustering in InfluxDB Enterprise](/enterprise_influxdb/v1/concepts/clustering/) for more information about cluster architecture._ @@ -292,19 +307,12 @@ Run the following command to search for a running `influxdb-meta` process: ps aux | grep -v grep | grep influxdb-meta ``` -You should see output similar to: +The output is similar to the following: ``` influxdb 3207 0.8 4.4 483000 22168 ? Ssl 17:05 0:08 /usr/bin/influxd-meta -config /etc/influxdb/influxdb-meta.conf ``` -{{% note %}} -It is possible to start the cluster with a single meta node but you -must pass the `-single-server flag` when starting the single meta node. -Please note that a cluster with only one meta node is **not** recommended for -production environments. -{{% /note %}} - {{% /expand %}} {{< /expand-wrapper >}} @@ -350,9 +358,9 @@ enterprise-meta-02:8091 {{< latest-patch >}}-c{{< latest-patch >}} enterprise-meta-03:8091 {{< latest-patch >}}-c{{< latest-patch >}} ``` -Note that your cluster must have at least three meta nodes. +_Your cluster must have at least three meta nodes. If you do not see your meta nodes in the output, retry adding them to -the cluster. +the cluster._ {{% /expand %}} {{< /expand-wrapper >}} diff --git a/content/enterprise_influxdb/v1/introduction/installation/single-server.md b/content/enterprise_influxdb/v1/introduction/installation/single-server.md index 8a0ad2f0a..3ebb48701 100644 --- a/content/enterprise_influxdb/v1/introduction/installation/single-server.md +++ b/content/enterprise_influxdb/v1/introduction/installation/single-server.md @@ -9,7 +9,7 @@ menu: parent: Install --- -Installing and running InfluxDB Enterprise on a single server or node is an +Installing and running InfluxDB Enterprise on a single server, or node, is an alternative to using [InfluxDB OSS 1.x](/influxdb/v1). InfluxDB Enterprise provides advanced functionality such as [LDAP authentication](/enterprise_influxdb/v1/administration/configure/security/ldap/), @@ -75,11 +75,11 @@ through server restarts. ## Set up, configure, and start the meta service The InfluxDB Enterprise meta process oversees and manages the InfluxDB Enterprise -data process. In multi-node clusters, meta nodes manage data syncing and high -availability of data nodes. In a single-node installation, the meta process +data process. In multi-node clusters, meta nodes (typically 3 nodes) manage data syncing and high +availability of data nodes. In a single-server (single-node) installation, a meta process and the accompanying [`influxd-ctl` utility](/enterprise_influxdb/v1/tools/influxd-ctl/) -still manage the "cluster", even though the meta and data processes exist on the -same server. +still manage the "cluster", but with a single meta node and the data +processes running on the same server. 1. **Download and install the InfluxDB Enterprise meta service**: @@ -174,10 +174,11 @@ The `license-key` and `license-path` settings are mutually exclusive and one mus internal-shared-secret = "" ``` -3. **Start the InfluxDB Enterprise meta service**: +3. **Start the InfluxDB Enterprise meta service in single-server mode**: - Run the command appropriate to your operating system's service manager. - + Run the `start` command appropriate to your operating system's service manager. + In the command, include the `-single-server` flag, which ensures that the single meta node + is the leader and has all the metadata for the cluster. {{< tabs-wrapper >}} {{% tabs "small" %}} @@ -185,24 +186,93 @@ The `license-key` and `license-path` settings are mutually exclusive and one mus [systemd](#) {{% /tabs %}} {{% tab-content %}} + +Edit the `influxdb-meta` init script to include the `-single-server` flag: - +1. Open the init script for editing, for example: -```sh -service influxdb-meta start -``` + ```bash + sudo nano /etc/init.d/influxdb-meta + ``` + +2. Find the section of the script that starts the `influxdb-meta` service and add the `-single-server` flag--for example: + + ```sh + case "$1" in + start) + echo "Starting InfluxDB Meta..." + /usr/bin/influxdb-meta -single-server & + ;; + stop) + echo "Stopping InfluxDB Meta..." + killall influxdb-meta + ;; + restart) + $0 stop + $0 start + ;; + *) + echo "Usage: $0 {start|stop|restart}" + exit 1 + esac + + exit 0 + ``` + +3. Restart the service to apply the changes: + + ```bash + sudo service influxdb-meta restart + ``` + +For more information about sysvinit and initscripts, see the [sysvinit](https://wiki.gentoo.org/wiki/Sysvinit) Gentoo Linux documentation. + {{% /tab-content %}} {{% tab-content %}} + +Edit the `influxdb-meta` service unit file or a drop-in configuration file to +include the `-single-server` flag--for example: - +1. Use `systemctl edit` with the `--drop-in` option to create the drop-in configuration file for the service: -```sh -sudo systemctl start influxdb-meta -``` + ```bash + sudo systemctl edit --drop-in influxdb-meta + ``` + +2. Add the following to the drop-in configuration file to include the -single-server flag in the startup command: + + ```systemd + [Service] + ExecStart= + ExecStart=/usr/bin/influxdb-meta -single-server + ``` + +3. Start the service using `systemctl`: + + ```bash + sudo systemctl start influxdb-meta + ``` + +4. Reload the Systemd Daemon: Reload the systemd daemon to apply the changes: + + ```bash + sudo systemctl daemon-reload + ``` + +5. Start the service using systemctl: + + ```bash + sudo systemctl start influxdb-meta + ``` + +For more information about systemd unit files, see the Arch Linux documentation +for [Writing unit files](https://wiki.archlinux.org/title/Systemd#Writing_unit_files) + + {{% /tab-content %}} {{< /tabs-wrapper >}} -4. **Ensure the `influxdb-meta` process is running**: +1. **Ensure the `influxdb-meta` process is running**: Use `ps aux` to list running processes and `grep` to filter the list of running process to those that contain `influxdb-meta` and filter out the @@ -218,7 +288,7 @@ sudo systemctl start influxdb-meta influxdb 3207 0.8 4.4 483000 22168 ? Ssl 17:05 0:08 /usr/bin/influxd-meta -config /etc/influxdb/influxdb-meta.conf ``` -5. **Use `influxd-ctl` to add the meta process to the InfluxDB Enterprise "cluster"**: +2. **Use `influxd-ctl` to add the meta process to the InfluxDB Enterprise "cluster"**: ```sh influxd-ctl add-meta :8091 @@ -230,7 +300,7 @@ sudo systemctl start influxdb-meta Added meta node x at :8091 ``` -6. **Use `influxd-ctl` to verify the meta node was added to the InfluxDB Enterprise "cluster"**: +3. **Use `influxd-ctl` to verify the meta node was added to the InfluxDB Enterprise "cluster"**: ```sh influxd-ctl show diff --git a/content/enterprise_influxdb/v1/introduction/installation_requirements.md b/content/enterprise_influxdb/v1/introduction/installation_requirements.md index 2e8a09634..966e0287a 100644 --- a/content/enterprise_influxdb/v1/introduction/installation_requirements.md +++ b/content/enterprise_influxdb/v1/introduction/installation_requirements.md @@ -31,11 +31,13 @@ The following are the most frequently overlooked requirements when installing a - [Synchronize time between hosts](#synchronize-time-between-hosts) - [Use SSDs](#use-ssds) - [Do not use NFS or NFS-based services](#do-not-use-nfs-or-nfs-based-services) +- [Do not use LVM](#do-not-use-lvm) - [Disable swap](#disable-swap) - [Use three and only three meta nodes](#use-three-and-only-three-meta-nodes) - [Meta and data nodes are fully independent](#meta-and-data-nodes-are-fully-independent) - [Install Chronograf last](#install-chronograf-last) + #### Ensure connectivity between machines All nodes in the cluster must be able to resolve each other by hostname or IP, @@ -64,6 +66,13 @@ or services such as [AWS EFS](https://aws.amazon.com/efs/), [Google Filestore](https://cloud.google.com/filestore), or [Azure files](https://azure.microsoft.com/en-us/services/storage/files/). +#### Do not use LVM + +Don't use LVM for software RAID, JBOD, or disk encryption. +These use cases can lead to performance issues. + +If you use LVM solely for creating logical volumes, use it with Device Mapper’s linear mapping for optimal performance. + #### Disable swap To avoid potential disk contention when InfluxDB is under high load, diff --git a/content/enterprise_influxdb/v1/tools/api.md b/content/enterprise_influxdb/v1/tools/api.md index 861a63620..b53ab3526 100644 --- a/content/enterprise_influxdb/v1/tools/api.md +++ b/content/enterprise_influxdb/v1/tools/api.md @@ -249,7 +249,7 @@ curl --request POST "http://localhost:8086/api/v2/delete?bucket=exampleDB/autoge }' ``` -If you use the `predicate` option in your request, review [delete predicate syntax](/influxdb/latest/reference/syntax/delete-predicate/) and note its [limitations](/influxdb/latest/reference/syntax/delete-predicate/#limitations). +If you use the `predicate` option in your request, review [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/) and note its [limitations](/influxdb/v2/reference/syntax/delete-predicate/#limitations). ## InfluxDB 1.x HTTP endpoints The following InfluxDB 1.x API endpoints are available: diff --git a/content/enterprise_influxdb/v1/tools/flux-vscode.md b/content/enterprise_influxdb/v1/tools/flux-vscode.md index a34f6e94d..506b24a61 100644 --- a/content/enterprise_influxdb/v1/tools/flux-vscode.md +++ b/content/enterprise_influxdb/v1/tools/flux-vscode.md @@ -18,15 +18,15 @@ provides Flux syntax highlighting, autocompletion, and a direct InfluxDB server integration that lets you run Flux scripts natively and show results in VS Code. {{% note %}} -#### Enable Flux in InfluxDB 1.8 -To use the Flux VS Code extension with InfluxDB 1.8, ensure Flux is enabled in +#### Enable Flux in InfluxDB 1.11 +To use the Flux VS Code extension with InfluxDB 1.11, ensure Flux is enabled in your InfluxDB configuration file. For more information, see [Enable Flux](/enterprise_influxdb/v1/flux/installation/). {{% /note %}} ##### On this page - [Install the Flux VS Code extension](#install-the-flux-vs-code-extension) -- [Connect to InfluxDB 1.8](#connect-to-influxdb-18) +- [Connect to InfluxDB 1.11](#connect-to-influxdb-111) - [Query InfluxDB from VS Code](#query-influxdb-from-vs-code) - [Explore your schema](#explore-your-schema) - [Debug Flux queries](#debug-flux-queries) @@ -38,7 +38,7 @@ The Flux VS Code extension is available in the **Visual Studio Marketplace**. For information about installing extensions from the Visual Studio marketplace, see the [Extension Marketplace documentation](https://code.visualstudio.com/docs/editor/extension-gallery). -## Connect to InfluxDB 1.8 +## Connect to InfluxDB 1.11 To create an InfluxDB connection in VS Code: 1. Open the **VS Code Command Pallet** ({{< keybind mac="⇧⌘P" other="Ctrl+Shift+P" >}}). diff --git a/content/enterprise_influxdb/v1/tools/influx-cli/_index.md b/content/enterprise_influxdb/v1/tools/influx-cli/_index.md index 4aaa7814f..e2f366db8 100644 --- a/content/enterprise_influxdb/v1/tools/influx-cli/_index.md +++ b/content/enterprise_influxdb/v1/tools/influx-cli/_index.md @@ -8,8 +8,8 @@ menu: v2: /influxdb/v2/reference/cli/influx/ --- -The `influx` command line interface (CLI) includes commands to manage many aspects of InfluxDB, including databases, organizations, users, and tasks. - +The `influx` command line interface (CLI) provides an interactive shell for the HTTP API associated with `influxd`. +It includes commands for writing and querying data, and managing many aspects of InfluxDB, including databases, organizations, and users. ## Usage @@ -17,7 +17,6 @@ The `influx` command line interface (CLI) includes commands to manage many aspec influx [flags] ``` - ## Flags {.no-shorthand} | Flag | Description | diff --git a/content/enterprise_influxdb/v1/tools/influx-cli/use-influx.md b/content/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli.md similarity index 72% rename from content/enterprise_influxdb/v1/tools/influx-cli/use-influx.md rename to content/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli.md index 506b5f7d6..899e8d239 100644 --- a/content/enterprise_influxdb/v1/tools/influx-cli/use-influx.md +++ b/content/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli.md @@ -1,40 +1,51 @@ --- title: Use influx - InfluxDB command line interface description: InfluxDB's command line interface (`influx`) is an interactive shell for the HTTP API. -aliases: - - /enterprise_influxdb/v1/tools/shell - - /enterprise_influxdb/v1/tools/use-influx/ menu: enterprise_influxdb_v1: - name: Use influx + name: Use influx CLI weight: 10 parent: influx +aliases: + - /enterprise_influxdb/v1/tools/influx-cli/use-influx/ + - /enterprise_influxdb/v1/tools/shell + - /enterprise_influxdb/v1/tools/use-influx/ +related: + - /enterprise_influxdb/v1/administration/backup-and-restore/ --- -InfluxDB's command line interface (`influx`) is an interactive shell for the HTTP API. -Use `influx` to write data (manually or from a file), query data interactively, and view query output in different formats. +The `influx` command line interface (CLI) provides an interactive shell for the HTTP API associated with `influxd`. +Use `influx` to write data (manually or from a file), query data interactively, view query output in different formats, and manage resources in InfluxDB. * [Launch `influx`](#launch-influx) * [`influx` Arguments](#influx-arguments) * [`influx` Commands](#influx-commands) ## Launch `influx` -If you [install](https://influxdata.com/downloads/) InfluxDB via a package manager, the CLI is installed at `/usr/bin/influx` (`/usr/local/bin/influx` on macOS). + +The `influx` CLI is included when you [install InfluxDB Enterprise](/enterprise_influxdb/v1/introduction/installation/). + +If you [install](https://influxdata.com/downloads/) InfluxDB via a package manager, the CLI is installed at `/usr/bin/influx` ( on macOS). To access the CLI, first launch the `influxd` database process and then launch `influx` in your terminal. -Once you've entered the shell and successfully connected to an InfluxDB node, you'll see the following output: -
-
+ ```bash -$ influx -Connected to http://localhost:8086 version {{< latest-patch >}} -InfluxDB shell version: {{< latest-patch >}} +influx ``` -> **Note:** The versions of InfluxDB and the CLI should be identical. If not, parsing issues can occur with queries. +If successfully connected to an InfluxDB node, the output is the following: -You can now enter InfluxQL queries as well as some CLI-specific commands directly in your terminal. -You can use `help` at any time to get a list of available commands. Use `Ctrl+C` to cancel if you want to cancel a long-running InfluxQL query. +```bash +Connected to http://localhost:8086 version {{< latest-patch >}} +InfluxDB shell version: {{< latest-patch >}} +> +``` + +_The versions of InfluxDB and the CLI should be identical. If not, parsing issues can occur with queries._ + +In the prompt, you can enter InfluxQL queries as well as CLI-specific commands. +Enter `help` to get a list of available commands. +Use `Ctrl+C` to cancel if you want to cancel a long-running InfluxQL query. ## Environment Variables @@ -67,11 +78,14 @@ List of host names that should **not** go through any proxy. If set to an asteri NO_PROXY=123.45.67.89,123.45.67.90 ``` -## `influx` Arguments -There are several arguments you can pass into `influx` when starting. -List them with `$ influx --help`. -The list below offers a brief discussion of each option. -We provide detailed information on `-execute`, `-format`, and `-import` at the end of this section. +## `influx` arguments + +Arguments specify connection, write, import, and output options for the CLI session. + +`influx` provides the following arguments: + +`-h`, `-help` +List `influx` arguments `-compressed` Set to true if the import file is compressed. @@ -96,8 +110,8 @@ The host to which `influx` connects. By default, InfluxDB runs on localhost. `-import` -Import new data from a file or import a previously [exported](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md) database from a file. -See [-import](#import-data-from-a-file-with--import). +Import new data or [exported data](/enterprise_influxdb/v1/administration/backup-and-restore/#exporting-data) from a file. +See [-import](#import-data-from-a-file). `-password 'password'` The password `influx` uses to connect to the server. @@ -107,7 +121,7 @@ variable. `-path` The path to the file to import. -Use with `-import`. +Use with [-import](#import-data-from-a-file). `-port 'port #'` The port to which `influx` connects. @@ -141,6 +155,12 @@ Alternatively, set the username for the CLI with the `INFLUX_USERNAME` environme `-version` Display the InfluxDB version and exit. +The following sections provide detailed examples for some arguments, including `-execute`, `-format`, and `-import`. + +- [Execute an InfluxQL command and quit with `-execute`](#execute-an-influxql-command-and-quit-with--execute) +- [Specify the format of the server responses with `-format`](#specify-the-format-of-the-server-responses-with--format) +- [Import data from a file](#import-data-from-a-file) + ### Execute an InfluxQL command and quit with `-execute` Execute queries that don't require a database specification: @@ -243,18 +263,19 @@ $ influx -format=json -pretty } ``` -### Import data from a file with `-import` +### Import data from a file -The import file has two sections: +An import file has two sections: -* **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/enterprise_influxdb/v1/query_language/manage-database/) for creating the relevant [database](/enterprise_influxdb/v1/concepts/glossary/) and managing the [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). +- _Optional_: **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/enterprise_influxdb/v1/query_language/manage-database/) for creating the relevant [database](/enterprise_influxdb/v1/concepts/glossary/) and managing the [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). If your database and retention policy already exist, your file can skip this section. -* **DML (Data Manipulation Language)**: Lists the relevant database and (if desired) retention policy and contains the data in [line protocol](/enterprise_influxdb/v1/concepts/glossary/#influxdb-line-protocol). +- **DML (Data Manipulation Language)**: Context metadata that specifies the database and (if desired) retention policy for the import and contains the data in [line protocol](/enterprise_influxdb/v1/concepts/glossary/#influxdb-line-protocol). -Example: +#### Example: import data from a file -File (`datarrr.txt`): -``` +The following `datarrr.txt` file is output using the [`influx_inspect export` command](/enterprise_influxdb/v1/tools/influx_inspect#export): + +```text # DDL CREATE DATABASE pirates CREATE RETENTION POLICY oneday ON pirates DURATION 1d REPLICATION 1 @@ -270,13 +291,17 @@ treasures,captain_id=tetra value=47 1439856000 treasures,captain_id=crunch value=109 1439858880 ``` -Command: -``` -$influx -import -path=datarrr.txt -precision=s +To import the file, enter the following command in your terminal: + +```bash +influx -import -path=datarrr.txt -precision=s ``` -Results: -``` +The data is imported into the database and retention policy specified in the `# DML` +context metadata. +The output is the following: + +```text 2015/12/22 12:25:06 Processed 2 commands 2015/12/22 12:25:06 Processed 5 inserts 2015/12/22 12:25:06 Failed 0 inserts @@ -289,18 +314,20 @@ Results: > Time elapsed: 56.740578415s. > Points per second (PPS): 54634 -Things to note about `-import`: +Keep the following in mind when using `-import`: -* Allow the database to ingest points by using `-pps` to set the number of points per second allowed by the import. By default, pps is zero and `influx` does not throttle importing. -* Imports work with `.gz` files, just include `-compressed` in the command. -* Include timestamps in the data file. InfluxDB will assign the same timestamp to points without a timestamp. This can lead to unintended [overwrite behavior](/enterprise_influxdb/v1/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points). -* If your data file has more than 5,000 points, it may be necessary to split that file into several files in order to write your data in batches to InfluxDB. -We recommend writing points in batches of 5,000 to 10,000 points. -Smaller batches, and more HTTP requests, will result in sub-optimal performance. -By default, the HTTP request times out after five seconds. -InfluxDB will still attempt to write the points after that time out but there will be no confirmation that they were successfully written. +- To throttle the import, use `-pps` to set the number of points per second to ingest. By default, pps is zero and `influx` does not throttle importing. +- To import a file compressed with `gzip` (GNU zip), include the -compressed flag. +- Include timestamps in the data file. + If points don’t include a timestamp, InfluxDB assigns the same timestamp to those points, which can result in unintended [duplicate points or overwrites](/enterprise_influxdb/v1/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points). +- If your data file contains more than 5,000 points, consider splitting it into smaller files to write data to InfluxDB in batches. + We recommend writing points in batches of 5,000 to 10,000 for optimal performance. + Writing smaller batches increases the number of HTTP requests, which can negatively impact performance. + By default, the HTTP request times out after five seconds. Although InfluxDB continues attempting to write the points after a timeout, you won’t receive confirmation of a successful write. -> **Note:** For how to export data from InfluxDB version 0.8.9, see [Exporting from 0.8.9](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md). +> **Note:** To export data from InfluxDB version 0.8.9, see [Exporting from 0.8.9](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md). + +For more information, see [exporting and importing data](/enterprise_influxdb/v1/administration/backup-and-restore/#exporting-and-importing-data). ## `influx` commands diff --git a/content/enterprise_influxdb/v1/tools/influx_inspect.md b/content/enterprise_influxdb/v1/tools/influx_inspect.md index d67469d12..0336aa9e4 100644 --- a/content/enterprise_influxdb/v1/tools/influx_inspect.md +++ b/content/enterprise_influxdb/v1/tools/influx_inspect.md @@ -29,18 +29,21 @@ influx_inspect [ [ command ] [ options ] ] The `influx_inspect` commands are summarized here, with links to detailed information on each of the commands. -* [`buildtsi`](#buildtsi): Converts in-memory (TSM-based) shards to TSI. -* [`deletetsm`](#deletetsm): Bulk deletes a measurement from a raw TSM file. -* [`dumptsi`](#dumptsi): Dumps low-level details about TSI files. -* [`dumptsm`](#dumptsm): Dumps low-level details about TSM files. -* [`dumptsmwal`](#dumptsmwal): Dump all data from a WAL file. -* [`export`](#export): Exports raw data from a shard in InfluxDB line protocol format. -* [`report`](#report): Displays a shard level report. -* [`report-disk`](#report-disk): Reports disk usage by shard and measurement. -* [`reporttsi`](#reporttsi): Reports on cardinality for measurements and shards. -* [`verify`](#verify): Verifies the integrity of TSM files. -* [`verify-seriesfile`](#verify-seriesfile): Verifies the integrity of series files. -* [`verify-tombstone`](#verify-tombstone): Verifies the integrity of tombstones. +- [`buildtsi`](#buildtsi): Converts in-memory (TSM-based) shards to TSI. +- [`check-schema`](#check-schema): Checks for type conflicts between shards. +- [`deletetsm`](#deletetsm): Bulk deletes a measurement from a raw TSM file. +- [`dumptsi`](#dumptsi): Dumps low-level details about TSI files. +- [`dumptsm`](#dumptsm): Dumps low-level details about TSM files. +- [`dumptsmwal`](#dumptsmwal): Dump all data from a WAL file. +- [`export`](#export): Exports raw data from a shard in InfluxDB line protocol format. +- [`merge-schema`](#merge-schema): Merges a set of schema files from the `check-schema` command. +- [`report`](#report): Displays a shard level report. +- [`report-db`](#report-db): Estimates InfluxDB Cloud (TSM) cardinality for a database. +- [`report-disk`](#report-disk): Reports disk usage by shard and measurement. +- [`reporttsi`](#reporttsi): Reports on cardinality for measurements and shards. +- [`verify`](#verify): Verifies the integrity of TSM files. +- [`verify-seriesfile`](#verify-seriesfile): Verifies the integrity of series files. +- [`verify-tombstone`](#verify-tombstone): Verifies the integrity of tombstones. ### `buildtsi` @@ -90,6 +93,9 @@ The name of the database. The path to the `data` directory. +Default value is `$HOME/.influxdb/data`. +See the [file system layout](/enterprise_influxdb/v1/concepts/file-system-layout/) for InfluxDB on your system. + ##### `[ -max-cache-size ]` The maximum size of the cache before it starts rejecting writes. @@ -117,28 +123,56 @@ Flag to enable output in verbose mode. The directory for the WAL (Write Ahead Log) files. +Default value is `$HOME/.influxdb/wal`. +See the [file system layout](/enterprise_influxdb/v1/concepts/file-system-layout/) for InfluxDB on your system. + #### Examples ##### Converting all shards on a node ``` -$ influx_inspect buildtsi -datadir ~/.influxdb/data -waldir ~/.influxdb/wal +$ influx_inspect buildtsi -datadir /var/lib/influxdb/data -waldir /var/lib/influxdb/wal ``` ##### Converting all shards for a database ``` -$ influx_inspect buildtsi -database mydb -datadir ~/.influxdb/data -waldir ~/.influxdb/wal +$ influx_inspect buildtsi -database mydb datadir /var/lib/influxdb/data -waldir /var/lib/influxdb/wal ``` ##### Converting a specific shard ``` -$ influx_inspect buildtsi -database stress -shard 1 -datadir ~/.influxdb/data -waldir ~/.influxdb/wal +$ influx_inspect buildtsi -database stress -shard 1 datadir /var/lib/influxdb/data -waldir /var/lib/influxdb/wal ``` +### `check-schema` + +Check for type conflicts between shards. + +#### Syntax + +``` +influx_inspect check-schema [ options ] +``` + +#### Options + +##### [ `-conflicts-file ` ] + +Filename conflicts data should be written to. Default is `conflicts.json`. + +##### [ `-path ` ] + +Directory path where `fields.idx` files are located. Default is the current +working directory `.`. + +##### [ `-schema-file ` ] + +Filename schema data should be written to. Default is `schema.json`. + ### `deletetsm` Use `deletetsm -measurement` to delete a measurement in a raw TSM file (from specified shards). @@ -350,7 +384,9 @@ Default value is `""`. ##### `-datadir ` The path to the `data` directory. -Default value is `"$HOME/.influxdb/data"`. + +Default value is `$HOME/.influxdb/data`. +See the [file system layout](/enterprise_influxdb/v1/concepts/file-system-layout/) for InfluxDB on your system. ##### [ `-end ` ] @@ -377,12 +413,12 @@ YYYY-MM-DDTHH:MM:SS+07:00 ##### [ `-lponly` ] Output data in line protocol format only. -Does not include comments or data definition language (DDL), like `CREATE DATABASE`. +Does not output data definition language (DDL) statements (such as `CREATE DATABASE`) or DML context metadata (such as `# CONTEXT-DATABASE`). ##### [ `-out ` ] The location for the export file. -Default value is `"$HOME/.influxdb/export"`. +Default value is `$HOME/.influxdb/export`. ##### [ `-retention ` ] @@ -396,7 +432,9 @@ The timestamp string must be in [RFC3339 format](https://tools.ietf.org/html/rfc ##### [ `-waldir ` ] Path to the [WAL](/enterprise_influxdb/v1/concepts/glossary/#wal-write-ahead-log) directory. -Default value is `"$HOME/.influxdb/wal"`. + +Default value is `$HOME/.influxdb/wal`. +See the [file system layout](/enterprise_influxdb/v1/concepts/file-system-layout/) for InfluxDB on your system. #### Examples @@ -409,23 +447,43 @@ influx_inspect export -compress ##### Export data from a specific database and retention policy ```bash -influx_inspect export -database mydb -retention autogen +influx_inspect export -database DATABASE_NAME -retention RETENTION_POLICY ``` ##### Output file ```bash # DDL -CREATE DATABASE MY_DB_NAME -CREATE RETENTION POLICY autogen ON MY_DB_NAME DURATION inf REPLICATION 1 +CREATE DATABASE DATABASE_NAME +CREATE RETENTION POLICY ON DURATION inf REPLICATION 1 # DML -# CONTEXT-DATABASE:MY_DB_NAME -# CONTEXT-RETENTION-POLICY:autogen +# CONTEXT-DATABASE:DATABASE_NAME +# CONTEXT-RETENTION-POLICY:RETENTION_POLICY randset value=97.9296104805 1439856000000000000 randset value=25.3849066842 1439856100000000000 ``` +### `merge-schema` + +Merge a set of schema files from the [`check-schema` command](#check-schema). + +#### Syntax + +``` +influx_inspect merge-schema [ options ] +``` + +#### Options + +##### [ `-conflicts-file ` ] + +Filename conflicts data should be written to. Default is `conflicts.json`. + +##### [ `-schema-file ` ] + +Filename for the output file. Default is `schema.json`. + ### `report` Displays series metadata for all shards. @@ -461,6 +519,48 @@ The flag to report exact cardinality counts instead of estimates. Default value is `false`. Note: This can use a lot of memory. +### `report-db` + +Use the `report-db` command to estimate the series cardinality of data in a +database when migrated to InfluxDB Cloud (TSM). InfluxDB Cloud (TSM) includes +field keys in the series key so unique field keys affect the total cardinality. +The total series cardinality of data in a InfluxDB 1.x database may differ from +from the series cardinality of that same data when migrated to InfluxDB Cloud (TSM). + +#### Syntax + +``` +influx_inspect report-db [ options ] +``` + +#### Options + +##### [ `-c ` ] + +Set worker concurrency. Default is `1`. + +##### `-db-path ` + +{{< req >}}: The path to the database. + +##### [ `-detailed` ] + +Include counts for fields, tags in the command output. + +##### [ `-exact` ] + +Report exact cardinality counts instead of estimates. +This method of calculation can use a lot of memory. + +##### [ `-rollup ` ] + +Specify the cardinality "rollup" level--the granularity of the cardinality report: + +- `t`: total +- `d`: database +- `r`: retention policy +- `m`: measurement (Default) + ### `report-disk` Use the `report-disk` command to review TSM file disk usage per shard and measurement in a specified directory. Useful for capacity planning and identifying which measurement or shard is using the most disk space. The default directory path `~/.influxdb/data/`. diff --git a/content/example.md b/content/example.md index 54aa4ed0e..d484b26f8 100644 --- a/content/example.md +++ b/content/example.md @@ -2,12 +2,11 @@ title: Example post description: This is just an example post to show the format of new 2.0 posts weight: 1 -draft: true related: - /influxdb/v2/write-data/ - /influxdb/v2/write-data/quick-start - https://influxdata.com, This is an external link -products: [cloud, oss, enterprise] +draft: true --- This is a paragraph. Lorem ipsum dolor ({{< icon "trash" "v2" >}}) sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. @@ -18,7 +17,7 @@ This is a paragraph. Lorem ipsum dolor ({{< icon "trash" "v2" >}}) sit amet, con This is **bold** text. This is _italic_ text. This is _**bold and italic**_. -### Clockface 3.x icons +### Clockface v2 icons {{< nav-icon "account" "v2" >}} {{< nav-icon "data" "v2" >}} @@ -93,7 +92,7 @@ This is **bold** text. This is _italic_ text. This is _**bold and italic**_. {{< icon "wrench" "v2" >}} wrench {{< icon "x" "v2" >}} x -### Clockface 3.x icons +### Clockface v3 icons {{< nav-icon "account" "v3" >}} {{< nav-icon "data" "v3" >}} @@ -175,7 +174,7 @@ This is **bold** text. This is _italic_ text. This is _**bold and italic**_. {{< icon "wrench" "v3" >}} wrench {{< icon "x" "v3" >}} x -### Clockface 4.x icons +### Clockface v4 icons {{< nav-icon "account" >}} {{< nav-icon "data" >}} @@ -254,11 +253,21 @@ This is **bold** text. This is _italic_ text. This is _**bold and italic**_. {{< icon "x" >}} x ## h2 This is a header2 -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. + +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. #### Here's a title for this codeblock + {{< code-tabs-wrapper >}} {{% code-tabs %}} [Flux](#) @@ -283,31 +292,65 @@ WHERE time > now() - 15m {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} -{{% enterprise %}} ### h3 This is a header3 -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. + +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. ![Test image](/img/chronograf/1-6-alerts-conditions.png) -{{< img-hd src="/img/test-image-2.png" alt="Test Image" />}} +{{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Test Image" />}} -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. -{{% /enterprise %}} +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. #### h4 This is a header4 -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. [Link to h2](#h2-this-is-a-header2) +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. + +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. [Link to h2](#h2-this-is-a-header2) ##### h5 This is a header5 -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. + +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. ###### h6 This is a header6 -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo. -This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, vel tempor odio dolor blandit justo.This is a paragraph +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. + +This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nunc rutrum, metus id scelerisque euismod, erat ante suscipit nibh, ac congue +enim risus id est. Etiam tristique nisi et tristique auctor. Morbi eu bibendum +erat. Sed ullamcorper, dui id lobortis efficitur, mauris odio pharetra neque, +vel tempor odio dolor blandit justo. --- @@ -315,8 +358,8 @@ There is a horizontal rule above and below this line. --- -{{% cloud %}} #### Inline Styles + This is an [inline link](#). This is `inline code`. This is an [`inline code link`](#). This is an [`inline code link` with text in the link](#). @@ -331,40 +374,40 @@ This is **bold**. This is _italic_. 2. Ordered list item nested 2 3. Ordered list item nested 3 - Unordered list line-item 3 -- Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. +- Unordered list line-item with multiple paragraphs. + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. + Etiam tristique nisi et tristique auctor. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. + Etiam tristique nisi et tristique auctor. -- Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. +- Unordered list line-item with multiple paragraphs. + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. + Etiam tristique nisi et tristique auctor. + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. + Etiam tristique nisi et tristique auctor. + 1. Ordered list line-item 1 2. Ordered list line-item 2 - 1. Ordered list line-item 2.1 - 2. Ordered list line-item 2.2 - 3. Ordered list line-item 2.3 _(this is just an li, no p tag)_ - - Unordered list item nested 1 - - Unordered list item nested 2 - - Unordered list item nested 3 - 4. Ordered list line-item 2.4 with hard return. - - - Unordered list item nested 1 - - Unordered list item nested 2 - - Unordered list item nested 3 - - With Another paragraph. - + 1. Ordered list line-item 2.1 + 2. Ordered list line-item 2.2 + 3. Ordered list line-item 2.3 _(this is just an li, no p tag)_ + - Unordered list item nested 1 + - Unordered list item nested 2 + - Unordered list item nested 3 + 4. Ordered list line-item 2.4 with hard return. + + - Unordered list item nested 1 + - Unordered list item nested 2 + - Unordered list item nested 3 + + With Another paragraph. + 3. Ordered list line-item 3 4. Ordered list line-item with multiple paragraphs. Lorem ipsum dolor sit amet, consectetur adipiscing elit. @@ -383,159 +426,280 @@ This is **bold**. This is _italic_. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. Etiam tristique nisi et tristique auctor. + + ```js + // This is a code block + cpu = from(bucket:"example-bucket") + |> range(start:-30m) + |> filter(fn:(r) => r._measurement == "cpu") + |> filter(fn:(r) => r._measurement == "cpu") |> filter(fn:(r) => r._measurement == "cpu") + + avg_cpu = cpu |> window(every:5m) |> mean() + + avg_cpu + |> group(none:true) + |> yield() + // + ``` + + ###### Here's a codeblock with a title + ```js + // This is a code block + cpu = from(bucket:"example-bucket") + |> range(start:-30m) + |> filter(fn:(r) => r._measurement == "cpu") + + avg_cpu = cpu |> window(every:5m) |> mean() + + avg_cpu + |> group(none:true) + |> yield() + // + ``` + + --- + +## Alert blocks + +> [!NOTE] +> This is a **Note**. +> Useful information that users should know, even when skimming content. + +> [!TIP] +> This is a **Tip**. +> Helpful advice for doing things better or more easily. + +> [!IMPORTANT] +> This is an **Important**. +> Key information users need to know to achieve their goal. + +> [!WARNING] +> This is a **Warning**. +> Urgent info that needs immediate user attention to avoid problems. + +> [!CAUTION] +> This is a **Caution**. +> Advises about risks or negative outcomes of certain actions. + + --- + +> [!Note] +> This is a basic note. + +> [!Note] +> ## h2 This is a header2 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ### h3 This is a header3 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ![Test image](/img/chronograf/1-6-alerts-conditions.png) +> +> {{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Test Image" />}} +> +> #### h4 This is a header4 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ##### h5 This is a header5 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ###### h6 This is a header6 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> +> #### Inline Styles +> This is an [inline link](#). This is `inline code`. +> This is an [`inline code link`](#) . +> This is **bold**. This is _italic_. +> +> - Unordered list line-item 1 +> - Unordered list line-item 2 +> - Unordered list line-item 2.1 +> - Unordered list line-item 2.2 +> - Unordered list line-item 2.3 +> - Unordered list line-item 3 +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 1. Unordered list line-item 1 +> 2. Unordered list line-item 2 +> 1. Unordered list line-item 2.1 +> 2. Unordered list line-item 2.2 +> 3. Unordered list line-item 2.3 +> 3. Unordered list line-item 3 +> 4. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 5. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[tab1](#) +[tab2](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```js -// This is a code block +// This is a code block inside of a blockquote cpu = from(bucket:"example-bucket") |> range(start:-30m) - |> filter(fn:(r) => r._measurement == "cpu") - |> filter(fn:(r) => r._measurement == "cpu") |> filter(fn:(r) => r._measurement == "cpu") |> filter(fn:(r) => r._measurement == "cpu") - -avg_cpu = cpu |> window(every:5m) |> mean() - -avg_cpu - |> group(none:true) - |> yield() -// + |> filter(fn:(r) => r._measurement == "cpu" and r._field == "someReallyLongFieldName") ``` - -###### Here's a codeblock with a title +{{% /code-tab-content %}} +{{% code-tab-content %}} ```js -// This is a code block -cpu = from(bucket:"example-bucket") +// This is a code block inside of a blockquote +cpu = from(bucket:"my-bucket") |> range(start:-30m) |> filter(fn:(r) => r._measurement == "cpu") - -avg_cpu = cpu |> window(every:5m) |> mean() - -avg_cpu - |> group(none:true) - |> yield() -// ``` -{{% /cloud %}} - -{{% enterprise %}} -###### This is a table -| Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | -| -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -| Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | -| Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | -| Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | -| Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | -| Row 5.1 | `Row 5.2` | Row 5.3 | Row 5.4 | Row 5.1 | `Row 5.2` | Row 5.3 | Row 5.4 | - -###### This is a table with lots of stuff -| Column 1 | Column 2 | Column 3 | Column 4 | -| -------- | -------- | -------- | -------- | -| Row 1.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | -| Row 2.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | -| Row 3.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | -| Row 4.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | - -> This is a basic block quote - -Paragraph after a blockquote. Lorem ipsum dolor sit amet, consectetur adipiscing elit. -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -> This is a multiple paragraph blockquote with internal elements. -> Lorem ipsum dolor sit amet, consectetur adipiscing elit. -> Lorem ipsum dolor sit amet, consectetur adipiscing elit. -> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} +> +> ###### This is a table > +> | Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | +> | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | +> | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | +> | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | +> | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | +> +> ###### This is a table with lots of stuff +> +> | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | +> | Row 1.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 2.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 3.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 4.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | + +--- + +> [!Tip] +> This is a basic tip. + +> [!Tip] +> ## h2 This is a header2 > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. > Etiam tristique nisi et tristique auctor. +> +> ### h3 This is a header3 > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. > Etiam tristique nisi et tristique auctor. - -{{% note %}} -This is a basic note. -{{% /note %}} -{{% /enterprise %}} - -{{% note %}} -## h2 This is a header2 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -### h3 This is a header3 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -{{< img-hd src="/img/test-image-2.png" alt="Test Image" />}} - -#### h4 This is a header4 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -##### h5 This is a header5 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -###### h6 This is a header6 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - +> +> ![Test image](/img/chronograf/1-6-alerts-conditions.png) +> +> {{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Test Image" />}} +> +> #### h4 This is a header4 > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. > Etiam tristique nisi et tristique auctor. +> +> ##### h5 This is a header5 > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. > Etiam tristique nisi et tristique auctor. - -#### Inline Styles -This is an [inline link](#). This is `inline code`. -This is an [`inline code link`](#) . -This is **bold**. This is _italic_. - -- Unordered list line-item 1 -- Unordered list line-item 2 - - Unordered list line-item 2.1 - - Unordered list line-item 2.2 - - Unordered list line-item 2.3 -- Unordered list line-item 3 -- Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -- Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -1. Unordered list line-item 1 -2. Unordered list line-item 2 - 1. Unordered list line-item 2.1 - 2. Unordered list line-item 2.2 - 3. Unordered list line-item 2.3 -3. Unordered list line-item 3 -4. Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -5. Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -{{< code-tabs-wrapper >}} +> +> ###### h6 This is a header6 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> +> #### Inline Styles +> This is an [inline link](#). This is `inline code`. +> This is an [`inline code link`](#) . +> This is **bold**. This is _italic_. +> +> - Unordered list line-item 1 +> - Unordered list line-item 2 +> - Unordered list line-item 2.1 +> - Unordered list line-item 2.2 +> - Unordered list line-item 2.3 +> - Unordered list line-item 3 +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 1. Unordered list line-item 1 +> 2. Unordered list line-item 2 +> 1. Unordered list line-item 2.1 +> 2. Unordered list line-item 2.2 +> 3. Unordered list line-item 2.3 +> 3. Unordered list line-item 3 +> 4. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 5. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> {{< code-tabs-wrapper >}} {{% code-tabs %}} [tab1](#) [tab2](#) @@ -557,114 +721,114 @@ cpu = from(bucket:"my-bucket") ``` {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +> +> ###### This is a table +> +> | Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | +> | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | +> | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | +> | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | +> | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | +> +> ###### This is a table with lots of stuff +> +> | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | +> | Row 1.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 2.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 3.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 4.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | -###### This is a table in a blockquote -| Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | -| -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -| Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | -| Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | -| Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | -| Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | +--- -{{% /note %}} - -{{% warn %}} -This is a basic warning. -{{% /warn %}} - - -{{% warn %}} -This is a multiple paragraph blockquote with internal elements. -Lorem ipsum dolor sit amet, consectetur adipiscing elit. -Lorem ipsum dolor sit amet, consectetur adipiscing elit. -Lorem ipsum dolor sit amet, consectetur adipiscing elit. - -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -## h2 This is a header2 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -{{< img-hd src="/img/test-image-2.png" alt="Test Image" />}} - -### h3 This is a header3 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -#### h4 This is a header4 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -##### h5 This is a header5 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -###### h6 This is a header6 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. +> [!Important] +> This is a basic important block. +> [!Important] +> ## h2 This is a header2 > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. > Etiam tristique nisi et tristique auctor. +> +> ### h3 This is a header3 > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. > Etiam tristique nisi et tristique auctor. - -#### Inline Styles -This is an [inline link](#). This is `inline code`. -This is an [`inline code link`](#) . -This is **bold**. This is _italic_. - -- Unordered list line-item 1 -- Unordered list line-item 2 - - Unordered list line-item 2.1 - - Unordered list line-item 2.2 - - Unordered list line-item 2.3 -- Unordered list line-item 3 -- Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -- Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -1. Unordered list line-item 1 -2. Unordered list line-item 2 - 1. Unordered list line-item 2.1 - 2. Unordered list line-item 2.2 - 3. Unordered list line-item 2.3 -3. Unordered list line-item 3 -4. Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -5. Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -{{< code-tabs-wrapper >}} +> +> ![Test image](/img/chronograf/1-6-alerts-conditions.png) +> +> {{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Test Image" />}} +> +> #### h4 This is a header4 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ##### h5 This is a header5 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ###### h6 This is a header6 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> +> #### Inline Styles +> This is an [inline link](#). This is `inline code`. +> This is an [`inline code link`](#) . +> This is **bold**. This is _italic_. +> +> - Unordered list line-item 1 +> - Unordered list line-item 2 +> - Unordered list line-item 2.1 +> - Unordered list line-item 2.2 +> - Unordered list line-item 2.3 +> - Unordered list line-item 3 +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 1. Unordered list line-item 1 +> 2. Unordered list line-item 2 +> 1. Unordered list line-item 2.1 +> 2. Unordered list line-item 2.2 +> 3. Unordered list line-item 2.3 +> 3. Unordered list line-item 3 +> 4. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 5. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> {{< code-tabs-wrapper >}} {{% code-tabs %}} [tab1](#) [tab2](#) @@ -686,109 +850,116 @@ cpu = from(bucket:"my-bucket") ``` {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +> +> ###### This is a table +> +> | Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | +> | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | +> | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | +> | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | +> | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | +> +> ###### This is a table with lots of stuff +> +> | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | +> | Row 1.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 2.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 3.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 4.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | -###### This is a table in a blockquote -| Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | -| -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -| Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | -| Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | -| Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | -| Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | -{{% /warn %}} -{{% cloud %}} -This is a multiple paragraph blockquote with internal elements. -Lorem ipsum dolor sit amet, consectetur adipiscing elit. -Lorem ipsum dolor sit amet, consectetur adipiscing elit. -Lorem ipsum dolor sit amet, consectetur adipiscing elit. +--- -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -## h2 This is a header2 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -{{< img-hd src="/img/test-image-2.png" alt="Test Image" />}} - -### h3 This is a header3 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -#### h4 This is a header4 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -##### h5 This is a header5 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. - -###### h6 This is a header6 -Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. -Etiam tristique nisi et tristique auctor. +> [!Warning] +> This is a basic warning. +> [!Warning] +> ## h2 This is a header2 > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. > Etiam tristique nisi et tristique auctor. +> +> ### h3 This is a header3 > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. > Etiam tristique nisi et tristique auctor. - -#### Inline Styles -This is an [inline link](#). This is `inline code`. -This is an [`inline code link`](#) . -This is **bold**. This is _italic_. - -- Unordered list line-item 1 -- Unordered list line-item 2 - - Unordered list line-item 2.1 - - Unordered list line-item 2.2 - - Unordered list line-item 2.3 -- Unordered list line-item 3 -- Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -- Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -1. Unordered list line-item 1 -2. Unordered list line-item 2 - 1. Unordered list line-item 2.1 - 2. Unordered list line-item 2.2 - 3. Unordered list line-item 2.3 -3. Unordered list line-item 3 -4. Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -5. Unordered list line-item with multiple paragraphs. - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. - Etiam tristique nisi et tristique auctor. - -{{< code-tabs-wrapper >}} +> +> ![Test image](/img/chronograf/1-6-alerts-conditions.png) +> +> {{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Test Image" />}} +> +> #### h4 This is a header4 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ##### h5 This is a header5 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ###### h6 This is a header6 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> +> #### Inline Styles +> This is an [inline link](#). This is `inline code`. +> This is an [`inline code link`](#) . +> This is **bold**. This is _italic_. +> +> - Unordered list line-item 1 +> - Unordered list line-item 2 +> - Unordered list line-item 2.1 +> - Unordered list line-item 2.2 +> - Unordered list line-item 2.3 +> - Unordered list line-item 3 +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 1. Unordered list line-item 1 +> 2. Unordered list line-item 2 +> 1. Unordered list line-item 2.1 +> 2. Unordered list line-item 2.2 +> 3. Unordered list line-item 2.3 +> 3. Unordered list line-item 3 +> 4. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 5. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> {{< code-tabs-wrapper >}} {{% code-tabs %}} [tab1](#) [tab2](#) @@ -810,16 +981,153 @@ cpu = from(bucket:"my-bucket") ``` {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +> +> ###### This is a table +> +> | Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | +> | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | +> | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | +> | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | +> | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | +> +> ###### This is a table with lots of stuff +> +> | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | +> | Row 1.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 2.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 3.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 4.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | -###### This is a table in a blockquote -| Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | -| -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -| Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | -| Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | -| Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | -| Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | +--- -{{% /cloud %}} +> [!Caution] +> This is a basic caution. + +> [!Caution] +> ## h2 This is a header2 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ### h3 This is a header3 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ![Test image](/img/chronograf/1-6-alerts-conditions.png) +> +> {{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Test Image" />}} +> +> #### h4 This is a header4 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ##### h5 This is a header5 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> ###### h6 This is a header6 +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> > Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> > Etiam tristique nisi et tristique auctor. +> +> #### Inline Styles +> This is an [inline link](#). This is `inline code`. +> This is an [`inline code link`](#) . +> This is **bold**. This is _italic_. +> +> - Unordered list line-item 1 +> - Unordered list line-item 2 +> - Unordered list line-item 2.1 +> - Unordered list line-item 2.2 +> - Unordered list line-item 2.3 +> - Unordered list line-item 3 +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> - Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 1. Unordered list line-item 1 +> 2. Unordered list line-item 2 +> 1. Unordered list line-item 2.1 +> 2. Unordered list line-item 2.2 +> 3. Unordered list line-item 2.3 +> 3. Unordered list line-item 3 +> 4. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> 5. Unordered list line-item with multiple paragraphs. +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. +> Nunc rutrum, metus id scelerisque euismod, erat ante, ac congue enim risus id est. +> Etiam tristique nisi et tristique auctor. +> +> {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[tab1](#) +[tab2](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```js +// This is a code block inside of a blockquote +cpu = from(bucket:"example-bucket") + |> range(start:-30m) + |> filter(fn:(r) => r._measurement == "cpu" and r._field == "someReallyLongFieldName") +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +// This is a code block inside of a blockquote +cpu = from(bucket:"my-bucket") + |> range(start:-30m) + |> filter(fn:(r) => r._measurement == "cpu") +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} +> +> ###### This is a table +> +> | Column 1 | Column 2 | Column 3 | Column 4 | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | +> | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | Row 1.1 | `Row 1.2` | Row 1.3 | Row 1.4 | +> | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | Row 2.1 | `Row 2.2` | Row 2.3 | Row 2.4 | +> | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | Row 3.1 | `Row 3.2` | Row 3.3 | Row 3.4 | +> | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | Row 4.1 | `Row 4.2` | Row 4.3 | Row 4.4 | +> +> ###### This is a table with lots of stuff +> +> | Column 1 | Column 2 | Column 3 | Column 4 | +> | -------- | -------- | -------- | -------- | +> | Row 1.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 1.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 2.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 2.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 3.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 3.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | +> | Row 4.1Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.2Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.3Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Row 4.4Lorem ipsum dolor sit amet, consectetur adipiscing elit. | {{< tabs-wrapper >}} {{% tabs %}} diff --git a/content/flux/v0/spec/options.md b/content/flux/v0/spec/options.md index ad243699e..93e4d7073 100644 --- a/content/flux/v0/spec/options.md +++ b/content/flux/v0/spec/options.md @@ -62,4 +62,9 @@ option location = timezone.fixed(offset: -5h) option location = timezone.location(name: "America/Denver") ``` +> [!Note] +> The `location` option only affects boundaries used for windowing, specifically around time shifts +> like daylight savings. It does not change timestamps in the `_time` column, which are always UTC. + + {{< page-nav prev="/flux/v0/spec/variables/" next="/flux/v0/spec/types/" >}} diff --git a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md index 0a1d5672f..c6c845c08 100644 --- a/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md +++ b/content/flux/v0/stdlib/influxdata/influxdb/cardinality.md @@ -1,7 +1,7 @@ --- title: influxdb.cardinality() function description: > - `influxdb.cardinality()` returns the series cardinality of data stored in InfluxDB. + `influxdb.cardinality()` returns the series cardinality of data retrieved from InfluxDB. menu: flux_v0_ref: name: influxdb.cardinality @@ -28,9 +28,16 @@ Fluxdoc syntax: https://github.com/influxdata/flux/blob/master/docs/fluxdoc.md -------------------------------------------------------------------------------> -`influxdb.cardinality()` returns the series cardinality of data stored in InfluxDB. +`influxdb.cardinality()` returns the series cardinality of data retrieved from InfluxDB. +{{% note %}} +Although this function is similar to InfluxQL's [`SHOW SERIES CARDINALITY`](/influxdb/v1/query_language/spec/#show-series-cardinality), +it works in a slightly different manner. + +`influxdb.cardinality()` is time bounded and reports the cardinality of data that matches the conditions passed into it rather than that of the bucket as a whole. +{{% /note %}} + ##### Function type signature @@ -107,6 +114,12 @@ The cardinality calculation excludes points that match the specified start time. Use a relative duration or absolute time. For example, `-1h` or `2019-08-28T22:00:00Z`. Durations are relative to `now()`. Default is `now()`. +{{% note %}} +The default value is `now()`, so any points that have been written into the future will +not be counted unless a future `stop` date is provided. +{{% /note %}} + + ### predicate Predicate function that filters records. @@ -120,15 +133,17 @@ Default is `(r) => true`. - [Query series cardinality in a bucket](#query-series-cardinality-in-a-bucket) - [Query series cardinality in a measurement//](#query-series-cardinality-in-a-measurement) - [Query series cardinality for a specific tag](#query-series-cardinality-for-a-specific-tag) +- [Query series cardinality of Data Written In the Last 4 Hours](#query-series-cardinality-of-data-written-in-the-last-4-hours) ### Query series cardinality in a bucket ```js import "influxdata/influxdb" -influxdb.cardinality(bucket: "example-bucket", start: -1y) +influxdb.cardinality(bucket: "example-bucket", start: time(v: 1)) ``` +Note: if points have been written into the future, you will need to add an appropriate `stop` date ### Query series cardinality in a measurement// @@ -138,7 +153,7 @@ import "influxdata/influxdb" influxdb.cardinality( bucket: "example-bucket", - start: -1y, + start: time(v: 1), predicate: (r) => r._measurement == "example-measurement", ) @@ -150,7 +165,16 @@ influxdb.cardinality( ```js import "influxdata/influxdb" -influxdb.cardinality(bucket: "example-bucket", start: -1y, predicate: (r) => r.exampleTag == "foo") +influxdb.cardinality(bucket: "example-bucket", start: time(v: 1), predicate: (r) => r.exampleTag == "foo") + +``` + + +### Query Cardinality of Data Written In the Last 4 hours +```js +import "influxdata/influxdb" + +influxdb.cardinality(bucket: "example-bucket", start: -4h) ``` diff --git a/content/flux/v0/stdlib/timezone/fixed.md b/content/flux/v0/stdlib/timezone/fixed.md index 458420782..2343a2167 100644 --- a/content/flux/v0/stdlib/timezone/fixed.md +++ b/content/flux/v0/stdlib/timezone/fixed.md @@ -77,3 +77,7 @@ option location = timezone.fixed(offset: -8h) ``` +> [!Note] +> The `location` option only affects boundaries used for windowing, specifically around time shifts +> like daylight savings. It does not change timestamps in the `_time` column, which are always UTC. + diff --git a/content/flux/v0/stdlib/timezone/location.md b/content/flux/v0/stdlib/timezone/location.md index 4fcaf06e4..f6dec797e 100644 --- a/content/flux/v0/stdlib/timezone/location.md +++ b/content/flux/v0/stdlib/timezone/location.md @@ -75,3 +75,6 @@ option location = timezone.location(name: "America/Los_Angeles") ``` +> [!Note] +> The `location` option only affects boundaries used for windowing, specifically around time shifts +> like daylight savings. It does not change timestamps in the `_time` column, which are always UTC. diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/_index.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/_index.md index 5e5975061..2d1b8b7e4 100644 --- a/content/influxdb/cloud-dedicated/admin/custom-partitions/_index.md +++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/_index.md @@ -11,405 +11,9 @@ weight: 103 influxdb/cloud-dedicated/tags: [storage] related: - /influxdb/cloud-dedicated/reference/internals/storage-engine/ +source: /shared/v3-distributed-admin-custom-partitions/_index.md --- -When writing data to {{< product-name >}}, the InfluxDB v3 storage engine stores -data in the [Object store](/influxdb/cloud-dedicated/reference/internals/storage-engine/#object-store) -in [Apache Parquet](https://parquet.apache.org/) format. -Each Parquet file represents a _partition_--a logical grouping of data. -By default, InfluxDB partitions each table by day. -{{< product-name >}} lets you customize the partitioning strategy and partition -by tag values and different time intervals. -Customize your partitioning strategy to optimize query performance for your -specific schema and workload. - -- [Advantages](#advantages) -- [Disadvantages](#disadvantages) -- [Limitations](#limitations) -- [How partitioning works](#how-partitioning-works) - - [Partition templates](#partition-templates) - - [Partition keys](#partition-keys) -- [Partitions in the query life cycle](#partitions-in-the-query-life-cycle) -- [Partition guides](#partition-guides) - {{< children type="anchored-list" >}} - -## Advantages - -The primary advantage of custom partitioning is that it lets you customize your -storage structure to improve query performance specific to your schema and workload. - -- **Optimized storage for improved performance on specific types of queries**. - For example, if queries often select data with a specific tag value, you can - partition by that tag to improve the performance of those queries. -- **Optimized storage for specific types of data**. For example, if the data you - store is sparse and the time ranges you query are often much larger than a day, - you could partition your data by week instead of by day. - -## Disadvantages - -Using custom partitioning may increase the load on other parts of the -[InfluxDB v3 storage engine](/influxdb/cloud-dedicated/reference/internals/storage-engine/), -but each can be scaled individually to address the added load. - -{{% note %}} -_The following disadvantages assume that your custom partitioning strategy includes -additional tags to partition by or partition intervals smaller than a day._ -{{% /note %}} - -- **Increased load on the [Ingester](/influxdb/cloud-dedicated/reference/internals/storage-engine/#ingester)** - as it groups data into smaller partitions and files. -- **Increased load on the [Catalog](/influxdb/cloud-dedicated/reference/internals/storage-engine/#catalog)** - as more references to partition Parquet file locations are stored and queried. -- **Increased load on the [Compactor](/influxdb/cloud-dedicated/reference/internals/storage-engine/#compactor)** - as more partition Parquet files need to be compacted. -- **Increased costs associated with [Object storage](/influxdb/cloud-dedicated/reference/internals/storage-engine/#object-storage)** - as more partition Parquet files are created and stored. -- **Risk of decreased performance for queries that don't use tags in the WHERE clause**. - These queries may end up reading many partitions and smaller files, degrading performance. - -## Limitations - -Custom partitioning has the following limitations: - -- Database and table partitions can only be defined on create. - You cannot update the partition strategy of a database or table after it has - been created. -- You can partition by up to eight dimensions (seven tags and a time interval). - -## How partitioning works - -### Partition templates - -A partition template defines the pattern used for _[partition keys](#partition-keys)_ -and determines the time interval that data is partitioned by. -Partition templates use tag values and -[Rust strftime date and time formatting syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). - -_For more detailed information, see [Partition templates](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/)._ - -### Partition keys - -A partition key uniquely identifies a partition. The structure of partition keys -is defined by a _[partition template](#partition-templates)_. Partition keys are -composed of up to eight parts or dimensions (tags, tag buckets, and time). -Each part is delimited by the partition key separator (`|`). - -{{< expand-wrapper >}} -{{% expand "View example partition templates and keys" %}} - -Given the following line protocol with the following timestamps: - -- 2023-12-31T23:00:00Z -- 2024-01-01T00:00:00Z -- 2024-01-01T01:00:00Z - -```text -production,line=A,station=cnc temp=81.2,qty=35i 1704063600000000000 -production,line=A,station=wld temp=92.8,qty=35i 1704063600000000000 -production,line=B,station=cnc temp=101.1,qty=43i 1704063600000000000 -production,line=B,station=wld temp=102.4,qty=43i 1704063600000000000 -production,line=A,station=cnc temp=81.9,qty=36i 1704067200000000000 -production,line=A,station=wld temp=110.0,qty=22i 1704067200000000000 -production,line=B,station=cnc temp=101.8,qty=44i 1704067200000000000 -production,line=B,station=wld temp=105.7,qty=44i 1704067200000000000 -production,line=A,station=cnc temp=82.2,qty=35i 1704070800000000000 -production,line=A,station=wld temp=92.1,qty=30i 1704070800000000000 -production,line=B,station=cnc temp=102.4,qty=43i 1704070800000000000 -production,line=B,station=wld temp=106.5,qty=43i 1704070800000000000 -``` - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `%Y-%m-%d` time (by day, default format) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `2023-12-31` -- `2024-01-01` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `%d %b %Y` time (by day, non-default format) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | 31 Dec 2023` -- `B | 31 Dec 2023` -- `A | 01 Jan 2024` -- `B | 01 Jan 2024` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `station` tag -- `%Y-%m-%d` time (by day, default format) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | cnc | 2023-12-31` -- `A | wld | 2023-12-31` -- `B | cnc | 2023-12-31` -- `B | wld | 2023-12-31` -- `A | cnc | 2024-01-01` -- `A | wld | 2024-01-01` -- `B | cnc | 2024-01-01` -- `B | wld | 2024-01-01` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `station,3` tag bucket -- `%Y-%m-%d` time (by day, default format) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | 0 | 2023-12-31` -- `B | 0 | 2023-12-31` -- `A | 0 | 2024-01-01` -- `B | 0 | 2024-01-01` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `station` tag -- `%Y-%m-%d %H:00` time (by hour) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | cnc | 2023-12-31 23:00` -- `A | wld | 2023-12-31 23:00` -- `B | cnc | 2023-12-31 23:00` -- `B | wld | 2023-12-31 23:00` -- `A | cnc | 2024-01-01 00:00` -- `A | wld | 2024-01-01 00:00` -- `B | cnc | 2024-01-01 00:00` -- `B | wld | 2024-01-01 00:00` -- `A | cnc | 2024-01-01 01:00` -- `A | wld | 2024-01-01 01:00` -- `B | cnc | 2024-01-01 01:00` -- `B | wld | 2024-01-01 01:00` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `station,50` tag bucket -- `%Y-%m-%d %H:00` time (by hour) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | 47 | 2023-12-31 23:00` -- `A | 9 | 2023-12-31 23:00` -- `B | 47 | 2023-12-31 23:00` -- `B | 9 | 2023-12-31 23:00` -- `A | 47 | 2024-01-01 00:00` -- `A | 9 | 2024-01-01 00:00` -- `B | 47 | 2024-01-01 00:00` -- `B | 9 | 2024-01-01 00:00` -- `A | 47 | 2024-01-01 01:00` -- `A | 9 | 2024-01-01 01:00` -- `B | 47 | 2024-01-01 01:00` -- `B | 9 | 2024-01-01 01:00` - -{{% /flex-content %}} - - - -{{% /flex %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Partitions in the query life cycle - -When querying data: - -1. The [Catalog](/influxdb/cloud-dedicated/reference/internals/storage-engine/#catalog) - provides the v3 query engine ([Querier](/influxdb/cloud-dedicated/reference/internals/storage-engine/#querier)) - with the locations of partitions that contain the queried time series data. -2. The query engine reads all rows in the returned partitions to identify what - rows match the logic in the query and should be included in the query result. - -The faster the query engine can identify what partitions to read and then read -the data in those partitions, the more performant queries are. - -_For more information about the query lifecycle, see -[InfluxDB v3 query life cycle](/influxdb/cloud-dedicated/reference/internals/storage-engine/#query-life-cycle)._ - -##### Query example - -Consider the following query that selects everything in the `production` table -where the `line` tag is `A` and the `station` tag is `cnc`: - -```sql -SELECT * -FROM production -WHERE - time >= now() - INTERVAL '1 week' - AND line = 'A' - AND station = 'cnc' -``` - -Using the default partitioning strategy (by day), the query engine -reads eight separate partitions (one partition for today and one for each of the -last seven days): - -- {{< datetime/current-date trimTime=true >}} -- {{< datetime/current-date offset=-1 trimTime=true >}} -- {{< datetime/current-date offset=-2 trimTime=true >}} -- {{< datetime/current-date offset=-3 trimTime=true >}} -- {{< datetime/current-date offset=-4 trimTime=true >}} -- {{< datetime/current-date offset=-5 trimTime=true >}} -- {{< datetime/current-date offset=-6 trimTime=true >}} -- {{< datetime/current-date offset=-7 trimTime=true >}} - -The query engine must scan _all_ rows in the partitions to identify rows -where `line` is `A` and `station` is `cnc`. This process takes valuable time -and results in less performant queries. - -However, if you partition by other tags, InfluxDB can identify partitions that -contain only the tag values your query needs and spend less time -scanning rows to see if they contain the tag values. - -For example, if data is partitioned by `line`, `station`, and day, although -there are more partition files, the query engine can quickly identify and read -only those with data relevant to the query: - -{{% columns 4 %}} - -- A | cnc | {{< datetime/current-date trimTime=true >}} -- A | wld | {{< datetime/current-date trimTime=true >}} -- B | cnc | {{< datetime/current-date trimTime=true >}} -- B | wld | {{< datetime/current-date trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-1 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-1 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-1 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-1 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-2 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-2 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-2 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-2 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-3 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-3 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-3 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-3 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-4 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-4 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-4 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-4 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-5 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-5 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-5 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-5 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-6 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-6 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-6 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-6 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-7 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-7 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-7 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-7 trimTime=true >}} - -{{% /columns %}} - ---- - -## Partition guides - -{{< children >}} + diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/best-practices.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/best-practices.md index c558808d3..782a2b0b5 100644 --- a/content/influxdb/cloud-dedicated/admin/custom-partitions/best-practices.md +++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/best-practices.md @@ -8,52 +8,9 @@ menu: name: Best practices parent: Manage data partitioning weight: 202 +source: /shared/v3-distributed-admin-custom-partitions/best-practices.md --- -Use the following best practices when defining custom partitioning strategies -for your data stored in {{< product-name >}}. - -- [Partition by tags that you commonly query for a specific value](#partition-by-tags-that-you-commonly-query-for-a-specific-value) -- [Only partition by tags that _always_ have a value](#only-partition-by-tags-that-always-have-a-value) -- [Avoid over-partitioning](#avoid-over-partitioning) - -## Partition by tags that you commonly query for a specific value - -Custom partitioning primarily benefits queries that look for a specific tag -value in the `WHERE` clause. For example, if you often query data related to a -specific ID, partitioning by the tag that stores the ID helps the InfluxDB -query engine to more quickly identify what partitions contain the relevant data. - -{{% note %}} - -#### Use tag buckets for high-cardinality tags - -Partitioning using distinct values of tags with many (10K+) unique values can -actually hurt query performance as partitions are created for each unique tag value. -Instead, use [tag buckets](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates) -to partition by high-cardinality tags. -This method of partitioning groups tag values into "buckets" and partitions by bucket. -{{% /note %}} - -## Only partition by tags that _always_ have a value - -You should only partition by tags that _always_ have a value. -If points don't have a value for the tag, InfluxDB can't store them in the correct partitions and, at query time, must read all the partitions. - -## Avoid over-partitioning - -As you plan your partitioning strategy, keep in mind that data can be -"over-partitioned"--meaning partitions are so granular that queries end up -having to retrieve and read many partitions from the object store, which -hurts query performance. - -- Avoid using partition time intervals that are **less than one day**. - - The partition time interval should be balanced with the actual amount of data - written during each interval. If a single interval doesn't contain a lot of data, - it is better to partition by larger time intervals. - -- Don't partition by tags that you typically don't use in your query workload. -- Don't partition by distinct values of high-cardinality tags. - Instead, [use tag buckets](#use-tag-buckets-for-high-cardinality-tags) to - partition by these tags. + diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md index 46129a41b..a46a60c1a 100644 --- a/content/influxdb/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md +++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/define-custom-partitions.md @@ -10,162 +10,9 @@ weight: 202 related: - /influxdb/cloud-dedicated/reference/cli/influxctl/database/create/ - /influxdb/cloud-dedicated/reference/cli/influxctl/table/create/ +source: /shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md --- -Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -to define custom partition strategies when creating a database or table. -By default, {{< product-name >}} partitions data by day. - -The partitioning strategy of a database or table is determined by a -[partition template](/influxdb/cloud-dedicated/admin/custom-partitions/#partition-templates) -which defines the naming pattern for [partition keys](/influxdb/cloud-dedicated/admin/custom-partitions/#partition-keys). -Partition keys uniquely identify each partition. -When a partition template is applied to a database, it becomes the default template -for all tables in that database, but can be overridden when creating a -table. - -- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template) -- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template) -- [Example partition templates](#example-partition-templates) - -{{% note %}} - -#### Partition templates can only be applied on create - -You can only apply a partition template when creating a database or table. -You can't update a partition template on an existing resource. -{{% /note %}} - -Use the following command flags to identify -[partition template parts](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-part-templates): - -- `--template-tag`: An [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#tag) - to use in the partition template. -- `--template-tag-bucket`: An [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#tag) - and number of "buckets" to group tag values into. - Provide the tag key and the number of buckets to bucket tag values into - separated by a comma: `tagKey,N`. -- `--template-timeformat`: A [Rust strftime date and time](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) - string that specifies the time format in the partition template and determines - the time interval to partition by. - -{{% note %}} -A partition template can include up to 7 total tag and tag bucket parts -and only 1 time part. -{{% /note %}} - -_View [partition template part restrictions](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#restrictions)._ - -{{% note %}} -#### Always provide a time format when using custom partitioning - -When defining a custom partition template for your database or table using any -of the `influxctl` `--template-*` flags, always include the `--template-timeformat` -flag with a time format to use in your partition template. -Otherwise, InfluxDB omits time from the partition template and won't compact partitions. -{{% /note %}} - -## Create a database with a custom partition template - -The following example creates a new `example-db` database and applies a partition -template that partitions by distinct values of two tags (`room` and `sensor-type`), -bucketed values of the `customerID` tag, and by week using the time format `%Y wk:%W`: - - - - -```sh -influxctl database create \ - --template-tag room \ - --template-tag sensor-type \ - --template-tag-bucket customerID,500 \ - --template-timeformat '%Y wk:%W' \ - example-db -``` - -## Create a table with a custom partition template - -The following example creates a new `example-table` table in the specified -database and applies a partition template that partitions by distinct values of -two tags (`room` and `sensor-type`), bucketed values of the `customerID` tag, -and by month using the time format `%Y-%m`: - - - - -{{% code-placeholders "DATABASE_NAME" %}} - -```sh -influxctl table create \ - --template-tag room \ - --template-tag sensor-type \ - --template-tag-bucket customerID,500 \ - --template-timeformat '%Y-%m' \ - DATABASE_NAME \ - example-table -``` - -{{% /code-placeholders %}} - -Replace the following in your command: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb/cloud-dedicated/admin/databases/) - - - -## Example partition templates - -Given the following [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) -with a `2024-01-01T00:00:00Z` timestamp: - -```text -prod,line=A,station=weld1 temp=81.9,qty=36i 1704067200000000000 -``` - -##### Partitioning by distinct tag values - -| Description | Tag parts | Time part | Resulting partition key | -| :---------------------- | :---------------- | :--------- | :----------------------- | -| By day (default) | | `%Y-%m-%d` | 2024-01-01 | -| By day (non-default) | | `%d %b %Y` | 01 Jan 2024 | -| By week | | `%Y wk:%W` | 2024 wk:01 | -| By month | | `%Y-%m` | 2024-01 | -| Single tag, by day | `line` | `%F` | A \| 2024-01-01 | -| Single tag, by week | `line` | `%Y wk:%W` | A \| 2024 wk:01 | -| Single tag, by month | `line` | `%Y-%m` | A \| 2024-01 | -| Multiple tags, by day | `line`, `station` | `%F` | A \| weld1 \| 2024-01-01 | -| Multiple tags, by week | `line`, `station` | `%Y wk:%W` | A \| weld1 \| 2024 wk:01 | -| Multiple tags, by month | `line`, `station` | `%Y-%m` | A \| weld1 \| 2024-01 | - -##### Partition by tag buckets - -| Description | Tag part | Tag bucket part | Time part | Resulting partition key | -| :--------------------------------- | :------- | :-------------- | :--------- | :---------------------- | -| Distinct tag, tag buckets, by day | `line` | `station,100` | `%F` | A \| 3 \| 2024-01-01 | -| Distinct tag, tag buckets, by week | `line` | `station,500` | `%Y wk:%W` | A \| 303 \| 2024 wk:01 | diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates.md index d024539bc..cb015f820 100644 --- a/content/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates.md +++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates.md @@ -8,276 +8,9 @@ menu: influxdb_cloud_dedicated: parent: Manage data partitioning weight: 202 +source: /shared/v3-distributed-admin-custom-partitions/partition-templates.md --- -Use partition templates to define the patterns used to generate partition keys. -A partition key uniquely identifies a partition and is used to name the partition -Parquet file in the [Object store](/influxdb/cloud-dedicated/reference/internals/storage-engine/#object-store). - -A partition template consists of 1-8 _template parts_---dimensions to partition data by. -There are three types of template parts: - -- **tag**: An [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#tag) - to partition by. -- **tag bucket**: An [InfluxDB tag](/influxdb/cloud-dedicated/reference/glossary/#tag) - and number of "buckets" to group tag values into. Data is partitioned by the - tag bucket rather than each distinct tag value. -- **time**: A Rust strftime date and time string that specifies the time interval - to partition data by. The smallest unit of time included in the time part - template is the interval used to partition data. - -{{% note %}} -A partition template can include up to 7 total tag and tag bucket parts -and only 1 time part. -{{% /note %}} - - -- [Restrictions](#restrictions) - - [Template part size limit](#template-part-size-limit) - - [Reserved keywords](#reserved-keywords) - - [Reserved Characters](#reserved-characters) -- [Tag part templates](#tag-part-templates) -- [Tag bucket part templates](#tag-bucket-part-templates) -- [Time part templates](#time-part-templates) - - [Date specifiers](#date-specifiers) - - [Time specifiers](#time-specifiers) - - [Time zone specifiers](#time-zone-specifiers) - - [Date and time specifiers](#date-and-time-specifiers) - - [Special specifiers](#special-specifiers) - - -## Restrictions - -### Template part size limit - -Each template part is limited to 200 bytes in length. -Anything longer will be truncated at 200 bytes and appended with `#`. - -### Partition key size limit - -With the truncation of template parts, the maximum length of a partition key is -1,607 bytes (1.57 KiB). - -### Reserved keywords - -The following reserved keywords cannot be used in partition templates: - -- `time` - -### Reserved Characters - -If used in template parts, non-ASCII characters and the following reserved -characters must be [percent encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding): - -- `|`: Partition key part delimiter -- `!`: Null or missing partition key part -- `^`: Empty string partition key part -- `#`: Key part truncation marker -- `%`: Required for unambiguous reversal of percent encoding - -## Tag part templates - -Tag part templates consist of a _tag key_ to partition by. -Generated partition keys include the unique _tag value_ specific to each partition. - -## Tag bucket part templates - -Tag bucket part templates consist of a _tag key_ to partition by and the -_number of "buckets" to partition tag values into_--for example: - -``` -customerID,500 -``` - -Values of the `customerID` tag are bucketed into 500 distinct "buckets." -Each bucket is identified by the remainder of the tag value hashed into a 32bit -integer divided by the specified number of buckets: - -```rust -hash(tagValue) % N -``` - -Generated partition keys include the unique _tag bucket identifier_ specific to -each partition. - -**Supported number of tag buckets**: 1-1,000 - -{{% note %}} -Tag buckets should be used to partition by high cardinality tags or tags with an -unknown number of distinct values. -{{% /note %}} - -## Time part templates - -Time part templates use [Rust strftime date and time formatting syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) -to specify time format in partition keys. -The smallest unit of time included in the time part template is the interval -used to partition data. - -{{% warn %}} -#### Avoid partitioning by less than one day - -We do not recommend using time intervals less than one day to partition data. -This can result in [over-partitioned data](/influxdb/cloud-dedicated/admin/custom-partitions/best-practices/#avoid-over-partitioning) -and may hurt query performance. -{{% /warn %}} - -- [Date specifiers](#date-specifiers) -- [Time specifiers](#time-specifiers) -- [Time zone specifiers](#time-zone-specifiers) -- [Date and time specifiers](#date-and-time-specifiers) -- [Special specifiers](#special-specifiers) - -{{% note %}} -The following is adapted from the -[Rust strftime source code](https://docs.rs/chrono/latest/src/chrono/format/strftime.rs.html). -{{% /note %}} - -### Date specifiers - -| Variable | Example | Description | -| :------: | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `%Y` | `2001` | The full proleptic Gregorian year, zero-padded to 4 digits. chrono supports years from -262144 to 262143. Note: years before 1 BCE or after 9999 CE, require an initial sign (+/-). | -| `%C` | `20` | The proleptic Gregorian year divided by 100, zero-padded to 2 digits. [^1] | -| `%y` | `01` | The proleptic Gregorian year modulo 100, zero-padded to 2 digits. [^1] | -| `%m` | `07` | Month number (01--12), zero-padded to 2 digits. | -| `%b` | `Jul` | Abbreviated month name. Always 3 letters. | -| `%B` | `July` | Full month name. Also accepts corresponding abbreviation in parsing. | -| `%h` | `Jul` | Same as `%b`. | -| `%d` | `08` | Day number (01--31), zero-padded to 2 digits. | -| `%e` | ` 8` | Same as `%d` but space-padded. Same as `%_d`. | -| `%a` | `Sun` | Abbreviated weekday name. Always 3 letters. | -| `%A` | `Sunday` | Full weekday name. Also accepts corresponding abbreviation in parsing. | -| `%w` | `0` | Sunday = 0, Monday = 1, ..., Saturday = 6. | -| `%u` | `7` | Monday = 1, Tuesday = 2, ..., Sunday = 7. (ISO 8601) | -| `%U` | `28` | Week number starting with Sunday (00--53), zero-padded to 2 digits. [^2] | -| `%W` | `27` | Same as `%U`, but week 1 starts with the first Monday in that year instead. | -| `%G` | `2001` | Same as `%Y` but uses the year number in ISO 8601 week date. [^3] | -| `%g` | `01` | Same as `%y` but uses the year number in ISO 8601 week date. [^3] | -| `%V` | `27` | Same as `%U` but uses the week number in ISO 8601 week date (01--53). [^3] | -| `%j` | `189` | Day of the year (001--366), zero-padded to 3 digits. | -| `%D` | `07/08/01` | Month-day-year format. Same as `%m/%d/%y`. | -| `%x` | `07/08/01` | Locale's date representation (e.g., 12/31/99). | -| `%F` | `2001-07-08` | Year-month-day format (ISO 8601). Same as `%Y-%m-%d`. | -| `%v` | ` 8-Jul-2001` | Day-month-year format. Same as `%e-%b-%Y`. | - -### Time specifiers - -| Variable | Example | Description | -| :------: | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | -| `%H` | `00` | Hour number (00--23), zero-padded to 2 digits. | -| `%k` | ` 0` | Same as `%H` but space-padded. Same as `%_H`. | -| `%I` | `12` | Hour number in 12-hour clocks (01--12), zero-padded to 2 digits. | -| `%l` | `12` | Same as `%I` but space-padded. Same as `%_I`. | -| `%P` | `am` | `am` or `pm` in 12-hour clocks. | -| `%p` | `AM` | `AM` or `PM` in 12-hour clocks. | -| `%M` | `34` | Minute number (00--59), zero-padded to 2 digits. | -| `%S` | `60` | Second number (00--60), zero-padded to 2 digits. [^4] | -| `%f` | `26490000` | Number of nanoseconds since last whole second. [^7] | -| `%.f` | `.026490` | Decimal fraction of a second. Consumes the leading dot. [^7] | -| `%.3f` | `.026` | Decimal fraction of a second with a fixed length of 3. | -| `%.6f` | `.026490` | Decimal fraction of a second with a fixed length of 6. | -| `%.9f` | `.026490000` | Decimal fraction of a second with a fixed length of 9. | -| `%3f` | `026` | Decimal fraction of a second like `%.3f` but without the leading dot. | -| `%6f` | `026490` | Decimal fraction of a second like `%.6f` but without the leading dot. | -| `%9f` | `026490000` | Decimal fraction of a second like `%.9f` but without the leading dot. | -| `%R` | `00:34` | Hour-minute format. Same as `%H:%M`. | -| `%T` | `00:34:60` | Hour-minute-second format. Same as `%H:%M:%S`. | -| `%X` | `00:34:60` | Locale's time representation (e.g., 23:13:48). | -| `%r` | `12:34:60 AM` | Locale's 12 hour clock time. (e.g., 11:11:04 PM). Falls back to `%X` if the locale does not have a 12 hour clock format. | - -### Time zone specifiers - -| Variable | Example | Description | -| :------: | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------- | -| `%Z` | `ACST` | Local time zone name. Skips all non-whitespace characters during parsing. Identical to `%:z` when formatting. [^8] | -| `%z` | `+0930` | Offset from the local time to UTC (with UTC being `+0000`). | -| `%:z` | `+09:30` | Same as `%z` but with a colon. | -| `%::z` | `+09:30:00` | Offset from the local time to UTC with seconds. | -| `%:::z` | `+09` | Offset from the local time to UTC without minutes. | -| `%#z` | `+09` | *Parsing only:* Same as `%z` but allows minutes to be missing or present. | - -### Date and time specifiers - -| Variable | Example | Description | -| :------: | :--------------------------------- | :--------------------------------------------------------------------- | -| `%c` | `Sun Jul 8 00:34:60 2001` | Locale's date and time (e.g., Thu Mar 3 23:05:25 2005). | -| `%+` | `2001-07-08T00:34:60.026490+09:30` | ISO 8601 / RFC 3339 date & time format. [^5] | -| `%s` | `994518299` | UNIX timestamp, the number of seconds since 1970-01-01 00:00 UTC. [^6] | - -### Special specifiers - -| Variable | Example | Description | -| :------: | :------ | :---------------------- | -| `%t` | | Literal tab (`\t`). | -| `%n` | | Literal newline (`\n`). | -| `%%` | | Literal percent sign. | - -It is possible to override the default padding behavior of numeric specifiers `%?`. -This is not allowed for other specifiers and results in the `BAD_FORMAT` error. - -Modifier | Description --------- | ----------- -`%-?` | Suppresses any padding including spaces and zeroes. (e.g. `%j` = `012`, `%-j` = `12`) -`%_?` | Uses spaces as a padding. (e.g. `%j` = `012`, `%_j` = ` 12`) -`%0?` | Uses zeroes as a padding. (e.g. `%e` = ` 9`, `%0e` = `09`) - -Notes: - -[^1]: `%C`, `%y`: - This is floor division, so 100 BCE (year number -99) will print `-1` and `99` respectively. -[^2]: `%U`: - Week 1 starts with the first Sunday in that year. - It is possible to have week 0 for days before the first Sunday. - -[^3]: `%G`, `%g`, `%V`: - Week 1 is the first week with at least 4 days in that year. - Week 0 does not exist, so this should be used with `%G` or `%g`. - -[^4]: `%S`: - It accounts for leap seconds, so `60` is possible. - -[^5]: `%+`: Same as `%Y-%m-%dT%H:%M:%S%.f%:z`, i.e. 0, 3, 6 or 9 fractional - digits for seconds and colons in the time zone offset. -
-
- This format also supports having a `Z` or `UTC` in place of `%:z`. They - are equivalent to `+00:00`. -
-
- Note that all `T`, `Z`, and `UTC` are parsed case-insensitively. -
-
- The typical `strftime` implementations have different (and locale-dependent) - formats for this specifier. While Chrono's format for `%+` is far more - stable, it is best to avoid this specifier if you want to control the exact - output. - -[^6]: `%s`: - This is not padded and can be negative. - For the purpose of Chrono, it only accounts for non-leap seconds - so it slightly differs from ISO C `strftime` behavior. - -[^7]: `%f`, `%.f`: -
- `%f` and `%.f` are notably different formatting specifiers.
- `%f` counts the number of nanoseconds since the last whole second, while `%.f` is a fraction of a - second.
- Example: 7μs is formatted as `7000` with `%f`, and formatted as `.000007` with `%.f`. - -[^8]: `%Z`: - Since `chrono` is not aware of timezones beyond their offsets, this specifier - **only prints the offset** when used for formatting. The timezone abbreviation - will NOT be printed. See [this issue](https://github.com/chronotope/chrono/issues/960) - for more information. -
-
- Offset will not be populated from the parsed data, nor will it be validated. - Timezone is completely ignored. Similar to the glibc `strptime` treatment of - this format code. -
-
- It is not possible to reliably convert from an abbreviation to an offset, - for example CDT can mean either Central Daylight Time (North America) or - China Daylight Time. -*/ \ No newline at end of file + diff --git a/content/influxdb/cloud-dedicated/admin/custom-partitions/view-partitions.md b/content/influxdb/cloud-dedicated/admin/custom-partitions/view-partitions.md new file mode 100644 index 000000000..18f5725d8 --- /dev/null +++ b/content/influxdb/cloud-dedicated/admin/custom-partitions/view-partitions.md @@ -0,0 +1,22 @@ +--- +title: View partition information +description: > + Query partition information from InfluxDB v3 system tables to view partition + templates and verify partitions are working as intended. +menu: + influxdb_cloud_dedicated: + name: View partitions + parent: Manage data partitioning +weight: 202 +list_code_example: | + ```sql + SELECT * FROM system.partitions WHERE table_name = 'example-table' + ``` +related: + - /influxdb/cloud-dedicated/admin/query-system-data/ +source: /shared/v3-distributed-admin-custom-partitions/view-partitions.md +--- + + diff --git a/content/influxdb/cloud-dedicated/admin/databases/create.md b/content/influxdb/cloud-dedicated/admin/databases/create.md index a40c1bc15..b0e2e9e5d 100644 --- a/content/influxdb/cloud-dedicated/admin/databases/create.md +++ b/content/influxdb/cloud-dedicated/admin/databases/create.md @@ -128,7 +128,7 @@ influxctl database create \ Replace the following in your command: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb/cloud-dedicated/admin/databases/) -- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`, `TAG_KEY_3`, and `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag]((/influxdb/cloud-dedicated/reference/glossary/#tag)) keys from your data +- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`, `TAG_KEY_3`, and `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag](/influxdb/cloud-dedicated/reference/glossary/#tag) keys from your data ## Database attributes @@ -194,14 +194,6 @@ flags to define partition template parts used to generate partition keys for the For more information, see [Manage data partitioning](/influxdb/cloud-dedicated/admin/custom-partitions/). -{{% note %}} - -#### Partition templates can only be applied on create - -You can only apply a partition template when creating a database. -You can't update a partition template on an existing database. -{{% /note %}} - {{% /tab-content %}} {{% tab-content %}} @@ -235,7 +227,7 @@ _This example uses [cURL](https://curl.se/) to send a Management HTTP API reques to use in the partition template. Limit is 7 total tags or tag buckets. - _Optional_: [InfluxDB tag buckets](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates) to use in the partition template. Limit is 7 total tags or tag buckets. - - _Optional_: A [Rust strftime date and time string](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) + - _Optional_: A supported [Rust strftime date and time string](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) that specifies the time format in the partition template and determines the time interval to partition by. Default is `%Y-%m-%d`. - Database name _(see [Database naming restrictions](#database-naming-restrictions))_. @@ -302,7 +294,7 @@ Replace the following in your request: - {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: the ID of the {{% product-name %}} [cluster](/influxdb/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to create the database for - {{% code-placeholder-key %}}`MANAGEMENT TOKEN`{{% /code-placeholder-key %}}: a [management token](/influxdb/cloud-dedicated/admin/tokens/management/) for your {{% product-name %}} cluster - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb/cloud-dedicated/admin/databases/) -- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`, `TAG_KEY_3`, and `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag]((/influxdb/cloud-dedicated/reference/glossary/#tag)) keys from your data +- {{% code-placeholder-key %}}`TAG_KEY_1`, `TAG_KEY_2`, `TAG_KEY_3`, and `TAG_KEY_4`{{% /code-placeholder-key %}}: [tag](/influxdb/cloud-dedicated/reference/glossary/#tag) keys from your data ## Database attributes @@ -341,21 +333,23 @@ format in the InfluxDB v3 storage engine. By default, data is partitioned by day but, depending on your schema and workload, customizing the partitioning strategy can improve query performance. -Use the [`partitionTemplate`](/influxdb/cloud-dedicated/api/management/#operation/CreateClusterDatabase) property to define an array of partition template parts used to generate partition keys for the database. +Use the [`partitionTemplate`](/influxdb/cloud-dedicated/api/management/#operation/CreateClusterDatabase) +property to define an array of partition template parts used to generate +partition keys for the database. For more information, see [Manage data partitioning](/influxdb/cloud-dedicated/admin/custom-partitions/). -{{% note %}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +{{% warn %}} #### Partition templates can only be applied on create You can only apply a partition template when creating a database. You can't update a partition template on an existing database. -{{% /note %}} - - -{{% /tab-content %}} -{{< /tabs-wrapper >}} +{{% /warn %}} ### Database naming restrictions diff --git a/content/influxdb/cloud-dedicated/admin/monitor-your-cluster.md b/content/influxdb/cloud-dedicated/admin/monitor-your-cluster.md index 99c31c5e6..7ca67867c 100644 --- a/content/influxdb/cloud-dedicated/admin/monitor-your-cluster.md +++ b/content/influxdb/cloud-dedicated/admin/monitor-your-cluster.md @@ -10,9 +10,9 @@ menu: weight: 104 --- -InfluxData provides a Grafana operational dashboard that provide observability -into the your {{< product-name >}} cluster. Use the operational dashboard to -monitor your cluster. +InfluxData provides a Grafana operational dashboard that provides observability +into your {{< product-name >}} cluster. +Use the operational dashboard to monitor your cluster. {{% note %}} #### Not available for all clusters @@ -40,7 +40,7 @@ If you do not have login credentials, [contact InfluxData support](https://suppo ## Dashboard sections and cells -The dashboard is divided into the following sections that visualize metrics +The dashboard contains the following sections that visualize metrics related to the health of components in your {{< product-name >}} cluster: - [Query Tier Cpu/Mem](#query-tier-cpumem) @@ -156,7 +156,7 @@ to the [Object store](/influxdb/cloud-dedicated/reference/internals/storage-engi #### CPU Utilization Ingesters (k8s) -CPU Utilization of Ingester pods as reported by the Kubernetes container usage. +CPU utilization of Ingester pods as reported by the Kubernetes container usage. Usage is reported by the number of CPU cores used by pods, including fractional cores. The CPU limit is represented by the top line in the visualization. @@ -284,7 +284,7 @@ _These do not represent the most recent logs._ The **Compaction Tier Cpu/Mem** section displays the CPU and memory usage of Compactor pods as reported by Kubernetes. [Compactors](/influxdb/cloud-dedicated/reference/internals/storage-engine/#compactor) -process and compress parquet files in the +process and compress Parquet files in the [Object store](/influxdb/cloud-dedicated/reference/internals/storage-engine/#object-store) to continually optimize storage. @@ -330,10 +330,10 @@ following levels: Parquet files store data partitioned by time and optionally tags _(see [Manage data partition](https://docs.influxdata.com/influxdb/cloud-dedicated/admin/custom-partitions/))_. -After four L0 files accumulate for a partition, they are are eligible for compaction. +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 will have exactly four files. If the number of L0 files compacted begins to -to increase, it indicates the compactor is not keeping up. +events have exactly four files. +An increase in the number of L0 files compacted indicates the compactor isn't keeping up. This histogram helps to determine if the Compactor is starting compactions as soon as it can. @@ -367,7 +367,7 @@ that the Catalog may be overloaded or unresponsive. #### Catalog Op Latency (P90) -The 90th percentile (P90) of query latency against the catalog service per operation. +The 90th percentile (P90) query latency for each operation against the catalog service. A high P90 value indicates that the Catalog may be overloaded. --- diff --git a/content/influxdb/cloud-dedicated/admin/query-system-data.md b/content/influxdb/cloud-dedicated/admin/query-system-data.md index 1ca08a5b5..ec7387937 100644 --- a/content/influxdb/cloud-dedicated/admin/query-system-data.md +++ b/content/influxdb/cloud-dedicated/admin/query-system-data.md @@ -1,4 +1,4 @@ ---- +--- title: Query system data description: > Query system tables in your InfluxDB Cloud Dedicated cluster to see data related @@ -10,28 +10,42 @@ menu: weight: 105 related: - /influxdb/cloud-dedicated/reference/cli/influxctl/query/ ---- + - /influxdb/cloud-dedicated/reference/internals/system-tables/ +--- {{< product-name >}} stores data related to queries, tables, partitions, and -compaction in system tables in your cluster. -Query data in your cluster's system tables for information about your cluster. +compaction in _system tables_ within your cluster. +System tables contain time series data used by and generated from the +{{< product-name >}} internal monitoring system. +You can query the cluster system tables for information about your cluster. - [Query system tables](#query-system-tables) + - [Optimize queries to reduce impact to your cluster](#optimize-queries-to-reduce-impact-to-your-cluster) - [System tables](#system-tables) + - [Understanding system table data distribution](#understanding-system-table-data-distribution) + - [system.queries](#systemqueries) + - [system.tables](#systemtables) + - [system.partitions](#systempartitions) + - [system.compactor](#systemcompactor) - [System query examples](#system-query-examples) + - [Query logs](#query-logs) + - [Partitions](#partitions) + - [Storage usage](#storage-usage) + - [Compaction](#compaction) {{% warn %}} -#### May impact overall cluster performance +#### May impact cluster performance -Querying InfluxDB v3 system tables may impact the overall write and query +Querying InfluxDB v3 system tables may impact write and query performance of your {{< product-name omit=" Clustered" >}} cluster. +Use filters to [optimize queries to reduce impact to your cluster](#optimize-queries-to-reduce-impact-to-your-cluster). #### System tables are subject to change System tables are not part of InfluxDB's stable API and may change with new releases. -The provided schema information and query examples are valid as of **April 11, 2024**. +The provided schema information and query examples are valid as of **September 18, 2024**. If you detect a schema change or a non-functioning query example, please [submit an issue](https://github.com/influxdata/docs-v2/issues/new/choose). @@ -40,16 +54,13 @@ If you detect a schema change or a non-functioning query example, please ## Query system tables -{{% warn %}} -_Querying system tables [may impact overall cluster performance](#may-impact-overall-cluster-performance)._ -{{% /warn %}} - {{% note %}} Querying system tables with `influxctl` requires **`influxctl` v2.8.0 or newer**. {{% /note %}} Use the [`influxctl query` command](/influxdb/cloud-dedicated/reference/cli/influxctl/query/) -and SQL to query system tables. Provide the following: +and SQL to query system tables. +Provide the following: - **Enable system tables** with the `--enable-system-tables` command flag. - **Database token**: A [database token](/influxdb/cloud-dedicated/admin/tokens/#database-tokens) @@ -61,6 +72,7 @@ and SQL to query system tables. Provide the following: [`influxctl` connection profile](/influxdb/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) or the `--database` command flag. - **SQL query**: The SQL query to execute. + Pass the query in one of the following ways: - a string on the command line @@ -119,12 +131,152 @@ Replace the following: When prompted, enter `y` to acknowledge the potential impact querying system tables may have on your cluster. +### Optimize queries to reduce impact to your cluster + +Querying InfluxDB v3 system tables may impact the performance of your +{{< product-name omit=" Clustered" >}} cluster. +As you write data to a cluster, the number of partitions and Parquet files +can increase to a point that impacts system table performance. +Queries that took milliseconds with fewer files and partitions might take 10 +seconds or longer as files and partitions increase. + +Use the following filters to optimize your system table queries and reduce the impact on your +cluster's performance. + +In your queries, replace the following: + +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the table to retrieve partitions for +- {{% code-placeholder-key %}}`PARTITION_ID`{{% /code-placeholder-key %}}: a [partition ID](#retrieve-a-partition-id) (int64) +- {{% code-placeholder-key %}}`PARTITION_KEY`{{% /code-placeholder-key %}}: a [partition key](/influxdb/cloud-dedicated/admin/custom-partitions/#partition-keys) + derived from the table's partition template. + The default format is `%Y-%m-%d` (for example, `2024-01-01`). + +##### Filter by table name + +When querying the `system.tables`, `system.partitions`, or `system.compactor` tables, use the +`WHERE` clause to filter by `table_name` . + +{{% code-placeholders "TABLE_NAME" %}} +```sql +SELECT * FROM system.partitions WHERE table_name = 'TABLE_NAME' +``` +{{% /code-placeholders%}} + +##### Filter by partition key + +When querying the `system.partitions` or `system.compactor` tables, use the `WHERE` clause to +filter by `partition_key`. + +{{% code-placeholders "PARTITION_KEY" %}} +```sql +SELECT * FROM system.partitions WHERE partition_key = 'PARTITION_KEY' +``` +{{% /code-placeholders %}} + +To further improve performance, use `AND` to pair `partition_key` with `table_name`--for example: + +{{% code-placeholders "TABLE_NAME|PARTITION_KEY" %}} +```sql +SELECT * +FROM system.partitions +WHERE + table_name = 'TABLE_NAME' + AND partition_key = 'PARTITION_KEY'; +``` +{{% /code-placeholders %}} + +##### Filter by partition ID + +When querying the `system.partitions` or `system.compactor` table, use the `WHERE` clause to +filter by `partition_id` . + +{{% code-placeholders "PARTITION_ID" %}} +```sql +SELECT * FROM system.partitions WHERE partition_id = PARTITION_ID +``` +{{% /code-placeholders %}} + +For the most optimized approach, use `AND` to pair `partition_id` with `table_name`--for example: + +{{% code-placeholders "TABLE_NAME|PARTITION_ID" %}} +```sql +SELECT * +FROM system.partitions +WHERE + table_name = 'TABLE_NAME' + AND partition_id = PARTITION_ID; +``` +{{% /code-placeholders %}} + +Although you don't need to pair `partition_id` with `table_name` (because a partition ID is unique within a cluster), +it's the most optimized approach, _especially when you have many tables in a database_. + +###### Retrieve a partition ID + +To retrieve a partition ID, query `system.partitions` for a `table_name` and `partition_key` pair--for example: + +{{% code-placeholders "TABLE_NAME|PARTITION_KEY" %}} +```sql +SELECT + table_name, + partition_key, + partition_id +FROM system.partitions +WHERE + table_name = 'TABLE_NAME' + AND partition_key = 'PARTITION_KEY'; +``` +{{% /code-placeholders %}} + +The result contains the `partition_id`: + +| table_name | partition_key | partition_id | +| :--------- | :---------------- | -----------: | +| weather | 43 \| 2020-05-27 | 1362 | + +##### Combine filters for performance improvement + +Use the `AND`, `OR`, or `IN` keywords to combine filters in your query. + +- **Use `OR` or `IN` conditions when filtering for different values in the same column**--for example: + + ```sql + WHERE partition_id = 1 OR partition_id = 2 + ``` + + Use `IN` to make multiple `OR` conditions more readable--for example: + + ```sql + WHERE table_name IN ('foo', 'bar', 'baz') + ``` + +- **Avoid mixing different columns in `OR` conditions**, as this won't improve performance--for example: + + ```sql + WHERE table_name = 'foo' OR partition_id = 2 -- This will not improve performance + ``` + ## System tables {{% warn %}} _System tables are [subject to change](#system-tables-are-subject-to-change)._ {{% /warn %}} +### Understanding system table data distribution + +Data in `system.tables`, `system.partitions`, and `system.compactor` includes +data for all [InfluxDB Queriers](/influxdb/cloud-dedicated/reference/internals/storage-engine/#querier) in your cluster. +The data comes from the catalog, and because all the queriers share one catalog, +the results from these three tables derive from the same source data, +regardless of which querier you connect to. + +However, the `system.queries` table is different--data is local to each Querier. +`system.queries` contains a non-persisted log of queries run against the current +querier to which your query is routed. +The query log is specific to the current Querier and isn't shared across +queriers in your cluster. +Logs are scoped to the specified database. + - [system.queries](#systemqueries) - [system.tables](#systemtables) - [system.partitions](#systempartitions) @@ -132,12 +284,18 @@ _System tables are [subject to change](#system-tables-are-subject-to-change)._ ### system.queries -The `system.queries` table contains an unpersisted log of queries run against -the current [InfluxDB Querier](/influxdb/cloud-dedicated/reference/internals/storage-engine/#querier) -to which your query is routed. -The query log is specific to the current Querier and is not shared across Queriers -in your cluster. -Logs are scoped to the specified database. +The `system.queries` table stores log entries for queries executed for the provided namespace (database) on the node that is _currently handling queries_. +`system.queries` reflects a process-local, in-memory, namespace-scoped query log. + +While this table may be useful for debugging and monitoring queries, keep the following in mind: + +- Records stored in `system.queries` are transient and volatile + - InfluxDB deletes `system.queries` records during pod restarts. + - Queries for one namespace can evict records from another namespace. +- Data reflects the state of a specific pod answering queries for the namespace. + - Data isn't shared across queriers in your cluster. + - A query for records in `system.queries` can return different results + depending on the pod the request was routed to. {{< expand-wrapper >}} {{% expand "View `system.queries` schema" %}} @@ -146,9 +304,9 @@ The `system.queries` table contains the following columns: - id - phase -- issue_time -- query_type -- query_text +- **issue_time**: timestamp when the query was issued +- **query_type**: type (syntax: `sql`, `flightsql`, or `influxql`) of the query +- **query_text**: query statement text - partitions - parquet_files - plan_duration @@ -157,14 +315,20 @@ The `system.queries` table contains the following columns: - end2end_duration - compute_duration - max_memory -- success +- **success**: execution status (boolean) of the query - running - cancelled -- trace_id +- **trace_id**: trace ID for debugging and monitoring events {{% /expand %}} {{< /expand-wrapper >}} +{{% note %}} +_When listing measurements (tables) available within a namespace, +some clients and query tools may include the `queries` table in the list of +namespace tables._ +{{% /note %}} + ### system.tables The `system.tables` table contains information about tables in the specified database. @@ -202,7 +366,7 @@ The `system.partitions` table contains the following columns: ### system.compactor -The `system.compaction` table contains information about compacted partition Parquet +The `system.compactor` table contains information about compacted partition Parquet files associated with the specified database. {{< expand-wrapper >}} @@ -222,27 +386,36 @@ The `system.compactor` table contains the following columns: - skipped_reason {{% /expand %}} -{{< /expand-wrapper >}} +{{< /expand-wrapper >}} ## System query examples +{{% warn %}} +#### May impact cluster performance + +Querying InfluxDB v3 system tables may impact write and query +performance of your {{< product-name omit=" Clustered" >}} cluster. + +The examples in this section include `WHERE` filters to [optimize queries and reduce impact to your cluster](#optimize-queries-to-reduce-impact-to-your-cluster). +{{% /warn %}} + - [Query logs](#query-logs) - [View all stored query logs](#view-all-stored-query-logs) - [View query logs for queries with end-to-end durations above a threshold](#view-query-logs-for-queries-with-end-to-end-durations-above-a-threshold) + - [View query logs for a specific query within a time interval](#view-query-logs-for-a-specific-query-within-a-time-interval) - [Partitions](#partitions) - - [View partition templates of all tables](#view-partition-templates-of-all-tables) - [View the partition template of a specific table](#view-the-partition-template-of-a-specific-table) - [View all partitions for a table](#view-all-partitions-for-a-table) - [View the number of partitions per table](#view-the-number-of-partitions-per-table) - [View the number of partitions for a specific table](#view-the-number-of-partitions-for-a-specific-table) - [Storage usage](#storage-usage) - - [View the size of tables in megabytes](#view-the-size-of-tables-in-megabytes) - - [View the size of a specific table in megabytes](#view-the-size-of-a-specific-table-in-megabytes) - - [View the total size of all compacted partitions per table in bytes](#view-the-total-size-of-all-compacted-partitions-per-table-in-bytes) - - [View the total size of all compacted partitions in bytes](#view-the-total-size-of-all-compacted-partitions-in-bytes) + - [View the size in megabytes of a specific table](#view-the-size-in-megabytes-of-a-specific-table) + - [View the size in megabytes per table](#view-the-size-in-megabytes-per-table) + - [View the total size in bytes of compacted partitions per table](#view-the-total-size-in-bytes-of-compacted-partitions-per-table) + - [View the total size in bytes of compacted partitions for a specific table](#view-the-total-size-in-bytes-of-compacted-partitions-for-a-specific-table) - [Compaction](#compaction) - - [View overall compaction totals for each table](#view-overall-compaction-totals-for-each-table) - - [View overall compaction totals for a specific table](#view-overall-compaction-totals-for-a-specific-table) + - [View compaction totals for each table](#view-compaction-totals-for-each-table) + - [View compaction totals for a specific table](#view-compaction-totals-for-a-specific-table) In the examples below, replace {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}} with the name of the table you want to query information about. @@ -265,29 +438,75 @@ The following returns query logs for queries with an end-to-end duration greater than 50 milliseconds. ```sql -SELECT * FROM system.queries WHERE end2end_duration::BIGINT > (50 * 1000000) +SELECT * +FROM + system.queries +WHERE + end2end_duration::BIGINT > (50 * 1000000) ``` ---- +### View query logs for a specific query within a time interval + +{{< code-tabs >}} +{{% tabs %}} +[SQL](#) +[Python](#) +{{% /tabs %}} +{{% code-tab-content %}} + +```sql +SELECT * +FROM system.queries +WHERE issue_time >= now() - INTERVAL '1 day' + AND query_text LIKE '%select * from home%' +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```python +from influxdb_client_3 import InfluxDBClient3 +client = InfluxDBClient3(token = DATABASE_TOKEN, + host = HOSTNAME, + org = '', + database=DATABASE_NAME) +client.query('select * from home') +reader = client.query(''' + SELECT * + FROM system.queries + WHERE issue_time >= now() - INTERVAL '1 day' + AND query_text LIKE '%select * from home%' + ''', + language='sql', + headers=[(b"iox-debug", b"true")], + mode="reader") +``` + +{{% /code-tab-content %}} +{{< /code-tabs >}} + +--- ### Partitions -#### View partition templates of all tables - -```sql -SELECT * FROM system.tables -``` - #### View the partition template of a specific table ```sql -SELECT * FROM system.tables WHERE table_name = 'TABLE_NAME' +SELECT * +FROM + system.tables +WHERE + table_name = 'TABLE_NAME' ``` #### View all partitions for a table ```sql -SELECT * FROM system.partitions WHERE table_name = 'TABLE_NAME' +SELECT * +FROM + system.partitions +WHERE + table_name = 'TABLE_NAME' ``` #### View the number of partitions per table @@ -298,6 +517,8 @@ SELECT COUNT(*) AS partition_count FROM system.partitions +WHERE + table_name IN ('foo', 'bar', 'baz') GROUP BY table_name ``` @@ -313,23 +534,11 @@ WHERE table_name = 'TABLE_NAME' ``` ---- +--- ### Storage usage -#### View the size of tables in megabytes - -```sql -SELECT - table_name, - SUM(total_size_mb) AS total_size_mb -FROM - system.partitions -GROUP BY - table_name -``` - -#### View the size of a specific table in megabytes +#### View the size in megabytes of a specific table ```sql SELECT @@ -340,7 +549,21 @@ WHERE table_name = 'TABLE_NAME' ``` -#### View the total size of all compacted partitions per table in bytes +#### View the size in megabytes per table + +```sql +SELECT + table_name, + SUM(total_size_mb) AS total_size_mb +FROM + system.partitions +WHERE + table_name IN ('foo', 'bar', 'baz') +GROUP BY + table_name +``` + +#### View the total size in bytes of compacted partitions per table ```sql SELECT @@ -348,24 +571,28 @@ SELECT SUM(total_l0_bytes) + SUM(total_l1_bytes) + SUM(total_l2_bytes) AS total_bytes FROM system.compactor +WHERE + table_name IN ('foo', 'bar', 'baz') GROUP BY table_name ``` -#### View the total size of all compacted partitions in bytes +#### View the total size in bytes of compacted partitions for a specific table ```sql SELECT SUM(total_l0_bytes) + SUM(total_l1_bytes) + SUM(total_l2_bytes) AS total_bytes FROM system.compactor +WHERE + table_name = 'TABLE_NAME' ``` ---- +--- ### Compaction -#### View overall compaction totals for each table +#### View compaction totals for each table ```sql SELECT @@ -378,11 +605,13 @@ SELECT SUM(total_l2_bytes) AS total_l2_bytes FROM system.compactor +WHERE + table_name IN ('foo', 'bar', 'baz') GROUP BY table_name ``` -#### View overall compaction totals for a specific table +#### View compaction totals for a specific table ```sql SELECT diff --git a/content/influxdb/cloud-dedicated/admin/sso.md b/content/influxdb/cloud-dedicated/admin/sso.md index deb45d9e2..b837b1ab9 100644 --- a/content/influxdb/cloud-dedicated/admin/sso.md +++ b/content/influxdb/cloud-dedicated/admin/sso.md @@ -14,14 +14,14 @@ of [Auth0](https://auth0.com) and your identity provider of choice. Use SSO to provide users seamless access to your {{< product-name >}} cluster with an existing set of credentials. -{{% cloud %}} -#### Contact InfluxData sales to enable SSO - -SSO is a paid upgrade to your {{< product-name >}} cluster. -To begin the process of enabling SSO, contact InfluxData Sales: - -Contact InfluxData Sales -{{% /cloud %}} +> [!Important] +> +> #### Contact InfluxData sales to enable SSO +> +> SSO is a paid upgrade to your {{< product-name >}} cluster. +> To begin the process of enabling SSO, contact InfluxData Sales: +> +> Contact InfluxData Sales - [SSO authorization flow](#sso-authorization-flow) - [Set up your identity provider](#set-up-your-identity-provider) diff --git a/content/influxdb/cloud-dedicated/admin/tables/create.md b/content/influxdb/cloud-dedicated/admin/tables/create.md index 5c89acd02..a49a08e2b 100644 --- a/content/influxdb/cloud-dedicated/admin/tables/create.md +++ b/content/influxdb/cloud-dedicated/admin/tables/create.md @@ -34,7 +34,7 @@ to a table, you must manually create the table before you write any data to it. to use in the partition template - _Optional_: [InfluxDB tag buckets](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates) to use in the partition template - - _Optional_: A [Rust strftime date and time string](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) + - _Optional_: A supported [Rust strftime date and time string](/influxdb/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates) that specifies the time format in the partition template and determines the time interval to partition by _(default is `%Y-%m-%d`)_ - The name of the database to create the table in @@ -71,9 +71,9 @@ If no template flags are provided, the table uses the partition template of the target database. For more information, see [Manage data partitioning](/influxdb/cloud-dedicated/admin/custom-partitions/). -{{% note %}} +{{% warn %}} #### Partition templates can only be applied on create You can only apply a partition template when creating a table. There is no way to update a partition template on an existing table. -{{% /note %}} +{{% /warn %}} diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/create.md b/content/influxdb/cloud-dedicated/admin/tokens/database/create.md index 69d1cbf11..d0be6c137 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/create.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/create.md @@ -50,7 +50,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) to create a [database token](/influxdb/cloud-dedicated/admin/tokens/database/) with permissions for reading and writing data in your {{< product-name omit=" Clustered" >}} cluster. +or the [Management HTTP API](/influxdb/cloud-dedicated/api/management/) to create a [database token](/influxdb/cloud-dedicated/admin/tokens/database/) with permissions for reading and writing data in your {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} {{% tabs %}} @@ -435,4 +435,4 @@ curl \ {{% /code-placeholders %}} {{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} \ No newline at end of file +{{< /code-tabs-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md b/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md index b4232c262..fce52f815 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/delete.md @@ -32,7 +32,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) +or the [Management HTTP API](/influxdb/cloud-dedicated/api/management/) to delete a database token from your {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/list.md b/content/influxdb/cloud-dedicated/admin/tokens/database/list.md index cfa05bf4a..aaecbb1fe 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/list.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/list.md @@ -36,7 +36,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) +or the [Management HTTP API](/influxdb/cloud-dedicated/api/management/) to list database tokens in your {{< product-name omit=" Clustered" >}} cluster. [List database tokens](#list-database-tokens) diff --git a/content/influxdb/cloud-dedicated/admin/tokens/database/update.md b/content/influxdb/cloud-dedicated/admin/tokens/database/update.md index c728685ba..69abd7568 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/database/update.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/database/update.md @@ -53,7 +53,7 @@ related: --- Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/) -or the [Management HTTP API](influxdb/cloud-dedicated/api/management/) +or the [Management HTTP API](/influxdb/cloud-dedicated/api/management/) to update a database token's permissions {{< product-name omit=" Clustered" >}} cluster. {{< tabs-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/admin/tokens/management/_index.md b/content/influxdb/cloud-dedicated/admin/tokens/management/_index.md index be24443b1..8c8c79b3c 100644 --- a/content/influxdb/cloud-dedicated/admin/tokens/management/_index.md +++ b/content/influxdb/cloud-dedicated/admin/tokens/management/_index.md @@ -11,6 +11,8 @@ menu: name: Management tokens weight: 101 influxdb/cloud-dedicated/tags: [tokens] +related: + - /influxdb/cloud-dedicated/reference/internals/security/ --- Management tokens grant permission to perform administrative actions such as @@ -21,24 +23,27 @@ managing users, databases, and database tokens in your Management tokens do _not_ grant permissions to write or query time series data in your {{< product-name omit=" Clustered">}} cluster. -To grant write or query permissions, use management tokens to create [database tokens](/influxdb/cloud-dedicated/admin/tokens/database/). +To grant write or query permissions, use management tokens to create +[database tokens](/influxdb/cloud-dedicated/admin/tokens/database/). {{% /note %}} -By default, management tokens are short-lived tokens issued by an OAuth2 identity -provider that grant a specific user administrative access to your -{{< product-name omit=" Clustered">}} cluster. +By default, management tokens are short-lived tokens issued by your identity +provider for a [specific client session](/influxdb/cloud-dedicated/reference/internals/security/#management-tokens-in-the-influxctl-cli) (for example, `influxctl`). + However, for automation purposes, you can manually create management tokens that authenticate directly with your InfluxDB Cluster and do not require human interaction with your identity provider. +_Manually created management tokens provide full access to all account resources +and aren't affected by [user groups](/influxdb/cloud-dedicated/reference/internals/security/#user-groups)_. {{% warn %}} #### For automation use cases only -The tools outlined below are meant for automation use cases and should not be -used to circumvent your identity provider. **Take great care when manually creating -and using management tokens**. +The tools outlined below are meant for automation use cases and shouldn't be +used to circumvent your identity provider or user group permissions. +**Take great care when manually creating and using management tokens**. -{{< product-name >}} requires at least one user associated with your cluster +{{< product-name >}} requires at least one [Admin user](/influxdb/cloud-dedicated/reference/internals/security/#admin-user-group) associated with your cluster and authorized through your OAuth2 identity provider to manually create a management token. {{% /warn %}} diff --git a/content/influxdb/cloud-dedicated/admin/users/_index.md b/content/influxdb/cloud-dedicated/admin/users/_index.md new file mode 100644 index 000000000..43e9d3778 --- /dev/null +++ b/content/influxdb/cloud-dedicated/admin/users/_index.md @@ -0,0 +1,92 @@ +--- +title: Manage users +seotitle: Manage users and permissions in InfluxDB Cloud Dedicated +description: > + Manage users and access to resources in your InfluxDB Cloud Dedicated cluster. + Assign user groups for role-based access control and security. +menu: + influxdb_cloud_dedicated: + parent: Administer InfluxDB Cloud +weight: 101 +influxdb/cloud-dedicated/tags: [user groups] +related: + - /influxdb/cloud-dedicated/reference/internals/security/ + - /influxdb/cloud-dedicated/admin/tokens/ +--- + +Manage users and access to resources in your {{% product-name %}} cluster. + +By assigning users to different groups based on the level of access they need, +you can minimize unnecessary access and reduce the risk of inadvertent +actions. +User groups associate access privileges with user attributes--an important part of the +Attribute-Based Access Control (ABAC) security model which grants access based on +user attributes, resource types, and environment context. + +- [Available user groups](#available-user-groups) +- [Manage users](#manage-users) + +## Available user groups + +In {{% product-name %}}, users have "management" responsibilities, such as creating and +deleting [databases](/influxdb/cloud-dedicated/admin/databases/), [viewing resource information](/influxdb/cloud-dedicated/admin/monitor-your-cluster/), and provisioning +[database tokens](/influxdb/cloud-dedicated/admin/tokens/database/) for reading and writing data. + +A user can belong to the following groups, each with predefined privileges: + +- **Admin**: Read and write permissions on all resources. +- **Member**: Read permission on certain resources and create permission for + database tokens; members can't delete or create databases or management tokens. +- **Auditor**: Read permission on all resources; auditors can't modify resources. + +{{% note %}} +#### Existing users are Admin by default + +With the release of user groups for {{% product-name %}}, all existing users +in your account are initially assigned to the Admin group, retaining full +access to resources in your cluster. +{{% /note %}} + +## Manage users + +- [Assign a user to a different group](#assign-a-user-to-a-different-group) +- [Invite a user to your account](#invite-a-user-to-your-account) + +### Assign a user to a different group + +To assign existing users in your account to different +groups, [contact InfluxData support](https://support.influxdata.com/s/login/) +and provide the list of users and the desired [user groups](#available-user-groups) +for each. + +### Invite a user to your account + +For new users that you want to add to your account, the InfluxData Support Team +configures invitations with the attributes and groups that you specify. + +1. [Contact InfluxData support](https://support.influxdata.com/s/login/) + to invite a user to your account. + In your request, provide the user details, including email address, desired + [user groups](#available-user-groups), and other attributes for the user. +2. InfluxData support creates the user account and emails the user an invitation + that includes following: + + - A login URL to authenticate access to the cluster + - The {{% product-name %}} **account ID** + - The {{% product-name %}} **cluster ID** + - The {{% product-name %}} **cluster URL** + - A password reset email for setting the login password + +3. The user accepts the invitation to your account + +With a valid password, the user can access cluster resources by interacting with the +[`influxctl`](/influxdb/cloud-dedicated/reference/influxctl/) command line tool. +The assigned user groups determine the user's access to resources. + +{{% note %}} +#### Use database tokens to authorize data reads and writes + +In {{% product-name %}}, user groups control access for managing cluster resources. +[Database tokens](/influxdb/cloud-dedicated/admin/tokens/database/) control access +for reading and writing data in cluster databases. +{{% /note %}} diff --git a/content/influxdb/cloud-dedicated/get-started/query.md b/content/influxdb/cloud-dedicated/get-started/query.md index 4b1ee4f91..9cbf6bd3d 100644 --- a/content/influxdb/cloud-dedicated/get-started/query.md +++ b/content/influxdb/cloud-dedicated/get-started/query.md @@ -162,7 +162,7 @@ WHERE {{% influxdb/custom-timestamps %}} ```sql SELECT - DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time, + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') as _time, room, selector_max(temp, time)['value'] AS 'max temp' FROM @@ -593,8 +593,7 @@ _If your project's virtual environment is already running, skip to step 3._ "time" "text/tabwriter" - "github.com/apache/arrow/go/v13/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -638,10 +637,9 @@ _If your project's virtual environment is already running, skip to step 3._ // Iterate over rows and prints column values in table format. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339). - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) @@ -661,8 +659,7 @@ _If your project's virtual environment is already running, skip to step 3._ - `io` - `os` - `text/tabwriter` - - `github.com/apache/arrow/go/v13/arrow` - - `github.com/InfluxCommunity/influxdb3-go/influxdb3` + - `github.com/InfluxCommunity/influxdb3-go/v2/influxdb3` 2. Defines a `Query()` function that does the following: diff --git a/content/influxdb/cloud-dedicated/get-started/setup.md b/content/influxdb/cloud-dedicated/get-started/setup.md index dc9ecc8dd..17c059110 100644 --- a/content/influxdb/cloud-dedicated/get-started/setup.md +++ b/content/influxdb/cloud-dedicated/get-started/setup.md @@ -14,6 +14,7 @@ weight: 101 metadata: [1 / 3] related: - /influxdb/cloud-dedicated/admin/databases/ + - /influxdb/cloud-dedicated/admin/tokens/ - /influxdb/cloud-dedicated/reference/cli/influxctl/ - /influxdb/cloud-dedicated/reference/api/ --- diff --git a/content/influxdb/cloud-dedicated/get-started/write.md b/content/influxdb/cloud-dedicated/get-started/write.md index 3e94cf27e..723bd4dd4 100644 --- a/content/influxdb/cloud-dedicated/get-started/write.md +++ b/content/influxdb/cloud-dedicated/get-started/write.md @@ -835,7 +835,7 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 "fmt" "log" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) // Write line protocol data to InfluxDB diff --git a/content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md b/content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md index d654d00a4..8a434a522 100644 --- a/content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md +++ b/content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md @@ -457,7 +457,8 @@ For {{% product-name %}} v1 API `/query` requests, set parameters as listed in t Parameter | Allowed in | Ignored | Value ----------|------------|---------|------------------------------------------------------------------------- -`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_ +`chunked` | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. +`chunked_size` | Query string | Honored | **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. `db` | Query string | Honored | Database name | `epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision) | `p` | Query string | Honored | Database token diff --git a/content/influxdb/cloud-dedicated/guides/migrate-data/migrate-tsm-to-cloud-dedicated.md b/content/influxdb/cloud-dedicated/guides/migrate-data/migrate-tsm-to-cloud-dedicated.md index 897026189..85b86519c 100644 --- a/content/influxdb/cloud-dedicated/guides/migrate-data/migrate-tsm-to-cloud-dedicated.md +++ b/content/influxdb/cloud-dedicated/guides/migrate-data/migrate-tsm-to-cloud-dedicated.md @@ -28,10 +28,9 @@ that queries data from an InfluxDB Cloud TSM-powered bucket in time-based batche and writes each batch to an {{< product-name >}} (InfluxDB v3) database in another organization. -{{% cloud %}} -All query requests are subject to your InfluxDB Cloud organization's -[rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). -{{% /cloud %}} +> [!Important] +> All query requests are subject to your InfluxDB Cloud organization's +> [rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - [Before you migrate](#before-you-migrate) - [Set up the migration](#set-up-the-migration) diff --git a/content/influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/go.md b/content/influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/go.md index df1933e5f..b9ee9b6b7 100644 --- a/content/influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/go.md +++ b/content/influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/go.md @@ -21,7 +21,7 @@ list_code_example: | ```go import ( "context" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -94,7 +94,7 @@ to install a recent version of the Go programming language for your system. In your terminal, enter the following command to download and install the client library: ```sh -go get github.com/InfluxCommunity/influxdb3-go +go get github.com/InfluxCommunity/influxdb3-go/v2 ``` - [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go) {{< req text="\* " color="magenta" >}}: Provides the `influxdb3` package and also installs the [Apache `arrow` module](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries. @@ -139,8 +139,7 @@ import ( "text/tabwriter" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" - "github.com/apache/arrow/go/v13/arrow" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -187,10 +186,9 @@ func Query() error { fmt.Fprintln(w, "Process each row as key-value pairs:") for iterator2.Next() { row := iterator2.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) @@ -236,8 +234,7 @@ import ( "text/tabwriter" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" - "github.com/apache/arrow/go/v13/arrow" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func InfluxQL() error { @@ -289,10 +286,9 @@ func InfluxQL() error { fmt.Fprintln(w, "Process each row as key-value pairs:") for iterator2.Next() { row := iterator2.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/cloud-dedicated/query-data/influxql/parameterized-queries.md b/content/influxdb/cloud-dedicated/query-data/influxql/parameterized-queries.md index 3769e1e3a..7402ee2e0 100644 --- a/content/influxdb/cloud-dedicated/query-data/influxql/parameterized-queries.md +++ b/content/influxdb/cloud-dedicated/query-data/influxql/parameterized-queries.md @@ -257,8 +257,7 @@ import ( "os" "text/tabwriter" "time" - "github.com/apache/arrow/go/v14/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query(query string, parameters influxdb3.QueryParameters, @@ -301,10 +300,10 @@ func Query(query string, parameters influxdb3.QueryParameters, // Process each row as key-value pairs. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339 format) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.Nanosecond).Format(time.RFC3339) + time := (row["time"].(time.Time)). + Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md b/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md index 9ce83c063..3dde19654 100644 --- a/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md +++ b/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md @@ -28,7 +28,7 @@ list_code_example: | ##### Aggregate by time-based intervals ```sql SELECT - DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) AS time, + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') AS time, mean(field1), sum(field2), tag1 @@ -206,7 +206,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time FROM home ... ``` @@ -225,7 +225,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time ... GROUP BY 1, room ... @@ -235,7 +235,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS _time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time FROM home ... GROUP BY _time, room @@ -247,7 +247,7 @@ The following example retrieves unique combinations of time intervals and rooms ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', @@ -288,7 +288,7 @@ If you want to reference a calculated time column by name, use an alias differen ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time, room, selector_max(temp, time)['value'] AS 'max temp', diff --git a/content/influxdb/cloud-dedicated/query-data/sql/parameterized-queries.md b/content/influxdb/cloud-dedicated/query-data/sql/parameterized-queries.md index b149ea65f..9296e0820 100644 --- a/content/influxdb/cloud-dedicated/query-data/sql/parameterized-queries.md +++ b/content/influxdb/cloud-dedicated/query-data/sql/parameterized-queries.md @@ -254,8 +254,7 @@ import ( "os" "text/tabwriter" "time" - "github.com/apache/arrow/go/v14/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query(query string, parameters influxdb3.QueryParameters) error { @@ -297,10 +296,10 @@ func Query(query string, parameters influxdb3.QueryParameters) error { // Process each row as key-value pairs. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339 format) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.Nanosecond).Format(time.RFC3339) + time := (row["time"].(time.Time)). + Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan.md b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan.md index 915b95683..f0da76fe1 100644 --- a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan.md +++ b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan.md @@ -25,7 +25,7 @@ By learning how to generate and interpret reports for the query plan, you can better understand how the query is executed and identify bottlenecks that affect the performance of your query. For example, if the query plan reveals that your query reads a large number of Parquet files, -you can then take steps to [optimize your query](/influxdb/cloud-dedicated/query-data/optimize-queries/), such as add filters to read less data or +you can then take steps to [optimize your query](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries/), such as add filters to read less data or configure your cluster to store fewer and larger files. - [Use EXPLAIN keywords to view a query plan](#use-explain-keywords-to-view-a-query-plan) @@ -113,7 +113,7 @@ Plans are in _tree format_--each plan is an upside-down tree in which execution and data flow from _leaf nodes_, the innermost steps in the plan, to outer _branch nodes_. Whether reading a logical or physical plan, keep the following in mind: -- Start at the the _leaf nodes_ and read upward. +- Start at the _leaf nodes_ and read upward. - At the top of the plan, the _root node_ represents the final, encompassing step. In a [physical plan](/influxdb/cloud-dedicated/reference/internals/query-plan/#physical-plan), each step is an [`ExecutionPlan` node](/influxdb/cloud-dedicated/reference/internals/query-plan/#execution-plan-nodes) that receives expressions for input data and output requirements, and computes a partition of data. @@ -770,4 +770,4 @@ Operator structure for aggregating, sorting, and final output. - `SortPreservingMergeExec: [city@0 ASC NULLS LAST]`: Merges and sorts the four sorted streams for the final output. In the preceding examples, the `EXPLAIN` report shows the query plan without executing the query. -To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/cloud-dedicated/reference/sql/explain/#explain-analyze) to generate the report and [tracing](/influxdb/cloud-dedicated/query-data/optimize-queries/#enable-trace-logging) for further debugging, if necessary. +To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/cloud-dedicated/reference/sql/explain/#explain-analyze) to generate the report and [tracing](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries/#enable-trace-logging) for further debugging, if necessary. diff --git a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries.md b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries.md index 5a297bd9a..6723b329f 100644 --- a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries.md +++ b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries.md @@ -16,6 +16,8 @@ related: aliases: - /influxdb/cloud-dedicated/query-data/execute-queries/optimize-queries/ - /influxdb/cloud-dedicated/query-data/execute-queries/analyze-query-plan/ + - /influxdb/cloud-dedicated/query-data/optimize-queries/ + --- Optimize SQL and InfluxQL queries to improve performance and reduce their memory and compute (CPU) requirements. @@ -24,38 +26,26 @@ Learn how to use observability tools to analyze query execution and view metrics - [Why is my query slow?](#why-is-my-query-slow) - [Strategies for improving query performance](#strategies-for-improving-query-performance) - [Query only the data you need](#query-only-the-data-you-need) -- [Analyze and troubleshoot queries](#analyze-and-troubleshoot-queries) +- [Recognize and address bottlenecks](#recognize-and-address-bottlenecks) + ## Why is my query slow? -Query performance depends on time range and complexity. -If a query is slower than you expect, it might be due to the following reasons: +Query performance depends on factors like the time range and query complexity. +If a query is slower than expected, consider the following potential causes: -- It queries data from a large time range. -- It includes intensive operations, such as querying many string values or `ORDER BY` sorting or re-sorting large amounts of data. +- The query spans a large time range, which increases the amount of data being processed. +- The query performs intensive operations, such as: + - Sorting or re-sorting large datasets with `ORDER BY`. + - Querying many string values, which can be computationally expensive. ## Strategies for improving query performance -The following design strategies generally improve query performance and resource use: +The following design strategies generally improve query performance and resource usage: -- Follow [schema design best practices](/influxdb/cloud-dedicated/write-data/best-practices/schema-design/) to make querying easier and more performant. -- [Query only the data you need](#query-only-the-data-you-need). -- [Downsample data](/influxdb/cloud-dedicated/process-data/downsample/) to reduce the amount of data you need to query. - -Some bottlenecks may be out of your control and are the result of a suboptimal execution plan, such as: - -- Applying the same sort (`ORDER BY`) to already sorted data. -- Retrieving many Parquet files from the Object store--the same query performs better if it retrieves fewer - though, larger - files. -- Querying many overlapped Parquet files. -- Performing a large number of table scans. - -{{% note %}} -#### Analyze query plans to view metrics and recognize bottlenecks - -To view runtime metrics for a query, such as the number of files scanned, use -the [`EXPLAIN ANALYZE` keywords](/influxdb/cloud-dedicated/reference/sql/explain/#explain-analyze) -and learn how to [analyze a query plan](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan/). -{{% /note %}} +- Follow [schema design best practices](/influxdb/cloud-dedicated/write-data/best-practices/schema-design/) to simplify and improve queries. +- [Query only the data you need](#query-only-the-data-you-need) to reduce unnecessary processing. +- [Downsample data](/influxdb/cloud-dedicated/process-data/downsample/) to decrease the volume of data queried. ### Query only the data you need @@ -87,10 +77,30 @@ two queries is minimal. In a table with over 1000 columns, the `SELECT *` query is slower and less efficient. -## Analyze and troubleshoot queries +## Recognize and address bottlenecks -Use the following tools to analyze and troubleshoot queries and find performance bottlenecks: +To identify performance bottlenecks, learn how to [analyze a query plan](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan/). +Query plans provide runtime metrics, such as the number of files scanned, that may reveal inefficiencies in query execution. -- [Analyze a query plan](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan/) -- [Enable trace logging for a query](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/trace/) -- [Retrieve `system.queries` information for a query](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/system-information/) +> [!Note] +> +> #### Request help to troubleshoot queries +> +> Some bottlenecks may result from suboptimal query [execution plans](/influxdb/cloud-dedicated/reference/internals/query-plan/#physical-plan) and are outside your control--for example: +> +> - Sorting (`ORDER BY`) data that is already sorted. +> - Retrieving numerous small Parquet files from the object store instead of fewer, larger files. +> - Querying many overlapped Parquet files. +> - Performing a high number of table scans. +> +> If you have followed steps to [optimize](#why-is-my-query-slow) and +> [troubleshoot a query](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/troubleshoot/), +> but it still doesn't meet performance requirements, +> contact the [InfluxData Support team](https://support.influxdata.com) for assistance. +> +> #### Query trace logging +> +> Currently, customers cannot enable trace logging for {{% product-name omit="Clustered" %}} clusters. +> InfluxData engineers can use query plans and trace logging to help pinpoint performance bottlenecks in a query. +> +> For help troubleshooting a query, contact the [InfluxData Support team](https://support.influxdata.com). diff --git a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/system-information.md b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/system-information.md index 7bb927cfc..72fd34b9a 100644 --- a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/system-information.md +++ b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/system-information.md @@ -22,15 +22,10 @@ The information in each system table is scoped to the namespace you're querying; you can only retrieve system information for that particular instance. To get information about queries you've run on the current instance, use SQL to query the [`system.queries` table](/influxdb/cloud-dedicated/reference/internals/system-tables/#systemqueries-measurement), which contains information from the Querier instance currently handling queries. -If you [enabled trace logging](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/trace/) for the query, the `trace-id` appears in the `system.queries.trace_id` column for the query. The `system.queries` table is an InfluxDB v3 **debug feature**. -To enable the feature and query `system.queries`, include an `"iox-debug"` header set to `"true"` and use SQL to query the table. +To enable the feature and query `system.queries`, include an `"iox-debug"` header set to `"true"` and use SQL to query the table--for example: -The following sample code shows how to use the Python client library to do the following: - -1. Enable tracing for a query. -2. Retrieve the trace ID record from `system.queries`. + Learn how to enable trace logging to help you identify performance bottlenecks and troubleshoot problems in queries. When you enable trace logging for a query, InfluxDB propagates your _trace ID_ through system processes and collects additional log information. diff --git a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/troubleshoot.md b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/troubleshoot.md index 80b91422d..ad812f0f4 100644 --- a/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/troubleshoot.md +++ b/content/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/troubleshoot.md @@ -14,12 +14,15 @@ related: - /influxdb/cloud-dedicated/reference/client-libraries/v3/ aliases: - /influxdb/cloud-dedicated/query-data/execute-queries/troubleshoot/ + - /influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/trace/ --- Troubleshoot SQL and InfluxQL queries that return unexpected results. - [Why doesn't my query return data?](#why-doesnt-my-query-return-data) - [Optimize slow or expensive queries](#optimize-slow-or-expensive-queries) +- [Analyze your queries](#analyze-your-queries) +- [Request help to troubleshoot queries](#request-help-to-troubleshoot-queries) ## Why doesn't my query return data? @@ -48,4 +51,35 @@ If a query times out or returns an error, it might be due to the following: If a query is slow or uses too many compute resources, limit the amount of data that it queries. -See how to [optimize queries](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries/) and use tools to view runtime metrics, identify bottlenecks, and debug queries. +See how to [optimize queries](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries/). + +## Analyze your queries + +Use the following tools to retrieve system query information, analyze query execution, +and find performance bottlenecks: + +- [Analyze a query plan](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/analyze-query-plan/) +- [Retrieve `system.queries` information for a query](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/system-information/) + +#### Request help to troubleshoot queries + +Some bottlenecks may result from suboptimal query [execution plans](/influxdb/cloud-dedicated/reference/internals/query-plan/#physical-plan) and are outside your control--for example: + +- Sorting (`ORDER BY`) data that is already sorted +- Retrieving numerous small Parquet files from the object store, instead of fewer, larger files +- Querying many overlapped Parquet files +- Performing a high number of table scans + +If you've followed steps to [optimize](/influxdb/cloud-dedicated/query-data/troubleshoot-and-optimize/optimize-queries/) +and [troubleshoot a query](#why-doesnt-my-query-return-data), +but it still doesn't meet performance requirements, +contact the [InfluxData Support team](https://support.influxdata.com) for assistance. + +> [!Note] +> +> #### Query trace logging +> +> Currently, customers cannot enable trace logging for {{% product-name omit="Clustered" %}} clusters. +> InfluxData engineers can use query plans and trace logging to help pinpoint performance bottlenecks in a query. +> +> For help troubleshooting a query, contact the [InfluxData Support team](https://support.influxdata.com). diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/_index.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/_index.md index 1aad420ea..d5f69eb40 100644 --- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/_index.md +++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/_index.md @@ -17,7 +17,7 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster. - [Usage](#usage) - [Commands](#commands) -- [Flags](#command-flags) +- [Global flags](#global-flags) - [Download and install influxctl](#download-and-install-influxctl) - [Configure connection profiles](#configure-connection-profiles) - [Authentication](#authentication) @@ -25,14 +25,14 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster. ## Usage ```sh -influxctl [flags] [command] +influxctl [global-flags] [command] ``` ## Commands | Command | Description | | :-------------------------------------------------------------------------- | :------------------------------------- | -| [auth](/influxdb/cloud-dedicated/reference/cli/influxctl/auth/) | Log in to or log out of InfluxDB v3 | +| [auth](/influxdb/cloud-dedicated/reference/cli/influxctl/auth/) | Log in to or log out of InfluxDB v3 | | [cluster](/influxdb/cloud-dedicated/reference/cli/influxctl/cluster/) | List InfluxDB v3 cluster information | | [database](/influxdb/cloud-dedicated/reference/cli/influxctl/database/) | Manage InfluxDB v3 databases | | [help](/influxdb/cloud-dedicated/reference/cli/influxctl/help/) | Output `influxctl` help information | @@ -45,15 +45,16 @@ influxctl [flags] [command] ## Global flags -| Flag | | Description | -| :--- | :---------- | :--------------------------------------------------------- | -| | `--debug` | Enable debug logging | -| | `--account` | Override account ID value in configuration file | -| | `--cluster` | Override cluster ID value in configuration file | -| | `--config` | Path to configuration file to use | -| | `--profile` | Specify a connection profile to use (default is `default`) | -| | `--trace` | Enable more verbose debug logging | -| `-h` | `--help` | Show help | +| Flag | | Description | +| :--- | :---------- | :----------------------------------------------------------- | +| | `--debug` | Enable debug logging | +| | `--account` | Override account ID value in configuration file | +| | `--cluster` | Override cluster ID value in configuration file | +| | `--config` | Path to configuration file to use | +| | `--profile` | Specify a connection profile to use (default is `default`) | +| | `--timeout` | Specify a timeout duration for API calls (default is `1m0s`) | +| | `--trace` | Enable more verbose debug logging | +| `-h` | `--help` | Show help | --- @@ -344,7 +345,6 @@ If stored at a non-default location, include the `--config` flag with each ## OAuth2 client authorization settings # [profile.auth.oauth2] # client_id = "" - # client_secret = "" # scopes = [""] # parameters = { audience = "" } # token_url = "https://indentityprovider/oauth2/v2/token" diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/database/create.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/database/create.md index 6ef6e4f8e..8096cb225 100644 --- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/database/create.md +++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/database/create.md @@ -156,8 +156,8 @@ influxctl database create \ ### Create a database with a custom partition template The following example creates a new `mydb` database and applies a partition -template that partitions by two tags (`room` and `sensor-type`) and by week using -the time format `%Y wk:%W`: +template that partitions by two tags (`room` and `sensor-type`) and by day using +the time format `%Y-%m-%d`: @@ -167,7 +167,7 @@ influxctl database create \ --template-tag room \ --template-tag sensor-type \ --template-tag-bucket customerID,1000 \ - --template-timeformat '%Y wk:%W' \ + --template-timeformat '%Y-%m-%d' \ mydb ``` diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/query.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/query.md index 1a58f28bd..66151e621 100644 --- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/query.md +++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/query.md @@ -420,7 +420,7 @@ Querying system tables can impact the overall performance of your InfluxDB's stable API and are subject to change. {{% /warn %}} -{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} +{{% code-placeholders "DATABASE_(TOKEN|NAME)|TABLE_NAME" %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} @@ -435,7 +435,7 @@ influxctl query \ --enable-system-tables \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ - "SELECT * FROM system.tables" + "SELECT * FROM system.tables WHERE table_name = 'TABLE_NAME'" ``` {{% /influxdb/custom-timestamps %}} {{% /code-tab-content %}} diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/table/create.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/table/create.md index fb0013ee1..dc817e362 100644 --- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/table/create.md +++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/table/create.md @@ -82,8 +82,8 @@ influxctl table create DATABASE_NAME TABLE_NAME ### Create a table with a custom partition template The following example creates a new table and applies a partition -template that partitions by two tags (`room` and `sensor-type`) and by week using -the time format `%Y wk:%W`: +template that partitions by two tags (`room` and `sensor-type`) and by day using +the time format `%Y-%m-%d`: {{% code-placeholders "(DATABASE|TABLE)_NAME" %}} ```sh @@ -91,7 +91,7 @@ influxctl table create \ --template-tag room \ --template-tag sensor-type \ --template-tag-bucket customerID,1000 \ - --template-timeformat '%Y wk:%W' \ + --template-timeformat '%Y-%m-%d' \ DATABASE_NAME \ TABLE_NAME ``` diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/user/delete.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/user/delete.md index e148e0a01..ba0a71e28 100644 --- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/user/delete.md +++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/user/delete.md @@ -9,6 +9,13 @@ weight: 301 draft: true --- +{{% warn %}} +#### InfluxData internal use only + +This command is for InfluxData internal use only and won't work when run by +a user account. +{{% /warn %}} + The `influxctl user delete` command deletes a user from your {{< product-name >}} account. diff --git a/content/influxdb/cloud-dedicated/reference/cli/influxctl/user/invite.md b/content/influxdb/cloud-dedicated/reference/cli/influxctl/user/invite.md index 61ae750a3..d3a84f2ec 100644 --- a/content/influxdb/cloud-dedicated/reference/cli/influxctl/user/invite.md +++ b/content/influxdb/cloud-dedicated/reference/cli/influxctl/user/invite.md @@ -1,7 +1,7 @@ --- title: influxctl user invite description: > - The `influxctl user invite` command invites a user to your InfluxDB Cloud Dedicated + The `influxctl user invite` command invites a user to an InfluxDB Cloud Dedicated account. menu: influxdb_cloud_dedicated: @@ -10,7 +10,14 @@ weight: 301 draft: true --- -The `influxctl user invite` command invites a user to your {{< product-name >}} +{{% warn %}} +#### InfluxData internal use only + +This command is for InfluxData internal use only and won't work when run by +a user account. +{{% /warn %}} + +The `influxctl user invite` command invites a user to an {{< product-name >}} account. ## Usage diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md b/content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md index 23a0823c8..5b7b1bf6f 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md @@ -21,7 +21,7 @@ list_code_example: | sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, - '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md index a1754ddc2..279ef36c1 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md @@ -1,7 +1,7 @@ --- title: InfluxDB v2 API client libraries description: > - InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). + InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). View the list of available client libraries. weight: 101 menu: @@ -25,7 +25,7 @@ prepend: ## Client libraries for InfluxDB 2.x and 1.8+ InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. -InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). +InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). Functionality varies among client libraries. InfluxDB client libraries are maintained by the InfluxDB community. diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md index 8026aa552..97d5438fa 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md @@ -33,11 +33,13 @@ prepend: 3. In your terminal, create a directory for your Node.js project and change to it. ```sh - mkdir influx-node-app && cd $_ + mkdir influx-node-app && cd influx-node-app ``` 4. Enter the following command to generate an npm package for your project. - The `npm` package manager is included with Node.js. + + - `npm`: the package manager included with Node.js + - `-y`: uses defaults for the package and bypasses prompts ```sh npm init -y @@ -53,15 +55,21 @@ Follow these steps to initialize the TypeScript project: ```sh npm i -g typescript && npm i --save-dev @types/node ``` -2. Create a TypeScript configuration with default values. + +2. Enter the following command to create a TypeScript configuration + (`tsconfig.json`) with default values: ```sh tsc --init ``` -3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. +3. Run the TypeScript compiler. + To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. + + + ```sh - tsc -w -p + tsc --watch ``` ## Install dependencies diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md index 13d6077f5..240556922 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md @@ -20,7 +20,7 @@ to write and query data stored in an {{% product-name %}} database. ## Installation ```sh -go get github.com/InfluxCommunity/influxdb3-go +go get github.com/InfluxCommunity/influxdb3-go/v2 ``` ## Importing the package @@ -31,7 +31,7 @@ Import the package: ```go import ( - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) ``` @@ -75,7 +75,7 @@ Initializes and returns a `influxdb3.Client` instance with the following: package main import ( - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func main() { @@ -177,4 +177,4 @@ query := `SELECT * AND time <= 1641124000s + 8h` queryOptions := influxdb3.QueryOptions{QueryType: influxdb3.InfluxQL} iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query) -``` \ No newline at end of file +``` diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md index 6ea1c9859..d8e3e5ad6 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md @@ -8,48 +8,45 @@ menu: parent: v3 client libraries identifier: influxdb3-python influxdb/cloud-dedicated/tags: [Flight API, python, gRPC, SQL, client libraries] -metadata: [influxdb3-python v0.5.0] +metadata: [influxdb3-python v0.10.0] weight: 201 aliases: - /influxdb/cloud-dedicated/reference/client-libraries/v3/pyinflux3/ related: - /influxdb/cloud-dedicated/query-data/execute-queries/troubleshoot/ -list_code_example: > - + ```python - from influxdb_client_3 import(InfluxDBClient3, - WriteOptions, - write_client_options) + # Example: Write and query data - # Instantiate batch writing options for the client + # Write sensor data in batches from a CSV file to a database + client.write_file(file='./data/home-sensor-data.csv', + timestamp_column='time', + tag_columns=["room"]) - write_options = WriteOptions() - wco = write_client_options(write_options=write_options) - - # Instantiate an InfluxDB v3 client - - with InfluxDBClient3(host=f"{{< influxdb/host >}}", - database=f"DATABASE_NAME", - token=f"DATABASE_TOKEN", - write_client_options=wco) as client: - - # Write data in batches - client.write_file(file='./data/home-sensor-data.csv', timestamp_column='time', - tag_columns=["room"]) - - # Execute a query and retrieve data formatted as a PyArrow Table - - table = client.query( + # Execute a query and retrieve data from the last 90 days + table = client.query( '''SELECT * FROM home WHERE time >= now() - INTERVAL '90 days' ORDER BY time''') - ``` + + # This script assumes the client object is correctly configured + # with your database name, token, and host URL. + # After the script runs, the table variable contains the data + # formatted as a PyArrow table. + ``` --- The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python) @@ -118,7 +115,7 @@ from influxdb_client_3 import InfluxDBClient3, Point, WriteOptions - [`influxdb_client_3.Point`](#class-point): a class for constructing a time series data point - `influxdb_client_3.WriteOptions`: a class for configuring client - write options. + write options ## API reference @@ -185,9 +182,8 @@ Given that `write_client_options` isn't specified, the client uses the default [ ```python import os ``` - - --> + ```python from influxdb_client_3 import InfluxDBClient3 @@ -958,7 +954,7 @@ fh.close() client = InfluxDBClient3(host=f"{{< influxdb/host >}}", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN", - fco=flight_client_options(tls_root_certs=cert)) + flight_client_options=flight_client_options(tls_root_certs=cert)) ``` {{% /code-placeholders %}} diff --git a/content/influxdb/cloud-dedicated/reference/glossary.md b/content/influxdb/cloud-dedicated/reference/glossary.md index 1034d43b3..8e9e84714 100644 --- a/content/influxdb/cloud-dedicated/reference/glossary.md +++ b/content/influxdb/cloud-dedicated/reference/glossary.md @@ -46,7 +46,8 @@ Related entries: ### aggregate A function that returns an aggregated value across a set of points. -For a list of available aggregation functions, see [SQL aggregate functions](/influxdb/cloud-dedicated/reference/sql/functions/aggregate/). +For a list of available aggregation functions, +see [SQL aggregate functions](/influxdb/cloud-dedicated/reference/sql/functions/aggregate/). @@ -330,6 +331,7 @@ Related entries: [field](#field), [field key](#field-key), [field set](#field-set), +[tag set](#tag-set), [tag value](#tag-value), [timestamp](#timestamp) @@ -356,7 +358,7 @@ Related entries: Flush jitter prevents every Telegraf output plugin from sending writes simultaneously, which can overwhelm some data sinks. -Each flush interval, every Telegraf output plugin will sleep for a random time +Each flush interval, every Telegraf output plugin sleeps for a random time between zero and the flush jitter before emitting metrics. Flush jitter smooths out write spikes when running a large number of Telegraf instances. @@ -369,7 +371,7 @@ Related entries: A function is an operation that performs a specific task. Functions take input, operate on that input, and then return output. For a complete list of available SQL functions, see -[SQL functions](/inflxudb/cloud-dedicated/reference/sql/functions/). +[SQL functions](/influxdb/cloud-dedicated/reference/sql/functions/). @@ -400,10 +402,10 @@ Identifiers are tokens that refer to specific database objects such as database names, field keys, measurement names, tag keys, etc. Related entries: -[database](#database) +[database](#database), [field key](#field-key), [measurement](#measurement), -[tag key](#tag-key), +[tag key](#tag-key) ### influx @@ -422,8 +424,7 @@ and other required processes. ### InfluxDB -An open source time series database (TSDB) developed by InfluxData. -Written in Go and optimized for fast, high-availability storage and retrieval of +An open source time series database (TSDB) developed by InfluxData, optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet of Things sensor data, and real-time analytics. @@ -435,8 +436,8 @@ The SQL-like query language used to query data in InfluxDB. Telegraf input plugins actively gather metrics and deliver them to the core agent, where aggregator, processor, and output plugins can operate on the metrics. -In order to activate an input plugin, it needs to be enabled and configured in -Telegraf's configuration file. +To activate an input plugin, enable and configure it in the +Telegraf configuration file. Related entries: [aggregator plugin](#aggregator-plugin), @@ -760,7 +761,7 @@ in the cluster (replication factor), and the time range covered by shard groups (shard group duration). RPs are unique per database and along with the measurement and tag set define a series. -In {{< product-name >}} the equivalent is [retention period](#retention-period), +In {{< product-name >}}, the equivalent is [retention period](#retention-period), however retention periods are not part of the data model. The retention period describes the data persistence behavior of a database. @@ -837,8 +838,8 @@ Related entries: ### series -A collection of data in the InfluxDB data structure that share a common -_measurement_, _tag set_, and _field key_. +In the InfluxDB 3 data structure, a collection of data that share a common +_measurement_ and _tag set_. Related entries: [field set](#field-set), @@ -847,12 +848,13 @@ Related entries: ### series cardinality -The number of unique measurement, tag set, and field key combinations in an InfluxDB database. +The number of unique measurement (table), tag set, and field key combinations in an InfluxDB database. -For example, assume that an InfluxDB bucket has one measurement. +For example, assume that an InfluxDB database has one measurement. The single measurement has two tag keys: `email` and `status`. -If there are three different `email`s, and each email address is associated with two -different `status`es, the series cardinality for the measurement is 6 +If there are three different `email` tag values, +and each email address is associated with two +different `status` tag values, then the series cardinality for the measurement is 6 (3 × 2 = 6): | email | status | @@ -867,7 +869,7 @@ different `status`es, the series cardinality for the measurement is 6 In some cases, performing this multiplication may overestimate series cardinality because of the presence of dependent tags. Dependent tags are scoped by another tag and do not increase series cardinality. -If we add the tag `firstname` to the example above, the series cardinality +If we add the tag `firstname` to the preceding example, the series cardinality would not be 18 (3 × 2 × 3 = 18). The series cardinality would remain unchanged at 6, as `firstname` is already scoped by the `email` tag: @@ -892,7 +894,7 @@ A series key identifies a particular series by measurement, tag set, and field k For example: -``` +```text # measurement, tag set, field key h2o_level, location=santa_monica, h2o_feet ``` @@ -1129,18 +1131,17 @@ A statement that sets or updates the value stored in a variable. ## W -### WAL (Write Ahead Log) - enterprise +### WAL (Write-Ahead Log) The temporary cache for recently written points. To reduce the frequency that permanent storage files are accessed, InfluxDB caches new points in the WAL until their total size or age triggers a flush to -more permanent storage. This allows for efficient batching of the writes into the TSM. +more permanent storage. This allows for efficient batching of the writes into +the storage engine. -Points in the WAL can be queried and persist through a system reboot. -On process start, all points in the WAL must be flushed before the system accepts new writes. - -Related entries: -[tsm](#tsm-time-structured-merge-tree) +Points in the WAL are queryable and persist through a system reboot. +On process start, all points in the WAL must be flushed before the system +accepts new writes. ### windowing diff --git a/content/influxdb/cloud-dedicated/reference/influxql/_index.md b/content/influxdb/cloud-dedicated/reference/influxql/_index.md index 2389c551a..12dc39b1d 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/_index.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/_index.md @@ -1,786 +1,13 @@ --- title: InfluxQL reference documentation -list_title: InfluxQL -description: InfluxQL is an SQL-like query language for interacting with data in InfluxDB. +description: > + InfluxQL is an SQL-like query language for interacting with data in InfluxDB. menu: influxdb_cloud_dedicated: parent: Reference name: InfluxQL reference identifier: influxql-reference weight: 102 + +source: /shared/influxql-v3-reference/_index.md --- - -InfluxQL (Influx Query Language) is an SQL-like query language used to interact -with InfluxDB and work with times series data. - -{{% warn %}} -#### InfluxQL feature support - -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features are still being implemented. -For information about the current implementation status of InfluxQL features, -see [InfluxQL feature support](/influxdb/cloud-dedicated/reference/influxql/feature-support/). -{{% /warn %}} - -- [Notation](#notation) -- [Query representation](#query-representation) - - [Characters](#characters) - - [Letters and digits](#letters-and-digits) - - [Identifiers](#identifiers) - - [Keywords](#keywords) - - [Literals](#literals) -- [Queries](#queries) -- [Statements](#statements) -- [Clauses](#clauses) -- [Expressions](#expressions) -- [Comments](#comments) -- [Other](#other) -- [Result set](#result-set) - - - -## Notation - -The syntax is specified using Extended Backus-Naur Form ("EBNF"). -EBNF is the same notation used in the [Go programming language specification](https://golang.org/ref/spec). - -```go -Production = production_name "=" [ Expression ] "." . -Expression = Alternative { "|" Alternative } . -Alternative = Term { Term } . -Term = production_name | token [ "…" token ] | Group | Option | Repetition . -Group = "(" Expression ")" . -Option = "[" Expression "]" . -Repetition = "{" Expression "}" . -``` - -Notation operators in order of increasing precedence: - -``` -| alternation -() grouping -[] option (0 or 1 times) -{} repetition (0 to n times) -``` - -## Query representation - -### Characters - -InfluxQL is Unicode text encoded in [UTF-8](http://en.wikipedia.org/wiki/UTF-8). - -``` -newline = /* the Unicode code point U+000A */ . -unicode_char = /* an arbitrary Unicode code point except newline */ . -``` - -### Letters and digits - -Letters are the set of ASCII letters and the underscore (`_`, U+005F). - -Only decimal digits are supported. - -``` -letter = ascii_letter | "_" . -ascii_letter = "A" … "Z" | "a" … "z" . -digit = "0" … "9" . -``` - -### Identifiers - -Identifiers are tokens that refer to -[database](/influxdb/cloud-dedicated/reference/glossary/#database) names, -[retention policy](/influxdb/cloud-dedicated/reference/glossary/#retention-policy-rp) names, -[measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) names, -[tag keys](/influxdb/cloud-dedicated/reference/glossary/#tag-key), and -[field keys](/influxdb/cloud-dedicated/reference/glossary/#field-key). - -The rules are as follows: - -- Double-quoted identifiers can contain any Unicode character except for a new line. -- Double-quoted identifiers can also contain escaped `"` characters (that is, `\"`) -- Double-quoted identifiers can include InfluxQL [keywords](#keywords). -- Unquoted identifiers must start with an upper or lowercase ASCII character or "_". -- Unquoted identifiers may contain only ASCII letters, decimal digits, and "_". - -``` -identifier = unquoted_identifier | quoted_identifier . -unquoted_identifier = ( letter ) { letter | digit } . -quoted_identifier = `"` unicode_char { unicode_char } `"` . -``` - -#### Examples - -``` -cpu -_cpu_stats -"1h" -"anything really" -"1_Crazy-1337.identifier>NAME👍" -``` - -### Keywords - -``` -ALL ALTER ANY AS ASC BEGIN -BY CREATE CONTINUOUS DATABASE DATABASES DEFAULT -DELETE DESC DESTINATIONS DIAGNOSTICS DISTINCT DROP -DURATION END EVERY EXPLAIN FIELD FOR -FROM GRANT GRANTS GROUP GROUPS IN -INF INSERT INTO KEY KEYS KILL -LIMIT SHOW MEASUREMENT MEASUREMENTS NAME OFFSET -ON ORDER PASSWORD POLICY POLICIES PRIVILEGES -QUERIES QUERY READ REPLICATION RESAMPLE RETENTION -REVOKE SELECT SERIES SET SHARD SHARDS -SLIMIT SOFFSET STATS SUBSCRIPTION SUBSCRIPTIONS TAG -TO USER USERS VALUES WHERE WITH -WRITE -``` - -If you use an InfluxQL keyword as an -[identifier](/influxdb/cloud-dedicated/reference/glossary/#identifier), -double-quote the identifier in every query. - -The `time` keyword is a special case. -`time` can be a -database name, -[measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) name, -[retention policy](/influxdb/cloud-dedicated/reference/glossary/#retention-policy-rp) name, and -[user](/influxdb/cloud-dedicated/reference/glossary/#user) name. - -In those cases, you don't need to double-quote `time` in queries. - -`time` can't be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key) or -[tag key](/influxdb/cloud-dedicated/reference/glossary/#tag-key); -InfluxDB rejects writes with `time` as a field key or tag key and returns an error. - - -### Literals - -#### Integers - -InfluxQL supports decimal integer literals. -Hexadecimal and octal literals aren't currently supported. - -``` -int_lit = ( "1" … "9" ) { digit } . -``` - -#### Floats - -InfluxQL supports floating-point literals. -Exponents aren't currently supported. - -``` -float_lit = int_lit "." int_lit . -``` - -#### Strings - -String literals must be surrounded by single quotes. -Strings may contain `'` characters as long as they are escaped (that is, , `\'`) - -``` -string_lit = `'` { unicode_char } `'` . -``` - -#### Durations - -Duration literals specify a length of time. -An integer literal followed immediately (with no spaces) by one of the duration units listed below is interpreted as a duration literal. -Durations can be specified with mixed units. - -##### Duration units - -| Units | Meaning | -| ------ | --------------------------------------- | -| ns | nanoseconds (1 billionth of a second) | -| u or µ | microseconds (1 millionth of a second) | -| ms | milliseconds (1 thousandth of a second) | -| s | second | -| m | minute | -| h | hour | -| d | day | -| w | week | - -``` -duration_lit = int_lit duration_unit . -duration_unit = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" . -``` - -#### Dates & Times - -Unlike other notations used in InfluxQL, the date and time literal format isn't specified by EBNF. -InfluxQL date and time is specified using Go's time parsing format and -[reference date](https://pkg.go.dev/time#pkg-constants) written in the format required by InfluxQL. -The reference date time is: - -InfluxQL reference date time: January 2nd, 2006 at 3:04:05 PM - -``` -time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02" . -``` - -#### Booleans - -``` -bool_lit = TRUE | FALSE . -``` - -#### Regular Expressions - -``` -regex_lit = "/" { unicode_char } "/" . -``` - -**Comparators:** -`=~` matches against -`!~` doesn't match against - -{{% note %}} -InfluxQL supports using regular expressions when specifying: - -- [field keys](/influxdb/cloud-dedicated/reference/glossary/#field-key) and [tag keys](/influxdb/cloud-dedicated/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/cloud-dedicated/reference/influxql/select/) -- [measurements](/influxdb/cloud-dedicated/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/cloud-dedicated/reference/influxql/select/#from-clause) -- [tag values](/influxdb/cloud-dedicated/reference/glossary/#tag-value) and - string [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value) - in the [`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/) -- [tag keys](/influxdb/cloud-dedicated/reference/glossary/#tag-key) in the - [`GROUP BY` clause](/influxdb/cloud-dedicated/reference/influxql/group-by/) - -Currently, InfluxQL doesn't support using regular expressions to match non-string -field values in the `WHERE` clause, [databases](/influxdb/cloud-dedicated/reference/glossary/#database), -and [retention polices](/influxdb/cloud-dedicated/reference/glossary/#retention-policy-rp). -{{% /note %}} - -## Queries - -A query is composed of one or more statements separated by a semicolon (`;`). - -``` -query = statement { ";" statement } . - -statement = explain_stmt | - explain_analyze_stmt | - select_stmt | - show_field_keys_stmt | - show_measurements_stmt | - show_retention_policies_stmt | - show_tag_keys_stmt | - show_tag_values_with_key = stmt . -``` - - - -## Statements - -### EXPLAIN - -Parses and plans the query, and then prints a summary of estimated costs. - -Many SQL engines use the `EXPLAIN` statement to show join order, join algorithms, and predicate and expression pushdown. -Since InfluxQL doesn't support joins, the cost of an InfluxQL query is typically a function of the total series accessed, the number of iterator accesses to a TSM file, and the number of TSM blocks that need to be scanned. - -A query plan generated by `EXPLAIN` contains the following elements: - -- expression -- auxiliary fields -- number of shards -- number of series -- cached values -- number of files -- number of blocks -- size of blocks - -``` -explain_stmt = "EXPLAIN" select_stmt . -``` - -#### Example - -```sql -> explain select sum(pointReq) from "_internal"."monitor"."write" group by hostname; -> QUERY PLAN ------- -EXPRESSION: sum(pointReq::integer) -NUMBER OF SHARDS: 2 -NUMBER OF SERIES: 2 -CACHED VALUES: 110 -NUMBER OF FILES: 1 -NUMBER OF BLOCKS: 1 -SIZE OF BLOCKS: 931 -``` - -### EXPLAIN ANALYZE - -Executes the specified `SELECT` statement and returns data about the query performance and storage during runtime, visualized as a tree. Use this statement to analyze query performance and storage, including [execution time](#execution-time) and [planning time](#planning-time), and the [iterator type](#iterator-type) and [cursor type](#cursor-type). - -For example, if you execute the following statement: - -```sql -> explain analyze select mean(usage_steal) from cpu where time >= '2018-02-22T00:00:00Z' and time < '2018-02-22T12:00:00Z' -``` - -The output is similar to the following: - -```sql -EXPLAIN ANALYZE ---------------- -. -└── select - ├── execution_time: 2.25823ms - ├── planning_time: 18.381616ms - ├── total_time: 20.639846ms - └── field_iterators - ├── labels - │ └── statement: SELECT mean(usage_steal::float) FROM telegraf."default".cpu - └── expression - ├── labels - │ └── expr: mean(usage_steal::float) - └── create_iterator - ├── labels - │ ├── measurement: cpu - │ └── shard_id: 608 - ├── cursors_ref: 779 - ├── cursors_aux: 0 - ├── cursors_cond: 0 - ├── float_blocks_decoded: 431 - ├── float_blocks_size_bytes: 1003552 - ├── integer_blocks_decoded: 0 - ├── integer_blocks_size_bytes: 0 - ├── unsigned_blocks_decoded: 0 - ├── unsigned_blocks_size_bytes: 0 - ├── string_blocks_decoded: 0 - ├── string_blocks_size_bytes: 0 - ├── boolean_blocks_decoded: 0 - ├── boolean_blocks_size_bytes: 0 - └── planning_time: 14.805277ms``` -``` - -{{% note %}} -`EXPLAIN ANALYZE` ignores query output, so the cost of serialization to JSON or -CSV isn't accounted for. -{{% /note %}} - -##### execution_time - -Shows the amount of time the query took to execute, including reading the time series data, performing operations as data flows through iterators, and draining processed data from iterators. Execution time doesn't include the time taken to serialize the output into JSON or other formats. - -##### planning_time - -Shows the amount of time the query took to plan. -Planning a query in InfluxDB requires a number of steps. Depending on the complexity of the query, planning can require more work and consume more CPU and memory resources than executing the query. For example, the number of series keys required to execute a query affects how quickly the query is planned and how much memory the planning requires. - -First, InfluxDB determines the effective time range of the query and selects the shards to access. -Next, for each shard and each measurement, InfluxDB performs the following steps: - -1. Select matching series keys from the index, filtered by tag predicates in the `WHERE` clause. -2. Group filtered series keys into tag sets based on the `GROUP BY` dimensions. -3. Enumerate each tag set and create a cursor and iterator for each series key. -4. Merge iterators and return the merged result to the query executor. - -##### iterator type - -`EXPLAIN ANALYZE` supports the following iterator types: - -- `create_iterator` node represents work done by the local influxd instance──a complex composition of nested iterators combined and merged to produce the final query output. -- (InfluxDB Enterprise only) `remote_iterator` node represents work done on remote machines. - -For more information about iterators, see [Understanding iterators](#understanding-iterators). - -##### cursor type - -`EXPLAIN ANALYZE` distinguishes 3 cursor types. While the cursor types have the same data structures and equal CPU and I/O costs, each cursor type is constructed for a different reason and separated in the final output. Consider the following cursor types when tuning a statement: - -- cursor_ref: Reference cursor created for `SELECT` projections that include a function, such as `last()` or `mean()`. -- cursor_aux: Auxiliary cursor created for simple expression projections (not selectors or an aggregation). For example, `SELECT foo FROM m` or `SELECT foo+bar FROM m`, where `foo` and `bar` are fields. -- cursor_cond: Condition cursor created for fields referenced in a `WHERE` clause. - -For more information about cursors, see [Understanding cursors](#understanding-cursors). - -##### block types - -`EXPLAIN ANALYZE` separates storage block types, and reports the total number of -blocks decoded and their size (in bytes) on disk. The following block types are supported: - -| Type | Description | -| :--------- | :------------------------------------ | -| `float` | 64-bit IEEE-754 floating-point number | -| `integer` | 64-bit signed integer | -| `unsigned` | 64-bit unsigned integer | -| `boolean` | 1-bit, LSB encoded | -| `string` | UTF-8 string | - -### SELECT - -``` -select_stmt = "SELECT" fields from_clause [ where_clause ] - [ group_by_clause ] [ order_by_clause ] [ limit_clause ] - [ offset_clause ] [ slimit_clause ] [ soffset_clause ] [ timezone_clause ] . -``` - -#### Example - -Select from measurements grouped by the day with a timezone - -```sql -SELECT mean("value") FROM "cpu" GROUP BY region, time(1d) fill(0) tz('America/Chicago') -``` - - - - - - - -### SHOW FIELD KEYS - -``` -show_field_keys_stmt = "SHOW FIELD KEYS" [on_clause] [ from_clause ] . -``` - -#### Examples - -```sql --- show field keys and field value data types from all measurements -SHOW FIELD KEYS - --- show field keys and field value data types from specified measurement -SHOW FIELD KEYS FROM "cpu" -``` - -### SHOW MEASUREMENTS - -``` -show_measurements_stmt = "SHOW MEASUREMENTS" [on_clause] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all measurements -SHOW MEASUREMENTS - --- show measurements where region tag = 'uswest' AND host tag = 'serverA' -SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' - --- show measurements that start with 'h2o' -SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ -``` - - - - - - - -### SHOW TAG KEYS - -``` -show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ] - [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all tag keys -SHOW TAG KEYS - --- show all tag keys from the cpu measurement -SHOW TAG KEYS FROM "cpu" - --- show all tag keys from the cpu measurement where the region key = 'uswest' -SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' - --- show all tag keys where the host key = 'serverA' -SHOW TAG KEYS WHERE "host" = 'serverA' -``` - -### SHOW TAG VALUES - -``` -show_tag_values_stmt = "SHOW TAG VALUES" [on_clause] [ from_clause ] with_tag_clause [ where_clause ] - [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all tag values across all measurements for the region tag -SHOW TAG VALUES WITH KEY = "region" - --- show tag values from the cpu measurement for the region tag -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" - --- show tag values across all measurements for all tag keys that do not include the letter c -SHOW TAG VALUES WITH KEY !~ /.*c.*/ - --- show tag values from the cpu measurement for region & host tag keys where service = 'redis' -SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' -``` - - - -## Clauses - -``` -from_clause = "FROM" measurements . - -group_by_clause = "GROUP BY" dimensions fill(fill_option). - -limit_clause = "LIMIT" int_lit . - -offset_clause = "OFFSET" int_lit . - -slimit_clause = "SLIMIT" int_lit . - -soffset_clause = "SOFFSET" int_lit . - -timezone_clause = tz(string_lit) . - -on_clause = "ON" db_name . - -order_by_clause = "ORDER BY" sort_fields . - -where_clause = "WHERE" expr . - -with_measurement_clause = "WITH MEASUREMENT" ( "=" measurement | "=~" regex_lit ) . - -with_tag_clause = "WITH KEY" ( "=" tag_key | "!=" tag_key | "=~" regex_lit | "IN (" tag_keys ")" ) . -``` - -## Expressions - -``` -binary_op = "+" | "-" | "*" | "/" | "%" | "&" | "|" | "^" | "AND" | - "OR" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" . - -expr = unary_expr { binary_op unary_expr } . - -unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit | - float_lit | bool_lit | duration_lit | regex_lit . -``` - -## Default time range - -The default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to _now_. - -## Comments - -Use comments with InfluxQL statements to describe your queries. - -- A single line comment begins with two hyphens (`--`) and ends where InfluxDB detects a line break. - This comment type cannot span several lines. -- A multi-line comment begins with `/*` and ends with `*/`. This comment type can span several lines. - Multi-line comments do not support nested multi-line comments. - -## Other - -``` -alias = "AS" identifier . - -back_ref = ( policy_name ".:MEASUREMENT" ) | - ( db_name "." [ policy_name ] ".:MEASUREMENT" ) . - -db_name = identifier . - -dimension = expr . - -dimensions = dimension { "," dimension } . - -field_key = identifier . - -field = expr [ alias ] . - -fields = field { "," field } . - -fill_option = "null" | "none" | "previous" | int_lit | float_lit | "linear" . - -host = string_lit . - -measurement = measurement_name | - ( policy_name "." measurement_name ) | - ( db_name "." [ policy_name ] "." measurement_name ) . - -measurements = measurement { "," measurement } . - -measurement_name = identifier | regex_lit . - -policy_name = identifier . - -retention_policy = identifier . - -retention_policy_name = "NAME" identifier . - -series_id = int_lit . - -sort_field = field_key [ ASC | DESC ] . - -sort_fields = sort_field { "," sort_field } . - -tag_key = identifier . - -tag_keys = tag_key { "," tag_key } . - -var_ref = measurement . -``` diff --git a/content/influxdb/cloud-dedicated/reference/influxql/feature-support.md b/content/influxdb/cloud-dedicated/reference/influxql/feature-support.md index 72a67d3fe..04b0b2473 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/feature-support.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/feature-support.md @@ -9,173 +9,6 @@ menu: influxdb_cloud_dedicated: parent: influxql-reference weight: 220 + +source: /shared/influxql-v3-reference/feature-support.md --- - -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features are still being implemented. -This page provides information about the current implementation status of -InfluxQL features. - -- [In-progress features](#in-progress-features) - - [Time zones](#time-zones) - - [SLIMIT clause](#slimit-clause) - - [SOFFSET clause](#soffset-clause) - - [Metaqueries](#metaqueries) -- [Function support](#function-support) - - [Aggregate functions](#aggregate-functions) - - [Selector functions](#selector-functions) - - [Transformations](#transformations) - - [Technical and predictive analysis](#technical-and-predictive-analysis) - -## In-progress features - -### Time zones - -InfluxQL in {{< product-name >}} does not currently support the time zone clause, -which applies a time zone offset to UTC timestamps in query results. - - - -### SLIMIT clause - -InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause, -which limits the number of [series](/influxdb/cloud-dedicated/reference/glossary/#series) -returned in query results. - - - -### SOFFSET clause - -InfluxQL in {{< product-name >}} does not currently support the `SOFFSET` clause, -which specifies the number of [series](/influxdb/cloud-dedicated/reference/glossary/#series) -to skip before returning results. - - - -### Metaqueries - -InfluxQL metaqueries return information about the schema of time series data -stored in InfluxDB. -The following table provides information about what metaqueries are available in -{{< product-name >}}: - -| Metaquery | Supported | -| :------------------------------------------------------------ | :----------------------: | -| SHOW DATABASES | | -| **SHOW RETENTION POLICIES** | **{{< icon "check" >}}** | -| **SHOW MEASUREMENTS** | **{{< icon "check" >}}** | -| SHOW SERIES | | -| SHOW SERIES CARDINALITY | | -| **SHOW TAG KEYS** | **{{< icon "check" >}}** | -| SHOW TAG KEY CARDINALITY | | -| **SHOW TAG VALUES** | **{{< icon "check" >}}** | -| SHOW TAG VALUES CARDINALITY | | -| **SHOW FIELD KEYS** | **{{< icon "check" >}}** | -| SHOW FIELD KEYS CARDINALITY | | - -{{% note %}} -#### Cardinality metaqueries - -With the InfluxDB 3.0 storage engine, series cardinality is no longer a limiting -factor for database performance. -Cardinality-related metaqueries will likely not be supported with the InfluxDB 3.0 -storage engine. -{{% /note %}} - -## Function support - -### Aggregate functions - -| Function | Supported | -| :---------------------------------------------------------------------------------------- | :----------------------: | -| [COUNT()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#count) | **{{< icon "check" >}}** | -| [DISTINCT()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#distinct) | **{{< icon "check" >}}** | -| INTEGRAL() | | -| [MEAN()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#mean) | **{{< icon "check" >}}** | -| [MEDIAN()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#median) | **{{< icon "check" >}}** | -| [MODE()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#mode) | **{{< icon "check" >}}** | -| [SPREAD()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#spread) | **{{< icon "check" >}}** | -| [STDDEV()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#stddev) | **{{< icon "check" >}}** | -| [SUM()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#sum) | **{{< icon "check" >}}** | - - - -### Selector functions - -| Function | Supported | -| :------------------------------------------------------------------------------------------- | :----------------------: | -| [BOTTOM()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#bottom) | **{{< icon "check" >}}** | -| [FIRST()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#first) | **{{< icon "check" >}}** | -| [LAST()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#last) | **{{< icon "check" >}}** | -| [MAX()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#max) | **{{< icon "check" >}}** | -| [MIN()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#min) | **{{< icon "check" >}}** | -| [PERCENTILE()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#percentile) | **{{< icon "check" >}}** | -| SAMPLE() | | -| [TOP()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#top) | **{{< icon "check" >}}** | - - - -### Transformations - -| Function | Supported | -| :--------------------------------------------------------------------------------------------------------------------------- | :----------------------: | -| [ABS()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#abs) | **{{< icon "check" >}}** | -| [ACOS()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#acos) | **{{< icon "check" >}}** | -| [ASIN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#asin) | **{{< icon "check" >}}** | -| [ATAN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#atan) | **{{< icon "check" >}}** | -| [ATAN2()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#atan2) | **{{< icon "check" >}}** | -| [CEIL()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#ceil) | **{{< icon "check" >}}** | -| [COS()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#cos) | **{{< icon "check" >}}** | -| [CUMULATIVE_SUM()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#cumulative_sum) | **{{< icon "check" >}}** | -| [DERIVATIVE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#derivative) | **{{< icon "check" >}}** | -| [DIFFERENCE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#difference) | **{{< icon "check" >}}** | -| [ELAPSED()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#elapsed) | **{{< icon "check" >}}** | -| [EXP()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#exp) | **{{< icon "check" >}}** | -| [FLOOR()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#floor) | **{{< icon "check" >}}** | -| [LN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#ln) | **{{< icon "check" >}}** | -| [LOG()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#log) | **{{< icon "check" >}}** | -| [LOG2()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#log2) | **{{< icon "check" >}}** | -| [LOG10()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#log10) | **{{< icon "check" >}}** | -| [MOVING_AVERAGE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#moving_average) | **{{< icon "check" >}}** | -| [NON_NEGATIVE_DERIVATIVE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#non_negative_derivative) | **{{< icon "check" >}}** | -| [NON_NEGATIVE_DIFFERENCE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#non_negative_difference) | **{{< icon "check" >}}** | -| [POW()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#pow) | **{{< icon "check" >}}** | -| [ROUND()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#round) | **{{< icon "check" >}}** | -| [SIN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#sin) | **{{< icon "check" >}}** | -| [SQRT()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#sqrt) | **{{< icon "check" >}}** | -| [TAN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#tan) | **{{< icon "check" >}}** | - -### Technical and predictive analysis - -| Function | Supported | -| :-------------------------------------------------------------------- | :-------: | -| CHANDE_MOMENTUM_OSCILLATOR() | | -| DOUBLE_EXPONENTIAL_MOVING_AVERAGE() | | -| EXPONENTIAL_MOVING_AVERAGE() | | -| HOLT_WINTERS() | | -| HOLT_WINTERS_WITH_FIT() | | -| KAUFMANS_EFFICIENCY_RATIO() | | -| KAUFMANS_ADAPTIVE_MOVING_AVERAGE() | | -| RELATIVE_STRENGTH_INDEX() | | -| TRIPLE_EXPONENTIAL_MOVING_AVERAGE() | | -| TRIPLE_EXPONENTIAL_DERIVATIVE() | | - - - -### Date and time functions - -| Function | Supported | -| :------------------------------------------------------------------------------- | :----------------------: | -| [now()](/influxdb/cloud-dedicated/reference/influxql/functions/date-time/#now) | **{{< icon "check" >}}** | -| [time()](/influxdb/cloud-dedicated/reference/influxql/functions/date-time/#time) | **{{< icon "check" >}}** | -| tz() | | - - - -### Miscellaneous functions - -| Function | Supported | -| :-------------------------------------------------------------------------- | :----------------------: | -| [fill()](/influxdb/cloud-dedicated/reference/influxql/functions/misc/#fill) | **{{< icon "check" >}}** | diff --git a/content/influxdb/cloud-dedicated/reference/influxql/functions/_index.md b/content/influxdb/cloud-dedicated/reference/influxql/functions/_index.md index 38d178a01..dd9e8acab 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/functions/_index.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/functions/_index.md @@ -8,79 +8,6 @@ menu: parent: influxql-reference identifier: influxql-functions weight: 208 + +source: /shared/influxql-v3-reference/functions/_index.md --- - -Use InfluxQL functions to aggregate, select, transform, analyze, and predict data. - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/cloud-dedicated/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## InfluxQL functions (by type) - -- [Aggregates](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/) - - [COUNT()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#count) - - [DISTINCT()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#distinct) - - [MEAN()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#mean) - - [MEDIAN()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#median) - - [STDDEV()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#stddev) - - [SUM()](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#sum) - - - -- [Selectors](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/) - - [BOTTOM()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#bottom) - - [FIRST()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#first) - - [LAST()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#last) - - [MAX()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#max) - - [MIN()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#min) - - [PERCENTILE()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#percentile) - - [TOP()](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#top) - -- [Transformations](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/) - - [ABS()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#abs) - - [ACOS()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#acos) - - [ASIN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#asin) - - [ATAN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#atan) - - [ATAN2()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#atan2) - - [CEIL()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#ceil) - - [COS()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#cos) - - [CUMULATIVE_SUM()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#cumulative_sum) - - [DERIVATIVE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#derivative) - - [DIFFERENCE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#difference) - - [EXP()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#exp) - - [FLOOR()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#floor) - - [HISTOGRAM()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#histogram) - - [LN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#ln) - - [LOG()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#log) - - [LOG2()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#log2) - - [LOG10()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#log10) - - [MOVING_AVERAGE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#moving_average) - - [NON_NEGATIVE_DERIVATIVE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#non_negative_derivative) - - [NON_NEGATIVE_DIFFERENCE()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#non_negative_difference) - - [POW()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#pow) - - [ROUND()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#round) - - [SIN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#sin) - - [SQRT()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#sqrt) - - [TAN()](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#tan) - -- [Date and time](/influxdb/cloud-dedicated/reference/influxql/functions/date-time/) - - [now()](/influxdb/cloud-dedicated/reference/influxql/functions/date-time/#now) - - [time()](/influxdb/cloud-dedicated/reference/influxql/functions/date-time/#time) -- [Miscellaneous](/influxdb/cloud-dedicated/reference/influxql/functions/misc/) - - [fill()](/influxdb/cloud-dedicated/reference/influxql/functions/misc/#fill) - - - - - - - - - - diff --git a/content/influxdb/cloud-dedicated/reference/influxql/functions/aggregates.md b/content/influxdb/cloud-dedicated/reference/influxql/functions/aggregates.md index d45f14958..76310289e 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/functions/aggregates.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/functions/aggregates.md @@ -10,922 +10,6 @@ menu: weight: 205 related: - /influxdb/cloud-dedicated/query-data/influxql/aggregate-select/ + +source: /shared/influxql-v3-reference/functions/aggregates.md --- - -Use aggregate functions to assess, aggregate, and return values in your data. -Aggregate functions return one row containing the aggregate values from each InfluxQL group. - -_Examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -- [COUNT()](#count) -- [DISTINCT()](#distinct) -- [MEAN()](#mean) -- [MEDIAN()](#median) -- [MODE()](#mode) -- [SPREAD()](#spread) -- [STDDEV()](#stddev) -- [SUM()](#sum) - - - - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/cloud-dedicated/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## COUNT() - -Returns the number of non-null [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -COUNT(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Count the number of non-null values in a field" %}} - -```sql -SELECT COUNT(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 1970-01-01T00:00:00Z | 26 | - -{{% /expand %}} - -{{% expand "Count the number of non-null values in each field" %}} - -```sql -SELECT COUNT(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count_co | count_hum | count_temp | -| :------------------- | -------: | --------: | ---------: | -| 1970-01-01T00:00:00Z | 26 | 26 | 26 | - -{{% /expand %}} - -{{% expand "Count the number of non-null values in fields where the field key matches a regular expression" %}} - -```sql -SELECT COUNT(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count_hum | count_temp | -| :------------------- | --------: | ---------: | -| 1970-01-01T00:00:00Z | 26 | 26 | - -{{% /expand %}} - -{{% expand "Count distinct values for a field" %}} - -InfluxQL supports nesting [`DISTINCT()`](#distinct) in `COUNT()`. - -```sql -SELECT COUNT(DISTINCT(co)) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 1970-01-01T00:00:00Z | 12 | - -{{% /expand %}} - -{{% expand "Count the number of non-null field values within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - COUNT(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 2022-01-01T06:00:00Z | 4 | -| 2022-01-01T12:00:00Z | 6 | -| 2022-01-01T18:00:00Z | 3 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DISTINCT() - -Returns the list of unique [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -DISTINCT(field_key) -``` - -#### Arguments - -- **field_key**: Field key to return distinct values from. - Supports all field types. - -#### Notable behaviors - -- InfluxQL supports nesting `DISTINCT()` with [`COUNT()`](#count-distinct-values-for-a-field). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "List the distinct field values" %}} - -```sql -SELECT DISTINCT(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | distinct | -| :------------------- | -------: | -| 1970-01-01T00:00:00Z | 0 | -| 1970-01-01T00:00:00Z | 1 | -| 1970-01-01T00:00:00Z | 3 | -| 1970-01-01T00:00:00Z | 4 | -| 1970-01-01T00:00:00Z | 7 | -| 1970-01-01T00:00:00Z | 5 | -| 1970-01-01T00:00:00Z | 9 | -| 1970-01-01T00:00:00Z | 18 | -| 1970-01-01T00:00:00Z | 14 | -| 1970-01-01T00:00:00Z | 22 | -| 1970-01-01T00:00:00Z | 17 | -| 1970-01-01T00:00:00Z | 26 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - - -## MEAN() - -Returns the arithmetic mean (average) of [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -MEAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the mean value of a field" %}} - -```sql -SELECT MEAN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of each field" %}} - -```sql -SELECT MEAN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ----------------: | -------: | -----------------: | -| 1970-01-01T00:00:00Z | 5.269230769230769 | 36.15 | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of fields where the field key matches a regular expression" %}} - -```sql -SELECT MEAN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean_hum | mean_temp | -| :------------------- | -------: | -----------------: | -| 1970-01-01T00:00:00Z | 36.15 | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MEAN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 22.275 | -| 2022-01-01T12:00:00Z | 22.649999999999995 | -| 2022-01-01T18:00:00Z | 23.033333333333335 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MEDIAN() - -Returns the middle value from a sorted list of [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -MEDIAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MEDIAN()` is nearly equivalent to - [`PERCENTILE(field_key, 50)`](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/#percentile), - except `MEDIAN()` returns the average of the two middle field values if the - field contains an even number of values. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the median value of a field" %}} - -```sql -SELECT MEDIAN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median | -| :------------------- | -----: | -| 1970-01-01T00:00:00Z | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of each field" %}} - -```sql -SELECT MEDIAN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median_co | median_hum | median_temp | -| :------------------- | --------: | ---------: | ----------: | -| 1970-01-01T00:00:00Z | 1 | 36.05 | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of fields where the field key matches a regular expression" %}} - - -```sql -SELECT MEDIAN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median_hum | median_temp | -| :------------------- | ---------: | ----------: | -| 1970-01-01T00:00:00Z | 36.05 | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MEDIAN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 22.549999999999997 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MODE() - -Returns the most frequent value in a list of -[field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -MODE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. - -#### Notable behaviors - -- `MODE()` returns the field value with the earliest - [timestamp](/influxdb/cloud-dedicated/reference/glossary/#timestamp) - if there's a tie between two or more values for the maximum number of occurrences. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Calculate the mode value of a field" %}} - -```sql -SELECT MODE(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode | -| :------------------- | ---: | -| 1970-01-01T00:00:00Z | 0 | - -{{% /expand %}} - -{{% expand "Calculate the mode value of each field" %}} - -```sql -SELECT MODE(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode_co | mode_hum | mode_temp | -| :------------------- | ------: | -------: | --------: | -| 1970-01-01T00:00:00Z | 0 | 36 | 22.7 | - -{{% /expand %}} - -{{% expand "Calculate the mode of field keys that match a regular expression" %}} - -```sql -SELECT MODE(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode_hum | mode_temp | -| :------------------- | -------: | --------: | -| 1970-01-01T00:00:00Z | 36 | 22.7 | - -{{% /expand %}} - -{{% expand "Calculate the mode a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MODE(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 1 | -| 2022-01-01T18:00:00Z | 18 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SPREAD() - -Returns the difference between the minimum and maximum -[field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -SPREAD(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Calculate the spread of a field" %}} - -```sql -SELECT SPREAD(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of each field" %}} - -```sql -SELECT SPREAD(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread_co | spread_hum | spread_temp | -| :------------------- | --------: | ---------: | -----------------: | -| 1970-01-01T00:00:00Z | 26 | 1 | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of field keys that match a regular expression" %}} - -```sql -SELECT SPREAD(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread_hum | spread_temp | -| :------------------- | ---------: | -----------------: | -| 1970-01-01T00:00:00Z | 1 | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SPREAD(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread | -| :------------------- | -----: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 9 | -| 2022-01-01T18:00:00Z | 8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## STDDEV() - -Returns the standard deviation of [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -STDDEV(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the standard deviation of a field" %}} - -```sql -SELECT STDDEV(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of each field" %}} - -```sql -SELECT STDDEV(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev_co | stddev_hum | stddev_temp | -| :------------------- | ----------------: | ------------------: | -----------------: | -| 1970-01-01T00:00:00Z | 7.774613519951676 | 0.25495097567963926 | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of fields where the field key matches a regular expression" %}} - -```sql -SELECT STDDEV(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev_hum | stddev_temp | -| :------------------- | ------------------: | -----------------: | -| 1970-01-01T00:00:00Z | 0.25495097567963926 | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - STDDEV(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 3.6742346141747673 | -| 2022-01-01T18:00:00Z | 4 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SUM() - -Returns the sum of [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -SUM(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the sum of values in a field" %}} - -```sql -SELECT SUM(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | --: | -| 1970-01-01T00:00:00Z | 137 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values in each field" %}} - -```sql -SELECT SUM(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum_co | sum_hum | sum_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 137 | 939.9 | 582.3 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values for fields where the field key matches a regular expression" %}} - -```sql -SELECT SUM(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum_hum | sum_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 939.9 | 582.3 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values in a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SUM(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | --: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 21 | -| 2022-01-01T18:00:00Z | 66 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/reference/influxql/functions/date-time.md b/content/influxdb/cloud-dedicated/reference/influxql/functions/date-time.md index 9cd19b4a4..cf834a564 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/functions/date-time.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/functions/date-time.md @@ -8,138 +8,6 @@ menu: name: Date and time parent: influxql-functions weight: 206 + +source: /shared/influxql-v3-reference/functions/date-time.md --- - -Use InfluxQL date and time functions to perform time-related operations. - -- [now()](#now) -- [time()](#time) - - -## now() - -Returns the current system time (UTC). -_Supported only in the [`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/)._ - -```sql -now() -``` - -## time() - -Used in the [`GROUP BY` clause](/influxdb/cloud-dedicated/reference/influxql/group-by/) -to group data into time-based intervals, also known as "windows", using the specified interval. -Timestamps in the `time` column are updated to the start boundary of the window -they're in and grouped by `time`. -Windows use preset round-number boundaries based on the specified interval that -are independent of time conditions in the -[`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/). - -This operation can be used to do the following: - -- Downsample data by aggregating multiple points in each window into a single - point per window. -- Normalize irregular time series data to occur at regular intervals. - -_Supported only in the [`GROUP BY` clause](/influxdb/cloud-dedicated/reference/influxql/group-by/)._ - -```sql -time(interval[, offset]) -``` - -#### Arguments - -- **interval**: Duration literal that specifies the window interval. -- **offset**: Duration literal that shifts preset time boundaries forward or backward. - Can be positive or negative. _Default is `0s`._ - -##### Examples {#time-examples} - -{{< expand-wrapper >}} - -{{% expand "Downsample data into time-based intervals" %}} - -The following example uses the -[Bitcoin price sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#bitcoin-price-data). - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'GBP' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(2d) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-05-01T00:00:00Z | 23680.120447159094 | -| 2023-05-03T00:00:00Z | 24048.71484033149 | -| 2023-05-05T00:00:00Z | 24461.9194901099 | -| 2023-05-07T00:00:00Z | 23796.43801933702 | -| 2023-05-09T00:00:00Z | 23118.709889285707 | -| 2023-05-11T00:00:00Z | 22465.008364444446 | -| 2023-05-13T00:00:00Z | 22499.464763186803 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - diff --git a/content/influxdb/cloud-dedicated/reference/influxql/functions/misc.md b/content/influxdb/cloud-dedicated/reference/influxql/functions/misc.md index 247cd349b..f2c033e76 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/functions/misc.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/functions/misc.md @@ -10,237 +10,6 @@ menu: identifier: influxql-misc-functions parent: influxql-functions weight: 206 + +source: /shared/influxql-v3-reference/functions/misc.md --- - -Use InfluxQL miscellaneous functions to perform different operations in -InfluxQL queries. - -- [fill()](#fill) - -## fill() - -Fills _null_ field values returned from empty time windows in `GROUP BY time()` -queries with a specified fill value. - -_Supported only in the [`GROUP BY` clause](/influxdb/cloud-dedicated/reference/influxql/group-by/)._ - -```sql -fill(behavior) -``` - -#### Arguments - -- **behavior**: Defines the behavior of the fill operation. - If no `FILL` clause is included, the default behavior is `fill(null)`. - - The following options are available: - - - **numeric literal**: Replaces null values with the specified numeric literal. - - **linear**: Uses linear interpolation between existing values to replace null values. - - **none**: Removes rows with null field values. - - **null**: Keeps null values and associated timestamps. - - **previous**: Replaces null values with the most recent non-null value. - -#### Examples {#fill-examples} - -The following example uses the -[Bitcoin price sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#bitcoin-price-data). - -{{< tabs-wrapper >}} -{{% tabs "small" %}} -[fill(numeric_literal)](#) -[fill(linear)](#) -[fill(none)](#) -[fill(null)](#) -[fill(previous)](#) -{{% /tabs %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(0) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 0 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(linear) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29285.3651 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(none) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(null) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(previous) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - - - diff --git a/content/influxdb/cloud-dedicated/reference/influxql/functions/selectors.md b/content/influxdb/cloud-dedicated/reference/influxql/functions/selectors.md index 650fda35c..97966fc06 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/functions/selectors.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/functions/selectors.md @@ -10,1059 +10,6 @@ menu: weight: 205 related: - /influxdb/cloud-dedicated/query-data/influxql/aggregate-select/ + +source: /shared/influxql-v3-reference/functions/selectors.md --- - -Use selector functions to assess, select, and return values in your data. -Selector functions return one or more rows with the selected values from each -InfluxQL group. - -_Examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -- [BOTTOM()](#bottom) -- [FIRST()](#first) -- [LAST()](#last) -- [MAX()](#max) -- [MIN()](#min) -- [PERCENTILE()](#percentile) -- [TOP()](#top) -- [Notable behaviors of selector functions](#notable-behaviors-of-selector-functions) - - - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/cloud-dedicated/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## BOTTOM() - -Returns the smallest `N` [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). -`BOTTOM()` supports int64 and float64 field value [data types](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -BOTTOM(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) -``` - -{{% note %}} -**Note:** `BOTTOM()` returns the field value with the earliest timestamp if -there's a tie between two or more values for the smallest value. -{{% /note %}} - -#### Arguments - -- **field_expression**: Expression to identify the field to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key) - or constant. -- **tag_expression**: Expression to identify a tag key to segment by. - Can be a [tag key](/influxdb/cloud-dedicated/reference/glossary/#tag-key) - or constant. Comma-delimit multiple tags. -- **N**: Number of results to return from each InfluxQL group or specified tag segment. - -#### Notable behaviors - -- `BOTTOM()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `BOTTOM()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the bottom three values of a field" %}} - -```sql -SELECT BOTTOM(temp, 3) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | -| :------------------- | -----: | -| 2022-01-01T08:00:00Z | 21 | -| 2022-01-01T08:00:00Z | 21.1 | -| 2022-01-01T09:00:00Z | 21.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom field value for two unique tag values" %}} - -```sql -SELECT BOTTOM(temp, room, 2) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | room | -| :------------------- | -----: | :---------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom three field values and the tag value associated with each" %}} - -```sql -SELECT BOTTOM(temp, 3), room FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | room | -| :------------------- | -----: | ----------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | -| 2022-01-01T09:00:00Z | 21.4 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom field values for unique tag values and within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} -```sql -SELECT - BOTTOM(temp, room, 2) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -GROUP BY time(2h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | bottom | room | -| :------------------- | -----: | :---------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | -| 2022-01-01T10:00:00Z | 21.8 | Living Room | -| 2022-01-01T11:00:00Z | 22.4 | Kitchen | -| 2022-01-01T12:00:00Z | 22.2 | Living Room | -| 2022-01-01T12:00:00Z | 22.5 | Kitchen | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `BOTTOM()` -[maintains the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FIRST() - -Returns the [field value](/influxdb/cloud-dedicated/reference/glossary/#field-value) with the oldest timestamp. - -```sql -FIRST(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). - -#### Notable behaviors - -- `FIRST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the first value for a field" %}} - -```sql -SELECT FIRST(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | first | -| :------------------- | ----: | -| 2022-01-01T08:00:00Z | 21.1 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the first value from each field" %}} - -```sql -SELECT FIRST(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first_co | first_hum | first_temp | -| :------------------- | -------: | --------: | ---------: | -| 1970-01-01T00:00:00Z | 0 | 35.9 | 21.1 | - -{{% /expand %}} - -{{% expand "Select the first value from field keys that match a regular expression" %}} - -```sql -SELECT FIRST(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first_hum | first_temp | -| :------------------- | --------: | ---------: | -| 1970-01-01T00:00:00Z | 35.9 | 21.1 | - -{{% /expand %}} - -{{% expand "Select the first value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - FIRST(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first | -| :------------------- | ----: | -| 2022-01-01T06:00:00Z | 21 | -| 2022-01-01T12:00:00Z | 22.5 | -| 2022-01-01T18:00:00Z | 23.3 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `FIRST()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LAST() - -Returns the [field value](/influxdb/cloud-dedicated/reference/glossary/#field-value) with the most recent timestamp. - -```sql -LAST(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). - -#### Notable behaviors - -- `LAST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the last value for a field" %}} - -```sql -SELECT LAST(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | last | -| :------------------- | ---: | -| 2022-01-01T20:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the last value from each field" %}} - -```sql -SELECT LAST(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last_co | last_hum | last_temp | -| :------------------- | ------: | -------: | --------: | -| 1970-01-01T00:00:00Z | 26 | 36.5 | 22.7 | - -{{% /expand %}} - -{{% expand "Select the last value from field keys that match a regular expression" %}} - -```sql -SELECT LAST(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last_hum | last_temp | -| :------------------- | -------: | --------: | -| 1970-01-01T00:00:00Z | 36.5 | 22.7 | - -{{% /expand %}} - -{{% expand "Select the last value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - LAST(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 22.4 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `LAST()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MAX() - -Returns the greatest [field value](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -MAX(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MAX()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the maximum value from a field" %}} - -```sql -SELECT MAX(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | max | -| :------------------- | --: | -| 2022-01-01T20:00:00Z | 26 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the maximum value from each field" %}} - -```sql -SELECT MAX(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max_co | max_hum | max_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 26 | 36.9 | 23.3 | - -{{% /expand %}} - -{{% expand "Select the maximum value from field keys that match a regular expression" %}} - -```sql -SELECT MAX(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max_hum | max_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 36.9 | 23.3 | - -{{% /expand %}} - -{{% expand "Select the maximum value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MAX(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 23 | -| 2022-01-01T12:00:00Z | 22.8 | -| 2022-01-01T18:00:00Z | 23.3 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `MAX()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MIN() - -Returns the lowest [field value](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -MIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MIN()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the minimum value from a field" %}} - -```sql -SELECT MIN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | min | -| :------------------- | --: | -| 2022-01-01T08:00:00Z | 21 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the minimum value from each field" %}} - -```sql -SELECT MIN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min_co | min_hum | min_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 0 | 35.9 | 21 | - -{{% /expand %}} - -{{% expand "Select the minimum value from field keys that match a regular expression" %}} - -```sql -SELECT MIN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min_hum | min_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 35.9 | 21 | - -{{% /expand %}} - -{{% expand "Select the minimum value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MIN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 21 | -| 2022-01-01T12:00:00Z | 22.4 | -| 2022-01-01T18:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `MIN()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## PERCENTILE() - -Returns the `N`th percentile [field value](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -PERCENTILE(field_expression, N) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. -- **N**: Percentile to return. - Must be an integer or float value **greater than 0 and less than or equal to 100**. - -#### Notable behaviors - -- `PERCENTILE()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `PERCENTILE(example_field, 100)` is equivalent to [`MAX(example_field)`](#max). -- `PERCENTILE(example_field, 50)` is nearly equivalent to - [`MEDIAN(example_field)`](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/#median), - except `MEDIAN()` returns the average of the two middle values if the field - contains an even number of values. -- `PERCENTILE(example_field, 0)` returns _null_. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the 50th percentile value from a field" %}} - -```sql -SELECT PERCENTILE(temp, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | percentile | -| :------------------- | ---------: | -| 2022-01-01T11:00:00Z | 22.4 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from each field" %}} - -```sql -SELECT PERCENTILE(*, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile_co | percentile_hum | percentile_temp | -| :------------------- | ------------: | -------------: | --------------: | -| 1970-01-01T00:00:00Z | 1 | 36 | 22.4 | - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from field keys that match a regular expression" %}} - -```sql -SELECT PERCENTILE(/^[th]/, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile_hum | percentile_temp | -| :------------------- | -------------: | --------------: | -| 1970-01-01T00:00:00Z | 36 | 22.4 | - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - PERCENTILE(temp, 50) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile | -| :------------------- | ---------: | -| 2022-01-01T06:00:00Z | 22.4 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `PERCENTILE()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - - - -## TOP() - -Returns the greatest `N` [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). -`TOP()` supports int64 and float64 field value [data types](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -TOP(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) -``` - -{{% note %}} -**Note:** `TOP()` returns the field value with the earliest timestamp if there's -a tie between two or more values for the greatest value. -{{% /note %}} - -#### Arguments - -- **field_expression**: Expression to identify the field to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key) - or constant. -- **tag_expression**: Expression to identify a tag key to segment by. - Can be a [tag key](/influxdb/cloud-dedicated/reference/glossary/#tag-key) - or constant. Comma-delimit multiple tags. -- **N**: Number of results to return from each InfluxQL group or specified tag segment. - -#### Notable behaviors - -- `TOP()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `TOP()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the top three values of a field" %}} - -```sql -SELECT TOP(temp, 3) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | -| :------------------- | ---: | -| 2022-01-01T09:00:00Z | 23 | -| 2022-01-01T18:00:00Z | 23.3 | -| 2022-01-01T19:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top field value for two unique tag values" %}} - -```sql -SELECT TOP(temp, room, 2) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T18:00:00Z | 22.8 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top three field values and the tag value associated with each" %}} - -```sql -SELECT TOP(temp, 3), room FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :------ | -| 2022-01-01T09:00:00Z | 23 | Kitchen | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T19:00:00Z | 23.1 | Kitchen | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top field values for unique tag values and within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} -```sql -SELECT - TOP(temp, room, 2) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -GROUP BY time(2h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T09:00:00Z | 23 | Kitchen | -| 2022-01-01T09:00:00Z | 21.4 | Living Room | -| 2022-01-01T10:00:00Z | 22.7 | Kitchen | -| 2022-01-01T11:00:00Z | 22.2 | Living Room | -| 2022-01-01T12:00:00Z | 22.5 | Kitchen | -| 2022-01-01T12:00:00Z | 22.2 | Living Room | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `TOP()` -[maintains the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable behaviors of selector functions - -- [Timestamps when grouping by time](#timestamps-when-grouping-by-time) -- [Selector functions may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected) - -### Timestamps when grouping by time - -When using selector functions with a `GROUP BY time()` clause, most selector -functions return the timestamp of the starting boundary for each time interval. -However functions with an `N` argument that specifies the number of results to -return per group maintain the original timestamp of each returned point. - -{{< flex >}} -{{% flex-content %}} - -###### Return the start time of each time interval - -- [FIRST()](#first) -- [LAST()](#last) -- [MAX()](#max) -- [MIN()](#min) -- [PERCENTILE()](#percentile) - -{{% /flex-content %}} -{{% flex-content %}} - -###### Maintain the original timestamp - -- [BOTTOM()](#bottom) -- [TOP()](#top) - - -{{% /flex-content %}} -{{< /flex >}} - -### Selector functions may return fewer points than expected - -Queries that use the following selector functions with an `N` argument may -return fewer points than expected. - -- [BOTTOM()](#bottom) -- [TOP()](#top) - - -If the InfluxQL group or specified tag key contains `X` points or unique tag -values and `X` is less than `N`, the function returns `X` results instead of `N` -for each group or tag value. - -{{< expand-wrapper >}} -{{% expand "View example for `FN(field_key, N)`" %}} - -The example below selects the bottom 5 temperatures from the Kitchen between -{{% influxdb/custom-timestamps-span %}}2022-01-01T08:00:00Z{{% /influxdb/custom-timestamps-span %}} -and {{% influxdb/custom-timestamps-span %}}2022-01-01T10:00:00Z{{% /influxdb/custom-timestamps-span %}}. -There are only 3 points recorded for the Kitchen during the queried time range, -so the query returns 3 points instead of 5. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT BOTTOM(temp, 5) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' - AND room = 'Kitchen' -``` - -| time | bottom | -| :------------------- | -----: | -| 2022-01-01T08:00:00Z | 21 | -| 2022-01-01T09:00:00Z | 23 | -| 2022-01-01T10:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "View example for `FN(field_key, tag_key, N)`" %}} - -The example below selects the top temperature from 3 unique values of the `room` tag. -However, the `room` tag only has 2 unique values, so results only contain 2 values. - -```sql -SELECT TOP(temp, room, 3) FROM home -``` - -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T18:00:00Z | 22.8 | Living Room | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/reference/influxql/functions/technical-analysis.md b/content/influxdb/cloud-dedicated/reference/influxql/functions/technical-analysis.md index 12a5159b5..298ec0c2b 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/functions/technical-analysis.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/functions/technical-analysis.md @@ -10,1905 +10,6 @@ menu: weight: 205 # None of these functions work yet so listing as draft draft: true + +source: /shared/influxql-v3-reference/functions/technical-analysis.md --- - -Use technical analysis functions to apply algorithms to your time series data. -Many of these algorithms are often used to analyze financial and investment data, -but have application in other use cases as well. - -- [Predictive analysis](#predictive-analysis): - - [HOLT_WINTERS()](#holt_winters) -- [Technical analysis](#technical-analysis-functions): - - [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) - - [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) - - [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) - - [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) - - [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) - - [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) - - [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) - - [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) - -## Predictive analysis - -Predictive analysis functions are a type of technical analysis algorithms that -predict and forecast future values. - -### HOLT_WINTERS() - -Returns N number of predicted [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value) -using the [Holt-Winters](https://www.otexts.org/fpp/7/5) seasonal method. -`HOLT_WINTERS_WITH_FIT()` returns the fitted values in addition to `N` seasonally -adjusted predicted field values. - -Input data points must occur at regular time intervals. -To ensure regular time intervals, `HOLT_WINTERS` requires an aggregate expression -as input and a a `GROUP BY time()` to apply the aggregate operation at regular intervals. - -Use `HOLT_WINTERS()` to: - -- Predict when data values will cross a given threshold -- Compare predicted values with actual values to detect anomalies in your data - -```sql -HOLT_WINTERS[_WITH_FIT](aggregate_expression, N, S) -``` - -#### Arguments {#arguments-holt-winters} - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/cloud-dedicated/reference/influxql/functions/aggregate/). - The expression can operate on a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. -- **N**: Number of values to predict. - Predicted values occur at the same interval specified in the `GROUP BY time()` clause. -- **S**: Seasonal pattern length (number of values per season) to use when - adjusting for seasonal patterns. - To _not_ seasonally adjust predicted values, set `S` to `0` or `1.` - -#### Notable behaviors - -- In some cases, you may receive fewer than `N` predicted points. - This typically occurs when the seasonal adjustment (`S`) is invalid or when - input data is not suited for the Holt Winters algorithm. - -#### Examples - -The following examples use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -{{< expand-wrapper >}} -{{% expand "Use Holt Winters to predict field values with seasonal adjustment" %}} - -```sql -SELECT - HOLT_WINTERS(MEAN(temp_avg), 12, 12) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters | -| :------------------- | -----------------: | -| 2023-01-23T00:00:00Z | 52.141810685706844 | -| 2023-02-22T00:00:00Z | 55.41941302100692 | -| 2023-03-24T00:00:00Z | 59.74300473524414 | -| 2023-04-23T00:00:00Z | 59.91932719987093 | -| 2023-05-23T00:00:00Z | 56.03083957191051 | -| 2023-06-22T00:00:00Z | 59.98437978757551 | -| 2023-07-22T00:00:00Z | 60.903170945334175 | -| 2023-08-21T00:00:00Z | 60.75738169893358 | -| 2023-09-20T00:00:00Z | 56.619132830933445 | -| 2023-10-20T00:00:00Z | 56.10559366563841 | -| 2023-11-19T00:00:00Z | 56.248977829575935 | -| 2023-12-19T00:00:00Z | 56.075540144158985 | - -{{% /expand %}} -{{% expand "Use Holt Winters to predict field values with no seasonal adjustment" %}} - -```sql -SELECT - HOLT_WINTERS(MEAN(temp_avg), 12, 0) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters | -| :------------------- | ----------------: | -| 2023-01-23T00:00:00Z | 58.55632627159769 | -| 2023-02-22T00:00:00Z | 58.55632627159944 | -| 2023-03-24T00:00:00Z | 58.55632627160024 | -| 2023-04-23T00:00:00Z | 58.55632627160061 | -| 2023-05-23T00:00:00Z | 58.55632627160079 | -| 2023-06-22T00:00:00Z | 58.55632627160087 | -| 2023-07-22T00:00:00Z | 58.5563262716009 | -| 2023-08-21T00:00:00Z | 58.55632627160092 | -| 2023-09-20T00:00:00Z | 58.55632627160093 | -| 2023-10-20T00:00:00Z | 58.55632627160094 | -| 2023-11-19T00:00:00Z | 58.55632627160094 | -| 2023-12-19T00:00:00Z | 58.55632627160094 | - -{{% /expand %}} - -{{% expand "Use Holt Winters to predict field values with fitted values" %}} - -```sql -SELECT - HOLT_WINTERS_WITH_FIT(MEAN(temp_avg), 12, 12) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2021-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters_with_fit | -| :------------------- | --------------------: | -| 2020-12-04T00:00:00Z | 50.5 | -| 2021-01-03T00:00:00Z | 53.280924101779426 | -| 2021-02-02T00:00:00Z | 52.099111942046704 | -| 2021-03-04T00:00:00Z | 55.84541855092053 | -| 2021-04-03T00:00:00Z | 60.06803481717513 | -| 2021-05-03T00:00:00Z | 60.414989273392976 | -| 2021-06-02T00:00:00Z | 58.265755948192606 | -| 2021-07-02T00:00:00Z | 63.12426388001118 | -| 2021-08-01T00:00:00Z | 64.34281315294628 | -| 2021-08-31T00:00:00Z | 62.701261106938865 | -| 2021-09-30T00:00:00Z | 58.39095413696881 | -| 2021-10-30T00:00:00Z | 57.571954549171174 | -| 2021-11-29T00:00:00Z | 57.72622091917164 | -| 2021-12-29T00:00:00Z | 56.21981843845102 | -| 2022-01-28T00:00:00Z | 52.592076197024845 | -| 2022-02-27T00:00:00Z | 55.20608671167453 | -| 2022-03-29T00:00:00Z | 59.01290245961656 | -| 2022-04-28T00:00:00Z | 59.10660216049941 | -| 2022-05-28T00:00:00Z | 55.87577637598558 | -| 2022-06-27T00:00:00Z | 59.10005762573857 | -| 2022-07-27T00:00:00Z | 60.04395791516323 | -| 2022-08-26T00:00:00Z | 59.76994469907478 | -| 2022-09-25T00:00:00Z | 56.21467016861341 | -| 2022-10-25T00:00:00Z | 55.76538052914458 | -| 2022-11-24T00:00:00Z | 55.95817013792435 | -| 2022-12-24T00:00:00Z | 55.78474730739332 | -| 2023-01-23T00:00:00Z | 52.33558076070284 | -| 2023-02-22T00:00:00Z | 55.15350456137378 | -| 2023-03-24T00:00:00Z | 58.95292137832944 | -| 2023-04-23T00:00:00Z | 59.15381228655361 | -| 2023-05-23T00:00:00Z | 55.77542228450764 | -| 2023-06-22T00:00:00Z | 59.05797349347727 | -| 2023-07-22T00:00:00Z | 59.87830149275526 | -| 2023-08-21T00:00:00Z | 59.718176562030116 | -| 2023-09-20T00:00:00Z | 56.13817596332756 | -| 2023-10-20T00:00:00Z | 55.626497950276445 | -| 2023-11-19T00:00:00Z | 55.81338302167719 | -| 2023-12-19T00:00:00Z | 55.75008713518608 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Technical analysis functions - -Technical analysis functions apply widely used algorithms to your data. -While they are primarily used in finance and investing, they have -application in other industries. - -- [Notable behaviors of technical analysis functions](#notable-behaviors-of-technical-analysis-functions) -- [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) -- [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) -- [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) -- [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) -- [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) -- [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) -- [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) -- [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) - -### Notable behaviors of technical analysis functions - -#### Must use aggregate or selector functions when grouping by time - -All technical analysis functions support `GROUP BY` clauses that group by tags, -but do not directly support `GROUP BY` clauses that group by time. -To use technical analysis functions with with a `GROUP BY time()` clause, apply -an [aggregate](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/) -or [selector](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/) -function to the **field_expression** argument. -The technical analysis function operates on the result of the aggregate or -selector operation. - ---- - -### CHANDE_MOMENTUM_OSCILLATOR() - -The Chande Momentum Oscillator (CMO) is a technical momentum indicator developed by Tushar Chande. -The CMO indicator is created by calculating the difference between the sum of all -recent higher data points and the sum of all recent lower data points, -then dividing the result by the sum of all data movement over a given time period. -The result is multiplied by 100 to give the -100 to +100 range. -{{% cite %}}[Source](https://www.fidelity.com/learning-center/trading-investing/technical-analysis/technical-indicator-guide/cmo){{% /cite %}} - -```sql -CHANDE_MOMENTUM_OSCILLATOR(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-cmo} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period` | - | simple | `period` | - | none | `period - 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - - **none**: The algorithm does not perform any warmup at all. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 53.84615384615377 | -| 2022-01-01T12:00:00Z | 55.5555555555555 | -| 2022-01-01T13:00:00Z | -19.999999999999858 | -| 2022-01-01T14:00:00Z | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 59.99999999999972 | -| 2022-01-01T16:00:00Z | -14.285714285714432 | -| 2022-01-01T17:00:00Z | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator_co | chande_momentum_oscillator_hum | chande_momentum_oscillator_temp | -| :------------------- | ----------------------------: | -----------------------------: | ------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 20 | 53.84615384615377 | -| 2022-01-01T12:00:00Z | 0 | 20 | 55.5555555555555 | -| 2022-01-01T13:00:00Z | 100 | 42.85714285714228 | -19.999999999999858 | -| 2022-01-01T14:00:00Z | 100 | 24.999999999999332 | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 100 | 25.000000000000444 | 59.99999999999972 | -| 2022-01-01T16:00:00Z | 100 | 0 | -14.285714285714432 | -| 2022-01-01T17:00:00Z | 100 | -100 | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 100 | 50.0000000000003 | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 100 | 28.5714285714285 | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 100 | 38.461538461538545 | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T14:00:00Z | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 59.99999999999972 | -| 2022-01-01T16:00:00Z | -14.285714285714432 | -| 2022-01-01T17:00:00Z | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T12:00:00Z | 94.9367088607595 | -| 2022-01-01T13:00:00Z | 95.04132231404957 | -| 2022-01-01T14:00:00Z | 95.04132231404955 | -| 2022-01-01T15:00:00Z | 92.68218929543389 | -| 2022-01-01T16:00:00Z | 83.79002019036625 | -| 2022-01-01T17:00:00Z | 84.72964405398058 | -| 2022-01-01T18:00:00Z | 86.77405015296912 | -| 2022-01-01T19:00:00Z | 76.28466518769179 | -| 2022-01-01T20:00:00Z | 53.322717259176535 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2020-07-07T00:00:00Z | 100 | -| 2020-10-05T00:00:00Z | 21.498959056210964 | -| 2021-01-03T00:00:00Z | 2.0072053525475924 | -| 2021-04-03T00:00:00Z | -6.190741773563866 | -| 2021-07-02T00:00:00Z | -8.924485125858132 | -| 2021-09-30T00:00:00Z | 1.2078830260648301 | -| 2021-12-29T00:00:00Z | -5.181655747468743 | -| 2022-03-29T00:00:00Z | -2.3768115942029 | -| 2022-06-27T00:00:00Z | 6.511381683430422 | -| 2022-09-25T00:00:00Z | -7.7487391104997485 | -| 2022-12-24T00:00:00Z | 2.928763268960232 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### DOUBLE_EXPONENTIAL_MOVING_AVERAGE() - -The Double Exponential Moving Average (DEMA) attempts to remove the inherent lag -associated with moving averages by placing more weight on recent values. -The name suggests this is achieved by applying a double exponential smoothing which is not the case. -The value of an [EMA](#exponential_moving_average) is doubled. -To keep the value in line with the actual data and to remove the lag, the value "EMA of EMA" -is subtracted from the previously doubled EMA. -{{% cite %}}[Source](https://en.wikipedia.org/wiki/Double_exponential_moving_average){{% /cite %}} - -```sql -DOUBLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-dema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `(period - 1) × 2` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T11:00:00Z | 22.630333333333333 | -| 2022-01-01T12:00:00Z | 22.5854 | -| 2022-01-01T13:00:00Z | 22.747560000000004 | -| 2022-01-01T14:00:00Z | 22.814328 | -| 2022-01-01T15:00:00Z | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 22.55332832 | -| 2022-01-01T17:00:00Z | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 23.0672594816 | -| 2022-01-01T19:00:00Z | 23.12957407488 | -| 2022-01-01T20:00:00Z | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average_co | double_exponential_moving_average_hum | double_exponential_moving_average_temp | -| :------------------- | -----------------------------------: | ------------------------------------: | -------------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.056000000000004 | 22.630333333333333 | -| 2022-01-01T12:00:00Z | 0 | 36.019200000000005 | 22.5854 | -| 2022-01-01T13:00:00Z | 0.64 | 36.322880000000005 | 22.747560000000004 | -| 2022-01-01T14:00:00Z | 0.9279999999999999 | 36.332544000000006 | 22.814328 | -| 2022-01-01T15:00:00Z | 2.3232 | 36.266816000000006 | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 5.49376 | 36.104463360000004 | 22.55332832 | -| 2022-01-01T17:00:00Z | 8.15616 | 36.029302272 | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 15.0096384 | 36.573555916800004 | 23.0672594816 | -| 2022-01-01T19:00:00Z | 20.51534848 | 36.62971828224 | 23.12957407488 | -| 2022-01-01T20:00:00Z | 25.294948352 | 36.581181808640004 | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.814328 | -| 2022-01-01T15:00:00Z | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 22.55332832 | -| 2022-01-01T17:00:00Z | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 23.0672594816 | -| 2022-01-01T19:00:00Z | 23.12957407488 | -| 2022-01-01T20:00:00Z | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.8312 | -| 2022-01-01T15:00:00Z | 22.792303999999998 | -| 2022-01-01T16:00:00Z | 22.5715328 | -| 2022-01-01T17:00:00Z | 22.65660992 | -| 2022-01-01T18:00:00Z | 23.078180096 | -| 2022-01-01T19:00:00Z | 23.137436544 | -| 2022-01-01T20:00:00Z | 22.89677901824 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2020-07-07T00:00:00Z | 63.01034259259259 | -| 2020-10-05T00:00:00Z | 59.68671666666667 | -| 2021-01-03T00:00:00Z | 56.266558888888895 | -| 2021-04-03T00:00:00Z | 58.20687488888889 | -| 2021-07-02T00:00:00Z | 61.229622000000006 | -| 2021-09-30T00:00:00Z | 58.78596032888889 | -| 2021-12-29T00:00:00Z | 55.1067106968889 | -| 2022-03-29T00:00:00Z | 57.311773784533344 | -| 2022-06-27T00:00:00Z | 61.66637935722668 | -| 2022-09-25T00:00:00Z | 57.77452777735112 | -| 2022-12-24T00:00:00Z | 55.044203430886405 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### EXPONENTIAL_MOVING_AVERAGE() - -An exponential moving average (EMA) (or exponentially weighted moving average) -is a type of moving average similar to a -[simple moving average](/influxdb/cloud-dedicated/reference/influxql/functions/transformations/#moving_average), -except more weight is given to the latest data. - -This type of moving average reacts faster to recent data changes than a simple moving average. -{{% cite %}}[Source](https://www.investopedia.com/terms/e/ema.asp){{% /cite %}} - -```sql -EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-ema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `period - 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 22.47 | -| 2022-01-01T12:00:00Z | 22.482 | -| 2022-01-01T13:00:00Z | 22.6092 | -| 2022-01-01T14:00:00Z | 22.68552 | -| 2022-01-01T15:00:00Z | 22.691312 | -| 2022-01-01T16:00:00Z | 22.5747872 | -| 2022-01-01T17:00:00Z | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 22.894923392 | -| 2022-01-01T19:00:00Z | 22.9769540352 | -| 2022-01-01T20:00:00Z | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average_co | exponential_moving_average_hum | exponential_moving_average_temp | -| :------------------- | ----------------------------: | -----------------------------: | ------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.06 | 22.47 | -| 2022-01-01T12:00:00Z | 0 | 36.036 | 22.482 | -| 2022-01-01T13:00:00Z | 0.4 | 36.2216 | 22.6092 | -| 2022-01-01T14:00:00Z | 0.64 | 36.25296 | 22.68552 | -| 2022-01-01T15:00:00Z | 1.584 | 36.231776 | 22.691312 | -| 2022-01-01T16:00:00Z | 3.7504000000000004 | 36.1390656 | 22.5747872 | -| 2022-01-01T17:00:00Z | 5.85024 | 36.08343936 | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 10.710144 | 36.410063616 | 22.894923392 | -| 2022-01-01T19:00:00Z | 15.2260864 | 36.4860381696 | 22.9769540352 | -| 2022-01-01T20:00:00Z | 19.53565184 | 36.49162290176 | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T14:00:00Z | 22.68552 | -| 2022-01-01T15:00:00Z | 22.691312 | -| 2022-01-01T16:00:00Z | 22.5747872 | -| 2022-01-01T17:00:00Z | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 22.894923392 | -| 2022-01-01T19:00:00Z | 22.9769540352 | -| 2022-01-01T20:00:00Z | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 22.275 | -| 2022-01-01T12:00:00Z | 22.365 | -| 2022-01-01T13:00:00Z | 22.538999999999998 | -| 2022-01-01T14:00:00Z | 22.6434 | -| 2022-01-01T15:00:00Z | 22.66604 | -| 2022-01-01T16:00:00Z | 22.559624 | -| 2022-01-01T17:00:00Z | 22.6157744 | -| 2022-01-01T18:00:00Z | 22.88946464 | -| 2022-01-01T19:00:00Z | 22.973678784 | -| 2022-01-01T20:00:00Z | 22.8642072704 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2020-07-07T00:00:00Z | 59.971944444444446 | -| 2020-10-05T00:00:00Z | 58.65427777777778 | -| 2021-01-03T00:00:00Z | 56.77478888888889 | -| 2021-04-03T00:00:00Z | 57.86042888888889 | -| 2021-07-02T00:00:00Z | 59.836257333333336 | -| 2021-09-30T00:00:00Z | 58.657309955555554 | -| 2021-12-29T00:00:00Z | 56.38994152888889 | -| 2022-03-29T00:00:00Z | 57.44729825066667 | -| 2022-06-27T00:00:00Z | 60.13504561706667 | -| 2022-09-25T00:00:00Z | 58.085471814684446 | -| 2022-12-24T00:00:00Z | 56.30128308881067 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### KAUFMANS_EFFICIENCY_RATIO() - -Kaufman's Efficiency Ration, or simply "Efficiency Ratio" (ER), is calculated by -dividing the data change over a period by the absolute sum of the data movements -that occurred to achieve that change. -The resulting ratio ranges between 0 and 1 with higher values representing a -more efficient or trending market. - -The ER is very similar to the [Chande Momentum Oscillator](#chande_momentum_oscillator) (CMO). -The difference is that the CMO takes market direction into account, but if you -take the absolute CMO and divide by 100, you you get the Efficiency Ratio. -{{% cite %}}[Source](http://etfhq.com/blog/2011/02/07/kaufmans-efficiency-ratio/){{% /cite %}} - -```sql -KAUFMANS_EFFICIENCY_RATIO(field_expression, period[, hold_period]) -``` - -#### Arguments {#arguments-er} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is the same as `period`. - Must be an integer greater than or equal to `1`. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2022-01-01T12:00:00Z | 0.555555555555555 | -| 2022-01-01T13:00:00Z | 0.19999999999999857 | -| 2022-01-01T14:00:00Z | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio_co | kaufmans_efficiency_ratio_hum | kaufmans_efficiency_ratio_temp | -| :------------------- | ---------------------------: | ----------------------------: | -----------------------------: | -| 2022-01-01T12:00:00Z | 0 | 0.2 | 0.555555555555555 | -| 2022-01-01T13:00:00Z | 1 | 0.4285714285714228 | 0.19999999999999857 | -| 2022-01-01T14:00:00Z | 1 | 0.24999999999999334 | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 1 | 0.25000000000000444 | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 1 | 0 | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 1 | 1 | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 1 | 0.500000000000003 | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 1 | 0.285714285714285 | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 1 | 0.38461538461538547 | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2022-01-01T14:00:00Z | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2020-10-05T00:00:00Z | 0.21498959056210964 | -| 2021-01-03T00:00:00Z | 0.020072053525475923 | -| 2021-04-03T00:00:00Z | 0.06190741773563866 | -| 2021-07-02T00:00:00Z | 0.08924485125858131 | -| 2021-09-30T00:00:00Z | 0.0120788302606483 | -| 2021-12-29T00:00:00Z | 0.05181655747468743 | -| 2022-03-29T00:00:00Z | 0.023768115942028996 | -| 2022-06-27T00:00:00Z | 0.06511381683430421 | -| 2022-09-25T00:00:00Z | 0.07748739110499749 | -| 2022-12-24T00:00:00Z | 0.029287632689602317 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### KAUFMANS_ADAPTIVE_MOVING_AVERAGE() - -Kaufman's Adaptive Moving Average (KAMA) is a moving average designed to account -for sample noise or volatility. -KAMA will closely follow data points when the data swings are relatively small and noise is low. -KAMA will adjust when the data swings widen and follow data from a greater distance. -This trend-following indicator can be used to identify the overall trend, -time turning points and filter data movements. -{{% cite %}}[Source](http://stockcharts.com/school/doku.php?id=chart_school:technical_indicators:kaufman_s_adaptive_moving_average){{% /cite %}} - -```sql -KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_expression, period[, hold_period]) -``` - -#### Arguments {#arguments-kama} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is the same as `period`. - Must be an integer greater than or equal to `1`. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2022-01-01T12:00:00Z | 22.415923627793976 | -| 2022-01-01T13:00:00Z | 22.429061002513993 | -| 2022-01-01T14:00:00Z | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average_co | kaufmans_adaptive_moving_average_hum | kaufmans_adaptive_moving_average_temp | -| :------------------- | ----------------------------------: | -----------------------------------: | ------------------------------------: | -| 2022-01-01T12:00:00Z | 0 | 36 | 22.415923627793976 | -| 2022-01-01T13:00:00Z | 0.44444444444444453 | 36.052029136316335 | 22.429061002513993 | -| 2022-01-01T14:00:00Z | 0.6913580246913581 | 36.063497322866624 | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 1.7174211248285327 | 36.06981031521873 | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 4.065233958238074 | 36.069519741586184 | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 6.258463310132264 | 36.03862207865899 | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 11.476924061184592 | 36.153751327944484 | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 16.153846700658107 | 36.17872350475971 | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 20.52991483369895 | 36.206893865280215 | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2022-01-01T14:00:00Z | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2020-10-05T00:00:00Z | 64.23776629054989 | -| 2021-01-03T00:00:00Z | 64.17743082167587 | -| 2021-04-03T00:00:00Z | 64.12884833681618 | -| 2021-07-02T00:00:00Z | 64.11026540732492 | -| 2021-09-30T00:00:00Z | 64.07304846623671 | -| 2021-12-29T00:00:00Z | 63.97149717822299 | -| 2022-03-29T00:00:00Z | 63.94081206327896 | -| 2022-06-27T00:00:00Z | 63.94324197904272 | -| 2022-09-25T00:00:00Z | 63.83284150412919 | -| 2022-12-24T00:00:00Z | 63.76394979616807 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### RELATIVE_STRENGTH_INDEX() - -The relative strength index (RSI) is a momentum indicator that compares the -magnitude of recent increases and decreases over a specified time period to -measure speed and change of data movements. -{{% cite %}}[Source](https://www.investopedia.com/terms/r/rsi.asp){{% /cite %}} - -```sql -RELATIVE_STRENGTH_INDEX(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-rsi} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is the same as the `period`. - Must be an integer greater than or equal to `-1`. -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T12:00:00Z | 92.39130434782608 | -| 2022-01-01T13:00:00Z | 92.78350515463916 | -| 2022-01-01T14:00:00Z | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index_co | relative_strength_index_hum | relative_strength_index_temp | -| :------------------- | -------------------------: | --------------------------: | ---------------------------: | -| 2022-01-01T12:00:00Z | | 98.11827956989245 | 92.39130434782608 | -| 2022-01-01T13:00:00Z | 100 | 98.23677581863977 | 92.78350515463916 | -| 2022-01-01T14:00:00Z | 100 | 95.04467912266443 | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 100 | 93.02941956003185 | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 100 | 88.05084037126848 | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 100 | 88.05084037126848 | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 100 | 91.63299959013992 | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 100 | 80.85951627810859 | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 100 | 76.8440852816889 | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T14:00:00Z | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T12:00:00Z | 97.46835443037975 | -| 2022-01-01T13:00:00Z | 97.52066115702479 | -| 2022-01-01T14:00:00Z | 97.52066115702479 | -| 2022-01-01T15:00:00Z | 96.34109464771694 | -| 2022-01-01T16:00:00Z | 91.89501009518312 | -| 2022-01-01T17:00:00Z | 92.36482202699028 | -| 2022-01-01T18:00:00Z | 93.38702507648456 | -| 2022-01-01T19:00:00Z | 88.1423325938459 | -| 2022-01-01T20:00:00Z | 76.66135862958828 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2020-10-05T00:00:00Z | 69.9692046299246 | -| 2021-01-03T00:00:00Z | 63.37405020679043 | -| 2021-04-03T00:00:00Z | 70.82662989351107 | -| 2021-07-02T00:00:00Z | 74.90131747577793 | -| 2021-09-30T00:00:00Z | 56.212729394565066 | -| 2021-12-29T00:00:00Z | 46.095152535803514 | -| 2022-03-29T00:00:00Z | 60.709021374375894 | -| 2022-06-27T00:00:00Z | 69.93773053391476 | -| 2022-09-25T00:00:00Z | 44.87321655968338 | -| 2022-12-24T00:00:00Z | 41.845933101386215 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### TRIPLE_EXPONENTIAL_MOVING_AVERAGE() - -The triple exponential moving average (TEMA) filters out volatility from -conventional moving averages. -While the name implies that it's a triple exponential smoothing, it's actually a -composite of a [single exponential moving average](#exponential_moving_average), -a [double exponential moving average](#double_exponential_moving_average), -and a triple exponential moving average. -{{% cite %}}[Source](https://www.investopedia.com/terms/t/triple-exponential-moving-average.asp){{% /cite %}} - -```sql -TRIPLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-tema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `(period - 1) × 3` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T11:00:00Z | 22.54347777777777 | -| 2022-01-01T12:00:00Z | 22.499126666666672 | -| 2022-01-01T13:00:00Z | 22.716772000000002 | -| 2022-01-01T14:00:00Z | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 22.6128236096 | -| 2022-01-01T18:00:00Z | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average_co | triple_exponential_moving_average_hum | triple_exponential_moving_average_temp | -| :------------------- | -----------------------------------: | ------------------------------------: | -------------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.03026666666666 | 22.54347777777777 | -| 2022-01-01T12:00:00Z | 0 | 35.99608 | 22.499126666666672 | -| 2022-01-01T13:00:00Z | 0.7840000000000001 | 36.379856000000004 | 22.716772000000002 | -| 2022-01-01T14:00:00Z | 1.0432 | 36.353712 | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 2.663040000000001 | 36.25279040000001 | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 6.300159999999999 | 36.054262656000006 | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 8.977536 | 35.98746094080001 | 22.6128236096 | -| 2022-01-01T18:00:00Z | 16.698608639999996 | 36.67902875136 | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 22.122591232 | 36.68111467007999 | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 26.541314662400005 | 36.579546917888 | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 22.6128236096 | -| 2022-01-01T18:00:00Z | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T17:00:00Z | 22.65201408 | -| 2022-01-01T18:00:00Z | 23.164150553600003 | -| 2022-01-01T19:00:00Z | 23.17404420096 | -| 2022-01-01T20:00:00Z | 22.84003200512 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2020-07-07T00:00:00Z | 64.17547253086421 | -| 2020-10-05T00:00:00Z | 59.182219074074055 | -| 2021-01-03T00:00:00Z | 55.03945899999998 | -| 2021-04-03T00:00:00Z | 57.98342055555557 | -| 2021-07-02T00:00:00Z | 61.72370060000002 | -| 2021-09-30T00:00:00Z | 58.3235789128889 | -| 2021-12-29T00:00:00Z | 53.982153124088896 | -| 2022-03-29T00:00:00Z | 57.325663060373344 | -| 2022-06-27T00:00:00Z | 62.67482784650667 | -| 2022-09-25T00:00:00Z | 57.274230204423134 | -| 2022-12-24T00:00:00Z | 54.17634351477504 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### TRIPLE_EXPONENTIAL_DERIVATIVE() - -The triple exponential derivative indicator, commonly referred to as "TRIX," is -an oscillator used to identify oversold and overbought markets, and can also be -used as a momentum indicator. -TRIX calculates a [triple exponential moving average](#triple_exponential_moving_average) -of the [log](/influxdb/v2/query-data/influxql/functions/transformations/#log) -of the data input over the period of time. -The previous value is subtracted from the previous value. -This prevents cycles that are shorter than the defined period from being considered by the indicator. - -Like many oscillators, TRIX oscillates around a zero line. When used as an oscillator, -a positive value indicates an overbought market while a negative value indicates an oversold market. -When used as a momentum indicator, a positive value suggests momentum is increasing -while a negative value suggests momentum is decreasing. -Many analysts believe that when the TRIX crosses above the zero line it gives a -buy signal, and when it closes below the zero line, it gives a sell signal. -{{% cite %}}[Source](https://www.investopedia.com/articles/technical/02/092402.asp){{% /cite %}} - -```sql -TRIPLE_EXPONENTIAL_DERIVATIVE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-trix} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :--------------------- | - | exponential | `period` | - | simple | `(period - 1) × 3 + 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T12:00:00Z | 0.5731400170122969 | -| 2022-01-01T13:00:00Z | 0.5082054442170802 | -| 2022-01-01T14:00:00Z | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative_co | triple_exponential_derivative_hum | triple_exponential_derivative_temp | -| :------------------- | -------------------------------: | --------------------------------: | ---------------------------------: | -| 2022-01-01T12:00:00Z | | 0.011689978802653656 | 0.5731400170122969 | -| 2022-01-01T13:00:00Z | | 0.08193865253971477 | 0.5082054442170802 | -| 2022-01-01T14:00:00Z | 179.99999999999997 | 0.10794983570248107 | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 148.57142857142853 | 0.0905729924662868 | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 140.22988505747128 | 0.02876803922613469 | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 92.48803827751195 | -0.022670378539191294 | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 84.49217002237135 | 0.10699801078373206 | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 64.59469801081093 | 0.17000537478475408 | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 48.10094220759999 | 0.16771238737589567 | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T14:00:00Z | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T18:00:00Z | 0.3040309049773704 | -| 2022-01-01T19:00:00Z | 0.37510717611963784 | -| 2022-01-01T20:00:00Z | 0.2625157254706467 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2020-10-05T00:00:00Z | 1.8609138140919912 | -| 2021-01-03T00:00:00Z | 0.8545019640246121 | -| 2021-04-03T00:00:00Z | 0.6716861515154271 | -| 2021-07-02T00:00:00Z | 1.0528294030543783 | -| 2021-09-30T00:00:00Z | 0.6847349621789123 | -| 2021-12-29T00:00:00Z | -0.18257939931221046 | -| 2022-03-29T00:00:00Z | -0.1722392917734461 | -| 2022-06-27T00:00:00Z | 0.6038050639217252 | -| 2022-09-25T00:00:00Z | 0.21734485841473639 | -| 2022-12-24T00:00:00Z | -0.44578753427667595 | - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/reference/influxql/functions/transformations.md b/content/influxdb/cloud-dedicated/reference/influxql/functions/transformations.md index c922fdc5c..5c767c9d7 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/functions/transformations.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/functions/transformations.md @@ -1,6 +1,6 @@ --- title: InfluxQL transformation functions -list_title: Tranfsormation functions +list_title: Transformation functions description: > Use transformation functions modify and return values in each row of queried data. menu: @@ -8,2743 +8,6 @@ menu: name: Transformations parent: influxql-functions weight: 205 + +source: /shared/influxql-v3-reference/functions/transformations.md --- - -InfluxQL transformation functions modify and return values in each row of queried data. - -- [ABS()](#abs) -- [ACOS()](#acos) -- [ASIN()](#asin) -- [ATAN()](#atan) -- [ATAN2()](#atan2) -- [CEIL()](#ceil) -- [COS()](#cos) -- [CUMULATIVE_SUM()](#cumulative_sum) -- [DERIVATIVE()](#derivative) -- [DIFFERENCE()](#difference) -- [ELAPSED()](#elapsed) -- [EXP()](#exp) -- [FLOOR()](#floor) -- [LN()](#ln) -- [LOG()](#log) -- [LOG2()](#log2) -- [LOG10()](#log10) -- [MOVING_AVERAGE()](#moving_average) -- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) -- [NON_NEGATIVE_DIFFERENCE()](#non_negative_difference) -- [POW()](#pow) -- [ROUND()](#round) -- [SIN()](#sin) -- [SQRT()](#sqrt) -- [TAN()](#tan) - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/cloud-dedicated/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## Notable behaviors of transformation functions - -#### Must use aggregate or selector functions when grouping by time - -Most transformation functions support `GROUP BY` clauses that group by tags, -but do not directly support `GROUP BY` clauses that group by time. -To use transformation functions with with a `GROUP BY time()` clause, apply -an [aggregate](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/) -or [selector](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/) -function to the **field_expression** argument. -The transformation operates on the result of the aggregate or selector operation. - ---- - -## ABS() - -Returns the absolute value of the field value. - -```sql -ABS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ABS()` to a field" %}} - -```sql -SELECT - a, - ABS(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | abs | -| :------------------- | -----------------: | ----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.33909108671076 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 0.774984088561186 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 0.921037167720451 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 0.73880754843378 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 0.905980032168252 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 0.891164752631417 | - -{{% /expand %}} - -{{% expand "Apply `ABS()` to each field" %}} - -```sql -SELECT ABS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | abs_a | abs_b | -| :------------------- | ----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.163643058925645 | -| 2023-01-01T00:01:00Z | 0.774984088561186 | 0.137034364053949 | -| 2023-01-01T00:02:00Z | 0.921037167720451 | 0.482943221384294 | -| 2023-01-01T00:03:00Z | 0.73880754843378 | 0.0729732928756677 | -| 2023-01-01T00:04:00Z | 0.905980032168252 | 1.77857552719844 | -| 2023-01-01T00:05:00Z | 0.891164752631417 | 0.741147445214238 | - -{{% /expand %}} - -{{% expand "Apply `ABS()` to time windows (grouped by time)" %}} - -```sql -SELECT - ABS(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | abs | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 0.4345725888930678 | -| 2023-01-01T00:10:00Z | 0.12861008519618367 | -| 2023-01-01T00:20:00Z | 0.030168160597251192 | -| 2023-01-01T00:30:00Z | 0.02928699660831855 | -| 2023-01-01T00:40:00Z | 0.02211434600834538 | -| 2023-01-01T00:50:00Z | 0.15530468657783394 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ACOS() - -Returns the arccosine (in radians) of the field value. -Field values must be between -1 and 1. - -```sql -ACOS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ACOS()` to a field" %}} - -```sql -SELECT - a, - ACOS(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | acos | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 1.2248457522250173 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 2.4574862443115 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 2.741531473732281 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 2.4020955294179256 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 2.7044854502651114 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 2.6707024029338 | - -{{% /expand %}} - -{{% expand "Apply `ACOS()` to each field" %}} - -```sql -SELECT ACOS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | acos_a | acos_b | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 1.2248457522250173 | 1.7351786975993897 | -| 2023-01-01T00:01:00Z | 2.4574862443115 | 1.433329416131427 | -| 2023-01-01T00:02:00Z | 2.741531473732281 | 2.074809114132046 | -| 2023-01-01T00:03:00Z | 2.4020955294179256 | 1.6438345403920092 | -| 2023-01-01T00:04:00Z | 2.7044854502651114 | | -| 2023-01-01T00:05:00Z | 2.6707024029338 | 0.7360183965088304 | - -{{% /expand %}} - -{{% expand "Apply `ACOS()` to time windows (grouped by time)" %}} - -```sql -SELECT - ACOS(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | acos | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 2.0203599837582877 | -| 2023-01-01T00:10:00Z | 1.441829029328407 | -| 2023-01-01T00:20:00Z | 1.5406235882252437 | -| 2023-01-01T00:30:00Z | 1.5415051418561052 | -| 2023-01-01T00:40:00Z | 1.5486801779072885 | -| 2023-01-01T00:50:00Z | 1.41486045205998 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ASIN() - -Returns the arcsine (in radians) of the field value. -Field values must be between -1 and 1. - -```sql -ASIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ASIN()` to a field" %}} - -```sql -SELECT - a, - ASIN(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | asin | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.34595057456987915 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | -0.8866899175166036 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | -1.1707351469373848 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | -0.8312992026230288 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | -1.133689123470215 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | -1.0999060761389035 | - -{{% /expand %}} - -{{% expand "Apply `ASIN()` to each field" %}} - -```sql -SELECT ASIN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | asin_a | asin_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.34595057456987915 | -0.1643823708044932 | -| 2023-01-01T00:01:00Z | -0.8866899175166036 | 0.1374669106634696 | -| 2023-01-01T00:02:00Z | -1.1707351469373848 | -0.5040127873371497 | -| 2023-01-01T00:03:00Z | -0.8312992026230288 | -0.07303821359711259 | -| 2023-01-01T00:04:00Z | -1.133689123470215 | | -| 2023-01-01T00:05:00Z | -1.0999060761389035 | 0.8347779302860662 | - -{{% /expand %}} - -{{% expand "Apply `ASIN()` to time windows (grouped by time)" %}} - -```sql -SELECT - ASIN(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | asin | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.44956365696339134 | -| 2023-01-01T00:10:00Z | 0.1289672974664895 | -| 2023-01-01T00:20:00Z | 0.030172738569652847 | -| 2023-01-01T00:30:00Z | 0.029291184938791334 | -| 2023-01-01T00:40:00Z | 0.022116148887608062 | -| 2023-01-01T00:50:00Z | 0.15593587473491674 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ATAN() - -Returns the arctangent (in radians) of the field value. - -```sql -ATAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ATAN()` to a field" %}} - -```sql -SELECT - a, - ATAN(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | atan | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.32692355076199897 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | -0.659300127490126 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | -0.7443170183837121 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | -0.6362993731936669 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | -0.7361091800814261 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | -0.727912249468035 | - -{{% /expand %}} - -{{% expand "Apply `ATAN()` to each field" %}} - -```sql -SELECT ATAN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan_a | atan_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.32692355076199897 | -0.1622053541422186 | -| 2023-01-01T00:01:00Z | -0.659300127490126 | 0.13618613793696105 | -| 2023-01-01T00:02:00Z | -0.7443170183837121 | -0.4499093121666581 | -| 2023-01-01T00:03:00Z | -0.6362993731936669 | -0.07284417510130452 | -| 2023-01-01T00:04:00Z | -0.7361091800814261 | 1.0585985450688151 | -| 2023-01-01T00:05:00Z | -0.727912249468035 | 0.6378113578294793 | - -{{% /expand %}} - -{{% expand "Apply `ATAN()` to time windows (grouped by time)" %}} - -```sql -SELECT - ATAN(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.4099506966510045 | -| 2023-01-01T00:10:00Z | 0.1279079463727065 | -| 2023-01-01T00:20:00Z | 0.030159013397288013 | -| 2023-01-01T00:30:00Z | 0.02927862748761639 | -| 2023-01-01T00:40:00Z | 0.022110742100818606 | -| 2023-01-01T00:50:00Z | 0.15407382461141705 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ATAN2() - -Returns the the arctangent of `y/x` in radians. - -```sql -ATAN2(expression_y, expression_x) -``` - -#### Arguments - -- **expression_y**: Expression to identify the `y` numeric value or one or more - fields to operate on. - Can be a number literal, [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **expression_x**: Expression to identify the `x` numeric value or one or more - fields to operate on. - Can be a number literal, [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ATAN2()` to a field divided by another field" %}} - -```sql -SELECT ATAN2(a, b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2 | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 2.0204217911794937 | -| 2023-01-01T00:01:00Z | -1.395783190047229 | -| 2023-01-01T00:02:00Z | -2.053731408859953 | -| 2023-01-01T00:03:00Z | -1.669248713922653 | -| 2023-01-01T00:04:00Z | -0.47112754043763505 | -| 2023-01-01T00:05:00Z | -0.8770454978291377 | - -{{% /expand %}} - -{{% expand "Apply `ATAN2()` to each field divided by a numeric value" %}} - -```sql -SELECT ATAN2(*, 2) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2_a | atan2_b | -| :------------------- | -------------------: | --------------------: | -| 2023-01-01T00:00:00Z | 0.16794843225523703 | -0.0816396675119722 | -| 2023-01-01T00:01:00Z | -0.36967737169970566 | 0.06841026268126137 | -| 2023-01-01T00:02:00Z | -0.4315666721698651 | -0.2369359777533473 | -| 2023-01-01T00:03:00Z | -0.35385538623378937 | -0.036470468100670846 | -| 2023-01-01T00:04:00Z | -0.4253376417906667 | 0.7268651162204586 | -| 2023-01-01T00:05:00Z | -0.41917415992493756 | 0.35488446257957357 | - -{{% /expand %}} - -{{% expand "Apply `ATAN2()` to time windows (grouped by time)" %}} - -```sql -SELECT - ATAN2(MEAN(a), MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2 | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | -1.278967897411707 | -| 2023-01-01T00:10:00Z | 2.3520553840586773 | -| 2023-01-01T00:20:00Z | 2.226497789888965 | -| 2023-01-01T00:30:00Z | 3.0977773783018656 | -| 2023-01-01T00:40:00Z | 2.9285769547942677 | -| 2023-01-01T00:50:00Z | 0.9505419744107901 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## CEIL() - -Returns the subsequent value rounded up to the nearest integer. - -```sql -CEIL(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `CEIL()` to a field" %}} - -```sql -SELECT - b, - CEIL(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | ceil | -| :------------------- | ------------------: | ---: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 1 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | - -{{% /expand %}} - -{{% expand "Apply `CEIL()` to each field" %}} - -```sql -SELECT CEIL(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ceil_a | ceil_b | -| :------------------- | -----: | -----: | -| 2023-01-01T00:00:00Z | 1 | -0 | -| 2023-01-01T00:01:00Z | -0 | 1 | -| 2023-01-01T00:02:00Z | -0 | -0 | -| 2023-01-01T00:03:00Z | -0 | -0 | -| 2023-01-01T00:04:00Z | -0 | 2 | -| 2023-01-01T00:05:00Z | -0 | 1 | - -{{% /expand %}} - -{{% expand "Apply `CEIL()` to time windows (grouped by time)" %}} - -```sql -SELECT - CEIL(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ceil | -| :------------------- | ---: | -| 2023-01-01T00:00:00Z | 1 | -| 2023-01-01T00:10:00Z | -0 | -| 2023-01-01T00:20:00Z | -0 | -| 2023-01-01T00:30:00Z | -0 | -| 2023-01-01T00:40:00Z | -0 | -| 2023-01-01T00:50:00Z | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## COS() - -Returns the cosine of the field value. - -```sql -COS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `COS()` to a field" %}} - -```sql -SELECT - b, - COS(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | cos | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | 0.9866403278718959 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.9906254752128878 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | 0.8856319645801471 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | 0.9973386305831397 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | -0.20628737691395405 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.7376943643170851 | - -{{% /expand %}} - -{{% expand "Apply `COS()` to each field" %}} - -```sql -SELECT COS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cos_a | cos_b | -| :------------------- | -----------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.9430573869206459 | 0.9866403278718959 | -| 2023-01-01T00:01:00Z | 0.7144321674550146 | 0.9906254752128878 | -| 2023-01-01T00:02:00Z | 0.6049946586273094 | 0.8856319645801471 | -| 2023-01-01T00:03:00Z | 0.7392720891861374 | 0.9973386305831397 | -| 2023-01-01T00:04:00Z | 0.616914561474936 | -0.20628737691395405 | -| 2023-01-01T00:05:00Z | 0.6285065034701617 | 0.7376943643170851 | - -{{% /expand %}} - -{{% expand "Apply `COS()` to time windows (grouped by time)" %}} - -```sql -SELECT - COS(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cos | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 0.9914907269510592 | -| 2023-01-01T00:10:00Z | 0.9918765457796455 | -| 2023-01-01T00:20:00Z | 0.9997307399250498 | -| 2023-01-01T00:30:00Z | 0.7850670342365872 | -| 2023-01-01T00:40:00Z | 0.9947779847618986 | -| 2023-01-01T00:50:00Z | 0.9938532355205111 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## CUMULATIVE_SUM() - -Returns the running total of subsequent [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -CUMULATIVE_SUM(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `CUMULATIVE_SUM()` to a field" %}} - -```sql -SELECT CUMULATIVE_SUM(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to each field" %}} - -```sql -SELECT CUMULATIVE_SUM(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum_a | cumulative_sum_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to field keys that match a regular expression" %}} - -```sql -SELECT CUMULATIVE_SUM(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum_a | cumulative_sum_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to time windows (grouped by time)" %}} - -```sql -SELECT - CUMULATIVE_SUM(SUM(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 1.3054783385851743 | -| 2023-01-01T00:10:00Z | 0.029980276948385454 | -| 2023-01-01T00:20:00Z | -0.20208529969578404 | -| 2023-01-01T00:30:00Z | -6.882005145666267 | -| 2023-01-01T00:40:00Z | -7.904410787756402 | -| 2023-01-01T00:50:00Z | -6.795080184131271 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DERIVATIVE() - -Returns the rate of change between subsequent [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value) -per `unit`. - -```sql -SELECT DERIVATIVE(field_expression[, unit]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **unit**: Unit of time to use to calculate the rate of change. - Supports [duration literals](/influxdb/cloud-dedicated/reference/influxql/#durations). - _Default is `1s` (per second)_. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `DERIVATIVE()` to a field to calculate the per second change" %}} - -```sql -SELECT DERIVATIVE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | --------------------: | -| 2023-01-01T00:01:00Z | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to a field to calculate the per 5 minute change" %}} - -```sql -SELECT DERIVATIVE(b, 5m) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | ------------------: | -| 2023-01-01T00:01:00Z | 1.5033871148979698 | -| 2023-01-01T00:02:00Z | -3.0998879271912148 | -| 2023-01-01T00:03:00Z | 2.0498496425431316 | -| 2023-01-01T00:04:00Z | 9.257744100370537 | -| 2023-01-01T00:05:00Z | -5.187140409921009 | -| 2023-01-01T00:06:00Z | -2.26736721151909 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to each field" %}} - -```sql -SELECT DERIVATIVE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative_a | derivative_b | -| :------------------- | ---------------------: | --------------------: | -| 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to field keys that match a regular expression" %}} - -```sql -SELECT DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative_a | derivative_b | -| :------------------- | ---------------------: | --------------------: | -| 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to time windows (grouped by time)" %}} - -```sql -SELECT - DERIVATIVE(MEAN(b), 1m) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | --------------------: | -| 2023-01-01T00:10:00Z | -0.025809764002219633 | -| 2023-01-01T00:20:00Z | 0.010434324849926194 | -| 2023-01-01T00:30:00Z | -0.06447854269326314 | -| 2023-01-01T00:40:00Z | 0.05657514203880348 | -| 2023-01-01T00:50:00Z | 0.021317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DIFFERENCE() - -Returns the result of subtraction between subsequent [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -DIFFERENCE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [NON_NEGATIVE_DIFFERENCE()](#non_negative_difference) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `DIFFERENCE()` to a field" %}} - -```sql -SELECT DIFFERENCE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference | -| :------------------- | -------------------: | -| 2023-01-01T00:01:00Z | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to each field" %}} - -```sql -SELECT DIFFERENCE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference_a | difference_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to field keys that match a regular expression" %}} - -```sql -SELECT DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference_a | difference_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to time windows (grouped by time)" %}} - -```sql -SELECT - DIFFERENCE(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference | -| :------------------- | ------------------: | -| 2023-01-01T00:10:00Z | -0.2580976400221963 | -| 2023-01-01T00:20:00Z | 0.10434324849926194 | -| 2023-01-01T00:30:00Z | -0.6447854269326314 | -| 2023-01-01T00:40:00Z | 0.5657514203880348 | -| 2023-01-01T00:50:00Z | 0.21317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ELAPSED() - -Returns the difference between subsequent [field value's](/influxdb/cloud-dedicated/reference/glossary/#field-value) -timestamps in a specified `unit` of time. - -```sql -ELAPSED(field_expression[, unit ]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. -- **unit**: Unit of time to return the elapsed time in. - Supports [duration literals](/influxdb/cloud-dedicated/reference/influxql/#durations). - _Default is `1ns` (nanoseconds)_. - -#### Notable behaviors - -- If the `unit` is greater than the elapsed time between points, `ELAPSED()` - returns `0`. -- `ELAPSED()` supports the `GROUP BY time()` clause but the query results aren't very useful. - An `ELAPSED()` query with a nested function and a `GROUP BY time()` clause - returns the interval specified in the `GROUP BY time()` clause. - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ELAPSED()` to a field and return elapsed time in nanoseconds" %}} - -```sql -SELECT ELAPSED(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed | -| :------------------- | ----------: | -| 2023-01-01T00:01:00Z | 60000000000 | -| 2023-01-01T00:02:00Z | 60000000000 | -| 2023-01-01T00:03:00Z | 60000000000 | -| 2023-01-01T00:04:00Z | 60000000000 | -| 2023-01-01T00:05:00Z | 60000000000 | -| 2023-01-01T00:06:00Z | 60000000000 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to a field and return elapsed time in seconds" %}} - -```sql -SELECT ELAPSED(b, 1s) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed | -| :------------------- | ------: | -| 2023-01-01T00:01:00Z | 60 | -| 2023-01-01T00:02:00Z | 60 | -| 2023-01-01T00:03:00Z | 60 | -| 2023-01-01T00:04:00Z | 60 | -| 2023-01-01T00:05:00Z | 60 | -| 2023-01-01T00:06:00Z | 60 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to each field" %}} - -```sql -SELECT ELAPSED(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed_a | elapsed_b | -| :------------------- | ----------: | ----------: | -| 2023-01-01T00:01:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:02:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:03:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:04:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:05:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:06:00Z | 60000000000 | 60000000000 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to field keys that match a regular expression" %}} - -```sql -SELECT ELAPSED(/[ab]/, 1s) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed_a | elapsed_b | -| :------------------- | --------: | --------: | -| 2023-01-01T00:01:00Z | 60 | 60 | -| 2023-01-01T00:02:00Z | 60 | 60 | -| 2023-01-01T00:03:00Z | 60 | 60 | -| 2023-01-01T00:04:00Z | 60 | 60 | -| 2023-01-01T00:05:00Z | 60 | 60 | -| 2023-01-01T00:06:00Z | 60 | 60 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## EXP() - -Returns the exponential of the field value. - -```sql -EXP(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `EXP()` to a field" %}} - -```sql -SELECT - a, - EXP(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | exp | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 1.4036711951820788 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 0.460711111517308 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 0.39810592427186076 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 0.4776831901055915 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 0.40414561525252984 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 0.4101777188333968 | - -{{% /expand %}} - -{{% expand "Apply `EXP()` to each field" %}} - -```sql -SELECT EXP(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | exp_a | exp_b | -| :------------------- | ------------------: | -----------------: | -| 2023-01-01T00:00:00Z | 1.4036711951820788 | 0.8490450268435884 | -| 2023-01-01T00:01:00Z | 0.460711111517308 | 1.14686755886191 | -| 2023-01-01T00:02:00Z | 0.39810592427186076 | 0.6169648527893578 | -| 2023-01-01T00:03:00Z | 0.4776831901055915 | 0.929625657322271 | -| 2023-01-01T00:04:00Z | 0.40414561525252984 | 5.921415512753404 | -| 2023-01-01T00:05:00Z | 0.4101777188333968 | 2.09834186598405 | - -{{% /expand %}} - -{{% expand "Apply `EXP()` to time windows (grouped by time)" %}} - -```sql -SELECT - EXP(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | exp | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 0.6475413743155294 | -| 2023-01-01T00:10:00Z | 1.137246608416461 | -| 2023-01-01T00:20:00Z | 1.030627830373793 | -| 2023-01-01T00:30:00Z | 1.029720078241656 | -| 2023-01-01T00:40:00Z | 1.0223606806499268 | -| 2023-01-01T00:50:00Z | 1.1680137850180072 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FLOOR() - -Returns the subsequent value rounded down to the nearest integer. - -```sql -FLOOR(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `FLOOR()` to a field" %}} - -```sql -SELECT - b, - FLOOR(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | floor | -| :------------------- | ------------------: | ----: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -1 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -1 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -1 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 1 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0 | - -{{% /expand %}} - -{{% expand "Apply `FLOOR()` to each field" %}} - -```sql -SELECT FLOOR(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | floor_a | floor_b | -| :------------------- | ------: | ------: | -| 2023-01-01T00:00:00Z | 0 | -1 | -| 2023-01-01T00:01:00Z | -1 | 0 | -| 2023-01-01T00:02:00Z | -1 | -1 | -| 2023-01-01T00:03:00Z | -1 | -1 | -| 2023-01-01T00:04:00Z | -1 | 1 | -| 2023-01-01T00:05:00Z | -1 | 0 | - -{{% /expand %}} - -{{% expand "Apply `FLOOR()` to time windows (grouped by time)" %}} - -```sql -SELECT - FLOOR(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | floor | -| :------------------- | ----: | -| 2023-01-01T00:00:00Z | -5 | -| 2023-01-01T00:10:00Z | 1 | -| 2023-01-01T00:20:00Z | 0 | -| 2023-01-01T00:30:00Z | 0 | -| 2023-01-01T00:40:00Z | 0 | -| 2023-01-01T00:50:00Z | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LN() - -Returns the natural logarithm of the field value. -Field values must be greater than or equal to 0. - -```sql -LN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LN()` to a field" %}} - -```sql -SELECT - b, - LN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | ln | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -1.98752355209665 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5758127783016702 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2995556920844895 | - -{{% /expand %}} - -{{% expand "Apply `LN()` to each field" %}} - -```sql -SELECT LN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ln_a | ln_b | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -1.0814865153308908 | | -| 2023-01-01T00:01:00Z | | -1.98752355209665 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.5758127783016702 | -| 2023-01-01T00:05:00Z | | -0.2995556920844895 | - -{{% /expand %}} - -{{% expand "Apply `LN()` to time windows (grouped by time)" %}} - -```sql -SELECT - LN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ln | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.25161504572793725 | -| 2023-01-01T00:20:00Z | -1.1983831026157092 | -| 2023-01-01T00:30:00Z | -1.2280265702380913 | -| 2023-01-01T00:40:00Z | -1.5089436474159283 | -| 2023-01-01T00:50:00Z | 0.4402187212890264 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG() - -Returns the logarithm of the field value with base `b`. -Field values must be greater than or equal to 0. - -```sql -LOG(field_expression, b) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **b**: Logarithm base to use in the operation. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG()` to a field with a base of 3" %}} - -```sql -SELECT - b, - LOG(b, 3) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -1.8091219009630797 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5241273780031629 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2726673414946528 | - -{{% /expand %}} - -{{% expand "Apply `LOG()` to each field with a base of 5" %}} - -```sql -SELECT LOG(*, 5) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log_a | log_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.6719653532302217 | | -| 2023-01-01T00:01:00Z | | -1.2349178161776593 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.3577725949246566 | -| 2023-01-01T00:05:00Z | | -0.18612441633827553 | - -{{% /expand %}} - -{{% expand "Apply `LOG()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG(SUM(a), 10) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.10927502592347751 | -| 2023-01-01T00:20:00Z | -0.5204511686721008 | -| 2023-01-01T00:30:00Z | -0.5333251630849791 | -| 2023-01-01T00:40:00Z | -0.6553258995757036 | -| 2023-01-01T00:50:00Z | 0.1911845614863297 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG2() - -Returns the logarithm of the field value to the base 2. -Field values must be greater than or equal to 0. - -```sql -LOG2(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG2()` to a field" %}} - -```sql -SELECT - b, - LOG2(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log2 | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -2.8673903722598544 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.8307222397363156 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.4321675114403543 | - -{{% /expand %}} - -{{% expand "Apply `LOG2()` to each field" %}} - -```sql -SELECT LOG2(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log2_a | log2_b | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | -1.560255232456162 | | -| 2023-01-01T00:01:00Z | | -2.8673903722598544 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.8307222397363156 | -| 2023-01-01T00:05:00Z | | -0.4321675114403543 | - -{{% /expand %}} - -{{% expand "Apply `LOG2()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG2(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log2 | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.36300377868474476 | -| 2023-01-01T00:20:00Z | -1.7289013592288134 | -| 2023-01-01T00:30:00Z | -1.7716678429623767 | -| 2023-01-01T00:40:00Z | -2.1769455171078644 | -| 2023-01-01T00:50:00Z | 0.6351013661101591 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG10() - -Returns the logarithm of the field value to the base 10. -Field values must be greater than or equal to 0. - -```sql -LOG10(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG10()` to a field" %}} - -```sql -SELECT - b, - LOG10(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log10 | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -0.8631705113283253 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.25007231222579585 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.1300953840950034 | - -{{% /expand %}} - -{{% expand "Apply `LOG10()` to each field" %}} - -```sql -SELECT LOG10(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log10_a | log10_b | -| :------------------- | -------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.46968362586098245 | | -| 2023-01-01T00:01:00Z | | -0.8631705113283253 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.25007231222579585 | -| 2023-01-01T00:05:00Z | | -0.1300953840950034 | - -{{% /expand %}} - -{{% expand "Apply `LOG10()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG10(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log10 | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.10927502592347751 | -| 2023-01-01T00:20:00Z | -0.520451168672101 | -| 2023-01-01T00:30:00Z | -0.5333251630849791 | -| 2023-01-01T00:40:00Z | -0.6553258995757036 | -| 2023-01-01T00:50:00Z | 0.19118456148632973 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MOVING_AVERAGE() - -Returns the rolling average across a window of subsequent [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). - -```sql -MOVING_AVERAGE(field_expression, N) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. -- **N**: Number of field values to use when calculating the moving average. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `MOVING_AVERAGE()` to a field" %}} - -```sql -SELECT MOVING_AVERAGE(a, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average | -| :------------------- | ------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to each field" %}} - -```sql -SELECT MOVING_AVERAGE(*, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average_a | moving_average_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to field keys that match a regular expression" %}} - -```sql -SELECT MOVING_AVERAGE(/[ab]/, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average_a | moving_average_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to time windows (grouped by time)" %}} - -```sql -SELECT - MOVING_AVERAGE(SUM(a), 3) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average | -| :------------------- | ------------------: | -| 2023-01-01T00:20:00Z | -0.9193144769987766 | -| 2023-01-01T00:30:00Z | 0.626884141339178 | -| 2023-01-01T00:40:00Z | 0.27189834404638374 | -| 2023-01-01T00:50:00Z | 0.6890200973149928 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## NON_NEGATIVE_DERIVATIVE() - -Returns only non-negative rate of change between subsequent -[field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). -Negative rates of change return _null_. - -```sql -NON_NEGATIVE_DERIVATIVE(field_expression[, unit]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **unit**: Unit of time to use to calculate the rate of change. - Supports [duration literals](/influxdb/cloud-dedicated/reference/influxql/#durations). - _Default is `1s` (per second)_. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [DERIVATIVE()](#derivative) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per second change" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | 0.03085914700123513 | -| 2023-01-01T00:08:00Z | 0.0227877053636946 | -| 2023-01-01T00:10:00Z | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | 0.014999637478226817 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per 5 minute change" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(b, 5m) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 1.5033871148979698 | -| 2023-01-01T00:03:00Z | 2.0498496425431316 | -| 2023-01-01T00:04:00Z | 9.257744100370537 | -| 2023-01-01T00:08:00Z | 6.836311609108379 | -| 2023-01-01T00:10:00Z | 0.5028191431616502 | -| 2023-01-01T00:11:00Z | 4.499891243468045 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to each field" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative_a | non_negative_derivative_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | | -| 2023-01-01T00:08:00Z | | 0.0227877053636946 | -| 2023-01-01T00:09:00Z | 0.018437240876186967 | | -| 2023-01-01T00:10:00Z | | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | | 0.014999637478226817 | -| 2023-01-01T00:13:00Z | 0.006694752202850366 | | -| 2023-01-01T00:14:00Z | 0.011836797386191167 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to field keys that match a regular expression" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative_a | non_negative_derivative_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | | -| 2023-01-01T00:08:00Z | | 0.0227877053636946 | -| 2023-01-01T00:09:00Z | 0.018437240876186967 | | -| 2023-01-01T00:10:00Z | | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | | 0.014999637478226817 | -| 2023-01-01T00:13:00Z | 0.006694752202850366 | | -| 2023-01-01T00:14:00Z | 0.011836797386191167 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to time windows (grouped by time)" %}} - -```sql -SELECT - NON_NEGATIVE_DERIVATIVE(MEAN(b), 1m) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:20:00Z | 0.010434324849926194 | -| 2023-01-01T00:40:00Z | 0.05657514203880348 | -| 2023-01-01T00:50:00Z | 0.021317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## NON_NEGATIVE_DIFFERENCE() - -Returns only non-negative result of subtraction between subsequent -[field values](/influxdb/cloud-dedicated/reference/glossary/#field-value). -Negative differences return _null_. - -```sql -NON_NEGATIVE_DIFFERENCE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [DIFFERENCE()](#difference) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to a field" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | 1.8515488200741077 | -| 2023-01-01T00:08:00Z | 1.367262321821676 | -| 2023-01-01T00:10:00Z | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | 0.899978248693609 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to each field" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference_a | non_negative_difference_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | | -| 2023-01-01T00:06:00Z | 1.002297066299117 | | -| 2023-01-01T00:08:00Z | | 1.367262321821676 | -| 2023-01-01T00:09:00Z | 1.106234452571218 | | -| 2023-01-01T00:10:00Z | | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | | 0.899978248693609 | -| 2023-01-01T00:13:00Z | 0.401685132171022 | | -| 2023-01-01T00:14:00Z | 0.71020784317147 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to field keys that match a regular expression" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference_a | non_negative_difference_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | | -| 2023-01-01T00:06:00Z | 1.002297066299117 | | -| 2023-01-01T00:08:00Z | | 1.367262321821676 | -| 2023-01-01T00:09:00Z | 1.106234452571218 | | -| 2023-01-01T00:10:00Z | | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | | 0.899978248693609 | -| 2023-01-01T00:13:00Z | 0.401685132171022 | | -| 2023-01-01T00:14:00Z | 0.71020784317147 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to time windows (grouped by time)" %}} - -```sql -SELECT - NON_NEGATIVE_DIFFERENCE(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference | -| :------------------- | ----------------------: | -| 2023-01-01T00:20:00Z | 0.10434324849926194 | -| 2023-01-01T00:40:00Z | 0.5657514203880348 | -| 2023-01-01T00:50:00Z | 0.21317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## POW() - -Returns the field value to the power of `x`. - -```sql -POW(field_expression, x) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **x**: Power to raise to. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `POW()` to a field with a power of 3" %}} - -```sql -SELECT - b, - POW(b, 3) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | pow | -| :------------------- | ------------------: | ---------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.004382205777325515 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.002573288422171338 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.1126388541916811 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0003885901893904874 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 5.626222933751733 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.4071119474284653 | - -{{% /expand %}} - -{{% expand "Apply `POW()` to each field with a power of 5" %}} - -```sql -SELECT POW(*, 5) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | pow_a | pow_b | -| :------------------- | -------------------: | -----------------------: | -| 2023-01-01T00:00:00Z | 0.004483135555212479 | -0.00011735131084020357 | -| 2023-01-01T00:01:00Z | -0.2795528536239978 | 0.000048322282876973225 | -| 2023-01-01T00:02:00Z | -0.6628050073932118 | -0.026271227986693114 | -| 2023-01-01T00:03:00Z | -0.22011853819169455 | -0.000002069282189962477 | -| 2023-01-01T00:04:00Z | -0.6103699296012646 | 17.797604890097084 | -| 2023-01-01T00:05:00Z | -0.5620694808926487 | 0.22362640363833164 | - -{{% /expand %}} - -{{% expand "Apply `POW()` to time windows (grouped by time)" %}} - -```sql -SELECT - POW(SUM(a), 10) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | pow | -| :------------------- | -----------------------: | -| 2023-01-01T00:00:00Z | 2402278.159218532 | -| 2023-01-01T00:10:00Z | 12.380844221267186 | -| 2023-01-01T00:20:00Z | 0.000006244365466732681 | -| 2023-01-01T00:30:00Z | 0.0000046424621235691315 | -| 2023-01-01T00:40:00Z | 2.7973126174031977e-7 | -| 2023-01-01T00:50:00Z | 81.6292140233699 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ROUND() - -Returns a field value rounded to the nearest integer. - -```sql -ROUND(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ROUND()` to a field" %}} - -```sql -SELECT - b, - ROUND(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | round | -| :------------------- | ------------------: | ----: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | - -{{% /expand %}} - -{{% expand "Apply `ROUND()` to each field" %}} - -```sql -SELECT ROUND(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | round_a | round_b | -| :------------------- | ------: | ------: | -| 2023-01-01T00:00:00Z | 0 | -0 | -| 2023-01-01T00:01:00Z | -1 | 0 | -| 2023-01-01T00:02:00Z | -1 | -0 | -| 2023-01-01T00:03:00Z | -1 | -0 | -| 2023-01-01T00:04:00Z | -1 | 2 | -| 2023-01-01T00:05:00Z | -1 | 1 | - -{{% /expand %}} - -{{% expand "Apply `ROUND()` to time windows (grouped by time)" %}} - -```sql -SELECT - ROUND(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | round | -| :------------------- | ----: | -| 2023-01-01T00:00:00Z | -4 | -| 2023-01-01T00:10:00Z | 1 | -| 2023-01-01T00:20:00Z | 0 | -| 2023-01-01T00:30:00Z | 0 | -| 2023-01-01T00:40:00Z | 0 | -| 2023-01-01T00:50:00Z | 2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SIN() - -Returns the sine of a field value. - -```sql -SIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `SIN()` to a field" %}} - -```sql -SELECT - b, - SIN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | sin | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.1629136686003898 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13660588515594851 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.4643877941052164 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0729085450859347 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.9784914502058565 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.6751348197618099 | - -{{% /expand %}} - -{{% expand "Apply `SIN()` to each field" %}} - -```sql -SELECT SIN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sin_a | sin_b | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.3326300722640741 | -0.1629136686003898 | -| 2023-01-01T00:01:00Z | -0.6997047077914582 | 0.13660588515594851 | -| 2023-01-01T00:02:00Z | -0.7962295291135749 | -0.4643877941052164 | -| 2023-01-01T00:03:00Z | -0.673406844448706 | -0.0729085450859347 | -| 2023-01-01T00:04:00Z | -0.7870301289278495 | 0.9784914502058565 | -| 2023-01-01T00:05:00Z | -0.7778043295686337 | 0.6751348197618099 | - -{{% /expand %}} - -{{% expand "Apply `SIN()` to time windows (grouped by time)" %}} - -```sql -SELECT - SIN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sin | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | 0.933528830283535 | -| 2023-01-01T00:10:00Z | 0.9597472276784815 | -| 2023-01-01T00:20:00Z | 0.29712628761434723 | -| 2023-01-01T00:30:00Z | 0.2887011711003489 | -| 2023-01-01T00:40:00Z | 0.21934537994884437 | -| 2023-01-01T00:50:00Z | 0.9998424824522808 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SQRT() - -Returns the square root of a field value. -Field values must be greater than or equal to 0. -Negative field values return null. - -```sql -SQRT(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `SQRT()` to a field" %}} - -```sql -SELECT - b, - SQRT(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | sqrt | -| :------------------- | ------------------: | -----------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.370181528515334 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 1.3336324558132349 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.860899207349059 | - -{{% /expand %}} - -{{% expand "Apply `SQRT()` to each field" %}} - -```sql -SELECT SQRT(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sqrt_a | sqrt_b | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.5823152811928947 | | -| 2023-01-01T00:01:00Z | | 0.370181528515334 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 1.3336324558132349 | -| 2023-01-01T00:05:00Z | | 0.860899207349059 | - -{{% /expand %}} - -{{% expand "Apply `SQRT()` to time windows (grouped by time)" %}} - -```sql -SELECT - SQRT(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sqrt | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 1.134063865909604 | -| 2023-01-01T00:20:00Z | 0.5492555015405052 | -| 2023-01-01T00:30:00Z | 0.5411746169982342 | -| 2023-01-01T00:40:00Z | 0.4702589287652642 | -| 2023-01-01T00:50:00Z | 1.2462130097934059 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## TAN() - -Returns the tangent of the field value. - -```sql -TAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `TAN()` to a field" %}} - -```sql -SELECT - b, - TAN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | tan | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.16511961248511045 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13789861917955581 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.5243575352718546 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.07310309943905952 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | -4.743341375725582 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.9151958486043346 | - -{{% /expand %}} - -{{% expand "Apply `TAN()` to each field" %}} - -```sql -SELECT TAN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | tan_a | tan_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.3527145610408791 | -0.16511961248511045 | -| 2023-01-01T00:01:00Z | -0.9793857830953787 | 0.13789861917955581 | -| 2023-01-01T00:02:00Z | -1.3160934857179802 | -0.5243575352718546 | -| 2023-01-01T00:03:00Z | -0.9109052733075013 | -0.07310309943905952 | -| 2023-01-01T00:04:00Z | -1.2757522322802637 | -4.743341375725582 | -| 2023-01-01T00:05:00Z | -1.2375438046768912 | 0.9151958486043346 | - -{{% /expand %}} - -{{% expand "Apply `TAN()` to time windows (grouped by time)" %}} - -```sql -SELECT - TAN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | tan | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | -2.603968631156288 | -| 2023-01-01T00:10:00Z | 3.4171098358131733 | -| 2023-01-01T00:20:00Z | 0.31117972731464494 | -| 2023-01-01T00:30:00Z | 0.30154101138968664 | -| 2023-01-01T00:40:00Z | 0.22482036866737865 | -| 2023-01-01T00:50:00Z | 56.3338223288096 | - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/reference/influxql/group-by.md b/content/influxdb/cloud-dedicated/reference/influxql/group-by.md index 3a2afc5d2..434f4b56e 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/group-by.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/group-by.md @@ -13,632 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_expression_n] ``` + +source: /shared/influxql-v3-reference/group-by.md --- - -Use the `GROUP BY` clause to group data by one or more specified -[tags](/influxdb/cloud-dedicated/reference/glossary/#tag) or into specified time intervals. -`GROUP BY` requires an [aggregate](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/) -or [selector](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/) -function in the `SELECT` statement. - - - -- [Syntax](#syntax) -- [GROUP BY clause behaviors](#group-by-clause-behaviors) -- [GROUP BY tags](#group-by-tags) - - [GROUP BY tags examples](#group-by-tags-examples) -- [GROUP BY time](#group-by-time) - - [GROUP by time and fill gaps](#group-by-time-and-fill-gaps) - - [GROUP BY time examples](#group-by-time-examples) - - [GROUP BY time with offset](#group-by-time-with-offset) - - [GROUP BY time and fill gaps](#group-by-time-and-fill-gaps) -- [Result set](#result-set) - - [Default time range](#default-time-range) -- [Notable behaviors of the GROUP BY clause](#notable-behaviors-of-the-group-by-clause) - - [Cannot group by fields](#cannot-group-by-fields) - - [Tag order does not matter](#tag-order-does-not-matter) - - [Grouping by tag and no time range returns unexpected timestamps](#grouping-by-tag-and-no-time-range-returns-unexpected-timestamps) - - [Data grouped by time may return unexpected timestamps](#data-grouped-by-time-may-return-unexpected-timestamps) - - [Example data](#example-data) - - [Query results](#query-results) - - [Fill with no data in the queried time range](#fill-with-no-data-in-the-queried-time-range) - - [Fill with previous if no previous value exists](#fill-with-previous-if-no-previous-value-exists) - - [Fill with linear interpolation if there are not two values to interpolate between](#fill-with-linear-interpolation-if-there-are-not-two-values-to-interpolate-between) - - - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_expression_n] -``` - -- **group_expression**: Expression to identify tags or time intervals to group by. - Can be a [tag key](/influxdb/cloud-dedicated/reference/glossary/#tag-key), - constant, [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/), - wildcard (`*`), or [function expression](/influxdb/cloud-dedicated/reference/influxql/functions/). - -## GROUP BY clause behaviors - -- `GROUP BY tag_key` - Groups data by a specific tag -- `GROUP BY tag_key1, tag_key2` - Groups data by more than one tag -- `GROUP BY *` - Groups data by all [tags](/influxdb/cloud-dedicated/reference/glossary/#tag) -- `GROUP BY /regex/` - Groups data by tag keys that match the regular expression -- `GROUP BY time()` - Groups data into time intervals (windows) - -{{% note %}} -If a query includes `WHERE` and `GROUP BY`, the `GROUP BY` clause must appear after -the `WHERE` clause. -{{% /note %}} - -## GROUP BY tags - -Groups data by one or more tag columns. - -### GROUP BY tags examples - -The following examples use the -[Bitcoin price sample data](/influxdb/cloud-dedicated/reference/sample-data/#bitcoin-price-data). - -{{< expand-wrapper >}} - -{{% expand "Group data by a single tag" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY code -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by more than one tag" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY code, description -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, description=Euro -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, description=British Pound Sterling -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, description=United States Dollar -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by all tags" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY * -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, crypto=bitcoin, description=Euro, symbol=€ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, crypto=bitcoin, description=British Pound Sterling, symbol=£ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, crypto=bitcoin, description=United States Dollar, symbol=$ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by tag keys that match a regular expression" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY /^[cd]/ -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, crypto=bitcoin, description=Euro -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, crypto=bitcoin, description=British Pound Sterling -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, crypto=bitcoin, description=United States Dollar -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{< /expand-wrapper >}} - -## GROUP BY time - -`GROUP BY time()` groups data by into specified time intervals, also known as "windows", -and applies the [aggregate](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/) -and [selector](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/) -functions in the `SELECT` clause to each interval. -Use the [`time()` function](/influxdb/cloud-dedicated/reference/influxql/functions/date-time/#time) -to specify the time interval to group by. - -```sql -SELECT_clause FROM_clause WHERE GROUP BY time(time_interval[, offset])[, group_expression (...)] [fill(behavior)] -``` - -`GROUP BY time()` intervals use preset round-number time boundaries that -are independent of time conditions in the [`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/). -**Output data uses window start boundaries as the aggregate timestamps.** -Use the `offset` argument of the `time()` function to shift time boundaries forward or -backward in time. - -### GROUP by time and fill gaps - -When grouping by time, if a window in the queried time range does not contain data, -results return a row for the empty window containing the timestamp of the empty -window and _null_ values for each queried field. -Use the [`fill()` function](/influxdb/cloud-dedicated/reference/influxql/functions/misc/#fill) -_at the end of the `GROUP BY` clause_ to replace _null_ field values. -If no `FILL` clause is included, the default behavior is `fill(null)`. - -`fill()` provides the following behaviors for filling values: - -- **numeric literal**: Replaces null values with the specified numeric literal. -- **linear**: Uses linear interpolation between existing values to replace null values. -- **none**: Removes rows with null field values. -- **null**: Keeps null values and associated timestamps. -- **previous**: Replaces null values with the most recent non-null value. - -_See the [`fill()` documentation](/influxdb/cloud-dedicated/reference/influxql/functions/misc/#fill) -for detailed examples._ - -### GROUP BY time examples - -The following examples use the -[Bitcoin price sample data](/influxdb/cloud-dedicated/reference/sample-data/#bitcoin-price-data). - -{{< expand-wrapper >}} - -{{% expand "Group and aggregate query results into 1 hour windows" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(1h) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-05-01T00:00:00Z | 24494.27265 | -| 2023-05-01T01:00:00Z | 24452.1698 | -| 2023-05-01T02:00:00Z | 23902.666124999996 | -| 2023-05-01T03:00:00Z | 23875.211349999998 | -| 2023-05-01T04:00:00Z | 23855.6441 | -| ... | ... | - - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 1 week intervals by tag" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(1w), code -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 27681.21808576779 | -| 2023-05-04T00:00:00Z | 27829.413580354256 | -| 2023-05-11T00:00:00Z | 26210.24799033149 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 23744.083925842704 | -| 2023-05-04T00:00:00Z | 23871.201395652173 | -| 2023-05-11T00:00:00Z | 22482.33174723755 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 28415.88231123595 | -| 2023-05-04T00:00:00Z | 28568.010941384844 | -| 2023-05-11T00:00:00Z | 26905.87242099449 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -###### GROUP BY time with offset - -{{< expand-wrapper >}} -{{% expand "Group and aggregate query results into 1 hour intervals and offset time boundaries by +15 minutes" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-02T00:00:00Z' -GROUP BY time(1h, 15m) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-30T23:15:00Z | | -| 2023-05-01T00:15:00Z | 29313.6754 | -| 2023-05-01T01:15:00Z | 28932.0882 | -| 2023-05-01T02:15:00Z | 28596.375225000003 | -| 2023-05-01T03:15:00Z | 28578.915075 | -| ... | ... | - -_Note that `offset` forces the first time boundary to be outside -the queried time range so the query returns no results for that first interval._ - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 1 hour intervals and offset time boundaries by -15 minutes" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-02T00:00:00Z' -GROUP BY time(1h, -15m) -``` -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-30T23:45:00Z | 29319.9092 | -| 2023-05-01T00:45:00Z | 29285.3651 | -| 2023-05-01T01:45:00Z | 28607.202666666668 | -| 2023-05-01T02:45:00Z | 28576.056175 | -| 2023-05-01T03:45:00Z | 28566.96315 | -| ... | ... | - -{{% /expand %}} -{{< /expand-wrapper >}} - -###### GROUP BY time and fill gaps - -{{< expand-wrapper >}} -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps with `0`" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(0) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 0 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps using linear interpolation" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(linear) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29285.3651 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps with previous values" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(previous) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{< /expand-wrapper >}} - -## Result set - -If at least one row satisfies the query, {{% product-name %}} returns row data in the query result set. -If a query uses a `GROUP BY` clause, the result set includes the following: - -- Columns listed in the query's `SELECT` clause -- A `time` column that contains the timestamp for the record or the group -- An `iox::measurement` column that contains the record's measurement (table) name -- Columns listed in the query's `GROUP BY` clause; each row in the result set contains the values used for grouping - -### Default time range - -If a query doesn't specify a time range in the -[`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/), InfluxDB uses the -[default time range](/influxdb/cloud-dedicated/reference/influxql/#default-time-range) for filtering and grouping by time. -If a query includes the `GROUP BY` clause and doesn't specify a time range in the -`WHERE` clause, the default time group is the -[default time range](/influxdb/cloud-dedicated/reference/influxql/#default-time-range), and the `time` column in the result set contains the start of the range--for example: - -```sql -SELECT mean(temp) FROM home GROUP BY room -``` - -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 22.623076923076926 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ----------------: | -| 1970-01-01T00:00:00Z | 22.16923076923077 | - -## Notable behaviors of the GROUP BY clause - -### Cannot group by fields - -InfluxQL does not support grouping data by **fields**. - -### Tag order does not matter - -The order that tags are listed in the `GROUP BY` clause does not affect how -data is grouped. - -### Grouping by tag and no time range returns unexpected timestamps - -The `time` column contains the start of the [default time range](#default-time-range). - -### Data grouped by time may return unexpected timestamps - -Because `GROUP BY time()` intervals use preset round-number time boundaries that -are independent of time conditions in the [`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/), -results may include timestamps outside of the queried time range. -Results represent only data with timestamps in the specified time range, but -output timestamps are determined by by the preset time boundaries. - -The following example groups data by 1-hour intervals, but the time range defined -in the `WHERE` clause covers only part of a window: - -```sql -SELECT MEAN(field) -FROM example -WHERE - time >= '2022-01-01T00:30:00Z' - AND time <= '2022-01-01T01:30:00Z' -GROUP BY time(1h) -``` - -{{% note %}} -**Note**: The timestamp in the first row of query results data occurs before the start of -the queried time range. -[See why](#why-do-these-results-include-timestamps-outside-of-the-queried-time-range). -{{% /note %}} - -{{% influxdb/custom-timestamps %}} -{{< flex >}} -{{% flex-content %}} -#### Example data - -| time | field | -| :------------------- | ----: | -| 2022-01-01T00:00:00Z | 8 | -| 2022-01-01T00:15:00Z | 4 | -| 2022-01-01T00:30:00Z | 0 | -| 2022-01-01T00:45:00Z | 8 | -| 2022-01-01T01:00:00Z | 5 | -| 2022-01-01T01:15:00Z | 0 | -| 2022-01-01T01:30:00Z | 8 | -| 2022-01-01T01:45:00Z | 8 | -| 2022-01-01T02:00:00Z | 9 | -| 2022-01-01T02:15:00Z | 6 | -| 2022-01-01T02:30:00Z | 3 | -| 2022-01-01T02:45:00Z | 0 | - -{{% /flex-content %}} -{{% flex-content %}} - -#### Query results - -| time | field | -| :------------------- | ----: | -| 2022-01-01T00:00:00Z | 4 | -| 2022-01-01T01:00:00Z | 5.25 | -| 2022-01-01T02:00:00Z | 6 | - -{{% /flex-content %}} -{{< /flex >}} -{{% /influxdb/custom-timestamps %}} - -{{< expand-wrapper >}} -{{% expand "Why do these results include timestamps outside of the queried time range?" %}} - -`GROUP BY time()` creates windows with predefined time boundaries based on the -specified interval. These boundaries are not determined by the queried time -range, however, aggregate values in query results are calculated using only -values that are in the queried time range. - -{{< html-diagram/influxql-windows >}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Fill with no data in the queried time range - -Queries ignore `fill()` if no data exists in the queried time range. -This is the expected behavior. - -### Fill with previous if no previous value exists - -`fill(previous)` doesn’t fill null values if there is no previous value in -the queried time range. - -### Fill with linear interpolation if there are not two values to interpolate between - -`fill(linear)` doesn't fill null values if there are no values before or after -the null value in the queried time range. diff --git a/content/influxdb/cloud-dedicated/reference/influxql/internals.md b/content/influxdb/cloud-dedicated/reference/influxql/internals.md index 657f6b28c..44d07a93a 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/internals.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/internals.md @@ -6,159 +6,6 @@ menu: name: InfluxQL internals parent: influxql-reference weight: 219 + +source: /shared/influxql-v3-reference/internals.md --- - -Learn about the implementation of InfluxQL to understand how -results are processed and how to create efficient queries: - -- [Query life cycle](#query-life-cycle) -- [Understanding iterators](#understanding-iterators) -- [Cursors](#cursors) -- [Auxiliary fields](#auxiliary-fields) -- [Built-in iterators](#built-in-iterators) -- [Call iterators](#call-iterators) - -## Query life cycle - -1. InfluxQL query string is tokenized and then parsed into an abstract syntax - tree (AST). This is the code representation of the query itself. - -2. The AST is passed to the `QueryExecutor` which directs queries to the - appropriate handlers. For example, queries related to meta data are executed - by the **meta service** and `SELECT` statements are executed by the shards - themselves. - -3. The query engine then determines the shards that match the `SELECT` - statement's time range. From these shards, iterators are created for each - field in the statement. - -4. Iterators are passed to the emitter which drains them and joins the resulting - points. The emitter's job is to convert simple time/value points into the - more complex result objects that are returned to the client. - -### Understanding iterators - -Iterators provide a simple interface for looping over a set of points. -For example, this is an iterator over Float points: - -``` -type FloatIterator interface { - Next() *FloatPoint -} -``` - -These iterators are created through the `IteratorCreator` interface: - -``` -type IteratorCreator interface { - CreateIterator(opt *IteratorOptions) (Iterator, error) -} -``` - -The `IteratorOptions` provide arguments about field selection, time ranges, -and dimensions that the iterator creator can use when planning an iterator. -The `IteratorCreator` interface is used at many levels such as the `Shards`, -`Shard`, and `Engine`. This allows optimizations to be performed when applicable -such as returning a precomputed `COUNT()`. - -Iterators aren't just for reading raw data from storage, though. Iterators can be -composed so that they provide additional functionality around an input -iterator. For example, a `DistinctIterator` can compute the distinct values for -each time window for an input iterator. Or a `FillIterator` can generate -additional points that are missing from an input iterator. - -This composition also lends itself well to aggregation. -For example, in the following SQL, `MEAN(value)` is a `MeanIterator` that wraps an iterator from the -underlying shards: - -```sql -SELECT MEAN(value) FROM cpu GROUP BY time(10m) -``` - -The following example wraps `MEAN(value)` with an additional iterator (`DERIVATIVE()`) to determine -the derivative of the mean: - -```sql -SELECT DERIVATIVE(MEAN(value), 20m) FROM cpu GROUP BY time(10m) -``` - -### Cursors - -A **cursor** identifies data by shard in tuples (time, value) for a single series (measurement, tag set and field). The cursor traverses data stored as a log-structured merge-tree and handles deduplication across levels, tombstones for deleted data, and merging the cache (Write Ahead Log). A cursor sorts the `(time, value)` tuples by time in ascending or descending order. - -For example, a query that evaluates one field for 1,000 series over 3 shards constructs a minimum of 3,000 cursors (1,000 per shard). - -### Auxiliary fields - -Because InfluxQL allows users to use selector functions such as `FIRST()`, -`LAST()`, `MIN()`, and `MAX()`, the engine must provide a way to return related -data at the same time with the selected point. - -Let's look at the following query: - -```sql -SELECT FIRST(value), host FROM cpu GROUP BY time(1h) -``` - -We are selecting the first `value` that occurs every hour but we also want to -retrieve the `host` associated with that point. Since the `Point` types only -specify a single typed `Value` for efficiency, we push the `host` into the -auxiliary fields of the point. These auxiliary fields are attached to the point -until it is passed to the emitter where the fields get split off to their own -iterator. - -### Built-in iterators - -There are many helper iterators that let us build queries: - -* Merge Iterator - This iterator combines one or more iterators into a single - new iterator of the same type. This iterator guarantees that all points - within a window will be output before starting the next window, but does not - provide ordering guarantees within the window. This allows for fast access - for aggregate queries that don't need stronger sorting guarantees. - -* Sorted Merge Iterator - Like `MergeIterator`, this iterator combines one or more iterators - into a new iterator of the same type. However, this iterator guarantees - time ordering of every point. This makes it slower than the `MergeIterator` - but this ordering guarantee is required for non-aggregate queries which - return the raw data points. - -* Limit Iterator - This iterator limits the number of points per name or tag - group. This is the implementation of the `LIMIT` & `OFFSET` syntax. - -* Fill Iterator - This iterator injects extra points if they are missing from - the input iterator. It can provide `null` points, points with the previous - value, or points with a specific value. - -* Buffered Iterator - This iterator provides the ability to "unread" a point - back onto a buffer so it can be read again next time. This is used extensively - to provide lookahead for windowing. - -* Reduce Iterator - This iterator calls a reduction function for each point in - a window. When the window is complete, then all points for that window are - output. This is used for simple aggregate functions such as `COUNT()`. - -* Reduce Slice Iterator - This iterator collects all points for a window first, - and then passes them all to a reduction function at once. The results are - returned from the iterator. This is used for aggregate functions such as - `DERIVATIVE()`. - -* Transform Iterator - This iterator calls a transform function for each point - from an input iterator. This is used for executing binary expressions. - -* Dedupe Iterator - This iterator only outputs unique points. Because it is resource-intensive, this iterator is only used for small queries such as meta query statements. - -### Call iterators - -Function calls in InfluxQL are implemented at two levels: - -- Some calls can be -wrapped at multiple layers to improve efficiency. For example, a `COUNT()` can -be performed at the shard level and then multiple `CountIterator`s can be -wrapped with another `CountIterator` to compute the count of all shards. These -iterators can be created using `NewCallIterator()`. - -- Some iterators are more complex or need to be implemented at a higher level. -For example, the `DERIVATIVE()` function needs to retrieve all points for a window -before performing the calculation. This iterator is created by the engine itself -and is never requested to be created by the lower levels. diff --git a/content/influxdb/cloud-dedicated/reference/influxql/limit-and-slimit.md b/content/influxdb/cloud-dedicated/reference/influxql/limit-and-slimit.md index 97acae6c5..dac4b5e15 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/limit-and-slimit.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/limit-and-slimit.md @@ -13,249 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT row_N SLIMIT series_N ``` + +source: /shared/influxql-v3-reference/limit-and-slimit.md --- - -Use `LIMIT` to limit the number of **rows** returned per InfluxQL group. -Use `SLIMIT` to limit the number of [series](/influxdb/cloud-dedicated/reference/glossary/#series) -returned in query results. - -- [LIMIT clause](#limit-clause) - - [Syntax](#limit-syntax) - - [Examples](#limit-examples) -- [SLIMIT clause](#slimit-clause) - - - - - - -## LIMIT clause - -The `LIMIT` clause limits the number of rows to return from each InfluxQL group. -If the query doesn't include a [`GROUP BY` clause](/influxdb/cloud-dedicated/reference/influxql/group-by/), -the entire result set is considered a single group. -If a query [groups data by time](/influxdb/cloud-dedicated/reference/influxql/group-by/#group-by-time), -limits are applied after aggregate and selector operations are applied to each -time window. - -### Syntax {#limit-syntax} - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT N -``` - -#### Arguments - -- **N**: Maximum number of points to return from each InfluxQL group. - If `N` is greater than the number of points in a group, - all points from the group are returned. - -### Examples {#limit-examples} - -The following examples use the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Limit the number of rows returned" %}} - -```sql -SELECT * FROM home LIMIT 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Limit the number of rows returned from each InfluxQL group" %}} - -```sql -SELECT - MEAN(*) -FROM home -GROUP BY - time(2h), - room -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ------: | -------: | -----------------: | -| 2022-01-01T08:00:00Z | 0 | 36.05 | 22 | -| 2022-01-01T10:00:00Z | 0 | 36.05 | 22.549999999999997 | -| 2022-01-01T12:00:00Z | 0.5 | 36.25 | 22.65 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ------: | -------: | -----------------: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21.25 | -| 2022-01-01T10:00:00Z | 0 | 36 | 22 | -| 2022-01-01T12:00:00Z | 0 | 35.95 | 22.299999999999997 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## SLIMIT clause - -{{% warn %}} -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features, such as `SLIMIT` are still -being implemented. For more information, see -[InfluxQL feature support](/influxdb/cloud-dedicated/reference/influxql/feature-support/). -{{% /warn %}} - - diff --git a/content/influxdb/cloud-dedicated/reference/influxql/math-operators.md b/content/influxdb/cloud-dedicated/reference/influxql/math-operators.md index 2441b3724..f295eea6e 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/math-operators.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/math-operators.md @@ -9,273 +9,6 @@ menu: parent: influxql-reference identifier: influxql-mathematical-operators weight: 215 + +source: /shared/influxql-v3-reference/math-operators.md --- - -Use InfluxQL mathematical operators to perform mathematical operations in InfluxQL queries. -Mathematical operators follow the [standard order of operations](https://golang.org/ref/spec#Operator_precedence). -Parentheses take precedence to division and multiplication, which takes precedence to addition and subtraction. -For example `5 / 2 + 3 * 2 = (5 / 2) + (3 * 2)` and `5 + 2 * 3 - 2 = 5 + (2 * 3) - 2`. - -- [Addition](#addition) -- [Subtraction](#subtraction) -- [Multiplication](#multiplication) -- [Division](#division) -- [Modulo](#modulo) -- [Bitwise AND](#bitwise-and) -- [Bitwise OR](#bitwise-or) -- [Bitwise Exclusive-OR](#bitwise-exclusive-or) -- [Unsupported Operators](#unsupported-operators) -- [Notable behaviors of mathematical operators](#notable-behaviors-of-mathematical-operators) - -## Addition - -Add two numeric operands. Operands may be an identifier, constant, or literal -numeric value. - -```sql -SELECT A + 5 FROM example - -SELECT A + B FROM example - -SELECT * FROM example WHERE A + 5 > 10 - -SELECT * FROM example WHERE A + B > 10 -``` - -## Subtraction - -Subtract one numeric operand from another. Operands may be an identifier, -constant, or literal numeric value. - -```sql -SELECT 1 - A FROM example - -SELECT B - A FROM example - -SELECT * FROM example WHERE 1 - A <= 3 - -SELECT * FROM example WHERE B - A <= 3 -``` - -## Multiplication - -Multiply two numeric operands. Operands may be an identifier, constant, or literal -numeric value. - -```sql -SELECT A * 10 FROM example - -SELECT A * B FROM example - -SELECT * FROM example WHERE A * 10 >= 20 - -SELECT * FROM example WHERE A * B >= 20 -``` - -Multiplication distributes across other operators. - -```sql -SELECT 10 * (A + B + C) FROM example - -SELECT 10 * (A - B - C) FROM example - -SELECT 10 * (A + B - C) FROM example -``` - -## Division - -Divide one numeric operand by another. Operands may be an identifier, constant, -or literal numeric value. - -```sql -SELECT A / 10 FROM example - -SELECT A / B FROM example - -SELECT * FROM example WHERE A / 10 <= 2 - -SELECT * FROM example WHERE A / B <= 2 -``` - -Division distributes across other operators. - -```sql -SELECT 10 / (A + B + C) FROM example - -SELECT 10 / (A - B - C) FROM example - -SELECT 10 / (A + B - C) FROM example -``` - -## Modulo - -Perform a modulo operation with two numeric operands. Operands may be an -identifier, constant, or literal numeric value. - -```sql -SELECT A % 2 FROM example - -SELECT A % B FROM example - -SELECT A FROM example WHERE A % 2 = 0 - -SELECT A, B FROM example WHERE A % B = 0 -``` - -## Bitwise AND - -Perform a bitwise `AND` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A & 255 FROM example - -SELECT A & B FROM example - -SELECT (A ^ true) & B FROM example - -SELECT * FROM example WHERE A & 15 > 0 -``` - -## Bitwise OR - -Perform a bitwise `OR` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A | 5 FROM example - -SELECT A | B FROM example - -SELECT * FROM example WHERE "bitfield" | 12 = 12 -``` - -## Bitwise Exclusive-OR - -Perform a bitwise `Exclusive-OR` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A ^ 255 FROM example - -SELECT A ^ B FROM example - -SELECT * FROM example WHERE "bitfield" ^ 6 > 0 -``` - -## Unsupported Operators - -### Inequalities - -Using any of `=`,`!=`,`<`,`>`,`<=`,`>=`,`<>` in the `SELECT` statement yields -empty results for all types. -Comparison operators can only be used in the `WHERE` clause. - -### Logical Operators - -Using any of `!|`,`NAND`,`XOR`,`NOR` yield a parser error. - -Additionally using `AND`, `OR` in the `SELECT` clause of a query will not behave -as mathematical operators and simply yield empty results, as they are InfluxQL tokens. -However, you can apply the bitwise operators `&`, `|` and `^` to boolean values. - -### Bitwise Not - -There is no bitwise-not operator, because the results you expect depend on the width of your bitfield. -InfluxQL does not know how wide your bitfield is, so cannot implement a suitable -bitwise-not operator. - -For example, if your bitfield is 8 bits wide, then the integer 1 represents the bits `0000 0001`. -The bitwise-not of this should return the bits `1111 1110` (that is, the integer 254) -However, if your bitfield is 16 bits wide, then the integer 1 represents the bits `0000 0000 0000 0001`. -The bitwise-not of this should return the bits `1111 1111 1111 1110` (that is, the integer 65534) - -#### Solution - -You can implement a bitwise-not operation by using the `^` (bitwise xor) operator -together with the number representing all-ones for your word-width: - -For 8-bit data: - -```sql -SELECT A ^ 255 FROM example -``` - -For 16-bit data: - -```sql -SELECT A ^ 65535 FROM example -``` - -For 32-bit data: - -```sql -SELECT A ^ 4294967295 FROM example -``` - -In each case, the constant you need can be calculated as `(2 ** width) - 1`. - -## Notable behaviors of mathematical operators - -- [Mathematical operators with wildcards and regular expressions](#mathematical-operators-with-wildcards-and-regular-expressions) -- [Mathematical operators with functions](#mathematical-operators-with-functions) - -### Mathematical operators with wildcards and regular expressions - -InfluxQL does not support combining mathematical operations with a wildcard (`*`) -or [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/) -in the `SELECT` clause. -The following queries are invalid and the output is an error: - -Perform a mathematical operation on a wildcard. - -```sql -SELECT * + 2 FROM "nope" --- ERR: unsupported expression with wildcard: * + 2 -``` - -Perform a mathematical operation on a wildcard within a function. - -```sql -SELECT COUNT(*) / 2 FROM "nope" --- ERR: unsupported expression with wildcard: count(*) / 2 -``` - -Perform a mathematical operation on a regular expression. - -```sql -SELECT /A/ + 2 FROM "nope" --- ERR: error parsing query: found +, expected FROM at line 1, char 12 -``` - -Perform a mathematical operation on a regular expression within a function. - -```sql -SELECT COUNT(/A/) + 2 FROM "nope" --- ERR: unsupported expression with regex field: count(/A/) + 2 -``` - -### Mathematical operators with functions - -InfluxQL does not support mathematical operators inside of function calls. -Note that InfluxQL only allows functions in the `SELECT` clause. - -For example, the following will work: - -```sql -SELECT 10 * mean("value") FROM "cpu" -``` - -However, the following query will return a parse error: - -```sql -SELECT mean(10 * "value") FROM "cpu" --- Error: expected field argument in mean() -``` - - diff --git a/content/influxdb/cloud-dedicated/reference/influxql/offset-and-soffset.md b/content/influxdb/cloud-dedicated/reference/influxql/offset-and-soffset.md index ee4462a88..2d4080ee9 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/offset-and-soffset.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/offset-and-soffset.md @@ -14,236 +14,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] OFFSET row_N [SLIMIT_clause] SOFFSET series_N ``` + +source: /shared/influxql-v3-reference/offset-and-soffset.md --- - -Use `OFFSET` to specify the number of [rows](/influxdb/cloud-dedicated/reference/glossary/#series) -to skip in each InfluxQL group before returning results. -Use `SOFFSET` to specify the number of [series](/influxdb/cloud-dedicated/reference/glossary/#series) -to skip before returning results. - - - [OFFSET clause](#offset-clause) - - [Syntax](#offset-syntax) - - [Notable OFFSET clause behaviors](#notable-offset-clause-behaviors) - - [Examples](#offset-examples) - - [SOFFSET clause](#soffset-clause) - - - - -## `OFFSET` clause - -The `OFFSET` clause skips `N` rows in each InfluxQL group before returning results. -Offsets honor row limits specified in the -[`LIMIT` clause](/influxdb/cloud-dedicated/reference/influxql/limit-and-slimit/#limit-clause) -and display the limited number of rows after the specified offset. -Use `LIMIT` and `OFFSET` together to paginate query results. - -### Syntax {#offset-syntax} - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] OFFSET N [SLIMIT_clause] [SOFFSET_clause] -``` - -#### Arguments - -- **N**: Number of rows to skip in each InfluxQL group before returning results. - -### Notable OFFSET clause behaviors - -- If there is no `LIMIT` clause in a query with an `OFFSET` clause, the query - returns a single row per InfluxQL group at the specified offset. -- If the query doesn't include a [`GROUP BY` clause](/influxdb/cloud-dedicated/reference/influxql/group-by/), - the entire result set is considered a single group and is returned in full. -- If a query [groups data by time](/influxdb/cloud-dedicated/reference/influxql/group-by/#group-by-time), - the offset is applied after aggregate and selector operations are applied to each - time window. -- If the [`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/) - includes a time range and the `OFFSET` clause causes InfluxQL to return points - with timestamps outside of that time range, InfluxQL returns no results. - -### Examples {#offset-examples} - -The following examples use the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Return the nth row" %}} - -```sql -SELECT * FROM home OFFSET 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Paginate results by 3 and return the 2nd page of results" %}} - -```sql -SELECT * FROM home WHERE room = 'Kitchen' LIMIT 3 OFFSET 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Paginate results from each series by 3 and return the 2nd page of each series" %}} - -```sql -SELECT * FROM home GROUP BY * LIMIT 3 OFFSET 3 -``` - -{{% influxdb/custom-timestamps %}} - -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | 22.5 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | 22.8 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | 22.2 | -| 2022-01-01T12:00:00Z | 0 | 35.9 | 22.2 | -| 2022-01-01T13:00:00Z | 0 | 36 | 22.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## `SOFFSET` clause - -{{% warn %}} -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features, such as `SOFFSET` are still -being implemented. For more information, see -[InfluxQL feature support](/influxdb/cloud-dedicated/reference/influxql/feature-support/). -{{% /warn %}} - - diff --git a/content/influxdb/cloud-dedicated/reference/influxql/order-by.md b/content/influxdb/cloud-dedicated/reference/influxql/order-by.md index c4c5bc3cc..68f56d5af 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/order-by.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/order-by.md @@ -13,97 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [DESC|ASC] ``` + +source: /shared/influxql-v3-reference/order-by.md --- - -Use the `ORDER BY` clause to sort data by time in ascending or descending order. -InfluxQL only supports sorting data by `time`. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [ASC|DESC] -``` - -- If the the `ORDER BY` clause is not included, the default behavior is to sort data by - time in **ascending** order: `ORDER BY time ASC`. -- If the query includes [`WHERE`](/influxdb/cloud-dedicated/reference/influxql/where/) - and [`GROUP BY`](/influxdb/cloud-dedicated/reference/influxql/group-by/) clauses, - the `ORDER BY` clause must come **after** these clauses. - -#### Sort orders - -- **ASC (ascending)**: The first row in the results has the oldest timestamp. - The last row in the results has the most recent timestamp. -- **DESC (descending)**: The first row in the results has the most recent timestamp. - The last row in the results has the oldest timestamp. - -## Examples - -The following examples use the -[Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Sort data with the oldest points first" %}} - -{{% note %}} -Ordering data by time in ascending order is the default behavior. -Including `ORDER BY time ASC` in the query isn't necessary, but it is supported. -{{% /note %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -ORDER BY time ASC -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Sort data with the newest points first" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -ORDER BY time DESC -``` - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/reference/influxql/quoting.md b/content/influxdb/cloud-dedicated/reference/influxql/quoting.md index ea6da0163..20836dd2b 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/quoting.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/quoting.md @@ -17,48 +17,6 @@ list_code_example: | -- Quoted identifier "this-is-an-identifier" ``` + +source: /shared/influxql-v3-reference/quoting.md --- - -InfluxQL supports both single and double quotation marks, but they each function -differently and serve different purposes. - -- [Single quotes](#single-quotes) -- [Double quotes](#double-quotes) - -## Single quotes - -Use single quotation marks (`'`) in the -[string literal](/influxdb/cloud-dedicated/reference/influxql/#strings) and -[timestamp literal](/influxdb/cloud-dedicated/reference/influxql/#dates--times) syntax. - -In the following example, the `WHERE` clause evaluates the value of the `room` tag. -Tags only contain string values, so the right operand of the predicate expression -should be a string literal. - -```sql -... WHERE room = 'Kitchen' -``` - -## Double quotes - -Use double quotation marks (`"`) to quote [identifiers](/influxdb/cloud-dedicated/reference/influxql/#identifiers). -Identifiers **must** be double-quoted in the following cases: - -- The identifier contains non-word characters. - Word characters are defined as `[a-z,A-Z,0-9,_]`. -- The identifier is case-sensitive. -- The identifier contains [InfluxQL keywords](/influxdb/cloud-dedicated/reference/influxql/#keywords). -- The identifier begins with a digit. - -Double-quoted identifiers can also: - -- Contain any Unicode character except for a new line. -- Contain escaped `"` characters (for example: `\"`). -- Include [InfluxQL keywords](/influxdb/cloud-dedicated/reference/influxql/#keywords). - -**While not always necessary, we recommend that you double quote identifiers.** - -{{% note %}} -InfluxQL quoting guidelines differ from -[line protocol quoting guidelines](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#quotes). -{{% /note %}} \ No newline at end of file diff --git a/content/influxdb/cloud-dedicated/reference/influxql/regular-expressions.md b/content/influxdb/cloud-dedicated/reference/influxql/regular-expressions.md index 20b8f2177..e80a00a16 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/regular-expressions.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/regular-expressions.md @@ -13,198 +13,6 @@ list_code_example: | ```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` + +source: /shared/influxql-v3-reference/regular-expressions.md --- - -Regular expressions are a sequence of characters used to identify patterns in -identifiers and string values. -InfluxQL supports regular expressions in the following operations: - -- Identifying **fields** and **tags** to query in the - [`SELECT` clause](/influxdb/cloud-dedicated/reference/influxql/select/). -- Identifying **measurements** to query in the - [`FROM` clause](/influxdb/cloud-dedicated/reference/influxql/select/#from-clause). -- Testing **tag values** and **string field values** in the - [`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/). -- Identifying **tag keys** to group by in the - [`GROUP BY` clause](/influxdb/cloud-dedicated/reference/influxql/group-by/) - -{{% note %}} -#### Query performance - -Regular expression comparisons are more computationally intensive than exact -string comparisons. Queries with regular expressions are not as performant -as those without. -{{% /note %}} - -## Regular expression syntax - -InfluxQL Regular expressions are surrounded by `/` characters and use the -[Go regular expression syntax](http://golang.org/pkg/regexp/syntax/). - -```sql -/regular_expression/ -``` - -### Regular expression flags - -Regular expression flags modify the pattern-matching behavior of the expression. -InfluxQL supports the following regular expression flags: - -| Flag | Description | -| :--- | :------------------------------------------------------------------------------ | -| i | case-insensitive | -| m | multi-line mode: `^` and `$` match begin/end line in addition to begin/end text | -| s | let `.` match `\n` | -| U | ungreedy: swap meaning of `x*` and `x*?`, `x+` and `x+?`, etc. | - -Include regular expression flags at the beginning of your regular expression -pattern enclosed in parentheses (`()`) and preceded by a question mark (`?`). - -```sql -/(?iU)foo*/ -``` - -## Regular expression operators - -InfluxQL provides the following regular expression operators that test if a -string operand matches a regular expression: - -- `=~`: Returns true if the string matches the regular expression -- `!~`: Returns true if the string does not match the regular expression - -InfluxQL regular expression operators are used to test string column values in -the [`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/). - -## Regular expression examples - -The examples below use the following sample data sets: - -- [NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data) -- [Get started home sensor data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data) - -{{< expand-wrapper >}} - -{{% expand "Use a regular expression to specify field keys and tag keys in the SELECT clause" %}} - -```sql -SELECT /^t/ FROM weather -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | temp_avg | temp_max | temp_min | -| :------------------- | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | 52 | 66 | 44 | -| 2020-01-01T00:00:00Z | 53 | 59 | 47 | -| 2020-01-01T00:00:00Z | 50 | 57 | 44 | -| 2020-01-02T00:00:00Z | 54 | 61 | 49 | -| 2020-01-02T00:00:00Z | 51 | 60 | 44 | -| 2020-01-02T00:00:00Z | 53 | 66 | 42 | -| ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify measurements in the FROM clause" %}} - -```sql -SELECT /^t/ FROM /^[hw]/ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | temp | temp_avg | temp_max | temp_min | -| :------------------- | ---: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | | 52 | 66 | 44 | -| 2020-01-01T00:00:00Z | | 53 | 59 | 47 | -| 2020-01-01T00:00:00Z | | 50 | 57 | 44 | -| 2020-01-02T00:00:00Z | | 54 | 61 | 49 | -| 2020-01-02T00:00:00Z | | 51 | 60 | 44 | -| 2020-01-02T00:00:00Z | | 53 | 66 | 42 | -| ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify tag values in the WHERE clause" %}} - -```sql -SELECT * FROM weather WHERE location !~ /^[S]/ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | location | precip | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | :------- | -----: | -------: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | Concord | 0 | 52 | 66 | 44 | 3.13 | -| 2020-01-01T00:00:00Z | Hayward | 0 | 50 | 57 | 44 | 2.24 | -| 2020-01-02T00:00:00Z | Concord | 0 | 53 | 66 | 42 | 3.13 | -| 2020-01-02T00:00:00Z | Hayward | 0 | 51 | 60 | 44 | 3.8 | -| 2020-01-03T00:00:00Z | Concord | 0 | 49 | 60 | 38 | 2.68 | -| 2020-01-03T00:00:00Z | Hayward | 0 | 50 | 62 | 41 | 3.13 | -| ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify a tag with no value in the WHERE clause" %}} - -```sql -SELECT * FROM home, weather WHERE location !~ /./ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | --: | ---: | -------- | ------ | :---------- | ---: | -------- | -------- | -------- | -------- | -| 2022-01-01T08:00:00Z | 0 | 35.9 | | | Kitchen | 21 | | | | | -| 2022-01-01T08:00:00Z | 0 | 35.9 | | | Living Room | 21.1 | | | | | -| 2022-01-01T09:00:00Z | 0 | 36.2 | | | Kitchen | 23 | | | | | -| 2022-01-01T09:00:00Z | 0 | 35.9 | | | Living Room | 21.4 | | | | | -| 2022-01-01T10:00:00Z | 0 | 36.1 | | | Kitchen | 22.7 | | | | | -| 2022-01-01T10:00:00Z | 0 | 36 | | | Living Room | 21.8 | | | | | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify tag keys in the GROUP BY clause" %}} - -```sql -SELECT MAX(precip) FROM weather GROUP BY /^l/ -``` - -{{% influxql/table-meta %}} -name: weather -tags: location=Concord -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2021-10-24T00:00:00Z | 4.53 | - -{{% influxql/table-meta %}} -name: weather -tags: location=Hayward -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2022-12-31T00:00:00Z | 4.34 | - -{{% influxql/table-meta %}} -name: weather -tags: location=San Francisco -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2021-10-24T00:00:00Z | 4.02 | - -{{% /expand %}} - -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/reference/influxql/select.md b/content/influxdb/cloud-dedicated/reference/influxql/select.md index 5d5c246e4..8e06ad799 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/select.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/select.md @@ -14,451 +14,6 @@ list_code_example: | ```sql SELECT [,,] FROM [,] ``` + +source: /shared/influxql-v3-reference/select.md --- - -Use the `SELECT` statement to query data from one or more -[measurements](/influxdb/cloud-dedicated/reference/glossary/#measurement). -The `SELECT` statement **requires** a [`SELECT` clause](#select-clause) and a -[`FROM` clause](#from-clause). - -- [Syntax](#syntax) - - [SELECT clause](#select-clause) - - [FROM clause](#from-clause) -- [Notable SELECT statement behaviors](#notable-select-statement-behaviors) -- [Data types and casting operations](#data-types-and-casting-operations) -- [SELECT statement examples](#select-statement-examples) - - -## Syntax - -```sql -SELECT field_expression[, ..., field_expression_n[, tag_expression[, ..., tag_expression_n]]] FROM measurement_expression[, ..., measurement_expression_n] -``` - -### SELECT clause - -The `SELECT` clause supports several formats for identifying data to query. -It requires one or more **field expressions** and optional **tag expressions**. - -- **field_expression**: Expression to identify one or more fields to return in query results. - Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), - constant, [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/), - [wildcard (`*`)](#wildcard-expressions-in-select-clauses), or - [function expression](/influxdb/cloud-dedicated/reference/influxql/functions/) and any - combination of arithmetic operators. -- **tag_expression**: Expression to identify one or more tags to return in query results. - Can be a [tag key](/influxdb/cloud-dedicated/reference/glossary/#tag-key) or constant. - -#### Select clause behaviors - -- `SELECT field_key` - Returns a specific field. -- `SELECT field_key1, field_key2` - Returns two specific fields. -- `SELECT field_key, tag_key` - Returns a specific field and tag. -- `SELECT *` - Returns all [fields](/influxdb/cloud-dedicated/reference/glossary/#field) - and [tags](/influxdb/cloud-dedicated/reference/glossary/#tag). - _See [Wildcard expressions](#wildcard-expressions)._ -- `SELECT /^[t]/` - Returns all [fields](/influxdb/cloud-dedicated/reference/glossary/#field) - and [tags](/influxdb/cloud-dedicated/reference/glossary/#tag) with keys that - match the regular expression. At least one field key must match the regular - expression. If no field keys match the regular expression, no results are - returned. - -### FROM clause - -The `FROM` clause specifies the -[measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) or -[subquery](/influxdb/cloud-dedicated/reference/influxql/subqueries/) to query. -It requires one or more comma-delimited -[measurement expressions](#measurement_expression) or [subqueries](#subquery). - -#### measurement_expression - -A measurement expression identifies a measurement to query. -It can be a measurement name, fully-qualified measurement, constant, or -a [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/). - -- **Measurement name**: When using just the measurement name, InfluxQL assumes - the default retention policy of the database specified in the query request. - - ```sql - FROM measurement - ``` - -- **Fully-qualified measurement**: A fully qualified measurement includes a - database name, retention policy name, and measurement name, each separated by - a period (`.`). If the retention policy is not specified, InfluxQL uses the - default retention policy for the specified database. - -```sql -FROM database.retention_policy.measurement - --- Fully-qualified measurement with default retention policy -FROM database..measurement -``` - -{{% note %}} -#### InfluxQL retention policies - -In {{< product-name >}}, **retention policies** are not part of the data model -like they are in InfluxDB 1.x. -Each {{< product-name >}} database has a **retention period** which defines the -maximum age of data to retain in the database. To use fully-qualified -measurements in InfluxQL queries, use the following naming convention when -[creating a database](/influxdb/cloud-dedicated/admin/databases/create/): - -``` -database_name/retention_policy -``` -{{% /note %}} - -#### Subquery - -An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. -The outer query queries results returned by the inner query (subquery). - -For more information, see [InfluxQL subqueries](/influxdb/cloud-dedicated/reference/influxql/subqueries/). - -## Notable SELECT statement behaviors - -- [Must query at least one field](#must-query-at-least-one-field) -- [Wildcard expressions](#wildcard-expressions) -- [Cannot include both aggregate and non-aggregate field expressions](#cannot-include-both-aggregate-and-non-aggregate-field-expressions) - -### Must query at least one field - -A query requires at least one [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key) -in the `SELECT` clause to return data. -If the `SELECT` clause includes only [tag keys](/influxdb/cloud-dedicated/reference/glossary/#tag-key), -the query returns an empty result. -When using regular expressions in the `SELECT` clause, if regular expression -matches only tag keys and no field keys, the query returns an empty result. - -To return data associated with tag keys, include at least one field key in the -`SELECT` clause. - -### Wildcard expressions - -When using a wildcard expression (`*`) in the `SELECT` clause, the query returns -all tags and fields. -If a [function](/influxdb/cloud-dedicated/reference/influxql/functions/) is -applied to a wildcard expression, the query returns all _fields_ with -the function applied, but does not return _tags_ unless they are included in -the `SELECT` clause. - -### Cannot include both aggregate and non-aggregate field expressions - -The `SELECT` statement cannot include an aggregate field expression -(one that uses an [aggregate](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/) -or [selector](/influxdb/cloud-dedicated/reference/influxql/functions/aggregates/) -function) **and** a non-aggregate field expression. -For example, in the following query, an aggregate function is applied to one -field, but not the other: - -```sql -SELECT mean(temp), hum FROM home -``` - -This query returns an error. -For more information, see [error about mixing aggregate and non-aggregate queries](/enterprise_influxdb/v1/troubleshooting/errors/#error-parsing-query-mixing-aggregate-and-non-aggregate-queries-is-not-supported). - -## Data types and casting operations - -The [`SELECT` clause](#select-clause) supports specifying a -[field's](/influxdb/cloud-dedicated/reference/glossary/#field) type and basic -casting operations with the `::` syntax. - -```sql -SELECT field_expression::type FROM measurement_expression -``` - -The `::` syntax allows users to perform basic cast operations in queries. -Currently, InfluxQL supports casting _numeric_ [field values](/influxdb/cloud-dedicated/reference/glossary/#field-value) -to other numeric types. -Casting to an **identifier type** acts as a filter on results and returns only -columns of that specific identifier type along with the `time` column. - -{{< flex >}} -{{% flex-content "third" %}} - -##### Numeric types - -- `float` -- `integer` -- `unsigned` - -{{% /flex-content %}} -{{% flex-content "third" %}} - -##### Non-numeric types - -- `string` -- `boolean` - -{{% /flex-content %}} -{{% flex-content "third" %}} - -##### Identifier types - -- `field` -- `tag` - -{{% /flex-content %}} -{{< /flex >}} - -{{% note %}} -InfluxQL returns no data if the query attempts to cast a numeric value to a -non-numeric type and vice versa. -{{% /note %}} - -When casting a float value to an integer or unsigned integer, the float value -is truncated at the decimal point. No rounding is performed. - -## SELECT statement examples - -The examples below use the following sample data sets: - -- [Get started home sensor data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data) -- [NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data) - -{{< expand-wrapper >}} -{{% expand "Select all fields and tags from a measurement" %}} - -```sql -SELECT * FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select specific tags and fields from a measurement" %}} - -```sql -SELECT temp, hum, room FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | temp | hum | room | -| :------------------- | ---: | ---: | :---------- | -| 2022-01-01T08:00:00Z | 21 | 35.9 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | 35.9 | Living Room | -| 2022-01-01T09:00:00Z | 23 | 36.2 | Kitchen | -| 2022-01-01T09:00:00Z | 21.4 | 35.9 | Living Room | -| 2022-01-01T10:00:00Z | 22.7 | 36.1 | Kitchen | -| 2022-01-01T10:00:00Z | 21.8 | 36 | Living Room | -| ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select all fields from a measurement" %}} - -```sql -SELECT *::field FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | 21.8 | -| ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select a field from a measurement and perform basic arithmetic" %}} - -```sql -SELECT (temp * (9 / 5)) + 32 FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | temp | -| :------------------- | ----------------: | -| 2022-01-01T08:00:00Z | 69.80000000000001 | -| 2022-01-01T08:00:00Z | 69.98 | -| 2022-01-01T09:00:00Z | 73.4 | -| 2022-01-01T09:00:00Z | 70.52 | -| 2022-01-01T10:00:00Z | 72.86 | -| 2022-01-01T10:00:00Z | 71.24000000000001 | -| ... | ... | - -{{% /influxdb/custom-timestamps %}} - -{{% note %}} -**Note:** InfluxDB follows the standard order of operations. -See [InfluxQL mathematical operators](/influxdb/cloud-dedicated/reference/influxql/math-operators/) -for more on supported operators. -{{% /note %}} - -{{% /expand %}} - -{{% expand "Select all data from more than one measurement" %}} - -```sql -SELECT * FROM home, weather -``` - -{{% influxql/table-meta %}} -Name: weather -{{% /influxql/table-meta %}} - -| time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | --: | --: | :------------ | -----: | :--- | ---: | -------: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | | | Concord | 0 | | | 52 | 66 | 44 | 3.13 | -| 2020-01-01T00:00:00Z | | | San Francisco | 0 | | | 53 | 59 | 47 | 14.32 | -| 2020-01-01T00:00:00Z | | | Hayward | 0 | | | 50 | 57 | 44 | 2.24 | -| 2020-01-02T00:00:00Z | | | San Francisco | 0 | | | 54 | 61 | 49 | 5.82 | -| 2020-01-02T00:00:00Z | | | Hayward | 0 | | | 51 | 60 | 44 | 3.8 | -| 2020-01-02T00:00:00Z | | | Concord | 0 | | | 53 | 66 | 42 | 3.13 | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Select all data from a fully-qualified measurement (with default retention policy)" %}} - -```sql -SELECT * FROM "get-started"..home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -### Type-casting examples - -{{< expand-wrapper >}} - -{{% expand "Cast an integer field to a float" %}} - -```sql -SELECT co::float FROM home -``` - -{{% /expand %}} - -{{% expand "Cast a float field to an integer" %}} - -```sql -SELECT temp::integer FROM home -``` - -{{% /expand %}} - -{{% expand "Cast a float field to an unsigned integer" %}} - -```sql -SELECT temp::unsigned FROM home -``` - -{{% /expand %}} - -{{< /expand-wrapper >}} - - diff --git a/content/influxdb/cloud-dedicated/reference/influxql/show.md b/content/influxdb/cloud-dedicated/reference/influxql/show.md index a33950ceb..07e341809 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/show.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/show.md @@ -14,153 +14,6 @@ list_code_example: | ``` related: - /influxdb/cloud-dedicated/query-data/influxql/explore-schema/ + +source: /shared/influxql-v3-reference/show.md --- - -Use InfluxQL `SHOW` statements to query schema information from a database. - -- [SHOW RETENTION POLICIES](#show-retention-policies) -- [SHOW MEASUREMENTS](#show-measurements) -- [SHOW FIELD KEYS](#show-field-keys) -- [SHOW TAG KEYS](#show-tag-keys) -- [SHOW TAG VALUES](#show-tag-values) - -## SHOW RETENTION POLICIES - -Use the `SHOW RETENTION POLICIES` statement to list retention policies associated -with a database. -Each database has a single retention policy--`autogen`. - -{{% note %}} -In {{< product-name >}}, retention policies are not part of the -data structure but are expected by InfluxQL and used in fully-qualified measurements -in the [`FROM` clause](/influxdb/cloud-dedicated/reference/influxql/select/#from-clause). -The data returned for each retention policy does not represent the actual -retention-related attributes of the database. The values are placeholder values -meant only for InfluxQL feature parity. - -For information about database data retention, see -[List databases](/influxdb/cloud-dedicated/admin/databases/list/). -{{% /note %}} - -```sql -SHOW RETENTION POLICIES [ON ] -``` - -#### Examples - -```sql --- Show retention policies in the database specified in the query request -SHOW RETENTION POLICIES - --- Show retention policies in a specific database -SHOW RETENTION POLICIES ON "example-database" -``` - -## SHOW MEASUREMENTS - -Use the `SHOW MEASUREMENTS` statement to list measurements in a database. - -```sql -SHOW MEASUREMENTS [with_measurement_clause] [where_clause] [limit_clause] [offset_clause] -``` - -#### Examples - -```sql --- Show all measurements -SHOW MEASUREMENTS - --- Show measurements where region tag = 'uswest' AND host tag = 'serverA' -SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' - --- Show measurements that start with 'h2o' -SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ -``` - -## SHOW FIELD KEYS - -Use the `SHOW FIELD KEYS` statement to list all field keys in a measurement. - -```sql -SHOW FIELD KEYS [from_clause] -``` - -#### Examples - -```sql --- Show field keys and field value data types from all measurements -SHOW FIELD KEYS - --- Show field keys and field value data types from specified measurement -SHOW FIELD KEYS FROM "cpu" -``` - -## SHOW TAG KEYS - -Use the `SHOW TAG KEYS` statement to list tag keys in a measurement. - -```sql -SHOW TAG KEYS [from_clause] [where_clause] [limit_clause] [offset_clause] -``` - -#### Examples - -```sql --- Show all tag keys -SHOW TAG KEYS - --- Show all tag keys from the cpu measurement -SHOW TAG KEYS FROM "cpu" - --- Show all tag keys from the cpu measurement where the region key = 'uswest' -SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' - --- Show all tag keys where the host key = 'serverA' -SHOW TAG KEYS WHERE "host" = 'serverA' -``` - -## SHOW TAG VALUES - -Use the `SHOW TAG VALUES` statement to list values of specified tags in a database. - -```sql -SHOW TAG VALUES [from_clause] WITH KEY = [where_clause] [limit_clause] [offset_clause] -``` - -By default, the `SHOW TAG VALUES` statement only returns unique tag values from -**the last day**. To modify the time range, include a -[`WHERE` clause with a time-based predicate](/influxdb/cloud-dedicated/reference/influxql/where/#time-ranges). - -{{% note %}} - -#### Include a FROM clause - -We strongly recommend including a `FROM` clause with the `SHOW TAG VALUES` -statement that specifies 1-50 tables to query. -Without a `FROM` clause, the InfluxDB query engine must read data from all -tables and return unique tag values from each. - -Depending on the number of tables in your database and the number of unique tag -values in each table, excluding a `FROM` clause can result in poor query performance, -query timeouts, or unnecessary resource allocation that may affect other queries. - -{{% /note %}} - -#### Examples - -```sql --- Show tag values from the cpu measurement for the region tag -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" - --- Show tag values from the cpu measurement for the region tag for a custom time range -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" WHERE time > -7d - --- Show tag values from multiple measurements for the region tag -SHOW TAG VALUES FROM "cpu", "memory", "disk" WITH KEY = "region" - --- Show tag values from the cpu measurement for all tag keys that do not include the letter c -SHOW TAG VALUES FROM "cpu" WITH KEY !~ /.*c.*/ - --- Show tag values from the cpu measurement for region & host tag keys where service = 'redis' -SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' -``` diff --git a/content/influxdb/cloud-dedicated/reference/influxql/subqueries.md b/content/influxdb/cloud-dedicated/reference/influxql/subqueries.md index 45626be6c..ca11e2a15 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/subqueries.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/subqueries.md @@ -13,234 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` + +source: /shared/influxql-v3-reference/subqueries.md --- - -An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. -The outer query queries results returned by the inner query (subquery). - -- [Syntax](#syntax) -- [Examples](#examples) -- [Notable subquery behaviors](#notable-subquery-behaviors) - -{{% note %}} -InfluxQL does not support a `HAVING` clause, however InfluxQL subqueries offer -functionality similar to the [SQL `HAVING` clause](/influxdb/cloud-dedicated/reference/sql/having/). -{{% /note %}} - -## Syntax - -```sql -SELECT_clause FROM ( SELECT_statement ) [...] -``` - -When using subqueries, InfluxQL **performs the inner query first**, then performs -the outer query. - -The outer query requires a [`SELECT` clause](/influxdb/cloud-dedicated/reference/influxql/select/#select-clause) -and a [`FROM` clause](/influxdb/cloud-dedicated/reference/influxql/select/#from-clause). -The inner query is enclosed in parentheses in the outer query's `FROM` clause. - -InfluxQL supports multiple nested subqueries: - -```sql -SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] -``` - -## Examples - -{{% note %}} -#### Sample data - -The examples below use the following sample data sets: - -- [Get started home sensor data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data) -- [Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data) -{{% /note %}} - -{{< expand-wrapper >}} - -{{% expand "Apply an aggregate function to an aggregated result set" %}} - -```sql -SELECT - SUM(max) -FROM - ( - SELECT - MAX(temp) - FROM - home - GROUP BY - room - ) -``` - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | ---: | -| 1970-01-01T00:00:00Z | 46.1 | - -{{% /expand %}} - -{{% expand "Calculate the average difference between two fields" %}} - -```sql -SELECT - MEAN(difference) -FROM - ( - SELECT - a - b AS difference - FROM - numbers - ) -``` - -{{% influxql/table-meta %}} -Table: numbers -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -------------------: | -| 1970-01-01T00:00:00Z | -0.03629771779732732 | - -{{% /expand %}} - -{{% expand "Filter aggregate values based on a threshold" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - co_change -FROM - ( - SELECT - SPREAD(co) AS co_change - FROM - home - GROUP BY - room, - time(2h) - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' - AND co_change >= 4 -``` - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | co_chnage | -| :------------------- | --------: | -| 2022-01-01T18:00:00Z | 4 | -| 2022-01-01T18:00:00Z | 5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Perform additional aggregate operations on aggregate values" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SUM(co_derivative) AS sum_derivative -FROM - ( - SELECT - DERIVATIVE(MEAN(co)) AS co_derivative - FROM - home - GROUP BY - time(12m), - room - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY - room -``` - -{{% /influxdb/custom-timestamps %}} - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | room | sum_derivative | -| :------------------- | :---------- | -------------: | -| 1970-01-01T00:00:00Z | Kitchen | 5.2 | -| 1970-01-01T00:00:00Z | Living Room | 3.4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable subquery behaviors - -- [Apply time bounds to the outer query to improve performance](#apply-time-bounds-to-the-outer-query-to-improve-performance) -- [Cannot use multiple SELECT statements in a subquery](#cannot-use-multiple-select-statements-in-a-subquery) - -### Apply time bounds to the outer query to improve performance - -To improve the performance of InfluxQL queries that use subqueries and a -specified time range, apply the `WHERE` clause with time-based predicates to the -outer query rather than the inner query. -For example--the following queries return the same results, but **the query with -time-based predicate on the outer query is more performant than the query with -time-based predicate on the inner query**: - -{{% influxdb/custom-timestamps %}} - -#### Time bounds on the outer query {note="(Recommended)"} - -```sql -SELECT - inner_value AS value -FROM - ( - SELECT - raw_value as inner_value - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -``` - -#### Time bounds on the inner query - -```sql -SELECT - inner_value AS value -FROM - ( - SELECT - raw_value as inner_value - WHERE - time >= '2022-07-19T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' - ) -``` -{{% /influxdb/custom-timestamps %}} - -### Cannot use multiple SELECT statements in a subquery - -InfluxQL does not support multiple -[`SELECT` statements](/influxdb/cloud-dedicated/reference/influxql/select/) -per subquery: - -```sql -SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] -``` - -However, InfluxQL does support multiple nested subqueries per outer query: - -```sql -SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] - ------------------ ---------------- - Subquery 1 Subquery 2 -``` diff --git a/content/influxdb/cloud-dedicated/reference/influxql/time-and-timezone.md b/content/influxdb/cloud-dedicated/reference/influxql/time-and-timezone.md index 090382024..54834043f 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/time-and-timezone.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/time-and-timezone.md @@ -13,369 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` + +source: /shared/influxql-v3-reference/time-and-timezone.md --- - -InfluxQL is designed for working with time series data and includes features specifically for working with time. -You can review the following ways to work with time and timestamps in your InfluxQL queries: - -- [Time syntax](#time-syntax) - - [Add and subtract time values](#add-and-subtract-time-values) -- [Query time range](#query-time-range) - - [Supported operators](#supported-operators) -- [Query examples](#query-examples) -- [Time zone clause](#time-zone-clause) -- [Notable behaviors](#notable-behaviors) - - [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - - [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) - - [Cannot use parameters for durations](#cannot-use-parameters-for-durations) - -## Time syntax - -InfluxQL supports the following timestamp literal syntaxes: - -```sql -'2006-01-02T15:04:05.00Z' -- RFC3339 date-time string -'2006-01-02 15:04:05.00' -- RFC3339-like date-time string -1136189045000000000 -- Unix nanosecond epoch time -1136189045s -- Unix epoch time -``` - -- **RFC3339 date-time string**: - [String literal](/influxdb/cloud-dedicated/reference/influxql/#strings) using - the RFC3339 timestamp format, `YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`. -- **RFC3339-like date-time string**: - [String literal](/influxdb/cloud-dedicated/reference/influxql/#strings) using - the RFC3339-like timestamp format, `YYYY-MM-DD HH:MM:SS.nnnnnnnnn`. -- **Unix nanosecond epoch time**: - [Integer](/influxdb/cloud-dedicated/reference/influxql/#integers) that - represents the number of nanoseconds elapsed since the - [Unix epoch](/influxdb/cloud-dedicated/reference/glossary/#unix-epoch). -- **Unix epoch time**: - [Duration literal](/influxdb/cloud-dedicated/reference/influxql/#durations) - that represents the number of specified time units elapsed since the - [Unix epoch](/influxdb/cloud-dedicated/reference/glossary/#unix-epoch). - _[View supported duration units](/influxdb/cloud-dedicated/reference/influxql/#durations)_. - -##### Supported timestamp values - -| | RFC3339 | Unix nanosecond time | -| ----------- | :----------------------------: | -------------------: | -| **Maximum** | 2262-04-11T23:47:16.854775807Z | 9223372036854775807 | -| **Minimum** | 1677-09-21T00:12:43.145224193Z | -9223372036854775807 | - -### Add and subtract time values - -Timestamp values support addition and subtraction operations with -[duration literals](/influxdb/cloud-dedicated/reference/influxql/#durations). -Add (`+`) or subtract (`-`) a duration to or from a timestamp to return an -updated timestamp. - -```sql -'2023-01-01T00:00:00Z' + 2h -- Resolves to 2023-01-01T02:00:00Z -'2023-01-01 00:00:00' - 20h -- Resolves to 2022-12-31T04:00:00Z -1672531200000000000 + 1y -- Resolves to 2024-01-01T00:00:00Z -``` - -{{% note %}} -InfluxQL requires a whitespace between the `+` operators `-` and the duration literal. -{{% /note %}} - -## Query time range - -To specify the time range of a query, use conditional expressions in the -[`WHERE` clause](/inflxudb/cloud-dedicated/reference/influxql/where/) that -compare the value of the `time` column to an absolute timestamp or a relative -timestamp. - -- **Absolute time range**: Define query time bounds with timestamp literals - - ```sql - WHERE time >= '2023-01-01T00:00:00Z' AND time <= '2023-07-01T00:00:00Z' - WHERE time >= '2023-01-01 00:00:00' AND time <= '2023-07-01 00:00:00' - WHERE time >= 1672531200000000000 AND time <= 1688169600000000000 - WHERE time >= 1672531200s and time <= 1688169600000ms - ``` - -- **Relative time range**: Define query time bounds with a duration literal - added to or subtracted from timestamp literals. - - {{% note %}} - Use `now()` to return the current system time (UTC). - {{% /note %}} - - ```sql - -- Query data from the last day - WHERE time >= now() - 1d - - -- Query data from the previous week - WHERE time >= now() - 1w AND time <= now() - 2w - - -- Query data relative to a specific time - WHERE time >= '2023-01-01' - 1w AND time <= '2023-01-01' + 1w - ``` - -### Supported operators - -Conditional expressions with time operands support the following comparison operators: - -| Operator | Meaning | -|:--------:|:------- | -| `=` | equal to | -| `<>` | not equal to | -| `!=` | not equal to | -| `>` | greater than | -| `>=` | greater than or equal to | -| `<` | less than | -| `<=` | less than or equal to | - -{{% note %}} -Currently, InfluxQL supports the `AND` logical operator to define query time bounds, -but does not support using the `OR` logical operator to query multiple time ranges. -{{% /note %}} - -## Query examples - -The following examples use the -[Get started home sensor sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Specify a time range with RFC3339 date-time strings" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range with RFC3339-like date-time strings" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01 08:00:00' - AND time <= '2022-01-01 12:00:00' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Specify a time range with nanosecond epoch timestamps" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= 1641024000000000000 - AND time <= 1641038400000000000 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range with second-precision epoch timestamps" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= 1641024000s - AND time <= 1641038400s -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range relative to a timestamp" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | -| 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | -| 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | -| 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range relative to now" %}} - -```sql -SELECT * FROM home WHERE time >= now() - 2h -``` - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Time zone clause - -{{% warn %}} -InfluxQL in {{< product-name >}} does not currently support the time zone clause, -which applies a time zone offset to UTC timestamps in query results. -{{% /warn %}} - - - - - -## Notable behaviors - -- [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) -- [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) -- [Cannot use parameters for durations](#cannot-use-parameters-for-durations) - -### Cannot query multiple time ranges - -InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. -For example, the following query returns no results: - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') - OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') -``` - -{{% /influxdb/custom-timestamps %}} - -### Querying future data with a `GROUP BY time()` clause - -Queries that do not specify time bounds in the `WHERE` clause and do not include -a `GROUP BY time()` clause use the [minimum and maximum timestamps](#supported-timestamp-values) -as the default time range. -If the query includes a `GROUP BY time()` clause, the default time range is -between `1677-09-21T00:12:43.145224193Z` and -[`now()`](/influxdb/cloud-dedicated/reference/influxql/functions/date-time/#now). - -To query data with timestamps that occur in the future (after `now()`), -provide an explicit upper bound in the `WHERE` clause. - -### Cannot use parameters for durations - -Currently, InfluxDB doesn't support using parameters for durations in -[parameterized queries](/influxdb/cloud-dedicated/query-data/parameterized-queries/). diff --git a/content/influxdb/cloud-dedicated/reference/influxql/where.md b/content/influxdb/cloud-dedicated/reference/influxql/where.md index 65a2668ff..85358d2d6 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/where.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/where.md @@ -12,359 +12,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` + +source: /shared/influxql-v3-reference/where.md --- - -Use the `WHERE` clause to filter data based on -[field values](/influxdb/cloud-dedicated/reference/glossary/#field), -[tag values](/influxdb/cloud-dedicated/reference/glossary/#tag), and -[timestamps](/influxdb/cloud-dedicated/reference/glossary/#timestamp). - -- [Syntax](#syntax) -- [Operators](#comparison-operators) - - [Comparison operators](#comparison-operators) - - [Logical operators](#logical-operators) -- [Time ranges](#time-ranges) -- [Regular expressions](#regular-expressions) -- [WHERE clause examples](#where-clause-examples) -- [Notable behaviors](#notable-behaviors) - - [Single and double quotes](#single-and-double-quotes) - - [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - -## Syntax - -```sql -SELECT_clause FROM_clause WHERE [(AND|OR) [...]] -``` - -- **conditional_expression**: Comparison between two operands that evaluates to - `true` or `false`. Comparison logic is determined by - [operators](#operators) used in the expression. - These expressions can operate on InfluxDB fields, tags, and timestamps. - Use logical operators (`AND`, `OR`) to chain multiple conditional expressions - together. - -## Operators - -Operators evaluate the relationship between two operands and return -`true` or `false`. - -### Comparison operators - -| Operator | Meaning | Supported data types | -| :------: | :--------------------------------- | :---------------------- | -| `=` | Equal to | all | -| `<>` | Not equal to | all | -| `!=` | Not equal to | all | -| `>` | Greater than | numeric, timestamp | -| `>=` | Greater than or equal to | numeric, timestamp | -| `<` | Less than | numeric, timestamp | -| `<=` | Less than or equal to | numeric, timestamp | -| `=~` | Matches a regular expression | strings | -| `!~` | Doesn't match a regular expression | strings | - -### Logical operators - -| Operator | Meaning | -| :------- | :---------------------------------------------------------------------- | -| `AND` | Returns `true` if both operands are `true`. Otherwise, returns `false`. | -| `OR` | Returns `true` if any operand is `true`. Otherwise, returns `false`. | - -## Time ranges - -Use the `WHERE` clause to specify a time range to query. -If a time range isn't specified in the `WHERE` clause, the [default time range](/influxdb/cloud-dedicated/reference/influxql/#default-time-range) is used. - -Timestamps are stored in the `time` column. -Use comparison operators to compare the value of the `time` column to a -timestamp literal, integer (Unix nanosecond timestamp), or [expression](/influxdb/cloud-dedicated/reference/glossary/#expression). - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Timestamp](#) -[Integer](#) -[Expression](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-07-01T00:00:00Z' -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -WHERE - time >= 1672531200000000000 - AND time < 1688169600000000000 -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -WHERE - time >= now() - 1d - AND time < now() -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -See [Time syntax](/influxdb/cloud-dedicated/reference/influxql/time-and-timezone/#time-syntax) -for information on how to specify alternative time ranges in the `WHERE` clause. - -{{% note %}} -InfluxQL [does not support querying multiple time ranges](#cannot-query-multiple-time-ranges). -{{% /note %}} - -## Regular expressions - -Regular expressions can be used to evaluate _string_ values in the `WHERE` clause -using regular expression comparison operators: - -- `=~`: Matches a regular expression -- `!~`: Doesn't match a regular expression - -```sql -SELECT * FROM home WHERE room =~ /^K/ -``` - -For more information about InfluxQL regular expression syntax, see -[InfluxQL regular expressions](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/). - -## WHERE clause examples - -The following examples use the -[Get started home sensor sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} -{{% expand "Select data with a specific tag value" %}} - -```sql -SELECT * FROM home WHERE room = 'Living Room' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| 2022-01-01T11:00:00Z | 0 | 36 | Living Room | 22.2 | -| 2022-01-01T12:00:00Z | 0 | 35.9 | Living Room | 22.2 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data from a specific time range" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data from a relative time range" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | -| 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | -| 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | -| 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select field values above a threshold" %}} - -```sql -SELECT co FROM home WHERE co > 9 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | -| :------------------- | --: | -| 2022-01-01T18:00:00Z | 18 | -| 2022-01-01T19:00:00Z | 14 | -| 2022-01-01T19:00:00Z | 22 | -| 2022-01-01T20:00:00Z | 17 | -| 2022-01-01T20:00:00Z | 26 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select specific field values" %}} - -```sql -SELECT room, co FROM home WHERE co = 9 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | room | co | -| :------------------- | :---------- | --: | -| 2022-01-01T17:00:00Z | Kitchen | 9 | -| 2022-01-01T18:00:00Z | Living Room | 9 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select field values based on arithmetic" %}} - -```sql -SELECT room, co FROM home WHERE co - 10 > 5 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | room | co | -| :------------------- | :---------- | --: | -| 2022-01-01T18:00:00Z | Kitchen | 18 | -| 2022-01-01T19:00:00Z | Kitchen | 22 | -| 2022-01-01T20:00:00Z | Living Room | 17 | -| 2022-01-01T20:00:00Z | Kitchen | 26 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data with field values above a threshold and a specific tag value" %}} - -```sql -SELECT * FROM home WHERE temp > 22.7 AND room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | -| 2022-01-01T14:00:00Z | 1 | 36.3 | Kitchen | 22.8 | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data based on the relationship between columns" %}} - -```sql -SELECT co, temp FROM home WHERE co > temp -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | temp | -| :------------------- | --: | ---: | -| 2022-01-01T20:00:00Z | 26 | 22.7 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable behaviors - -- [Single and double quotes](#single-and-double-quotes) -- [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - -### Single and double quotes - -In InfluxQL, single quotation marks (`'`) and double quotation marks (`"`) work -differently and can alter the way a `WHERE` clause functions. -Single quotes are used in [string](/influxdb/cloud-dedicated/reference/influxql/#strings) -and [timestamp](/influxdb/cloud-dedicated/reference/influxql/#dates--times) literals. -Double quotes are used to quote [identifiers](/influxdb/cloud-dedicated/reference/influxql/#identifiers), -(time, field, and tag column names). - -For example, the following conditional expression compares the value of the -`location` _column_ to the _literal string_, `London`: - -```sql -"location" = 'London' -``` - -The following conditional expression compares the value of the `location` _column_ -to the value of the `London` _column_: - -```sql -"location" = "London" -``` - -Misused double and single quotes in the `WHERE` clause often results in unexpected -empty query results. -For more information about quotation marks, see -[InfluxQL quotation](/influxdb/cloud-dedicated/reference/influxql/quoting/). - -### Cannot query multiple time ranges - -InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. -For example, the following query returns no results: - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') - OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') -``` - -{{% /influxdb/custom-timestamps %}} diff --git a/content/influxdb/cloud-dedicated/reference/internals/data-retention.md b/content/influxdb/cloud-dedicated/reference/internals/data-retention.md index 618e6beb2..da8cb914d 100644 --- a/content/influxdb/cloud-dedicated/reference/internals/data-retention.md +++ b/content/influxdb/cloud-dedicated/reference/internals/data-retention.md @@ -22,8 +22,8 @@ are filtered out of query results, even though the data may still exist. ## Database retention period A **database retention period** is the duration of time that a database retains data. -Retention periods are designed to automatically delete expired data and optimize -storage without any user intervention. +Retention periods automatically delete expired data and optimize +storage without the need for user intervention. Retention periods can be as short as an hour or infinite. [Points](/influxdb/cloud-dedicated/reference/glossary/#point) in a database with @@ -40,6 +40,6 @@ to view your databases' retention periods. ## When does data actually get deleted? InfluxDB routinely deletes [Parquet](https://parquet.apache.org/) files containing only expired data. -InfluxDB retains expired Parquet files for approximately 100 days for disaster recovery. -After the disaster recovery period, expired Parquet files are permanently deleted -and can't be recovered. +Expired Parquet files are retained for approximately 30 days for disaster recovery purposes. +After this period, the files are permanently deleted and cannot be recovered. +For more information see [data durability](/influxdb/cloud-dedicated/reference/internals/durability/). diff --git a/content/influxdb/cloud-dedicated/reference/internals/durability.md b/content/influxdb/cloud-dedicated/reference/internals/durability.md index b444f671c..0fe773096 100644 --- a/content/influxdb/cloud-dedicated/reference/internals/durability.md +++ b/content/influxdb/cloud-dedicated/reference/internals/durability.md @@ -12,6 +12,7 @@ menu: influxdb/cloud-dedicated/tags: [backups, internals] related: - https://docs.aws.amazon.com/AmazonS3/latest/userguide/DataDurability.html, AWS S3 Data Durabililty + - /influxdb/cloud-dedicated/reference/internals/storage-engine/ --- {{< product-name >}} writes data to multiple Write-Ahead-Log (WAL) files on local @@ -24,30 +25,25 @@ across a minimum of three availability zones in a cloud region. 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. - - -The _InfluxDB catalog_ is a relational, PostreSQL-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. +never replaced nor modified. Parquet files are stored in object storage and +referenced in the [Catalog](/influxdb/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 when the retention period is reached for data within -a database, the associated Parquet files are marked as deleted _in the catalog_, -but the actual Parquet files are _not removed from object storage_. -All queries filter out data that has been marked as deleted. -Parquet files remain in object storage for approximately 100 days after the -youngest data in the Parquet file ages out of retention. +When data is deleted or expires (reaches the database's [retention period](/influxdb/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 >}}, the data is first written to a -Write-Ahead-Log (WAL) on locally-attached storage on the ingester node before -the write request is acknowledged. 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 InfluxDB catalog to -reference the newly created Parquet files. If an ingester is gracefully shut +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](/influxdb/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](/influxdb/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. @@ -55,7 +51,7 @@ the WAL to the Parquet files before shutting down. {{< product-name >}} implements the following data backup strategies: -- **Backup of WAL file**: The WAL file is written on locally-attached storage. +- **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. @@ -67,11 +63,11 @@ the WAL to the Parquet files before shutting down. 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 100 days). + plus an additional time period (approximately 30 days). - **Backup of catalog**: InfluxData keeps a transaction log of all recent updates - to the [InfluxDB catalog](#influxdb-catalog) and generates a daily backup of - the catalog. Backups are preserved for at least 100 days in object storage across a minimum + to the [InfluxDB catalog](/influxdb/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 @@ -84,6 +80,6 @@ InfluxData can perform the following recovery operations: - **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 InfluxDB catalog to - the most recent daily backup of the catalog and then reapply any transactions +- **Recovery of the catalog**: InfluxData can restore the [Catalog](/influxdb/cloud-dedicated/reference/internals/storage-engine/#catalog) to + the most recent daily backup and then reapply any transactions that occurred since the interruption. diff --git a/content/influxdb/cloud-dedicated/reference/internals/security.md b/content/influxdb/cloud-dedicated/reference/internals/security.md index 915c486c4..6a74cdaa6 100644 --- a/content/influxdb/cloud-dedicated/reference/internals/security.md +++ b/content/influxdb/cloud-dedicated/reference/internals/security.md @@ -8,6 +8,9 @@ menu: name: Security parent: InfluxDB internals influxdb/cloud-dedicated/tags: [security, internals] +related: + - /influxdb/cloud-dedicated/admin/tokens + - /influxdb/cloud-dedicated/admin/users --- InfluxData's information security program is based on industry-recognized standards and frameworks, @@ -233,21 +236,25 @@ Users can configure the following security controls: ### Access, authentication, and authorization -{{< product-name >}} uses [Auth0](https://auth0.com/) for authentication and -separates workload cluster management authorizations (using _management tokens_) +{{< product-name >}} separates workload cluster management authorizations +(using _management tokens_) from database read and write authorizations (using _database tokens_). - [User provisioning](#user-provisioning) +- [User groups](#user-groups) - [Management tokens](#management-tokens) - [Database tokens](#database-tokens) #### User provisioning -InfluxData uses [Auth0](https://auth0.com/) to create user accounts and assign -permission sets to user accounts on {{% product-name %}}. -After a user account is created, InfluxData provides the user with the following: +InfluxData follows security best practices for creating user accounts +and managing permissions to resources. -- An **Auth0 login** to authenticate access to the cluster +InfluxData Support creates user accounts with [user group](#user-groups) permissions +for access to {{% product-name omit="Clustered" %}} cluster resources. +After creating the user account, InfluxData provides the user with the following: + +- A login URL for authenticating access to the cluster - The {{% product-name %}} **account ID** - The {{% product-name %}} **cluster ID** - The {{% product-name %}} **cluster URL** @@ -255,15 +262,46 @@ After a user account is created, InfluxData provides the user with the following With a valid password, the user can login by invoking one of the [`influxctl` commands](/influxdb/cloud-dedicated/reference/influxctl/). -The command initiates an Auth0 browser login so that the password is never +The command initiates a browser login between the identity provider and the user +so that the password is never exchanged with `influxctl`. -After a successful Auth0 authentication, {{% product-name %}} provides the +After a successful authentication, {{% product-name %}} provides the user's `influxctl` session with a short-lived [management token](#management-tokens) for access to the Granite service. -The user interacts with the `influxctl` command line tool to manage the workload -cluster, including creating [database tokens](#database-tokens) for database -read and write access and [creating long-lived management tokens](/influxdb/cloud-dedicated/admin/management-tokens/) -for use with the [Management API](/influxdb/cloud-dedicated/api/management/). +The user interacts with the `influxctl` command line tool to view or manage +cluster resources. +The [user groups](#user-groups) assigned to the user determine the level of +access to resources. + +#### User groups + +User groups associate access privileges with user attributes--an important part of the +Attribute-Based Access Control (ABAC) security model, which grants access based on +user attributes, resource types, and environment context. + +In {{% product-name %}}, a user can belong to any of the following user groups, +each with predefined privileges: + +- [Admin user group](#admin-user-group) +- [Member user group](#member-user-group) +- [Auditor user group](#auditor-user-group) + +##### Admin user group + +Admins are {{% product-name %}} users who have read and write permissions on +all resources (for all clusters) in the account. +Only Admins can create [management tokens](#management-tokens). + +##### Member user group + +Members are {{% product-name %}} users who have read permission on certain +resources and create permission for [database tokens](#database-tokens). +Members can't delete or create databases or management tokens. + +##### Auditor user group + +Auditors are {{% product-name %}} users who have read permission on all resources +(for all clusters) in the account; auditors can't modify account resources. #### Management tokens @@ -279,11 +317,24 @@ Management tokens consist of the following: - An access token string (sensitive) - A permission set for management activities (configured during user provisioning) -- A mandatory 1 hour expiration for tokens generated by logging in to `influxctl` +- For tokens generated by logging in to `influxctl`, a mandatory 1 hour expiration +In {{% product-name %}}, management tokens may be created by +the account's identity provider +for user authentication in clients, such as `influxctl`, or they may be manually +created by [Admin](#admins-role-admin) +users for automation using the Management API. + +- [Management tokens in the `influxctl` CLI](#management-tokens-in-influxctl-cli) +- [Management tokens and the Management API](#management-tokens-and-the-management-api) + +##### Management tokens in influxctl CLI + +In {{% product-name %}}, the account's identity provider creates management tokens +for user authentication in tools such as `influxctl`. When a user issues a command using the `influxctl` command-line tool, `influxctl` sends the management token string with the request to the server, -where Granite validates the token (for example, using Auth0). +where Granite validates the token. If the management token is valid and not expired, the service then compares the token's permissions against the permissions needed to complete the user's request. @@ -300,13 +351,17 @@ For example, a user's Linux system would store the management token at ##### Management tokens and the Management API -A user associated with the cluster and authorized through OAuth may use -`influxctl` to -[manually create and revoke management tokens](/influxdb/cloud-dedicated/admin/tokens/management/) -for automation use -cases--for example, using the [Management API for -{{% product-name %}}](/influxdb/cloud-dedicated/api/management/) to rotate -database tokens or create tables. +For automation use cases, [Admins](#admin-group) can +[manually create and revoke long-lived management tokens](/influxdb/cloud-dedicated/admin/tokens/management/) +for use with the [Management API](/influxdb/cloud-dedicated/api/management/)--for +example, to rotate database tokens or create tables. + +Manually created management tokens: + +- aren't affected by [user group](#user-groups) permissions +- have an optional expiration and don't require human interaction with the OAuth provider +- are for automation use cases +- shouldn't be used to circumvent the OAuth provider To authenticate a Management API request, the user passes the manually created token in the HTTP `Authorization` header: @@ -315,17 +370,15 @@ token in the HTTP `Authorization` header: Authorization MANAGEMENT_TOKEN ``` -A manually created management token has an optional expiration and -doesn't require human interaction with the OAuth provider. - -Manually created management tokens are meant for automation use cases -and shouldn't be used to circumvent the OAuth provider. - #### Database tokens -Database tokens provide authorization for users and client applications to read and write data and metadata in an {{% product-name %}} database. +[Admins](#admin-group) and [Members](#member-group), can create +[database tokens](#database-tokens) for database read and write access. +Database tokens provide authorization for users and client applications to read +and write data and metadata in an {{% product-name %}} database. All data write and query API requests require a valid database token with sufficient permissions. -_**Note:** an all-access management token can't read or write to a database because it's not a database token._ +_**Note:** an all-access [management token](#management-tokens) can't read or +write to a database because it's not a database token._ Database tokens consist of the following: diff --git a/content/influxdb/cloud-dedicated/reference/internals/system-tables.md b/content/influxdb/cloud-dedicated/reference/internals/system-tables.md deleted file mode 100644 index 84abaae47..000000000 --- a/content/influxdb/cloud-dedicated/reference/internals/system-tables.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: InfluxDB system tables -description: > - InfluxDB system measurements contain time series data used by and generated from the - InfluxDB internal monitoring system. -menu: - influxdb_cloud_dedicated: - name: System tables - parent: InfluxDB internals -weight: 103 -influxdb/cloud-dedicated/tags: [tables, information schema] -related: - - /influxdb/cloud-dedicated/reference/sql/information-schema/ ---- - -InfluxDB system measurements contain time series data used by and generated from the -InfluxDB internal monitoring system. - -Each {{% product-name %}} namespace includes the following system measurements: - - - -- [system.queries measurement](#systemqueries-measurement) - - [system.queries schema](#systemqueries-schema) - -## system.queries measurement - -The `system.queries` measurement stores log entries for queries executed for the provided namespace (database) on the node that is currently handling queries. - -```python -from influxdb_client_3 import InfluxDBClient3 -client = InfluxDBClient3(token = DATABASE_TOKEN, - host = HOSTNAME, - org = '', - database=DATABASE_NAME) -client.query('select * from home') -reader = client.query(''' - SELECT * - FROM system.queries - WHERE issue_time >= now() - INTERVAL '1 day' - AND query_text LIKE '%select * from home%' - ''', - language='sql', - headers=[(b"iox-debug", b"true")], - mode="reader") -print("# system.queries schema\n") -print(reader.schema) -``` - - - -`system.queries` has the following schema: - -```python -# system.queries schema - -issue_time: timestamp[ns] not null -query_type: string not null -query_text: string not null -completed_duration: duration[ns] -success: bool not null -trace_id: string -``` - -_When listing measurements (tables) available within a namespace, some clients and query tools may include the `queries` table in the list of namespace tables._ - -`system.queries` reflects a process-local, in-memory, namespace-scoped query log. -The query log isn't shared across instances within the same deployment. -While this table may be useful for debugging and monitoring queries, keep the following in mind: - -- Records stored in `system.queries` are volatile. - - Records are lost on pod restarts. - - Queries for one namespace can evict records from another namespace. -- Data reflects the state of a specific pod answering queries for the namespace----the log view is scoped to the requesting namespace and queries aren't leaked across namespaces. - - A query for records in `system.queries` can return different results depending on the pod the request was routed to. - -**Data retention:** System data can be transient and is deleted on pod restarts. -The log size per instance is limited and the log view is scoped to the requesting namespace. - -### system.queries schema - -- **system.queries** _(measurement)_ - - **fields**: - - **issue_time**: timestamp when the query was issued - - **query_type**: type (syntax: `sql`, `flightsql`, or `influxql`) of the query - - **query_text**: query statement text - - **success**: execution status (boolean) of the query - - **completed_duration**: time (duration) that the query took to complete - - **trace_id**: trace ID for debugging and monitoring events diff --git a/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md b/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md index 25c8ecadb..06b540bdf 100644 --- a/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md +++ b/content/influxdb/cloud-dedicated/reference/release-notes/influxctl.md @@ -11,12 +11,54 @@ menu: weight: 202 --- +## v2.9.8 {date="2024-10-15"} + +### Bug Fixes + +- Continue revoking tokens on error. +- Reject unsupported input to `--template-timeformat`. +- Remove unused `client_secret` option from + [connection configuration profiles](/influxdb/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles). + +### Dependency Updates + +- Update Go to v1.23.2. +- Update `github.com/jedib0t/go-pretty/v6` from 6.5.9 to 6.6.0. +- Update `github.com/urfave/cli/v2` from 2.27.4 to 2.27.5. +- Update `google.golang.org/grpc` from 1.66.0 to 1.67.1. +- Update `google.golang.org/protobuf` from 1.34.2 to 1.35.1. + +--- + +## v2.9.7 {date="2024-09-11"} + +### Features + +- Add [global `--timeout` flag](/influxdb/cloud-dedicated/reference/cli/influxctl/#global-flags). +- Improve timezone support. + +### Bug Fixes + +- Use passthrough resolver for gRPC. + +### Dependency Updates + +- Update Go to 1.23.1. +- Update `github.com/pelletier/go-toml/v2` from 2.2.2 to 2.2.3. +- Update `golang.org/x/mod` from 0.20.0 to 0.21.0. +- Update `golang.org/x/oauth2` from 0.22.0 to 0.23.0. +- Update `google.golang.org/grpc` from 1.65.0 to 1.66.0. + +--- + ## v2.9.6 {date="2024-08-15"} ### Bug Fixes - Update query to wait for EOF on stdin instead of the first newline. +--- + ## v2.9.5 {date="2024-08-13"} ### Bug Fixes @@ -29,6 +71,8 @@ weight: 202 - Update `golang.org/x/mod` from 0.19.0 to 0.20.0 - Update `golang.org/x/oauth2` from 0.21.0 to 0.22.0 +--- + ## v2.9.4 {date="2024-07-25"} ### Bug Fixes @@ -40,12 +84,16 @@ weight: 202 - Update `golang.org/x/mod` from 0.18.0 to 0.19.0 - Update `google.golang.org/grpc` from 1.64.0 to 1.65.0 +--- + ## v2.9.3 {date="2024-06-26"} ### Bug Fixes - Update query subcommand to safely handle null timestamp in response. +--- + ## v2.9.2 {date="2024-06-17"} ### Bug Fixes @@ -56,6 +104,8 @@ weight: 202 - Update `google.golang.org/protobuf` from 1.34.1 to 1.34.2. +--- + ## v2.9.1 {date="2024-06-06"} ### Dependency Updates @@ -69,6 +119,8 @@ weight: 202 - Update `google.golang.org/protobuf` from 1.34.0 to 1.34.1 - Update build dependencies. +--- + ## v2.9.0 {date="2024-05-06"} ### Features @@ -80,7 +132,7 @@ weight: 202 - Update unimplemented error message with additional information. -### Dependecy Updates +### Dependency Updates - Update `github.com/apache/arrow/go/v16` from 16.0.0-20240401180149-68241d8a86e9 to 16.0.0. - Update `github.com/jedib0t/go-pretty/v6` from 6.5.8 to 6.5.9. @@ -188,7 +240,7 @@ associated with another InfluxDB cluster. ### Bug Fixes -- Update arrow to allow non-TLS connections. +- Update Arrow to allow non-TLS connections. - Do not attempt to load cached tokens when an admin token file is provided. - Print retention period up to days rather than very large hours. - Fix indentation of help output. diff --git a/content/influxdb/cloud-dedicated/reference/sql/_index.md b/content/influxdb/cloud-dedicated/reference/sql/_index.md index 2a1389883..49f5d1331 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/_index.md +++ b/content/influxdb/cloud-dedicated/reference/sql/_index.md @@ -9,689 +9,10 @@ menu: weight: 101 related: - /influxdb/cloud-dedicated/reference/internals/arrow-flightsql/ + +source: /content/shared/sql-reference/_index.md --- -{{% product-name %}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. - -- [Identifiers](#identifiers) -- [Quoting and case sensitivity](#quoting-and-case-sensitivity) -- [Literals](#literals) -- [Duration units](#duration-units) -- [Operators](#operators) -- [Keywords](#keywords) -- [Conditional expressions](#conditional-expressions) -- [Statements and clauses](#statements-and-clauses) -- [Comments](#comments) -- [Functions](#functions) - -## Identifiers - -An identifier is a token which refers to the name of an InfluxDB database object, such as a **measurement** or a column name (**time**, **tag keys**, or **field keys**). - -## Quoting - -Use double quotes on [identifiers](#identifiers) to treat them as case-sensitive. -Use single quotes on string literals. - -General quoting guidelines: - -- Single quote RFC3339 and RFC3339-like time values. -- Do _not_ quote Unix epoch time values (integers cast to a timestamp). -- Double-quote mixed case, [camel case](https://en.wikipedia.org/wiki/Camel_case) or case-sensitive identifiers. -- Double-quote identifiers that contain special characters or whitespace characters. - -##### Quoting examples - -```sql --- Double-quote identifiers that contain whitespace -SELECT "water temperature", "buoy location" FROM buoy - --- Double-quote measurement names with special characters -SELECT * FROM "h2o-temperature" - --- Double-quote identifiers that should be treated as case-sensitive -SELECT "pH" FROM "Water" -``` - -{{% note %}} -**Note:** We recommend always double-quoting identifiers, regardless of case-sensitivity. -{{% /note %}} - - -Unquoted identifiers **are not** case-sensitive and match any measurement, tag key, or field key with the same characters, despite case. -For example, if you have two fields in a measurement named `ph` and `pH`, the unquoted identifier, `pH` will match both. -To query in a case-sensitive manner, double-quote identifiers. - -## Literals - -A literal is an explicit value not represented by an identifier. - -### String literals - -String literals are surrounded by single quotes. - -```sql -'santa_monica' -'pH' -'average temperature' -``` - -### Numeric literals - -Number literals are positive or negative numbers that are either exact numbers or floats. - -```sql --- Integers -10 -+10 --10 - --- Unsigned integers -10::BIGINT UNSIGNED -+10::BIGINT UNSIGNED - --- Floats -10.78654 --100.56 -``` - -### Date and time literals - -The following date and time literals are supported: - -```sql -'2022-01-31T06:30:30.123Z' -- (RFC3339) -'2022-01-31T06:30:30.123' -- (RFC3339-like) -'2022-01-31 06:30:30.123' -- (RFC3339-like) -'2022-01-31 06:30:30' -- ((RFC3339-like, no fractional seconds) -1643610630123000000::TIMESTAMP -- (Unix epoch nanosecond cast to a timestamp) -``` - -### Boolean literals - -Boolean literals are either `TRUE` or `FALSE`. - -## Duration units - -Interval literals specify a length or unit of time. - -```sql -INTERVAL '4 minutes' -INTERVAL '12 days 6 hours 30 minutes' -``` - -The following units of time are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks -- months -- years -- century - -## Operators - -Operators are reserved words or characters which perform certain operations, including comparisons and arithmetic. - -### Arithmetic operators - -Arithmetic operators take two numeric values (either literals or variables) and -perform a calculation that returns a single numeric value. - -| Operator | Description | Example | Result | -| :------: | :------------- | ------- | -----: | -| `+` | Addition | `2 + 2` | `4` | -| `-` | Subtraction | `4 - 2` | `2` | -| `*` | Multiplication | `2 * 3` | `6` | -| `/` | Division | `6 / 3` | `2` | -| `%` | Modulo | `7 % 2` | `1` | - -### Comparison operators - -Comparison operators evaluate the relationship between the left and right operands and `TRUE` or `FALSE`. - -| Operator | Meaning | Example | -| :------: | :------------------------------------------------------- | :----------------- | -| `=` | Equal to | `123 = 123` | -| `<>` | Not equal to | `123 <> 456` | -| `!=` | Not equal to | `123 != 456` | -| `>` | Greater than | `3 > 2` | -| `>=` | Greater than or equal to | `3 >= 2` | -| `<` | Less than | `1 < 2` | -| `<=` | Less than or equal to | `1 <= 2` | -| `~` | Matches a regular expression | `'abc' ~ 'a.*'` | -| `~\*` | Matches a regular expression _(case-insensitive)_ | `'Abc' ~\* 'A.*'` | -| `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | -| `!~\*` | Does not match a regular expression _(case-insensitive)_ | `'Abc' !~\* 'a.*'` | - -### Logical operators - -| Operator | Meaning | -| :-------: | :------------------------------------------------------------------------- | -| `AND` | Returns true if both operands are true. Otherwise, returns false. | -| `BETWEEN` | Returns true if the left operand is within the range of the right operand. | -| `EXISTS` | Returns true if the operand is not null. | -| `IN` | Returns true if the left operand is in the right operand list. | -| `LIKE` | Returns true if the left operand matches the right operand pattern string. | -| `NOT` | Negates the subsequent expression. | -| `OR` | Returns true if any operand is true. Otherwise, returns false. | - -### Bitwise operators - -Bitwise operators perform bitwise operations on bit patterns or binary numerals. - -| Operator | Meaning | Example | Result | -| :------: | :------------------ | :------- | -----: | -| `&` | Bitwise and | `5 & 3` | `1` | -| `\|` | Bitwise or | `5 \| 3` | `7` | -| `^` | Bitwise xor | `5 ^ 3` | `6` | -| `>>` | Bitwise shift right | `5 >> 3` | `0` | -| `<<` | Bitwise shift left | `5 << 3` | `40` | - -### Other operators - -| Operator | Meaning | Example | Result | -| :------------: | :----------------------- | :-------------------------------------------------------------------------------------- | :------------ | -| `\|\|` | Concatenates strings | `'Hello' \|\| ' world'` | `Hello world` | -| `AT TIME ZONE` | Apply a time zone offset | _[View example](/influxdb/cloud-dedicated/reference/sql/operators/other/#at-time-zone)_ | | - -## Keywords - -The following reserved keywords cannot be used as identifiers. - -```sql -AND -ALL -ANALYZE -AS -ASC -AT TIME ZONE -BETWEEN -BOTTOM -CASE -DESC -DISTINCT -EXISTS -EXPLAIN -FROM -GROUP BY -HAVING -IN -INNER JOIN -JOIN -LEFT JOIN -LIKE -LIMIT -NOT -EXISTS -NOT IN -OR -ORDER BY -FULL OUTER JOIN -RIGHT JOIN -SELECT -TOP -TYPE -UNION -UNION ALL -WHERE -WITH -``` - -## Conditional expressions - -Conditional expressions evaluate conditions based on input values. -The following conditional expressions are supported: - -| Expression | Description | -| :--------- | :----------------------------------------------------------------- | -| CASE | Allows for use of WHEN-THEN-ELSE statements. | -| COALESCE | Returns the first non-NULL expression in a specified list. | -| NULLIF | Returns a NULL value if value1 = value2. Otherwise returns value1. | - -## Statements and clauses - -InfluxDB SQL supports the following basic syntax for queries: - -```sql -[ WITH with_query [, …] ] -SELECT [ ALL | DISTINCT ] select_expr [, …] -[ FROM from_item [, …] ] -[ JOIN join_item [, …] ] -[ WHERE condition ] -[ GROUP BY grouping_element [, …] ] -[ HAVING condition] -[ UNION [ ALL ] ] -[ ORDER BY expression [ ASC | DESC ][, …] ] -[ LIMIT count ] -``` - -### SELECT statement and FROM clause - -Use the SQL `SELECT` statement to query data from a specific measurement or measurements. The `FROM` clause always accompanies the `SELECT` statement. - -#### Examples - -```sql -SELECT * FROM "h2o_feet" -``` -### WHERE clause - -Use the `WHERE` clause to filter results based on `fields`, `tags`, and `timestamps`. -Use predicates to evaluate each row. -Rows that evaluate as `TRUE` are returned in the result set. -Rows that evaluate as `FALSE` are omitted from the result set. - -#### Examples - -```sql -SELECT * FROM "h2o_feet" WHERE "water_level" <= 9 -``` -```sql -SELECT - * -FROM - "h2o_feet" -WHERE - "location" = 'santa_monica' - AND "level description" = 'below 3 feet' -``` - -### JOIN clause - -Use the `JOIN` clause to join data from multiple measurements (tables). -For more information about joins, see -[JOIN clause](/influxdb/cloud-dedicated/reference/sql/join/). -The following join types are supported: - -{{< flex >}} -{{< flex-content "quarter" >}} - -

INNER JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="inner small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

LEFT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="left small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

RIGHT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="right small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

FULL [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="full small center" >}} -
-{{< /flex-content >}} -{{< /flex >}} - -{{< expand-wrapper >}} -{{% expand "INNER JOIN" %}} - -Inner joins combine rows from tables on the left and right side of the join -based on common column values defined in the `ON` clause. Rows that don't have -matching column values are not included in the output table. - -```sql -SELECT - * -FROM - home -INNER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "LEFT [OUTER] JOIN" %}} - -A left outer join returns all rows from the left side of the join and only -returns data from the right side of the join in rows with matching column values -defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -LEFT OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "RIGHT [OUTER] JOIN" %}} - -A right outer join returns all rows from the right side of the join and only -returns data from the left side of the join in rows with matching column values -defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -RIGHT OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "FULL [OUTER] JOIN" %}} - -A full outer join returns all data from the left and right sides of the join and -combines rows with matching column values defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -FULL OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` -{{% /expand %}} -{{< /expand-wrapper >}} - -### GROUP BY clause - -Use the `GROUP BY` clause to group query results based on specified column values. `GROUP BY` **requires** an aggregate or selector function in the `SELECT` statement. - -#### Examples - -```sql -SELECT - MEAN("water_level"), - "location" -FROM - "h2o_feet" -GROUP BY - "location" -``` - -### HAVING clause - - Use the `HAVING` clause to filter query results based on a specified condition. - The `HAVING` clause must _follow_ the `GROUP BY` clause, but _precede_ the `ORDER BY` clause. - -#### Examples - -```sql -SELECT - MEAN("water_level"), - "location" -FROM - "h2o_feet" -GROUP BY - "location" -HAVING - MEAN("water_level") > 4 -ORDER BY - "location" -``` - -### UNION clause - -The `UNION` clause combines the results of two or more `SELECT` statements without returning any duplicate rows. `UNION ALL` returns all results, including duplicates. - -#### Examples - -```sql -SELECT - 'pH' -FROM - "h2o_pH" -UNION ALL -SELECT - "location" -FROM - "h2o_quality" -``` - -### ORDER BY clause - -The `ORDER BY` clause orders results by specified columns and order. -Sort data based on fields, tags, and timestamps. -The following orders are supported: - -- `ASC`: ascending _(default)_ -- `DESC`: descending - -#### Examples - -```sql -SELECT - "water_level", - "location" -FROM - "h2o_feet" -ORDER BY - "location", - "time" DESC -``` - -### LIMIT clause - -The `LIMIT` clause limits the number of rows to return. -The defined limit should be a non-negative integer. - -#### Examples - -```sql -SELECT - "water_level", - "location" -FROM - "h2o_feet" -LIMIT - 10 -``` - -### WITH clause - -The `WITH` clause provides a way to write auxiliary statements for use in a larger query. -It can help break down large, complicated queries into simpler forms. - -```sql -WITH summary_data as -(SELECT degrees, location, time - FROM average_temperature) -SELECT * FROM summary_data -``` - -### OVER clause - -The `OVER` clause is used with SQL window functions. -A **window function** performs a calculation across a set of table rows that are related in some way to the current row. - While similar to aggregate functions, window functions output results into rows retaining their separate identities. - -```sql -SELECT - time, - water_level -FROM - ( - SELECT - time, - "water_level", - row_number() OVER ( - order by - water_level desc - ) as rn - FROM - h2o_feet - ) -WHERE - rn <= 3; -``` - -## Comments - -Use comments to describe and add detail or notes to your queries. - -- Single line comments use the double hyphen `--` symbol. Single line comments end with a line break. -- Multi-line comments begin with `/*` and end with ` */`. - -```sql --- Single-line comment - -/* - * Multi-line comment - */ -``` - -## Schema information - -{{% product-name %}} supports the following metadata schema queries: - -```sql -SHOW tables - -SHOW columns FROM -``` - -## Functions - -Following is a list of supported functions by type. - -### Aggregate functions - -An aggregate function performs a calculation or computation on a set of data values in a column and returns a single value. - -| Function | Description | -| :------- | :--------------------------------------------------------- | -| COUNT() | Returns returns the number of rows from a field or tag key | -| AVG() | Returns the average value of a column | -| SUM() | Returns the summed value of a column | -| MEAN() | Returns the mean value of a column | -| MIN() | Returns the smallest value of the selected column | -| MAX() | Returns the largest value of the selected column | - -#### Examples - -```sql - -SELECT COUNT("water_level") -FROM "h2o_feet" - -SELECT AVG("water_level"), "location" -FROM "h2o_feet" -GROUP BY "location" - -SELECT SUM("water_level"), "location" -FROM "h2o_feet" -GROUP BY "location" -``` - -### Selector functions - -Selector functions are unique to InfluxDB. They behave like aggregate functions in that they take a row of data and compute it down to a single value. However, selectors are unique in that they return a **time value** in addition to the computed value. In short, selectors return an aggregated value along with a timestamp. - -| Function | Description | -| :--------------- | :-------------------------------------------------------------- | -| SELECTOR_FIRST() | Returns the first value of a selected column and timestamp. | -| SELECTOR_LAST() | Returns the last value of a selected column and timestamp. | -| SELECTOR_MIN() | Returns the smallest value of a selected column and timestamp. | -| SELECTOR_MAX() | Returns the largest value of a selected column and timestamp. | - -#### Examples - -```sql -SELECT -SELECTOR_MAX("pH", time)['value'], -SELECTOR_MAX("pH", time)['time'] -FROM "h2o_pH" - -SELECT -SELECTOR_LAST("water_level", time)['value'], -SELECTOR_LAST("water_level", time)['time'] -FROM "h2o_feet" -WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19T00:00:00Z' - -``` - -### Date and time functions - -| Function | Description | -| :----------- | :---------------------------------------------------------------------------------------------- | -| DATE_BIN() | Bins the input timestamp into a specified interval. | -| DATE_TRUNC() | Truncates a timestamp expression based on the date part specified, such as hour, day, or month. | -| DATE_PART() | Returns the specified part of a date. | -| NOW() | Returns the current time (UTC). | - -#### Examples - -```sql -SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z'::timestamp) AS "_time", -SUM(water_level) -FROM "h2o_feet" -GROUP BY "_time" -``` - -```sql -SELECT DATE_TRUNC('month',time) AS "date", -SUM(water_level) -FROM "h2o_feet" -GROUP BY time -``` - -### Approximate functions - -| Function | Description | -| :--------------------------------- | :-------------------------------------------------------------------------------------------- | -| APPROX_MEDIAN | Returns the approximate median of input values. | -| APPROX_DISTINCT | Returns the approximate count of the number of distinct values. Implemented only for strings. | -| APPROX_PERCENTILE_CONT | Returns the approximate percentile of input values. | -| APPROX_PERCENTILE_CONT_WITH_WEIGHT | Returns the approximate percentile of input values with weight. | - - -### Math functions - -| Function | Description | -| :------- | :------------------------------------------------------------------------------- | -| ABS() | Absolute value | -| ACOS() | Inverse cosine | -| ASIN() | Inverse sine | -| ATAN() | Inverse tangent | -| ATAN2() | Inverse tangent of y / x | -| CEIL() | Returns the smallest integer value greater than or equal to the specified number | -| COS() | Cosine | -| EXP() | Exponential | -| FLOOR() | Nearest integer less than or equal to the specified number | -| LN() | Natural logarithm | -| LOG10() | Base 10 logarithm | -| LOG2() | Base 2 logarithm | -| POWER() | Returns the value of a number raised to the power of the number | -| ROUND() | Round to the nearest integer | -| SIGNUM() | Sign of the argument (-1, 0, +1) | -| SINE() | Sine | -| SQRT() | Returns the square root of a number | -| TAN() | Tangent | -| TRUNC() | Truncates a number to the specified number of decimal places | - -### Conditional functions - -| Function | Description | -| :------- | :--------------------------------------------------------------------------------------------------------- | -| COALESCE | Returns the first argument that is not null. If all arguments are null, then `COALESCE` will return nulls. | -| NULLIF | Returns a null value if value1 equals value2, otherwise returns value1. | - - -### Regular expression functions - -| Function | Description | -| :------------- | :---------------------------------------------------------------------------- | -| REGEXP_MATCH | Matches a regular expression against a string and returns matched substrings. | -| REGEXP_REPLACE | Replaces substrings that match a regular expression by a new substring. | + diff --git a/content/influxdb/cloud-dedicated/reference/sql/data-types.md b/content/influxdb/cloud-dedicated/reference/sql/data-types.md index ea4763ffc..d1891e999 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/data-types.md +++ b/content/influxdb/cloud-dedicated/reference/sql/data-types.md @@ -11,207 +11,10 @@ menu: weight: 200 related: - /influxdb/cloud-dedicated/query-data/sql/cast-types/ + +source: /content/shared/sql-reference/data-types.md --- -InfluxDB Cloud Dedicated uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. -Data types define the type of values that can be stored in table columns. -In InfluxDB's SQL implementation, a **measurement** is structured as a table, -and **tags**, **fields** and **timestamps** are exposed as columns. - -DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. -Data types stored in InfluxDB's storage engine are mapped to SQL data types at query time. - -{{% note %}} -When performing casting operations, cast to the **name** of the data type, not the actual data type. -Names and identifiers in SQL are _case-insensitive_ by default. For example: - -```sql -SELECT - '99'::BIGINT, - '2019-09-18T00:00:00Z'::timestamp -``` - -{{% /note %}} - -- [String types](#string-types) -- [Numeric types](#numeric-types) - - [Integers](#integers) - - [Unsigned integers](#unsigned-integers) - - [Floats](#floats) -- [Date and time data types](#date-and-time-data-types) - - [Timestamp](#timestamp) - - [Interval](#interval) -- [Boolean types](#boolean-types) -- [Unsupported SQL types](#unsupported-sql-types) -- [Data types compatible with parameters](#data-types-compatible-with-parameters) - -## String types - -| Name | Data type | Description | -| :------ | :-------- | --------------------------------- | -| STRING | UTF8 | Character string, variable-length | -| CHAR | UTF8 | Character string, fixed-length | -| VARCHAR | UTF8 | Character string, variable-length | -| TEXT | UTF8 | Variable unlimited length | - -##### Example string literals - -```sql -'abcdefghijk' -'time' -'h2o_temperature' -``` - -## Numeric types - -The following numeric types are supported: - -| Name | Data type | Description | -| :-------------- | :-------- | :--------------------------- | -| BIGINT | INT64 | 64-bit signed integer | -| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | -| DOUBLE | FLOAT64 | 64-bit floating-point number | - -### Integers - -InfluxDB SQL supports the 64-bit signed integers: - -**Minimum signed integer**: `-9223372036854775808` -**Maximum signed integer**: `9223372036854775807` - -##### Example integer literals - -```sql -234 --446 -5 -``` - -### Unsigned integers - -InfluxDB SQL supports the 64-bit unsigned integers: - -**Minimum unsigned integer**: `0` -**Maximum unsigned integer**: `18446744073709551615` - -##### Example unsigned integer literals - -Unsigned integer literals are comprised of an integer cast to the `BIGINT UNSIGNED` type: - -```sql -234::BIGINT UNSIGNED -458374893::BIGINT UNSIGNED -5::BIGINT UNSIGNED -``` - -### Floats - -InfluxDB SQL supports the 64-bit double floating point values. -Floats can be a decimal point, decimal integer, or decimal fraction. - -##### Example float literals - -```sql -23.8 --446.89 -5.00 -0.033 -``` - -## Date and time data types - -InfluxDB SQL supports the following DATE/TIME data types: - -| Name | Data type | Description | -| :-------- | :-------- | :------------------------------------------------------------------- | -| TIMESTAMP | TIMESTAMP | TimeUnit::Nanosecond, None | -| INTERVAL | INTERVAL | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) | - -### Timestamp - -A time type is a single point in time using nanosecond precision. - -The following date and time formats are supported: - -```sql -YYYY-MM-DDT00:00:00.000Z -YYYY-MM-DDT00:00:00.000-00:00 -YYYY-MM-DD 00:00:00.000-00:00 -YYYY-MM-DDT00:00:00Z -YYYY-MM-DD 00:00:00.000 -YYYY-MM-DD 00:00:00 -``` - -##### Example timestamp literals - -```sql -'2023-01-02T03:04:06.000Z' -'2023-01-02T03:04:06.000-00:00' -'2023-01-02 03:04:06.000-00:00' -'2023-01-02T03:04:06Z' -'2023-01-02 03:04:06.000' -'2023-01-02 03:04:06' -``` - -### Interval - -The INTERVAL data type can be used with the following precision: - -- nanosecond -- microsecond -- millisecond -- second -- minute -- hour -- day -- week -- month -- year -- century - -##### Example interval literals -```sql -INTERVAL '10 minutes' -INTERVAL '1 year' -INTERVAL '2 days 1 hour 31 minutes' -``` - -## Boolean types - -Booleans store TRUE or FALSE values. - -| Name | Data type | Description | -| :------ | :-------- | :------------------- | -| BOOLEAN | BOOLEAN | True or false values | - -##### Example boolean literals - -```sql -true -TRUE -false -FALSE -``` - -## Unsupported SQL types - -The following SQL types are not currently supported: - -- UUID -- BLOB -- CLOB -- BINARY -- VARBINARY -- REGCLASS -- NVARCHAR -- CUSTOM -- ARRAY -- ENUM -- SET -- DATETIME -- BYTEA - -## Data types compatible with parameters - -For information about data types that can be substituted by parameters, -see how to [use parameterized queries with SQL](/influxdb/cloud-dedicated/query-data/sql/parameterized-queries/). + diff --git a/content/influxdb/cloud-dedicated/reference/sql/explain.md b/content/influxdb/cloud-dedicated/reference/sql/explain.md index fdbf0bae8..9f939e15e 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/explain.md +++ b/content/influxdb/cloud-dedicated/reference/sql/explain.md @@ -11,113 +11,10 @@ related: - /influxdb/cloud-dedicated/reference/internals/query-plan/ - /influxdb/cloud-dedicated/query-data/execute-queries/analyze-query-plan/ - /influxdb/cloud-dedicated/query-data/execute-queries/troubleshoot/ + +source: /content/shared/sql-reference/explain.md --- -The `EXPLAIN` command returns the [logical plan](/influxdb/cloud-dedicated/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb/cloud-dedicated/reference/internals/query-plan/#physical-plan) for the -specified SQL statement. - -```sql -EXPLAIN [ANALYZE] [VERBOSE] statement -``` - -- [`EXPLAIN`](#explain) - - [Example `EXPLAIN`](#example-explain) -- [`EXPLAIN ANALYZE`](#explain-analyze) - - [Example `EXPLAIN ANALYZE`](#example-explain-analyze) -- [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose) - - [Example `EXPLAIN ANALYZE VERBOSE`](#example-explain-analyze-verbose) - -## `EXPLAIN` - -Returns the logical plan and physical (execution) plan of a statement. -To output more details, use `EXPLAIN VERBOSE`. - -`EXPLAIN` doesn't execute the statement. -To execute the statement and view runtime metrics, use [`EXPLAIN ANALYZE`](#explain-analyze). - -### Example `EXPLAIN` - -```sql -EXPLAIN -SELECT - room, - avg(temp) AS temp -FROM home -GROUP BY room -``` - -{{< expand-wrapper >}} -{{% expand "View `EXPLAIN` example output" %}} - -| | plan_type | plan | -|---:|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 0 | logical_plan | Projection: home.room, AVG(home.temp) AS temp | -| | | Aggregate: groupBy=[[home.room]], aggr=[[AVG(home.temp)]] | -| | | TableScan: home projection=[room, temp] | -| 1 | physical_plan | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp] | -| | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)] | -| | | CoalesceBatchesExec: target_batch_size=8192 | -| | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8 | -| | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)] | -| | | ParquetExec: file_groups={8 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet, 70434/116281/b7a9e7c57fbfc3bba9427e4b3e35c89e001e2e618b0c7eb9feb4d50a3932f4db/d29370d4-262f-0d32-2459-fe7b099f682f.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], ...]}, projection=[room, temp] | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `EXPLAIN ANALYZE` - -Executes a statement and returns the execution plan and runtime metrics of the statement. -The report includes the [logical plan](/influxdb/cloud-dedicated/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb/cloud-dedicated/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution. - -If the plan requires reading lots of data files, `EXPLAIN` and `EXPLAIN ANALYZE` may truncate the list of files in the report. -To output more information, including intermediate plans and paths for all scanned Parquet files, use [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose). - -### Example `EXPLAIN ANALYZE` - -```sql -EXPLAIN ANALYZE -SELECT - room, - avg(temp) AS temp -FROM home -WHERE time >= '2023-01-01' AND time <= '2023-12-31' -GROUP BY room -``` - -{{< expand-wrapper >}} -{{% expand "View `EXPLAIN ANALYZE` example output" %}} - -| | plan_type | plan | -|---:|:------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 0 | Plan with Metrics | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp], metrics=[output_rows=2, elapsed_compute=4.768µs] | -| | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=140.405µs] | -| | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=2, elapsed_compute=6.821µs] | -| | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=2, elapsed_compute=18.408µs, repart_time=59.698µs, fetch_time=1.057882762s, send_time=5.83µs] | -| | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=137.577µs] | -| | | RepartitionExec: partitioning=RoundRobinBatch(8), input_partitions=6, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=46, elapsed_compute=26.637µs, repart_time=6ns, fetch_time=399.971411ms, send_time=6.658µs] | -| | | ProjectionExec: expr=[room@0 as room, temp@2 as temp], metrics=[output_rows=46, elapsed_compute=3.102µs] | -| | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=46, elapsed_compute=25.585µs] | -| | | FilterExec: time@1 >= 1672531200000000000 AND time@1 <= 1703980800000000000, metrics=[output_rows=46, elapsed_compute=26.51µs] | -| | | ParquetExec: file_groups={6 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], ...]}, projection=[room, time, temp], output_ordering=[room@0 ASC, time@1 ASC], predicate=time@6 >= 1672531200000000000 AND time@6 <= 1703980800000000000, pruning_predicate=time_max@0 >= 1672531200000000000 AND time_min@1 <= 1703980800000000000, required_guarantees=[], metrics=[output_rows=46, elapsed_compute=6ns, predicate_evaluation_errors=0, bytes_scanned=3279, row_groups_pruned_statistics=0, file_open_errors=0, file_scan_errors=0, pushdown_rows_filtered=0, num_predicate_creation_errors=0, row_groups_pruned_bloom_filter=0, page_index_rows_filtered=0, time_elapsed_opening=398.462968ms, time_elapsed_processing=1.626106ms, time_elapsed_scanning_total=1.36822ms, page_index_eval_time=33.474µs, pushdown_eval_time=14.267µs, time_elapsed_scanning_until_data=1.27694ms] | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `EXPLAIN ANALYZE VERBOSE` - -Executes a statement and returns the execution plan, runtime metrics, and additional details helpful for debugging the statement. - -The report includes the following: - -- the [logical plan](/influxdb/cloud-dedicated/reference/internals/query-plan/#logical-plan) -- the [physical plan](/influxdb/cloud-dedicated/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution -- Information truncated in the `EXPLAIN` report--for example, the paths for all [Parquet files retrieved for the query](/influxdb/cloud-dedicated/reference/internals/query-plan/#file_groups). -- All intermediate physical plans that DataFusion and the [Querier](/influxdb/cloud-dedicated/reference/internals/storage-engine/#querier) generate before generating the final physical plan--helpful in debugging to see when an [`ExecutionPlan` node](/influxdb/cloud-dedicated/reference/internals/query-plan/#executionplan-nodes) is added or removed, and how InfluxDB optimizes the query. - -### Example `EXPLAIN ANALYZE VERBOSE` - -```SQL -EXPLAIN ANALYZE VERBOSE SELECT temp FROM home -WHERE time >= now() - INTERVAL '7 days' AND room = 'Kitchen' -ORDER BY time -``` + diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/_index.md b/content/influxdb/cloud-dedicated/reference/sql/functions/_index.md index 2140890fa..4c3d36ea3 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/_index.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/_index.md @@ -9,6 +9,10 @@ menu: parent: SQL reference identifier: sql-functions weight: 220 + +source: /content/shared/sql-reference/functions/_index.md --- -{{< children >}} \ No newline at end of file + diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/aggregate.md b/content/influxdb/cloud-dedicated/reference/sql/functions/aggregate.md index 4fe73a646..cea84b8ef 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/aggregate.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/aggregate.md @@ -10,1450 +10,10 @@ menu: weight: 301 related: - /influxdb/cloud-dedicated/query-data/sql/aggregate-select/ + +source: /content/shared/sql-reference/functions/aggregate.md --- -SQL aggregate functions aggregate values in a specified column for each -group or SQL partition and return a single row per group containing the -aggregate value. - -- [General aggregate functions](#general-aggregate-functions) - - [array_agg](#array_agg) - - [avg](#avg) - - [bit_and](#bit_and) - - [bit_or](#bit_or) - - [bit_xor](#bit_xor) - - [bool_and](#bool_and) - - [bool_or](#bool_or) - - [count](#count) - - [first_value](#first_value) - - [last_value](#last_value) - - [max](#max) - - [mean](#mean) - - [median](#median) - - [min](#min) - - [sum](#sum) -- [Statistical aggregate functions](#statistical-aggregate-functions) - - [corr](#corr) - - [covar](#covar) - - [covar_pop](#covar_pop) - - [covar_samp](#covar_samp) - - regr_avgx - - regr_avgy - - regr_count - - regr_intercept - - regr_r2 - - regr_slope - - regr_sxx - - regr_syy - - regr_sxy - - [stddev](#stddev) - - [stddev_pop](#stddev_pop) - - [stddev_samp](#stddev_samp) - - [var](#var) - - [var_pop](#var_pop) - - [var_samp](#var_samp) -- [Approximate aggregate functions](#approximate-aggregate-functions) - - [approx_distinct](#approx_distinct) - - [approx_median](#approx_median) - - [approx_percentile_cont](#approx_percentile_cont) - - [approx_percentile_cont_with_weight](#approx_percentile_cont_with_weight) - ---- - -## General aggregate functions - -- [array_agg](#array_agg) -- [avg](#avg) -- [bit_and](#bit_and) -- [bit_or](#bit_or) -- [bit_xor](#bit_xor) -- [bool_and](#bool_and) -- [bool_or](#bool_or) -- [count](#count) -- [first_value](#first_value) -- [last_value](#last_value) -- [max](#max) -- [mean](#mean) -- [median](#median) -- [min](#min) -- [sum](#sum) - -### array_agg - -Returns an array created from the expression elements. - -{{% note %}} -`array_agg` returns a `LIST` arrow type which is not supported by InfluxDB. -To use with InfluxDB, use bracket notation to reference the index of an element -in the returned array. Arrays are 1-indexed. -{{% /note %}} - -```sql -array_agg(expression) -``` - -#### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `array_agg` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - array_agg(temp)[3] AS '3rd_temp' -FROM home -GROUP BY room -``` - -| room | 3rd_temp | -| :---------- | -------: | -| Kitchen | 22.7 | -| Living Room | 21.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### avg - -Returns the average of numeric values in the specified column. - -```sql -avg(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -##### Aliases - -- `mean` - -{{< expand-wrapper >}} -{{% expand "View `avg` query example" %}} - -```sql -SELECT - location, - avg(water_level) AS water_level_avg -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_avg | -| :----------- | -----------------: | -| coyote_creek | 5.359142420303919 | -| santa_monica | 3.5307120942458843 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_and - -Computes the bitwise `AND` of all non-null input values. - -```sql -bit_and(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_and` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_and(precip::BIGINT) AS precip_bit_and -FROM weather -GROUP BY location -``` - -| location | precip_bit_and | -| :------------ | -------------: | -| Concord | 0 | -| Hayward | 0 | -| San Francisco | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_or - -Computes the bitwise OR of all non-null input values. - -```sql -bit_or(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_or` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_or(precip::BIGINT) AS precip_bit_or -FROM weather -GROUP BY location -``` - -| location | precip_bit_or | -| :------------ | ------------: | -| Concord | 7 | -| Hayward | 7 | -| San Francisco | 7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_xor - -Computes the bitwise exclusive OR of all non-null input values. - -```sql -bit_xor(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_xor` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_xor(precip::BIGINT) AS precip_bit_xor -FROM weather -GROUP BY location -``` - -| location | precip_bit_xor | -| :------------ | -------------: | -| Concord | 4 | -| Hayward | 6 | -| San Francisco | 4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bool_and - -Returns `true` if _all_ non-null input values are `true`, otherwise returns `false`. - -```sql -bool_and(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bool_and` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bool_and(precip > 0) AS precip_bool_and -FROM weather -GROUP BY location -``` - -| location | precip_bool_and | -| :------------ | --------------: | -| Concord | false | -| Hayward | false | -| San Francisco | false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bool_or - -Returns `true` if _any_ non-null input value is `true`, otherwise returns `false`. - -```sql -bool_or(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bool_or` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bool_or(precip > 0) AS precip_bool_or -FROM weather -GROUP BY location -``` - -| location | precip_bool_or | -| :------------ | -------------: | -| Concord | true | -| Hayward | true | -| San Francisco | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### count - -Returns the number of rows in the specified column. - -Count includes _null_ values in the total count. -To exclude _null_ values from the total count, include ` IS NOT NULL` -in the `WHERE` clause. - -```sql -count(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `count` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - count(precip) AS precip_count -FROM weather -GROUP BY location -``` - -| location | precip_count | -| :------------ | -----------: | -| Concord | 1094 | -| Hayward | 1096 | -| San Francisco | 1096 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### first_value - -Returns the first element in an aggregation group according to the specified ordering. -If no ordering is specified, returns an arbitrary element from the group. - -```sql -first_value(expression [ORDER BY expression]) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `first_value` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - first_value(temp_max ORDER BY time) AS temp_max_first_value -FROM weather -GROUP BY location -``` - -| location | temp_max_first_value | -| :------------ | -------------------: | -| Concord | 59 | -| Hayward | 57 | -| San Francisco | 66 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### last_value - -Returns the last element in an aggregation group according to the specified ordering. -If no ordering is specified, returns an arbitrary element from the group. - -```sql -last_value(expression [ORDER BY expression]) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `last_value` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - last_value(temp_max ORDER BY time) AS temp_max_last_value -FROM weather -GROUP BY location -``` - -| location | temp_max_last_value | -| :------------ | ------------------: | -| Concord | 59 | -| Hayward | 58 | -| San Francisco | 62 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### max - -Returns the maximum value in the specified column. - -```sql -max(expression) -``` - -_To return both the maximum value and its associated timestamp, use -[`selector_max`](/influxdb/cloud-dedicated/reference/sql/functions/selector/#selector_max)._ - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `max` query example" %}} - -```sql -SELECT - location, - max(water_level) AS water_level_max -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_max | -| :----------- | --------------: | -| santa_monica | 7.205 | -| coyote_creek | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### mean - -_Alias of [avg](#avg)._ - -### median - -Returns the median value in the specified column. - -``` -median(expression) -``` - -#### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `median` query example" %}} - -```sql -SELECT - location, - median(water_level) AS water_level_max -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_median | -| :----------- | -----------------: | -| coyote_creek | 5.4645 | -| santa_monica | 3.471 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### min - -Returns the minimum value in the specified column. - -```sql -min(expression) -``` - -_To return both the minimum value and its associated timestamp, use -[`selector_max`](/influxdb/cloud-dedicated/reference/sql/functions/selector/#selector_min)._ - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `min` query example" %}} - -```sql -SELECT - location, - min(water_level) AS water_level_min -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_min | -| :----------- | --------------: | -| coyote_creek | -0.61 | -| santa_monica | -0.243 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### sum - -Returns the sum of all values in the specified column. - -```sql -sum(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sum` query example" %}} - -```sql -SELECT - location, - sum(water_level) AS water_level_sum -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_sum | -| :----------- | -----------------: | -| santa_monica | 27024.070369358 | -| coyote_creek | 40750.918963991004 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - -## Statistical aggregate functions - -- [corr](#corr) -- [covar](#covar) -- [covar_pop](#covar_pop) -- [covar_samp](#covar_samp) -- [stddev](#stddev) -- [stddev_pop](#stddev_pop) -- [stddev_samp](#stddev_samp) -- [var](#var) -- [var_pop](#var_pop) -- [var_samp](#var_samp) - -### corr - -Returns the coefficient of correlation between two numeric values. - -```sql -corr(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `corr` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - corr(hum, temp) AS correlation -FROM home -GROUP BY room -``` - -| room | correlation | -| :---------- | ------------------: | -| Living Room | 0.43665270457835725 | -| Kitchen | 0.6741766954929539 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar - -Returns the covariance of a set of number pairs. - -```sql -covar(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar(hum, temp) AS covar -FROM home -GROUP BY room -``` - -| room | covar | -| :---------- | ------------------: | -| Living Room | 0.03346153846153959 | -| Kitchen | 0.11134615384615432 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar_pop - -Returns the population covariance of a set of number pairs. - -```sql -covar_pop(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar_pop(hum, temp) AS covar_pop -FROM home -GROUP BY room -``` - -| room | covar_pop | -| :---------- | -------------------: | -| Kitchen | 0.10278106508875783 | -| Living Room | 0.030887573964498087 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar_samp - -Returns the sample covariance of a set of number pairs. - -```sql -covar_samp(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar_samp(hum, temp) AS covar_samp -FROM home -GROUP BY room -``` - -| room | covar_samp | -| :---------- | ------------------: | -| Kitchen | 0.11134615384615432 | -| Living Room | 0.03346153846153959 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_avgx - -Computes the average of the independent variable (input), `expression_x`, for the -non-null dependent variable, `expression_y`. - -```sql -regr_avgx(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_avgx` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_avgx(temp_min, temp_max) AS temp_regr_avgx -FROM weather -GROUP BY location -``` - -| location | temp_regr_avgx | -| :------------ | ----------------: | -| Concord | 75.54379562043796 | -| Hayward | 69.14808043875686 | -| San Francisco | 67.59945255474454 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_avgy - -Computes the average of the dependent variable (output), `expression_y`, for the -non-null dependent variable, `expression_y`. - -```sql -regr_avgy(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_avgy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_avgy(temp_min, temp_max) AS temp_regr_avgy -FROM weather -GROUP BY location -``` - -| location | temp_regr_avgy | -| :------------ | -----------------: | -| Concord | 50.153284671532845 | -| Hayward | 50.913162705667276 | -| San Francisco | 51.52372262773722 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_count - -Counts the number of non-null paired data points. - -```sql -regr_count(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_count` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_count(temp_min, temp_max) AS temp_regr_count -FROM weather -GROUP BY location -``` - -| location | temp_regr_count | -| :------------ | --------------: | -| Concord | 1096 | -| Hayward | 1094 | -| San Francisco | 1096 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_intercept - -Computes the y-intercept of the linear regression line. -For the equation `(y = kx + b)`, this function returns `b`. - -```sql -regr_intercept(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_intercept` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_intercept(temp_min, temp_max) AS temp_regr_intercept -FROM weather -GROUP BY location -``` - -| location | temp_regr_intercept | -| :------------ | ------------------: | -| Concord | 11.636281392206769 | -| Hayward | 12.876956842745152 | -| San Francisco | 19.125237647086607 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_r2 - -Computes the square of the correlation coefficient between the independent and -dependent variables. - -```sql -regr_r2(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_r2` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_r2(temp_min, temp_max) AS temp_regr_r2 -FROM weather -GROUP BY location -``` - -| location | temp_regr_r2 | -| :------------ | -----------------: | -| Concord | 0.6474628308450441 | -| Hayward | 0.5166296626320914 | -| San Francisco | 0.5032317511200297 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_slope - -Returns the slope of the linear regression line for non-null pairs in aggregate columns. -Given input column `Y` and `X`: `regr_slope(Y, X)` returns the slope -(`k` in `Y = k*X + b`) using minimal RSS fitting. - -``` sql -regr_slope(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Y expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: X expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_slope` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_slope(temp_min, temp_max) AS temp_regr_slope -FROM weather -GROUP BY location -``` - -| location | temp_regr_slope | -| :------------ | -----------------: | -| Concord | 0.5098632252058237 | -| Hayward | 0.5500688612261629 | -| San Francisco | 0.4792714105844738 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_sxx - -Computes the sum of squares of the independent variable. - -```sql -regr_sxx(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_sxx` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_sxx(temp_min, temp_max) AS temp_regr_sxx -FROM weather -GROUP BY location -``` - -| location | temp_regr_sxx | -| :------------ | -----------------: | -| Concord | 210751.89781021897 | -| Hayward | 99644.01096892142 | -| San Francisco | 77413.15967153282 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_syy - -Computes the sum of squares of the dependent variable. - -```sql -regr_syy(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_syy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_syy(temp_min, temp_max) AS temp_regr_syy -FROM weather -GROUP BY location -``` - -| location | temp_regr_syy | -| :------------ | -----------------: | -| Concord | 84618.24817518248 | -| Hayward | 58358.750457038404 | -| San Francisco | 35335.38321167884 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_sxy - -Computes the sum of products of paired data points. - -```sql -regr_sxy(expression_y, expression_x) -``` - -#### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_sxy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_sxy(temp_min, temp_max) AS temp_regr_sxy -FROM weather -GROUP BY location -``` - -| location | temp_regr_sxy | -| :------------ | -----------------: | -| Concord | 107454.64233576645 | -| Hayward | 54811.06764168191 | -| San Francisco | 37101.914233576645 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev - -Returns the standard deviation of a set of numbers. - -```sql -stddev(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev(co) AS stddev -FROM home -GROUP BY room -``` - -| room | stddev | -| :---------- | ----------------: | -| Living Room | 5.885662718931967 | -| Kitchen | 9.321879418735037 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev_pop - -Returns the population standard deviation of a set of numbers. - -```sql -stddev_pop(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev_pop(co) AS stddev_pop -FROM home -GROUP BY room -``` - -| room | stddev_pop | -| :---------- | ----------------: | -| Kitchen | 8.956172047894082 | -| Living Room | 5.654761830612032 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev_samp - -Returns the sample standard deviation of a set of numbers. - -```sql -stddev_samp(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev_samp(co) AS stddev_samp -FROM home -GROUP BY room -``` - -| room | stddev_samp | -| :---------- | ----------------: | -| Living Room | 5.885662718931967 | -| Kitchen | 9.321879418735037 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var - -Returns the statistical variance of a set of numbers. - -```sql -var(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var(co) AS var -FROM home -GROUP BY room -``` - -| room | var | -| :---------- | ----------------: | -| Living Room | 34.64102564102564 | -| Kitchen | 86.89743589743587 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var_pop - -Returns the statistical population variance of a set of numbers. - -```sql -var_pop(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var_pop(co) AS var_pop -FROM home -GROUP BY room -``` - -| room | var_pop | -| :---------- | -----------------: | -| Living Room | 31.976331360946745 | -| Kitchen | 80.21301775147927 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var_samp - -Returns the statistical sample variance of a set of numbers. - -```sql -var_samp(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var_samp(co) AS var_samp -FROM home -GROUP BY room -``` - -| room | var_samp | -| :---------- | ----------------: | -| Kitchen | 86.89743589743587 | -| Living Room | 34.64102564102564 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Approximate aggregate functions - -- [approx_distinct](#approx_distinct) -- [approx_median](#approx_median) -- [approx_percentile_cont](#approx_percentile_cont) -- [approx_percentile_cont_with_weight](#approx_percentile_cont_with_weight) - -### approx_distinct - -Returns the approximate number of distinct input values calculated using the -HyperLogLog algorithm. - -```sql -approx_distinct(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `approx_distinct` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_distinct(co::string) AS approx_distinct -FROM home -GROUP BY room -``` - -| room | approx_distinct | -| :---------- | --------------: | -| Living Room | 7 | -| Kitchen | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_median - -Returns the approximate median (50th percentile) of input values. -It is an alias of `approx_percentile_cont(x, 0.5)`. - -```sql -approx_median(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `approx_median` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_median(temp) AS approx_median -FROM home -GROUP BY room -``` - -| room | approx_median | -| :---------- | ------------: | -| Kitchen | 22.7 | -| Living Room | 22.3 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_percentile_cont - -Returns the approximate percentile of input values using the t-digest algorithm. - -```sql -approx_percentile_cont(expression, percentile, centroids) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). -- **centroids**: Number of centroids to use in the t-digest algorithm. _Default is 100_. - - If there are this number or fewer unique values, you can expect an exact result. - A higher number of centroids results in a more accurate approximation, but - requires more memory to compute. - -{{< expand-wrapper >}} -{{% expand "View `approx_percentile_cont` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_percentile_cont(temp, 0.99) AS "99th_percentile" -FROM home -GROUP BY room -``` - -| room | 99th_percentile | -| :---------- | --------------: | -| Kitchen | 23.3 | -| Living Room | 22.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_percentile_cont_with_weight - -Returns the weighted approximate percentile of input values using the -t-digest algorithm. - -```sql -approx_percentile_cont_with_weight(expression, weight, percentile) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **weight**: Expression to use as weight. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). - -{{< expand-wrapper >}} -{{% expand "View `approx_percentile_cont_with_weight` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_percentile_cont_with_weight(temp, co, 0.99) AS "co_weighted_99th_percentile" -FROM home -GROUP BY room -``` - -| room | co_weighted_99th_percentile | -| :---------- | --------------------------: | -| Kitchen | 23.3 | -| Living Room | 22.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/conditional.md b/content/influxdb/cloud-dedicated/reference/sql/functions/conditional.md index eced9f4d3..82dfd78e8 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/conditional.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/conditional.md @@ -8,137 +8,10 @@ menu: name: Conditional parent: sql-functions weight: 306 + +source: /content/shared/sql-reference/functions/conditional.md --- -The InfluxDB SQL implementation supports the following conditional functions for -conditionally handling _null_ values: - -- [coalesce](#coalesce) -- [ifnull](#ifnull) -- [nullif](#nullif) -- [nvl](#nvl) - -## coalesce - -Returns the first of its arguments that is not _null_. -Returns _null_ if all arguments are _null_. -This function is often used to substitute a default value for _null_ values. - -```sql -coalesce(expression1[, ..., expression_n]) -``` - -##### Arguments - -- **expression1, expression_n**: - Expression to use if previous expressions are _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. - Pass as many expression arguments as necessary. - -{{< expand-wrapper >}} -{{% expand "View `coalesce` query example" %}} - -```sql -SELECT - val1, - val2, - val3, - coalesce(val1, val2, val3, 'quz') AS coalesce -FROM - (values ('foo', 'bar', 'baz'), - (NULL, 'bar', 'baz'), - (NULL, NULL, 'baz'), - (NULL, NULL, NULL) - ) data(val1, val2, val3) -``` - -| val1 | val2 | val3 | coalesce | -| :--: | :--: | :--: | :------: | -| foo | bar | baz | foo | -| | bar | baz | bar | -| | | baz | baz | -| | | | quz | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ifnull - -_Alias of [nvl](#nvl)._ - -## nullif - -Returns _null_ if _expression1_ equals _expression2_; otherwise it returns _expression1_. -This can be used to perform the inverse operation of [`coalesce`](#coalesce). - -```sql -nullif(expression1, expression2) -``` - -##### Arguments - -- **expression1**: Expression to compare and return if equal to expression2. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression2**: Expression to compare to expression1. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nullif` query example" %}} - -```sql -SELECT - value, - nullif(value, 'baz') AS nullif -FROM - (values ('foo'), - ('bar'), - ('baz') - ) data(value) -``` - -| value | nullif | -| :---- | :----- | -| foo | foo | -| bar | bar | -| baz | | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## nvl - -Returns _expression2_ if _expression1_ is _null_; otherwise it returns _expression1_. - -```sql -nvl(expression1, expression2) -``` - -##### Arguments - -- **expression1**: Return this expression if not _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression2**: Return this expression if _expression1_ is _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nvl` query example" %}} - -```sql -SELECT - value, - nvl(value, 'baz') AS nvl -FROM - (values ('foo'), - ('bar'), - (NULL) - ) data(value) -``` - -| value | nvl | -| :---- | :-- | -| foo | foo | -| bar | bar | -| | baz | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/math.md b/content/influxdb/cloud-dedicated/reference/sql/functions/math.md index 29e494630..b96c3302a 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/math.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/math.md @@ -8,1276 +8,10 @@ menu: name: Math parent: sql-functions weight: 306 + +source: /content/shared/sql-reference/functions/math.md --- -The InfluxDB SQL implementation supports the following math functions for -performing mathematic operations: - -- [abs](#abs) -- [acos](#acos) -- [acosh](#acosh) -- [asin](#asin) -- [asinh](#asinh) -- [atan](#atan) -- [atanh](#atanh) -- [atan2](#atan2) -- [cbrt](#cbrt) -- [ceil](#ceil) -- [cos](#cos) -- [cosh](#cosh) -- [degrees](#degrees) -- [exp](#exp) -- [factorial](#factorial) -- [floor](#floor) -- [gcd](#gcd) -- [isnan](#isnan) -- [iszero](#iszero) -- [lcm](#lcm) -- [ln](#ln) -- [log](#log) -- [log10](#log10) -- [log2](#log2) -- [nanvl](#nanvl) -- [pi](#pi) -- [power](#power) -- [pow](#pow) -- [radians](#radians) -- [random](#random) -- [round](#round) -- [signum](#signum) -- [sin](#sin) -- [sinh](#sinh) -- [sqrt](#sqrt) -- [tan](#tan) -- [tanh](#tanh) -- [trunc](#trunc) - -## abs - -Returns the absolute value of a number. - -```sql -abs(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `abs` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT abs(temp) AS abs FROM home LIMIT 3 -``` - -| abs | -| ---: | -| 21 | -| 23 | -| 22.7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## acos - -Returns the arc cosine or inverse cosine of a number. - -```sql -acos(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `acos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT acos(temp * .01) AS acos FROM home LIMIT 3 -``` - -| acos | -| -----------------: | -| 1.359221367036801 | -| 1.3387186439321834 | -| 1.3418001704498232 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## acosh - -Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. - -```sql -acosh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `acosh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT acosh(temp) AS acosh FROM home LIMIT 3 -``` - -| acosh | -| -----------------: | -| 3.737102242198924 | -| 3.8281684713331012 | -| 3.8150265878962055 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## asin - -Returns the arc sine or inverse sine of a number. - -```sql -asin(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `asin` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT asin(temp * .01) AS asin FROM home LIMIT 3 -``` - -| asin | -| ------------------: | -| 0.2115749597580956 | -| 0.23207768286271319 | -| 0.22899615634507337 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## asinh - -Returns the area hyperbolic sine or inverse hyperbolic sine of a number. - -```sql -asinh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `asinh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT asinh(temp) AS asinh FROM home LIMIT 3 -``` - -| asinh | -| -----------------: | -| 3.7382360302615427 | -| 3.8291136516208812 | -| 3.8159969160459988 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atan - -Returns the arc tangent or inverse tangent of a number. - -```sql -atan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atan` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atan(temp * .01) AS atan FROM home LIMIT 3 -``` - -| atan | -| ------------------: | -| 0.206992194219821 | -| 0.22606838799388393 | -| 0.22321725383717603 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atanh - -Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. - -```sql -atanh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atanh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atanh(temp * .01) AS atanh FROM home LIMIT 3 -``` - -| atanh | -| ------------------: | -| 0.21317134656485978 | -| 0.2341894667593668 | -| 0.23102419806174476 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atan2 - -Returns the arc tangent or inverse tangent of `expression_y / expression_x`. - -```sql -atan2(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: First numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Second numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atan2` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atan2(temp, hum) AS atan2 FROM home LIMIT 3 -``` - -| atan2 | -| -----------------: | -| 0.5292859396993504 | -| 0.5660139100632452 | -| 0.5613335864315844 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cbrt - -Returns the cube root of a number. - -```sql -cbrt(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cbrt` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cbrt(temp) AS cbrt FROM home LIMIT 3 -``` - -| cbrt | -| -----------------: | -| 2.7589241763811208 | -| 2.843866979851566 | -| 2.831448188528187 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ceil - -Returns the nearest integer greater than or equal to a number. - -```sql -ceil(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `ceil` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT ceil(temp) AS ceil FROM home LIMIT 3 -``` - -| ceil | -| ---: | -| 21 | -| 23 | -| 23 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cos - -Returns the cosine of a number. - -```sql -cos(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cos(temp) AS cos FROM home LIMIT 3 -``` - -| cos | -| ------------------: | -| -0.5477292602242684 | -| -0.5328330203333975 | -| -0.7591100556583898 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cosh - -Returns the hyperbolic cosine of a number. - -```sql -cosh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cosh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cosh(temp) AS cosh FROM home LIMIT 3 -``` - -| cosh | -| -----------------: | -| 659407867.2416073 | -| 4872401723.124452 | -| 3609563974.9715896 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## degrees - -Converts radians to degrees. - -```sql -degrees(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `degrees` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT degrees(a) AS degrees FROM numbers LIMIT 3 -``` - -| degrees | -| ------------------: | -| 19.428488139031185 | -| -44.403317464348774 | -| -52.771542485064785 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## exp - -Returns the base-e exponential of a number. - -```sql -exp(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to use as the exponent. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `exp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT exp(temp) AS exp FROM home LIMIT 3 -``` - -| exp | -| -----------------: | -| 1318815734.4832146 | -| 9744803446.248903 | -| 7219127949.943179 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## factorial - -Returns 1 if value is less than 2. - -```sql -factorial(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `factorial` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT factorial((b + 2)::BIGINT) AS factorial FROM numbers LIMIT 3 -``` - -| factorial | -| --------: | -| 1 | -| 2 | -| 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## floor - -Returns the nearest integer less than or equal to a number. - -```sql -floor(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `floor` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT floor(temp) AS floor FROM home LIMIT 3 -``` - -| floor | -| ----: | -| 21 | -| 23 | -| 22 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## gcd - -Returns the greatest common divisor of `expression_x` and `expression_y`. -Returns `0` if both inputs are zero. - -```sql -gcd(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: First numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Second numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `gcd` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT gcd((a * 5)::BIGINT, (b * 5)::BIGINT) AS gcd FROM numbers LIMIT 3 -``` - -| gcd | -| --------: | -| 1 | -| 3 | -| 2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## isnan - -Returns `true` if a given number is ±NaN, otherwise returns `false`. - -```sql -isnan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Must be a float (`DOUBLE`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `isnan` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/cloud-dedicated/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT isnan(a) -FROM - (VALUES (4.56), - ('NaN'::DOUBLE), - (16.2) - ) AS data(a) -``` - -| isnan | -| ----: | -| false | -| true | -| false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## iszero - -Returns `true` if the given number is ±0.0, otherwise returns `false`. - -```sql -iszero(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `iszero` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/cloud-dedicated/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT iszero(a) -FROM - (VALUES (0), - (1), - (2) - ) AS data(a) -``` - -| iszero | -| -----: | -| true | -| false | -| false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lcm - -Returns the least common multiple of `expression_x` and `expression_y`. -Returns `0` if either input is zero. - -```sql -lcm(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: First numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Second numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `lcm` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT lcm((a * 10)::BIGINT, (b * 10)::BIGINT) AS lcm FROM numbers LIMIT 3 -``` - -| lcm | -| --: | -| 3 | -| 7 | -| 36 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ln - -Returns the natural logarithm of a number. - -```sql -ln(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `ln` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT ln(temp) AS ln FROM home LIMIT 3 -``` - -| ln | -| -----------------: | -| 3.044522437723423 | -| 3.1354942159291497 | -| 3.122364924487357 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log - -Returns the base-x logarithm of a number. - -``` -log([base, ]numeric_expression) -``` - -#### Arguments - -- **base**: Base numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - Default is `10`. -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - temp, - log(2, temp) AS temp_log2, - log(4, temp) AS temp_log4, - log(temp) AS temp_log10 -FROM home -LIMIT 3 -``` - -| temp | temp_log2 | temp_log4 | temp_log10 | -| :--- | ----------------: | -----------------: | -----------------: | -| 21 | 4.392317422778761 | 2.1961587113893803 | 1.322219294733919 | -| 23 | 4.523561956057013 | 2.2617809780285065 | 1.3617278360175928 | -| 22.7 | 4.504620392403553 | 2.2523101962017766 | 1.3560258571931225 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log10 - -Returns the base-10 logarithm of a number. - -```sql -log10(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log10` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT log10(temp) AS log10 FROM home LIMIT 3 -``` - -| log10 | -| -----------------: | -| 1.3222192947339193 | -| 1.3617278360175928 | -| 1.3560258571931227 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log2 - -Returns the base-2 logarithm of a number. - -```sql -log2(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log2` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT log2(temp) AS log2 FROM home LIMIT 3 -``` - -| log2 | -| ----------------: | -| 4.392317422778761 | -| 4.523561956057013 | -| 4.504620392403552 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## nanvl - -Returns the first argument if it’s not `±NaN`. -Otherwise returns the second argument. - -```sql -nanvl(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: Numeric expression to return if it’s not `NaN`. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Numeric expression to return if the first expression is `NaN`. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nanvl` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/cloud-dedicated/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT nanvl(a, 0.0) AS nanvl -FROM - (VALUES (4.56), - ('NaN'::DOUBLE), - (16.2) - ) AS data(a) -``` - -| nanvl | -| ----: | -| 4.56 | -| 0 | -| 16.2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## pi - -Returns an approximate value of π. - -```sql -pi() -``` - -{{< expand-wrapper >}} -{{% expand "View `pi` query example" %}} - -```sql -SELECT pi() AS pi -``` - -| pi | -| :---------------- | -| 3.141592653589793 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## power - -Returns a base expression raised to the power of an exponent. - -```sql -power(base, exponent) -``` - -##### Aliases - -- `pow` - -##### Arguments - -- **base**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **exponent**: Exponent numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `power` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT power(temp, hum * .1) AS power FROM home LIMIT 3 -``` - -| power | -| -----------------: | -| 55817.099910217476 | -| 85007.01501569824 | -| 78569.38332452129 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `pow` - -_Alias of [power](#power)._ - -## radians - -Converts degrees to radians. - -```sql -radians(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `radians` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT radians(b) AS radians FROM numbers LIMIT 3 -``` - -| radians | -| --------------------: | -| -0.0028561101762876 | -| 0.0023917008411179744 | -| -0.008428949313343818 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## random - -Returns a random float value between 0 and 1. -The random seed is unique to each row. - -```sql -random() -``` - -{{< expand-wrapper >}} -{{% expand "View `random` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT temp * random() AS random FROM home LIMIT 3 -``` - -{{% note %}} -Due to the nature of the function, your results will not match the results below. -{{% /note %}} - -| random | -| -----------------: | -| 0.5030770374815072 | -| 12.938847036567514 | -| 2.8204596545385385 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## round - -Rounds a number to the nearest integer. - -```sql -round(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `round` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT round(temp) AS round FROM home LIMIT 3 -``` - -| round | -| ----: | -| 21 | -| 23 | -| 23 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## signum - -Returns the sign of a number. -Negative numbers return `-1`. -Zero and positive numbers return `1`. - -```sql -signum(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `signum` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT signum(temp - 23) AS signum FROM home LIMIT 3 -``` - -| signum | -| -----: | -| -1 | -| 1 | -| -1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sin - -Returns the sine of a number. - -```sql -sin(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sin` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sin(temp) AS sin FROM home LIMIT 3 -``` - -| sin | -| ------------------: | -| 0.8366556385360561 | -| -0.8462204041751706 | -| -0.6509623056662469 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sinh - -Returns the hyperbolic sine of a number. - -```sql -sinh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sinh ` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sinh(temp) AS sinh FROM home LIMIT 3 -``` - -| sinh | -| -----------------: | -| 659407867.2416073 | -| 4872401723.124452 | -| 3609563974.9715896 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sqrt - -Returns the square root of a number. - -```sql -sqrt(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sqrt` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sqrt(temp) AS sqrt FROM home LIMIT 3 -``` - -| sqrt | -| ----------------: | -| 4.58257569495584 | -| 4.795831523312719 | -| 4.764451699828638 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## tan - -Returns the tangent of a number. - -```sql -tan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `tan` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT tan(temp) AS tan FROM home LIMIT 3 -``` - -| tan | -| ------------------: | -| -1.5274985276366035 | -| 1.5881530833912738 | -| 0.8575335036257101 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## tanh - -Returns the hyperbolic tangent of a number. - -```sql -tanh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `tanh` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT tanh(a) AS tanh FROM numbers LIMIT 3 -``` - -| tanh | -| ------------------: | -| 0.32666571332086836 | -| -0.6498182711525403 | -| -0.7263877015335474 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## trunc - -Truncates a number toward zero (at the decimal point). - -```sql -trunc(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `trunc` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT trunc(temp) AS trunc FROM home LIMIT 3 -``` - -| trunc | -| ----: | -| 21 | -| 23 | -| 22 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/misc.md b/content/influxdb/cloud-dedicated/reference/sql/functions/misc.md index 189fbe5cb..d92fbd86c 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/misc.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/misc.md @@ -8,239 +8,10 @@ menu: name: Miscellaneous parent: sql-functions weight: 310 + +source: /content/shared/sql-reference/functions/misc.md --- -The InfluxDB SQL implementation supports the following miscellaneous functions -for performing a variety of operations: - -- [arrow_cast](#arrow_cast) -- [arrow_typeof](#arrow_typeof) -- [interpolate](#interpolate) -- [locf](#locf) - - -## arrow_cast - -Casts a value to a specific Arrow data type. - -```sql -arrow_cast(expression, datatype) -``` - -#### Arguments - -- **expression**: Expression to cast. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. -- **datatype**: [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) - to cast to. - -{{< expand-wrapper >}} -{{% expand "View `arrow_cast` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - arrow_cast(time, 'Int64') AS time, - arrow_cast(temp, 'Utf8') AS temp, - arrow_cast(co, 'Float64')AS co -FROM home -LIMIT 1 -``` - -| time | temp | co | -| :------------------ | ---: | --: | -| 1641024000000000000 | 21.0 | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## arrow_typeof - -Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) -of the the expression: - -```sql -arrow_typeof(expression) -``` - -##### Arguments - -- **expression**: Expression to evaluate. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. - -{{< expand-wrapper >}} -{{% expand "View `arrow_typeof` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - arrow_typeof(time) AS time, - arrow_typeof(room) AS room, - arrow_typeof(temp) AS temp, - arrow_typeof(co) AS co -FROM home -LIMIT 1 -``` - -| time | room | temp | co | -| :-------------------------- | :---------------------- | :------ | :---- | -| Timestamp(Nanosecond, None) | Dictionary(Int32, Utf8) | Float64 | Int64 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## interpolate - -Fills null values in a specified aggregated column by interpolating values -from existing values. -Must be used with [`date_bin_gapfill`](/influxdb/cloud-dedicated/reference/sql/functions/time-and-date/#date_bin_gapfill). - -```sql -interpolate(aggregate_expression) -``` - -##### Arguments - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/cloud-dedicated/reference/sql/functions/aggregate/). - The expression can be a constant, column, or function, and any combination of - arithmetic operators supported by the aggregate function. - -##### Related functions - -[date_bin_gapfill](/influxdb/cloud-dedicated/reference/sql/functions/time-and-date/#date_bin_gapfill), -[locf](#locf) - -{{< expand-wrapper >}} -{{% expand "View `interpolate` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - interpolate(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 22 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 22.85 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.25 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.6 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## locf - -Fills null values in a specified aggregated column by carrying the last observed -value forward. -Must be used with [`date_bin_gapfill`](/influxdb/cloud-dedicated/reference/sql/functions/time-and-date/#date_bin_gapfill). - -_LOCF is an initialism of "last observation carried forward."_ - -```sql -locf(aggregate_expression) -``` - -##### Arguments - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/cloud-dedicated/reference/sql/functions/aggregate/). - The expression can be a constant, column, or function, and any combination of - arithmetic operators supported by the aggregate function. - -##### Related functions - -[date_bin_gapfill](/influxdb/cloud-dedicated/reference/sql/functions/time-and-date/#date_bin_gapfill), -[interpolate](#interpolate) - -{{< expand-wrapper >}} -{{% expand "View `locf` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - locf(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 21 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 23 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - - diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/regular-expression.md b/content/influxdb/cloud-dedicated/reference/sql/functions/regular-expression.md index f45693db6..2a8211bf9 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/regular-expression.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/regular-expression.md @@ -9,145 +9,10 @@ menu: parent: sql-functions weight: 308 influxdb/cloud-dedicated/tags: [regular expressions, sql] + +source: /content/shared/sql-reference/functions/regular-expression.md --- -The InfluxDB SQL implementation uses the -[PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions) -regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax) -(excluding some features such as look-around and back-references) and supports -the following regular expression functions: - -- [regexp_like](#regexp_like) -- [regexp_match](#regexp_match) -- [regexp_replace](#regexp_replace) - -## regexp_like - -True if a regular expression has at least one match in a string; -false otherwise. - -```sql -regexp_like(str, regexp[, flags]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to test against the string expression. - Can be a constant, column, or function. -- **flags**: Optional regular expression flags that control the behavior of the - regular expression. The following flags are supported: - - **i**: (insensitive) Ignore case when matching. - - **m**: (multi-line) `^` and `$` match the beginning and end of a line, respectively. - - **s**: (single-line) `.` matches newline (`\n`). - - **R**: (CRLF) When multi-line mode is enabled, `\r\n` is used to delimit lines. - - **U**: (ungreedy) Swap the meaning of `x*` and `x*?`. - -{{< expand-wrapper >}} -{{% expand "View `regexp_replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - regexp_like(room::STRING, 'R', 'i') AS regexp_like -FROM home -``` - -| room | regexp_like | -| :---------- | :---------- | -| Kitchen | false | -| Living Room | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## regexp_match - -Returns a list of regular expression matches in a string. - -```sql -regexp_match(str, regexp, flags) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to match against. - Can be a constant, column, or function. -- **flags**: Regular expression flags that control the behavior of the - regular expression. The following flags are supported. - - **i**: (insensitive) Ignore case when matching. - -{{< expand-wrapper >}} -{{% expand "View `regexp_replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -{{% note %}} -`regexp_match` returns a _list_ Arrow type, which is not supported by InfluxDB. -Use _bracket notation_ to reference a value in the list. -Lists use 1-based indexing. -{{% /note %}} - -```sql -SELECT DISTINCT - room, - regexp_match(room::STRING, '.{3}')[1] AS regexp_match -FROM home -``` - -| room | regexp_match | -| :---------- | :----------- | -| Kitchen | Kit | -| Living Room | Liv | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## regexp_replace - -Replaces substrings in a string that match a regular expression. - -```sql -regexp_replace(str, regexp, replacement, flags) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to match against. - Can be a constant, column, or function. -- **replacement**: Replacement string expression. - Can be a constant, column, or function, and any combination of string operators. -- **flags**: Regular expression flags that control the behavior of the - regular expression. The following flags are supported. - - **g**: (global) Search globally and don't return after the first match. - - **i**: (insensitive) Ignore case when matching. - -{{< expand-wrapper >}} -{{% expand "View `regexp_replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - regexp_replace(room::STRING, '\sRoom', '', 'gi') AS regexp_replace -FROM home -``` - -| room | regexp_replace | -| :---------- | :------------- | -| Kitchen | Kitchen | -| Living Room | Living | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/selector.md b/content/influxdb/cloud-dedicated/reference/sql/functions/selector.md index 855f18c17..1bd067704 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/selector.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/selector.md @@ -10,191 +10,10 @@ menu: weight: 302 related: - /influxdb/cloud-dedicated/query-data/sql/aggregate-select/ + +source: /content/shared/sql-reference/functions/selector.md --- -SQL selector functions are designed to work with time series data. -They behave similarly to aggregate functions in that they take a collection of -data and return a single value. -However, selectors are unique in that they return a _struct_ that contains -a **time value** in addition to the computed value. - -- [How do selector functions work?](#how-do-selector-functions-work) -- [Selector functions](#selector-functions) - - [selector_min](#selector_min) - - [selector_max](#selector_max) - - [selector_first](#selector_first) - - [selector_last](#selector_last) - -## How do selector functions work? - -Each selector function returns an [Arrow _struct_](https://arrow.apache.org/docs/format/Columnar.html#struct-layout) -(similar to a JSON object) representing a single time and value from the -specified column in the each group. -What time and value get returned depend on the logic in the selector function. -For example, `selector_first` returns the value of specified column in the first row of the group. -`selector_max` returns the maximum value of the specified column in the group. - -### Selector struct schema - -The struct returned from a selector function has two properties: - -- **time**: `time` value in the selected row -- **value**: value of the specified column in the selected row - -```js -{time: 2023-01-01T00:00:00Z, value: 72.1} -``` - -### Selector functions in use - -In your `SELECT` statement, execute a selector function and use bracket notation -to reference properties of the [returned struct](#selector-struct-schema) to -populate the column value: - -```sql -SELECT - selector_first(temp, time)['time'] AS time, - selector_first(temp, time)['value'] AS temp, - room -FROM home -GROUP BY room -``` - -## Selector functions - -- [selector_min](#selector_min) -- [selector_max](#selector_max) -- [selector_first](#selector_first) -- [selector_last](#selector_last) - -### selector_min - -Returns the smallest value of a selected column and a timestamp. - -```sql -selector_min(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_min` query example" %}} - -```sql -SELECT - selector_min(water_level, time)['time'] AS time, - selector_min(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T14:30:00Z | -0.61 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_max - -Returns the largest value of a selected column and a timestamp. - -```sql -selector_max(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_max` query example" %}} - -```sql -SELECT - selector_max(water_level, time)['time'] AS time, - selector_max(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T07:24:00Z | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_first - -Returns the first value ordered by time ascending. - -```sql -selector_first(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_first` query example" %}} - -```sql -SELECT - selector_first(water_level, time)['time'] AS time, - selector_first(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T07:24:00Z | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_last - -Returns the last value ordered by time ascending. - -```sql -selector_last(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_last` query example" %}} - -```sql -SELECT - selector_last(water_level, time)['time'] AS time, - selector_last(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-09-17T21:42:00Z | 4.938 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/string.md b/content/influxdb/cloud-dedicated/reference/sql/functions/string.md index 700ce122a..33d9e2312 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/string.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/string.md @@ -8,1498 +8,10 @@ menu: name: String parent: sql-functions weight: 307 + +source: /content/shared/sql-reference/functions/string.md --- -The InfluxDB SQL implementation supports the following string functions for -operating on string values: - -- [ascii](#ascii) -- [bit_length](#bit_length) -- [btrim](#btrim) -- [char_length](#char_length) -- [character_length](#character_length) -- [concat](#concat) -- [concat_ws](#concat_ws) -- [chr](#chr) -- [ends_with](#ends_with) -- [find_in_set](#find_in_set) -- [initcap](#initcap) -- [instr](#instr) -- [left](#left) -- [length](#length) -- [levenshtein](#levenshtein) -- [lower](#lower) -- [lpad](#lpad) -- [ltrim](#ltrim) -- [md5](#md5) -- [octet_length](#octet_length) -- [overlay](#overlay) -- [position](#position) -- [repeat](#repeat) -- [replace](#replace) -- [reverse](#reverse) -- [right](#right) -- [rpad](#rpad) -- [rtrim](#rtrim) -- [split_part](#split_part) -- [starts_with](#starts_with) -- [strpos](#strpos) -- [substr](#substr) -- [substr_index](#substr_index) -- [to_hex](#to_hex) -- [translate](#translate) -- [trim](#trim) -- [upper](#upper) -- [uuid](#uuid) - -## ascii - -Returns the ASCII value of the first character in a string. - -{{% note %}} -`ascii` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -ascii(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[chr](#chr) - -{{< expand-wrapper >}} -{{% expand "View `ascii` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - ascii(room)::BIGINT AS ascii -FROM home -``` - -| room | ascii | -| :---------- | ----: | -| Kitchen | 75 | -| Living Room | 76 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## bit_length - -Returns the bit length of a string. - -{{% note %}} -`bit_length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -bit_length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[length](#length), [octet_length](#octet_length) - -{{< expand-wrapper >}} -{{% expand "View `bit_length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - bit_length(room)::BIGINT AS bit_length -FROM home -``` - -| room | bit_length | -| :---------- | ---------: | -| Living Room | 88 | -| Kitchen | 56 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## btrim - -Trims the specified trim string from the start and end of a string. -If no trim string is provided, all whitespace is removed from the start and end -of the input string. - -```sql -btrim(str[, trim_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **trim_str**: String expression to trim from the beginning and end of the input string. - Can be a constant, column, or function, and any combination of arithmetic operators. - _Default is whitespace characters_. - -##### Related functions - -[ltrim](#ltrim), -[rtrim](#rtrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `btrim` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - btrim(room::STRING, ' Room') AS btrim -FROM home -``` - -| room | btrim | -| :---------- | :------ | -| Living Room | Living | -| Kitchen | Kitchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## char_length - -_Alias of [length](#length)._ - -## character_length - -_Alias of [length](#length)._ - -## concat - -Concatenates multiple strings together. - -```sql -concat(str[, ..., str_n]) -``` - -##### Arguments - -- **str**: String expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. -- **str_n**: Subsequent string expression to concatenate. - -##### Related functions - -[contcat_ws](#contcat_ws) - -{{< expand-wrapper >}} -{{% expand "View `concat` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - concat('At ', time::STRING, ', the ', room, ' was ', temp::STRING, '°C.') AS concat -FROM home -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| concat | -| :---------------------------------------------- | -| At 2022-01-01T08:00:00, the Kitchen was 21.0°C. | -| At 2022-01-01T09:00:00, the Kitchen was 23.0°C. | -| At 2022-01-01T10:00:00, the Kitchen was 22.7°C. | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## concat_ws - -Concatenates multiple strings together with a specified separator. - -```sql -concat_ws(separator, str[, ..., str_n]) -``` - -##### Arguments - -- **separator**: Separator to insert between concatenated strings. -- **str**: String expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. -- **str_n**: Subsequent string expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[concat](#concat) - -{{< expand-wrapper >}} -{{% expand "View `concat_ws` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - concat_ws(' -- ', time::STRING, room, temp::STRING) AS concat_ws -FROM home -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| concat_ws | -| :----------------------------------------- | -| 2022-01-01T08:00:00 \-\- Kitchen \-\- 21.0 | -| 2022-01-01T09:00:00 \-\- Kitchen \-\- 23.0 | -| 2022-01-01T10:00:00 \-\- Kitchen \-\- 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## chr - -Returns the character with the specified ASCII or Unicode code value. - -``` -chr(expression) -``` - -#### Arguments - -- **expression**: Expression containing the ASCII or Unicode code value to operate on. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. - -##### Related functions - -[ascii](#ascii) - -{{< expand-wrapper >}} -{{% expand "View `chr` query example" %}} - -```sql -SELECT - ascii, - chr(ascii) AS chr -FROM - (values (112), - (75), - (214) - ) data(ascii) -``` - -| ascii | chr | -| :---- | :-: | -| 112 | p | -| 75 | K | -| 214 | Ö | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ends_with - -Tests if a string ends with a substring. - -```sql -ends_with(str, substr) -``` - -##### Arguments - -- **str**: String expression to test. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to test for. - -{{< expand-wrapper >}} -{{% expand "View `ends_with` query example" %}} - -```sql -SELECT - string, - ends_with(string, 'USA') AS ends_with -FROM - (values ('New York, USA'), - ('London, UK'), - ('San Francisco, USA') - ) data(string) -``` - -| string | ends_with | -| :----------------- | :-------- | -| New York, USA | true | -| London, UK | false | -| San Francisco, USA | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## find_in_set - -Returns the position of a string in a comma-delimited list of substrings. -Returns 0 if the string is not in the list of substrings. - -```sql -find_in_set(str, strlist) -``` - -##### Arguments - -- **str**: String expression to find in `strlist`. -- **strlist**: A string containing a comma-delimited list of substrings. - -{{< expand-wrapper >}} -{{% expand "View `find_in_set` query example" %}} - -```sql -SELECT - string, - find_in_set(string, 'Isaac,John,Sara') AS find_in_set -FROM - (values ('John'), - ('Sarah'), - ('Isaac') - ) data(string) -``` - -| string | find_in_set | -| :----- | ----------: | -| John | 2 | -| Sarah | 0 | -| Isaac | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## initcap - -Capitalizes the first character in each word in the input string. -Words are delimited by non-alphanumeric characters. - -```sql -initcap(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[lower](#lower), -[upper](#upper) - -{{< expand-wrapper >}} -{{% expand "View `initcap` query example" %}} - -```sql -SELECT - string, - initcap(string) AS initcap -FROM - (values ('hello world'), - ('hello-world'), - ('hello_world') - ) data(string) -``` - -| string | initcap | -| :---------- | :---------- | -| hello world | Hello World | -| hello-world | Hello-World | -| hello_world | Hello_World | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## instr - -Returns the location where a substring first appears in a string (starting at 1). -If the substring is not in the string, the function returns 0. - -```sql -instr(str, substr) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `instr` query example" %}} - -```sql -SELECT - string, - instr(string, 'neighbor') AS instr -FROM - (values ('good neighbor'), - ('bad neighbor'), - ('next-door neighbor'), - ('friend') - ) data(string) -``` - -| string | instr | -| :----------------- | ----: | -| good neighbor | 6 | -| bad neighbor | 5 | -| next-door neighbor | 11 | -| friend | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## left - -Returns a specified number of characters from the left side of a string. - -```sql -left(str, n) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of characters to return. - -##### Related functions - -[right](#right) - -{{< expand-wrapper >}} -{{% expand "View `left` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - left(room::STRING, 3) AS left -FROM home -``` - -| room | left | -| :---------- | :--- | -| Kitchen | Kit | -| Living Room | Liv | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## length - -Returns the number of characters in a string. - -{{% note %}} -`char_length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Aliases - -- char\_length -- character\_length - -##### Related functions - -[bit_length](#bit_length), -[octet_length](#octet_length) - -{{< expand-wrapper >}} -{{% expand "View `length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - length(room)::BIGINT AS length -FROM home -``` - -| room | length | -| :---------- | -----: | -| Kitchen | 7 | -| Living Room | 11 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## levenshtein - -Returns the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) -between two strings. - -```sql -levenshtein(str1, str2) -``` - -##### Arguments -- **str1**: First string expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **str2**: Second string expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `levenshtein` query example" %}} - -```sql -SELECT - string1, - string2, - levenshtein(string1, string2) AS levenshtein -FROM - (values ('kitten', 'sitting'), - ('puppy', 'jumping'), - ('cow', 'lowing') - ) data(string1, string2) -``` - -| string1 | string2 | levenshtein | -| :------ | :------ | ----------: | -| kitten | sitting | 3 | -| puppy | jumping | 5 | -| cow | lowing | 4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lower - -Converts a string to lower-case. - -```sql -lower(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[initcap](#initcap), -[upper](#upper) - -{{< expand-wrapper >}} -{{% expand "View `lower` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - lower(room::STRING) AS lower -FROM home -``` - -| room | lower | -| :---------- | :---------- | -| Kitchen | kitchen | -| Living Room | living room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lpad - -Pads the left side of a string with another string to a specified string length. - -```sql -lpad(str, n[, padding_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: String length to pad to. -- **padding_str**: String expression to pad with. - Can be a constant, column, or function, and any combination of string operators. - _Default is a space._ - -##### Related functions - -[rpad](#rpad) - -{{< expand-wrapper >}} -{{% expand "View `lpad` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - lpad(room::STRING, 14, '-') AS lpad -FROM home -``` - -| room | lpad | -| :---------- | :-------------------- | -| Kitchen | \-\-\-\-\-\-\-Kitchen | -| Living Room | \-\-\-Living Room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ltrim - -Removes leading spaces from a string. - -```sql -ltrim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[rtrim](#rtrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `ltrim` query example" %}} - -```sql -SELECT - string, - ltrim(string) AS ltrim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | ltrim | -| :-------------------------------------- | :-------------------------------------- | -|   Leading spaces | Leading spaces | -| Trailing spaces   | Trailing spaces   | -| Leading and trailing spaces   | Leading and trailing spaces   | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## md5 - -Computes an MD5 128-bit checksum for a string expression. - -```sql -md5(str) -``` - -##### Arguments - -- **expression**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `md5` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - md5(room) AS md5 -FROM home -``` - -| room | md5 | -| :---------- | :------------------------------- | -| Kitchen | 33fa00a66f2edf0d1c5697a9f8693ba8 | -| Living Room | f45b0e6aec165544faccaf2cad820542 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## octet_length - -Returns the length of a string in bytes. - -{{% note %}} -`length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -octet_length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[bit_length](#bit_length), -[length](#length) - -{{< expand-wrapper >}} -{{% expand "View `octet_length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - octet_length(room)::BIGINT AS octet_length -FROM home -``` - -| room | octet_length | -| :---------- | -----------: | -| Living Room | 11 | -| Kitchen | 7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## overlay - -Replaces part of a string with another substring using a specified starting -position and number of characters to replace. - -```sql -overlay(str PLACING substr FROM pos [FOR count]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to use to replace part of the specified string (`str`). - Can be a constant, column, or function, and any combination of string operators. -- **pos**: Start position of the substring replacement (`substr`). -- **count**: Number of characters in the string (`str`) to replace with the - substring (`substr`) beginning from the start position (`pos`). - If not specified, the function uses the length of the substring. - -{{< expand-wrapper >}} -{{% expand "View `overlay` query example" %}} - -```sql -SELECT - string, - overlay(string PLACING '****' FROM 1 FOR 12) AS overlay -FROM - (values ('2223000048410010'), - ('2222420000001113'), - ('4917484589897107') - ) data(string) -``` - -| string | overlay | -| :--------------- | :------- | -| 2223000048410010 | ****0010 | -| 2222420000001113 | ****1113 | -| 4917484589897107 | ****7107 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## position - -Returns the position of a substring in a string. - -```sql -position(substr IN str) -``` - -##### Arguments - -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. -- **str**: String expression to search. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `position` query example" %}} - -```sql -SELECT - string, - position('oo' IN string) AS position -FROM - (values ('cool'), - ('scoop'), - ('ice cream') - ) data(string) -``` - -| string | position | -| :-------- | -------: | -| cool | 2 | -| scoop | 3 | -| ice cream | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## repeat - -Returns a string with an input string repeated a specified number of times. - -```sql -repeat(str, n) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of times to repeat the input string. - -{{< expand-wrapper >}} -{{% expand "View `repeat` query example" %}} - -```sql -SELECT - string, - repeat(string, 3) AS repeat -FROM - (values ('foo '), - ('bar '), - ('baz ') - ) data(string) -``` - -| string | repeat | -| :-------- | :---------- | -| foo  | foo foo foo | -| bar  | bar bar bar | -| baz  | baz baz baz | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## replace - -Replaces all occurrences of a specified substring in a string with a new substring. - -```sql -replace(str, substr, replacement) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to replace in the input string. - Can be a constant, column, or function, and any combination of string operators. -- **replacement**: Replacement substring expression. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - replace(room::STRING, ' ', '_') AS replace -FROM home -``` - -| room | replace | -| :---------- | :---------- | -| Kitchen | Kitchen | -| Living Room | Living_Room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## reverse - -Reverses the character order of a string. - -```sql -reverse(str) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `reverse` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - reverse(room::STRING) AS reverse -FROM home -``` - -| room | reverse | -| :---------- | :---------- | -| Kitchen | nehctiK | -| Living Room | mooR gniviL | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## right - -Returns a specified number of characters from the right side of a string. - -```sql -right(str, n) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of characters to return. - -##### Related functions - -[left](#left) - -{{< expand-wrapper >}} -{{% expand "View `right` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - right(room::STRING, 3) AS right -FROM home -``` - -| room | right | -| :---------- | :---- | -| Living Room | oom | -| Kitchen | hen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## rpad - -Pads the right side of a string with another string to a specified string length. - -```sql -rpad(str, n[, padding_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: String length to pad to. -- **padding_str**: String expression to pad with. - Can be a constant, column, or function, and any combination of string operators. - _Default is a space._ - -##### Related functions - -[lpad](#lpad) - -{{< expand-wrapper >}} -{{% expand "View `rpad` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - rpad(room::STRING, 14, '-') AS rpad -FROM home -``` - -| room | rpad | -| :---------- | :-------------------- | -| Kitchen | Kitchen\-\-\-\-\-\-\- | -| Living Room | Living Room\-\-\- | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## rtrim - -Removes trailing spaces from a string. - -```sql -rtrim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[ltrim](#ltrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `rtrim` query example" %}} - -```sql -SELECT - string, - rtrim(string) AS rtrim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | rtrim | -| :-------------------------------------- | :-------------------------------------- | -|   Leading spaces |   Leading spaces | -| Trailing spaces   | Trailing spaces | -| Leading and trailing spaces   |   Leading and trailing spaces | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## split_part - -Splits a string based on a specified delimiter and returns the substring in the -specified position. - -```sql -split_part(str, delimiter, pos) -``` - -##### Arguments - -- **str**: String expression to spit. - Can be a constant, column, or function, and any combination of string operators. -- **delimiter**: String or character to split on. -- **pos**: Position of the part to return. - -{{< expand-wrapper >}} -{{% expand "View `split_part` query example" %}} - -```sql -SELECT - url, - split_part(url, '.', 1) AS split_part -FROM - (values ('www.influxdata.com'), - ('docs.influxdata.com'), - ('community.influxdata.com') - ) data(url) -``` - -| url | split_part | -| :----------------------- | :--------- | -| www.influxdata.com | www | -| docs.influxdata.com | docs | -| community.influxdata.com | community | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## starts_with - -Tests if a string starts with a substring. - -```sql -starts_with(str, substr) -``` - -##### Arguments - -- **str**: String expression to test. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to test for. - -{{< expand-wrapper >}} -{{% expand "View `starts_with` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - starts_with(room::STRING, 'Kit') AS starts_with -FROM home -``` - -| room | starts_with | -| :---------- | :---------- | -| Kitchen | true | -| Living Room | false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## strpos - -Returns the starting position of a specified substring in a string. -Positions begin at 1. -If the substring does not exist in the string, the function returns 0. - -{{% note %}} -`strpos` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -strpos(str, substr) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `strpos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - strpos(room::STRING, 'Room')::BIGINT AS strpos -FROM home -``` - -| room | strpos | -| :---------- | -----: | -| Kitchen | 0 | -| Living Room | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## substr - -Extracts a substring of a specified number of characters from a specific -starting position in a string. - -```sql -substr(str, start_pos[, length]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **start_pos**: Character position to start the substring at. - The first character in the string has a position of 1. -- **length**: Number of characters to extract. - If not specified, returns the rest of the string after the start position. - -{{< expand-wrapper >}} -{{% expand "View `substr` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - substr(room::STRING, 3, 5) AS substr -FROM home -``` - -| room | substr | -| :---------- | :--------- | -| Living Room | ving  | -| Kitchen | tchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## substr_index - -Returns the substring that occurs before or after the specified number (`count`) -of delimiter (`delimiter`) occurrences in a string (`str`). -If the count is positive, the function returns everything to the left of the -final delimiter (counting from the left). -If the count is negative, the function returns everything to the right of the -final delimiter (counting from the right). - -```sql -substr_index(str, delimiter, count) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **delimiter**: String expression to use to delimit substrings in the string (`str`). - Can be a constant, column, or function, and any combination of string operators. -- **count**: The Nth occurrence of the delimiter (`delimiter`) to split on. - Can be a constant, column, or function, and any combination of arithmetic operators. - Supports positive and negative numbers. - -{{< expand-wrapper >}} -{{% expand "View `substr_index` query example" %}} - -```sql -SELECT - url, - substr_index(url, '.', 1) AS subdomain, - substr_index(url, '.', -1) AS tld -FROM - (values ('docs.influxdata.com'), - ('community.influxdata.com'), - ('cloud2.influxdata.com') - ) data(url) -``` - -| url | subdomain | tld | -| :----------------------- | :-------- | :-- | -| docs.influxdata.com | docs | com | -| community.influxdata.com | community | com | -| arrow.apache.org | arrow | org | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## translate - -Translates characters in a string to specified translation characters. - -```sql -translate(str, chars, translation) -``` - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **chars**: Characters to translate. -- **translation**: Translation characters. Translation characters replace only - characters at the same position in the **chars** string. - -{{< expand-wrapper >}} -{{% expand "View `translate` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - translate(room::STRING, 'Rom', 'sOn') AS translate -FROM home -``` - -| room | translate | -| :---------- | :---------- | -| Living Room | Living sOOn | -| Kitchen | Kitchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_hex - -Converts an integer to a hexadecimal string. - -```sql -to_hex(int) -``` - -##### Arguments - -- **int**: Integer expression to convert. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `to_hex` query example" %}} - -```sql -SELECT - int, - to_hex(int) AS to_hex -FROM - (values (123), - (345), - (678) - ) data(int) -``` - -| int | to_hex | -| :-- | -----: | -| 123 | 7b | -| 345 | 159 | -| 678 | 2a6 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## trim - -Removes leading and trailing spaces from a string. - -```sql -trim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[ltrim](#ltrim), -[rtrim](#rtrim) - -{{< expand-wrapper >}} -{{% expand "View `trim` query example" %}} - -```sql -SELECT - string, - trim(string) AS trim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | trim | -| :-------------------------------------- | :-------------------------- | -|   Leading spaces | Leading spaces | -| Trailing spaces   | Trailing spaces | -| Leading and trailing spaces   | Leading and trailing spaces | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## upper - -Converts a string to upper-case. - -```sql -upper(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[initcap](#initcap), -[lower](#lower) - -{{< expand-wrapper >}} -{{% expand "View `upper` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - upper(room::STRING) AS upper -FROM home -``` - -| room | upper | -| :---------- | :---------- | -| Living Room | LIVING ROOM | -| Kitchen | KITCHEN | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## uuid - -Returns a UUID v4 string value that is unique per row. - -```sql -uuid() -``` - -{{< expand-wrapper >}} -{{% expand "View `uuid` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - uuid() AS uuid -FROM (SELECT DISTINCT room FROM home) -``` - -| room | uuid | -| :---------- | :----------------------------------: | -| Kitchen | f0b41da9-e334-4b7d-b925-a54ca6b082f3 | -| Living Room | c31be90e-c4ed-4304-b633-47b969ef3ab6 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md index a05e25321..0c292c426 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md @@ -8,820 +8,10 @@ menu: name: Time and date parent: sql-functions weight: 305 + +source: /content/shared/sql-reference/functions/time-and-date.md --- -InfluxDB's SQL implementation supports time and date functions that are useful when working with time series data. - -- [current_date](#current_date) -- [current_time](#current_time) -- [date_bin](#date_bin) -- [date_bin_gapfill](#date_bin_gapfill) -- [date_trunc](#date_trunc) -- [datetrunc](#datetrunc) -- [date_part](#date_part) -- [datepart](#datepart) -- [extract](#extract) -- [from_unixtime](#from_unixtime) -- [now](#now) -- [to_timestamp](#to_timestamp) -- [to_timestamp_millis](#to_timestamp_millis) -- [to_timestamp_micros](#to_timestamp_micros) -- [to_timestamp_nanos](#to_timestamp_nanos) -- [to_timestamp_seconds](#to_timestamp_seconds) - -## current_date - -Returns the current UTC date. - -{{% note %}} -`current_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a timestamp](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-a-timestamp-type). -{{% /note %}} - -The `current_date()` return value is determined at query time and will return -the same date, no matter when in the query plan the function executes. - -``` -current_date() -``` - -{{< expand-wrapper >}} -{{% expand "View `current_date` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - time, - temp, - current_date()::TIMESTAMP AS current_date -FROM home -WHERE - time > current_date()::TIMESTAMP - INTERVAL '5 years' -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| time | temp | current_date | -| :------------------- | ---: | :---------------------------- | -| 2022-01-01T08:00:00Z | 21 | {{< datetime/current-date >}} | -| 2022-01-01T09:00:00Z | 23 | {{< datetime/current-date >}} | -| 2022-01-01T10:00:00Z | 22.7 | {{< datetime/current-date >}} | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## current_time - -Returns the current UTC time. - -{{% note %}} -`current_date` returns a `TIME64` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a string](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-a-string-type). -{{% /note %}} - -The `current_time()` return value is determined at query time and will return the same time, -no matter when in the query plan the function executes. - -``` -current_time() -``` - -{{< expand-wrapper >}} -{{% expand "View `current_time` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - time, - temp, - current_time()::STRING AS current_time -FROM home -LIMIT 3 -``` - -| time | temp | current_time | -| :------------------- | ---: | :---------------------------- | -| 2022-01-01T08:00:00Z | 21 | {{< datetime/current-time >}} | -| 2022-01-01T09:00:00Z | 23 | {{< datetime/current-time >}} | -| 2022-01-01T10:00:00Z | 22.7 | {{< datetime/current-time >}} | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## date_bin - -Calculates time intervals and returns the start of the interval nearest to the specified timestamp. -Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" -and applying an aggregate or selector function to each window. - -For example, given an input -timestamp of `2023-01-01T18:18:18Z`, if you bin data into 15-minute intervals, the output timestamp is `2023-01-01T18:15:00Z`--the start of the 15-minute bin that includes the input. - -```sql -date_bin(interval, expression[, origin_timestamp]) -``` - -##### Arguments: - -- **interval**: Bin interval. -- **expression**: Time expression to operate on. - Can be a constant, column, or function. -- **origin_timestamp**: Starting point used to determine bin boundaries. - _Default is the Unix epoch._ - -The following intervals are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks -- months -- years -- century - -{{< expand-wrapper >}} -{{% expand "View `date_bin` query example" %}} - -The following query returns the daily average of water levels in the queried time range. - -```sql -SELECT - date_bin(INTERVAL '1 day', time, TIMESTAMP '1970-01-01 00:00:00Z') AS time, - avg("water_level") AS water_level_avg -FROM "h2o_feet" -WHERE - time >= timestamp '2019-09-10T00:00:00Z' - AND time <= timestamp '2019-09-20T00:00:00Z' -GROUP BY 1 -ORDER BY time DESC -``` - -| time | water_level_avg | -| :----------------------- | :----------------- | -| 2019-09-17T00:00:00.000Z | 4.370175687443861 | -| 2019-09-16T00:00:00.000Z | 4.6034785848437485 | -| 2019-09-15T00:00:00.000Z | 4.680651501506248 | -| 2019-09-14T00:00:00.000Z | 4.857683652395836 | -| 2019-09-13T00:00:00.000Z | 4.911051520291668 | -| 2019-09-12T00:00:00.000Z | 4.763990784533338 | -| 2019-09-11T00:00:00.000Z | 4.6582452515041695 | -| 2019-09-10T00:00:00.000Z | 4.608425018785421 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## date_bin_gapfill - -Calculates time intervals and returns the start of the interval nearest to the specified timestamp. -If no rows exist in a time interval, a new row is inserted with a `time` value -set to the interval start time, all columns in the `GROUP BY` clause populated, -and null values in aggregate columns. - -Use `date_bin_gapfill` with [`interpolate`](/influxdb/cloud-dedicated/reference/sql/functions/misc/#interpolate) -or [`locf`](/influxdb/cloud-dedicated/reference/sql/functions/misc/#locf) to -[fill gaps in data]() -at specified time intervals. - -```sql -date_bin_gapfill(interval, expression[, origin_timestamp]) -``` - -{{% note %}} -`date_bin_gapfill` requires [time bounds](/influxdb/cloud-dedicated/query-data/sql/basic-query/#query-data-within-time-boundaries) -in the `WHERE` clause. -{{% /note %}} - -##### Arguments: - -- **interval**: Bin interval. -- **expression**: Time expression to operate on. - Can be a constant, column, or function. -- **origin_timestamp**: Starting point used to determine bin boundaries. - _Default is the Unix epoch._ - -The following intervals are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks -- months -- years -- century - -##### Related functions - -[interpolate](/influxdb/cloud-dedicated/reference/sql/functions/misc/#interpolate), -[locf](/influxdb/cloud-dedicated/reference/sql/functions/misc/#locf) - -{{< expand-wrapper >}} -{{% expand "View `date_bin_gapfill` query examples" %}} - -_The following examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -- [Use date_bin_gapfill to insert rows when no rows exists](#use-date_bin_gapfill-to-insert-rows-when-no-rows-exists) -- [Use date_bin_gapfill to fill gaps in data](#use-date_bin_gapfill-to-fill-gaps-in-data) - -#### Use date_bin_gapfill to insert rows when no rows exists - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - avg(temp) as temp -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | temp | -| :------------------- | :---------- | ---: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -#### Use date_bin_gapfill to fill gaps in data - -Use `interpolate` and `locf` to fill the null values in rows inserted by -`date_bin_gapfill`. - -{{< tabs-wrapper >}} -{{% tabs "small" %}} -[interpolate](#) -[locf](#) -{{% /tabs %}} -{{% tab-content %}} - -The example below uses [`interpolate`](/influxdb/cloud-dedicated/reference/sql/functions/misc/#interpolate) -to fill null values by interpolating values between non-null values. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - interpolate(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 22 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 22.85 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.25 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.6 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /tab-content %}} -{{% tab-content %}} - -The example below uses [`locf`](/influxdb/cloud-dedicated/reference/sql/functions/misc/#locf) -to fill null values by carrying the last observed value forward. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - locf(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 21 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 23 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - -{{% /expand %}} -{{< /expand-wrapper >}} - - -## date_trunc - -Truncates a timestamp value to a specified precision. - -```sql -date_trunc(precision, expression) -``` - -##### Arguments: - -- **precision**: Time precision to truncate to. - The following precisions are supported: - - - year - - month - - week - - day - - hour - - minute - - second - -- **expression**: Time expression to operate on. - Can be a constant, column, or function. - -##### Aliases - -- `datetrunc` - -{{< expand-wrapper >}} -{{% expand "View `date_trunc` query examples" %}} - -#### Use date_trunc to return hourly averages - -```sql -SELECT - avg(water_level) AS level, - date_trunc('hour', time) AS hour -FROM h2o_feet -WHERE - time >= timestamp '2019-09-10T00:00:00Z' - AND time <= timestamp '2019-09-12T00:00:00Z' -GROUP BY hour -ORDER BY hour -``` - -| hour | level | -| :----------------------- | :----------------- | -| 2019-09-10T00:00:00.000Z | 3.7248000000000006 | -| 2019-09-10T01:00:00.000Z | 3.8561499999999995 | -| 2019-09-10T02:00:00.000Z | 4.5405999999999995 | -| 2019-09-10T03:00:00.000Z | 5.5548072072500005 | -| 2019-09-10T04:00:00.000Z | 6.433900000000001 | -| 2019-09-10T05:00:00.000Z | 6.810949999999998 | - -#### Use date_trunc to return weekly averages - -```sql -SELECT - mean(water_level) as level, - date_trunc('week',time) AS week -FROM h2o_feet -WHERE - time >= timestamp '2019-08-01T00:00:00Z' - AND time <= timestamp '2019-10-31T00:00:00Z' -GROUP BY week -ORDER BY week -``` - -| level | week | -| :----------------- | :----------------------- | -| 4.3314415259020835 | 2019-08-12T00:00:00.000Z | -| 4.234838403584523 | 2019-08-19T00:00:00.000Z | -| 4.4184818559633925 | 2019-08-26T00:00:00.000Z | -| 4.405153386766021 | 2019-09-02T00:00:00.000Z | -| 4.725866897257734 | 2019-09-09T00:00:00.000Z | -| 4.499938596774042 | 2019-09-16T00:00:00.000Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## datetrunc - -_Alias of [date_trunc](#date_trunc)._ - -## date_part - -Returns the specified part of the date as an integer. - -```sql -date_part(part, expression) -``` - -##### Arguments: - -- **part**: Part of the date to return. - The following date parts are supported: - - - year - - month - - week _(week of the year)_ - - day _(day of the month)_ - - hour - - minute - - second - - millisecond - - microsecond - - nanosecond - - dow _(day of the week)_ - - doy _(day of the year)_ - -- **expression**: Time expression to operate on. - Can be a constant, column, or function. - -##### Aliases - -- `datepart` - -{{< expand-wrapper >}} -{{% expand "View `date_part` query examples" %}} - -```sql -SELECT - date_part('hour', time) AS hour, - time, - "level description", - location -FROM h2o_feet -WHERE - time >= timestamp '2019-08-17T02:54:00Z' - AND time <= timestamp '2019-08-17T03:06:00Z' -ORDER BY time -``` - -| hour | time | level description | location | -| :--: | :------------------- | :------------------- | :----------- | -| 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | coyote_creek | -| 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | santa_monica | -| 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | coyote_creek | -| 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | santa_monica | -| 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | coyote_creek | -| 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | santa_monica | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## datepart - -_Alias of [date_part](#date_part)._ - -## extract - -Returns a sub-field from a time value as an integer. -Similar to `date_part`, but with different arguments. - -```sql -extract(field FROM source) -``` - -##### Arguments - -- **field**: Part or field of the date to return. - The following date fields are supported: - - - year - - month - - week _(week of the year)_ - - day _(day of the month)_ - - hour - - minute - - second - - millisecond - - microsecond - - nanosecond - - dow _(day of the week)_ - - doy _(day of the year)_ - -- **source**: Source time expression to operate on. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `extract` query example" %}} - -```sql -SELECT - extract(day from time) AS day -FROM - h2o_feet -LIMIT 1 -``` - -| day | -| :-- | -| 25 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## from_unixtime - -Converts an integer to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). -Input is parsed as a [Unix nanosecond timestamp](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) -and returns the corresponding RFC3339 timestamp. - -```sql -from_unixtime(expression) -``` - -##### Arguments: - -- **expression**: Integer expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `from_unixtime` query example" %}} - -```sql -SELECT - from_unixtime(1672531200000000000) AS RFC3339 -``` - -| RFC3339 | -| :------------------- | -| 2023-01-01T00:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## now - -Returns the current UTC timestamp. - -The `now()` return value is determined at query time and will return the same timestamp, -no matter when in the query plan the function executes. - -```sql -now() -``` - -{{< expand-wrapper >}} -{{% expand "View `now` query example" %}} - -```sql -SELECT - "water_level", - "time" -FROM h2o_feet -WHERE - time <= now() - interval '12 minutes' -``` - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp - -Converts a value to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix nanosecond timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp(expression) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp` query example" %}} - -```sql -SELECT to_timestamp(1704067200000000000) -``` - -| to_timestamp(Int64(1704067200000000000)) | -| :--------------------------------------- | -| 2024-01-01T00:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_millis - -Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix millisecond timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_millis(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_millis` query example" %}} - -```sql -SELECT to_timestamp_millis(1704067200001) AS time -``` - -Results -| to_timestamp_millis(Int64(1704067200001)) | -| :---------------------------------------- | -| 2024-01-01T00:00:00.001Z | - -{{% /expand %}} -{{% expand "View `to_timestamp_millis` example with string format parsing" %}} - -```sql -SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond -``` - -| millisecond | -| :----------------------- | -| 2024-01-01T01:01:59.123Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_micros - -Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix microsecond timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_micros(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_micros` query example" %}} - -```sql -SELECT to_timestamp_micros(1704067200000001) -``` - -| to_timestamp_micros(Int64(1704067200000001)) | -| :------------------------------------------- | -| 2024-01-01T00:00:00.000001Z | -{{% /expand %}} -{{% expand "View `to_timestamp_micros` example with string format parsing" %}} - -```sql -SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond -``` - -| microsecond | -| :-------------------------- | -| 2024-01-01T01:01:59.123456Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_nanos - -Converts a value to RFC3339 nanosecond timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix nanosecond timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_nanos(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_nanos` query example" %}} - -```sql -SELECT to_timestamp_nanos(1704067200000000001) -``` - -| to_timestamp_nanos(Int64(1704067200000000001)) | -| :--------------------------------------------- | -| 2024-01-01T00:00:00.000000001Z | -{{% /expand %}} -{{% expand "View `to_timestamp_nanos` example with string format parsing" %}} - -```sql -SELECT to_timestamp_nanos('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS nanosecond -``` - -| nanosecond | -| :----------------------------- | -| 2024-01-01T01:01:59.123456789Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_seconds - -Converts a value to RFC3339 second timestamp format (`YYYY-MM-DDT00:00:00Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix second timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_seconds(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_seconds` query example" %}} - -```sql -SELECT to_timestamp_seconds(1704067201) -``` - -| to_timestamp_seconds(Int64(1704067201)) | -| :-------------------------------------- | -| 2024-01-01T00:00:01Z | - -{{% /expand %}} -{{% expand "View `to_timestamp_seconds` example with string format parsing" %}} - -```sql -SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS second -``` - -| second | -| :------------------- | -| 2024-01-01T01:01:59Z | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/group-by.md b/content/influxdb/cloud-dedicated/reference/sql/group-by.md index 1088eb33f..6a071c666 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/group-by.md +++ b/content/influxdb/cloud-dedicated/reference/sql/group-by.md @@ -7,92 +7,10 @@ menu: name: GROUP BY clause parent: SQL reference weight: 203 + +source: /content/shared/sql-reference/group-by.md --- -Use the `GROUP BY` clause to group data by values. - -`GROUP BY` is an optional clause used to group rows that have the same values for all columns and expressions in the list. -To output an aggregation for each group, include an aggregate or selector function in the `SELECT` statement. -When `GROUP BY` appears in a query, the `SELECT` list can only use columns that appear in the `GROUP BY` list -or in aggregate expressions. - -`GROUP BY` can use column aliases that are defined in the `SELECT` clause. -`GROUP BY` can't use an alias named `time`. -In a `GROUP BY` list, `time` always refers to the measurement `time` column. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT - AGGREGATE_FN(field1), - tag1 -FROM measurement -GROUP BY tag1 -``` - -## Examples - -### Group data by tag values - -```sql -SELECT - AVG("water_level") AS "avg_water_level", - "location" -FROM "h2o_feet" -GROUP BY "location" -``` - -{{< expand-wrapper >}}} -{{% expand "View example results" %}} - -| avg_water_level | location | -| ----------------: | ------------ | -| 5.359142420303919 | coyote_creek | -| 3.530712094245885 | santa_monica | - -{{% /expand %}} -{{< /expand-wrapper >}} - -Group results in 15 minute time intervals by tag: - -```sql -SELECT - "location", - DATE_BIN(INTERVAL '15 minutes', time, TIMESTAMP '2022-01-01 00:00:00Z') AS _time, - COUNT("water_level") AS count -FROM "h2o_feet" -WHERE - time >= timestamp '2019-09-17T00:00:00Z' - AND time <= timestamp '2019-09-17T01:00:00Z' -GROUP BY - _time, - location -ORDER BY - location, - _time -``` - -{{< expand-wrapper >}}} -{{% expand "View example results" %}} - -The query uses the `COUNT()` function to count the number of `water_level` points per 15 minute interval. -Results are then ordered by location and time. - -| location | _time | count | -| :----------- | :-------------------- | ----: | -| coyote_creek | 2019-09-16T23:45:00Z | 1 | -| coyote_creek | 2019-09-17T00:00:00Z | 2 | -| coyote_creek | 2019-09-17T00:15:00Z | 3 | -| coyote_creek | 2019-09-17T00:30:00Z | 2 | -| coyote_creek | 2019-09-17T00:45:00Z | 3 | -| santa_monica | 2019-09-16T23:45:00Z | 1 | -| santa_monica | 2019-09-17T00:00:00Z | 2 | -| santa_monica | 2019-09-17T00:15:00Z | 3 | -| santa_monica | 2019-09-17T00:30:00Z | 2 | -| santa_monica | 2019-09-17T00:45:00Z | 3 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/having.md b/content/influxdb/cloud-dedicated/reference/sql/having.md index b6c86e0c9..ef06f40c1 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/having.md +++ b/content/influxdb/cloud-dedicated/reference/sql/having.md @@ -10,78 +10,10 @@ menu: weight: 205 related: - /influxdb/cloud-dedicated/reference/sql/subqueries/ + +source: /content/shared/sql-reference/having.md --- -The `HAVING` clause places conditions on results created by an aggregate operation on groups. -The `HAVING` clause must follow the `GROUP BY` clause and precede the `ORDER BY` clause. - -{{% note %}} -The `WHERE` clause filters rows based on specified conditions _before_ the aggregate operation. -The `HAVING` clause filters rows based on specified conditions _after_ the aggregate operation has taken place. -{{% /note %}} - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [HAVING_clause] [ORDER_BY_clause] -``` - -## Examples - -### Return rows with an aggregate value greater than a specified number - -```sql -SELECT - MEAN("water_level") AS "mean_water_level", "location" -FROM - "h2o_feet" -GROUP BY - "location" -HAVING - "mean_water_level" > 5 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns on rows with values in the `mean_water_level` greater than 5 _after_ the aggregate operation. - -| location | mean_water_level | -| :----------- | :---------------- | -| coyote_creek | 5.359142420303919 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Return the average result greater than a specified number from a specific time range - -```sql -SELECT - AVG("water_level") AS "avg_water_level", - "time" -FROM - "h2o_feet" -WHERE - time >= '2019-09-01T00:00:00Z' AND time <= '2019-09-02T00:00:00Z' -GROUP BY - "time" -HAVING - "avg_water_level" > 6.82 -ORDER BY - "time" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query calculates the average water level per time and only returns rows with an average greater than 6.82 during the specified time range. - -| time | avg_water_level | -| :------------------- | -----------------: | -| 2019-09-01T22:06:00Z | 6.8225 | -| 2019-09-01T22:12:00Z | 6.8405000000000005 | -| 2019-09-01T22:30:00Z | 6.8505 | -| 2019-09-01T22:36:00Z | 6.8325 | -{{% /expand %}} -{{< /expand-wrapper >}} \ No newline at end of file + diff --git a/content/influxdb/cloud-dedicated/reference/sql/information-schema.md b/content/influxdb/cloud-dedicated/reference/sql/information-schema.md index 3457859ff..7d39b904e 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/information-schema.md +++ b/content/influxdb/cloud-dedicated/reference/sql/information-schema.md @@ -7,140 +7,10 @@ menu: influxdb_cloud_dedicated: parent: SQL reference weight: 210 + +source: /content/shared/sql-reference/information-schema.md --- -The underlying query engine for the InfluxDB SQL implementation, -[DataFusion](https://arrow.apache.org/datafusion/index.html), provides commands -that return metadata related to your data schema. -To access this information, use the `SHOW TABLES`, `SHOW COLUMNS`, and -`SHOW ALL` commands or query views in the [ISO](https://www.iso.org/) SQL -`information_schema` schema. - -In the context of InfluxDB, a [measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) -is represented as a table. Time, [tags](/influxdb/cloud-dedicated/reference/glossary/#tag), -and [fields](/influxdb/cloud-dedicated/reference/glossary/#field) are each represented -by columns in a table. - -- [SHOW TABLES](#show-tables) - - [Example SHOW TABLES output](#example-show-tables-output) -- [SHOW COLUMNS](#show-columns) - - [Example SHOW COLUMNS output](#example-show-columns-output) -- [SHOW ALL](#show-all) - - [Example SHOW ALL output](#view-show-all-example-output) - -## SHOW TABLES - -Returns information about tables (measurements) in an InfluxDB bucket. - -```sql -SHOW TABLES -``` - -You can also query the `information_schema.tables` view: - -```sql -SELECT * FROM information_schema.tables -``` - -#### Example SHOW TABLES output - -_Measurements are those that use the **`iox` table schema**._ - -| table_catalog | table_schema | table_name | table_type | -| :------------ | :----------------- | :---------- | :--------- | -| public | iox | home | BASE TABLE | -| public | system | queries | BASE TABLE | -| public | information_schema | tables | VIEW | -| public | information_schema | views | VIEW | -| public | information_schema | columns | VIEW | -| public | information_schema | df_settings | VIEW | - -## SHOW COLUMNS - -Returns information about the schema of a table (measurement) in an InfluxDB bucket. - -```sql -SHOW COLUMNS FROM example_table -``` - -You can also query the `information_schema.columns` view: - -```sql -SELECT - table_catalog, - table_schema, - table_name, - column_name, - data_type, - is_nullable -FROM information_schema.columns -WHERE table_name = 'example_table' -``` - -#### Example SHOW COLUMNS output - -| table_catalog | table_schema | table_name | column_name | data_type | is_nullable | -| :------------ | :----------- | :--------- | :---------- | :-------------------------- | :---------- | -| public | iox | home | co | Int64 | YES | -| public | iox | home | hum | Float64 | YES | -| public | iox | home | room | Dictionary(Int32, Utf8) | YES | -| public | iox | home | temp | Float64 | YES | -| public | iox | home | time | Timestamp(Nanosecond, None) | NO | - -## SHOW ALL - -Returns the configuration options of the current session. - -```sql -SHOW ALL -``` - -You can also query the `information_schema.df_settings` view: - -```sql -SELECT * FROM information_schema.df_settings -``` - -{{< expand-wrapper >}} -{{% expand "View `SHOW ALL` example output" %}} - -| name | setting | -| :-------------------------------------------------------- | :------- | -| datafusion.catalog.create_default_catalog_and_schema | true | -| datafusion.catalog.default_catalog | public | -| datafusion.catalog.default_schema | iox | -| datafusion.catalog.format | | -| datafusion.catalog.has_header | false | -| datafusion.catalog.information_schema | true | -| datafusion.catalog.location | | -| datafusion.execution.batch_size | 8192 | -| datafusion.execution.coalesce_batches | true | -| datafusion.execution.collect_statistics | false | -| datafusion.execution.parquet.enable_page_index | false | -| datafusion.execution.parquet.metadata_size_hint | | -| datafusion.execution.parquet.pruning | true | -| datafusion.execution.parquet.pushdown_filters | true | -| datafusion.execution.parquet.reorder_filters | true | -| datafusion.execution.parquet.skip_metadata | true | -| datafusion.execution.target_partitions | 4 | -| datafusion.execution.time_zone | +00:00 | -| datafusion.explain.logical_plan_only | false | -| datafusion.explain.physical_plan_only | false | -| datafusion.optimizer.enable_round_robin_repartition | true | -| datafusion.optimizer.filter_null_join_keys | false | -| datafusion.optimizer.hash_join_single_partition_threshold | 1048576 | -| datafusion.optimizer.max_passes | 3 | -| datafusion.optimizer.prefer_hash_join | true | -| datafusion.optimizer.repartition_aggregations | true | -| datafusion.optimizer.repartition_file_min_size | 10485760 | -| datafusion.optimizer.repartition_file_scans | true | -| datafusion.optimizer.repartition_joins | true | -| datafusion.optimizer.repartition_sorts | false | -| datafusion.optimizer.repartition_windows | true | -| datafusion.optimizer.skip_failed_rules | true | -| datafusion.optimizer.top_down_join_key_reordering | true | -| datafusion.sql_parser.enable_ident_normalization | true | -| datafusion.sql_parser.parse_float_as_decimal | false | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/join.md b/content/influxdb/cloud-dedicated/reference/sql/join.md index b4288a5cb..1aef87a61 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/join.md +++ b/content/influxdb/cloud-dedicated/reference/sql/join.md @@ -7,267 +7,10 @@ menu: name: JOIN clause parent: SQL reference weight: 202 + +source: /content/shared/sql-reference/join.md --- -Use the `JOIN` clause to join data from different tables together based on -logical relationships. - -- [Syntax](#syntax) -- [Join types](#join-types) - - [INNER JOIN](#inner-join) - - [LEFT [OUTER] JOIN](#left-outer-join) - - [RIGHT [OUTER] JOIN](#right-outer-join) - - [FULL [OUTER] JOIN](#full-outer-join) -- [Troubleshoot joins](#troubleshoot-joins) - -## Syntax - -```sql -SELECT_clause -FROM -[INNER | LEFT [OUTER] | RIGHT [OUTER] | FULL [OUTER]] JOIN -ON -[WHERE_clause] -[GROUP_BY_clause] -[HAVING_clause] -[ORDER_BY_clause] -``` - -### Arguments - -- **left_join_items**: One or more tables specified in the `FROM` clause that - represent the left side of the join. -- **right_join_items**: One or more tables specified in the `JOIN` clause that - represent the right side of the join. -- **join_condition**: A predicate expression in the `ON` clause that uses the - `=` (equal to) comparison operator to compare column values from the left side - of the join to column values on the right side of the join. Rows with values - that match the defined predicate are joined using the specified - [join type](#join-types). - - -
- -{{% note %}} -If both sides of the join include columns with the same name, you need to -use the fully-qualified reference to prevent ambiguity. -A _fully-qualified reference_ uses dot notation to reference both the table name -and the column name--for example: `table_name.column_name` -{{% /note %}} - -## Join types - -The following joins types are supported: - -{{< flex >}} -{{< flex-content "quarter" >}} - -

INNER JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="inner small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

LEFT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="left small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

RIGHT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="right small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

FULL [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="full small center" >}} -
-{{< /flex-content >}} -{{< /flex >}} - -#### Join sample tables - -The examples below illustrate join methods using the following tables: - -{{% influxdb/custom-timestamps %}} - -##### prod_line - -| time | station | produced | -| :------------------- | :-----: | -------: | -| 2022-01-01T08:00:00Z | B1 | 26 | -| 2022-01-01T09:00:00Z | B1 | 54 | -| 2022-01-01T10:00:00Z | B1 | 56 | -| 2022-01-01T11:00:00Z | B1 | | -| 2022-01-01T12:00:00Z | B1 | 82 | - -##### errors - -| time | station | level | message | -| :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### INNER JOIN - -Inner joins combine rows from tables on the left and right side of the join -based on common column values defined in the `ON` clause. Rows that don't have -matching column values are not included in the output table. - -{{% influxdb/custom-timestamps %}} - -#### Inner join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -RIGHT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` -##### Inner join results - -| time | station | produced | time | station | level | message | -| :------------------- | :-----: | -------: | :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### LEFT [OUTER] JOIN - -A left outer join returns all rows from the left side of the join and only -returns data from the right side of the join in rows with matching column values -defined in the `ON` clause. - -{{% influxdb/custom-timestamps %}} - -#### Left outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -LEFT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` - -##### Left outer join results - -| time | station | produced | time | station | level | message | -| -------------------- | ------- | -------- | -------------------- | ------- | ----- | -------------------- | -| 2022-01-01T08:00:00Z | B1 | 26 | | | | | -| 2022-01-01T09:00:00Z | B1 | 54 | | | | | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | -| 2022-01-01T12:00:00Z | B1 | 82 | | | | | - -{{% /influxdb/custom-timestamps %}} - - -### RIGHT [OUTER] JOIN - -A right outer join returns all rows from the right side of the join and only -returns data from the left side of the join in rows with matching column values -defined in the `ON` clause. - -{{% influxdb/custom-timestamps %}} - -#### Right outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -RIGHT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` - -##### Right outer join results - -| time | station | produced | time | station | level | message | -| :------------------- | :-----: | -------: | :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### FULL [OUTER] JOIN - -A full outer join returns all data from the left and right sides of the join and -combines rows with matching column values defined in the `ON` clause. -Data that is not available on each respective side of the join is NULL. - -{{% influxdb/custom-timestamps %}} - -#### Full outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -FULL JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - time -``` - -##### Full outer join results - -| time | station | produced | time | station | level | message | -| -------------------- | ------- | -------- | -------------------- | ------- | ----- | -------------------- | -| 2022-01-01T08:00:00Z | B1 | 26 | | | | | -| 2022-01-01T09:00:00Z | B1 | 54 | | | | | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | -| 2022-01-01T12:00:00Z | B1 | 82 | | | | | - -{{% /influxdb/custom-timestamps %}} - -## Troubleshoot joins - -### Ambiguous reference to unqualified field - -If a column exists on both sides of the join and is used in in the `SELECT`, -`ON`, `WHERE`, `HAVING`, `GROUP BY`, or `ORDER BY` clause, you must use a -[fully-qualified reference](#fully-qualified-reference). For example, if both -sides of the join have a `time` column and you want to explicitly select a -time column, you must specifiy which side of the join to use the time column from: - -{{% code-callout "prod_line.time" "green" %}} -``` -SELECT - prod_line.time, - produced, - message, -FROM - prod_line -INNER JOIN errors ON - -- ... -``` -{{% /code-callout %}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/limit.md b/content/influxdb/cloud-dedicated/reference/sql/limit.md index 8ae057222..b522340c0 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/limit.md +++ b/content/influxdb/cloud-dedicated/reference/sql/limit.md @@ -7,70 +7,10 @@ menu: name: LIMIT clause parent: SQL reference weight: 206 + +source: /content/shared/sql-reference/limit.md --- -The `LIMIT` clause limits the number of rows returned by a query to a specified non-negative integer. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT -``` - -## Examples - -### Limit results to a maximum of five rows - -```sql -SELECT - "water_level","location", "time" -FROM - "h2o_feet" -LIMIT - 5 -``` -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns a maximum of 5 results. - -| location | time | water_level | -| :----------- | :----------------------- | ----------- | -| coyote_creek | 2019-08-28T00:00:00.000Z | 4.206 | -| coyote_creek | 2019-08-28T00:06:00.000Z | 4.052 | -| coyote_creek | 2019-08-28T00:12:00.000Z | 3.901 | -| coyote_creek | 2019-08-28T00:18:00.000Z | 3.773 | -| coyote_creek | 2019-08-28T00:24:00.000Z | 3.632 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Sort and limit results - -Use the `ORDER BY` and `LIMIT` clauses to first sort results by specified columns, -then limit the sorted results by a specified number. - -```sql -SELECT - "water_level", "location", "time" -FROM - "h2o_feet" -ORDER BY - "water_level" DESC -LIMIT - 3 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns the highest 3 `water_level` readings in the `h2o_feet` measurement. - -| location | time | water_level | -| :----------- | :----------------------- | ----------- | -| coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | -| coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | -| coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | -{{% /expand %}} -{{< /expand-wrapper >}} - + diff --git a/content/influxdb/cloud-dedicated/reference/sql/operators/_index.md b/content/influxdb/cloud-dedicated/reference/sql/operators/_index.md index 18d745431..ec2d6379f 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/operators/_index.md +++ b/content/influxdb/cloud-dedicated/reference/sql/operators/_index.md @@ -8,11 +8,10 @@ menu: name: Operators parent: SQL reference weight: 211 + +source: /content/shared/sql-reference/operators/_index.md --- -SQL operators are reserved words or characters which perform certain operations, -including comparisons and arithmetic. - -{{< children type="anchored-list" >}} - -{{< children hlevel="h2" >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/operators/arithmetic.md b/content/influxdb/cloud-dedicated/reference/sql/operators/arithmetic.md index d1ea4e129..17eda1e8c 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/operators/arithmetic.md +++ b/content/influxdb/cloud-dedicated/reference/sql/operators/arithmetic.md @@ -17,140 +17,10 @@ list_code_example: | | `*` | Multiplication | `2 * 3` | `6` | | `/` | Division | `6 / 3` | `2` | | `%` | Modulo | `7 % 2` | `1` | + +source: /content/shared/sql-reference/operators/arithmetic.md --- -Arithmetic operators take two numeric values (either literals or variables) -and perform a calculation that returns a single numeric value. - -| Operator | Description | | -| :------: | :------------- | :------------------------------------- | -| `+` | Addition | [{{< icon "link" >}}](#addition) | -| `-` | Subtraction | [{{< icon "link" >}}](#subtraction) | -| `*` | Multiplication | [{{< icon "link" >}}](#multiplication) | -| `/` | Division | [{{< icon "link" >}}](#division) | -| `%` | Modulo | [{{< icon "link" >}}](#modulo) | - -## + {#addition .monospace} - -The `+` operator adds two operands together and returns the sum. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 + 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(1) + int64(2) | -| ------------------: | -| 3 | - -{{% /flex-content %}} -{{< /flex >}} - -## - {#subtraction .monospace} - -The `-` operator subtracts the right operand from the left operand and returns -the difference. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 4 - 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(4) - int64(2) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -## * {#multiplication .monospace} - -The `*` operator multiplies two operands together and returns the product. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 2 * 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(2) * int64(3) | -| ------------------: | -| 6 | - -{{% /flex-content %}} -{{< /flex >}} - -## / {#division .monospace} - -The `/` operator divides the left operand by the right operand and returns the quotient. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 6 / 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(6) / int64(3) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -## % {#modulo .monospace} - -The `%` (modulo) operator divides the left operand by the right operand and returns the -remainder. If the left operand is not divisible by the right operand, it returns -the left operand. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 8 % 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(8) % Int64(3) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 % 8 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) % Int64(8) | -| ------------------: | -| 3 | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/operators/bitwise.md b/content/influxdb/cloud-dedicated/reference/sql/operators/bitwise.md index 7e18b6562..0c14b734b 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/operators/bitwise.md +++ b/content/influxdb/cloud-dedicated/reference/sql/operators/bitwise.md @@ -16,137 +16,10 @@ list_code_example: | | `^` | Bitwise xor | `5 ^ 3` | `6` | | `>>` | Bitwise shift right | `5 >> 3` | `0` | | `<<` | Bitwise shift left | `5 << 3` | `40` | + +source: /content/shared/sql-reference/operators/bitwise.md --- -Bitwise operators perform bitwise operations on bit patterns or binary numerals. - -| Operator | Meaning | | -| :------: | :------------------ | :------------------------------------------ | -| `&` | Bitwise and | [{{< icon "link" >}}](#bitwise-and) | -| `\|` | Bitwise or | [{{< icon "link" >}}](#bitwise-or) | -| `^` | Bitwise xor | [{{< icon "link" >}}](#bitwise-xor) | -| `>>` | Bitwise shift right | [{{< icon "link" >}}](#bitwise-shift-right) | -| `<<` | Bitwise shift left | [{{< icon "link" >}}](#bitwise-shift-left) | - -## & {#bitwise-and .monospace} - -The `&` (bitwise AND) operator compares each bit of the left operand to the -corresponding bit of the right operand. -If both bits are 1, the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 & 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) & Int64(3) | -| ------------------: | -| 1 | - -{{% /flex-content %}} -{{< /flex >}} - -## \| {#bitwise-or .monospace} - -The `|` (bitwise OR or inclusive OR) operator compares each bit of the left -operand to the corresponding bit of the right operand. -If either bit is 1, the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 | 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \| Int64(3) | -| -------------------: | -| 7 | - -{{% /flex-content %}} -{{< /flex >}} - -## ^ {#bitwise-xor .monospace} - -The `^` (bitwise XOR or exclusive OR) operator compares each bit of the left -operand to the corresponding bit of the right operand. -If the bit in one of the operands is 0 and the bit in the other operand is 1, -the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 ^ 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) BIT_XOR Int64(3) | -| ------------------------: | -| 6 | - -{{% /flex-content %}} -{{< /flex >}} - -## \>\> {#bitwise-shift-right .monospace} - -The `>>` (bitwise shift right) operator shifts the bits in the left operand to -the right by the number of positions specified in the right operand. -For unsigned numbers, bit positions vacated by the shift operation are filled with 0. -For signed numbers, the sign bit is used to fill the vacated bit positions. -If the number is positive, the bit position is filled with 0. -If the number is negative, the bit position is filled with 1. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 >> 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \>\> Int64(3) | -| ---------------------: | -| 0 | - -{{% /flex-content %}} -{{< /flex >}} - -## \<\< {#bitwise-shift-left .monospace} - -The `<<` (bitwise shift left) operator shifts the bits in the left operand to -the left by the number of positions specified in the right operand. -Bit positions vacated by the shift operation are filled with 0. -Bits that shift off the end are discarded, including the sign bit. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 << 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \<\< Int64(3) | -| ---------------------: | -| 40 | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/operators/comparison.md b/content/influxdb/cloud-dedicated/reference/sql/operators/comparison.md index c875d4b2a..c2fbe072a 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/operators/comparison.md +++ b/content/influxdb/cloud-dedicated/reference/sql/operators/comparison.md @@ -23,267 +23,10 @@ list_code_example: | | `~*` | Matches a regular expression _(case-insensitive)_ | `'Abc' ~* 'A.*'` | | `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | | `!~*` | Does not match a regular expression _(case-insensitive)_ | `'Abc' !~* 'a.*'` | + +source: /content/shared/sql-reference/operators/comparison.md --- -Comparison operators evaluate the relationship between the left and right -operands and returns `true` or `false`. - - -| Operator | Meaning | | -| :------: | :------------------------------------------------------- | :------------------------------------------------------ | -| `=` | Equal to | [{{< icon "link" >}}](#equal-to) | -| `<>` | Not equal to | [{{< icon "link" >}}](#not-equal-to) | -| `!=` | Not equal to | [{{< icon "link" >}}](#not-equal-to) | -| `>` | Greater than | [{{< icon "link" >}}](#greater-than) | -| `>=` | Greater than or equal to | [{{< icon "link" >}}](#greater-than-or-equal) | -| `<` | Less than | [{{< icon "link" >}}](#less-than) | -| `<=` | Less than or equal to | [{{< icon "link" >}}](#less-than-or-equal) | -| `~` | Matches a regular expression | [{{< icon "link" >}}](#regexp-match) | -| `~*` | Matches a regular expression _(case-insensitive)_ | [{{< icon "link" >}}](#regexp-match-case-insensitive) | -| `!~` | Does not match a regular expression | [{{< icon "link" >}}](#regexp-nomatch) | -| `!~*` | Does not match a regular expression _(case-insensitive)_ | [{{< icon "link" >}}](#regexp-nomatch-case-insensitive) | - -## = {#equal-to .monospace} - -The `=` operator compares the left and right operands and, if equal, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 = 123 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) = Int64(123) | -| :---------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !=, <> {#not-equal-to .monospace} - -The `!=` and `<>` operators compare the left and right operands and, if not equal, -returns `true`. Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 != 456 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) != Int64(456) | -| :----------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 <> 456 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) != Int64(456) | -| :----------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## > {#greater-than .monospace} - -The `>` operator compares the left and right operands and, if the left operand -is greater than the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 > 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) > Int64(2) | -| :------------------ | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## >= {#greater-than-or-equal .monospace} - -The `>=` operator compares the left and right operands and, if the left operand -is greater than or equal to the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 >= 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) >= Int64(2) | -| :------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## < {#less-than .monospace} - -The `<` operator compares the left and right operands and, if the left operand -is less than the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 < 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int641(1) < Int64(2) | -| :------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## <= {#less-than-or-equal .monospace} - -The `<=` operator compares the left and right operands and, if the left operand -is less than or equal to the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 <= 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int641(1) <= Int64(2) | -| :-------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## ~ {#regexp-match .monospace} - -The `~` operator compares the left string operand to the right regular expression -operand and, if it matches (case-sensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'abc' ~ 'a.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("abc") ~ Utf8("a.*") | -| :------------------------ | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## ~* {#regexp-match-case-insensitive .monospace} - -The `~*` operator compares the left string operand to the right regular expression -operand and, if it matches (case-insensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Abc' ~* 'A.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("Abc") ~* Utf8("A.*") | -| :------------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !~ {#regexp-nomatch .monospace} - -The `!~` operator compares the left string operand to the right regular expression -operand and, if it does not match (case-sensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'abc' !~ 'd.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("abc") !~ Utf8("d.*") | -| :------------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !~* {#regexp-nomatch-case-insensitive .monospace} - -The `!~*` operator compares the left string operand to the right regular expression -operand and, if it does not match (case-insensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Abc' !~* 'a.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("Abc") !~* Utf8("a.*") | -| :-------------------------- | -| false | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/operators/logical.md b/content/influxdb/cloud-dedicated/reference/sql/operators/logical.md index 92f75a27e..fa4342197 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/operators/logical.md +++ b/content/influxdb/cloud-dedicated/reference/sql/operators/logical.md @@ -21,443 +21,10 @@ list_code_example: | | `LIKE` | Returns true if the left operand matches the right operand pattern string. | | `NOT` | Negates the subsequent expression. | | `OR` | Returns true if any operand is true. Otherwise, returns false. | + +source: /content/shared/sql-reference/operators/logical.md --- -Logical operators combine or manipulate conditions in a SQL query. - -| Operator | Meaning | | -| :-------: | :------------------------------------------------------------------------- | :------------------------------ | -| `AND` | Returns true if both operands are true. Otherwise, returns false. | [{{< icon "link" >}}](#and) | -| `BETWEEN` | Returns true if the left operand is within the range of the right operand. | [{{< icon "link" >}}](#between) | -| `EXISTS` | Returns true if the results of a subquery are not empty. | [{{< icon "link" >}}](#exists) | -| `IN` | Returns true if the left operand is in the right operand list. | [{{< icon "link" >}}](#in) | -| `LIKE` | Returns true if the left operand matches the right operand pattern string. | [{{< icon "link" >}}](#like) | -| `NOT` | Negates the subsequent expression. | [{{< icon "link" >}}](#not) | -| `OR` | Returns true if any operand is true. Otherwise, returns false. | [{{< icon "link" >}}](#or) | - -{{% note %}} -#### Sample data - -Query examples on this page use the following sample data sets: - -- [Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data) -- [Home sensor actions sample data](/influxdb/cloud-dedicated/reference/sample-data/#home-sensor-actions-data) -{{% /note %}} - -## AND {.monospace} - -The `AND` operand returns `true` if both operands are `true`. Otherwise, it returns false. -This operator is typically used in the [`WHERE` clause](/influxdb/cloud-dedicated/reference/sql/where/) -to combine multiple conditions. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT true AND false AS "AND condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| AND condition | -| :------------ | -| false | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`AND` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co > 10 - AND room = 'Kitchen' -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## BETWEEN {.monospace} - -The `BETWEEN` operator returns `true` if the left numeric operand is within the -range specified in the right operand. Otherwise, it returns `false` - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 6 BETWEEN 5 AND 8 AS "BETWEEN condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| BETWEEN condition | -| :---------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`BETWEEN` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co BETWEEN 5 AND 10 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## EXISTS {.monospace} - -The `EXISTS` operator returns `true` if result of a -[correlated subquery](/influxdb/cloud-dedicated/reference/sql/subqueries/#correlated-subqueries) -is not empty. Otherwise it returns `false`. - -_See [SQL subquery operators](/influxdb/cloud-dedicated/reference/sql/subqueries/#subquery-operators)._ - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`EXISTS` operator with a subquery in the `WHERE` clause" %}} - -```sql -SELECT * -FROM - home home_actions -WHERE EXISTS ( - SELECT * - FROM home - WHERE - home.co = home_actions.co - 1 -) -ORDER BY time -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | -| 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | -| 1 | 36.1 | Living Room | 22.3 | 2022-01-01T15:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## IN {.monospace} - -The `IN` operator returns `true` if the left operand is in the right operand -list or subquery result. Otherwise, it returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'John' IN ('Jane', 'John') AS "IN condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| IN condition | -| :----------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -_See [SQL subquery operators](/influxdb/cloud-dedicated/reference/sql/subqueries/#subquery-operators)._ - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`IN` operator with a list in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room IN ('Bathroom', 'Bedroom', 'Kitchen') -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`IN` operator with a subquery in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room IN ( - SELECT DISTINCT room - FROM home_actions - ) -ORDER BY time -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## LIKE {.monospace} - -The `LIKE` operator returns `true` if the left operand matches the string pattern -specified in the right operand. -`LIKE` expressions support [SQL wildcard characters](#sql-wildcard-characters). - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'John' LIKE 'J_%n' AS "LIKE condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| LIKE condition | -| :------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -{{< expand-wrapper >}} -{{% expand "`LIKE` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room LIKE '%Room' -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -### SQL wildcard characters - -The InfluxDB SQL implementation supports the following wildcard characters when -using the `LIKE` operator to match strings to a pattern. - -| Character | Description | -| :-------: | :--------------------------------- | -| `%` | Represents zero or more characters | -| `_` | Represents any single character | - -## NOT {.monospace} - -The `NOT` operator negates the subsequent expression. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT NOT true AS "NOT condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| NOT condition | -| :------------ | -| false | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`NOT IN`" %}} - -```sql -SELECT * -FROM home -WHERE - room NOT IN ('Kitchen', 'Bathroom') -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "`NOT EXISTS`" %}} - -```sql -SELECT * -FROM - home home_actions -WHERE NOT EXISTS ( - SELECT * - FROM home - WHERE - home.co = home_actions.co + 4 -) -ORDER BY time -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "`NOT BETWEEN`" %}} - -```sql -SELECT * -FROM home -WHERE - co NOT BETWEEN 1 AND 22 - AND room = 'Kitchen' -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## OR {.monospace} - -The `OR` operator returns `true` if any operand is `true`. -Otherwise, it returns `false`. -This operator is typically used in the [`WHERE` clause](/influxdb/cloud-dedicated/reference/sql/where/) -to combine multiple conditions. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT true OR false AS "OR condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| OR condition | -| :----------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`OR` in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co > 20 - OR temp > 23 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/operators/other.md b/content/influxdb/cloud-dedicated/reference/sql/operators/other.md index 5fe800ec4..f9d8fd974 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/operators/other.md +++ b/content/influxdb/cloud-dedicated/reference/sql/operators/other.md @@ -13,52 +13,10 @@ list_code_example: | | :------------: | :----------------------- | :-------------------------------------- | :------------ | | `\|\|` | Concatenate strings | `'Hello' \|\| ' world'` | `Hello world` | | `AT TIME ZONE` | Apply a time zone offset | _[View example](/influxdb/cloud-dedicated/reference/sql/operators/other/#at-time-zone)_ | | + +source: /content/shared/sql-reference/operators/other.md --- -SQL supports miscellaneous operators that perform various operations. - -| Operator | Meaning | | -| :------------: | :----------------------- | :------------------------------------------ | -| `\|\|` | Concatenate strings | [{{< icon "link" >}}](#concatenate-strings) | -| `AT TIME ZONE` | Apply a time zone offset | [{{< icon "link" >}}](#at-time-zone) | - -## || {#concatenate-strings} - -The `||` operator concatenates two string operands into a single string. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Hello' || ' world' AS "Concatenated" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Concatenated | -| :----------- | -| Hello world | - -{{% /flex-content %}} -{{< /flex >}} - -## AT TIME ZONE - -The `AT TIME ZONE` operator applies the offset of the specified time zone to a -timestamp type and returns an updated UTC timestamp. Time zone offsets are -provided by the the operating system time zone database. - -{{% note %}} -Timestamp types in InfluxDB always represent a UTC time. The returned timestamp -is a UTC timestamp adjusted for the offset of the specified time zone. -{{% /note %}} - -```sql -SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'UTC with TZ offset' -``` - -| UTC with TZ offset | -| :----------------------- | -| 2024-01-01T08:00:00.000Z | + diff --git a/content/influxdb/cloud-dedicated/reference/sql/order-by.md b/content/influxdb/cloud-dedicated/reference/sql/order-by.md index 4251df4fc..f2500a571 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/order-by.md +++ b/content/influxdb/cloud-dedicated/reference/sql/order-by.md @@ -8,91 +8,10 @@ menu: name: ORDER BY clause parent: SQL reference weight: 204 + +source: /content/shared/sql-reference/order-by.md --- -The `ORDER BY` clause sort results by specified columns and order. -Sort data based on fields, tags, and timestamps. -The following orders are supported: - -- `ASC`: ascending _(default)_ -- `DESC`: descending - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -[SELECT CLAUSE] [FROM CLAUSE] [ ORDER BY expression [ ASC | DESC ][, …] ] -``` - -{{% note %}} -**Note:** If your query includes a `GROUP BY` clause, the `ORDER BY` clause must appear **after** the `GROUP BY` clause. -{{% /note %}} - -## Examples - -### Sort data by time with the most recent first - -```sql -SELECT - "water_level", "time" -FROM - "h2o_feet" -WHERE - "location" = 'coyote_creek' -ORDER BY - time DESC -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -| time | water_level | -| :----------------------- | :----------- | -| 2019-09-17T16:24:00.000Z | 3.235 | -| 2019-09-17T16:18:00.000Z | 3.314 | -| 2019-09-17T16:12:00.000Z | 3.402 | -| 2019-09-17T16:06:00.000Z | 3.497 | -| 2019-09-17T16:00:00.000Z | 3.599 | -| 2019-09-17T15:54:00.000Z | 3.704 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Sort data by tag or field values - -```sql -SELECT - "water_level", "time", "location" -FROM - "h2o_feet" -ORDER BY - "location", "water_level" DESC -``` - -### Sort data by selection order - -```sql -SELECT - "location","water_level", "time" -FROM - "h2o_feet" -ORDER BY - 1, 2 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query sorts results the location of a column in the `SELECT` statement: -first by `location` (1), and second by `water_level` (2). - -| location | time | water_level | -| :----------- | :----------------------- | :---------- | -| coyote_creek | 2019-08-28T14:30:00.000Z | -0.61 | -| coyote_creek | 2019-08-29T15:18:00.000Z | -0.594 | -| coyote_creek | 2019-08-28T14:36:00.000Z | -0.591 | -| coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | -| coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | -| coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/select.md b/content/influxdb/cloud-dedicated/reference/sql/select.md index 0005dbb09..c866e59b0 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/select.md +++ b/content/influxdb/cloud-dedicated/reference/sql/select.md @@ -9,106 +9,10 @@ menu: weight: 201 related: - /influxdb/cloud-dedicated/reference/sql/subqueries/ + +source: /content/shared/sql-reference/select.md --- -Use the `SELECT` statement to query data from an InfluxDB measurement. -The `SELECT` clause is required when querying data in SQL. - -- [Syntax](#syntax) -- [Examples](#examples) - -### Syntax - -```sql -SELECT a, b, "time" FROM -``` - -{{% note %}} -**Note:** When querying InfluxDB, the `SELECT` statement **always requires** a `FROM` clause. -{{% /note %}} - -The SELECT clause supports the following: - - - `SELECT *` - return all tags, fields and timestamps. - - `SELECT DISTINCT` to return all distinct (different) values. - - `SELECT <"field" or "tag">` - returns a specified field or tag. - - `SELECT <"field" or "tag">, <"field" or "tag">` - returns more than one tag or field. - - `SELECT <"field"> AS a `- return the field as the alias. - -## Examples - -The following examples use data from the NOAA database. -To download the NOAA test data see [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). - -### Select all fields and tags from a measurement - -```sql -SELECT * FROM h2o_feet LIMIT 10 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -| level description | location | time | water_level | -| :------------------------ | :----------- | :----------------------- | :---------- | -| at or greater than 9 feet | coyote_creek | 2019-09-01T00:00:00.000Z | 9.126144144 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T00:06:00.000Z | 9.009 | -| between 6 and 9 feet | coyote_creek | 2019-09-01T00:12:00.000Z | 8.862 | -| between 6 and 9 feet | coyote_creek | 2019-09-01T00:18:00.000Z | 8.714 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select specific tags and fields from a measurement - -```sql -SELECT "location", "water_level" FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "1" %}} -| location | water_level | -| :----------- | :---------- | -| coyote_creek | 9.126144144 | -| coyote_creek | 9.009 | -| coyote_creek | 8.862 | -| coyote_creek | 8.714 | -| coyote_creek | 8.547 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select a field, tag and timestamp from a measurement - -```sql -SELECT "water_level", "location", "time" FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "2" %}} -| location | time | water_level | -| :----------- | :----------------------- | :---------- | -| coyote_creek | 2019-08-20T00:00:00.000Z | 8.638 | -| coyote_creek | 2019-08-20T00:06:00.000Z | 8.658 | -| coyote_creek | 2019-08-20T00:12:00.000Z | 8.678 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select a field and perform basic arithmetic - -The following query takes the value of water_level, multiplies it by 3 and adds 5 to the result. - -```sql -SELECT ("water_level" * 3) + 5 FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "3" %}} -| water_level | -| :----------------- | -| 30.128 | -| 30.641000000000002 | -| 31.142000000000003 | -| 31.586 | -| 32.027 | -| 32.378432432 | -{{% /expand %}} -{{< /expand-wrapper >}} - + diff --git a/content/influxdb/cloud-dedicated/reference/sql/subqueries.md b/content/influxdb/cloud-dedicated/reference/sql/subqueries.md index 7857549f2..523853252 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/subqueries.md +++ b/content/influxdb/cloud-dedicated/reference/sql/subqueries.md @@ -13,744 +13,10 @@ related: - /influxdb/cloud-dedicated/reference/sql/select/ - /influxdb/cloud-dedicated/reference/sql/where/ - /influxdb/cloud-dedicated/reference/sql/having/ + +source: /content/shared/sql-reference/subqueries.md --- -Subqueries (also known as inner queries or nested queries) are queries within -a query. -Subqueries can be used in `SELECT`, `FROM`, `WHERE`, and `HAVING` clauses. - -- [Subquery operators](#subquery-operators) - - [[ NOT ] EXISTS](#-not--exists) - - [[ NOT ] IN](#-not--in) -- [SELECT clause subqueries](#select-clause-subqueries) -- [FROM clause subqueries](#from-clause-subqueries) -- [WHERE clause subqueries](#where-clause-subqueries) -- [HAVING clause subqueries](#having-clause-subqueries) -- [Subquery categories](#subquery-categories) - - [Correlated subqueries](#correlated-subqueries) - - [Non-correlated subqueries](#non-correlated-subqueries) - - [Scalar subqueries](#scalar-subqueries) - - [Non-scalar subqueries](#non-scalar-subqueries) - -{{% note %}} -#### Sample data - -Query examples on this page use the following sample data sets: - -- [Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data) -- [Home sensor actions sample data](/influxdb/cloud-dedicated/reference/sample-data/#home-sensor-actions-data) -- [NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data) - -{{% /note %}} - -## Subquery operators - -- [[ NOT ] EXISTS](#-not--exists) -- [[ NOT ] IN](#-not--in) - -### [ NOT ] EXISTS - -The `EXISTS` operator returns all rows where a -_[correlated subquery](#correlated-subqueries)_ produces one or more matches for -that row. `NOT EXISTS` returns all rows where a _correlated subquery_ produces -zero matches for that row. Only _correlated subqueries_ are supported. - -#### Syntax {#-not-exists-syntax} - -```sql -[NOT] EXISTS (subquery) -``` - -### [ NOT ] IN - -The `IN` operator returns all rows where a given expression’s value can be found -in the results of a _[correlated subquery](#correlated-subqueries)_. -`NOT IN` returns all rows where a given expression’s value cannot be found in -the results of a subquery or list of values. - -#### Syntax {#-not-in-syntax} - -```sql -expression [NOT] IN (subquery|list-literal) -``` - -#### Examples {#-not-in-examples} - -{{< expand-wrapper >}} -{{% expand "View `IN` examples using a query" %}} -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[IN](#) -[NOT IN](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - room IN ( - SELECT - DISTINCT room - FROM - home_actions - ) -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - room NOT IN ( - SELECT - DISTINCT room - FROM - home_actions - ) -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} -{{% /expand %}} - -{{% expand "View `IN` examples using a list literal" %}} -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[IN](#) -[NOT IN](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM home -WHERE room IN ('Bathroom', 'Bedroom', 'Kitchen') -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM home -WHERE room NOT IN ('Bathroom', 'Bedroom', 'Kitchen') -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## SELECT clause subqueries - -`SELECT` clause subqueries use values returned from the inner query as part -of the outer query's `SELECT` list. -The `SELECT` clause only supports [scalar subqueries](#scalar-subqueries) that -return a single value per execution of the inner query. -The returned value can be unique per row. - -### Syntax {#select-subquery-syntax} - -```sql -SELECT [expression1[, expression2, ..., expressionN],] () -``` - -{{% note %}} -`SELECT` clause subqueries can be used as an alternative to `JOIN` operations. -{{% /note %}} - -### Examples {#select-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "`SELECT` clause with correlated subquery" %}} - -```sql -SELECT - time, - room, - co, - ( - SELECT - MAX(description) - FROM - home_actions - WHERE - time = home.time - AND room = home.room - AND level != 'ok' - ) AS "Alert Description" -FROM - home -ORDER BY - room, - time -``` - -#### Inner query results - -Because the inner query is a [correlated subquery](#correlated-subqueries), -the result depends on the values of `room` and `time` columns in the outer query. -The results below represent the action description for each `room` and `time` -combination with a `level` value that does not equal `ok`. - -{{% influxdb/custom-timestamps %}} -| time | room | MAX(home_actions.description) | -| :------------------- | :---------- | :------------------------------------------ | -| 2022-01-01T18:00:00Z | Kitchen | Carbon monoxide level above normal: 18 ppm. | -| 2022-01-01T19:00:00Z | Kitchen | Carbon monoxide level above normal: 22 ppm. | -| 2022-01-01T20:00:00Z | Kitchen | Carbon monoxide level above normal: 26 ppm. | -| 2022-01-01T19:00:00Z | Living Room | Carbon monoxide level above normal: 14 ppm. | -| 2022-01-01T20:00:00Z | Living Room | Carbon monoxide level above normal: 17 ppm. | -{{% /influxdb/custom-timestamps %}} - -#### Outer query results - -{{% influxdb/custom-timestamps %}} -| time | room | co | Alert Description | -| :------------------- | :---------- | --: | :------------------------------------------ | -| 2022-01-01T08:00:00Z | Kitchen | 0 | | -| 2022-01-01T09:00:00Z | Kitchen | 0 | | -| 2022-01-01T10:00:00Z | Kitchen | 0 | | -| 2022-01-01T11:00:00Z | Kitchen | 0 | | -| 2022-01-01T12:00:00Z | Kitchen | 0 | | -| 2022-01-01T13:00:00Z | Kitchen | 1 | | -| 2022-01-01T14:00:00Z | Kitchen | 1 | | -| 2022-01-01T15:00:00Z | Kitchen | 3 | | -| 2022-01-01T16:00:00Z | Kitchen | 7 | | -| 2022-01-01T17:00:00Z | Kitchen | 9 | | -| 2022-01-01T18:00:00Z | Kitchen | 18 | Carbon monoxide level above normal: 18 ppm. | -| 2022-01-01T19:00:00Z | Kitchen | 22 | Carbon monoxide level above normal: 22 ppm. | -| 2022-01-01T20:00:00Z | Kitchen | 26 | Carbon monoxide level above normal: 26 ppm. | -| 2022-01-01T08:00:00Z | Living Room | 0 | | -| 2022-01-01T09:00:00Z | Living Room | 0 | | -| 2022-01-01T10:00:00Z | Living Room | 0 | | -| 2022-01-01T11:00:00Z | Living Room | 0 | | -| 2022-01-01T12:00:00Z | Living Room | 0 | | -| 2022-01-01T13:00:00Z | Living Room | 0 | | -| 2022-01-01T14:00:00Z | Living Room | 0 | | -| 2022-01-01T15:00:00Z | Living Room | 1 | | -| 2022-01-01T16:00:00Z | Living Room | 4 | | -| 2022-01-01T17:00:00Z | Living Room | 5 | | -| 2022-01-01T18:00:00Z | Living Room | 9 | | -| 2022-01-01T19:00:00Z | Living Room | 14 | Carbon monoxide level above normal: 14 ppm. | -| 2022-01-01T20:00:00Z | Living Room | 17 | Carbon monoxide level above normal: 17 ppm. | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FROM clause subqueries - -`FROM` clause subqueries return a set of results that is then queried and -operated on by the outer query. - -### Syntax {#from-subquery-syntax} - -```sql -SELECT expression1[, expression2, ..., expressionN] FROM () -``` - -### Examples {#from-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "View `FROM` clause subquery example" %}} - -The following query returns the average of maximum values per room. -The inner query returns the maximum value for each field from each room. -The outer query uses the results of the inner query and returns the average -maximum value for each field. - -```sql -SELECT - AVG(max_co) AS avg_max_co, - AVG(max_hum) AS avg_max_hum, - AVG(max_temp) AS avg_max_temp -FROM - ( - SELECT - room, - MAX(co) AS max_co, - MAX(hum) AS max_hum, - MAX(temp) AS max_temp - FROM - home - GROUP BY - room - ) -``` - -#### Inner query results - -| room | max_co | max_hum | max_temp | -| :---------- | -----: | ------: | -------: | -| Living Room | 17 | 36.4 | 22.8 | -| Kitchen | 26 | 36.9 | 23.3 | - -#### Outer query results - -| avg_max_co | avg_max_hum | avg_max_temp | -| ---------: | ----------: | -----------: | -| 21.5 | 36.7 | 23.1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## WHERE clause subqueries - -[`WHERE` clause](/influxdb/cloud-dedicated/reference/sql/where/) subqueries -compare an expression to the result of the subquery and return _true_ or _false_. -Rows that evaluate to _false_ or NULL are filtered from results. -The `WHERE` clause supports correlated and non-correlated subqueries -as well as scalar and non-scalar subqueries (depending on the the operator used -in the predicate expression). - -### Syntax {#where-subquery-syntax} - -```sql -SELECT - expression1[, expression2, ..., expressionN] -FROM - -WHERE - expression operator () -``` - -{{% note %}} -`WHERE` clause subqueries can be used as an alternative to `JOIN` operations. -{{% /note %}} - -### Examples {#where-subquery-examples} -{{< expand-wrapper >}} -{{% expand "`WHERE` clause with scalar subquery" %}} - -The following query returns all points with `temp` values above the average -of all `temp` values. The subquery returns the average `temp` value. - -```sql -SELECT - * -FROM - home -WHERE - temp > ( - SELECT - AVG(temp) - FROM - home - ) -``` - -#### Inner query result - -| AVG(home.temp) | -| :----------------- | -| 22.396153846153844 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | -| 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | -| 3 | 36.2 | Kitchen | 22.7 | 2022-01-01T15:00:00Z | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | -| 0 | 36 | Living Room | 22.4 | 2022-01-01T13:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`WHERE` clause with non-scalar subquery" %}} - -Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and -can only return a single column. -The values in the returned column are evaluated as a list. - -The following query returns all points in the `home` measurement associated with -the same timestamps as `warn` level alerts in the `home_actions` measurement. - -```sql -SELECT - * -FROM - home -WHERE - time IN ( - SELECT - DISTINCT time - FROM - home_actions - WHERE - level = 'warn' - ) -``` - -#### Inner query result - -{{% influxdb/custom-timestamps %}} -| time | -| :------------------- | -| 2022-01-01T18:00:00Z | -| 2022-01-01T19:00:00Z | -| 2022-01-01T20:00:00Z | -{{% /influxdb/custom-timestamps %}} - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | -| 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`WHERE` clause with correlated subquery" %}} - -The following query returns rows with temperature values greater than the median -temperature value for each room. The subquery in the `WHERE` clause uses the -`room` value from the outer query to return the median `temp` value for that -specific room. - -```sql -SELECT - time, - room, - temp -FROM - home outer_query -WHERE - temp > ( - SELECT - median(temp) AS temp - FROM - home - WHERE - room = outer_query.room - GROUP BY - room - ) -ORDER BY room, time -``` - -#### Inner query result - -The result of the inner query depends on the value of `room` in the outer query, -but the following table contains the median `temp` value for each room. - -| room | temp | -| :---------- | ---: | -| Living Room | 22.3 | -| Kitchen | 22.7 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| time | room | temp | -| :------------------- | :---------- | ---: | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T13:00:00Z | Kitchen | 22.8 | -| 2022-01-01T14:00:00Z | Kitchen | 22.8 | -| 2022-01-01T18:00:00Z | Kitchen | 23.3 | -| 2022-01-01T19:00:00Z | Kitchen | 23.1 | -| 2022-01-01T13:00:00Z | Living Room | 22.4 | -| 2022-01-01T16:00:00Z | Living Room | 22.4 | -| 2022-01-01T17:00:00Z | Living Room | 22.6 | -| 2022-01-01T18:00:00Z | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | Living Room | 22.5 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## HAVING clause subqueries - -[`HAVING` clause](/influxdb/cloud-dedicated/reference/sql/having/) subqueries -compare an expression that uses aggregate values returned by aggregate functions -in the `SELECT` clause to the result of the subquery and return _true_ or _false_. -Rows that evaluate to _false_ or NULL are filtered from results. -The `HAVING` clause supports correlated and non-correlated subqueries -as well as scalar and non-scalar subqueries (depending on the the operator used -in the predicate expression). - -### Syntax {#having-subquery-syntax} - -```sql -SELECT - aggregate_expression1[, aggregate_expression2, ..., aggregate_expressionN] -FROM - -WHERE - -GROUP BY - column_expression1[, column_expression2, ..., column_expressionN] -HAVING - expression operator () -``` - -### Examples {#having-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "`HAVING` clause with scalar subquery" %}} - -The following query returns all two hour blocks of time with average `temp` values -greater then the median `temp` value. - -```sql -SELECT - DATE_BIN(INTERVAL '2 hours', time) AS "2-hour block", - AVG(temp) AS avg_temp -FROM - home -GROUP BY - 1 -HAVING - avg_temp > ( - SELECT - MEDIAN(temp) - FROM - home - ) -``` - -#### Inner query result - -| MEDIAN(home.temp) | -| :---------------- | -| 22.45 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | avg_temp | -| :------------------- | -------: | -| 2022-01-01T12:00:00Z | 22.475 | -| 2022-01-01T16:00:00Z | 22.525 | -| 2022-01-01T18:00:00Z | 22.925 | -| 2022-01-01T14:00:00Z | 22.525 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`HAVING` clause with non-scalar subquery" %}} - -Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and -can only return a single column. -The values in the returned column are evaluated as a list. - -The following query returns the maximum `co` and `temp` values within 2-hour -windows of time where the `time` value associated with time window is also -associated with a warning in the `home_actions` measurement. - -```sql -SELECT - date_bin(INTERVAL '2 hours', time) AS "2-hour block", - max(co) AS max_co, - max(temp) as max_temp -FROM - home -GROUP BY - 1, - room -HAVING - "2-hour block" IN ( - SELECT - DISTINCT time - FROM - home_actions - WHERE - level = 'warn' - ) -``` - -#### Inner query result - -{{% influxdb/custom-timestamps %}} -| time | -| :------------------- | -| 2022-01-01T18:00:00Z | -| 2022-01-01T19:00:00Z | -| 2022-01-01T20:00:00Z | -{{% /influxdb/custom-timestamps %}} - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | max_co | max_temp | -| :------------------- | -----: | -------: | -| 2022-01-01T18:00:00Z | 14 | 22.8 | -| 2022-01-01T18:00:00Z | 22 | 23.3 | -| 2022-01-01T20:00:00Z | 17 | 22.2 | -| 2022-01-01T20:00:00Z | 26 | 22.7 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`HAVING` clause with correlated subquery" %}} - -The following query returns 2-hour windows of time with average `temp` values -greater than the median `temp` value for each room. The subquery in the `HAVING` -clause uses the `room` value from the outer query to return the median `temp` value -for that specific room. - -```sql -SELECT - time, - room, - temp -FROM - home outer_query -WHERE - temp > ( - SELECT - median(temp) AS temp - FROM - home - WHERE - room = outer_query.room - GROUP BY - room - ) -ORDER BY room, time -``` - -#### Inner query result - -The result of the inner query depends on the value of `room` in the outer query, -but the following table contains the median `temp` value for each room. - -| room | temp | -| :---------- | ---: | -| Living Room | 22.3 | -| Kitchen | 22.7 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | room | avg_temp | -| :------------------- | :---------- | -----------------: | -| 2022-01-01T14:00:00Z | Kitchen | 22.75 | -| 2022-01-01T18:00:00Z | Kitchen | 23.200000000000003 | -| 2022-01-01T16:00:00Z | Living Room | 22.5 | -| 2022-01-01T18:00:00Z | Living Room | 22.65 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Subquery categories - -SQL subqueries can be categorized as one or more of the following based on the -behavior of the subquery: - -- [correlated](#correlated-subqueries) or [non-correlated](#non-correlated-subqueries) -- [scalar](#scalar-subqueries) or [non-scalar](#non-scalar-subqueries) - -### Correlated subqueries - -In a **correlated** subquery, the inner query depends on the values of the -current row being processed. - -In the query below, the inner query (`SELECT temp_avg FROM weather WHERE location = home.room`) -depends on data (`home.room`) from the outer query -(`SELECT time, room, temp FROM home`) and is therefore a _correlated_ subquery. - -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - temp = ( - SELECT - temp_avg - FROM - weather - WHERE - location = home.room - ) -``` - -{{% note %}} -#### Correlated subquery performance - -Because correlated subqueries depend on the outer query and typically must -execute for each row returned by the outer query, correlated subqueries are -**less performant** than non-correlated subqueries. -{{% /note %}} - -### Non-correlated subqueries - -In a **non-correlated** subquery, the inner query _doesn't_ depend on the outer -query and executes independently. -The inner query executes first, and then passes the results to the outer query. - -In the query below, the inner query (`SELECT MIN(temp_avg) FROM weather`) can -run independently from the outer query (`SELECT time, temp FROM home`) and is -therefore a _non-correlated_ subquery. - -```sql -SELECT - time, - temp -FROM - home -WHERE - temp < ( - SELECT - MIN(temp_avg) - FROM - weather - ) -``` - -### Scalar subqueries - -A **scalar** subquery returns a single value (one column of one row). -If no rows are returned, the subquery returns NULL. - -The example subquery below returns the average value of a specified column. -This value is a single scalar value. - -```sql -SELECT * FROM home WHERE co > (SELECT avg(co) FROM home) -``` - -### Non-scalar subqueries - -A **non-scalar** subquery returns 0, 1, or multiple rows, each of which may -contain 1 or multiple columns. For each column, if there is no value to return, -the subquery returns NULL. If no rows qualify to be returned, the subquery -returns 0 rows. - -The example subquery below returns all distinct values in a column. -Multiple values are returned. - -```sql -SELECT * FROM home WHERE room IN (SELECT DISTINCT room FROM home_actions) -``` \ No newline at end of file + diff --git a/content/influxdb/cloud-dedicated/reference/sql/table-value-constructor.md b/content/influxdb/cloud-dedicated/reference/sql/table-value-constructor.md index f01f26250..8951ee48c 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/table-value-constructor.md +++ b/content/influxdb/cloud-dedicated/reference/sql/table-value-constructor.md @@ -7,115 +7,10 @@ menu: influxdb_cloud_dedicated: parent: SQL reference weight: 220 + +source: /content/shared/sql-reference/table-value-constructor.md --- -The table value constructor (TVC) uses the `VALUES` keyword to specify a set of -row value expressions to construct into a table. -The TVC can be used in the `FROM` clause -to build an ad hoc table at query time. - -```sql -VALUES (row_value_list)[,...n] -``` - -##### Arguments - -- **row_value_list**: - Comma-delimited list of column values. - Enclose each list in parentheses and separate multiple lists with commas. - Each list must have the same number of values and values must be in the same - order as columns in the table. - Each list must contain a value for each column. - -## Usage - -```sql -SELECT - expression[,...n] -FROM - (VALUES (row_value_list)[,...n]) [AS] table_name(column_name[,...n]) -``` - -{{% note %}} -When using the TVC, the `AS` keyword is optional and implied when naming the -table and providing column names. -{{% /note %}} - -## Examples - -- [Select data from an ad hoc table](#select-data-from-an-ad-hoc-table) - - -### Select data from an ad hoc table - -```sql -SELECT * -FROM - (VALUES ('2023-01-01 12:00:00'::TIMESTAMP, 1.23, 4.56), - ('2023-01-01 13:00:00'::TIMESTAMP, 2.46, 8.1), - ('2023-01-01 13:00:00'::TIMESTAMP, 4.81, 16.2) - ) AS data(time, f1, f2) -``` - -| time | f1 | f2 | -| :------------------- | ---: | ---: | -| 2023-01-01T12:00:00Z | 1.23 | 4.56 | -| 2023-01-01T13:00:00Z | 2.46 | 8.1 | -| 2023-01-01T13:00:00Z | 4.81 | 16.2 | - - + diff --git a/content/influxdb/cloud-dedicated/reference/sql/union.md b/content/influxdb/cloud-dedicated/reference/sql/union.md index 778b1eadd..9188a76a6 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/union.md +++ b/content/influxdb/cloud-dedicated/reference/sql/union.md @@ -8,161 +8,10 @@ menu: name: UNION clause parent: SQL reference weight: 206 + +source: /content/shared/sql-reference/union.md --- -The `UNION` clause combines the results of two or more `SELECT` statements into -a single result set. -By default, `UNION` only keeps unique rows. -To keep all rows, including duplicates, use `UNION ALL`. - -- [Syntax](#syntax) -- [Examples](#examples) - -**When using the `UNION` clause**: - -- The number of columns in each result set must be the same. -- Columns must be in the same order and of the same or compatible data types. - -## Syntax - -```sql -SELECT expression[,...n] -FROM measurement_1 -UNION [ALL] -SELECT expression[,...n] -FROM measurement_2 -``` - -## Examples - -- [Union results from different measurements](#union-results-from-different-measurements) -- [Return the highest and lowest three results in a single result set](#return-the-highest-and-lowest-three-results-in-a-single-result-set) -- [Union query results with custom data](#union-query-results-with-custom-data) - -### Union results from different measurements - -```sql -( - SELECT - 'h2o_pH' AS measurement, - time, - "pH" AS "water_pH" - FROM "h2o_pH" - LIMIT 4 -) -UNION -( - SELECT - 'h2o_quality' AS measurement, - time, - index - FROM h2o_quality - LIMIT 4 -) -``` -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| measurement | time | water_pH | -| :---------- | :------------------- | -------: | -| h2o_pH | 2019-08-27T00:12:00Z | 7 | -| h2o_pH | 2019-08-27T00:18:00Z | 8 | -| h2o_quality | 2019-09-11T01:06:00Z | 89 | -| h2o_pH | 2019-08-27T00:06:00Z | 7 | -| h2o_quality | 2019-09-11T00:00:00Z | 26 | -| h2o_quality | 2019-09-11T01:00:00Z | 19 | -| h2o_quality | 2019-09-11T00:48:00Z | 65 | -| h2o_pH | 2019-08-27T00:00:00Z | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Return the highest and lowest three results in a single result set - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol)._ - -```sql -( - SELECT - 'low' as type, - time, - co - FROM home - ORDER BY co ASC - LIMIT 3 -) -UNION -( - SELECT - 'high' as type, - time, - co - FROM home - ORDER BY co DESC - LIMIT 3 -) -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| type | time | co | -| :--- | :------------------- | --: | -| high | 2022-01-01T20:00:00Z | 26 | -| high | 2022-01-01T19:00:00Z | 22 | -| high | 2022-01-01T18:00:00Z | 18 | -| low | 2022-01-01T14:00:00Z | 0 | -| low | 2022-01-01T10:00:00Z | 0 | -| low | 2022-01-01T08:00:00Z | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Union query results with custom data - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-dedicated/get-started/write/#construct-line-protocol). -It also uses the [table value constructor](/influxdb/cloud-dedicated/reference/sql/table-value-constructor/) -to build a table with custom data._ - -```sql -SELECT * -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -UNION -SELECT * FROM - (VALUES (0, 34.2, 'Bedroom', 21.1, '2022-01-01T08:00:00Z'::TIMESTAMP), - (0, 34.5, 'Bedroom', 21.2, '2022-01-01T09:00:00Z'::TIMESTAMP), - (0, 34.6, 'Bedroom', 21.5, '2022-01-01T10:00:00Z'::TIMESTAMP), - (0, 34.5, 'Bedroom', 21.8, '2022-01-01T11:00:00Z'::TIMESTAMP), - (0, 33.9, 'Bedroom', 22.0, '2022-01-01T12:00:00Z'::TIMESTAMP) - ) newRoom(co, hum, room, temp, time) -ORDER BY room, time -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 34.2 | Bedroom | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 34.5 | Bedroom | 21.2 | 2022-01-01T09:00:00Z | -| 0 | 34.6 | Bedroom | 21.5 | 2022-01-01T10:00:00Z | -| 0 | 34.5 | Bedroom | 21.8 | 2022-01-01T11:00:00Z | -| 0 | 33.9 | Bedroom | 22 | 2022-01-01T12:00:00Z | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | -| 0 | 35.9 | Living Room | 22.2 | 2022-01-01T12:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/reference/sql/where.md b/content/influxdb/cloud-dedicated/reference/sql/where.md index d0801b86c..bf49d5086 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/where.md +++ b/content/influxdb/cloud-dedicated/reference/sql/where.md @@ -10,125 +10,10 @@ menu: weight: 202 related: - /influxdb/cloud-dedicated/reference/sql/subqueries/ + +source: /content/shared/sql-reference/where.md --- -Use the `WHERE` clause to filter results based on fields, tags, or timestamps. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause WHERE [(AND|OR) [...]] -``` - -{{% note %}} -**Note:** Unlike InfluxQL, SQL **supports** `OR` in the `WHERE` clause to specify multiple conditions, including time ranges. -{{% /note %}} - -## Examples - -Note that single quotes are required for string literals in the `WHERE` clause. - -### Filter data based on field values - -```sql -SELECT * -FROM "h2o_feet" -WHERE "water_level" >= 9.78 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns data from the `h2o_feet` measurement with `water_level` field values -that are greater than or equal to 9.78. - -| level description | location | time | water_level | -| :------------------------ | :----------- | :----------------------- | :---------- | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:06:00.000Z | 9.8 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:12:00.000Z | 9.829 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:18:00.000Z | 9.862 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:24:00.000Z | 9.892 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:30:00.000Z | 9.902 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:36:00.000Z | 9.898 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - -### Filter data based on specific tag and field values - -```sql -SELECT * -FROM "h2o_feet" -WHERE "location" = 'santa_monica' and "level description" = 'below 3 feet' -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns all data from the `h2o_feet` measurement with the `location` tag key, `santa_monica`, -and a `level description` field value that equals `below 3 feet`. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | santa_monica | 2019-09-01T00:00:00.000Z | 1.529 | -| below 3 feet | santa_monica | 2019-09-01T00:06:00.000Z | 1.444 | -| below 3 feet | santa_monica | 2019-09-01T00:12:00.000Z | 1.335 | -| below 3 feet | santa_monica | 2019-09-01T00:18:00.000Z | 1.345 | -| below 3 feet | santa_monica | 2019-09-01T00:24:00.000Z | 1.27 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Filter data within a specific time period - -```sql -SELECT * -FROM h2o_feet -WHERE "location" = 'santa_monica' -AND "time" >= '2019-08-19T12:00:00Z'::timestamp AND "time" <= '2019-08-19T13:00:00Z'::timestamp -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns results with timestamps greater than or equal to `08-19-2019T12:00:00Z` and -less than or equal to `08-19-2019T13:00:00Z`. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | santa_monica | 2019-08-19T12:00:00.000Z | 2.533 | -| below 3 feet | santa_monica | 2019-08-19T12:06:00.000Z | 2.543 | -| below 3 feet | santa_monica | 2019-08-19T12:12:00.000Z | 2.385 | -| below 3 feet | santa_monica | 2019-08-19T12:18:00.000Z | 2.362 | -| below 3 feet | santa_monica | 2019-08-19T12:24:00.000Z | 2.405 | -| below 3 feet | santa_monica | 2019-08-19T12:30:00.000Z | 2.398 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Filter data using the OR operator - -```sql -SELECT * -FROM "h2o_feet" -WHERE "level description" = 'less than 3 feet' OR "water_level" < 2.5 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns results with a `level description` field value equal to `less than 3 feet` or a `water_level` field value less than 2.5. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | coyote_creek | 2019-08-25T10:06:00.000Z | 2.398 | -| below 3 feet | coyote_creek | 2019-08-25T10:12:00.000Z | 2.234 | -| below 3 feet | coyote_creek | 2019-08-25T10:18:00.000Z | 2.064 | -| below 3 feet | coyote_creek | 2019-08-25T10:24:00.000Z | 1.893 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md b/content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md index e7a5dbeeb..fbb22ebec 100644 --- a/content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md +++ b/content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md @@ -119,7 +119,7 @@ The following steps set up a Go project using the which provides the InfluxDB `influxdb3` Go client library module. ```sh - go get github.com/InfluxCommunity/influxdb3-go + go get github.com/InfluxCommunity/influxdb3-go/v2 ``` @@ -228,7 +228,7 @@ points. "os" "fmt" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" "github.com/influxdata/line-protocol/v2/lineprotocol" ) diff --git a/content/influxdb/cloud-dedicated/write-data/troubleshoot.md b/content/influxdb/cloud-dedicated/write-data/troubleshoot.md index 97720907d..5c1759906 100644 --- a/content/influxdb/cloud-dedicated/write-data/troubleshoot.md +++ b/content/influxdb/cloud-dedicated/write-data/troubleshoot.md @@ -32,9 +32,8 @@ Learn how to avoid unexpected results and recover from errors when writing to {{ 2. If successful, attempts to [ingest data](/influxdb/cloud-dedicated/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](#review-http-status-codes). 3. Ingests or rejects data in the batch and returns one of the following HTTP status codes: - - `204 No Content`: all data in the batch is ingested - - `201 Created` (_If the cluster is configured to allow **partial writes**_): some points in the batch are ingested and queryable, and some points are rejected - - `400 Bad Request`: all data is rejected + - `204 No Content`: All data in the batch is ingested. + - `400 Bad Request`: Some (_when **partial writes** are configured for the cluster_) or all of the data has been rejected. Data that has not been rejected is ingested and queryable. The response body contains error details about [rejected points](#troubleshoot-rejected-points), up to 100 points. @@ -51,9 +50,8 @@ The `message` property of the response body may contain additional details about | HTTP response code | Response body | Description | |:------------------------------|:------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `201 "Created"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections | _If **partial writes** are configured for the cluster_, and if some of the data is ingested and some of the data is rejected | | `204 No Content"` | no response body | If InfluxDB ingested all of the data in the batch | -| `400 "Bad request"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections line | If request data is malformed | +| `400 "Bad request"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections | If some (_when **partial writes** are configured for the cluster_) or all request data isn't allowed (for example, if it is malformed or falls outside of the bucket's retention period)--the response body indicates whether a partial write has occurred or if all data has been rejected | | `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-dedicated/admin/tokens/) doesn't have [permission](/influxdb/cloud-dedicated/reference/cli/influxctl/token/create/#examples) to write to the database. See [examples using credentials](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb) in write requests. | | `404 "Not found"` | requested **resource type** (for example, "organization" or "database"), and **resource name** | If a requested resource (for example, organization or database) wasn't found | | `422 "Unprocessable Entity"` | `message` contains details about the error | If the data isn't allowed (for example, falls outside of the database’s retention period). diff --git a/content/influxdb/cloud-serverless/_index.md b/content/influxdb/cloud-serverless/_index.md index 2149d7656..494e92d8c 100644 --- a/content/influxdb/cloud-serverless/_index.md +++ b/content/influxdb/cloud-serverless/_index.md @@ -11,25 +11,29 @@ menu: weight: 1 --- -{{% note %}} -This InfluxDB Cloud documentation applies to all [organizations](/influxdb/cloud-serverless/admin/organizations/) created through -**cloud2.influxdata.com** on or after **January 31, 2023** that are powered by -the InfluxDB v3 storage engine. If your organization was created before this -date or through the Google Cloud Platform (GCP) or Azure marketplaces, see the -[InfluxDB Cloud (TSM) documentation](/influxdb/cloud/). +> [!Note] +> This InfluxDB Cloud documentation applies to all [organizations](/influxdb/cloud-serverless/admin/organizations/) created through +> **cloud2.influxdata.com** on or after **January 31, 2023** that are powered by +> the InfluxDB v3 storage engine. If your organization was created before this +> date or through the Google Cloud Platform (GCP) or Azure marketplaces, see the +> [InfluxDB Cloud (TSM) documentation](/influxdb/cloud/). +> +> To see which storage engine your organization is using, +> find the **InfluxDB Cloud powered by** link in your +> [InfluxDB Cloud organization homepage](https://cloud2.influxdata.com) version information. +> If your organization is using InfluxDB v3, you'll see +> **InfluxDB Cloud Serverless** followed by the version number. -To see which storage engine your organization is using, -find the **InfluxDB Cloud powered by** link in your -[InfluxDB Cloud organization homepage](https://cloud2.influxdata.com) version information. -If your organization is using InfluxDB v3, you'll see -**InfluxDB Cloud Serverless** followed by the version number. +> [!Warn] +> #### InfluxDB v3 and Flux +> +> InfluxDB Cloud Serverless and other InfluxDB v3 products don't support Flux. +> Although Flux might still work with {{% product-name %}}, it isn't +> officially supported or optimized for InfluxDB v3. +> +> Flux is now in maintenance mode. For more information, see +> [The future of Flux](/flux/v0/future-of-flux). -#### InfluxDB v3 and Flux - -InfluxDB Cloud Serverless and other InfluxDB v3 products do not support Flux. -Flux is now in maintenance mode. For more information, see -[The future of Flux](/flux/v0/future-of-flux). -{{% /note %}} InfluxDB Cloud Serverless is a hosted and managed version of InfluxDB backed by InfluxDB 3.0, the time series platform designed to handle high write and query loads. diff --git a/content/influxdb/cloud-serverless/admin/billing/limits.md b/content/influxdb/cloud-serverless/admin/billing/limits.md index 34f130434..c04ac3028 100644 --- a/content/influxdb/cloud-serverless/admin/billing/limits.md +++ b/content/influxdb/cloud-serverless/admin/billing/limits.md @@ -153,7 +153,7 @@ number of columns allowed in a table. - Consider storing new fields in a new [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) (not to exceed the [maximum number of tables](#maximum-number-of-tables-reached)). - Review [InfluxDB schema design recommendations](/influxdb/cloud-serverless/write-data/best-practices/schema-design/). -- Customers with an annual or support contract can contact [InfluxData Support](https://support.influxdata.com) to request a review of their database schema. +- Customers with an [annual or support contract](https://www.influxdata.com/influxdb-cloud-pricing/) can contact [InfluxData Support](https://support.influxdata.com) to request a review of their database schema. #### Maximum number of tables reached diff --git a/content/influxdb/cloud-serverless/get-started/query.md b/content/influxdb/cloud-serverless/get-started/query.md index 823cd453a..7fc2a7d93 100644 --- a/content/influxdb/cloud-serverless/get-started/query.md +++ b/content/influxdb/cloud-serverless/get-started/query.md @@ -160,7 +160,7 @@ WHERE {{% influxdb/custom-timestamps %}} ```sql SELECT - DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time, + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') as _time, room, selector_max(temp, time)['value'] AS 'max temp' FROM @@ -538,8 +538,7 @@ _If your project's virtual environment is already running, skip to step 3._ "time" "text/tabwriter" - "github.com/apache/arrow/go/v13/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -583,10 +582,9 @@ _If your project's virtual environment is already running, skip to step 3._ // Iterate over rows and prints column values in table format. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339). - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) @@ -606,8 +604,7 @@ _If your project's virtual environment is already running, skip to step 3._ - `io` - `os` - `text/tabwriter` - - `github.com/apache/arrow/go/v13/arrow` - - `github.com/InfluxCommunity/influxdb3-go/influxdb3` + - `github.com/InfluxCommunity/influxdb3-go/v2/influxdb3` 2. Defines a `Query()` function that does the following: diff --git a/content/influxdb/cloud-serverless/get-started/write.md b/content/influxdb/cloud-serverless/get-started/write.md index cd358cdb4..b31439c80 100644 --- a/content/influxdb/cloud-serverless/get-started/write.md +++ b/content/influxdb/cloud-serverless/get-started/write.md @@ -804,7 +804,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu "fmt" "log" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) // Write line protocol data to InfluxDB diff --git a/content/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless.md b/content/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless.md index 6e1f8126b..2e62533b8 100644 --- a/content/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless.md +++ b/content/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless.md @@ -23,10 +23,9 @@ the exported data to a bucket in your InfluxDB Cloud Serverless organization. Because full data migrations will likely exceed your organizations' limits and adjustable quotas, migrate your data in batches. -{{% cloud %}} -All write requests are subject to your InfluxDB Cloud Serverless organization's -[rate limits and adjustable quotas](/influxdb/cloud-serverless/account-management/limits/). -{{% /cloud %}} +> [!Important] +> All write requests are subject to your InfluxDB Cloud Serverless organization's +> [rate limits and adjustable quotas](/influxdb/cloud-serverless/account-management/limits/). diff --git a/content/influxdb/cloud-serverless/guides/migrate-data/migrate-tsm-to-serverless.md b/content/influxdb/cloud-serverless/guides/migrate-data/migrate-tsm-to-serverless.md index 97418e25a..bfaeb6907 100644 --- a/content/influxdb/cloud-serverless/guides/migrate-data/migrate-tsm-to-serverless.md +++ b/content/influxdb/cloud-serverless/guides/migrate-data/migrate-tsm-to-serverless.md @@ -31,10 +31,9 @@ that queries data from an InfluxDB Cloud TSM-powered bucket in time-based batche and writes each batch to an InfluxDB Cloud Serverless (InfluxDB v3) bucket in another organization. -{{% cloud %}} -All query and write requests are subject to your InfluxDB Cloud organization's -[rate limits and adjustable quotas](/influxdb/cloud-serverless/account-management/limits/). -{{% /cloud %}} +> [!Important] +> All query and write requests are subject to your InfluxDB Cloud organization's +> [rate limits and adjustable quotas](/influxdb/cloud-serverless/account-management/limits/). - [Before you migrate](#before-you-migrate) - [Set up the migration](#set-up-the-migration) diff --git a/content/influxdb/cloud-serverless/query-data/execute-queries/client-libraries/go.md b/content/influxdb/cloud-serverless/query-data/execute-queries/client-libraries/go.md index 629ebb93a..6e11e6d34 100644 --- a/content/influxdb/cloud-serverless/query-data/execute-queries/client-libraries/go.md +++ b/content/influxdb/cloud-serverless/query-data/execute-queries/client-libraries/go.md @@ -21,7 +21,7 @@ list_code_example: | ```go import ( "context" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -94,7 +94,7 @@ to install a recent version of the Go programming language for your system. In your terminal, enter the following command to download and install the client library: ```sh -go get github.com/InfluxCommunity/influxdb3-go +go get github.com/InfluxCommunity/influxdb3-go/v2 ``` - [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go) {{< req text="\* " color="magenta" >}}: Provides the `influxdb3` package and also installs the [Apache `arrow` module](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries. @@ -138,8 +138,7 @@ import ( "text/tabwriter" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" - "github.com/apache/arrow/go/v13/arrow" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -186,10 +185,9 @@ func Query() error { fmt.Fprintln(w, "Process each row as key-value pairs:") for iterator2.Next() { row := iterator2.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) @@ -235,8 +233,7 @@ import ( "text/tabwriter" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" - "github.com/apache/arrow/go/v13/arrow" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func InfluxQL() error { @@ -288,10 +285,9 @@ func InfluxQL() error { fmt.Fprintln(w, "Process each row as key-value pairs:") for iterator2.Next() { row := iterator2.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md b/content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md index 949636421..6b9a3ba05 100644 --- a/content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md +++ b/content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md @@ -62,7 +62,8 @@ For {{% product-name %}} v1 API `/query` requests, set parameters as listed in t Parameter | Allowed in | Ignored | Value ------------|--------------|---------|------------------------------------------------------------------------- -`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_ +`chunked` | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. +`chunked_size` | Query string | Honored | **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. `db` | Query string | Honored | Database name [mapped to a bucket](/influxdb/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets) `epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision) `pretty` | Query string | Ignored | N/A diff --git a/content/influxdb/cloud-serverless/query-data/influxql/parameterized-queries.md b/content/influxdb/cloud-serverless/query-data/influxql/parameterized-queries.md index 28d97f66f..27faaf457 100644 --- a/content/influxdb/cloud-serverless/query-data/influxql/parameterized-queries.md +++ b/content/influxdb/cloud-serverless/query-data/influxql/parameterized-queries.md @@ -257,8 +257,7 @@ import ( "os" "text/tabwriter" "time" - "github.com/apache/arrow/go/v14/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query(query string, parameters influxdb3.QueryParameters, @@ -301,10 +300,10 @@ func Query(query string, parameters influxdb3.QueryParameters, // Process each row as key-value pairs. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339 format) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.Nanosecond).Format(time.RFC3339) + time := (row["time"].(time.Time)). + Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md b/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md index f63fd487f..30aae448f 100644 --- a/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md +++ b/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md @@ -28,7 +28,7 @@ list_code_example: | ##### Aggregate by time-based intervals ```sql SELECT - DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) AS time, + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') AS time, mean(field1), sum(field2), tag1 @@ -206,7 +206,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time FROM home ... ``` @@ -224,7 +224,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time ... GROUP BY 1, room ... @@ -234,7 +234,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS _time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time FROM home ... GROUP BY _time, room @@ -246,7 +246,7 @@ The following example retrieves unique combinations of time intervals and rooms ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', @@ -287,7 +287,7 @@ If you want to reference a calculated time column by name, use an alias differen ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time, room, selector_max(temp, time)['value'] AS 'max temp', diff --git a/content/influxdb/cloud-serverless/query-data/sql/parameterized-queries.md b/content/influxdb/cloud-serverless/query-data/sql/parameterized-queries.md index 094485874..ff6830a0a 100644 --- a/content/influxdb/cloud-serverless/query-data/sql/parameterized-queries.md +++ b/content/influxdb/cloud-serverless/query-data/sql/parameterized-queries.md @@ -254,8 +254,7 @@ import ( "os" "text/tabwriter" "time" - "github.com/apache/arrow/go/v14/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query(query string, parameters influxdb3.QueryParameters) error { @@ -297,10 +296,10 @@ func Query(query string, parameters influxdb3.QueryParameters) error { // Process each row as key-value pairs. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339 format) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.Nanosecond).Format(time.RFC3339) + time := (row["time"].(time.Time)). + Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan.md b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan.md index e2926ca49..8d61f5508 100644 --- a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan.md +++ b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan.md @@ -24,7 +24,7 @@ By learning how to generate and interpret reports for the query plan, you can better understand how the query is executed and identify bottlenecks that affect the performance of your query. For example, if the query plan reveals that your query reads a large number of Parquet files, -you can then take steps to [optimize your query](/influxdb/cloud-serverless/query-data/optimize-queries/), such as add filters to read less data. +you can then take steps to [optimize your query](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries/), such as add filters to read less data. - [Use EXPLAIN keywords to view a query plan](#use-explain-keywords-to-view-a-query-plan) - [Read an EXPLAIN report](#read-an-explain-report) @@ -65,7 +65,7 @@ import pandas as pd import tabulate # Required for pandas.to_markdown() # Instantiate an InfluxDB client. -client = InfluxDBClient3(token = f"TOKEN", +client = InfluxDBClient3(token = f"API_TOKEN", host = f"{{< influxdb/host >}}", database = f"BUCKET_NAME") @@ -109,7 +109,7 @@ Plans are in _tree format_--each plan is an upside-down tree in which execution and data flow from _leaf nodes_, the innermost steps in the plan, to outer _branch nodes_. Whether reading a logical or physical plan, keep the following in mind: -- Start at the the _leaf nodes_ and read upward. +- Start at the _leaf nodes_ and read upward. - At the top of the plan, the _root node_ represents the final, encompassing execution step. In a [physical plan](/influxdb/cloud-serverless/reference/internals/query-plan/#physical-plan), each step is an [`ExecutionPlan` node](/influxdb/cloud-serverless/reference/internals/query-plan/#executionplan-nodes) that receives expressions for input data and output requirements, and computes a partition of data. @@ -766,4 +766,4 @@ Operator structure for aggregating, sorting, and final output. - `SortPreservingMergeExec: [city@0 ASC NULLS LAST]`: Merges and sorts the four sorted streams for the final output. In the preceding examples, the `EXPLAIN` report shows the query plan without executing the query. -To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/cloud-serverless/reference/sql/explain/#explain-analyze) to generate the report and [tracing](/influxdb/cloud-serverless/query-data/optimize-queries/#enable-trace-logging) for further debugging, if necessary. +To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/cloud-serverless/reference/sql/explain/#explain-analyze) to generate the report and [tracing](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries/#enable-trace-logging) for further debugging, if necessary. diff --git a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md index c4856774a..11baace57 100644 --- a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md +++ b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries.md @@ -15,44 +15,45 @@ related: - /influxdb/cloud-serverless/query-data/execute-queries/analyze-query-plan/ aliases: - /influxdb/cloud-serverless/query-data/execute-queries/optimize-queries/ + - /influxdb/cloud-serverless/query-data/optimize-queries/ --- Optimize SQL and InfluxQL queries to improve performance and reduce their memory and compute (CPU) requirements. Learn how to use observability tools to analyze query execution and view metrics. +> [!Note] +> +> #### Custom partitioning not supported +> +> {{% product-name %}} doesn't support custom partitioning. +> +> Custom partitioning can benefit queries that look for a specific tag value in the `WHERE` clause. +> To use custom partitioning, consider [InfluxDB Cloud Dedicated](/influxdb/cloud-dedicated/admin/custom-partitions/) +> or [InfluxDB Clustered](/influxdb/clustered/admin/custom-partitions/). + - [Why is my query slow?](#why-is-my-query-slow) - [Strategies for improving query performance](#strategies-for-improving-query-performance) - [Query only the data you need](#query-only-the-data-you-need) -- [Analyze and troubleshoot queries](#analyze-and-troubleshoot-queries) +- [Recognize and address bottlenecks](#recognize-and-address-bottlenecks) + ## Why is my query slow? -Query performance depends on time range and complexity. -If a query is slower than you expect, it might be due to the following reasons: +Query performance depends on factors like the time range and query complexity. +If a query is slower than expected, consider the following potential causes: -- It queries data from a large time range. -- It includes intensive operations, such as querying many string values or `ORDER BY` sorting or re-sorting large amounts of data. +- The query spans a large time range, which increases the amount of data being processed. +- The query performs intensive operations, such as: + - Sorting or re-sorting large datasets with `ORDER BY`. + - Querying many string values, which can be computationally expensive. ## Strategies for improving query performance -The following design strategies generally improve query performance and resource use: +The following design strategies generally improve query performance and resource usage: -- Follow [schema design best practices](/influxdb/cloud-dedicated/write-data/best-practices/schema-design/) to make querying easier and more performant. -- [Query only the data you need](#query-only-the-data-you-need). -- [Downsample data](/influxdb/cloud-dedicated/process-data/downsample/) to reduce the amount of data you need to query. - -Some bottlenecks may be out of your control and are the result of a suboptimal execution plan, such as: - -- Applying the same sort (`ORDER BY`) to already sorted data. -- Retrieving many Parquet files from the Object store--the same query performs better if it retrieves fewer - though, larger - files. -- Querying many overlapped Parquet files. -- Performing a large number of table scans. - -{{% note %}} -#### Analyze query plans to view metrics and recognize bottlenecks - -To view runtime metrics for a query, such as the number of files scanned, use the [`EXPLAIN ANALYZE` keywords](/influxdb/cloud-serverless/reference/sql/explain/#explain-analyze) and learn how to [analyze a query plan](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan/). -{{% /note %}} +- Follow [schema design best practices](/influxdb/cloud-serverless/write-data/best-practices/schema-design/) to simplify and improve queries. +- [Query only the data you need](#query-only-the-data-you-need) to reduce unnecessary processing. +- [Downsample data](/influxdb/cloud-serverless/process-data/downsample/) to decrease the volume of data queried. ### Query only the data you need @@ -61,7 +62,7 @@ To view runtime metrics for a query, such as the number of files scanned, use th InfluxDB v3 stores data in a Parquet file for each measurement and day, and retrieves files from the Object store to answer a query. To reduce the number of files that a query needs to retrieve from the Object store, -include a [`WHERE` clause](/influxdb/cloud-dedicated/reference/sql/where/) that +include a [`WHERE` clause](/influxdb/cloud-serverless/reference/sql/where/) that filters data by a time range. #### SELECT only columns you need @@ -82,15 +83,31 @@ two queries is minimal. In a table with over 1000 columns, the `SELECT *` query is slower and less efficient. -## Analyze and troubleshoot queries +## Recognize and address bottlenecks -Use the following tools to analyze and troubleshoot queries and find performance bottlenecks: +To identify performance bottlenecks, learn how to [analyze a query plan](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan/). +Query plans provide runtime metrics, such as the number of files scanned, that may reveal inefficiencies in query execution. -- [Analyze a query plan](/influxdb/cloud-serverless/query-data/analyze-query-plan/) -- [Enable trace logging for a query](#enable-trace-logging-for-a-query) - -### Enable trace logging for a query - -Customers with an {{% product-name %}} [annual or support contract](https://www.influxdata.com/influxdb-cloud-pricing/) can [contact InfluxData Support](https://support.influxdata.com/) to enable tracing and request help troubleshooting your query. -With tracing enabled, InfluxData Support can trace system processes and analyze log information for a query instance. -The tracing system follows the [OpenTelemetry traces](https://opentelemetry.io/docs/concepts/signals/traces/) model for providing observability into a request. +> [!Note] +> +> #### Request help to troubleshoot queries +> +> Some bottlenecks may result from suboptimal query [execution plans](/influxdb/cloud-serverless/reference/internals/query-plan/#physical-plan) that are outside your control. Examples include: +> +> - Sorting (`ORDER BY`) data that is already sorted. +> - Retrieving numerous small Parquet files from the object store instead of fewer, larger files. +> - Querying many overlapped Parquet files. +> - Performing a high number of table scans. +> +> If you've followed steps to [optimize](#why-is-my-query-slow) and +> [troubleshoot a query](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/troubleshoot/), +> but it still doesn't meet performance requirements, request help troubleshooting. +> Customers with an {{% product-name %}} [annual or support contract](https://www.influxdata.com/influxdb-cloud-pricing/) +> can [contact InfluxData Support](https://support.influxdata.com/) for assistance. +> +> #### Query trace logging +> +> Customers with an {{% product-name %}} [annual or support contract](https://www.influxdata.com/influxdb-cloud-pricing/) can [contact InfluxData Support](https://support.influxdata.com/) to enable tracing for queries. +> With tracing enabled, InfluxData Support can analyze system processes and logs for specific query instances. +> +> The tracing system uses the [OpenTelemetry traces](https://opentelemetry.io/docs/concepts/signals/traces/) model to provide observability into requests and identify performance bottlenecks. diff --git a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/troubleshoot.md b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/troubleshoot.md index 95f0d4e0c..08806691f 100644 --- a/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/troubleshoot.md +++ b/content/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/troubleshoot.md @@ -20,6 +20,8 @@ Troubleshoot SQL and InfluxQL queries that return unexpected results. - [Why doesn't my query return data?](#why-doesnt-my-query-return-data) - [Optimize slow or expensive queries](#optimize-slow-or-expensive-queries) +- [Analyze your queries](#analyze-your-queries) +- [Request help to troubleshoot queries](#request-help-to-troubleshoot-queries) ## Why doesn't my query return data? @@ -48,4 +50,40 @@ If a query times out or returns an error, it might be due to the following: If a query is slow or uses too many compute resources, limit the amount of data that it queries. -See how to [optimize queries](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries/) and use tools to view runtime metrics, identify bottlenecks, and debug queries. +See how to [optimize queries](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/optimize-queries/). + +## Analyze your queries + +Use the following tools to retrieve system query information, analyze query execution, +and find performance bottlenecks: + +- [Analyze a query plan](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/analyze-query-plan/) +- [Retrieve `system.queries` information for a query](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/system-information/) + +#### Request help to troubleshoot queries + +Some bottlenecks may result from suboptimal query [execution plans](/influxdb/cloud-serverless/reference/internals/query-plan/#physical-plan) and are outside your control--for example: + +- Sorting (`ORDER BY`) data that is already sorted +- Retrieving numerous small Parquet files from the object store, instead of fewer, larger files +- Querying many overlapped Parquet files +- Performing a high number of table scans + +If you've followed steps to [optimize](#why-is-my-query-slow) and +[troubleshoot a query](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/troubleshoot/), +but it still doesn't meet performance requirements, request help troubleshooting. +Customers with an {{% product-name %}} [annual or support contract](https://www.influxdata.com/influxdb-cloud-pricing/) +can [contact InfluxData Support](https://support.influxdata.com/) for assistance. + +> [!Note] +> +> #### Query trace logging +> +> Currently, customers cannot enable trace logging for {{% product-name omit="Clustered" %}} clusters. +> InfluxData engineers can use query plans and trace logging to help pinpoint performance bottlenecks in a query. +> +> If you've followed steps to [optimize](#why-is-my-query-slow) and +> [troubleshoot a query](/influxdb/cloud-serverless/query-data/troubleshoot-and-optimize/troubleshoot/), +> but it still doesn't meet performance requirements, request help troubleshooting. +> Customers with an {{% product-name %}} [annual or support contract](https://www.influxdata.com/influxdb-cloud-pricing/) +> can [contact InfluxData Support](https://support.influxdata.com/) for assistance. diff --git a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/_index.md b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/_index.md index f891b58fe..99612c1b8 100644 --- a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/_index.md +++ b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/_index.md @@ -10,10 +10,10 @@ weight: 101 influxdb/cloud-serverless/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/create.md b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/create.md index f004f4fcc..79347fe75 100644 --- a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/create.md +++ b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/create.md @@ -11,11 +11,11 @@ influxdb/cloud-serverless/tags: [authorization] updated_in: CLI v2.0.3 --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth create` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth create` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/delete.md b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/delete.md index 7b4746851..5294bf3e7 100644 --- a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/delete.md +++ b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/delete.md @@ -10,11 +10,11 @@ weight: 101 influxdb/cloud-serverless/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth delete` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth delete` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/list.md b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/list.md index 5fa185922..749e40683 100644 --- a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/list.md +++ b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/list.md @@ -10,11 +10,11 @@ weight: 101 influxdb/cloud-serverless/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth list` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth list` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-active.md b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-active.md index 91b26e5a6..996db4ebd 100644 --- a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-active.md +++ b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-active.md @@ -10,11 +10,11 @@ weight: 101 influxdb/cloud-serverless/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth set-active` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +>#### Not supported in InfluxDB Cloud +>**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +>Using the `influx v1 auth set-active` command with InfluxDB Cloud will result in an error. +>To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-inactive.md b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-inactive.md index 1b42bd385..36e47c5c6 100644 --- a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-inactive.md +++ b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-inactive.md @@ -10,11 +10,11 @@ weight: 101 influxdb/cloud-serverless/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth set-inactive` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth set-inactive` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-password.md b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-password.md index 101695a5b..f1270e318 100644 --- a/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-password.md +++ b/content/influxdb/cloud-serverless/reference/cli/influx/v1/auth/set-password.md @@ -11,11 +11,11 @@ influxdb/cloud-serverless/tags: [authorization] updated_in: CLI v2.0.3 --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth set-password` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth set-password` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md b/content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md index ac2ffbc89..ca89ed104 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md @@ -21,7 +21,7 @@ list_code_example: | sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, - '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', @@ -80,7 +80,7 @@ import tabulate sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, - '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/_index.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/_index.md index 67b783049..5cfd07120 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/_index.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/_index.md @@ -1,7 +1,7 @@ --- title: InfluxDB v2 API client libraries description: > - InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). + InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). View the list of available client libraries. weight: 101 menu: @@ -25,11 +25,10 @@ prepend: ## Client libraries for InfluxDB 2.x and 1.8+ InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. -InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). +InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). Functionality varies among client libraries. -These client libraries are in active development and may not be feature-complete. - +InfluxDB client libraries are maintained by the InfluxDB community. For specifics about a client library, see the library's GitHub repository. {{< children depth="999" type="list" >}} diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md index 968529dbf..a5874dc3f 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md @@ -35,11 +35,13 @@ Install the Node.js JavaScript client library to write data to InfluxDB {{% prod 3. In your terminal, create a directory for your Node.js project and change to it. ```sh - mkdir influx-node-app && cd $_ + mkdir influx-node-app && cd influx-node-app ``` 4. Enter the following command to generate an npm package for your project. - The `npm` package manager is included with Node.js. + + - `npm`: the package manager included with Node.js + - `-y`: uses defaults for the package and bypasses prompts ```sh npm init -y @@ -55,15 +57,21 @@ Follow these steps to initialize the TypeScript project: ```sh npm i -g typescript && npm i --save-dev @types/node ``` -2. Create a TypeScript configuration with default values. + +2. Enter the following command to create a TypeScript configuration + (`tsconfig.json`) with default values: ```sh tsc --init ``` -3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. +3. Run the TypeScript compiler. + To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. + + + ```sh - tsc -w -p + tsc --watch ``` ## Install dependencies @@ -84,7 +92,7 @@ It only works with InfluxDB v2 management APIs. The client examples include an [`env`](https://github.com/influxdata/influxdb-client-js/blob/master/examples/env.js) module for accessing your InfluxDB properties from environment variables or from `env.js`. The examples use these properties to interact with the InfluxDB API. -Set environment variables or update `env.js` with your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/), [organization](/influxdb/cloud-serverless/organizations/), [token](/influxdb/cloud-serverless/security/tokens/), and [url](/influxdb/cloud-serverless/reference/urls/). +Set environment variables or update `env.js` with your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/), [organization](/influxdb/cloud-serverless/organizations/), [token](/influxdb/cloud-serverless/security/tokens/), and [URL](/influxdb/cloud-serverless/reference/urls/). ```sh export INFLUX_URL=https://{{< influxdb/host >}} diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md b/content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md index d8b8b3490..936fa6af0 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md @@ -20,7 +20,7 @@ to write and query data stored in an {{% product-name %}} bucket. ## Installation ```sh -go get github.com/InfluxCommunity/influxdb3-go +go get github.com/InfluxCommunity/influxdb3-go/v2 ``` ## Importing the package @@ -31,7 +31,7 @@ Import the package: ```go import ( - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) ``` @@ -75,7 +75,7 @@ Initializes and returns a `influxdb3.Client` instance with the following: package main import ( - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -176,4 +176,4 @@ query := `SELECT * AND time <= 1641124000s + 8h` queryOptions := influxdb3.QueryOptions{QueryType: influxdb3.InfluxQL} iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query) -``` \ No newline at end of file +``` diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md b/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md index 492e8d1d9..28695d39e 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md @@ -9,12 +9,45 @@ menu: identifier: influxdb3-python influxdb/cloud-serverless/tags: [Flight API, python, gRPC, SQL, client libraries] -metadata: [influxdb3-python v0.5.0] +metadata: [influxdb3-python v0.10.0] weight: 201 aliases: - /influxdb/cloud-serverless/reference/client-libraries/v3/pyinflux3/ related: - /influxdb/cloud-serverless/query-data/execute-queries/troubleshoot/ +list_code_example: | + + + + + ```python + # Example: Write and query data + + # Write sensor data in batches from a CSV file to a database + client.write_file(file='./data/home-sensor-data.csv', + timestamp_column='time', + tag_columns=["room"]) + + # Execute a query and retrieve data from the last 90 days + table = client.query( + '''SELECT * + FROM home + WHERE time >= now() - INTERVAL '90 days' + ORDER BY time''') + + # This script assumes the client object is correctly configured + # with your bucket name, token, and host URL. + # After the script runs, the table variable contains the data + # formatted as a PyArrow table. + ``` --- The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python/) @@ -939,7 +972,7 @@ fh.close() client = InfluxDBClient3(host=f"{{< influxdb/host >}}", database=f"BUCKET_NAME", token=f"API_TOKEN", - fco=flight_client_options(tls_root_certs=cert)) + flight_client_options=flight_client_options(tls_root_certs=cert)) ``` {{% /code-placeholders %}} diff --git a/content/influxdb/cloud-serverless/reference/glossary.md b/content/influxdb/cloud-serverless/reference/glossary.md index c8c078857..2cd49fc2e 100644 --- a/content/influxdb/cloud-serverless/reference/glossary.md +++ b/content/influxdb/cloud-serverless/reference/glossary.md @@ -340,6 +340,7 @@ Related entries: [field](#field), [field key](#field-key), [field set](#field-set), +[tag set](#tag-set), [tag value](#tag-value), [timestamp](#timestamp) @@ -366,7 +367,7 @@ Related entries: Flush jitter prevents every Telegraf output plugin from sending writes simultaneously, which can overwhelm some data sinks. -Each flush interval, every Telegraf output plugin will sleep for a random time +Each flush interval, every Telegraf output plugin sleeps for a random time between zero and the flush jitter before emitting metrics. Flush jitter smooths out write spikes when running a large number of Telegraf instances. @@ -379,7 +380,7 @@ Related entries: A function is an operation that performs a specific task. Functions take input, operate on that input, and then return output. For a complete list of available SQL functions, see -[SQL functions](/inflxudb/cloud-serverless/reference/sql/functions/). +[SQL functions](/influxdb/cloud-serverless/reference/sql/functions/). @@ -434,8 +435,7 @@ and other required processes. ### InfluxDB -An open source time series database (TSDB) developed by InfluxData. -Written in Go and optimized for fast, high-availability storage and retrieval of +An open source time series database (TSDB) developed by InfluxData, optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet of Things sensor data, and real-time analytics. @@ -447,8 +447,8 @@ The SQL-like query language used to query data in InfluxDB. Telegraf input plugins actively gather metrics and deliver them to the core agent, where aggregator, processor, and output plugins can operate on the metrics. -In order to activate an input plugin, it needs to be enabled and configured in -Telegraf's configuration file. +To activate an input plugin, enable and configure it in the +Telegraf configuration file. Related entries: [aggregator plugin](#aggregator-plugin), @@ -471,8 +471,9 @@ Related entries: ### IOx -The IOx (InfluxDB v3) storage engine is a real-time, columnar database optimized for time series -data built in Rust on top of [Apache Arrow](https://arrow.apache.org/) and +The IOx storage engine (InfluxDB v3 storage engine) is a real-time, columnar +database optimized for time series data built in Rust on top of +[Apache Arrow](https://arrow.apache.org/) and [DataFusion](https://arrow.apache.org/datafusion/user-guide/introduction.html). IOx replaces the [TSM (Time Structured Merge tree)](#tsm-time-structured-merge-tree) storage engine. @@ -848,8 +849,8 @@ Related entries: ### series -A collection of data in the InfluxDB data structure that share a common -_measurement_, _tag set_, and _field key_. +In the InfluxDB 3 data structure, a collection of data that share a common +_measurement_ and _tag set_. Related entries: [field set](#field-set), @@ -860,10 +861,11 @@ Related entries: The number of unique measurement, tag set, and field key combinations in an {{% product-name %}} bucket. -For example, assume that an InfluxDB bucket has one measurement. +For example, assume that an InfluxDB database has one measurement. The single measurement has two tag keys: `email` and `status`. -If there are three different `email`s, and each email address is associated with two -different `status`es, the series cardinality for the measurement is 6 +If there are three different `email` tag values, +and each email address is associated with two +different `status` tag values, then the series cardinality for the measurement is 6 (3 × 2 = 6): | email | status | @@ -878,7 +880,7 @@ different `status`es, the series cardinality for the measurement is 6 In some cases, performing this multiplication may overestimate series cardinality because of the presence of dependent tags. Dependent tags are scoped by another tag and do not increase series cardinality. -If we add the tag `firstname` to the example above, the series cardinality +If we add the tag `firstname` to the preceding example, the series cardinality would not be 18 (3 × 2 × 3 = 18). The series cardinality would remain unchanged at 6, as `firstname` is already scoped by the `email` tag: @@ -1136,18 +1138,17 @@ A statement that sets or updates the value stored in a variable. ## W -### WAL (Write Ahead Log) - enterprise +### WAL (Write-Ahead Log) The temporary cache for recently written points. To reduce the frequency that permanent storage files are accessed, InfluxDB caches new points in the WAL until their total size or age triggers a flush to -more permanent storage. This allows for efficient batching of the writes into the TSM. +more permanent storage. This allows for efficient batching of the writes into +the storage engine. -Points in the WAL can be queried and persist through a system reboot. -On process start, all points in the WAL must be flushed before the system accepts new writes. - -Related entries: -[tsm](#tsm-time-structured-merge-tree) +Points in the WAL are queryable and persist through a system reboot. +On process start, all points in the WAL must be flushed before the system +accepts new writes. ### windowing diff --git a/content/influxdb/cloud-serverless/reference/influxql/_index.md b/content/influxdb/cloud-serverless/reference/influxql/_index.md index 75ecdad2a..ec46ee1e5 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/_index.md +++ b/content/influxdb/cloud-serverless/reference/influxql/_index.md @@ -1,786 +1,13 @@ --- title: InfluxQL reference documentation -list_title: InfluxQL -description: InfluxQL is an SQL-like query language for interacting with data in InfluxDB. +description: > + InfluxQL is an SQL-like query language for interacting with data in InfluxDB. menu: influxdb_cloud_serverless: parent: Reference name: InfluxQL reference identifier: influxql-reference weight: 102 + +source: /shared/influxql-v3-reference/_index.md --- - -InfluxQL (Influx Query Language) is an SQL-like query language used to interact -with InfluxDB and work with times series data. - -{{% warn %}} -#### InfluxQL feature support - -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features are still being implemented. -For information about the current implementation status of InfluxQL features, -see [InfluxQL feature support](/influxdb/cloud-serverless/reference/influxql/feature-support/). -{{% /warn %}} - -- [Notation](#notation) -- [Query representation](#query-representation) - - [Characters](#characters) - - [Letters and digits](#letters-and-digits) - - [Identifiers](#identifiers) - - [Keywords](#keywords) - - [Literals](#literals) -- [Queries](#queries) -- [Statements](#statements) -- [Clauses](#clauses) -- [Expressions](#expressions) -- [Comments](#comments) -- [Other](#other) -- [Result set](#result-set) - - - -## Notation - -The syntax is specified using Extended Backus-Naur Form ("EBNF"). -EBNF is the same notation used in the [Go programming language specification](https://golang.org/ref/spec). - -```go -Production = production_name "=" [ Expression ] "." . -Expression = Alternative { "|" Alternative } . -Alternative = Term { Term } . -Term = production_name | token [ "…" token ] | Group | Option | Repetition . -Group = "(" Expression ")" . -Option = "[" Expression "]" . -Repetition = "{" Expression "}" . -``` - -Notation operators in order of increasing precedence: - -``` -| alternation -() grouping -[] option (0 or 1 times) -{} repetition (0 to n times) -``` - -## Query representation - -### Characters - -InfluxQL is Unicode text encoded in [UTF-8](http://en.wikipedia.org/wiki/UTF-8). - -``` -newline = /* the Unicode code point U+000A */ . -unicode_char = /* an arbitrary Unicode code point except newline */ . -``` - -### Letters and digits - -Letters are the set of ASCII letters and the underscore (`_`, U+005F). - -Only decimal digits are supported. - -``` -letter = ascii_letter | "_" . -ascii_letter = "A" … "Z" | "a" … "z" . -digit = "0" … "9" . -``` - -### Identifiers - -Identifiers are tokens that refer to -[database](/influxdb/cloud-serverless/reference/glossary/#database) names, -[retention policy](/influxdb/cloud-serverless/reference/glossary/#retention-policy-rp) names, -[measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) names, -[tag keys](/influxdb/cloud-serverless/reference/glossary/#tag-key), and -[field keys](/influxdb/cloud-serverless/reference/glossary/#field-key). - -The rules are as follows: - -- Double-quoted identifiers can contain any Unicode character except for a new line. -- Double-quoted identifiers can also contain escaped `"` characters (that is, `\"`) -- Double-quoted identifiers can include InfluxQL [keywords](#keywords). -- Unquoted identifiers must start with an upper or lowercase ASCII character or "_". -- Unquoted identifiers may contain only ASCII letters, decimal digits, and "_". - -``` -identifier = unquoted_identifier | quoted_identifier . -unquoted_identifier = ( letter ) { letter | digit } . -quoted_identifier = `"` unicode_char { unicode_char } `"` . -``` - -#### Examples - -``` -cpu -_cpu_stats -"1h" -"anything really" -"1_Crazy-1337.identifier>NAME👍" -``` - -### Keywords - -``` -ALL ALTER ANY AS ASC BEGIN -BY CREATE CONTINUOUS DATABASE DATABASES DEFAULT -DELETE DESC DESTINATIONS DIAGNOSTICS DISTINCT DROP -DURATION END EVERY EXPLAIN FIELD FOR -FROM GRANT GRANTS GROUP GROUPS IN -INF INSERT INTO KEY KEYS KILL -LIMIT SHOW MEASUREMENT MEASUREMENTS NAME OFFSET -ON ORDER PASSWORD POLICY POLICIES PRIVILEGES -QUERIES QUERY READ REPLICATION RESAMPLE RETENTION -REVOKE SELECT SERIES SET SHARD SHARDS -SLIMIT SOFFSET STATS SUBSCRIPTION SUBSCRIPTIONS TAG -TO USER USERS VALUES WHERE WITH -WRITE -``` - -If you use an InfluxQL keyword as an -[identifier](/influxdb/cloud-serverless/reference/glossary/#identifier), -double-quote the identifier in every query. - -The `time` keyword is a special case. -`time` can be a -database name, -[measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) name, -[retention policy](/influxdb/cloud-serverless/reference/glossary/#retention-policy-rp) name, and -[user](/influxdb/cloud-serverless/reference/glossary/#user) name. - -In those cases, you don't need to double-quote `time` in queries. - -`time` can't be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key) or -[tag key](/influxdb/cloud-serverless/reference/glossary/#tag-key); -InfluxDB rejects writes with `time` as a field key or tag key and returns an error. - - -### Literals - -#### Integers - -InfluxQL supports decimal integer literals. -Hexadecimal and octal literals aren't currently supported. - -``` -int_lit = ( "1" … "9" ) { digit } . -``` - -#### Floats - -InfluxQL supports floating-point literals. -Exponents aren't currently supported. - -``` -float_lit = int_lit "." int_lit . -``` - -#### Strings - -String literals must be surrounded by single quotes. -Strings may contain `'` characters as long as they are escaped (that is, , `\'`) - -``` -string_lit = `'` { unicode_char } `'` . -``` - -#### Durations - -Duration literals specify a length of time. -An integer literal followed immediately (with no spaces) by one of the duration units listed below is interpreted as a duration literal. -Durations can be specified with mixed units. - -##### Duration units - -| Units | Meaning | -| ------ | --------------------------------------- | -| ns | nanoseconds (1 billionth of a second) | -| u or µ | microseconds (1 millionth of a second) | -| ms | milliseconds (1 thousandth of a second) | -| s | second | -| m | minute | -| h | hour | -| d | day | -| w | week | - -``` -duration_lit = int_lit duration_unit . -duration_unit = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" . -``` - -#### Dates & Times - -Unlike other notations used in InfluxQL, the date and time literal format isn't specified by EBNF. -InfluxQL date and time is specified using Go's time parsing format and -[reference date](https://pkg.go.dev/time#pkg-constants) written in the format required by InfluxQL. -The reference date time is: - -InfluxQL reference date time: January 2nd, 2006 at 3:04:05 PM - -``` -time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02" . -``` - -#### Booleans - -``` -bool_lit = TRUE | FALSE . -``` - -#### Regular Expressions - -``` -regex_lit = "/" { unicode_char } "/" . -``` - -**Comparators:** -`=~` matches against -`!~` doesn't match against - -{{% note %}} -InfluxQL supports using regular expressions when specifying: - -- [field keys](/influxdb/cloud-serverless/reference/glossary/#field-key) and [tag keys](/influxdb/cloud-serverless/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/cloud-serverless/reference/influxql/select/) -- [measurements](/influxdb/cloud-serverless/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/cloud-serverless/reference/influxql/select/#from-clause) -- [tag values](/influxdb/cloud-serverless/reference/glossary/#tag-value) and - string [field values](/influxdb/cloud-serverless/reference/glossary/#field-value) - in the [`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/) -- [tag keys](/influxdb/cloud-serverless/reference/glossary/#tag-key) in the - [`GROUP BY` clause](/influxdb/cloud-serverless/reference/influxql/group-by/) - -Currently, InfluxQL doesn't support using regular expressions to match non-string -field values in the `WHERE` clause, [databases](/influxdb/cloud-serverless/reference/glossary/#database), -and [retention polices](/influxdb/cloud-serverless/reference/glossary/#retention-policy-rp). -{{% /note %}} - -## Queries - -A query is composed of one or more statements separated by a semicolon (`;`). - -``` -query = statement { ";" statement } . - -statement = explain_stmt | - explain_analyze_stmt | - select_stmt | - show_field_keys_stmt | - show_measurements_stmt | - show_retention_policies_stmt | - show_tag_keys_stmt | - show_tag_values_with_key = stmt . -``` - - - -## Statements - -### EXPLAIN - -Parses and plans the query, and then prints a summary of estimated costs. - -Many SQL engines use the `EXPLAIN` statement to show join order, join algorithms, and predicate and expression pushdown. -Since InfluxQL doesn't support joins, the cost of an InfluxQL query is typically a function of the total series accessed, the number of iterator accesses to a TSM file, and the number of TSM blocks that need to be scanned. - -A query plan generated by `EXPLAIN` contains the following elements: - -- expression -- auxiliary fields -- number of shards -- number of series -- cached values -- number of files -- number of blocks -- size of blocks - -``` -explain_stmt = "EXPLAIN" select_stmt . -``` - -#### Example - -```sql -> explain select sum(pointReq) from "_internal"."monitor"."write" group by hostname; -> QUERY PLAN ------- -EXPRESSION: sum(pointReq::integer) -NUMBER OF SHARDS: 2 -NUMBER OF SERIES: 2 -CACHED VALUES: 110 -NUMBER OF FILES: 1 -NUMBER OF BLOCKS: 1 -SIZE OF BLOCKS: 931 -``` - -### EXPLAIN ANALYZE - -Executes the specified `SELECT` statement and returns data about the query performance and storage during runtime, visualized as a tree. Use this statement to analyze query performance and storage, including [execution time](#execution-time) and [planning time](#planning-time), and the [iterator type](#iterator-type) and [cursor type](#cursor-type). - -For example, if you execute the following statement: - -```sql -> explain analyze select mean(usage_steal) from cpu where time >= '2018-02-22T00:00:00Z' and time < '2018-02-22T12:00:00Z' -``` - -The output is similar to the following: - -```sql -EXPLAIN ANALYZE ---------------- -. -└── select - ├── execution_time: 2.25823ms - ├── planning_time: 18.381616ms - ├── total_time: 20.639846ms - └── field_iterators - ├── labels - │ └── statement: SELECT mean(usage_steal::float) FROM telegraf."default".cpu - └── expression - ├── labels - │ └── expr: mean(usage_steal::float) - └── create_iterator - ├── labels - │ ├── measurement: cpu - │ └── shard_id: 608 - ├── cursors_ref: 779 - ├── cursors_aux: 0 - ├── cursors_cond: 0 - ├── float_blocks_decoded: 431 - ├── float_blocks_size_bytes: 1003552 - ├── integer_blocks_decoded: 0 - ├── integer_blocks_size_bytes: 0 - ├── unsigned_blocks_decoded: 0 - ├── unsigned_blocks_size_bytes: 0 - ├── string_blocks_decoded: 0 - ├── string_blocks_size_bytes: 0 - ├── boolean_blocks_decoded: 0 - ├── boolean_blocks_size_bytes: 0 - └── planning_time: 14.805277ms``` -``` - -{{% note %}} -`EXPLAIN ANALYZE` ignores query output, so the cost of serialization to JSON or -CSV isn't accounted for. -{{% /note %}} - -##### execution_time - -Shows the amount of time the query took to execute, including reading the time series data, performing operations as data flows through iterators, and draining processed data from iterators. Execution time doesn't include the time taken to serialize the output into JSON or other formats. - -##### planning_time - -Shows the amount of time the query took to plan. -Planning a query in InfluxDB requires a number of steps. Depending on the complexity of the query, planning can require more work and consume more CPU and memory resources than executing the query. For example, the number of series keys required to execute a query affects how quickly the query is planned and how much memory the planning requires. - -First, InfluxDB determines the effective time range of the query and selects the shards to access. -Next, for each shard and each measurement, InfluxDB performs the following steps: - -1. Select matching series keys from the index, filtered by tag predicates in the `WHERE` clause. -2. Group filtered series keys into tag sets based on the `GROUP BY` dimensions. -3. Enumerate each tag set and create a cursor and iterator for each series key. -4. Merge iterators and return the merged result to the query executor. - -##### iterator type - -`EXPLAIN ANALYZE` supports the following iterator types: - -- `create_iterator` node represents work done by the local influxd instance──a complex composition of nested iterators combined and merged to produce the final query output. -- (InfluxDB Enterprise only) `remote_iterator` node represents work done on remote machines. - -For more information about iterators, see [Understanding iterators](#understanding-iterators). - -##### cursor type - -`EXPLAIN ANALYZE` distinguishes 3 cursor types. While the cursor types have the same data structures and equal CPU and I/O costs, each cursor type is constructed for a different reason and separated in the final output. Consider the following cursor types when tuning a statement: - -- cursor_ref: Reference cursor created for `SELECT` projections that include a function, such as `last()` or `mean()`. -- cursor_aux: Auxiliary cursor created for simple expression projections (not selectors or an aggregation). For example, `SELECT foo FROM m` or `SELECT foo+bar FROM m`, where `foo` and `bar` are fields. -- cursor_cond: Condition cursor created for fields referenced in a `WHERE` clause. - -For more information about cursors, see [Understanding cursors](#understanding-cursors). - -##### block types - -`EXPLAIN ANALYZE` separates storage block types, and reports the total number of -blocks decoded and their size (in bytes) on disk. The following block types are supported: - -| Type | Description | -| :--------- | :------------------------------------ | -| `float` | 64-bit IEEE-754 floating-point number | -| `integer` | 64-bit signed integer | -| `unsigned` | 64-bit unsigned integer | -| `boolean` | 1-bit, LSB encoded | -| `string` | UTF-8 string | - -### SELECT - -``` -select_stmt = "SELECT" fields from_clause [ where_clause ] - [ group_by_clause ] [ order_by_clause ] [ limit_clause ] - [ offset_clause ] [ slimit_clause ] [ soffset_clause ] [ timezone_clause ] . -``` - -#### Example - -Select from measurements grouped by the day with a timezone - -```sql -SELECT mean("value") FROM "cpu" GROUP BY region, time(1d) fill(0) tz('America/Chicago') -``` - - - - - - - -### SHOW FIELD KEYS - -``` -show_field_keys_stmt = "SHOW FIELD KEYS" [on_clause] [ from_clause ] . -``` - -#### Examples - -```sql --- show field keys and field value data types from all measurements -SHOW FIELD KEYS - --- show field keys and field value data types from specified measurement -SHOW FIELD KEYS FROM "cpu" -``` - -### SHOW MEASUREMENTS - -``` -show_measurements_stmt = "SHOW MEASUREMENTS" [on_clause] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all measurements -SHOW MEASUREMENTS - --- show measurements where region tag = 'uswest' AND host tag = 'serverA' -SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' - --- show measurements that start with 'h2o' -SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ -``` - - - - - - - -### SHOW TAG KEYS - -``` -show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ] - [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all tag keys -SHOW TAG KEYS - --- show all tag keys from the cpu measurement -SHOW TAG KEYS FROM "cpu" - --- show all tag keys from the cpu measurement where the region key = 'uswest' -SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' - --- show all tag keys where the host key = 'serverA' -SHOW TAG KEYS WHERE "host" = 'serverA' -``` - -### SHOW TAG VALUES - -``` -show_tag_values_stmt = "SHOW TAG VALUES" [on_clause] [ from_clause ] with_tag_clause [ where_clause ] - [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all tag values across all measurements for the region tag -SHOW TAG VALUES WITH KEY = "region" - --- show tag values from the cpu measurement for the region tag -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" - --- show tag values across all measurements for all tag keys that do not include the letter c -SHOW TAG VALUES WITH KEY !~ /.*c.*/ - --- show tag values from the cpu measurement for region & host tag keys where service = 'redis' -SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' -``` - - - -## Clauses - -``` -from_clause = "FROM" measurements . - -group_by_clause = "GROUP BY" dimensions fill(fill_option). - -limit_clause = "LIMIT" int_lit . - -offset_clause = "OFFSET" int_lit . - -slimit_clause = "SLIMIT" int_lit . - -soffset_clause = "SOFFSET" int_lit . - -timezone_clause = tz(string_lit) . - -on_clause = "ON" db_name . - -order_by_clause = "ORDER BY" sort_fields . - -where_clause = "WHERE" expr . - -with_measurement_clause = "WITH MEASUREMENT" ( "=" measurement | "=~" regex_lit ) . - -with_tag_clause = "WITH KEY" ( "=" tag_key | "!=" tag_key | "=~" regex_lit | "IN (" tag_keys ")" ) . -``` - -## Expressions - -``` -binary_op = "+" | "-" | "*" | "/" | "%" | "&" | "|" | "^" | "AND" | - "OR" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" . - -expr = unary_expr { binary_op unary_expr } . - -unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit | - float_lit | bool_lit | duration_lit | regex_lit . -``` - -## Default time range - -The default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to _now_. - -## Comments - -Use comments with InfluxQL statements to describe your queries. - -- A single line comment begins with two hyphens (`--`) and ends where InfluxDB detects a line break. - This comment type cannot span several lines. -- A multi-line comment begins with `/*` and ends with `*/`. This comment type can span several lines. - Multi-line comments do not support nested multi-line comments. - -## Other - -``` -alias = "AS" identifier . - -back_ref = ( policy_name ".:MEASUREMENT" ) | - ( db_name "." [ policy_name ] ".:MEASUREMENT" ) . - -db_name = identifier . - -dimension = expr . - -dimensions = dimension { "," dimension } . - -field_key = identifier . - -field = expr [ alias ] . - -fields = field { "," field } . - -fill_option = "null" | "none" | "previous" | int_lit | float_lit | "linear" . - -host = string_lit . - -measurement = measurement_name | - ( policy_name "." measurement_name ) | - ( db_name "." [ policy_name ] "." measurement_name ) . - -measurements = measurement { "," measurement } . - -measurement_name = identifier | regex_lit . - -policy_name = identifier . - -retention_policy = identifier . - -retention_policy_name = "NAME" identifier . - -series_id = int_lit . - -sort_field = field_key [ ASC | DESC ] . - -sort_fields = sort_field { "," sort_field } . - -tag_key = identifier . - -tag_keys = tag_key { "," tag_key } . - -var_ref = measurement . -``` diff --git a/content/influxdb/cloud-serverless/reference/influxql/feature-support.md b/content/influxdb/cloud-serverless/reference/influxql/feature-support.md index 16257c1ac..89c6e319d 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/feature-support.md +++ b/content/influxdb/cloud-serverless/reference/influxql/feature-support.md @@ -9,173 +9,6 @@ menu: influxdb_cloud_serverless: parent: influxql-reference weight: 220 + +source: /shared/influxql-v3-reference/feature-support.md --- - -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features are still being implemented. -This page provides information about the current implementation status of -InfluxQL features. - -- [In-progress features](#in-progress-features) - - [Time zones](#time-zones) - - [SLIMIT clause](#slimit-clause) - - [SOFFSET clause](#soffset-clause) - - [Metaqueries](#metaqueries) -- [Function support](#function-support) - - [Aggregate functions](#aggregate-functions) - - [Selector functions](#selector-functions) - - [Transformations](#transformations) - - [Technical and predictive analysis](#technical-and-predictive-analysis) - -## In-progress features - -### Time zones - -InfluxQL in {{< product-name >}} does not currently support the time zone clause, -which applies a time zone offset to UTC timestamps in query results. - - - -### SLIMIT clause - -InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause, -which limits the number of [series](/influxdb/cloud-serverless/reference/glossary/#series) -returned in query results. - - - -### SOFFSET clause - -InfluxQL in {{< product-name >}} does not currently support the `SOFFSET` clause, -which specifies the number of [series](/influxdb/cloud-serverless/reference/glossary/#series) -to skip before returning results. - - - -### Metaqueries - -InfluxQL metaqueries return information about the schema of time series data -stored in InfluxDB. -The following table provides information about what metaqueries are available in -{{< product-name >}}: - -| Metaquery | Supported | -| :------------------------------------------------------------ | :----------------------: | -| SHOW DATABASES | | -| **SHOW RETENTION POLICIES** | **{{< icon "check" >}}** | -| **SHOW MEASUREMENTS** | **{{< icon "check" >}}** | -| SHOW SERIES | | -| SHOW SERIES CARDINALITY | | -| **SHOW TAG KEYS** | **{{< icon "check" >}}** | -| SHOW TAG KEY CARDINALITY | | -| **SHOW TAG VALUES** | **{{< icon "check" >}}** | -| SHOW TAG VALUES CARDINALITY | | -| **SHOW FIELD KEYS** | **{{< icon "check" >}}** | -| SHOW FIELD KEYS CARDINALITY | | - -{{% note %}} -#### Cardinality metaqueries - -With the InfluxDB 3.0 storage engine, series cardinality is no longer a limiting -factor for database performance. -Cardinality-related metaqueries will likely not be supported with the InfluxDB 3.0 -storage engine. -{{% /note %}} - -## Function support - -### Aggregate functions - -| Function | Supported | -| :----------------------------------------------------------------------------------------- | :----------------------: | -| [COUNT()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#count) | **{{< icon "check" >}}** | -| [DISTINCT()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#distinct) | **{{< icon "check" >}}** | -| INTEGRAL() | | -| [MEAN()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#mean) | **{{< icon "check" >}}** | -| [MEDIAN()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#median) | **{{< icon "check" >}}** | -| [MODE()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#mode) | **{{< icon "check" >}}** | -| [SPREAD()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#spread) | **{{< icon "check" >}}** | -| [STDDEV()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#stddev) | **{{< icon "check" >}}** | -| [SUM()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#sum) | **{{< icon "check" >}}** | - - - -### Selector functions - -| Function | Supported | -| :-------------------------------------------------------------------------------------------- | :----------------------: | -| [BOTTOM()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#bottom) | **{{< icon "check" >}}** | -| [FIRST()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#first) | **{{< icon "check" >}}** | -| [LAST()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#last) | **{{< icon "check" >}}** | -| [MAX()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#max) | **{{< icon "check" >}}** | -| [MIN()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#min) | **{{< icon "check" >}}** | -| [PERCENTILE()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#percentile) | **{{< icon "check" >}}** | -| SAMPLE() | | -| [TOP()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#top) | **{{< icon "check" >}}** | - - - -### Transformations - -| Function | Supported | -| :---------------------------------------------------------------------------------------------------------------------------- | :----------------------: | -| [ABS()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#abs) | **{{< icon "check" >}}** | -| [ACOS()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#acos) | **{{< icon "check" >}}** | -| [ASIN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#asin) | **{{< icon "check" >}}** | -| [ATAN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#atan) | **{{< icon "check" >}}** | -| [ATAN2()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#atan2) | **{{< icon "check" >}}** | -| [CEIL()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#ceil) | **{{< icon "check" >}}** | -| [COS()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#cos) | **{{< icon "check" >}}** | -| [CUMULATIVE_SUM()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#cumulative_sum) | **{{< icon "check" >}}** | -| [DERIVATIVE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#derivative) | **{{< icon "check" >}}** | -| [DIFFERENCE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#difference) | **{{< icon "check" >}}** | -| [ELAPSED()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#elapsed) | **{{< icon "check" >}}** | -| [EXP()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#exp) | **{{< icon "check" >}}** | -| [FLOOR()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#floor) | **{{< icon "check" >}}** | -| [LN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#ln) | **{{< icon "check" >}}** | -| [LOG()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#log) | **{{< icon "check" >}}** | -| [LOG2()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#log2) | **{{< icon "check" >}}** | -| [LOG10()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#log10) | **{{< icon "check" >}}** | -| [MOVING_AVERAGE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#moving_average) | **{{< icon "check" >}}** | -| [NON_NEGATIVE_DERIVATIVE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#non_negative_derivative) | **{{< icon "check" >}}** | -| [NON_NEGATIVE_DIFFERENCE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#non_negative_difference) | **{{< icon "check" >}}** | -| [POW()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#pow) | **{{< icon "check" >}}** | -| [ROUND()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#round) | **{{< icon "check" >}}** | -| [SIN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#sin) | **{{< icon "check" >}}** | -| [SQRT()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#sqrt) | **{{< icon "check" >}}** | -| [TAN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#tan) | **{{< icon "check" >}}** | - -### Technical and predictive analysis - -| Function | Supported | -| :-------------------------------------------------------------------- | :-------: | -| CHANDE_MOMENTUM_OSCILLATOR() | | -| DOUBLE_EXPONENTIAL_MOVING_AVERAGE() | | -| EXPONENTIAL_MOVING_AVERAGE() | | -| HOLT_WINTERS() | | -| HOLT_WINTERS_WITH_FIT() | | -| KAUFMANS_EFFICIENCY_RATIO() | | -| KAUFMANS_ADAPTIVE_MOVING_AVERAGE() | | -| RELATIVE_STRENGTH_INDEX() | | -| TRIPLE_EXPONENTIAL_MOVING_AVERAGE() | | -| TRIPLE_EXPONENTIAL_DERIVATIVE() | | - - - -### Date and time functions - -| Function | Supported | -| :-------------------------------------------------------------------------------- | :----------------------: | -| [now()](/influxdb/cloud-serverless/reference/influxql/functions/date-time/#now) | **{{< icon "check" >}}** | -| [time()](/influxdb/cloud-serverless/reference/influxql/functions/date-time/#time) | **{{< icon "check" >}}** | -| tz() | | - - - -### Miscellaneous functions - -| Function | Supported | -| :--------------------------------------------------------------------------- | :----------------------: | -| [fill()](/influxdb/cloud-serverless/reference/influxql/functions/misc/#fill) | **{{< icon "check" >}}** | diff --git a/content/influxdb/cloud-serverless/reference/influxql/functions/_index.md b/content/influxdb/cloud-serverless/reference/influxql/functions/_index.md index 0d428fdc6..b01927680 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/functions/_index.md +++ b/content/influxdb/cloud-serverless/reference/influxql/functions/_index.md @@ -8,79 +8,6 @@ menu: parent: influxql-reference identifier: influxql-functions weight: 208 + +source: /shared/influxql-v3-reference/functions/_index.md --- - -Use InfluxQL functions to aggregate, select, transform, analyze, and predict data. - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/cloud-serverless/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## InfluxQL functions (by type) - -- [Aggregates](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/) - - [COUNT()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#count) - - [DISTINCT()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#distinct) - - [MEAN()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#mean) - - [MEDIAN()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#median) - - [STDDEV()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#stddev) - - [SUM()](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#sum) - - - -- [Selectors](/influxdb/cloud-serverless/reference/influxql/functions/selectors/) - - [BOTTOM()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#bottom) - - [FIRST()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#first) - - [LAST()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#last) - - [MAX()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#max) - - [MIN()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#min) - - [PERCENTILE()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#percentile) - - [TOP()](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#top) - -- [Transformations](/influxdb/cloud-serverless/reference/influxql/functions/transformations/) - - [ABS()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#abs) - - [ACOS()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#acos) - - [ASIN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#asin) - - [ATAN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#atan) - - [ATAN2()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#atan2) - - [CEIL()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#ceil) - - [COS()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#cos) - - [CUMULATIVE_SUM()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#cumulative_sum) - - [DERIVATIVE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#derivative) - - [DIFFERENCE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#difference) - - [EXP()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#exp) - - [FLOOR()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#floor) - - [HISTOGRAM()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#histogram) - - [LN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#ln) - - [LOG()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#log) - - [LOG2()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#log2) - - [LOG10()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#log10) - - [MOVING_AVERAGE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#moving_average) - - [NON_NEGATIVE_DERIVATIVE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#non_negative_derivative) - - [NON_NEGATIVE_DIFFERENCE()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#non_negative_difference) - - [POW()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#pow) - - [ROUND()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#round) - - [SIN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#sin) - - [SQRT()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#sqrt) - - [TAN()](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#tan) - -- [Date and time](/influxdb/cloud-serverless/reference/influxql/functions/date-time/) - - [now()](/influxdb/cloud-serverless/reference/influxql/functions/date-time/#now) - - [time()](/influxdb/cloud-serverless/reference/influxql/functions/date-time/#time) -- [Miscellaneous](/influxdb/cloud-serverless/reference/influxql/functions/misc/) - - [fill()](/influxdb/cloud-serverless/reference/influxql/functions/misc/#fill) - - - - - - - - - - diff --git a/content/influxdb/cloud-serverless/reference/influxql/functions/aggregates.md b/content/influxdb/cloud-serverless/reference/influxql/functions/aggregates.md index 740e0f30d..0b775d39b 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/functions/aggregates.md +++ b/content/influxdb/cloud-serverless/reference/influxql/functions/aggregates.md @@ -10,922 +10,6 @@ menu: weight: 205 related: - /influxdb/cloud-serverless/query-data/influxql/aggregate-select/ + +source: /shared/influxql-v3-reference/functions/aggregates.md --- - -Use aggregate functions to assess, aggregate, and return values in your data. -Aggregate functions return one row containing the aggregate values from each InfluxQL group. - -_Examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -- [COUNT()](#count) -- [DISTINCT()](#distinct) -- [MEAN()](#mean) -- [MEDIAN()](#median) -- [MODE()](#mode) -- [SPREAD()](#spread) -- [STDDEV()](#stddev) -- [SUM()](#sum) - - - - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/cloud-serverless/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## COUNT() - -Returns the number of non-null [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -COUNT(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all [field data types](/influxdb/cloud-serverless/reference/glossary/#field-value). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Count the number of non-null values in a field" %}} - -```sql -SELECT COUNT(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 1970-01-01T00:00:00Z | 26 | - -{{% /expand %}} - -{{% expand "Count the number of non-null values in each field" %}} - -```sql -SELECT COUNT(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count_co | count_hum | count_temp | -| :------------------- | -------: | --------: | ---------: | -| 1970-01-01T00:00:00Z | 26 | 26 | 26 | - -{{% /expand %}} - -{{% expand "Count the number of non-null values in fields where the field key matches a regular expression" %}} - -```sql -SELECT COUNT(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count_hum | count_temp | -| :------------------- | --------: | ---------: | -| 1970-01-01T00:00:00Z | 26 | 26 | - -{{% /expand %}} - -{{% expand "Count distinct values for a field" %}} - -InfluxQL supports nesting [`DISTINCT()`](#distinct) in `COUNT()`. - -```sql -SELECT COUNT(DISTINCT(co)) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 1970-01-01T00:00:00Z | 12 | - -{{% /expand %}} - -{{% expand "Count the number of non-null field values within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - COUNT(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 2022-01-01T06:00:00Z | 4 | -| 2022-01-01T12:00:00Z | 6 | -| 2022-01-01T18:00:00Z | 3 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DISTINCT() - -Returns the list of unique [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -DISTINCT(field_key) -``` - -#### Arguments - -- **field_key**: Field key to return distinct values from. - Supports all field types. - -#### Notable behaviors - -- InfluxQL supports nesting `DISTINCT()` with [`COUNT()`](#count-distinct-values-for-a-field). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "List the distinct field values" %}} - -```sql -SELECT DISTINCT(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | distinct | -| :------------------- | -------: | -| 1970-01-01T00:00:00Z | 0 | -| 1970-01-01T00:00:00Z | 1 | -| 1970-01-01T00:00:00Z | 3 | -| 1970-01-01T00:00:00Z | 4 | -| 1970-01-01T00:00:00Z | 7 | -| 1970-01-01T00:00:00Z | 5 | -| 1970-01-01T00:00:00Z | 9 | -| 1970-01-01T00:00:00Z | 18 | -| 1970-01-01T00:00:00Z | 14 | -| 1970-01-01T00:00:00Z | 22 | -| 1970-01-01T00:00:00Z | 17 | -| 1970-01-01T00:00:00Z | 26 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - - -## MEAN() - -Returns the arithmetic mean (average) of [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -MEAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the mean value of a field" %}} - -```sql -SELECT MEAN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of each field" %}} - -```sql -SELECT MEAN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ----------------: | -------: | -----------------: | -| 1970-01-01T00:00:00Z | 5.269230769230769 | 36.15 | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of fields where the field key matches a regular expression" %}} - -```sql -SELECT MEAN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean_hum | mean_temp | -| :------------------- | -------: | -----------------: | -| 1970-01-01T00:00:00Z | 36.15 | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MEAN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 22.275 | -| 2022-01-01T12:00:00Z | 22.649999999999995 | -| 2022-01-01T18:00:00Z | 23.033333333333335 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MEDIAN() - -Returns the middle value from a sorted list of [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -MEDIAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MEDIAN()` is nearly equivalent to - [`PERCENTILE(field_key, 50)`](/influxdb/cloud-serverless/reference/influxql/functions/selectors/#percentile), - except `MEDIAN()` returns the average of the two middle field values if the - field contains an even number of values. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the median value of a field" %}} - -```sql -SELECT MEDIAN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median | -| :------------------- | -----: | -| 1970-01-01T00:00:00Z | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of each field" %}} - -```sql -SELECT MEDIAN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median_co | median_hum | median_temp | -| :------------------- | --------: | ---------: | ----------: | -| 1970-01-01T00:00:00Z | 1 | 36.05 | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of fields where the field key matches a regular expression" %}} - - -```sql -SELECT MEDIAN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median_hum | median_temp | -| :------------------- | ---------: | ----------: | -| 1970-01-01T00:00:00Z | 36.05 | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MEDIAN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 22.549999999999997 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MODE() - -Returns the most frequent value in a list of -[field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -MODE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. - -#### Notable behaviors - -- `MODE()` returns the field value with the earliest - [timestamp](/influxdb/cloud-serverless/reference/glossary/#timestamp) - if there's a tie between two or more values for the maximum number of occurrences. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Calculate the mode value of a field" %}} - -```sql -SELECT MODE(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode | -| :------------------- | ---: | -| 1970-01-01T00:00:00Z | 0 | - -{{% /expand %}} - -{{% expand "Calculate the mode value of each field" %}} - -```sql -SELECT MODE(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode_co | mode_hum | mode_temp | -| :------------------- | ------: | -------: | --------: | -| 1970-01-01T00:00:00Z | 0 | 36 | 22.7 | - -{{% /expand %}} - -{{% expand "Calculate the mode of field keys that match a regular expression" %}} - -```sql -SELECT MODE(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode_hum | mode_temp | -| :------------------- | -------: | --------: | -| 1970-01-01T00:00:00Z | 36 | 22.7 | - -{{% /expand %}} - -{{% expand "Calculate the mode a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MODE(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 1 | -| 2022-01-01T18:00:00Z | 18 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SPREAD() - -Returns the difference between the minimum and maximum -[field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -SPREAD(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Calculate the spread of a field" %}} - -```sql -SELECT SPREAD(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of each field" %}} - -```sql -SELECT SPREAD(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread_co | spread_hum | spread_temp | -| :------------------- | --------: | ---------: | -----------------: | -| 1970-01-01T00:00:00Z | 26 | 1 | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of field keys that match a regular expression" %}} - -```sql -SELECT SPREAD(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread_hum | spread_temp | -| :------------------- | ---------: | -----------------: | -| 1970-01-01T00:00:00Z | 1 | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SPREAD(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread | -| :------------------- | -----: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 9 | -| 2022-01-01T18:00:00Z | 8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## STDDEV() - -Returns the standard deviation of [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -STDDEV(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the standard deviation of a field" %}} - -```sql -SELECT STDDEV(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of each field" %}} - -```sql -SELECT STDDEV(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev_co | stddev_hum | stddev_temp | -| :------------------- | ----------------: | ------------------: | -----------------: | -| 1970-01-01T00:00:00Z | 7.774613519951676 | 0.25495097567963926 | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of fields where the field key matches a regular expression" %}} - -```sql -SELECT STDDEV(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev_hum | stddev_temp | -| :------------------- | ------------------: | -----------------: | -| 1970-01-01T00:00:00Z | 0.25495097567963926 | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - STDDEV(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 3.6742346141747673 | -| 2022-01-01T18:00:00Z | 4 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SUM() - -Returns the sum of [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -SUM(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the sum of values in a field" %}} - -```sql -SELECT SUM(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | --: | -| 1970-01-01T00:00:00Z | 137 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values in each field" %}} - -```sql -SELECT SUM(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum_co | sum_hum | sum_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 137 | 939.9 | 582.3 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values for fields where the field key matches a regular expression" %}} - -```sql -SELECT SUM(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum_hum | sum_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 939.9 | 582.3 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values in a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SUM(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | --: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 21 | -| 2022-01-01T18:00:00Z | 66 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/reference/influxql/functions/date-time.md b/content/influxdb/cloud-serverless/reference/influxql/functions/date-time.md index ac9642d48..6e3ca5903 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/functions/date-time.md +++ b/content/influxdb/cloud-serverless/reference/influxql/functions/date-time.md @@ -8,138 +8,6 @@ menu: name: Date and time parent: influxql-functions weight: 206 + +source: /shared/influxql-v3-reference/functions/date-time.md --- - -Use InfluxQL date and time functions to perform time-related operations. - -- [now()](#now) -- [time()](#time) - - -## now() - -Returns the current system time (UTC). -_Supported only in the [`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/)._ - -```sql -now() -``` - -## time() - -Used in the [`GROUP BY` clause](/influxdb/cloud-serverless/reference/influxql/group-by/) -to group data into time-based intervals, also known as "windows", using the specified interval. -Timestamps in the `time` column are updated to the start boundary of the window -they're in and grouped by `time`. -Windows use preset round-number boundaries based on the specified interval that -are independent of time conditions in the -[`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/). - -This operation can be used to do the following: - -- Downsample data by aggregating multiple points in each window into a single - point per window. -- Normalize irregular time series data to occur at regular intervals. - -_Supported only in the [`GROUP BY` clause](/influxdb/cloud-serverless/reference/influxql/group-by/)._ - -```sql -time(interval[, offset]) -``` - -#### Arguments - -- **interval**: Duration literal that specifies the window interval. -- **offset**: Duration literal that shifts preset time boundaries forward or backward. - Can be positive or negative. _Default is `0s`._ - -##### Examples {#time-examples} - -{{< expand-wrapper >}} - -{{% expand "Downsample data into time-based intervals" %}} - -The following example uses the -[Bitcoin price sample dataset](/influxdb/cloud-serverless/reference/sample-data/#bitcoin-price-data). - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'GBP' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(2d) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-05-01T00:00:00Z | 23680.120447159094 | -| 2023-05-03T00:00:00Z | 24048.71484033149 | -| 2023-05-05T00:00:00Z | 24461.9194901099 | -| 2023-05-07T00:00:00Z | 23796.43801933702 | -| 2023-05-09T00:00:00Z | 23118.709889285707 | -| 2023-05-11T00:00:00Z | 22465.008364444446 | -| 2023-05-13T00:00:00Z | 22499.464763186803 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - diff --git a/content/influxdb/cloud-serverless/reference/influxql/functions/misc.md b/content/influxdb/cloud-serverless/reference/influxql/functions/misc.md index 7401cdc09..c616d9ff0 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/functions/misc.md +++ b/content/influxdb/cloud-serverless/reference/influxql/functions/misc.md @@ -10,237 +10,6 @@ menu: identifier: influxql-misc-functions parent: influxql-functions weight: 206 + +source: /shared/influxql-v3-reference/functions/misc.md --- - -Use InfluxQL miscellaneous functions to perform different operations in -InfluxQL queries. - -- [fill()](#fill) - -## fill() - -Fills _null_ field values returned from empty time windows in `GROUP BY time()` -queries with a specified fill value. - -_Supported only in the [`GROUP BY` clause](/influxdb/cloud-serverless/reference/influxql/group-by/)._ - -```sql -fill(behavior) -``` - -#### Arguments - -- **behavior**: Defines the behavior of the fill operation. - If no `FILL` clause is included, the default behavior is `fill(null)`. - - The following options are available: - - - **numeric literal**: Replaces null values with the specified numeric literal. - - **linear**: Uses linear interpolation between existing values to replace null values. - - **none**: Removes rows with null field values. - - **null**: Keeps null values and associated timestamps. - - **previous**: Replaces null values with the most recent non-null value. - -#### Examples {#fill-examples} - -The following example uses the -[Bitcoin price sample dataset](/influxdb/cloud-serverless/reference/sample-data/#bitcoin-price-data). - -{{< tabs-wrapper >}} -{{% tabs "small" %}} -[fill(numeric_literal)](#) -[fill(linear)](#) -[fill(none)](#) -[fill(null)](#) -[fill(previous)](#) -{{% /tabs %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(0) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 0 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(linear) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29285.3651 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(none) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(null) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(previous) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - - - diff --git a/content/influxdb/cloud-serverless/reference/influxql/functions/selectors.md b/content/influxdb/cloud-serverless/reference/influxql/functions/selectors.md index 71f6dc173..02df0868b 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/functions/selectors.md +++ b/content/influxdb/cloud-serverless/reference/influxql/functions/selectors.md @@ -10,1059 +10,6 @@ menu: weight: 205 related: - /influxdb/cloud-serverless/query-data/influxql/aggregate-select/ + +source: /shared/influxql-v3-reference/functions/selectors.md --- - -Use selector functions to assess, select, and return values in your data. -Selector functions return one or more rows with the selected values from each -InfluxQL group. - -_Examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -- [BOTTOM()](#bottom) -- [FIRST()](#first) -- [LAST()](#last) -- [MAX()](#max) -- [MIN()](#min) -- [PERCENTILE()](#percentile) -- [TOP()](#top) -- [Notable behaviors of selector functions](#notable-behaviors-of-selector-functions) - - - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/cloud-serverless/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## BOTTOM() - -Returns the smallest `N` [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). -`BOTTOM()` supports int64 and float64 field value [data types](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -BOTTOM(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) -``` - -{{% note %}} -**Note:** `BOTTOM()` returns the field value with the earliest timestamp if -there's a tie between two or more values for the smallest value. -{{% /note %}} - -#### Arguments - -- **field_expression**: Expression to identify the field to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key) - or constant. -- **tag_expression**: Expression to identify a tag key to segment by. - Can be a [tag key](/influxdb/cloud-serverless/reference/glossary/#tag-key) - or constant. Comma-delimit multiple tags. -- **N**: Number of results to return from each InfluxQL group or specified tag segment. - -#### Notable behaviors - -- `BOTTOM()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `BOTTOM()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the bottom three values of a field" %}} - -```sql -SELECT BOTTOM(temp, 3) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | -| :------------------- | -----: | -| 2022-01-01T08:00:00Z | 21 | -| 2022-01-01T08:00:00Z | 21.1 | -| 2022-01-01T09:00:00Z | 21.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom field value for two unique tag values" %}} - -```sql -SELECT BOTTOM(temp, room, 2) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | room | -| :------------------- | -----: | :---------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom three field values and the tag value associated with each" %}} - -```sql -SELECT BOTTOM(temp, 3), room FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | room | -| :------------------- | -----: | ----------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | -| 2022-01-01T09:00:00Z | 21.4 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom field values for unique tag values and within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} -```sql -SELECT - BOTTOM(temp, room, 2) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -GROUP BY time(2h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | bottom | room | -| :------------------- | -----: | :---------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | -| 2022-01-01T10:00:00Z | 21.8 | Living Room | -| 2022-01-01T11:00:00Z | 22.4 | Kitchen | -| 2022-01-01T12:00:00Z | 22.2 | Living Room | -| 2022-01-01T12:00:00Z | 22.5 | Kitchen | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `BOTTOM()` -[maintains the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FIRST() - -Returns the [field value](/influxdb/cloud-serverless/reference/glossary/#field-value) with the oldest timestamp. - -```sql -FIRST(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field [data types](/influxdb/cloud-serverless/reference/glossary/#field-value). - -#### Notable behaviors - -- `FIRST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the first value for a field" %}} - -```sql -SELECT FIRST(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | first | -| :------------------- | ----: | -| 2022-01-01T08:00:00Z | 21.1 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the first value from each field" %}} - -```sql -SELECT FIRST(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first_co | first_hum | first_temp | -| :------------------- | -------: | --------: | ---------: | -| 1970-01-01T00:00:00Z | 0 | 35.9 | 21.1 | - -{{% /expand %}} - -{{% expand "Select the first value from field keys that match a regular expression" %}} - -```sql -SELECT FIRST(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first_hum | first_temp | -| :------------------- | --------: | ---------: | -| 1970-01-01T00:00:00Z | 35.9 | 21.1 | - -{{% /expand %}} - -{{% expand "Select the first value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - FIRST(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first | -| :------------------- | ----: | -| 2022-01-01T06:00:00Z | 21 | -| 2022-01-01T12:00:00Z | 22.5 | -| 2022-01-01T18:00:00Z | 23.3 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `FIRST()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LAST() - -Returns the [field value](/influxdb/cloud-serverless/reference/glossary/#field-value) with the most recent timestamp. - -```sql -LAST(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field [data types](/influxdb/cloud-serverless/reference/glossary/#field-value). - -#### Notable behaviors - -- `LAST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the last value for a field" %}} - -```sql -SELECT LAST(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | last | -| :------------------- | ---: | -| 2022-01-01T20:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the last value from each field" %}} - -```sql -SELECT LAST(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last_co | last_hum | last_temp | -| :------------------- | ------: | -------: | --------: | -| 1970-01-01T00:00:00Z | 26 | 36.5 | 22.7 | - -{{% /expand %}} - -{{% expand "Select the last value from field keys that match a regular expression" %}} - -```sql -SELECT LAST(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last_hum | last_temp | -| :------------------- | -------: | --------: | -| 1970-01-01T00:00:00Z | 36.5 | 22.7 | - -{{% /expand %}} - -{{% expand "Select the last value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - LAST(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 22.4 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `LAST()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MAX() - -Returns the greatest [field value](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -MAX(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MAX()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the maximum value from a field" %}} - -```sql -SELECT MAX(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | max | -| :------------------- | --: | -| 2022-01-01T20:00:00Z | 26 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the maximum value from each field" %}} - -```sql -SELECT MAX(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max_co | max_hum | max_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 26 | 36.9 | 23.3 | - -{{% /expand %}} - -{{% expand "Select the maximum value from field keys that match a regular expression" %}} - -```sql -SELECT MAX(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max_hum | max_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 36.9 | 23.3 | - -{{% /expand %}} - -{{% expand "Select the maximum value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MAX(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 23 | -| 2022-01-01T12:00:00Z | 22.8 | -| 2022-01-01T18:00:00Z | 23.3 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `MAX()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MIN() - -Returns the lowest [field value](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -MIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MIN()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the minimum value from a field" %}} - -```sql -SELECT MIN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | min | -| :------------------- | --: | -| 2022-01-01T08:00:00Z | 21 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the minimum value from each field" %}} - -```sql -SELECT MIN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min_co | min_hum | min_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 0 | 35.9 | 21 | - -{{% /expand %}} - -{{% expand "Select the minimum value from field keys that match a regular expression" %}} - -```sql -SELECT MIN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min_hum | min_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 35.9 | 21 | - -{{% /expand %}} - -{{% expand "Select the minimum value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MIN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 21 | -| 2022-01-01T12:00:00Z | 22.4 | -| 2022-01-01T18:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `MIN()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## PERCENTILE() - -Returns the `N`th percentile [field value](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -PERCENTILE(field_expression, N) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. -- **N**: Percentile to return. - Must be an integer or float value **greater than 0 and less than or equal to 100**. - -#### Notable behaviors - -- `PERCENTILE()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `PERCENTILE(example_field, 100)` is equivalent to [`MAX(example_field)`](#max). -- `PERCENTILE(example_field, 50)` is nearly equivalent to - [`MEDIAN(example_field)`](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/#median), - except `MEDIAN()` returns the average of the two middle values if the field - contains an even number of values. -- `PERCENTILE(example_field, 0)` returns _null_. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the 50th percentile value from a field" %}} - -```sql -SELECT PERCENTILE(temp, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | percentile | -| :------------------- | ---------: | -| 2022-01-01T11:00:00Z | 22.4 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from each field" %}} - -```sql -SELECT PERCENTILE(*, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile_co | percentile_hum | percentile_temp | -| :------------------- | ------------: | -------------: | --------------: | -| 1970-01-01T00:00:00Z | 1 | 36 | 22.4 | - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from field keys that match a regular expression" %}} - -```sql -SELECT PERCENTILE(/^[th]/, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile_hum | percentile_temp | -| :------------------- | -------------: | --------------: | -| 1970-01-01T00:00:00Z | 36 | 22.4 | - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - PERCENTILE(temp, 50) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile | -| :------------------- | ---------: | -| 2022-01-01T06:00:00Z | 22.4 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `PERCENTILE()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - - - -## TOP() - -Returns the greatest `N` [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). -`TOP()` supports int64 and float64 field value [data types](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -TOP(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) -``` - -{{% note %}} -**Note:** `TOP()` returns the field value with the earliest timestamp if there's -a tie between two or more values for the greatest value. -{{% /note %}} - -#### Arguments - -- **field_expression**: Expression to identify the field to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key) - or constant. -- **tag_expression**: Expression to identify a tag key to segment by. - Can be a [tag key](/influxdb/cloud-serverless/reference/glossary/#tag-key) - or constant. Comma-delimit multiple tags. -- **N**: Number of results to return from each InfluxQL group or specified tag segment. - -#### Notable behaviors - -- `TOP()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `TOP()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the top three values of a field" %}} - -```sql -SELECT TOP(temp, 3) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | -| :------------------- | ---: | -| 2022-01-01T09:00:00Z | 23 | -| 2022-01-01T18:00:00Z | 23.3 | -| 2022-01-01T19:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top field value for two unique tag values" %}} - -```sql -SELECT TOP(temp, room, 2) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T18:00:00Z | 22.8 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top three field values and the tag value associated with each" %}} - -```sql -SELECT TOP(temp, 3), room FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :------ | -| 2022-01-01T09:00:00Z | 23 | Kitchen | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T19:00:00Z | 23.1 | Kitchen | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top field values for unique tag values and within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} -```sql -SELECT - TOP(temp, room, 2) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -GROUP BY time(2h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T09:00:00Z | 23 | Kitchen | -| 2022-01-01T09:00:00Z | 21.4 | Living Room | -| 2022-01-01T10:00:00Z | 22.7 | Kitchen | -| 2022-01-01T11:00:00Z | 22.2 | Living Room | -| 2022-01-01T12:00:00Z | 22.5 | Kitchen | -| 2022-01-01T12:00:00Z | 22.2 | Living Room | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `TOP()` -[maintains the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable behaviors of selector functions - -- [Timestamps when grouping by time](#timestamps-when-grouping-by-time) -- [Selector functions may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected) - -### Timestamps when grouping by time - -When using selector functions with a `GROUP BY time()` clause, most selector -functions return the timestamp of the starting boundary for each time interval. -However functions with an `N` argument that specifies the number of results to -return per group maintain the original timestamp of each returned point. - -{{< flex >}} -{{% flex-content %}} - -###### Return the start time of each time interval - -- [FIRST()](#first) -- [LAST()](#last) -- [MAX()](#max) -- [MIN()](#min) -- [PERCENTILE()](#percentile) - -{{% /flex-content %}} -{{% flex-content %}} - -###### Maintain the original timestamp - -- [BOTTOM()](#bottom) -- [TOP()](#top) - - -{{% /flex-content %}} -{{< /flex >}} - -### Selector functions may return fewer points than expected - -Queries that use the following selector functions with an `N` argument may -return fewer points than expected. - -- [BOTTOM()](#bottom) -- [TOP()](#top) - - -If the InfluxQL group or specified tag key contains `X` points or unique tag -values and `X` is less than `N`, the function returns `X` results instead of `N` -for each group or tag value. - -{{< expand-wrapper >}} -{{% expand "View example for `FN(field_key, N)`" %}} - -The example below selects the bottom 5 temperatures from the Kitchen between -{{% influxdb/custom-timestamps-span %}}2022-01-01T08:00:00Z{{% /influxdb/custom-timestamps-span %}} -and {{% influxdb/custom-timestamps-span %}}2022-01-01T10:00:00Z{{% /influxdb/custom-timestamps-span %}}. -There are only 3 points recorded for the Kitchen during the queried time range, -so the query returns 3 points instead of 5. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT BOTTOM(temp, 5) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' - AND room = 'Kitchen' -``` - -| time | bottom | -| :------------------- | -----: | -| 2022-01-01T08:00:00Z | 21 | -| 2022-01-01T09:00:00Z | 23 | -| 2022-01-01T10:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "View example for `FN(field_key, tag_key, N)`" %}} - -The example below selects the top temperature from 3 unique values of the `room` tag. -However, the `room` tag only has 2 unique values, so results only contain 2 values. - -```sql -SELECT TOP(temp, room, 3) FROM home -``` - -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T18:00:00Z | 22.8 | Living Room | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/reference/influxql/functions/technical-analysis.md b/content/influxdb/cloud-serverless/reference/influxql/functions/technical-analysis.md index fb4d69bcd..e8322ec8c 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/functions/technical-analysis.md +++ b/content/influxdb/cloud-serverless/reference/influxql/functions/technical-analysis.md @@ -10,1905 +10,6 @@ menu: weight: 205 # None of these functions work yet so listing as draft draft: true + +source: /shared/influxql-v3-reference/functions/technical-analysis.md --- - -Use technical analysis functions to apply algorithms to your time series data. -Many of these algorithms are often used to analyze financial and investment data, -but have application in other use cases as well. - -- [Predictive analysis](#predictive-analysis): - - [HOLT_WINTERS()](#holt_winters) -- [Technical analysis](#technical-analysis-functions): - - [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) - - [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) - - [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) - - [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) - - [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) - - [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) - - [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) - - [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) - -## Predictive analysis - -Predictive analysis functions are a type of technical analysis algorithms that -predict and forecast future values. - -### HOLT_WINTERS() - -Returns N number of predicted [field values](/influxdb/cloud-serverless/reference/glossary/#field-value) -using the [Holt-Winters](https://www.otexts.org/fpp/7/5) seasonal method. -`HOLT_WINTERS_WITH_FIT()` returns the fitted values in addition to `N` seasonally -adjusted predicted field values. - -Input data points must occur at regular time intervals. -To ensure regular time intervals, `HOLT_WINTERS` requires an aggregate expression -as input and a a `GROUP BY time()` to apply the aggregate operation at regular intervals. - -Use `HOLT_WINTERS()` to: - -- Predict when data values will cross a given threshold -- Compare predicted values with actual values to detect anomalies in your data - -```sql -HOLT_WINTERS[_WITH_FIT](aggregate_expression, N, S) -``` - -#### Arguments {#arguments-holt-winters} - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/cloud-serverless/reference/influxql/functions/aggregate/). - The expression can operate on a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. -- **N**: Number of values to predict. - Predicted values occur at the same interval specified in the `GROUP BY time()` clause. -- **S**: Seasonal pattern length (number of values per season) to use when - adjusting for seasonal patterns. - To _not_ seasonally adjust predicted values, set `S` to `0` or `1.` - -#### Notable behaviors - -- In some cases, you may receive fewer than `N` predicted points. - This typically occurs when the seasonal adjustment (`S`) is invalid or when - input data is not suited for the Holt Winters algorithm. - -#### Examples - -The following examples use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -{{< expand-wrapper >}} -{{% expand "Use Holt Winters to predict field values with seasonal adjustment" %}} - -```sql -SELECT - HOLT_WINTERS(MEAN(temp_avg), 12, 12) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters | -| :------------------- | -----------------: | -| 2023-01-23T00:00:00Z | 52.141810685706844 | -| 2023-02-22T00:00:00Z | 55.41941302100692 | -| 2023-03-24T00:00:00Z | 59.74300473524414 | -| 2023-04-23T00:00:00Z | 59.91932719987093 | -| 2023-05-23T00:00:00Z | 56.03083957191051 | -| 2023-06-22T00:00:00Z | 59.98437978757551 | -| 2023-07-22T00:00:00Z | 60.903170945334175 | -| 2023-08-21T00:00:00Z | 60.75738169893358 | -| 2023-09-20T00:00:00Z | 56.619132830933445 | -| 2023-10-20T00:00:00Z | 56.10559366563841 | -| 2023-11-19T00:00:00Z | 56.248977829575935 | -| 2023-12-19T00:00:00Z | 56.075540144158985 | - -{{% /expand %}} -{{% expand "Use Holt Winters to predict field values with no seasonal adjustment" %}} - -```sql -SELECT - HOLT_WINTERS(MEAN(temp_avg), 12, 0) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters | -| :------------------- | ----------------: | -| 2023-01-23T00:00:00Z | 58.55632627159769 | -| 2023-02-22T00:00:00Z | 58.55632627159944 | -| 2023-03-24T00:00:00Z | 58.55632627160024 | -| 2023-04-23T00:00:00Z | 58.55632627160061 | -| 2023-05-23T00:00:00Z | 58.55632627160079 | -| 2023-06-22T00:00:00Z | 58.55632627160087 | -| 2023-07-22T00:00:00Z | 58.5563262716009 | -| 2023-08-21T00:00:00Z | 58.55632627160092 | -| 2023-09-20T00:00:00Z | 58.55632627160093 | -| 2023-10-20T00:00:00Z | 58.55632627160094 | -| 2023-11-19T00:00:00Z | 58.55632627160094 | -| 2023-12-19T00:00:00Z | 58.55632627160094 | - -{{% /expand %}} - -{{% expand "Use Holt Winters to predict field values with fitted values" %}} - -```sql -SELECT - HOLT_WINTERS_WITH_FIT(MEAN(temp_avg), 12, 12) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2021-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters_with_fit | -| :------------------- | --------------------: | -| 2020-12-04T00:00:00Z | 50.5 | -| 2021-01-03T00:00:00Z | 53.280924101779426 | -| 2021-02-02T00:00:00Z | 52.099111942046704 | -| 2021-03-04T00:00:00Z | 55.84541855092053 | -| 2021-04-03T00:00:00Z | 60.06803481717513 | -| 2021-05-03T00:00:00Z | 60.414989273392976 | -| 2021-06-02T00:00:00Z | 58.265755948192606 | -| 2021-07-02T00:00:00Z | 63.12426388001118 | -| 2021-08-01T00:00:00Z | 64.34281315294628 | -| 2021-08-31T00:00:00Z | 62.701261106938865 | -| 2021-09-30T00:00:00Z | 58.39095413696881 | -| 2021-10-30T00:00:00Z | 57.571954549171174 | -| 2021-11-29T00:00:00Z | 57.72622091917164 | -| 2021-12-29T00:00:00Z | 56.21981843845102 | -| 2022-01-28T00:00:00Z | 52.592076197024845 | -| 2022-02-27T00:00:00Z | 55.20608671167453 | -| 2022-03-29T00:00:00Z | 59.01290245961656 | -| 2022-04-28T00:00:00Z | 59.10660216049941 | -| 2022-05-28T00:00:00Z | 55.87577637598558 | -| 2022-06-27T00:00:00Z | 59.10005762573857 | -| 2022-07-27T00:00:00Z | 60.04395791516323 | -| 2022-08-26T00:00:00Z | 59.76994469907478 | -| 2022-09-25T00:00:00Z | 56.21467016861341 | -| 2022-10-25T00:00:00Z | 55.76538052914458 | -| 2022-11-24T00:00:00Z | 55.95817013792435 | -| 2022-12-24T00:00:00Z | 55.78474730739332 | -| 2023-01-23T00:00:00Z | 52.33558076070284 | -| 2023-02-22T00:00:00Z | 55.15350456137378 | -| 2023-03-24T00:00:00Z | 58.95292137832944 | -| 2023-04-23T00:00:00Z | 59.15381228655361 | -| 2023-05-23T00:00:00Z | 55.77542228450764 | -| 2023-06-22T00:00:00Z | 59.05797349347727 | -| 2023-07-22T00:00:00Z | 59.87830149275526 | -| 2023-08-21T00:00:00Z | 59.718176562030116 | -| 2023-09-20T00:00:00Z | 56.13817596332756 | -| 2023-10-20T00:00:00Z | 55.626497950276445 | -| 2023-11-19T00:00:00Z | 55.81338302167719 | -| 2023-12-19T00:00:00Z | 55.75008713518608 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Technical analysis functions - -Technical analysis functions apply widely used algorithms to your data. -While they are primarily used in finance and investing, they have -application in other industries. - -- [Notable behaviors of technical analysis functions](#notable-behaviors-of-technical-analysis-functions) -- [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) -- [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) -- [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) -- [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) -- [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) -- [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) -- [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) -- [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) - -### Notable behaviors of technical analysis functions - -#### Must use aggregate or selector functions when grouping by time - -All technical analysis functions support `GROUP BY` clauses that group by tags, -but do not directly support `GROUP BY` clauses that group by time. -To use technical analysis functions with with a `GROUP BY time()` clause, apply -an [aggregate](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/) -or [selector](/influxdb/cloud-serverless/reference/influxql/functions/selectors/) -function to the **field_expression** argument. -The technical analysis function operates on the result of the aggregate or -selector operation. - ---- - -### CHANDE_MOMENTUM_OSCILLATOR() - -The Chande Momentum Oscillator (CMO) is a technical momentum indicator developed by Tushar Chande. -The CMO indicator is created by calculating the difference between the sum of all -recent higher data points and the sum of all recent lower data points, -then dividing the result by the sum of all data movement over a given time period. -The result is multiplied by 100 to give the -100 to +100 range. -{{% cite %}}[Source](https://www.fidelity.com/learning-center/trading-investing/technical-analysis/technical-indicator-guide/cmo){{% /cite %}} - -```sql -CHANDE_MOMENTUM_OSCILLATOR(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-cmo} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period` | - | simple | `period` | - | none | `period - 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - - **none**: The algorithm does not perform any warmup at all. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 53.84615384615377 | -| 2022-01-01T12:00:00Z | 55.5555555555555 | -| 2022-01-01T13:00:00Z | -19.999999999999858 | -| 2022-01-01T14:00:00Z | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 59.99999999999972 | -| 2022-01-01T16:00:00Z | -14.285714285714432 | -| 2022-01-01T17:00:00Z | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator_co | chande_momentum_oscillator_hum | chande_momentum_oscillator_temp | -| :------------------- | ----------------------------: | -----------------------------: | ------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 20 | 53.84615384615377 | -| 2022-01-01T12:00:00Z | 0 | 20 | 55.5555555555555 | -| 2022-01-01T13:00:00Z | 100 | 42.85714285714228 | -19.999999999999858 | -| 2022-01-01T14:00:00Z | 100 | 24.999999999999332 | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 100 | 25.000000000000444 | 59.99999999999972 | -| 2022-01-01T16:00:00Z | 100 | 0 | -14.285714285714432 | -| 2022-01-01T17:00:00Z | 100 | -100 | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 100 | 50.0000000000003 | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 100 | 28.5714285714285 | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 100 | 38.461538461538545 | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T14:00:00Z | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 59.99999999999972 | -| 2022-01-01T16:00:00Z | -14.285714285714432 | -| 2022-01-01T17:00:00Z | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T12:00:00Z | 94.9367088607595 | -| 2022-01-01T13:00:00Z | 95.04132231404957 | -| 2022-01-01T14:00:00Z | 95.04132231404955 | -| 2022-01-01T15:00:00Z | 92.68218929543389 | -| 2022-01-01T16:00:00Z | 83.79002019036625 | -| 2022-01-01T17:00:00Z | 84.72964405398058 | -| 2022-01-01T18:00:00Z | 86.77405015296912 | -| 2022-01-01T19:00:00Z | 76.28466518769179 | -| 2022-01-01T20:00:00Z | 53.322717259176535 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2020-07-07T00:00:00Z | 100 | -| 2020-10-05T00:00:00Z | 21.498959056210964 | -| 2021-01-03T00:00:00Z | 2.0072053525475924 | -| 2021-04-03T00:00:00Z | -6.190741773563866 | -| 2021-07-02T00:00:00Z | -8.924485125858132 | -| 2021-09-30T00:00:00Z | 1.2078830260648301 | -| 2021-12-29T00:00:00Z | -5.181655747468743 | -| 2022-03-29T00:00:00Z | -2.3768115942029 | -| 2022-06-27T00:00:00Z | 6.511381683430422 | -| 2022-09-25T00:00:00Z | -7.7487391104997485 | -| 2022-12-24T00:00:00Z | 2.928763268960232 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### DOUBLE_EXPONENTIAL_MOVING_AVERAGE() - -The Double Exponential Moving Average (DEMA) attempts to remove the inherent lag -associated with moving averages by placing more weight on recent values. -The name suggests this is achieved by applying a double exponential smoothing which is not the case. -The value of an [EMA](#exponential_moving_average) is doubled. -To keep the value in line with the actual data and to remove the lag, the value "EMA of EMA" -is subtracted from the previously doubled EMA. -{{% cite %}}[Source](https://en.wikipedia.org/wiki/Double_exponential_moving_average){{% /cite %}} - -```sql -DOUBLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-dema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `(period - 1) × 2` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T11:00:00Z | 22.630333333333333 | -| 2022-01-01T12:00:00Z | 22.5854 | -| 2022-01-01T13:00:00Z | 22.747560000000004 | -| 2022-01-01T14:00:00Z | 22.814328 | -| 2022-01-01T15:00:00Z | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 22.55332832 | -| 2022-01-01T17:00:00Z | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 23.0672594816 | -| 2022-01-01T19:00:00Z | 23.12957407488 | -| 2022-01-01T20:00:00Z | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average_co | double_exponential_moving_average_hum | double_exponential_moving_average_temp | -| :------------------- | -----------------------------------: | ------------------------------------: | -------------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.056000000000004 | 22.630333333333333 | -| 2022-01-01T12:00:00Z | 0 | 36.019200000000005 | 22.5854 | -| 2022-01-01T13:00:00Z | 0.64 | 36.322880000000005 | 22.747560000000004 | -| 2022-01-01T14:00:00Z | 0.9279999999999999 | 36.332544000000006 | 22.814328 | -| 2022-01-01T15:00:00Z | 2.3232 | 36.266816000000006 | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 5.49376 | 36.104463360000004 | 22.55332832 | -| 2022-01-01T17:00:00Z | 8.15616 | 36.029302272 | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 15.0096384 | 36.573555916800004 | 23.0672594816 | -| 2022-01-01T19:00:00Z | 20.51534848 | 36.62971828224 | 23.12957407488 | -| 2022-01-01T20:00:00Z | 25.294948352 | 36.581181808640004 | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.814328 | -| 2022-01-01T15:00:00Z | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 22.55332832 | -| 2022-01-01T17:00:00Z | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 23.0672594816 | -| 2022-01-01T19:00:00Z | 23.12957407488 | -| 2022-01-01T20:00:00Z | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.8312 | -| 2022-01-01T15:00:00Z | 22.792303999999998 | -| 2022-01-01T16:00:00Z | 22.5715328 | -| 2022-01-01T17:00:00Z | 22.65660992 | -| 2022-01-01T18:00:00Z | 23.078180096 | -| 2022-01-01T19:00:00Z | 23.137436544 | -| 2022-01-01T20:00:00Z | 22.89677901824 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2020-07-07T00:00:00Z | 63.01034259259259 | -| 2020-10-05T00:00:00Z | 59.68671666666667 | -| 2021-01-03T00:00:00Z | 56.266558888888895 | -| 2021-04-03T00:00:00Z | 58.20687488888889 | -| 2021-07-02T00:00:00Z | 61.229622000000006 | -| 2021-09-30T00:00:00Z | 58.78596032888889 | -| 2021-12-29T00:00:00Z | 55.1067106968889 | -| 2022-03-29T00:00:00Z | 57.311773784533344 | -| 2022-06-27T00:00:00Z | 61.66637935722668 | -| 2022-09-25T00:00:00Z | 57.77452777735112 | -| 2022-12-24T00:00:00Z | 55.044203430886405 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### EXPONENTIAL_MOVING_AVERAGE() - -An exponential moving average (EMA) (or exponentially weighted moving average) -is a type of moving average similar to a -[simple moving average](/influxdb/cloud-serverless/reference/influxql/functions/transformations/#moving_average), -except more weight is given to the latest data. - -This type of moving average reacts faster to recent data changes than a simple moving average. -{{% cite %}}[Source](https://www.investopedia.com/terms/e/ema.asp){{% /cite %}} - -```sql -EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-ema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `period - 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 22.47 | -| 2022-01-01T12:00:00Z | 22.482 | -| 2022-01-01T13:00:00Z | 22.6092 | -| 2022-01-01T14:00:00Z | 22.68552 | -| 2022-01-01T15:00:00Z | 22.691312 | -| 2022-01-01T16:00:00Z | 22.5747872 | -| 2022-01-01T17:00:00Z | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 22.894923392 | -| 2022-01-01T19:00:00Z | 22.9769540352 | -| 2022-01-01T20:00:00Z | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average_co | exponential_moving_average_hum | exponential_moving_average_temp | -| :------------------- | ----------------------------: | -----------------------------: | ------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.06 | 22.47 | -| 2022-01-01T12:00:00Z | 0 | 36.036 | 22.482 | -| 2022-01-01T13:00:00Z | 0.4 | 36.2216 | 22.6092 | -| 2022-01-01T14:00:00Z | 0.64 | 36.25296 | 22.68552 | -| 2022-01-01T15:00:00Z | 1.584 | 36.231776 | 22.691312 | -| 2022-01-01T16:00:00Z | 3.7504000000000004 | 36.1390656 | 22.5747872 | -| 2022-01-01T17:00:00Z | 5.85024 | 36.08343936 | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 10.710144 | 36.410063616 | 22.894923392 | -| 2022-01-01T19:00:00Z | 15.2260864 | 36.4860381696 | 22.9769540352 | -| 2022-01-01T20:00:00Z | 19.53565184 | 36.49162290176 | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T14:00:00Z | 22.68552 | -| 2022-01-01T15:00:00Z | 22.691312 | -| 2022-01-01T16:00:00Z | 22.5747872 | -| 2022-01-01T17:00:00Z | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 22.894923392 | -| 2022-01-01T19:00:00Z | 22.9769540352 | -| 2022-01-01T20:00:00Z | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 22.275 | -| 2022-01-01T12:00:00Z | 22.365 | -| 2022-01-01T13:00:00Z | 22.538999999999998 | -| 2022-01-01T14:00:00Z | 22.6434 | -| 2022-01-01T15:00:00Z | 22.66604 | -| 2022-01-01T16:00:00Z | 22.559624 | -| 2022-01-01T17:00:00Z | 22.6157744 | -| 2022-01-01T18:00:00Z | 22.88946464 | -| 2022-01-01T19:00:00Z | 22.973678784 | -| 2022-01-01T20:00:00Z | 22.8642072704 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2020-07-07T00:00:00Z | 59.971944444444446 | -| 2020-10-05T00:00:00Z | 58.65427777777778 | -| 2021-01-03T00:00:00Z | 56.77478888888889 | -| 2021-04-03T00:00:00Z | 57.86042888888889 | -| 2021-07-02T00:00:00Z | 59.836257333333336 | -| 2021-09-30T00:00:00Z | 58.657309955555554 | -| 2021-12-29T00:00:00Z | 56.38994152888889 | -| 2022-03-29T00:00:00Z | 57.44729825066667 | -| 2022-06-27T00:00:00Z | 60.13504561706667 | -| 2022-09-25T00:00:00Z | 58.085471814684446 | -| 2022-12-24T00:00:00Z | 56.30128308881067 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### KAUFMANS_EFFICIENCY_RATIO() - -Kaufman's Efficiency Ration, or simply "Efficiency Ratio" (ER), is calculated by -dividing the data change over a period by the absolute sum of the data movements -that occurred to achieve that change. -The resulting ratio ranges between 0 and 1 with higher values representing a -more efficient or trending market. - -The ER is very similar to the [Chande Momentum Oscillator](#chande_momentum_oscillator) (CMO). -The difference is that the CMO takes market direction into account, but if you -take the absolute CMO and divide by 100, you you get the Efficiency Ratio. -{{% cite %}}[Source](http://etfhq.com/blog/2011/02/07/kaufmans-efficiency-ratio/){{% /cite %}} - -```sql -KAUFMANS_EFFICIENCY_RATIO(field_expression, period[, hold_period]) -``` - -#### Arguments {#arguments-er} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is the same as `period`. - Must be an integer greater than or equal to `1`. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2022-01-01T12:00:00Z | 0.555555555555555 | -| 2022-01-01T13:00:00Z | 0.19999999999999857 | -| 2022-01-01T14:00:00Z | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio_co | kaufmans_efficiency_ratio_hum | kaufmans_efficiency_ratio_temp | -| :------------------- | ---------------------------: | ----------------------------: | -----------------------------: | -| 2022-01-01T12:00:00Z | 0 | 0.2 | 0.555555555555555 | -| 2022-01-01T13:00:00Z | 1 | 0.4285714285714228 | 0.19999999999999857 | -| 2022-01-01T14:00:00Z | 1 | 0.24999999999999334 | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 1 | 0.25000000000000444 | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 1 | 0 | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 1 | 1 | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 1 | 0.500000000000003 | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 1 | 0.285714285714285 | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 1 | 0.38461538461538547 | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2022-01-01T14:00:00Z | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2020-10-05T00:00:00Z | 0.21498959056210964 | -| 2021-01-03T00:00:00Z | 0.020072053525475923 | -| 2021-04-03T00:00:00Z | 0.06190741773563866 | -| 2021-07-02T00:00:00Z | 0.08924485125858131 | -| 2021-09-30T00:00:00Z | 0.0120788302606483 | -| 2021-12-29T00:00:00Z | 0.05181655747468743 | -| 2022-03-29T00:00:00Z | 0.023768115942028996 | -| 2022-06-27T00:00:00Z | 0.06511381683430421 | -| 2022-09-25T00:00:00Z | 0.07748739110499749 | -| 2022-12-24T00:00:00Z | 0.029287632689602317 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### KAUFMANS_ADAPTIVE_MOVING_AVERAGE() - -Kaufman's Adaptive Moving Average (KAMA) is a moving average designed to account -for sample noise or volatility. -KAMA will closely follow data points when the data swings are relatively small and noise is low. -KAMA will adjust when the data swings widen and follow data from a greater distance. -This trend-following indicator can be used to identify the overall trend, -time turning points and filter data movements. -{{% cite %}}[Source](http://stockcharts.com/school/doku.php?id=chart_school:technical_indicators:kaufman_s_adaptive_moving_average){{% /cite %}} - -```sql -KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_expression, period[, hold_period]) -``` - -#### Arguments {#arguments-kama} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is the same as `period`. - Must be an integer greater than or equal to `1`. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2022-01-01T12:00:00Z | 22.415923627793976 | -| 2022-01-01T13:00:00Z | 22.429061002513993 | -| 2022-01-01T14:00:00Z | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average_co | kaufmans_adaptive_moving_average_hum | kaufmans_adaptive_moving_average_temp | -| :------------------- | ----------------------------------: | -----------------------------------: | ------------------------------------: | -| 2022-01-01T12:00:00Z | 0 | 36 | 22.415923627793976 | -| 2022-01-01T13:00:00Z | 0.44444444444444453 | 36.052029136316335 | 22.429061002513993 | -| 2022-01-01T14:00:00Z | 0.6913580246913581 | 36.063497322866624 | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 1.7174211248285327 | 36.06981031521873 | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 4.065233958238074 | 36.069519741586184 | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 6.258463310132264 | 36.03862207865899 | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 11.476924061184592 | 36.153751327944484 | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 16.153846700658107 | 36.17872350475971 | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 20.52991483369895 | 36.206893865280215 | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2022-01-01T14:00:00Z | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2020-10-05T00:00:00Z | 64.23776629054989 | -| 2021-01-03T00:00:00Z | 64.17743082167587 | -| 2021-04-03T00:00:00Z | 64.12884833681618 | -| 2021-07-02T00:00:00Z | 64.11026540732492 | -| 2021-09-30T00:00:00Z | 64.07304846623671 | -| 2021-12-29T00:00:00Z | 63.97149717822299 | -| 2022-03-29T00:00:00Z | 63.94081206327896 | -| 2022-06-27T00:00:00Z | 63.94324197904272 | -| 2022-09-25T00:00:00Z | 63.83284150412919 | -| 2022-12-24T00:00:00Z | 63.76394979616807 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### RELATIVE_STRENGTH_INDEX() - -The relative strength index (RSI) is a momentum indicator that compares the -magnitude of recent increases and decreases over a specified time period to -measure speed and change of data movements. -{{% cite %}}[Source](https://www.investopedia.com/terms/r/rsi.asp){{% /cite %}} - -```sql -RELATIVE_STRENGTH_INDEX(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-rsi} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is the same as the `period`. - Must be an integer greater than or equal to `-1`. -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T12:00:00Z | 92.39130434782608 | -| 2022-01-01T13:00:00Z | 92.78350515463916 | -| 2022-01-01T14:00:00Z | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index_co | relative_strength_index_hum | relative_strength_index_temp | -| :------------------- | -------------------------: | --------------------------: | ---------------------------: | -| 2022-01-01T12:00:00Z | | 98.11827956989245 | 92.39130434782608 | -| 2022-01-01T13:00:00Z | 100 | 98.23677581863977 | 92.78350515463916 | -| 2022-01-01T14:00:00Z | 100 | 95.04467912266443 | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 100 | 93.02941956003185 | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 100 | 88.05084037126848 | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 100 | 88.05084037126848 | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 100 | 91.63299959013992 | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 100 | 80.85951627810859 | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 100 | 76.8440852816889 | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T14:00:00Z | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T12:00:00Z | 97.46835443037975 | -| 2022-01-01T13:00:00Z | 97.52066115702479 | -| 2022-01-01T14:00:00Z | 97.52066115702479 | -| 2022-01-01T15:00:00Z | 96.34109464771694 | -| 2022-01-01T16:00:00Z | 91.89501009518312 | -| 2022-01-01T17:00:00Z | 92.36482202699028 | -| 2022-01-01T18:00:00Z | 93.38702507648456 | -| 2022-01-01T19:00:00Z | 88.1423325938459 | -| 2022-01-01T20:00:00Z | 76.66135862958828 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2020-10-05T00:00:00Z | 69.9692046299246 | -| 2021-01-03T00:00:00Z | 63.37405020679043 | -| 2021-04-03T00:00:00Z | 70.82662989351107 | -| 2021-07-02T00:00:00Z | 74.90131747577793 | -| 2021-09-30T00:00:00Z | 56.212729394565066 | -| 2021-12-29T00:00:00Z | 46.095152535803514 | -| 2022-03-29T00:00:00Z | 60.709021374375894 | -| 2022-06-27T00:00:00Z | 69.93773053391476 | -| 2022-09-25T00:00:00Z | 44.87321655968338 | -| 2022-12-24T00:00:00Z | 41.845933101386215 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### TRIPLE_EXPONENTIAL_MOVING_AVERAGE() - -The triple exponential moving average (TEMA) filters out volatility from -conventional moving averages. -While the name implies that it's a triple exponential smoothing, it's actually a -composite of a [single exponential moving average](#exponential_moving_average), -a [double exponential moving average](#double_exponential_moving_average), -and a triple exponential moving average. -{{% cite %}}[Source](https://www.investopedia.com/terms/t/triple-exponential-moving-average.asp){{% /cite %}} - -```sql -TRIPLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-tema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `(period - 1) × 3` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T11:00:00Z | 22.54347777777777 | -| 2022-01-01T12:00:00Z | 22.499126666666672 | -| 2022-01-01T13:00:00Z | 22.716772000000002 | -| 2022-01-01T14:00:00Z | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 22.6128236096 | -| 2022-01-01T18:00:00Z | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average_co | triple_exponential_moving_average_hum | triple_exponential_moving_average_temp | -| :------------------- | -----------------------------------: | ------------------------------------: | -------------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.03026666666666 | 22.54347777777777 | -| 2022-01-01T12:00:00Z | 0 | 35.99608 | 22.499126666666672 | -| 2022-01-01T13:00:00Z | 0.7840000000000001 | 36.379856000000004 | 22.716772000000002 | -| 2022-01-01T14:00:00Z | 1.0432 | 36.353712 | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 2.663040000000001 | 36.25279040000001 | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 6.300159999999999 | 36.054262656000006 | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 8.977536 | 35.98746094080001 | 22.6128236096 | -| 2022-01-01T18:00:00Z | 16.698608639999996 | 36.67902875136 | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 22.122591232 | 36.68111467007999 | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 26.541314662400005 | 36.579546917888 | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 22.6128236096 | -| 2022-01-01T18:00:00Z | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T17:00:00Z | 22.65201408 | -| 2022-01-01T18:00:00Z | 23.164150553600003 | -| 2022-01-01T19:00:00Z | 23.17404420096 | -| 2022-01-01T20:00:00Z | 22.84003200512 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2020-07-07T00:00:00Z | 64.17547253086421 | -| 2020-10-05T00:00:00Z | 59.182219074074055 | -| 2021-01-03T00:00:00Z | 55.03945899999998 | -| 2021-04-03T00:00:00Z | 57.98342055555557 | -| 2021-07-02T00:00:00Z | 61.72370060000002 | -| 2021-09-30T00:00:00Z | 58.3235789128889 | -| 2021-12-29T00:00:00Z | 53.982153124088896 | -| 2022-03-29T00:00:00Z | 57.325663060373344 | -| 2022-06-27T00:00:00Z | 62.67482784650667 | -| 2022-09-25T00:00:00Z | 57.274230204423134 | -| 2022-12-24T00:00:00Z | 54.17634351477504 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### TRIPLE_EXPONENTIAL_DERIVATIVE() - -The triple exponential derivative indicator, commonly referred to as "TRIX," is -an oscillator used to identify oversold and overbought markets, and can also be -used as a momentum indicator. -TRIX calculates a [triple exponential moving average](#triple_exponential_moving_average) -of the [log](/influxdb/v2/query-data/influxql/functions/transformations/#log) -of the data input over the period of time. -The previous value is subtracted from the previous value. -This prevents cycles that are shorter than the defined period from being considered by the indicator. - -Like many oscillators, TRIX oscillates around a zero line. When used as an oscillator, -a positive value indicates an overbought market while a negative value indicates an oversold market. -When used as a momentum indicator, a positive value suggests momentum is increasing -while a negative value suggests momentum is decreasing. -Many analysts believe that when the TRIX crosses above the zero line it gives a -buy signal, and when it closes below the zero line, it gives a sell signal. -{{% cite %}}[Source](https://www.investopedia.com/articles/technical/02/092402.asp){{% /cite %}} - -```sql -TRIPLE_EXPONENTIAL_DERIVATIVE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-trix} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :--------------------- | - | exponential | `period` | - | simple | `(period - 1) × 3 + 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T12:00:00Z | 0.5731400170122969 | -| 2022-01-01T13:00:00Z | 0.5082054442170802 | -| 2022-01-01T14:00:00Z | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative_co | triple_exponential_derivative_hum | triple_exponential_derivative_temp | -| :------------------- | -------------------------------: | --------------------------------: | ---------------------------------: | -| 2022-01-01T12:00:00Z | | 0.011689978802653656 | 0.5731400170122969 | -| 2022-01-01T13:00:00Z | | 0.08193865253971477 | 0.5082054442170802 | -| 2022-01-01T14:00:00Z | 179.99999999999997 | 0.10794983570248107 | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 148.57142857142853 | 0.0905729924662868 | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 140.22988505747128 | 0.02876803922613469 | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 92.48803827751195 | -0.022670378539191294 | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 84.49217002237135 | 0.10699801078373206 | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 64.59469801081093 | 0.17000537478475408 | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 48.10094220759999 | 0.16771238737589567 | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T14:00:00Z | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T18:00:00Z | 0.3040309049773704 | -| 2022-01-01T19:00:00Z | 0.37510717611963784 | -| 2022-01-01T20:00:00Z | 0.2625157254706467 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2020-10-05T00:00:00Z | 1.8609138140919912 | -| 2021-01-03T00:00:00Z | 0.8545019640246121 | -| 2021-04-03T00:00:00Z | 0.6716861515154271 | -| 2021-07-02T00:00:00Z | 1.0528294030543783 | -| 2021-09-30T00:00:00Z | 0.6847349621789123 | -| 2021-12-29T00:00:00Z | -0.18257939931221046 | -| 2022-03-29T00:00:00Z | -0.1722392917734461 | -| 2022-06-27T00:00:00Z | 0.6038050639217252 | -| 2022-09-25T00:00:00Z | 0.21734485841473639 | -| 2022-12-24T00:00:00Z | -0.44578753427667595 | - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/reference/influxql/functions/transformations.md b/content/influxdb/cloud-serverless/reference/influxql/functions/transformations.md index 242d99cba..789af31f1 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/functions/transformations.md +++ b/content/influxdb/cloud-serverless/reference/influxql/functions/transformations.md @@ -1,6 +1,6 @@ --- title: InfluxQL transformation functions -list_title: Tranfsormation functions +list_title: Transformation functions description: > Use transformation functions modify and return values in each row of queried data. menu: @@ -8,2743 +8,6 @@ menu: name: Transformations parent: influxql-functions weight: 205 + +source: /shared/influxql-v3-reference/functions/transformations.md --- - -InfluxQL transformation functions modify and return values in each row of queried data. - -- [ABS()](#abs) -- [ACOS()](#acos) -- [ASIN()](#asin) -- [ATAN()](#atan) -- [ATAN2()](#atan2) -- [CEIL()](#ceil) -- [COS()](#cos) -- [CUMULATIVE_SUM()](#cumulative_sum) -- [DERIVATIVE()](#derivative) -- [DIFFERENCE()](#difference) -- [ELAPSED()](#elapsed) -- [EXP()](#exp) -- [FLOOR()](#floor) -- [LN()](#ln) -- [LOG()](#log) -- [LOG2()](#log2) -- [LOG10()](#log10) -- [MOVING_AVERAGE()](#moving_average) -- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) -- [NON_NEGATIVE_DIFFERENCE()](#non_negative_difference) -- [POW()](#pow) -- [ROUND()](#round) -- [SIN()](#sin) -- [SQRT()](#sqrt) -- [TAN()](#tan) - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/cloud-serverless/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## Notable behaviors of transformation functions - -#### Must use aggregate or selector functions when grouping by time - -Most transformation functions support `GROUP BY` clauses that group by tags, -but do not directly support `GROUP BY` clauses that group by time. -To use transformation functions with with a `GROUP BY time()` clause, apply -an [aggregate](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/) -or [selector](/influxdb/cloud-serverless/reference/influxql/functions/selectors/) -function to the **field_expression** argument. -The transformation operates on the result of the aggregate or selector operation. - ---- - -## ABS() - -Returns the absolute value of the field value. - -```sql -ABS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ABS()` to a field" %}} - -```sql -SELECT - a, - ABS(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | abs | -| :------------------- | -----------------: | ----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.33909108671076 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 0.774984088561186 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 0.921037167720451 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 0.73880754843378 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 0.905980032168252 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 0.891164752631417 | - -{{% /expand %}} - -{{% expand "Apply `ABS()` to each field" %}} - -```sql -SELECT ABS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | abs_a | abs_b | -| :------------------- | ----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.163643058925645 | -| 2023-01-01T00:01:00Z | 0.774984088561186 | 0.137034364053949 | -| 2023-01-01T00:02:00Z | 0.921037167720451 | 0.482943221384294 | -| 2023-01-01T00:03:00Z | 0.73880754843378 | 0.0729732928756677 | -| 2023-01-01T00:04:00Z | 0.905980032168252 | 1.77857552719844 | -| 2023-01-01T00:05:00Z | 0.891164752631417 | 0.741147445214238 | - -{{% /expand %}} - -{{% expand "Apply `ABS()` to time windows (grouped by time)" %}} - -```sql -SELECT - ABS(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | abs | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 0.4345725888930678 | -| 2023-01-01T00:10:00Z | 0.12861008519618367 | -| 2023-01-01T00:20:00Z | 0.030168160597251192 | -| 2023-01-01T00:30:00Z | 0.02928699660831855 | -| 2023-01-01T00:40:00Z | 0.02211434600834538 | -| 2023-01-01T00:50:00Z | 0.15530468657783394 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ACOS() - -Returns the arccosine (in radians) of the field value. -Field values must be between -1 and 1. - -```sql -ACOS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ACOS()` to a field" %}} - -```sql -SELECT - a, - ACOS(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | acos | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 1.2248457522250173 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 2.4574862443115 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 2.741531473732281 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 2.4020955294179256 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 2.7044854502651114 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 2.6707024029338 | - -{{% /expand %}} - -{{% expand "Apply `ACOS()` to each field" %}} - -```sql -SELECT ACOS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | acos_a | acos_b | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 1.2248457522250173 | 1.7351786975993897 | -| 2023-01-01T00:01:00Z | 2.4574862443115 | 1.433329416131427 | -| 2023-01-01T00:02:00Z | 2.741531473732281 | 2.074809114132046 | -| 2023-01-01T00:03:00Z | 2.4020955294179256 | 1.6438345403920092 | -| 2023-01-01T00:04:00Z | 2.7044854502651114 | | -| 2023-01-01T00:05:00Z | 2.6707024029338 | 0.7360183965088304 | - -{{% /expand %}} - -{{% expand "Apply `ACOS()` to time windows (grouped by time)" %}} - -```sql -SELECT - ACOS(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | acos | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 2.0203599837582877 | -| 2023-01-01T00:10:00Z | 1.441829029328407 | -| 2023-01-01T00:20:00Z | 1.5406235882252437 | -| 2023-01-01T00:30:00Z | 1.5415051418561052 | -| 2023-01-01T00:40:00Z | 1.5486801779072885 | -| 2023-01-01T00:50:00Z | 1.41486045205998 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ASIN() - -Returns the arcsine (in radians) of the field value. -Field values must be between -1 and 1. - -```sql -ASIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ASIN()` to a field" %}} - -```sql -SELECT - a, - ASIN(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | asin | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.34595057456987915 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | -0.8866899175166036 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | -1.1707351469373848 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | -0.8312992026230288 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | -1.133689123470215 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | -1.0999060761389035 | - -{{% /expand %}} - -{{% expand "Apply `ASIN()` to each field" %}} - -```sql -SELECT ASIN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | asin_a | asin_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.34595057456987915 | -0.1643823708044932 | -| 2023-01-01T00:01:00Z | -0.8866899175166036 | 0.1374669106634696 | -| 2023-01-01T00:02:00Z | -1.1707351469373848 | -0.5040127873371497 | -| 2023-01-01T00:03:00Z | -0.8312992026230288 | -0.07303821359711259 | -| 2023-01-01T00:04:00Z | -1.133689123470215 | | -| 2023-01-01T00:05:00Z | -1.0999060761389035 | 0.8347779302860662 | - -{{% /expand %}} - -{{% expand "Apply `ASIN()` to time windows (grouped by time)" %}} - -```sql -SELECT - ASIN(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | asin | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.44956365696339134 | -| 2023-01-01T00:10:00Z | 0.1289672974664895 | -| 2023-01-01T00:20:00Z | 0.030172738569652847 | -| 2023-01-01T00:30:00Z | 0.029291184938791334 | -| 2023-01-01T00:40:00Z | 0.022116148887608062 | -| 2023-01-01T00:50:00Z | 0.15593587473491674 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ATAN() - -Returns the arctangent (in radians) of the field value. - -```sql -ATAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ATAN()` to a field" %}} - -```sql -SELECT - a, - ATAN(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | atan | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.32692355076199897 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | -0.659300127490126 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | -0.7443170183837121 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | -0.6362993731936669 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | -0.7361091800814261 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | -0.727912249468035 | - -{{% /expand %}} - -{{% expand "Apply `ATAN()` to each field" %}} - -```sql -SELECT ATAN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan_a | atan_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.32692355076199897 | -0.1622053541422186 | -| 2023-01-01T00:01:00Z | -0.659300127490126 | 0.13618613793696105 | -| 2023-01-01T00:02:00Z | -0.7443170183837121 | -0.4499093121666581 | -| 2023-01-01T00:03:00Z | -0.6362993731936669 | -0.07284417510130452 | -| 2023-01-01T00:04:00Z | -0.7361091800814261 | 1.0585985450688151 | -| 2023-01-01T00:05:00Z | -0.727912249468035 | 0.6378113578294793 | - -{{% /expand %}} - -{{% expand "Apply `ATAN()` to time windows (grouped by time)" %}} - -```sql -SELECT - ATAN(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.4099506966510045 | -| 2023-01-01T00:10:00Z | 0.1279079463727065 | -| 2023-01-01T00:20:00Z | 0.030159013397288013 | -| 2023-01-01T00:30:00Z | 0.02927862748761639 | -| 2023-01-01T00:40:00Z | 0.022110742100818606 | -| 2023-01-01T00:50:00Z | 0.15407382461141705 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ATAN2() - -Returns the the arctangent of `y/x` in radians. - -```sql -ATAN2(expression_y, expression_x) -``` - -#### Arguments - -- **expression_y**: Expression to identify the `y` numeric value or one or more - fields to operate on. - Can be a number literal, [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **expression_x**: Expression to identify the `x` numeric value or one or more - fields to operate on. - Can be a number literal, [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ATAN2()` to a field divided by another field" %}} - -```sql -SELECT ATAN2(a, b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2 | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 2.0204217911794937 | -| 2023-01-01T00:01:00Z | -1.395783190047229 | -| 2023-01-01T00:02:00Z | -2.053731408859953 | -| 2023-01-01T00:03:00Z | -1.669248713922653 | -| 2023-01-01T00:04:00Z | -0.47112754043763505 | -| 2023-01-01T00:05:00Z | -0.8770454978291377 | - -{{% /expand %}} - -{{% expand "Apply `ATAN2()` to each field divided by a numeric value" %}} - -```sql -SELECT ATAN2(*, 2) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2_a | atan2_b | -| :------------------- | -------------------: | --------------------: | -| 2023-01-01T00:00:00Z | 0.16794843225523703 | -0.0816396675119722 | -| 2023-01-01T00:01:00Z | -0.36967737169970566 | 0.06841026268126137 | -| 2023-01-01T00:02:00Z | -0.4315666721698651 | -0.2369359777533473 | -| 2023-01-01T00:03:00Z | -0.35385538623378937 | -0.036470468100670846 | -| 2023-01-01T00:04:00Z | -0.4253376417906667 | 0.7268651162204586 | -| 2023-01-01T00:05:00Z | -0.41917415992493756 | 0.35488446257957357 | - -{{% /expand %}} - -{{% expand "Apply `ATAN2()` to time windows (grouped by time)" %}} - -```sql -SELECT - ATAN2(MEAN(a), MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2 | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | -1.278967897411707 | -| 2023-01-01T00:10:00Z | 2.3520553840586773 | -| 2023-01-01T00:20:00Z | 2.226497789888965 | -| 2023-01-01T00:30:00Z | 3.0977773783018656 | -| 2023-01-01T00:40:00Z | 2.9285769547942677 | -| 2023-01-01T00:50:00Z | 0.9505419744107901 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## CEIL() - -Returns the subsequent value rounded up to the nearest integer. - -```sql -CEIL(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `CEIL()` to a field" %}} - -```sql -SELECT - b, - CEIL(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | ceil | -| :------------------- | ------------------: | ---: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 1 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | - -{{% /expand %}} - -{{% expand "Apply `CEIL()` to each field" %}} - -```sql -SELECT CEIL(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ceil_a | ceil_b | -| :------------------- | -----: | -----: | -| 2023-01-01T00:00:00Z | 1 | -0 | -| 2023-01-01T00:01:00Z | -0 | 1 | -| 2023-01-01T00:02:00Z | -0 | -0 | -| 2023-01-01T00:03:00Z | -0 | -0 | -| 2023-01-01T00:04:00Z | -0 | 2 | -| 2023-01-01T00:05:00Z | -0 | 1 | - -{{% /expand %}} - -{{% expand "Apply `CEIL()` to time windows (grouped by time)" %}} - -```sql -SELECT - CEIL(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ceil | -| :------------------- | ---: | -| 2023-01-01T00:00:00Z | 1 | -| 2023-01-01T00:10:00Z | -0 | -| 2023-01-01T00:20:00Z | -0 | -| 2023-01-01T00:30:00Z | -0 | -| 2023-01-01T00:40:00Z | -0 | -| 2023-01-01T00:50:00Z | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## COS() - -Returns the cosine of the field value. - -```sql -COS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `COS()` to a field" %}} - -```sql -SELECT - b, - COS(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | cos | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | 0.9866403278718959 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.9906254752128878 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | 0.8856319645801471 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | 0.9973386305831397 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | -0.20628737691395405 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.7376943643170851 | - -{{% /expand %}} - -{{% expand "Apply `COS()` to each field" %}} - -```sql -SELECT COS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cos_a | cos_b | -| :------------------- | -----------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.9430573869206459 | 0.9866403278718959 | -| 2023-01-01T00:01:00Z | 0.7144321674550146 | 0.9906254752128878 | -| 2023-01-01T00:02:00Z | 0.6049946586273094 | 0.8856319645801471 | -| 2023-01-01T00:03:00Z | 0.7392720891861374 | 0.9973386305831397 | -| 2023-01-01T00:04:00Z | 0.616914561474936 | -0.20628737691395405 | -| 2023-01-01T00:05:00Z | 0.6285065034701617 | 0.7376943643170851 | - -{{% /expand %}} - -{{% expand "Apply `COS()` to time windows (grouped by time)" %}} - -```sql -SELECT - COS(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cos | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 0.9914907269510592 | -| 2023-01-01T00:10:00Z | 0.9918765457796455 | -| 2023-01-01T00:20:00Z | 0.9997307399250498 | -| 2023-01-01T00:30:00Z | 0.7850670342365872 | -| 2023-01-01T00:40:00Z | 0.9947779847618986 | -| 2023-01-01T00:50:00Z | 0.9938532355205111 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## CUMULATIVE_SUM() - -Returns the running total of subsequent [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -CUMULATIVE_SUM(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `CUMULATIVE_SUM()` to a field" %}} - -```sql -SELECT CUMULATIVE_SUM(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to each field" %}} - -```sql -SELECT CUMULATIVE_SUM(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum_a | cumulative_sum_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to field keys that match a regular expression" %}} - -```sql -SELECT CUMULATIVE_SUM(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum_a | cumulative_sum_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to time windows (grouped by time)" %}} - -```sql -SELECT - CUMULATIVE_SUM(SUM(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 1.3054783385851743 | -| 2023-01-01T00:10:00Z | 0.029980276948385454 | -| 2023-01-01T00:20:00Z | -0.20208529969578404 | -| 2023-01-01T00:30:00Z | -6.882005145666267 | -| 2023-01-01T00:40:00Z | -7.904410787756402 | -| 2023-01-01T00:50:00Z | -6.795080184131271 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DERIVATIVE() - -Returns the rate of change between subsequent [field values](/influxdb/cloud-serverless/reference/glossary/#field-value) -per `unit`. - -```sql -SELECT DERIVATIVE(field_expression[, unit]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **unit**: Unit of time to use to calculate the rate of change. - Supports [duration literals](/influxdb/cloud-serverless/reference/influxql/#durations). - _Default is `1s` (per second)_. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `DERIVATIVE()` to a field to calculate the per second change" %}} - -```sql -SELECT DERIVATIVE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | --------------------: | -| 2023-01-01T00:01:00Z | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to a field to calculate the per 5 minute change" %}} - -```sql -SELECT DERIVATIVE(b, 5m) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | ------------------: | -| 2023-01-01T00:01:00Z | 1.5033871148979698 | -| 2023-01-01T00:02:00Z | -3.0998879271912148 | -| 2023-01-01T00:03:00Z | 2.0498496425431316 | -| 2023-01-01T00:04:00Z | 9.257744100370537 | -| 2023-01-01T00:05:00Z | -5.187140409921009 | -| 2023-01-01T00:06:00Z | -2.26736721151909 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to each field" %}} - -```sql -SELECT DERIVATIVE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative_a | derivative_b | -| :------------------- | ---------------------: | --------------------: | -| 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to field keys that match a regular expression" %}} - -```sql -SELECT DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative_a | derivative_b | -| :------------------- | ---------------------: | --------------------: | -| 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to time windows (grouped by time)" %}} - -```sql -SELECT - DERIVATIVE(MEAN(b), 1m) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | --------------------: | -| 2023-01-01T00:10:00Z | -0.025809764002219633 | -| 2023-01-01T00:20:00Z | 0.010434324849926194 | -| 2023-01-01T00:30:00Z | -0.06447854269326314 | -| 2023-01-01T00:40:00Z | 0.05657514203880348 | -| 2023-01-01T00:50:00Z | 0.021317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DIFFERENCE() - -Returns the result of subtraction between subsequent [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -DIFFERENCE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [NON_NEGATIVE_DIFFERENCE()](#non_negative_difference) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `DIFFERENCE()` to a field" %}} - -```sql -SELECT DIFFERENCE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference | -| :------------------- | -------------------: | -| 2023-01-01T00:01:00Z | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to each field" %}} - -```sql -SELECT DIFFERENCE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference_a | difference_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to field keys that match a regular expression" %}} - -```sql -SELECT DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference_a | difference_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to time windows (grouped by time)" %}} - -```sql -SELECT - DIFFERENCE(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference | -| :------------------- | ------------------: | -| 2023-01-01T00:10:00Z | -0.2580976400221963 | -| 2023-01-01T00:20:00Z | 0.10434324849926194 | -| 2023-01-01T00:30:00Z | -0.6447854269326314 | -| 2023-01-01T00:40:00Z | 0.5657514203880348 | -| 2023-01-01T00:50:00Z | 0.21317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ELAPSED() - -Returns the difference between subsequent [field value's](/influxdb/cloud-serverless/reference/glossary/#field-value) -timestamps in a specified `unit` of time. - -```sql -ELAPSED(field_expression[, unit ]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. -- **unit**: Unit of time to return the elapsed time in. - Supports [duration literals](/influxdb/cloud-serverless/reference/influxql/#durations). - _Default is `1ns` (nanoseconds)_. - -#### Notable behaviors - -- If the `unit` is greater than the elapsed time between points, `ELAPSED()` - returns `0`. -- `ELAPSED()` supports the `GROUP BY time()` clause but the query results aren't very useful. - An `ELAPSED()` query with a nested function and a `GROUP BY time()` clause - returns the interval specified in the `GROUP BY time()` clause. - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ELAPSED()` to a field and return elapsed time in nanoseconds" %}} - -```sql -SELECT ELAPSED(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed | -| :------------------- | ----------: | -| 2023-01-01T00:01:00Z | 60000000000 | -| 2023-01-01T00:02:00Z | 60000000000 | -| 2023-01-01T00:03:00Z | 60000000000 | -| 2023-01-01T00:04:00Z | 60000000000 | -| 2023-01-01T00:05:00Z | 60000000000 | -| 2023-01-01T00:06:00Z | 60000000000 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to a field and return elapsed time in seconds" %}} - -```sql -SELECT ELAPSED(b, 1s) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed | -| :------------------- | ------: | -| 2023-01-01T00:01:00Z | 60 | -| 2023-01-01T00:02:00Z | 60 | -| 2023-01-01T00:03:00Z | 60 | -| 2023-01-01T00:04:00Z | 60 | -| 2023-01-01T00:05:00Z | 60 | -| 2023-01-01T00:06:00Z | 60 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to each field" %}} - -```sql -SELECT ELAPSED(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed_a | elapsed_b | -| :------------------- | ----------: | ----------: | -| 2023-01-01T00:01:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:02:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:03:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:04:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:05:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:06:00Z | 60000000000 | 60000000000 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to field keys that match a regular expression" %}} - -```sql -SELECT ELAPSED(/[ab]/, 1s) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed_a | elapsed_b | -| :------------------- | --------: | --------: | -| 2023-01-01T00:01:00Z | 60 | 60 | -| 2023-01-01T00:02:00Z | 60 | 60 | -| 2023-01-01T00:03:00Z | 60 | 60 | -| 2023-01-01T00:04:00Z | 60 | 60 | -| 2023-01-01T00:05:00Z | 60 | 60 | -| 2023-01-01T00:06:00Z | 60 | 60 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## EXP() - -Returns the exponential of the field value. - -```sql -EXP(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `EXP()` to a field" %}} - -```sql -SELECT - a, - EXP(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | exp | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 1.4036711951820788 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 0.460711111517308 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 0.39810592427186076 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 0.4776831901055915 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 0.40414561525252984 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 0.4101777188333968 | - -{{% /expand %}} - -{{% expand "Apply `EXP()` to each field" %}} - -```sql -SELECT EXP(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | exp_a | exp_b | -| :------------------- | ------------------: | -----------------: | -| 2023-01-01T00:00:00Z | 1.4036711951820788 | 0.8490450268435884 | -| 2023-01-01T00:01:00Z | 0.460711111517308 | 1.14686755886191 | -| 2023-01-01T00:02:00Z | 0.39810592427186076 | 0.6169648527893578 | -| 2023-01-01T00:03:00Z | 0.4776831901055915 | 0.929625657322271 | -| 2023-01-01T00:04:00Z | 0.40414561525252984 | 5.921415512753404 | -| 2023-01-01T00:05:00Z | 0.4101777188333968 | 2.09834186598405 | - -{{% /expand %}} - -{{% expand "Apply `EXP()` to time windows (grouped by time)" %}} - -```sql -SELECT - EXP(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | exp | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 0.6475413743155294 | -| 2023-01-01T00:10:00Z | 1.137246608416461 | -| 2023-01-01T00:20:00Z | 1.030627830373793 | -| 2023-01-01T00:30:00Z | 1.029720078241656 | -| 2023-01-01T00:40:00Z | 1.0223606806499268 | -| 2023-01-01T00:50:00Z | 1.1680137850180072 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FLOOR() - -Returns the subsequent value rounded down to the nearest integer. - -```sql -FLOOR(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `FLOOR()` to a field" %}} - -```sql -SELECT - b, - FLOOR(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | floor | -| :------------------- | ------------------: | ----: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -1 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -1 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -1 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 1 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0 | - -{{% /expand %}} - -{{% expand "Apply `FLOOR()` to each field" %}} - -```sql -SELECT FLOOR(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | floor_a | floor_b | -| :------------------- | ------: | ------: | -| 2023-01-01T00:00:00Z | 0 | -1 | -| 2023-01-01T00:01:00Z | -1 | 0 | -| 2023-01-01T00:02:00Z | -1 | -1 | -| 2023-01-01T00:03:00Z | -1 | -1 | -| 2023-01-01T00:04:00Z | -1 | 1 | -| 2023-01-01T00:05:00Z | -1 | 0 | - -{{% /expand %}} - -{{% expand "Apply `FLOOR()` to time windows (grouped by time)" %}} - -```sql -SELECT - FLOOR(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | floor | -| :------------------- | ----: | -| 2023-01-01T00:00:00Z | -5 | -| 2023-01-01T00:10:00Z | 1 | -| 2023-01-01T00:20:00Z | 0 | -| 2023-01-01T00:30:00Z | 0 | -| 2023-01-01T00:40:00Z | 0 | -| 2023-01-01T00:50:00Z | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LN() - -Returns the natural logarithm of the field value. -Field values must be greater than or equal to 0. - -```sql -LN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LN()` to a field" %}} - -```sql -SELECT - b, - LN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | ln | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -1.98752355209665 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5758127783016702 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2995556920844895 | - -{{% /expand %}} - -{{% expand "Apply `LN()` to each field" %}} - -```sql -SELECT LN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ln_a | ln_b | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -1.0814865153308908 | | -| 2023-01-01T00:01:00Z | | -1.98752355209665 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.5758127783016702 | -| 2023-01-01T00:05:00Z | | -0.2995556920844895 | - -{{% /expand %}} - -{{% expand "Apply `LN()` to time windows (grouped by time)" %}} - -```sql -SELECT - LN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ln | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.25161504572793725 | -| 2023-01-01T00:20:00Z | -1.1983831026157092 | -| 2023-01-01T00:30:00Z | -1.2280265702380913 | -| 2023-01-01T00:40:00Z | -1.5089436474159283 | -| 2023-01-01T00:50:00Z | 0.4402187212890264 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG() - -Returns the logarithm of the field value with base `b`. -Field values must be greater than or equal to 0. - -```sql -LOG(field_expression, b) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **b**: Logarithm base to use in the operation. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG()` to a field with a base of 3" %}} - -```sql -SELECT - b, - LOG(b, 3) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -1.8091219009630797 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5241273780031629 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2726673414946528 | - -{{% /expand %}} - -{{% expand "Apply `LOG()` to each field with a base of 5" %}} - -```sql -SELECT LOG(*, 5) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log_a | log_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.6719653532302217 | | -| 2023-01-01T00:01:00Z | | -1.2349178161776593 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.3577725949246566 | -| 2023-01-01T00:05:00Z | | -0.18612441633827553 | - -{{% /expand %}} - -{{% expand "Apply `LOG()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG(SUM(a), 10) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.10927502592347751 | -| 2023-01-01T00:20:00Z | -0.5204511686721008 | -| 2023-01-01T00:30:00Z | -0.5333251630849791 | -| 2023-01-01T00:40:00Z | -0.6553258995757036 | -| 2023-01-01T00:50:00Z | 0.1911845614863297 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG2() - -Returns the logarithm of the field value to the base 2. -Field values must be greater than or equal to 0. - -```sql -LOG2(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG2()` to a field" %}} - -```sql -SELECT - b, - LOG2(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log2 | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -2.8673903722598544 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.8307222397363156 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.4321675114403543 | - -{{% /expand %}} - -{{% expand "Apply `LOG2()` to each field" %}} - -```sql -SELECT LOG2(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log2_a | log2_b | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | -1.560255232456162 | | -| 2023-01-01T00:01:00Z | | -2.8673903722598544 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.8307222397363156 | -| 2023-01-01T00:05:00Z | | -0.4321675114403543 | - -{{% /expand %}} - -{{% expand "Apply `LOG2()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG2(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log2 | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.36300377868474476 | -| 2023-01-01T00:20:00Z | -1.7289013592288134 | -| 2023-01-01T00:30:00Z | -1.7716678429623767 | -| 2023-01-01T00:40:00Z | -2.1769455171078644 | -| 2023-01-01T00:50:00Z | 0.6351013661101591 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG10() - -Returns the logarithm of the field value to the base 10. -Field values must be greater than or equal to 0. - -```sql -LOG10(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG10()` to a field" %}} - -```sql -SELECT - b, - LOG10(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log10 | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -0.8631705113283253 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.25007231222579585 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.1300953840950034 | - -{{% /expand %}} - -{{% expand "Apply `LOG10()` to each field" %}} - -```sql -SELECT LOG10(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log10_a | log10_b | -| :------------------- | -------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.46968362586098245 | | -| 2023-01-01T00:01:00Z | | -0.8631705113283253 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.25007231222579585 | -| 2023-01-01T00:05:00Z | | -0.1300953840950034 | - -{{% /expand %}} - -{{% expand "Apply `LOG10()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG10(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log10 | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.10927502592347751 | -| 2023-01-01T00:20:00Z | -0.520451168672101 | -| 2023-01-01T00:30:00Z | -0.5333251630849791 | -| 2023-01-01T00:40:00Z | -0.6553258995757036 | -| 2023-01-01T00:50:00Z | 0.19118456148632973 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MOVING_AVERAGE() - -Returns the rolling average across a window of subsequent [field values](/influxdb/cloud-serverless/reference/glossary/#field-value). - -```sql -MOVING_AVERAGE(field_expression, N) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. -- **N**: Number of field values to use when calculating the moving average. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `MOVING_AVERAGE()` to a field" %}} - -```sql -SELECT MOVING_AVERAGE(a, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average | -| :------------------- | ------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to each field" %}} - -```sql -SELECT MOVING_AVERAGE(*, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average_a | moving_average_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to field keys that match a regular expression" %}} - -```sql -SELECT MOVING_AVERAGE(/[ab]/, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average_a | moving_average_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to time windows (grouped by time)" %}} - -```sql -SELECT - MOVING_AVERAGE(SUM(a), 3) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average | -| :------------------- | ------------------: | -| 2023-01-01T00:20:00Z | -0.9193144769987766 | -| 2023-01-01T00:30:00Z | 0.626884141339178 | -| 2023-01-01T00:40:00Z | 0.27189834404638374 | -| 2023-01-01T00:50:00Z | 0.6890200973149928 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## NON_NEGATIVE_DERIVATIVE() - -Returns only non-negative rate of change between subsequent -[field values](/influxdb/cloud-serverless/reference/glossary/#field-value). -Negative rates of change return _null_. - -```sql -NON_NEGATIVE_DERIVATIVE(field_expression[, unit]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **unit**: Unit of time to use to calculate the rate of change. - Supports [duration literals](/influxdb/cloud-serverless/reference/influxql/#durations). - _Default is `1s` (per second)_. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [DERIVATIVE()](#derivative) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per second change" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | 0.03085914700123513 | -| 2023-01-01T00:08:00Z | 0.0227877053636946 | -| 2023-01-01T00:10:00Z | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | 0.014999637478226817 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per 5 minute change" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(b, 5m) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 1.5033871148979698 | -| 2023-01-01T00:03:00Z | 2.0498496425431316 | -| 2023-01-01T00:04:00Z | 9.257744100370537 | -| 2023-01-01T00:08:00Z | 6.836311609108379 | -| 2023-01-01T00:10:00Z | 0.5028191431616502 | -| 2023-01-01T00:11:00Z | 4.499891243468045 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to each field" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative_a | non_negative_derivative_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | | -| 2023-01-01T00:08:00Z | | 0.0227877053636946 | -| 2023-01-01T00:09:00Z | 0.018437240876186967 | | -| 2023-01-01T00:10:00Z | | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | | 0.014999637478226817 | -| 2023-01-01T00:13:00Z | 0.006694752202850366 | | -| 2023-01-01T00:14:00Z | 0.011836797386191167 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to field keys that match a regular expression" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative_a | non_negative_derivative_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | | -| 2023-01-01T00:08:00Z | | 0.0227877053636946 | -| 2023-01-01T00:09:00Z | 0.018437240876186967 | | -| 2023-01-01T00:10:00Z | | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | | 0.014999637478226817 | -| 2023-01-01T00:13:00Z | 0.006694752202850366 | | -| 2023-01-01T00:14:00Z | 0.011836797386191167 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to time windows (grouped by time)" %}} - -```sql -SELECT - NON_NEGATIVE_DERIVATIVE(MEAN(b), 1m) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:20:00Z | 0.010434324849926194 | -| 2023-01-01T00:40:00Z | 0.05657514203880348 | -| 2023-01-01T00:50:00Z | 0.021317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## NON_NEGATIVE_DIFFERENCE() - -Returns only non-negative result of subtraction between subsequent -[field values](/influxdb/cloud-serverless/reference/glossary/#field-value). -Negative differences return _null_. - -```sql -NON_NEGATIVE_DIFFERENCE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [DIFFERENCE()](#difference) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to a field" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | 1.8515488200741077 | -| 2023-01-01T00:08:00Z | 1.367262321821676 | -| 2023-01-01T00:10:00Z | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | 0.899978248693609 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to each field" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference_a | non_negative_difference_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | | -| 2023-01-01T00:06:00Z | 1.002297066299117 | | -| 2023-01-01T00:08:00Z | | 1.367262321821676 | -| 2023-01-01T00:09:00Z | 1.106234452571218 | | -| 2023-01-01T00:10:00Z | | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | | 0.899978248693609 | -| 2023-01-01T00:13:00Z | 0.401685132171022 | | -| 2023-01-01T00:14:00Z | 0.71020784317147 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to field keys that match a regular expression" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference_a | non_negative_difference_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | | -| 2023-01-01T00:06:00Z | 1.002297066299117 | | -| 2023-01-01T00:08:00Z | | 1.367262321821676 | -| 2023-01-01T00:09:00Z | 1.106234452571218 | | -| 2023-01-01T00:10:00Z | | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | | 0.899978248693609 | -| 2023-01-01T00:13:00Z | 0.401685132171022 | | -| 2023-01-01T00:14:00Z | 0.71020784317147 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to time windows (grouped by time)" %}} - -```sql -SELECT - NON_NEGATIVE_DIFFERENCE(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference | -| :------------------- | ----------------------: | -| 2023-01-01T00:20:00Z | 0.10434324849926194 | -| 2023-01-01T00:40:00Z | 0.5657514203880348 | -| 2023-01-01T00:50:00Z | 0.21317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## POW() - -Returns the field value to the power of `x`. - -```sql -POW(field_expression, x) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **x**: Power to raise to. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `POW()` to a field with a power of 3" %}} - -```sql -SELECT - b, - POW(b, 3) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | pow | -| :------------------- | ------------------: | ---------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.004382205777325515 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.002573288422171338 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.1126388541916811 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0003885901893904874 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 5.626222933751733 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.4071119474284653 | - -{{% /expand %}} - -{{% expand "Apply `POW()` to each field with a power of 5" %}} - -```sql -SELECT POW(*, 5) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | pow_a | pow_b | -| :------------------- | -------------------: | -----------------------: | -| 2023-01-01T00:00:00Z | 0.004483135555212479 | -0.00011735131084020357 | -| 2023-01-01T00:01:00Z | -0.2795528536239978 | 0.000048322282876973225 | -| 2023-01-01T00:02:00Z | -0.6628050073932118 | -0.026271227986693114 | -| 2023-01-01T00:03:00Z | -0.22011853819169455 | -0.000002069282189962477 | -| 2023-01-01T00:04:00Z | -0.6103699296012646 | 17.797604890097084 | -| 2023-01-01T00:05:00Z | -0.5620694808926487 | 0.22362640363833164 | - -{{% /expand %}} - -{{% expand "Apply `POW()` to time windows (grouped by time)" %}} - -```sql -SELECT - POW(SUM(a), 10) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | pow | -| :------------------- | -----------------------: | -| 2023-01-01T00:00:00Z | 2402278.159218532 | -| 2023-01-01T00:10:00Z | 12.380844221267186 | -| 2023-01-01T00:20:00Z | 0.000006244365466732681 | -| 2023-01-01T00:30:00Z | 0.0000046424621235691315 | -| 2023-01-01T00:40:00Z | 2.7973126174031977e-7 | -| 2023-01-01T00:50:00Z | 81.6292140233699 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ROUND() - -Returns a field value rounded to the nearest integer. - -```sql -ROUND(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ROUND()` to a field" %}} - -```sql -SELECT - b, - ROUND(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | round | -| :------------------- | ------------------: | ----: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | - -{{% /expand %}} - -{{% expand "Apply `ROUND()` to each field" %}} - -```sql -SELECT ROUND(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | round_a | round_b | -| :------------------- | ------: | ------: | -| 2023-01-01T00:00:00Z | 0 | -0 | -| 2023-01-01T00:01:00Z | -1 | 0 | -| 2023-01-01T00:02:00Z | -1 | -0 | -| 2023-01-01T00:03:00Z | -1 | -0 | -| 2023-01-01T00:04:00Z | -1 | 2 | -| 2023-01-01T00:05:00Z | -1 | 1 | - -{{% /expand %}} - -{{% expand "Apply `ROUND()` to time windows (grouped by time)" %}} - -```sql -SELECT - ROUND(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | round | -| :------------------- | ----: | -| 2023-01-01T00:00:00Z | -4 | -| 2023-01-01T00:10:00Z | 1 | -| 2023-01-01T00:20:00Z | 0 | -| 2023-01-01T00:30:00Z | 0 | -| 2023-01-01T00:40:00Z | 0 | -| 2023-01-01T00:50:00Z | 2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SIN() - -Returns the sine of a field value. - -```sql -SIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `SIN()` to a field" %}} - -```sql -SELECT - b, - SIN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | sin | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.1629136686003898 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13660588515594851 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.4643877941052164 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0729085450859347 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.9784914502058565 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.6751348197618099 | - -{{% /expand %}} - -{{% expand "Apply `SIN()` to each field" %}} - -```sql -SELECT SIN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sin_a | sin_b | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.3326300722640741 | -0.1629136686003898 | -| 2023-01-01T00:01:00Z | -0.6997047077914582 | 0.13660588515594851 | -| 2023-01-01T00:02:00Z | -0.7962295291135749 | -0.4643877941052164 | -| 2023-01-01T00:03:00Z | -0.673406844448706 | -0.0729085450859347 | -| 2023-01-01T00:04:00Z | -0.7870301289278495 | 0.9784914502058565 | -| 2023-01-01T00:05:00Z | -0.7778043295686337 | 0.6751348197618099 | - -{{% /expand %}} - -{{% expand "Apply `SIN()` to time windows (grouped by time)" %}} - -```sql -SELECT - SIN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sin | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | 0.933528830283535 | -| 2023-01-01T00:10:00Z | 0.9597472276784815 | -| 2023-01-01T00:20:00Z | 0.29712628761434723 | -| 2023-01-01T00:30:00Z | 0.2887011711003489 | -| 2023-01-01T00:40:00Z | 0.21934537994884437 | -| 2023-01-01T00:50:00Z | 0.9998424824522808 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SQRT() - -Returns the square root of a field value. -Field values must be greater than or equal to 0. -Negative field values return null. - -```sql -SQRT(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `SQRT()` to a field" %}} - -```sql -SELECT - b, - SQRT(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | sqrt | -| :------------------- | ------------------: | -----------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.370181528515334 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 1.3336324558132349 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.860899207349059 | - -{{% /expand %}} - -{{% expand "Apply `SQRT()` to each field" %}} - -```sql -SELECT SQRT(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sqrt_a | sqrt_b | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.5823152811928947 | | -| 2023-01-01T00:01:00Z | | 0.370181528515334 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 1.3336324558132349 | -| 2023-01-01T00:05:00Z | | 0.860899207349059 | - -{{% /expand %}} - -{{% expand "Apply `SQRT()` to time windows (grouped by time)" %}} - -```sql -SELECT - SQRT(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sqrt | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 1.134063865909604 | -| 2023-01-01T00:20:00Z | 0.5492555015405052 | -| 2023-01-01T00:30:00Z | 0.5411746169982342 | -| 2023-01-01T00:40:00Z | 0.4702589287652642 | -| 2023-01-01T00:50:00Z | 1.2462130097934059 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## TAN() - -Returns the tangent of the field value. - -```sql -TAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `TAN()` to a field" %}} - -```sql -SELECT - b, - TAN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | tan | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.16511961248511045 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13789861917955581 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.5243575352718546 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.07310309943905952 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | -4.743341375725582 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.9151958486043346 | - -{{% /expand %}} - -{{% expand "Apply `TAN()` to each field" %}} - -```sql -SELECT TAN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | tan_a | tan_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.3527145610408791 | -0.16511961248511045 | -| 2023-01-01T00:01:00Z | -0.9793857830953787 | 0.13789861917955581 | -| 2023-01-01T00:02:00Z | -1.3160934857179802 | -0.5243575352718546 | -| 2023-01-01T00:03:00Z | -0.9109052733075013 | -0.07310309943905952 | -| 2023-01-01T00:04:00Z | -1.2757522322802637 | -4.743341375725582 | -| 2023-01-01T00:05:00Z | -1.2375438046768912 | 0.9151958486043346 | - -{{% /expand %}} - -{{% expand "Apply `TAN()` to time windows (grouped by time)" %}} - -```sql -SELECT - TAN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | tan | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | -2.603968631156288 | -| 2023-01-01T00:10:00Z | 3.4171098358131733 | -| 2023-01-01T00:20:00Z | 0.31117972731464494 | -| 2023-01-01T00:30:00Z | 0.30154101138968664 | -| 2023-01-01T00:40:00Z | 0.22482036866737865 | -| 2023-01-01T00:50:00Z | 56.3338223288096 | - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/reference/influxql/group-by.md b/content/influxdb/cloud-serverless/reference/influxql/group-by.md index 9c8c809c2..489fd4903 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/group-by.md +++ b/content/influxdb/cloud-serverless/reference/influxql/group-by.md @@ -13,632 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_expression_n] ``` + +source: /shared/influxql-v3-reference/group-by.md --- - -Use the `GROUP BY` clause to group data by one or more specified -[tags](/influxdb/cloud-serverless/reference/glossary/#tag) or into specified time intervals. -`GROUP BY` requires an [aggregate](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/) -or [selector](/influxdb/cloud-serverless/reference/influxql/functions/selectors/) -function in the `SELECT` statement. - - - -- [Syntax](#syntax) -- [GROUP BY clause behaviors](#group-by-clause-behaviors) -- [Group by tags](#group-by-tags) - - [GROUP BY tags examples](#group-by-tags-examples) -- [GROUP BY time](#group-by-time) - - [GROUP by time and fill gaps](#group-by-time-and-fill-gaps) - - [GROUP BY time examples](#group-by-time-examples) - - [GROUP BY time with offset](#group-by-time-with-offset) - - [GROUP BY time and fill gaps](#group-by-time-and-fill-gaps) -- [Result set](#result-set) - - [Default time range](#default-time-range) -- [Notable behaviors of the GROUP BY clause](#notable-behaviors-of-the-group-by-clause) - - [Cannot group by fields](#cannot-group-by-fields) - - [Tag order does not matter](#tag-order-does-not-matter) - - [Grouping by tag and no time range returns unexpected timestamps](#grouping-by-tag-and-no-time-range-returns-unexpected-timestamps) - - [Data grouped by time may return unexpected timestamps](#data-grouped-by-time-may-return-unexpected-timestamps) - - [Example data](#example-data) - - [Query results](#query-results) - - [Fill with no data in the queried time range](#fill-with-no-data-in-the-queried-time-range) - - [Fill with previous if no previous value exists](#fill-with-previous-if-no-previous-value-exists) - - [Fill with linear interpolation if there are not two values to interpolate between](#fill-with-linear-interpolation-if-there-are-not-two-values-to-interpolate-between) - - - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_expression_n] -``` - -- **group_expression**: Expression to identify tags or time intervals to group by. - Can be a [tag key](/influxdb/cloud-serverless/reference/glossary/#tag-key), - constant, [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/), - wildcard (`*`), or [function expression](/influxdb/cloud-serverless/reference/influxql/functions/). - -## GROUP BY clause behaviors - -- `GROUP BY tag_key` - Groups data by a specific tag -- `GROUP BY tag_key1, tag_key2` - Groups data by more than one tag -- `GROUP BY *` - Groups data by all [tags](/influxdb/cloud-serverless/reference/glossary/#tag) -- `GROUP BY /regex/` - Groups data by tag keys that match the regular expression -- `GROUP BY time()` - Groups data into time intervals (windows) - -{{% note %}} -If a query includes `WHERE` and `GROUP BY`, the `GROUP BY` clause must appear after -the `WHERE` clause. -{{% /note %}} - -## GROUP BY tags - -Groups data by one or more tag columns. - -### GROUP BY tags examples - -The following examples use the -[Bitcoin price sample data](/influxdb/cloud-serverless/reference/sample-data/#bitcoin-price-data). - -{{< expand-wrapper >}} - -{{% expand "Group data by a single tag" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY code -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by more than one tag" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY code, description -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, description=Euro -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, description=British Pound Sterling -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, description=United States Dollar -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by all tags" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY * -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, crypto=bitcoin, description=Euro, symbol=€ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, crypto=bitcoin, description=British Pound Sterling, symbol=£ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, crypto=bitcoin, description=United States Dollar, symbol=$ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by tag keys that match a regular expression" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY /^[cd]/ -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, crypto=bitcoin, description=Euro -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, crypto=bitcoin, description=British Pound Sterling -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, crypto=bitcoin, description=United States Dollar -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{< /expand-wrapper >}} - -## GROUP BY time - -`GROUP BY time()` groups data by into specified time intervals, also known as "windows", -and applies the [aggregate](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/) -and [selector](/influxdb/cloud-serverless/reference/influxql/functions/selectors/) -functions in the `SELECT` clause to each interval. -Use the [`time()` function](/influxdb/cloud-serverless/reference/influxql/functions/date-time/#time) -to specify the time interval to group by. - -```sql -SELECT_clause FROM_clause WHERE GROUP BY time(time_interval[, offset])[, group_expression (...)] [fill(behavior)] -``` - -`GROUP BY time()` intervals use preset round-number time boundaries that -are independent of time conditions in the [`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/). -**Output data uses window start boundaries as the aggregate timestamps.** -Use the `offset` argument of the `time()` function to shift time boundaries forward or -backward in time. - -### GROUP by time and fill gaps - -When grouping by time, if a window in the queried time range does not contain data, -results return a row for the empty window containing the timestamp of the empty -window and _null_ values for each queried field. -Use the [`fill()` function](/influxdb/cloud-serverless/reference/influxql/functions/misc/#fill) -_at the end of the `GROUP BY` clause_ to replace _null_ field values. -If no `FILL` clause is included, the default behavior is `fill(null)`. - -`fill()` provides the following behaviors for filling values: - -- **numeric literal**: Replaces null values with the specified numeric literal. -- **linear**: Uses linear interpolation between existing values to replace null values. -- **none**: Removes rows with null field values. -- **null**: Keeps null values and associated timestamps. -- **previous**: Replaces null values with the most recent non-null value. - -_See the [`fill()` documentation](/influxdb/cloud-serverless/reference/influxql/functions/misc/#fill) -for detailed examples._ - -### GROUP BY time examples - -The following examples use the -[Bitcoin price sample data](/influxdb/cloud-serverless/reference/sample-data/#bitcoin-price-data). - -{{< expand-wrapper >}} - -{{% expand "Group and aggregate query results into 1 hour windows" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(1h) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-05-01T00:00:00Z | 24494.27265 | -| 2023-05-01T01:00:00Z | 24452.1698 | -| 2023-05-01T02:00:00Z | 23902.666124999996 | -| 2023-05-01T03:00:00Z | 23875.211349999998 | -| 2023-05-01T04:00:00Z | 23855.6441 | -| ... | ... | - - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 1 week intervals by tag" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(1w), code -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 27681.21808576779 | -| 2023-05-04T00:00:00Z | 27829.413580354256 | -| 2023-05-11T00:00:00Z | 26210.24799033149 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 23744.083925842704 | -| 2023-05-04T00:00:00Z | 23871.201395652173 | -| 2023-05-11T00:00:00Z | 22482.33174723755 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 28415.88231123595 | -| 2023-05-04T00:00:00Z | 28568.010941384844 | -| 2023-05-11T00:00:00Z | 26905.87242099449 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -###### GROUP BY time with offset - -{{< expand-wrapper >}} -{{% expand "Group and aggregate query results into 1 hour intervals and offset time boundaries by +15 minutes" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-02T00:00:00Z' -GROUP BY time(1h, 15m) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-30T23:15:00Z | | -| 2023-05-01T00:15:00Z | 29313.6754 | -| 2023-05-01T01:15:00Z | 28932.0882 | -| 2023-05-01T02:15:00Z | 28596.375225000003 | -| 2023-05-01T03:15:00Z | 28578.915075 | -| ... | ... | - -_Note that `offset` forces the first time boundary to be outside -the queried time range so the query returns no results for that first interval._ - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 1 hour intervals and offset time boundaries by -15 minutes" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-02T00:00:00Z' -GROUP BY time(1h, -15m) -``` -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-30T23:45:00Z | 29319.9092 | -| 2023-05-01T00:45:00Z | 29285.3651 | -| 2023-05-01T01:45:00Z | 28607.202666666668 | -| 2023-05-01T02:45:00Z | 28576.056175 | -| 2023-05-01T03:45:00Z | 28566.96315 | -| ... | ... | - -{{% /expand %}} -{{< /expand-wrapper >}} - -###### GROUP BY time and fill gaps - -{{< expand-wrapper >}} -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps with `0`" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(0) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 0 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps using linear interpolation" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(linear) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29285.3651 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps with previous values" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(previous) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{< /expand-wrapper >}} - -## Result set - -If at least one row satisfies the query, {{% product-name %}} returns row data in the query result set. -If a query uses a `GROUP BY` clause, the result set includes the following: - -- Columns listed in the query's `SELECT` clause -- A `time` column that contains the timestamp for the record or the group -- An `iox::measurement` column that contains the record's measurement (table) name -- Columns listed in the query's `GROUP BY` clause; each row in the result set contains the values used for grouping - -### Default time range - -If a query doesn't specify a time range in the -[`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/), InfluxDB uses the -[default time range](/influxdb/cloud-serverless/reference/influxql/#default-time-range) for filtering and grouping by time. -If a query includes the `GROUP BY` clause and doesn't specify a time range in the -`WHERE` clause, the default time group is the -[default time range](/influxdb/cloud-serverless/reference/influxql/#default-time-range), and the `time` column in the result set contains the start of the range--for example: - -```sql -SELECT mean(temp) FROM home GROUP BY room -``` - -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 22.623076923076926 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ----------------: | -| 1970-01-01T00:00:00Z | 22.16923076923077 | - -## Notable behaviors of the GROUP BY clause - -### Cannot group by fields - -InfluxQL does not support grouping data by **fields**. - -### Tag order does not matter - -The order that tags are listed in the `GROUP BY` clause does not affect how -data is grouped. - -### Grouping by tag and no time range returns unexpected timestamps - -The `time` column contains the start of the [default time range](#default-time-range). - -### Data grouped by time may return unexpected timestamps - -Because `GROUP BY time()` intervals use preset round-number time boundaries that -are independent of time conditions in the [`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/), -results may include timestamps outside of the queried time range. -Results represent only data with timestamps in the specified time range, but -output timestamps are determined by by the preset time boundaries. - -The following example groups data by 1-hour intervals, but the time range defined -in the `WHERE` clause covers only part of a window: - -```sql -SELECT MEAN(field) -FROM example -WHERE - time >= '2022-01-01T00:30:00Z' - AND time <= '2022-01-01T01:30:00Z' -GROUP BY time(1h) -``` - -{{% note %}} -**Note**: The timestamp in the first row of query results data occurs before the start of -the queried time range. -[See why](#why-do-these-results-include-timestamps-outside-of-the-queried-time-range). -{{% /note %}} - -{{% influxdb/custom-timestamps %}} -{{< flex >}} -{{% flex-content %}} -#### Example data - -| time | field | -| :------------------- | ----: | -| 2022-01-01T00:00:00Z | 8 | -| 2022-01-01T00:15:00Z | 4 | -| 2022-01-01T00:30:00Z | 0 | -| 2022-01-01T00:45:00Z | 8 | -| 2022-01-01T01:00:00Z | 5 | -| 2022-01-01T01:15:00Z | 0 | -| 2022-01-01T01:30:00Z | 8 | -| 2022-01-01T01:45:00Z | 8 | -| 2022-01-01T02:00:00Z | 9 | -| 2022-01-01T02:15:00Z | 6 | -| 2022-01-01T02:30:00Z | 3 | -| 2022-01-01T02:45:00Z | 0 | - -{{% /flex-content %}} -{{% flex-content %}} - -#### Query results - -| time | field | -| :------------------- | ----: | -| 2022-01-01T00:00:00Z | 4 | -| 2022-01-01T01:00:00Z | 5.25 | -| 2022-01-01T02:00:00Z | 6 | - -{{% /flex-content %}} -{{< /flex >}} -{{% /influxdb/custom-timestamps %}} - -{{< expand-wrapper >}} -{{% expand "Why do these results include timestamps outside of the queried time range?" %}} - -`GROUP BY time()` creates windows with predefined time boundaries based on the -specified interval. These boundaries are not determined by the queried time -range, however, aggregate values in query results are calculated using only -values that are in the queried time range. - -{{< html-diagram/influxql-windows >}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Fill with no data in the queried time range - -Queries ignore `fill()` if no data exists in the queried time range. -This is the expected behavior. - -### Fill with previous if no previous value exists - -`fill(previous)` doesn’t fill null values if there is no previous value in -the queried time range. - -### Fill with linear interpolation if there are not two values to interpolate between - -`fill(linear)` doesn't fill null values if there are no values before or after -the null value in the queried time range. diff --git a/content/influxdb/cloud-serverless/reference/influxql/internals.md b/content/influxdb/cloud-serverless/reference/influxql/internals.md index 7b0c460d0..c85ab6801 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/internals.md +++ b/content/influxdb/cloud-serverless/reference/influxql/internals.md @@ -6,159 +6,6 @@ menu: name: InfluxQL internals parent: influxql-reference weight: 219 + +source: /shared/influxql-v3-reference/internals.md --- - -Learn about the implementation of InfluxQL to understand how -results are processed and how to create efficient queries: - -- [Query life cycle](#query-life-cycle) -- [Understanding iterators](#understanding-iterators) -- [Cursors](#cursors) -- [Auxiliary fields](#auxiliary-fields) -- [Built-in iterators](#built-in-iterators) -- [Call iterators](#call-iterators) - -## Query life cycle - -1. InfluxQL query string is tokenized and then parsed into an abstract syntax - tree (AST). This is the code representation of the query itself. - -2. The AST is passed to the `QueryExecutor` which directs queries to the - appropriate handlers. For example, queries related to meta data are executed - by the **meta service** and `SELECT` statements are executed by the shards - themselves. - -3. The query engine then determines the shards that match the `SELECT` - statement's time range. From these shards, iterators are created for each - field in the statement. - -4. Iterators are passed to the emitter which drains them and joins the resulting - points. The emitter's job is to convert simple time/value points into the - more complex result objects that are returned to the client. - -### Understanding iterators - -Iterators provide a simple interface for looping over a set of points. -For example, this is an iterator over Float points: - -``` -type FloatIterator interface { - Next() *FloatPoint -} -``` - -These iterators are created through the `IteratorCreator` interface: - -``` -type IteratorCreator interface { - CreateIterator(opt *IteratorOptions) (Iterator, error) -} -``` - -The `IteratorOptions` provide arguments about field selection, time ranges, -and dimensions that the iterator creator can use when planning an iterator. -The `IteratorCreator` interface is used at many levels such as the `Shards`, -`Shard`, and `Engine`. This allows optimizations to be performed when applicable -such as returning a precomputed `COUNT()`. - -Iterators aren't just for reading raw data from storage, though. Iterators can be -composed so that they provide additional functionality around an input -iterator. For example, a `DistinctIterator` can compute the distinct values for -each time window for an input iterator. Or a `FillIterator` can generate -additional points that are missing from an input iterator. - -This composition also lends itself well to aggregation. -For example, in the following SQL, `MEAN(value)` is a `MeanIterator` that wraps an iterator from the -underlying shards: - -```sql -SELECT MEAN(value) FROM cpu GROUP BY time(10m) -``` - -The following example wraps `MEAN(value)` with an additional iterator (`DERIVATIVE()`) to determine -the derivative of the mean: - -```sql -SELECT DERIVATIVE(MEAN(value), 20m) FROM cpu GROUP BY time(10m) -``` - -### Cursors - -A **cursor** identifies data by shard in tuples (time, value) for a single series (measurement, tag set and field). The cursor traverses data stored as a log-structured merge-tree and handles deduplication across levels, tombstones for deleted data, and merging the cache (Write Ahead Log). A cursor sorts the `(time, value)` tuples by time in ascending or descending order. - -For example, a query that evaluates one field for 1,000 series over 3 shards constructs a minimum of 3,000 cursors (1,000 per shard). - -### Auxiliary fields - -Because InfluxQL allows users to use selector functions such as `FIRST()`, -`LAST()`, `MIN()`, and `MAX()`, the engine must provide a way to return related -data at the same time with the selected point. - -Let's look at the following query: - -```sql -SELECT FIRST(value), host FROM cpu GROUP BY time(1h) -``` - -We are selecting the first `value` that occurs every hour but we also want to -retrieve the `host` associated with that point. Since the `Point` types only -specify a single typed `Value` for efficiency, we push the `host` into the -auxiliary fields of the point. These auxiliary fields are attached to the point -until it is passed to the emitter where the fields get split off to their own -iterator. - -### Built-in iterators - -There are many helper iterators that let us build queries: - -* Merge Iterator - This iterator combines one or more iterators into a single - new iterator of the same type. This iterator guarantees that all points - within a window will be output before starting the next window, but does not - provide ordering guarantees within the window. This allows for fast access - for aggregate queries that don't need stronger sorting guarantees. - -* Sorted Merge Iterator - Like `MergeIterator`, this iterator combines one or more iterators - into a new iterator of the same type. However, this iterator guarantees - time ordering of every point. This makes it slower than the `MergeIterator` - but this ordering guarantee is required for non-aggregate queries which - return the raw data points. - -* Limit Iterator - This iterator limits the number of points per name or tag - group. This is the implementation of the `LIMIT` & `OFFSET` syntax. - -* Fill Iterator - This iterator injects extra points if they are missing from - the input iterator. It can provide `null` points, points with the previous - value, or points with a specific value. - -* Buffered Iterator - This iterator provides the ability to "unread" a point - back onto a buffer so it can be read again next time. This is used extensively - to provide lookahead for windowing. - -* Reduce Iterator - This iterator calls a reduction function for each point in - a window. When the window is complete, then all points for that window are - output. This is used for simple aggregate functions such as `COUNT()`. - -* Reduce Slice Iterator - This iterator collects all points for a window first, - and then passes them all to a reduction function at once. The results are - returned from the iterator. This is used for aggregate functions such as - `DERIVATIVE()`. - -* Transform Iterator - This iterator calls a transform function for each point - from an input iterator. This is used for executing binary expressions. - -* Dedupe Iterator - This iterator only outputs unique points. Because it is resource-intensive, this iterator is only used for small queries such as meta query statements. - -### Call iterators - -Function calls in InfluxQL are implemented at two levels: - -- Some calls can be -wrapped at multiple layers to improve efficiency. For example, a `COUNT()` can -be performed at the shard level and then multiple `CountIterator`s can be -wrapped with another `CountIterator` to compute the count of all shards. These -iterators can be created using `NewCallIterator()`. - -- Some iterators are more complex or need to be implemented at a higher level. -For example, the `DERIVATIVE()` function needs to retrieve all points for a window -before performing the calculation. This iterator is created by the engine itself -and is never requested to be created by the lower levels. diff --git a/content/influxdb/cloud-serverless/reference/influxql/limit-and-slimit.md b/content/influxdb/cloud-serverless/reference/influxql/limit-and-slimit.md index 331fc3d9e..db8ff2cea 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/limit-and-slimit.md +++ b/content/influxdb/cloud-serverless/reference/influxql/limit-and-slimit.md @@ -13,249 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT row_N SLIMIT series_N ``` + +source: /shared/influxql-v3-reference/limit-and-slimit.md --- - -Use `LIMIT` to limit the number of **rows** returned per InfluxQL group. -Use `SLIMIT` to limit the number of [series](/influxdb/cloud-serverless/reference/glossary/#series) -returned in query results. - -- [LIMIT clause](#limit-clause) - - [Syntax](#limit-syntax) - - [Examples](#limit-examples) -- [SLIMIT clause](#slimit-clause) - - - - - - -## LIMIT clause - -The `LIMIT` clause limits the number of rows to return from each InfluxQL group. -If the query doesn't include a [`GROUP BY` clause](/influxdb/cloud-serverless/reference/influxql/group-by/), -the entire result set is considered a single group. -If a query [groups data by time](/influxdb/cloud-serverless/reference/influxql/group-by/#group-by-time), -limits are applied after aggregate and selector operations are applied to each -time window. - -### Syntax {#limit-syntax} - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT N -``` - -#### Arguments - -- **N**: Maximum number of points to return from each InfluxQL group. - If `N` is greater than the number of points in a group, - all points from the group are returned. - -### Examples {#limit-examples} - -The following examples use the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Limit the number of rows returned" %}} - -```sql -SELECT * FROM home LIMIT 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Limit the number of rows returned from each InfluxQL group" %}} - -```sql -SELECT - MEAN(*) -FROM home -GROUP BY - time(2h), - room -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ------: | -------: | -----------------: | -| 2022-01-01T08:00:00Z | 0 | 36.05 | 22 | -| 2022-01-01T10:00:00Z | 0 | 36.05 | 22.549999999999997 | -| 2022-01-01T12:00:00Z | 0.5 | 36.25 | 22.65 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ------: | -------: | -----------------: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21.25 | -| 2022-01-01T10:00:00Z | 0 | 36 | 22 | -| 2022-01-01T12:00:00Z | 0 | 35.95 | 22.299999999999997 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## SLIMIT clause - -{{% warn %}} -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features, such as `SLIMIT` are still -being implemented. For more information, see -[InfluxQL feature support](/influxdb/cloud-serverless/reference/influxql/feature-support/). -{{% /warn %}} - - diff --git a/content/influxdb/cloud-serverless/reference/influxql/math-operators.md b/content/influxdb/cloud-serverless/reference/influxql/math-operators.md index fe4f485ac..6d72daf67 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/math-operators.md +++ b/content/influxdb/cloud-serverless/reference/influxql/math-operators.md @@ -9,273 +9,6 @@ menu: parent: influxql-reference identifier: influxql-mathematical-operators weight: 215 + +source: /shared/influxql-v3-reference/math-operators.md --- - -Use InfluxQL mathematical operators to perform mathematical operations in InfluxQL queries. -Mathematical operators follow the [standard order of operations](https://golang.org/ref/spec#Operator_precedence). -Parentheses take precedence to division and multiplication, which takes precedence to addition and subtraction. -For example `5 / 2 + 3 * 2 = (5 / 2) + (3 * 2)` and `5 + 2 * 3 - 2 = 5 + (2 * 3) - 2`. - -- [Addition](#addition) -- [Subtraction](#subtraction) -- [Multiplication](#multiplication) -- [Division](#division) -- [Modulo](#modulo) -- [Bitwise AND](#bitwise-and) -- [Bitwise OR](#bitwise-or) -- [Bitwise Exclusive-OR](#bitwise-exclusive-or) -- [Unsupported Operators](#unsupported-operators) -- [Notable behaviors of mathematical operators](#notable-behaviors-of-mathematical-operators) - -## Addition - -Add two numeric operands. Operands may be an identifier, constant, or literal -numeric value. - -```sql -SELECT A + 5 FROM example - -SELECT A + B FROM example - -SELECT * FROM example WHERE A + 5 > 10 - -SELECT * FROM example WHERE A + B > 10 -``` - -## Subtraction - -Subtract one numeric operand from another. Operands may be an identifier, -constant, or literal numeric value. - -```sql -SELECT 1 - A FROM example - -SELECT B - A FROM example - -SELECT * FROM example WHERE 1 - A <= 3 - -SELECT * FROM example WHERE B - A <= 3 -``` - -## Multiplication - -Multiply two numeric operands. Operands may be an identifier, constant, or literal -numeric value. - -```sql -SELECT A * 10 FROM example - -SELECT A * B FROM example - -SELECT * FROM example WHERE A * 10 >= 20 - -SELECT * FROM example WHERE A * B >= 20 -``` - -Multiplication distributes across other operators. - -```sql -SELECT 10 * (A + B + C) FROM example - -SELECT 10 * (A - B - C) FROM example - -SELECT 10 * (A + B - C) FROM example -``` - -## Division - -Divide one numeric operand by another. Operands may be an identifier, constant, -or literal numeric value. - -```sql -SELECT A / 10 FROM example - -SELECT A / B FROM example - -SELECT * FROM example WHERE A / 10 <= 2 - -SELECT * FROM example WHERE A / B <= 2 -``` - -Division distributes across other operators. - -```sql -SELECT 10 / (A + B + C) FROM example - -SELECT 10 / (A - B - C) FROM example - -SELECT 10 / (A + B - C) FROM example -``` - -## Modulo - -Perform a modulo operation with two numeric operands. Operands may be an -identifier, constant, or literal numeric value. - -```sql -SELECT A % 2 FROM example - -SELECT A % B FROM example - -SELECT A FROM example WHERE A % 2 = 0 - -SELECT A, B FROM example WHERE A % B = 0 -``` - -## Bitwise AND - -Perform a bitwise `AND` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A & 255 FROM example - -SELECT A & B FROM example - -SELECT (A ^ true) & B FROM example - -SELECT * FROM example WHERE A & 15 > 0 -``` - -## Bitwise OR - -Perform a bitwise `OR` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A | 5 FROM example - -SELECT A | B FROM example - -SELECT * FROM example WHERE "bitfield" | 12 = 12 -``` - -## Bitwise Exclusive-OR - -Perform a bitwise `Exclusive-OR` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A ^ 255 FROM example - -SELECT A ^ B FROM example - -SELECT * FROM example WHERE "bitfield" ^ 6 > 0 -``` - -## Unsupported Operators - -### Inequalities - -Using any of `=`,`!=`,`<`,`>`,`<=`,`>=`,`<>` in the `SELECT` statement yields -empty results for all types. -Comparison operators can only be used in the `WHERE` clause. - -### Logical Operators - -Using any of `!|`,`NAND`,`XOR`,`NOR` yield a parser error. - -Additionally using `AND`, `OR` in the `SELECT` clause of a query will not behave -as mathematical operators and simply yield empty results, as they are InfluxQL tokens. -However, you can apply the bitwise operators `&`, `|` and `^` to boolean values. - -### Bitwise Not - -There is no bitwise-not operator, because the results you expect depend on the width of your bitfield. -InfluxQL does not know how wide your bitfield is, so cannot implement a suitable -bitwise-not operator. - -For example, if your bitfield is 8 bits wide, then the integer 1 represents the bits `0000 0001`. -The bitwise-not of this should return the bits `1111 1110` (that is, the integer 254) -However, if your bitfield is 16 bits wide, then the integer 1 represents the bits `0000 0000 0000 0001`. -The bitwise-not of this should return the bits `1111 1111 1111 1110` (that is, the integer 65534) - -#### Solution - -You can implement a bitwise-not operation by using the `^` (bitwise xor) operator -together with the number representing all-ones for your word-width: - -For 8-bit data: - -```sql -SELECT A ^ 255 FROM example -``` - -For 16-bit data: - -```sql -SELECT A ^ 65535 FROM example -``` - -For 32-bit data: - -```sql -SELECT A ^ 4294967295 FROM example -``` - -In each case, the constant you need can be calculated as `(2 ** width) - 1`. - -## Notable behaviors of mathematical operators - -- [Mathematical operators with wildcards and regular expressions](#mathematical-operators-with-wildcards-and-regular-expressions) -- [Mathematical operators with functions](#mathematical-operators-with-functions) - -### Mathematical operators with wildcards and regular expressions - -InfluxQL does not support combining mathematical operations with a wildcard (`*`) -or [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/) -in the `SELECT` clause. -The following queries are invalid and the system returns an error: - -Perform a mathematical operation on a wildcard. - -```sql -SELECT * + 2 FROM "nope" --- ERR: unsupported expression with wildcard: * + 2 -``` - -Perform a mathematical operation on a wildcard within a function. - -```sql -SELECT COUNT(*) / 2 FROM "nope" --- ERR: unsupported expression with wildcard: count(*) / 2 -``` - -Perform a mathematical operation on a regular expression. - -```sql -SELECT /A/ + 2 FROM "nope" --- ERR: error parsing query: found +, expected FROM at line 1, char 12 -``` - -Perform a mathematical operation on a regular expression within a function. - -```sql -SELECT COUNT(/A/) + 2 FROM "nope" --- ERR: unsupported expression with regex field: count(/A/) + 2 -``` - -### Mathematical operators with functions - -InfluxQL does not support mathematical operators inside of function calls. -Note that InfluxQL only allows functions in the `SELECT` clause. - -For example, the following will work: - -```sql -SELECT 10 * mean("value") FROM "cpu" -``` - -However, the following query will return a parse error: - -```sql -SELECT mean(10 * "value") FROM "cpu" --- Error: expected field argument in mean() -``` - - diff --git a/content/influxdb/cloud-serverless/reference/influxql/offset-and-soffset.md b/content/influxdb/cloud-serverless/reference/influxql/offset-and-soffset.md index d2bbc7728..d99dbc08d 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/offset-and-soffset.md +++ b/content/influxdb/cloud-serverless/reference/influxql/offset-and-soffset.md @@ -14,236 +14,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] OFFSET row_N [SLIMIT_clause] SOFFSET series_N ``` + +source: /shared/influxql-v3-reference/offset-and-soffset.md --- - -Use `OFFSET` to specify the number of [rows](/influxdb/cloud-serverless/reference/glossary/#series) -to skip in each InfluxQL group before returning results. -Use `SOFFSET` to specify the number of [series](/influxdb/cloud-serverless/reference/glossary/#series) -to skip before returning results. - - - [OFFSET clause](#offset-clause) - - [Syntax](#offset-syntax) - - [Notable OFFSET clause behaviors](#notable-offset-clause-behaviors) - - [Examples](#offset-examples) - - [SOFFSET clause](#soffset-clause) - - - - -## `OFFSET` clause - -The `OFFSET` clause skips `N` rows in each InfluxQL group before returning results. -Offsets honor row limits specified in the -[`LIMIT` clause](/influxdb/cloud-serverless/reference/influxql/limit-and-slimit/#limit-clause) -and display the limited number of rows after the specified offset. -Use `LIMIT` and `OFFSET` together to paginate query results. - -### Syntax {#offset-syntax} - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] OFFSET N [SLIMIT_clause] [SOFFSET_clause] -``` - -#### Arguments - -- **N**: Number of rows to skip in each InfluxQL group before returning results. - -### Notable OFFSET clause behaviors - -- If there is no `LIMIT` clause in a query with an `OFFSET` clause, the query - returns a single row per InfluxQL group at the specified offset. -- If the query doesn't include a [`GROUP BY` clause](/influxdb/cloud-serverless/reference/influxql/group-by/), - the entire result set is considered a single group and is returned in full. -- If a query [groups data by time](/influxdb/cloud-serverless/reference/influxql/group-by/#group-by-time), - the offset is applied after aggregate and selector operations are applied to each - time window. -- If the [`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/) - includes a time range and the `OFFSET` clause causes InfluxQL to return points - with timestamps outside of that time range, InfluxQL returns no results. - -### Examples {#offset-examples} - -The following examples use the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Return the nth row" %}} - -```sql -SELECT * FROM home OFFSET 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Paginate results by 3 and return the 2nd page of results" %}} - -```sql -SELECT * FROM home WHERE room = 'Kitchen' LIMIT 3 OFFSET 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Paginate results from each series by 3 and return the 2nd page of each series" %}} - -```sql -SELECT * FROM home GROUP BY * LIMIT 3 OFFSET 3 -``` - -{{% influxdb/custom-timestamps %}} - -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | 22.5 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | 22.8 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | 22.2 | -| 2022-01-01T12:00:00Z | 0 | 35.9 | 22.2 | -| 2022-01-01T13:00:00Z | 0 | 36 | 22.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## `SOFFSET` clause - -{{% warn %}} -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features, such as `SOFFSET` are still -being implemented. For more information, see -[InfluxQL feature support](/influxdb/cloud-serverless/reference/influxql/feature-support/). -{{% /warn %}} - - diff --git a/content/influxdb/cloud-serverless/reference/influxql/order-by.md b/content/influxdb/cloud-serverless/reference/influxql/order-by.md index bfb2cabe5..8c2e1dffa 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/order-by.md +++ b/content/influxdb/cloud-serverless/reference/influxql/order-by.md @@ -13,97 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [DESC|ASC] ``` + +source: /shared/influxql-v3-reference/order-by.md --- - -Use the `ORDER BY` clause to sort data by time in ascending or descending order. -InfluxQL only supports sorting data by `time`. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [ASC|DESC] -``` - -- If the the `ORDER BY` clause is not included, the default behavior is to sort data by - time in **ascending** order: `ORDER BY time ASC`. -- If the query includes [`WHERE`](/influxdb/cloud-serverless/reference/influxql/where/) - and [`GROUP BY`](/influxdb/cloud-serverless/reference/influxql/group-by/) clauses, - the `ORDER BY` clause must come **after** these clauses. - -#### Sort orders - -- **ASC (ascending)**: The first row in the results has the oldest timestamp. - The last row in the results has the most recent timestamp. -- **DESC (descending)**: The first row in the results has the most recent timestamp. - The last row in the results has the oldest timestamp. - -## Examples - -The following examples use the -[Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Sort data with the oldest points first" %}} - -{{% note %}} -Ordering data by time in ascending order is the default behavior. -Including `ORDER BY time ASC` in the query isn't necessary, but it is supported. -{{% /note %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -ORDER BY time ASC -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Sort data with the newest points first" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -ORDER BY time DESC -``` - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/reference/influxql/quoting.md b/content/influxdb/cloud-serverless/reference/influxql/quoting.md index e277f35c2..47a47f715 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/quoting.md +++ b/content/influxdb/cloud-serverless/reference/influxql/quoting.md @@ -17,48 +17,6 @@ list_code_example: | -- Quoted identifier "this-is-an-identifier" ``` + +source: /shared/influxql-v3-reference/quoting.md --- - -InfluxQL supports both single and double quotation marks, but they each function -differently and serve different purposes. - -- [Single quotes](#single-quotes) -- [Double quotes](#double-quotes) - -## Single quotes - -Use single quotation marks (`'`) in the -[string literal](/influxdb/cloud-serverless/reference/influxql/#strings) and -[timestamp literal](/influxdb/cloud-serverless/reference/influxql/#dates--times) syntax. - -In the following example, the `WHERE` clause evaluates the value of the `room` tag. -Tags only contain string values, so the right operand of the predicate expression -should be a string literal. - -```sql -... WHERE room = 'Kitchen' -``` - -## Double quotes - -Use double quotation marks (`"`) to quote [identifiers](/influxdb/cloud-serverless/reference/influxql/#identifiers). -Identifiers **must** be double-quoted in the following cases: - -- The identifier contains non-word characters. - Word characters are defined as `[a-z,A-Z,0-9,_]`. -- The identifier is case-sensitive. -- The identifier contains [InfluxQL keywords](/influxdb/cloud-serverless/reference/influxql/#keywords). -- The identifier begins with a digit. - -Double-quoted identifiers can also: - -- Contain any Unicode character except for a new line. -- Contain escaped `"` characters (for example: `\"`). -- Include [InfluxQL keywords](/influxdb/cloud-serverless/reference/influxql/#keywords). - -**While not always necessary, we recommend that you double quote identifiers.** - -{{% note %}} -InfluxQL quoting guidelines differ from -[line protocol quoting guidelines](/influxdb/cloud-serverless/reference/syntax/line-protocol/#quotes). -{{% /note %}} \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/influxql/regular-expressions.md b/content/influxdb/cloud-serverless/reference/influxql/regular-expressions.md index 06bf3f06f..a8863971b 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/regular-expressions.md +++ b/content/influxdb/cloud-serverless/reference/influxql/regular-expressions.md @@ -13,198 +13,6 @@ list_code_example: | ```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` + +source: /shared/influxql-v3-reference/regular-expressions.md --- - -Regular expressions are a sequence of characters used to identify patterns in -identifiers and string values. -InfluxQL supports regular expressions in the following operations: - -- Identifying **fields** and **tags** to query in the - [`SELECT` clause](/influxdb/cloud-serverless/reference/influxql/select/). -- Identifying **measurements** to query in the - [`FROM` clause](/influxdb/cloud-serverless/reference/influxql/select/#from-clause). -- Testing **tag values** and **string field values** in the - [`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/). -- Identifying **tag keys** to group by in the - [`GROUP BY` clause](/influxdb/cloud-serverless/reference/influxql/group-by/) - -{{% note %}} -#### Query performance - -Regular expression comparisons are more computationally intensive than exact -string comparisons. Queries with regular expressions are not as performant -as those without. -{{% /note %}} - -## Regular expression syntax - -InfluxQL Regular expressions are surrounded by `/` characters and use the -[Go regular expression syntax](http://golang.org/pkg/regexp/syntax/). - -```sql -/regular_expression/ -``` - -### Regular expression flags - -Regular expression flags modify the pattern-matching behavior of the expression. -InfluxQL supports the following regular expression flags: - -| Flag | Description | -| :--- | :------------------------------------------------------------------------------ | -| i | case-insensitive | -| m | multi-line mode: `^` and `$` match begin/end line in addition to begin/end text | -| s | let `.` match `\n` | -| U | ungreedy: swap meaning of `x*` and `x*?`, `x+` and `x+?`, etc. | - -Include regular expression flags at the beginning of your regular expression -pattern enclosed in parentheses (`()`) and preceded by a question mark (`?`). - -```sql -/(?iU)foo*/ -``` - -## Regular expression operators - -InfluxQL provides the following regular expression operators that test if a -string operand matches a regular expression: - -- `=~`: Returns true if the string matches the regular expression -- `!~`: Returns true if the string does not match the regular expression - -InfluxQL regular expression operators are used to test string column values in -the [`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/). - -## Regular expression examples - -The examples below use the following sample data sets: - -- [NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data) -- [Get started home sensor data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data) - -{{< expand-wrapper >}} - -{{% expand "Use a regular expression to specify field keys and tag keys in the SELECT clause" %}} - -```sql -SELECT /^t/ FROM weather -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | temp_avg | temp_max | temp_min | -| :------------------- | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | 52 | 66 | 44 | -| 2020-01-01T00:00:00Z | 53 | 59 | 47 | -| 2020-01-01T00:00:00Z | 50 | 57 | 44 | -| 2020-01-02T00:00:00Z | 54 | 61 | 49 | -| 2020-01-02T00:00:00Z | 51 | 60 | 44 | -| 2020-01-02T00:00:00Z | 53 | 66 | 42 | -| ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify measurements in the FROM clause" %}} - -```sql -SELECT /^t/ FROM /^[hw]/ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | temp | temp_avg | temp_max | temp_min | -| :------------------- | ---: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | | 52 | 66 | 44 | -| 2020-01-01T00:00:00Z | | 53 | 59 | 47 | -| 2020-01-01T00:00:00Z | | 50 | 57 | 44 | -| 2020-01-02T00:00:00Z | | 54 | 61 | 49 | -| 2020-01-02T00:00:00Z | | 51 | 60 | 44 | -| 2020-01-02T00:00:00Z | | 53 | 66 | 42 | -| ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify tag values in the WHERE clause" %}} - -```sql -SELECT * FROM weather WHERE location !~ /^[S]/ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | location | precip | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | :------- | -----: | -------: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | Concord | 0 | 52 | 66 | 44 | 3.13 | -| 2020-01-01T00:00:00Z | Hayward | 0 | 50 | 57 | 44 | 2.24 | -| 2020-01-02T00:00:00Z | Concord | 0 | 53 | 66 | 42 | 3.13 | -| 2020-01-02T00:00:00Z | Hayward | 0 | 51 | 60 | 44 | 3.8 | -| 2020-01-03T00:00:00Z | Concord | 0 | 49 | 60 | 38 | 2.68 | -| 2020-01-03T00:00:00Z | Hayward | 0 | 50 | 62 | 41 | 3.13 | -| ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify a tag with no value in the WHERE clause" %}} - -```sql -SELECT * FROM home, weather WHERE location !~ /./ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | --: | ---: | -------- | ------ | :---------- | ---: | -------- | -------- | -------- | -------- | -| 2022-01-01T08:00:00Z | 0 | 35.9 | | | Kitchen | 21 | | | | | -| 2022-01-01T08:00:00Z | 0 | 35.9 | | | Living Room | 21.1 | | | | | -| 2022-01-01T09:00:00Z | 0 | 36.2 | | | Kitchen | 23 | | | | | -| 2022-01-01T09:00:00Z | 0 | 35.9 | | | Living Room | 21.4 | | | | | -| 2022-01-01T10:00:00Z | 0 | 36.1 | | | Kitchen | 22.7 | | | | | -| 2022-01-01T10:00:00Z | 0 | 36 | | | Living Room | 21.8 | | | | | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify tag keys in the GROUP BY clause" %}} - -```sql -SELECT MAX(precip) FROM weather GROUP BY /^l/ -``` - -{{% influxql/table-meta %}} -name: weather -tags: location=Concord -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2021-10-24T00:00:00Z | 4.53 | - -{{% influxql/table-meta %}} -name: weather -tags: location=Hayward -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2022-12-31T00:00:00Z | 4.34 | - -{{% influxql/table-meta %}} -name: weather -tags: location=San Francisco -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2021-10-24T00:00:00Z | 4.02 | - -{{% /expand %}} - -{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/reference/influxql/select.md b/content/influxdb/cloud-serverless/reference/influxql/select.md index c6bb5e42b..528fc551a 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/select.md +++ b/content/influxdb/cloud-serverless/reference/influxql/select.md @@ -14,451 +14,6 @@ list_code_example: | ```sql SELECT [,,] FROM [,] ``` + +source: /shared/influxql-v3-reference/select.md --- - -Use the `SELECT` statement to query data from one or more -[measurements](/influxdb/cloud-serverless/reference/glossary/#measurement). -The `SELECT` statement **requires** a [`SELECT` clause](#select-clause) and a -[`FROM` clause](#from-clause). - -- [Syntax](#syntax) - - [SELECT clause](#select-clause) - - [FROM clause](#from-clause) -- [Notable SELECT statement behaviors](#notable-select-statement-behaviors) -- [Data types and casting operations](#data-types-and-casting-operations) -- [SELECT statement examples](#select-statement-examples) - - -## Syntax - -```sql -SELECT field_expression[, ..., field_expression_n[, tag_expression[, ..., tag_expression_n]]] FROM measurement_expression[, ..., measurement_expression_n] -``` - -### SELECT clause - -The `SELECT` clause supports several formats for identifying data to query. -It requires one or more **field expressions** and optional **tag expressions**. - -- **field_expression**: Expression to identify one or more fields to return in query results. - Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), - constant, [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/), - [wildcard (`*`)](#wildcard-expressions-in-select-clauses), or - [function expression](/influxdb/cloud-serverless/reference/influxql/functions/) and any - combination of arithmetic operators. -- **tag_expression**: Expression to identify one or more tags to return in query results. - Can be a [tag key](/influxdb/cloud-serverless/reference/glossary/#tag-key) or constant. - -#### Select clause behaviors - -- `SELECT field_key` - Returns a specific field. -- `SELECT field_key1, field_key2` - Returns two specific fields. -- `SELECT field_key, tag_key` - Returns a specific field and tag. -- `SELECT *` - Returns all [fields](/influxdb/cloud-serverless/reference/glossary/#field) - and [tags](/influxdb/cloud-serverless/reference/glossary/#tag). - _See [Wildcard expressions](#wildcard-expressions)._ -- `SELECT /^[t]/` - Returns all [fields](/influxdb/cloud-serverless/reference/glossary/#field) - and [tags](/influxdb/cloud-serverless/reference/glossary/#tag) with keys that - match the regular expression. At least one field key must match the regular - expression. If no field keys match the regular expression, no results are - returned. - -### FROM clause - -The `FROM` clause specifies the -[measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) or -[subquery](/influxdb/cloud-serverless/reference/influxql/subqueries/) to query. -It requires one or more comma-delimited -[measurement expressions](#measurement_expression) or [subqueries](#subquery). - -#### measurement_expression - -A measurement expression identifies a measurement to query. -It can be a measurement name, fully-qualified measurement, constant, or -a [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/). - -- **Measurement name**: When using just the measurement name, InfluxQL assumes - the default retention policy of the database specified in the query request. - - ```sql - FROM measurement - ``` - -- **Fully-qualified measurement**: A fully qualified measurement includes a - database name, retention policy name, and measurement name, each separated by - a period (`.`). If the retention policy is not specified, InfluxQL uses the - default retention policy for the specified database. - -```sql -FROM database.retention_policy.measurement - --- Fully-qualified measurement with default retention policy -FROM database..measurement -``` - -{{% note %}} -#### InfluxQL retention policies - -In {{< product-name >}}, **retention policies** are not part of the data model -like they are in InfluxDB 1.x. -Each {{< product-name >}} database has a **retention period** which defines the -maximum age of data to retain in the database. To use fully-qualified -measurements in InfluxQL queries, use the following naming convention when -[creating a database](/influxdb/cloud-serverless/admin/databases/create/): - -``` -database_name/retention_policy -``` -{{% /note %}} - -#### Subquery - -An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. -The outer query queries results returned by the inner query (subquery). - -For more information, see [InfluxQL subqueries](/influxdb/cloud-serverless/reference/influxql/subqueries/). - -## Notable SELECT statement behaviors - -- [Must query at least one field](#must-query-at-least-one-field) -- [Wildcard expressions](#wildcard-expressions) -- [Cannot include both aggregate and non-aggregate field expressions](#cannot-include-both-aggregate-and-non-aggregate-field-expressions) - -### Must query at least one field - -A query requires at least one [field key](/influxdb/cloud-serverless/reference/glossary/#field-key) -in the `SELECT` clause to return data. -If the `SELECT` clause includes only [tag keys](/influxdb/cloud-serverless/reference/glossary/#tag-key), -the query returns an empty result. -When using regular expressions in the `SELECT` clause, if regular expression -matches only tag keys and no field keys, the query returns an empty result. - -To return data associated with tag keys, include at least one field key in the -`SELECT` clause. - -### Wildcard expressions - -When using a wildcard expression (`*`) in the `SELECT` clause, the query returns -all tags and fields. -If a [function](/influxdb/cloud-serverless/reference/influxql/functions/) is -applied to a wildcard expression, the query returns all _fields_ with -the function applied, but does not return _tags_ unless they are included in -the `SELECT` clause. - -### Cannot include both aggregate and non-aggregate field expressions - -The `SELECT` statement cannot include an aggregate field expression -(one that uses an [aggregate](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/) -or [selector](/influxdb/cloud-serverless/reference/influxql/functions/aggregates/) -function) **and** a non-aggregate field expression. -For example, in the following query, an aggregate function is applied to one -field, but not the other: - -```sql -SELECT mean(temp), hum FROM home -``` - -This query returns an error. -For more information, see [error about mixing aggregate and non-aggregate queries](/enterprise_influxdb/v1/troubleshooting/errors/#error-parsing-query-mixing-aggregate-and-non-aggregate-queries-is-not-supported). - -## Data types and casting operations - -The [`SELECT` clause](#select-clause) supports specifying a -[field's](/influxdb/cloud-serverless/reference/glossary/#field) type and basic -casting operations with the `::` syntax. - -```sql -SELECT field_expression::type FROM measurement_expression -``` - -The `::` syntax allows users to perform basic cast operations in queries. -Currently, InfluxQL supports casting _numeric_ [field values](/influxdb/cloud-serverless/reference/glossary/#field-value) -to other numeric types. -Casting to an **identifier type** acts as a filter on results and returns only -columns of that specific identifier type along with the `time` column. - -{{< flex >}} -{{% flex-content "third" %}} - -##### Numeric types - -- `float` -- `integer` -- `unsigned` - -{{% /flex-content %}} -{{% flex-content "third" %}} - -##### Non-numeric types - -- `string` -- `boolean` - -{{% /flex-content %}} -{{% flex-content "third" %}} - -##### Identifier types - -- `field` -- `tag` - -{{% /flex-content %}} -{{< /flex >}} - -{{% note %}} -InfluxQL returns no data if the query attempts to cast a numeric value to a -non-numeric type and vice versa. -{{% /note %}} - -When casting a float value to an integer or unsigned integer, the float value -is truncated at the decimal point. No rounding is performed. - -## SELECT statement examples - -The examples below use the following sample data sets: - -- [Get started home sensor data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data) -- [NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data) - -{{< expand-wrapper >}} -{{% expand "Select all fields and tags from a measurement" %}} - -```sql -SELECT * FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select specific tags and fields from a measurement" %}} - -```sql -SELECT temp, hum, room FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | temp | hum | room | -| :------------------- | ---: | ---: | :---------- | -| 2022-01-01T08:00:00Z | 21 | 35.9 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | 35.9 | Living Room | -| 2022-01-01T09:00:00Z | 23 | 36.2 | Kitchen | -| 2022-01-01T09:00:00Z | 21.4 | 35.9 | Living Room | -| 2022-01-01T10:00:00Z | 22.7 | 36.1 | Kitchen | -| 2022-01-01T10:00:00Z | 21.8 | 36 | Living Room | -| ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select all fields from a measurement" %}} - -```sql -SELECT *::field FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | 21.8 | -| ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select a field from a measurement and perform basic arithmetic" %}} - -```sql -SELECT (temp * (9 / 5)) + 32 FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | temp | -| :------------------- | ----------------: | -| 2022-01-01T08:00:00Z | 69.80000000000001 | -| 2022-01-01T08:00:00Z | 69.98 | -| 2022-01-01T09:00:00Z | 73.4 | -| 2022-01-01T09:00:00Z | 70.52 | -| 2022-01-01T10:00:00Z | 72.86 | -| 2022-01-01T10:00:00Z | 71.24000000000001 | -| ... | ... | - -{{% /influxdb/custom-timestamps %}} - -{{% note %}} -**Note:** InfluxDB follows the standard order of operations. -See [InfluxQL mathematical operators](/influxdb/cloud-serverless/reference/influxql/math-operators/) -for more on supported operators. -{{% /note %}} - -{{% /expand %}} - -{{% expand "Select all data from more than one measurement" %}} - -```sql -SELECT * FROM home, weather -``` - -{{% influxql/table-meta %}} -Name: weather -{{% /influxql/table-meta %}} - -| time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | --: | --: | :------------ | -----: | :--- | ---: | -------: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | | | Concord | 0 | | | 52 | 66 | 44 | 3.13 | -| 2020-01-01T00:00:00Z | | | San Francisco | 0 | | | 53 | 59 | 47 | 14.32 | -| 2020-01-01T00:00:00Z | | | Hayward | 0 | | | 50 | 57 | 44 | 2.24 | -| 2020-01-02T00:00:00Z | | | San Francisco | 0 | | | 54 | 61 | 49 | 5.82 | -| 2020-01-02T00:00:00Z | | | Hayward | 0 | | | 51 | 60 | 44 | 3.8 | -| 2020-01-02T00:00:00Z | | | Concord | 0 | | | 53 | 66 | 42 | 3.13 | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Select all data from a fully-qualified measurement (with default retention policy)" %}} - -```sql -SELECT * FROM "get-started"..home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -### Type-casting examples - -{{< expand-wrapper >}} - -{{% expand "Cast an integer field to a float" %}} - -```sql -SELECT co::float FROM home -``` - -{{% /expand %}} - -{{% expand "Cast a float field to an integer" %}} - -```sql -SELECT temp::integer FROM home -``` - -{{% /expand %}} - -{{% expand "Cast a float field to an unsigned integer" %}} - -```sql -SELECT temp::unsigned FROM home -``` - -{{% /expand %}} - -{{< /expand-wrapper >}} - - diff --git a/content/influxdb/cloud-serverless/reference/influxql/show.md b/content/influxdb/cloud-serverless/reference/influxql/show.md index 3b1901618..4a5341e95 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/show.md +++ b/content/influxdb/cloud-serverless/reference/influxql/show.md @@ -1,7 +1,7 @@ --- title: InfluxQL SHOW statements description: > - Use InfluxQL `SHOW` statements to query schema information from a bucket. + Use InfluxQL `SHOW` statements to query schema information from a database. menu: influxdb_cloud_serverless: name: SHOW statements @@ -14,153 +14,6 @@ list_code_example: | ``` related: - /influxdb/cloud-serverless/query-data/influxql/explore-schema/ + +source: /shared/influxql-v3-reference/show.md --- - -Use InfluxQL `SHOW` statements to query schema information from a database. - -- [SHOW RETENTION POLICIES](#show-retention-policies) -- [SHOW MEASUREMENTS](#show-measurements) -- [SHOW FIELD KEYS](#show-field-keys) -- [SHOW TAG KEYS](#show-tag-keys) -- [SHOW TAG VALUES](#show-tag-values) - -## SHOW RETENTION POLICIES - -Use the `SHOW RETENTION POLICIES` statement to list retention policies associated -with a database. -Each database has a single retention policy--`autogen`. - -{{% note %}} -In {{< product-name >}}, retention policies are not part of the -data structure but are expected by InfluxQL and used in fully-qualified measurements -in the [`FROM` clause](/influxdb/cloud-serverless/reference/influxql/select/#from-clause). -The data returned for each retention policy does not represent the actual -retention-related attributes of the database. The values are placeholder values -meant only for InfluxQL feature parity. - -For information about database data retention, see -[List databases](/influxdb/cloud-serverless/admin/databases/list/). -{{% /note %}} - -```sql -SHOW RETENTION POLICIES [ON ] -``` - -#### Examples - -```sql --- Show retention policies in the database specified in the query request -SHOW RETENTION POLICIES - --- Show retention policies in a specific database -SHOW RETENTION POLICIES ON "example-database" -``` - -## SHOW MEASUREMENTS - -Use the `SHOW MEASUREMENTS` statement to list measurements in a bucket. - -```sql -SHOW MEASUREMENTS [with_measurement_clause] [where_clause] [limit_clause] [offset_clause] -``` - -#### Examples - -```sql --- Show all measurements -SHOW MEASUREMENTS - --- Show measurements where region tag = 'uswest' AND host tag = 'serverA' -SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' - --- Show measurements that start with 'h2o' -SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ -``` - -## SHOW FIELD KEYS - -Use the `SHOW FIELD KEYS` statement to list all field keys in a measurement. - -```sql -SHOW FIELD KEYS [from_clause] -``` - -#### Examples - -```sql --- Show field keys and field value data types from all measurements -SHOW FIELD KEYS - --- Show field keys and field value data types from specified measurement -SHOW FIELD KEYS FROM "cpu" -``` - -## SHOW TAG KEYS - -Use the `SHOW TAG KEYS` statement to list tag keys in a measurement. - -```sql -SHOW TAG KEYS [from_clause] [where_clause] [limit_clause] [offset_clause] -``` - -#### Examples - -```sql --- Show all tag keys -SHOW TAG KEYS - --- Show all tag keys from the cpu measurement -SHOW TAG KEYS FROM "cpu" - --- Show all tag keys from the cpu measurement where the region key = 'uswest' -SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' - --- Show all tag keys where the host key = 'serverA' -SHOW TAG KEYS WHERE "host" = 'serverA' -``` - -## SHOW TAG VALUES - -Use the `SHOW TAG VALUES` statement to list values of specified tags in a database. - -```sql -SHOW TAG VALUES [from_clause] WITH KEY = [where_clause] [limit_clause] [offset_clause] -``` - -By default, the `SHOW TAG VALUES` statement only returns unique tag values from -**the last day**. To modify the time range, include a -[`WHERE` clause with a time-based predicate](/influxdb/cloud-serverless/reference/influxql/where/#time-ranges). - -{{% note %}} - -#### Include a FROM clause - -We strongly recommend including a `FROM` clause with the `SHOW TAG VALUES` -statement that specifies 1-50 tables to query. -Without a `FROM` clause, the InfluxDB query engine must read data from all -tables and return unique tag values from each. - -Depending on the number of tables in your database and the number of unique tag -values in each table, excluding a `FROM` clause can result in poor query performance, -query timeouts, or unnecessary resource allocation that may affect other queries. - -{{% /note %}} - -#### Examples - -```sql --- Show tag values from the cpu measurement for the region tag -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" - --- Show tag values from the cpu measurement for the region tag for a custom time range -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" WHERE time > -7d - --- Show tag values from multiple measurements for the region tag -SHOW TAG VALUES FROM "cpu", "memory", "disk" WITH KEY = "region" - --- Show tag values from the cpu measurement for all tag keys that do not include the letter c -SHOW TAG VALUES FROM "cpu" WITH KEY !~ /.*c.*/ - --- Show tag values from the cpu measurement for region & host tag keys where service = 'redis' -SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' -``` diff --git a/content/influxdb/cloud-serverless/reference/influxql/subqueries.md b/content/influxdb/cloud-serverless/reference/influxql/subqueries.md index aa609705c..8645f5443 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/subqueries.md +++ b/content/influxdb/cloud-serverless/reference/influxql/subqueries.md @@ -13,234 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` + +source: /shared/influxql-v3-reference/subqueries.md --- - -An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. -The outer query queries results returned by the inner query (subquery). - -- [Syntax](#syntax) -- [Examples](#examples) -- [Notable subquery behaviors](#notable-subquery-behaviors) - -{{% note %}} -InfluxQL does not support a `HAVING` clause, however InfluxQL subqueries offer -functionality similar to the [SQL `HAVING` clause](/influxdb/cloud-serverless/reference/sql/having/). -{{% /note %}} - -## Syntax - -```sql -SELECT_clause FROM ( SELECT_statement ) [...] -``` - -When using subqueries, InfluxQL **performs the inner query first**, then performs -the outer query. - -The outer query requires a [`SELECT` clause](/influxdb/cloud-serverless/reference/influxql/select/#select-clause) -and a [`FROM` clause](/influxdb/cloud-serverless/reference/influxql/select/#from-clause). -The inner query is enclosed in parentheses in the outer query's `FROM` clause. - -InfluxQL supports multiple nested subqueries: - -```sql -SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] -``` - -## Examples - -{{% note %}} -#### Sample data - -The examples below use the following sample data sets: - -- [Get started home sensor data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data) -- [Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data) -{{% /note %}} - -{{< expand-wrapper >}} - -{{% expand "Apply an aggregate function to an aggregated result set" %}} - -```sql -SELECT - SUM(max) -FROM - ( - SELECT - MAX(temp) - FROM - home - GROUP BY - room - ) -``` - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | ---: | -| 1970-01-01T00:00:00Z | 46.1 | - -{{% /expand %}} - -{{% expand "Calculate the average difference between two fields" %}} - -```sql -SELECT - MEAN(difference) -FROM - ( - SELECT - a - b AS difference - FROM - numbers - ) -``` - -{{% influxql/table-meta %}} -Table: numbers -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -------------------: | -| 1970-01-01T00:00:00Z | -0.03629771779732732 | - -{{% /expand %}} - -{{% expand "Filter aggregate values based on a threshold" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - co_change -FROM - ( - SELECT - SPREAD(co) AS co_change - FROM - home - GROUP BY - room, - time(2h) - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' - AND co_change >= 4 -``` - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | co_chnage | -| :------------------- | --------: | -| 2022-01-01T18:00:00Z | 4 | -| 2022-01-01T18:00:00Z | 5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Perform additional aggregate operations on aggregate values" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SUM(co_derivative) AS sum_derivative -FROM - ( - SELECT - DERIVATIVE(MEAN(co)) AS co_derivative - FROM - home - GROUP BY - time(12m), - room - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY - room -``` - -{{% /influxdb/custom-timestamps %}} - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | room | sum_derivative | -| :------------------- | :---------- | -------------: | -| 1970-01-01T00:00:00Z | Kitchen | 5.2 | -| 1970-01-01T00:00:00Z | Living Room | 3.4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable subquery behaviors - -- [Apply time bounds to the outer query to improve performance](#apply-time-bounds-to-the-outer-query-to-improve-performance) -- [Cannot use multiple SELECT statements in a subquery](#cannot-use-multiple-select-statements-in-a-subquery) - -### Apply time bounds to the outer query to improve performance - -To improve the performance of InfluxQL queries that use subqueries and a -specified time range, apply the `WHERE` clause with time-based predicates to the -outer query rather than the inner query. -For example--the following queries return the same results, but **the query with -time-based predicate on the outer query is more performant than the query with -time-based predicate on the inner query**: - -{{% influxdb/custom-timestamps %}} - -#### Time bounds on the outer query {note="(Recommended)"} - -```sql -SELECT - inner_value AS value -FROM - ( - SELECT - raw_value as inner_value - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -``` - -#### Time bounds on the inner query - -```sql -SELECT - inner_value AS value -FROM - ( - SELECT - raw_value as inner_value - WHERE - time >= '2022-07-19T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' - ) -``` -{{% /influxdb/custom-timestamps %}} - -### Cannot use multiple SELECT statements in a subquery - -InfluxQL does not support multiple -[`SELECT` statements](/influxdb/cloud-serverless/reference/influxql/select/) -per subquery: - -```sql -SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] -``` - -However, InfluxQL does support multiple nested subqueries per outer query: - -```sql -SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] - ------------------ ---------------- - Subquery 1 Subquery 2 -``` diff --git a/content/influxdb/cloud-serverless/reference/influxql/time-and-timezone.md b/content/influxdb/cloud-serverless/reference/influxql/time-and-timezone.md index 8d2df3f29..344a9cedf 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/time-and-timezone.md +++ b/content/influxdb/cloud-serverless/reference/influxql/time-and-timezone.md @@ -13,369 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` + +source: /shared/influxql-v3-reference/time-and-timezone.md --- - -InfluxQL is designed for working with time series data and includes features specifically for working with time. -You can review the following ways to work with time and timestamps in your InfluxQL queries: - -- [Time syntax](#time-syntax) - - [Add and subtract time values](#add-and-subtract-time-values) -- [Query time range](#query-time-range) - - [Supported operators](#supported-operators) -- [Query examples](#query-examples) -- [Time zone clause](#time-zone-clause) -- [Notable behaviors](#notable-behaviors) - - [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - - [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) - - [Cannot use parameters for durations](#cannot-use-parameters-for-durations) - -## Time syntax - -InfluxQL supports the following timestamp literal syntaxes: - -```sql -'2006-01-02T15:04:05.00Z' -- RFC3339 date-time string -'2006-01-02 15:04:05.00' -- RFC3339-like date-time string -1136189045000000000 -- Unix nanosecond epoch time -1136189045s -- Unix epoch time -``` - -- **RFC3339 date-time string**: - [String literal](/influxdb/cloud-serverless/reference/influxql/#strings) using - the RFC3339 timestamp format, `YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`. -- **RFC3339-like date-time string**: - [String literal](/influxdb/cloud-serverless/reference/influxql/#strings) using - the RFC3339-like timestamp format, `YYYY-MM-DD HH:MM:SS.nnnnnnnnn`. -- **Unix nanosecond epoch time**: - [Integer](/influxdb/cloud-serverless/reference/influxql/#integers) that - represents the number of nanoseconds elapsed since the - [Unix epoch](/influxdb/cloud-serverless/reference/glossary/#unix-epoch). -- **Unix epoch time**: - [Duration literal](/influxdb/cloud-serverless/reference/influxql/#durations) - that represents the number of specified time units elapsed since the - [Unix epoch](/influxdb/cloud-serverless/reference/glossary/#unix-epoch). - _[View supported duration units](/influxdb/cloud-serverless/reference/influxql/#durations)_. - -##### Supported timestamp values - -| | RFC3339 | Unix nanosecond time | -| ----------- | :----------------------------: | -------------------: | -| **Maximum** | 2262-04-11T23:47:16.854775807Z | 9223372036854775807 | -| **Minimum** | 1677-09-21T00:12:43.145224193Z | -9223372036854775807 | - -### Add and subtract time values - -Timestamp values support addition and subtraction operations with -[duration literals](/influxdb/cloud-serverless/reference/influxql/#durations). -Add (`+`) or subtract (`-`) a duration to or from a timestamp to return an -updated timestamp. - -```sql -'2023-01-01T00:00:00Z' + 2h -- Resolves to 2023-01-01T02:00:00Z -'2023-01-01 00:00:00' - 20h -- Resolves to 2022-12-31T04:00:00Z -1672531200000000000 + 1y -- Resolves to 2024-01-01T00:00:00Z -``` - -{{% note %}} -InfluxQL requires a whitespace between the `+` operators `-` and the duration literal. -{{% /note %}} - -## Query time range - -To specify the time range of a query, use conditional expressions in the -[`WHERE` clause](/inflxudb/cloud-serverless/reference/influxql/where/) that -compare the value of the `time` column to an absolute timestamp or a relative -timestamp. - -- **Absolute time range**: Define query time bounds with timestamp literals - - ```sql - WHERE time >= '2023-01-01T00:00:00Z' AND time <= '2023-07-01T00:00:00Z' - WHERE time >= '2023-01-01 00:00:00' AND time <= '2023-07-01 00:00:00' - WHERE time >= 1672531200000000000 AND time <= 1688169600000000000 - WHERE time >= 1672531200s and time <= 1688169600000ms - ``` - -- **Relative time range**: Define query time bounds with a duration literal - added to or subtracted from timestamp literals. - - {{% note %}} - Use `now()` to return the current system time (UTC). - {{% /note %}} - - ```sql - -- Query data from the last day - WHERE time >= now() - 1d - - -- Query data from the previous week - WHERE time >= now() - 1w AND time <= now() - 2w - - -- Query data relative to a specific time - WHERE time >= '2023-01-01' - 1w AND time <= '2023-01-01' + 1w - ``` - -### Supported operators - -Conditional expressions with time operands support the following comparison operators: - -| Operator | Meaning | -|:--------:|:------- | -| `=` | equal to | -| `<>` | not equal to | -| `!=` | not equal to | -| `>` | greater than | -| `>=` | greater than or equal to | -| `<` | less than | -| `<=` | less than or equal to | - -{{% note %}} -Currently, InfluxQL supports the `AND` logical operator to define query time bounds, -but does not support using the `OR` logical operator to query multiple time ranges. -{{% /note %}} - -## Query examples - -The following examples use the -[Get started home sensor sample dataset](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Specify a time range with RFC3339 date-time strings" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range with RFC3339-like date-time strings" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01 08:00:00' - AND time <= '2022-01-01 12:00:00' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Specify a time range with nanosecond epoch timestamps" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= 1641024000000000000 - AND time <= 1641038400000000000 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range with second-precision epoch timestamps" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= 1641024000s - AND time <= 1641038400s -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range relative to a timestamp" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | -| 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | -| 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | -| 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range relative to now" %}} - -```sql -SELECT * FROM home WHERE time >= now() - 2h -``` - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Time zone clause - -{{% warn %}} -InfluxQL in {{< product-name >}} does not currently support the time zone clause, -which applies a time zone offset to UTC timestamps in query results. -{{% /warn %}} - - - - - -## Notable behaviors - -- [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) -- [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) -- [Cannot use parameters for durations](#cannot-use-parameters-for-durations) - -### Cannot query multiple time ranges - -InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. -For example, the following query returns no results: - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') - OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') -``` - -{{% /influxdb/custom-timestamps %}} - -### Querying future data with a `GROUP BY time()` clause - -Queries that do not specify time bounds in the `WHERE` clause and do not include -a `GROUP BY time()` clause use the [minimum and maximum timestamps](#supported-timestamp-values) -as the default time range. -If the query includes a `GROUP BY time()` clause, the default time range is -between `1677-09-21T00:12:43.145224193Z` and -[`now()`](/influxdb/cloud-serverless/reference/influxql/functions/date-time/#now). - -To query data with timestamps that occur in the future (after `now()`), -provide an explicit upper bound in the `WHERE` clause. - -### Cannot use parameters for durations - -Currently, InfluxDB doesn't support using parameters for durations in -[parameterized queries](/influxdb/cloud-serverless/query-data/parameterized-queries/). diff --git a/content/influxdb/cloud-serverless/reference/influxql/where.md b/content/influxdb/cloud-serverless/reference/influxql/where.md index b69375095..52dbaa8e8 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/where.md +++ b/content/influxdb/cloud-serverless/reference/influxql/where.md @@ -12,359 +12,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` + +source: /shared/influxql-v3-reference/where.md --- - -Use the `WHERE` clause to filter data based on -[field values](/influxdb/cloud-serverless/reference/glossary/#field), -[tag values](/influxdb/cloud-serverless/reference/glossary/#tag), and -[timestamps](/influxdb/cloud-serverless/reference/glossary/#timestamp). - -- [Syntax](#syntax) -- [Operators](#comparison-operators) - - [Comparison operators](#comparison-operators) - - [Logical operators](#logical-operators) -- [Time ranges](#time-ranges) -- [Regular expressions](#regular-expressions) -- [WHERE clause examples](#where-clause-examples) -- [Notable behaviors](#notable-behaviors) - - [Single and double quotes](#single-and-double-quotes) - - [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - -## Syntax - -```sql -SELECT_clause FROM_clause WHERE [(AND|OR) [...]] -``` - -- **conditional_expression**: Comparison between two operands that evaluates to - `true` or `false`. Comparison logic is determined by - [operators](#operators) used in the expression. - These expressions can operate on InfluxDB fields, tags, and timestamps. - Use logical operators (`AND`, `OR`) to chain multiple conditional expressions - together. - -## Operators - -Operators evaluate the relationship between two operands and return -`true` or `false`. - -### Comparison operators - -| Operator | Meaning | Supported data types | -| :------: | :--------------------------------- | :---------------------- | -| `=` | Equal to | all | -| `<>` | Not equal to | all | -| `!=` | Not equal to | all | -| `>` | Greater than | numeric, timestamp | -| `>=` | Greater than or equal to | numeric, timestamp | -| `<` | Less than | numeric, timestamp | -| `<=` | Less than or equal to | numeric, timestamp | -| `=~` | Matches a regular expression | strings | -| `!~` | Doesn't match a regular expression | strings | - -### Logical operators - -| Operator | Meaning | -| :------- | :---------------------------------------------------------------------- | -| `AND` | Returns `true` if both operands are `true`. Otherwise, returns `false`. | -| `OR` | Returns `true` if any operand is `true`. Otherwise, returns `false`. | - -## Time ranges - -Use the `WHERE` clause to specify a time range to query. -If a time range isn't specified in the `WHERE` clause, the [default time range](/influxdb/cloud-serverless/reference/influxql/#default-time-range) is used. - -Timestamps are stored in the `time` column. -Use comparison operators to compare the value of the `time` column to a -timestamp literal, integer (Unix nanosecond timestamp), or [expression](/influxdb/cloud-serverless/reference/glossary/#expression). - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Timestamp](#) -[Integer](#) -[Expression](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-07-01T00:00:00Z' -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -WHERE - time >= 1672531200000000000 - AND time < 1688169600000000000 -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -WHERE - time >= now() - 1d - AND time < now() -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -See [Time syntax](/influxdb/cloud-serverless/reference/influxql/time-and-timezone/#time-syntax) -for information on how to specify alternative time ranges in the `WHERE` clause. - -{{% note %}} -InfluxQL [does not support querying multiple time ranges](#cannot-query-multiple-time-ranges). -{{% /note %}} - -## Regular expressions - -Regular expressions can be used to evaluate _string_ values in the `WHERE` clause -using regular expression comparison operators: - -- `=~`: Matches a regular expression -- `!~`: Doesn't match a regular expression - -```sql -SELECT * FROM home WHERE room =~ /^K/ -``` - -For more information about InfluxQL regular expression syntax, see -[InfluxQL regular expressions](/influxdb/cloud-serverless/reference/influxql/regular-expressions/). - -## WHERE clause examples - -The following examples use the -[Get started home sensor sample dataset](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} -{{% expand "Select data with a specific tag value" %}} - -```sql -SELECT * FROM home WHERE room = 'Living Room' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| 2022-01-01T11:00:00Z | 0 | 36 | Living Room | 22.2 | -| 2022-01-01T12:00:00Z | 0 | 35.9 | Living Room | 22.2 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data from a specific time range" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data from a relative time range" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | -| 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | -| 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | -| 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select field values above a threshold" %}} - -```sql -SELECT co FROM home WHERE co > 9 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | -| :------------------- | --: | -| 2022-01-01T18:00:00Z | 18 | -| 2022-01-01T19:00:00Z | 14 | -| 2022-01-01T19:00:00Z | 22 | -| 2022-01-01T20:00:00Z | 17 | -| 2022-01-01T20:00:00Z | 26 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select specific field values" %}} - -```sql -SELECT room, co FROM home WHERE co = 9 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | room | co | -| :------------------- | :---------- | --: | -| 2022-01-01T17:00:00Z | Kitchen | 9 | -| 2022-01-01T18:00:00Z | Living Room | 9 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select field values based on arithmetic" %}} - -```sql -SELECT room, co FROM home WHERE co - 10 > 5 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | room | co | -| :------------------- | :---------- | --: | -| 2022-01-01T18:00:00Z | Kitchen | 18 | -| 2022-01-01T19:00:00Z | Kitchen | 22 | -| 2022-01-01T20:00:00Z | Living Room | 17 | -| 2022-01-01T20:00:00Z | Kitchen | 26 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data with field values above a threshold and a specific tag value" %}} - -```sql -SELECT * FROM home WHERE temp > 22.7 AND room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | -| 2022-01-01T14:00:00Z | 1 | 36.3 | Kitchen | 22.8 | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data based on the relationship between columns" %}} - -```sql -SELECT co, temp FROM home WHERE co > temp -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | temp | -| :------------------- | --: | ---: | -| 2022-01-01T20:00:00Z | 26 | 22.7 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable behaviors - -- [Single and double quotes](#single-and-double-quotes) -- [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - -### Single and double quotes - -In InfluxQL, single quotation marks (`'`) and double quotation marks (`"`) work -differently and can alter the way a `WHERE` clause functions. -Single quotes are used in [string](/influxdb/cloud-serverless/reference/influxql/#strings) -and [timestamp](/influxdb/cloud-serverless/reference/influxql/#dates--times) literals. -Double quotes are used to quote [identifiers](/influxdb/cloud-serverless/reference/influxql/#identifiers), -(time, field, and tag column names). - -For example, the following conditional expression compares the value of the -`location` _column_ to the _literal string_, `London`: - -```sql -"location" = 'London' -``` - -The following conditional expression compares the value of the `location` _column_ -to the value of the `London` _column_: - -```sql -"location" = "London" -``` - -Misused double and single quotes in the `WHERE` clause often results in unexpected -empty query results. -For more information about quotation marks, see -[InfluxQL quotation](/influxdb/cloud-serverless/reference/influxql/quoting/). - -### Cannot query multiple time ranges - -InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. -For example, the following query returns no results: - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') - OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') -``` - -{{% /influxdb/custom-timestamps %}} diff --git a/content/influxdb/cloud-serverless/reference/sql/_index.md b/content/influxdb/cloud-serverless/reference/sql/_index.md index 790c0e005..404447230 100644 --- a/content/influxdb/cloud-serverless/reference/sql/_index.md +++ b/content/influxdb/cloud-serverless/reference/sql/_index.md @@ -9,689 +9,10 @@ menu: weight: 101 related: - /influxdb/cloud-serverless/reference/internals/arrow-flightsql/ + +source: /content/shared/sql-reference/_index.md --- -{{% product-name %}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. - -- [Identifiers](#identifiers) -- [Quoting and case sensitivity](#quoting-and-case-sensitivity) -- [Literals](#literals) -- [Duration units](#duration-units) -- [Operators](#operators) -- [Keywords](#keywords) -- [Conditional expressions](#conditional-expressions) -- [Statements and clauses](#statements-and-clauses) -- [Comments](#comments) -- [Functions](#functions) - -## Identifiers - -An identifier is a token which refers to the name of an InfluxDB database object, such as a **measurement** or a column name (**time**, **tag keys**, or **field keys**). - -## Quoting - -Use double quotes on [identifiers](#identifiers) to treat them as case-sensitive. -Use single quotes on string literals. - -General quoting guidelines: - -- Single quote RFC3339 and RFC3339-like time values. -- Do _not_ quote Unix epoch time values (integers cast to a timestamp). -- Double-quote mixed case, [camel case](https://en.wikipedia.org/wiki/Camel_case) or case-sensitive identifiers. -- Double-quote identifiers that contain special characters or whitespace characters. - -##### Quoting examples - -```sql --- Double-quote identifiers that contain whitespace -SELECT "water temperature", "buoy location" FROM buoy - --- Double-quote measurement names with special characters -SELECT * FROM "h2o-temperature" - --- Double-quote identifiers that should be treated as case-sensitive -SELECT "pH" FROM "Water" -``` - -{{% note %}} -**Note:** We recommend always double-quoting identifiers, regardless of case-sensitivity. -{{% /note %}} - - -Unquoted identifiers **are not** case-sensitive and match any measurement, tag key, or field key with the same characters, despite case. -For example, if you have two fields in a measurement named `ph` and `pH`, the unquoted identifier, `pH` will match both. -To query in a case-sensitive manner, double-quote identifiers. - -## Literals - -A literal is an explicit value not represented by an identifier. - -### String literals - -String literals are surrounded by single quotes. - -```sql -'santa_monica' -'pH' -'average temperature' -``` - -### Numeric literals - -Number literals are positive or negative numbers that are either exact numbers or floats. - -```sql --- Integers -10 -+10 --10 - --- Unsigned integers -10::BIGINT UNSIGNED -+10::BIGINT UNSIGNED - --- Floats -10.78654 --100.56 -``` - -### Date and time literals - -The following date and time literals are supported: - -```sql -'2022-01-31T06:30:30.123Z' -- (RFC3339) -'2022-01-31T06:30:30.123' -- (RFC3339-like) -'2022-01-31 06:30:30.123' -- (RFC3339-like) -'2022-01-31 06:30:30' -- ((RFC3339-like, no fractional seconds) -1643610630123000000::TIMESTAMP -- (Unix epoch nanosecond cast to a timestamp) -``` - -### Boolean literals - -Boolean literals are either `TRUE` or `FALSE`. - -## Duration units - -Interval literals specify a length or unit of time. - -```sql -INTERVAL '4 minutes' -INTERVAL '12 days 6 hours 30 minutes' -``` - -The following units of time are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks -- months -- years -- century - -## Operators - -Operators are reserved words or characters which perform certain operations, including comparisons and arithmetic. - -### Arithmetic operators - -Arithmetic operators take two numeric values (either literals or variables) and -perform a calculation that returns a single numeric value. - -| Operator | Description | Example | Result | -| :------: | :------------- | ------- | -----: | -| `+` | Addition | `2 + 2` | `4` | -| `-` | Subtraction | `4 - 2` | `2` | -| `*` | Multiplication | `2 * 3` | `6` | -| `/` | Division | `6 / 3` | `2` | -| `%` | Modulo | `7 % 2` | `1` | - -### Comparison operators - -Comparison operators evaluate the relationship between the left and right operands and `TRUE` or `FALSE`. - -| Operator | Meaning | Example | -| :------: | :------------------------------------------------------- | :----------------- | -| `=` | Equal to | `123 = 123` | -| `<>` | Not equal to | `123 <> 456` | -| `!=` | Not equal to | `123 != 456` | -| `>` | Greater than | `3 > 2` | -| `>=` | Greater than or equal to | `3 >= 2` | -| `<` | Less than | `1 < 2` | -| `<=` | Less than or equal to | `1 <= 2` | -| `~` | Matches a regular expression | `'abc' ~ 'a.*'` | -| `~\*` | Matches a regular expression _(case-insensitive)_ | `'Abc' ~\* 'A.*'` | -| `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | -| `!~\*` | Does not match a regular expression _(case-insensitive)_ | `'Abc' !~\* 'a.*'` | - -### Logical operators - -| Operator | Meaning | -| :-------: | :------------------------------------------------------------------------- | -| `AND` | Returns true if both operands are true. Otherwise, returns false. | -| `BETWEEN` | Returns true if the left operand is within the range of the right operand. | -| `EXISTS` | Returns true if the operand is not null. | -| `IN` | Returns true if the left operand is in the right operand list. | -| `LIKE` | Returns true if the left operand matches the right operand pattern string. | -| `NOT` | Negates the subsequent expression. | -| `OR` | Returns true if any operand is true. Otherwise, returns false. | - -### Bitwise operators - -Bitwise operators perform bitwise operations on bit patterns or binary numerals. - -| Operator | Meaning | Example | Result | -| :------: | :------------------ | :------- | -----: | -| `&` | Bitwise and | `5 & 3` | `1` | -| `\|` | Bitwise or | `5 \| 3` | `7` | -| `^` | Bitwise xor | `5 ^ 3` | `6` | -| `>>` | Bitwise shift right | `5 >> 3` | `0` | -| `<<` | Bitwise shift left | `5 << 3` | `40` | - -### Other operators - -| Operator | Meaning | Example | Result | -| :------------: | :----------------------- | :--------------------------------------------------------------------------------------- | :------------ | -| `\|\|` | Concatenates strings | `'Hello' \|\| ' world'` | `Hello world` | -| `AT TIME ZONE` | Apply a time zone offset | _[View example](/influxdb/cloud-serverless/reference/sql/operators/other/#at-time-zone)_ | | - -## Keywords - -The following reserved keywords cannot be used as identifiers. - -```sql -AND -ALL -ANALYZE -AS -ASC -AT TIME ZONE -BETWEEN -BOTTOM -CASE -DESC -DISTINCT -EXISTS -EXPLAIN -FROM -GROUP BY -HAVING -IN -INNER JOIN -JOIN -LEFT JOIN -LIKE -LIMIT -NOT -EXISTS -NOT IN -OR -ORDER BY -FULL OUTER JOIN -RIGHT JOIN -SELECT -TOP -TYPE -UNION -UNION ALL -WHERE -WITH -``` - -## Conditional expressions - -Conditional expressions evaluate conditions based on input values. -The following conditional expressions are supported: - -| Expression | Description | -| :--------- | :----------------------------------------------------------------- | -| CASE | Allows for use of WHEN-THEN-ELSE statements. | -| COALESCE | Returns the first non-NULL expression in a specified list. | -| NULLIF | Returns a NULL value if value1 = value2. Otherwise returns value1. | - -## Statements and clauses - -InfluxDB SQL supports the following basic syntax for queries: - -```sql -[ WITH with_query [, …] ] -SELECT [ ALL | DISTINCT ] select_expr [, …] -[ FROM from_item [, …] ] -[ JOIN join_item [, …] ] -[ WHERE condition ] -[ GROUP BY grouping_element [, …] ] -[ HAVING condition] -[ UNION [ ALL ] ] -[ ORDER BY expression [ ASC | DESC ][, …] ] -[ LIMIT count ] -``` - -### SELECT statement and FROM clause - -Use the SQL `SELECT` statement to query data from a specific measurement or measurements. The `FROM` clause always accompanies the `SELECT` statement. - -#### Examples - -```sql -SELECT * FROM "h2o_feet" -``` -### WHERE clause - -Use the `WHERE` clause to filter results based on `fields`, `tags`, and `timestamps`. -Use predicates to evaluate each row. -Rows that evaluate as `TRUE` are returned in the result set. -Rows that evaluate as `FALSE` are omitted from the result set. - -#### Examples - -```sql -SELECT * FROM "h2o_feet" WHERE "water_level" <= 9 -``` -```sql -SELECT - * -FROM - "h2o_feet" -WHERE - "location" = 'santa_monica' - AND "level description" = 'below 3 feet' -``` - -### JOIN clause - -Use the `JOIN` clause to join data from multiple measurements (tables). -For more information about joins, see -[JOIN clause](/influxdb/cloud-serverless/reference/sql/join/). -The following join types are supported: - -{{< flex >}} -{{< flex-content "quarter" >}} - -

INNER JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="inner small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

LEFT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="left small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

RIGHT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="right small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

FULL [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="full small center" >}} -
-{{< /flex-content >}} -{{< /flex >}} - -{{< expand-wrapper >}} -{{% expand "INNER JOIN" %}} - -Inner joins combine rows from tables on the left and right side of the join -based on common column values defined in the `ON` clause. Rows that don't have -matching column values are not included in the output table. - -```sql -SELECT - * -FROM - home -INNER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "LEFT [OUTER] JOIN" %}} - -A left outer join returns all rows from the left side of the join and only -returns data from the right side of the join in rows with matching column values -defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -LEFT OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "RIGHT [OUTER] JOIN" %}} - -A right outer join returns all rows from the right side of the join and only -returns data from the left side of the join in rows with matching column values -defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -RIGHT OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "FULL [OUTER] JOIN" %}} - -A full outer join returns all data from the left and right sides of the join and -combines rows with matching column values defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -FULL OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` -{{% /expand %}} -{{< /expand-wrapper >}} - -### GROUP BY clause - -Use the `GROUP BY` clause to group query results based on specified column values. `GROUP BY` **requires** an aggregate or selector function in the `SELECT` statement. - -#### Examples - -```sql -SELECT - MEAN("water_level"), - "location" -FROM - "h2o_feet" -GROUP BY - "location" -``` - -### HAVING clause - - Use the `HAVING` clause to filter query results based on a specified condition. - The `HAVING` clause must _follow_ the `GROUP BY` clause, but _precede_ the `ORDER BY` clause. - -#### Examples - -```sql -SELECT - MEAN("water_level"), - "location" -FROM - "h2o_feet" -GROUP BY - "location" -HAVING - MEAN("water_level") > 4 -ORDER BY - "location" -``` - -### UNION clause - -The `UNION` clause combines the results of two or more `SELECT` statements without returning any duplicate rows. `UNION ALL` returns all results, including duplicates. - -#### Examples - -```sql -SELECT - 'pH' -FROM - "h2o_pH" -UNION ALL -SELECT - "location" -FROM - "h2o_quality" -``` - -### ORDER BY clause - -The `ORDER BY` clause orders results by specified columns and order. -Sort data based on fields, tags, and timestamps. -The following orders are supported: - -- `ASC`: ascending _(default)_ -- `DESC`: descending - -#### Examples - -```sql -SELECT - "water_level", - "location" -FROM - "h2o_feet" -ORDER BY - "location", - "time" DESC -``` - -### LIMIT clause - -The `LIMIT` clause limits the number of rows to return. -The defined limit should be a non-negative integer. - -#### Examples - -```sql -SELECT - "water_level", - "location" -FROM - "h2o_feet" -LIMIT - 10 -``` - -### WITH clause - -The `WITH` clause provides a way to write auxiliary statements for use in a larger query. -It can help break down large, complicated queries into simpler forms. - -```sql -WITH summary_data as -(SELECT degrees, location, time - FROM average_temperature) -SELECT * FROM summary_data -``` - -### OVER clause - -The `OVER` clause is used with SQL window functions. -A **window function** performs a calculation across a set of table rows that are related in some way to the current row. - While similar to aggregate functions, window functions output results into rows retaining their separate identities. - -```sql -SELECT - time, - water_level -FROM - ( - SELECT - time, - "water_level", - row_number() OVER ( - order by - water_level desc - ) as rn - FROM - h2o_feet - ) -WHERE - rn <= 3; -``` - -## Comments - -Use comments to describe and add detail or notes to your queries. - -- Single line comments use the double hyphen `--` symbol. Single line comments end with a line break. -- Multi-line comments begin with `/*` and end with ` */`. - -```sql --- Single-line comment - -/* - * Multi-line comment - */ -``` - -## Schema information - -{{% product-name %}} supports the following metadata schema queries: - -```sql -SHOW tables - -SHOW columns FROM -``` - -## Functions - -Following is a list of supported functions by type. - -### Aggregate functions - -An aggregate function performs a calculation or computation on a set of data values in a column and returns a single value. - -| Function | Description | -| :------- | :--------------------------------------------------------- | -| COUNT() | Returns returns the number of rows from a field or tag key | -| AVG() | Returns the average value of a column | -| SUM() | Returns the summed value of a column | -| MEAN() | Returns the mean value of a column | -| MIN() | Returns the smallest value of the selected column | -| MAX() | Returns the largest value of the selected column | - -#### Examples - -```sql - -SELECT COUNT("water_level") -FROM "h2o_feet" - -SELECT AVG("water_level"), "location" -FROM "h2o_feet" -GROUP BY "location" - -SELECT SUM("water_level"), "location" -FROM "h2o_feet" -GROUP BY "location" -``` - -### Selector functions - -Selector functions are unique to InfluxDB. They behave like aggregate functions in that they take a row of data and compute it down to a single value. However, selectors are unique in that they return a **time value** in addition to the computed value. In short, selectors return an aggregated value along with a timestamp. - -| Function | Description | -| :--------------- | :-------------------------------------------------------------- | -| SELECTOR_FIRST() | Returns the first value of a selected column and timestamp. | -| SELECTOR_LAST() | Returns the last value of a selected column and timestamp. | -| SELECTOR_MIN() | Returns the smallest value of a selected column and timestamp. | -| SELECTOR_MAX() | Returns the largest value of a selected column and timestamp. | - -#### Examples - -```sql -SELECT -SELECTOR_MAX("pH", time)['value'], -SELECTOR_MAX("pH", time)['time'] -FROM "h2o_pH" - -SELECT -SELECTOR_LAST("water_level", time)['value'], -SELECTOR_LAST("water_level", time)['time'] -FROM "h2o_feet" -WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19T00:00:00Z' - -``` - -### Date and time functions - -| Function | Description | -| :----------- | :---------------------------------------------------------------------------------------------- | -| DATE_BIN() | Bins the input timestamp into a specified interval. | -| DATE_TRUNC() | Truncates a timestamp expression based on the date part specified, such as hour, day, or month. | -| DATE_PART() | Returns the specified part of a date. | -| NOW() | Returns the current time (UTC). | - -#### Examples - -```sql -SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z'::timestamp) AS "_time", -SUM(water_level) -FROM "h2o_feet" -GROUP BY "_time" -``` - -```sql -SELECT DATE_TRUNC('month',time) AS "date", -SUM(water_level) -FROM "h2o_feet" -GROUP BY time -``` - -### Approximate functions - -| Function | Description | -| :--------------------------------- | :-------------------------------------------------------------------------------------------- | -| APPROX_MEDIAN | Returns the approximate median of input values. | -| APPROX_DISTINCT | Returns the approximate count of the number of distinct values. Implemented only for strings. | -| APPROX_PERCENTILE_CONT | Returns the approximate percentile of input values. | -| APPROX_PERCENTILE_CONT_WITH_WEIGHT | Returns the approximate percentile of input values with weight. | - - -### Math functions - -| Function | Description | -| :------- | :------------------------------------------------------------------------------- | -| ABS() | Absolute value | -| ACOS() | Inverse cosine | -| ASIN() | Inverse sine | -| ATAN() | Inverse tangent | -| ATAN2() | Inverse tangent of y / x | -| CEIL() | Returns the smallest integer value greater than or equal to the specified number | -| COS() | Cosine | -| EXP() | Exponential | -| FLOOR() | Nearest integer less than or equal to the specified number | -| LN() | Natural logarithm | -| LOG10() | Base 10 logarithm | -| LOG2() | Base 2 logarithm | -| POWER() | Returns the value of a number raised to the power of the number | -| ROUND() | Round to the nearest integer | -| SIGNUM() | Sign of the argument (-1, 0, +1) | -| SINE() | Sine | -| SQRT() | Returns the square root of a number | -| TAN() | Tangent | -| TRUNC() | Truncates a number to the specified number of decimal places | - -### Conditional functions - -| Function | Description | -| :------- | :--------------------------------------------------------------------------------------------------------- | -| COALESCE | Returns the first argument that is not null. If all arguments are null, then `COALESCE` will return nulls. | -| NULLIF | Returns a null value if value1 equals value2, otherwise returns value1. | - - -### Regular expression functions - -| Function | Description | -| :------------- | :---------------------------------------------------------------------------- | -| REGEXP_MATCH | Matches a regular expression against a string and returns matched substrings. | -| REGEXP_REPLACE | Replaces substrings that match a regular expression by a new substring. | + diff --git a/content/influxdb/cloud-serverless/reference/sql/data-types.md b/content/influxdb/cloud-serverless/reference/sql/data-types.md index 54dcc94bc..683cade76 100644 --- a/content/influxdb/cloud-serverless/reference/sql/data-types.md +++ b/content/influxdb/cloud-serverless/reference/sql/data-types.md @@ -11,208 +11,10 @@ menu: weight: 200 related: - /influxdb/cloud-serverless/query-data/sql/cast-types/ + +source: /content/shared/sql-reference/data-types.md --- -InfluxDB Cloud Serverless uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. -Data types define the type of values that can be stored in table columns. -In InfluxDB's SQL implementation, a **measurement** is structured as a table, -and **tags**, **fields** and **timestamps** are exposed as columns. - -DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. -Data types stored in InfluxDB's storage engine are mapped to SQL data types at query time. - -{{% note %}} -When performing casting operations, cast to the **name** of the data type, not the actual data type. -Names and identifiers in SQL are _case-insensitive_ by default. For example: - -```sql -SELECT - '99'::BIGINT, - '2019-09-18T00:00:00Z'::timestamp -``` - -{{% /note %}} - -- [String types](#string-types) -- [Numeric types](#numeric-types) - - [Integers](#integers) - - [Unsigned integers](#unsigned-integers) - - [Floats](#floats) -- [Date and time data types](#date-and-time-data-types) - - [Timestamp](#timestamp) - - [Interval](#interval) -- [Boolean types](#boolean-types) -- [Unsupported SQL types](#unsupported-sql-types) -- [Data types compatible with parameters](#data-types-compatible-with-parameters) - -## String types - -| Name | Data type | Description | -| :------ | :-------- | --------------------------------- | -| STRING | UTF8 | Character string, variable-length | -| CHAR | UTF8 | Character string, fixed-length | -| VARCHAR | UTF8 | Character string, variable-length | -| TEXT | UTF8 | Variable unlimited length | - -##### Example string literals - -```sql -'abcdefghijk' -'time' -'h2o_temperature' -``` - -## Numeric types - -The following numeric types are supported: - -| Name | Data type | Description | -| :-------------- | :-------- | :--------------------------- | -| BIGINT | INT64 | 64-bit signed integer | -| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | -| DOUBLE | FLOAT64 | 64-bit floating-point number | - -### Integers - -InfluxDB SQL supports the 64-bit signed integers: - -**Minimum signed integer**: `-9223372036854775808` -**Maximum signed integer**: `9223372036854775807` - -##### Example integer literals - -```sql -234 --446 -5 -``` - -### Unsigned integers - -InfluxDB SQL supports the 64-bit unsigned integers: - -**Minimum unsigned integer**: `0` -**Maximum unsigned integer**: `18446744073709551615` - -##### Example unsigned integer literals - -Unsigned integer literals are comprised of an integer cast to the `BIGINT UNSIGNED` type: - -```sql -234::BIGINT UNSIGNED -458374893::BIGINT UNSIGNED -5::BIGINT UNSIGNED -``` - -### Floats - -InfluxDB SQL supports the 64-bit double floating point values. -Floats can be a decimal point, decimal integer, or decimal fraction. - -##### Example float literals - -```sql -23.8 --446.89 -5.00 -0.033 -``` - -## Date and time data types - -InfluxDB SQL supports the following DATE/TIME data types: - -| Name | Data type | Description | -| :-------- | :-------- | :------------------------------------------------------------------- | -| TIMESTAMP | TIMESTAMP | TimeUnit::Nanosecond, None | -| INTERVAL | INTERVAL | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) | - -### Timestamp - -A time type is a single point in time using nanosecond precision. - -The following date and time formats are supported: - -```sql -YYYY-MM-DDT00:00:00.000Z -YYYY-MM-DDT00:00:00.000-00:00 -YYYY-MM-DD 00:00:00.000-00:00 -YYYY-MM-DDT00:00:00Z -YYYY-MM-DD 00:00:00.000 -YYYY-MM-DD 00:00:00 -``` - -##### Example timestamp literals - -```sql -'2023-01-02T03:04:06.000Z' -'2023-01-02T03:04:06.000-00:00' -'2023-01-02 03:04:06.000-00:00' -'2023-01-02T03:04:06Z' -'2023-01-02 03:04:06.000' -'2023-01-02 03:04:06' -``` - -### Interval - -The INTERVAL data type can be used with the following precision: - -- nanosecond -- microsecond -- millisecond -- second -- minute -- hour -- day -- week -- month -- year -- century - -##### Example interval literals - -```sql -INTERVAL '10 minutes' -INTERVAL '1 year' -INTERVAL '2 days 1 hour 31 minutes' -``` - -## Boolean types - -Booleans store TRUE or FALSE values. - -| Name | Data type | Description | -| :------ | :-------- | :------------------- | -| BOOLEAN | BOOLEAN | True or false values | - -##### Example boolean literals - -```sql -true -TRUE -false -FALSE -``` - -## Unsupported SQL types - -The following SQL types are not currently supported: - -- UUID -- BLOB -- CLOB -- BINARY -- VARBINARY -- REGCLASS -- NVARCHAR -- CUSTOM -- ARRAY -- ENUM -- SET -- DATETIME -- BYTEA - -## Data types compatible with parameters - -For information about data types that can be substituted by parameters, -see how to [use parameterized queries with SQL](/influxdb/cloud-serverless/query-data/sql/parameterized-queries/). + diff --git a/content/influxdb/cloud-serverless/reference/sql/explain.md b/content/influxdb/cloud-serverless/reference/sql/explain.md index c627f6cf2..739e97676 100644 --- a/content/influxdb/cloud-serverless/reference/sql/explain.md +++ b/content/influxdb/cloud-serverless/reference/sql/explain.md @@ -11,113 +11,10 @@ related: - /influxdb/cloud-serverless/reference/internals/query-plan/ - /influxdb/cloud-serverless/query-data/execute-queries/analyze-query-plan/ - /influxdb/cloud-serverless/query-data/execute-queries/troubleshoot/ + +source: /content/shared/sql-reference/explain.md --- -The `EXPLAIN` command returns the [logical plan](/influxdb/cloud-serverless/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb/cloud-serverless/reference/internals/query-plan/#physical-plan) for the -specified SQL statement. - -```sql -EXPLAIN [ANALYZE] [VERBOSE] statement -``` - -- [`EXPLAIN`](#explain) - - [Example `EXPLAIN`](#example-explain) -- [`EXPLAIN ANALYZE`](#explain-analyze) - - [Example `EXPLAIN ANALYZE`](#example-explain-analyze) -- [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose) - - [Example `EXPLAIN ANALYZE VERBOSE`](#example-explain-analyze-verbose) - -## `EXPLAIN` - -Returns the logical plan and physical (execution) plan of a statement. -To output more details, use `EXPLAIN VERBOSE`. - -`EXPLAIN` doesn't execute the statement. -To execute the statement and view runtime metrics, use [`EXPLAIN ANALYZE`](#explain-analyze). - -### Example `EXPLAIN` - -```sql -EXPLAIN -SELECT - room, - avg(temp) AS temp -FROM home -GROUP BY room -``` - -{{< expand-wrapper >}} -{{% expand "View `EXPLAIN` example output" %}} - -| | plan_type | plan | -|---:|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 0 | logical_plan | Projection: home.room, AVG(home.temp) AS temp | -| | | Aggregate: groupBy=[[home.room]], aggr=[[AVG(home.temp)]] | -| | | TableScan: home projection=[room, temp] | -| 1 | physical_plan | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp] | -| | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)] | -| | | CoalesceBatchesExec: target_batch_size=8192 | -| | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8 | -| | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)] | -| | | ParquetExec: file_groups={8 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet, 70434/116281/b7a9e7c57fbfc3bba9427e4b3e35c89e001e2e618b0c7eb9feb4d50a3932f4db/d29370d4-262f-0d32-2459-fe7b099f682f.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], ...]}, projection=[room, temp] | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `EXPLAIN ANALYZE` - -Executes a statement and returns the execution plan and runtime metrics of the statement. -The report includes the [logical plan](/influxdb/cloud-serverless/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb/cloud-serverless/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution. - -If the plan requires reading lots of data files, `EXPLAIN` and `EXPLAIN ANALYZE` may truncate the list of files in the report. -To output more information, including intermediate plans and paths for all scanned Parquet files, use [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose). - -### Example `EXPLAIN ANALYZE` - -```sql -EXPLAIN ANALYZE -SELECT - room, - avg(temp) AS temp -FROM home -WHERE time >= '2023-01-01' AND time <= '2023-12-31' -GROUP BY room -``` - -{{< expand-wrapper >}} -{{% expand "View `EXPLAIN ANALYZE` example output" %}} - -| | plan_type | plan | -|---:|:------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 0 | Plan with Metrics | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp], metrics=[output_rows=2, elapsed_compute=4.768µs] | -| | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=140.405µs] | -| | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=2, elapsed_compute=6.821µs] | -| | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=2, elapsed_compute=18.408µs, repart_time=59.698µs, fetch_time=1.057882762s, send_time=5.83µs] | -| | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=137.577µs] | -| | | RepartitionExec: partitioning=RoundRobinBatch(8), input_partitions=6, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=46, elapsed_compute=26.637µs, repart_time=6ns, fetch_time=399.971411ms, send_time=6.658µs] | -| | | ProjectionExec: expr=[room@0 as room, temp@2 as temp], metrics=[output_rows=46, elapsed_compute=3.102µs] | -| | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=46, elapsed_compute=25.585µs] | -| | | FilterExec: time@1 >= 1672531200000000000 AND time@1 <= 1703980800000000000, metrics=[output_rows=46, elapsed_compute=26.51µs] | -| | | ParquetExec: file_groups={6 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], ...]}, projection=[room, time, temp], output_ordering=[room@0 ASC, time@1 ASC], predicate=time@6 >= 1672531200000000000 AND time@6 <= 1703980800000000000, pruning_predicate=time_max@0 >= 1672531200000000000 AND time_min@1 <= 1703980800000000000, required_guarantees=[], metrics=[output_rows=46, elapsed_compute=6ns, predicate_evaluation_errors=0, bytes_scanned=3279, row_groups_pruned_statistics=0, file_open_errors=0, file_scan_errors=0, pushdown_rows_filtered=0, num_predicate_creation_errors=0, row_groups_pruned_bloom_filter=0, page_index_rows_filtered=0, time_elapsed_opening=398.462968ms, time_elapsed_processing=1.626106ms, time_elapsed_scanning_total=1.36822ms, page_index_eval_time=33.474µs, pushdown_eval_time=14.267µs, time_elapsed_scanning_until_data=1.27694ms] | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `EXPLAIN ANALYZE VERBOSE` - -Executes a statement and returns the execution plan, runtime metrics, and additional details helpful for debugging the statement. - -The report includes the following: - -- the [logical plan](/influxdb/cloud-serverless/reference/internals/query-plan/#logical-plan) -- the [physical plan](/influxdb/cloud-serverless/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution -- Information truncated in the `EXPLAIN` report--for example, the paths for all [Parquet files retrieved for the query](/influxdb/cloud-serverless/reference/internals/query-plan/#file_groups). -- All intermediate physical plans that DataFusion and the [Querier](/influxdb/cloud-serverless/reference/internals/storage-engine/#querier) generate before generating the final physical plan--helpful in debugging to see when an [`ExecutionPlan` node](/influxdb/cloud-serverless/reference/internals/query-plan/#executionplan-nodes) is added or removed, and how InfluxDB optimizes the query. - -### Example `EXPLAIN ANALYZE VERBOSE` - -```SQL -EXPLAIN ANALYZE VERBOSE SELECT temp FROM home -WHERE time >= now() - INTERVAL '7 days' AND room = 'Kitchen' -ORDER BY time -``` + diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/_index.md b/content/influxdb/cloud-serverless/reference/sql/functions/_index.md index 845b45591..ba5d2c8aa 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/_index.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/_index.md @@ -9,6 +9,10 @@ menu: parent: SQL reference identifier: sql-functions weight: 220 + +source: /content/shared/sql-reference/functions/_index.md --- -{{< children >}} \ No newline at end of file + \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/aggregate.md b/content/influxdb/cloud-serverless/reference/sql/functions/aggregate.md index 7aaa1799d..8991f33db 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/aggregate.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/aggregate.md @@ -10,1459 +10,10 @@ menu: weight: 301 related: - /influxdb/cloud-serverless/query-data/sql/aggregate-select/ + +source: /content/shared/sql-reference/functions/aggregate.md --- -SQL aggregate functions aggregate values in a specified column for each -group or SQL partition and return a single row per group containing the -aggregate value. - -- [General aggregate functions](#general-aggregate-functions) - - [array_agg](#array_agg) - - [avg](#avg) - - [bit_and](#bit_and) - - [bit_or](#bit_or) - - [bit_xor](#bit_xor) - - [bool_and](#bool_and) - - [bool_or](#bool_or) - - [count](#count) - - [first_value](#first_value) - - [last_value](#last_value) - - [max](#max) - - [mean](#mean) - - [median](#median) - - [min](#min) - - [sum](#sum) -- [Statistical aggregate functions](#statistical-aggregate-functions) - - [corr](#corr) - - [covar](#covar) - - [covar_pop](#covar_pop) - - [covar_samp](#covar_samp) - - [regr_avgx](#regr_avgx) - - [regr_avgy](#regr_avgy) - - [regr_count](#regr_count) - - [regr_intercept](#regr_intercept) - - [regr_r2](#regr_r2) - - [regr_slope](#regr_slope) - - [regr_sxx](#regr_sxx) - - [regr_syy](#regr_syy) - - [regr_sxy](#regr_sxy) - - [stddev](#stddev) - - [stddev_pop](#stddev_pop) - - [stddev_samp](#stddev_samp) - - [var](#var) - - [var_pop](#var_pop) - - [var_samp](#var_samp) -- [Approximate aggregate functions](#approximate-aggregate-functions) - - [approx_distinct](#approx_distinct) - - [approx_median](#approx_median) - - [approx_percentile_cont](#approx_percentile_cont) - - [approx_percentile_cont_with_weight](#approx_percentile_cont_with_weight) - ---- - -## General aggregate functions - -- [array_agg](#array_agg) -- [avg](#avg) -- [bit_and](#bit_and) -- [bit_or](#bit_or) -- [bit_xor](#bit_xor) -- [bool_and](#bool_and) -- [bool_or](#bool_or) -- [count](#count) -- [first_value](#first_value) -- [last_value](#last_value) -- [max](#max) -- [mean](#mean) -- [median](#median) -- [min](#min) -- [sum](#sum) - -### array_agg - -Returns an array created from the expression elements. - -{{% note %}} -`array_agg` returns a `LIST` arrow type which is not supported by InfluxDB. -To use with InfluxDB, use bracket notation to reference the index of an element -in the returned array. Arrays are 1-indexed. -{{% /note %}} - -```sql -array_agg(expression) -``` - -#### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `array_agg` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - array_agg(temp)[3] AS '3rd_temp' -FROM home -GROUP BY room -``` - -| room | 3rd_temp | -| :---------- | -------: | -| Kitchen | 22.7 | -| Living Room | 21.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### avg - -Returns the average of numeric values in the specified column. - -```sql -avg(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -##### Aliases - -- `mean` - -{{< expand-wrapper >}} -{{% expand "View `avg` query example" %}} - -```sql -SELECT - location, - avg(water_level) AS water_level_avg -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_avg | -| :----------- | -----------------: | -| coyote_creek | 5.359142420303919 | -| santa_monica | 3.5307120942458843 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_and - -Computes the bitwise `AND` of all non-null input values. - -```sql -bit_and(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_and` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_and(precip::BIGINT) AS precip_bit_and -FROM weather -GROUP BY location -``` - -| location | precip_bit_and | -| :------------ | -------------: | -| Concord | 0 | -| Hayward | 0 | -| San Francisco | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_or - -Computes the bitwise OR of all non-null input values. - -```sql -bit_or(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_or` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_or(precip::BIGINT) AS precip_bit_or -FROM weather -GROUP BY location -``` - -| location | precip_bit_or | -| :------------ | ------------: | -| Concord | 7 | -| Hayward | 7 | -| San Francisco | 7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_xor - -Computes the bitwise exclusive OR of all non-null input values. - -```sql -bit_xor(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_xor` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_xor(precip::BIGINT) AS precip_bit_xor -FROM weather -GROUP BY location -``` - -| location | precip_bit_xor | -| :------------ | -------------: | -| Concord | 4 | -| Hayward | 6 | -| San Francisco | 4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bool_and - -Returns `true` if _all_ non-null input values are `true`, otherwise returns `false`. - -```sql -bool_and(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bool_and` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bool_and(precip > 0) AS precip_bool_and -FROM weather -GROUP BY location -``` - -| location | precip_bool_and | -| :------------ | --------------: | -| Concord | false | -| Hayward | false | -| San Francisco | false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bool_or - -Returns `true` if _any_ non-null input value is `true`, otherwise returns `false`. - -```sql -bool_or(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bool_or` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bool_or(precip > 0) AS precip_bool_or -FROM weather -GROUP BY location -``` - -| location | precip_bool_or | -| :------------ | -------------: | -| Concord | true | -| Hayward | true | -| San Francisco | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### count - -Returns the number of rows in the specified column. - -Count includes _null_ values in the total count. -To exclude _null_ values from the total count, include ` IS NOT NULL` -in the `WHERE` clause. - -```sql -count(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `count` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - count(precip) AS precip_count -FROM weather -GROUP BY location -``` - -| location | precip_count | -| :------------ | -----------: | -| Concord | 1094 | -| Hayward | 1096 | -| San Francisco | 1096 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### first_value - -Returns the first element in an aggregation group according to the specified ordering. -If no ordering is specified, returns an arbitrary element from the group. - -```sql -first_value(expression [ORDER BY expression]) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `first_value` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - first_value(temp_max ORDER BY time) AS temp_max_first_value -FROM weather -GROUP BY location -``` - -| location | temp_max_first_value | -| :------------ | -------------------: | -| Concord | 59 | -| Hayward | 57 | -| San Francisco | 66 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### last_value - -Returns the last element in an aggregation group according to the specified ordering. -If no ordering is specified, returns an arbitrary element from the group. - -```sql -last_value(expression [ORDER BY expression]) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `last_value` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - last_value(temp_max ORDER BY time) AS temp_max_last_value -FROM weather -GROUP BY location -``` - -| location | temp_max_last_value | -| :------------ | ------------------: | -| Concord | 59 | -| Hayward | 58 | -| San Francisco | 62 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### max - -Returns the maximum value in the specified column. - -```sql -max(expression) -``` - -_To return both the maximum value and its associated timestamp, use -[`selector_max`](/influxdb/cloud-serverless/reference/sql/functions/selector/#selector_max)._ - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `max` query example" %}} - -```sql -SELECT - location, - max(water_level) AS water_level_max -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_max | -| :----------- | --------------: | -| santa_monica | 7.205 | -| coyote_creek | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### mean - -_Alias of [avg](#avg)._ - -### median - -Returns the median value in the specified column. - -``` -median(expression) -``` - -#### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `median` query example" %}} - -```sql -SELECT - location, - median(water_level) AS water_level_max -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_median | -| :----------- | -----------------: | -| coyote_creek | 5.4645 | -| santa_monica | 3.471 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### min - -Returns the minimum value in the specified column. - -```sql -min(expression) -``` - -_To return both the minimum value and its associated timestamp, use -[`selector_max`](/influxdb/cloud-serverless/reference/sql/functions/selector/#selector_min)._ - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `min` query example" %}} - -```sql -SELECT - location, - min(water_level) AS water_level_min -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_min | -| :----------- | --------------: | -| coyote_creek | -0.61 | -| santa_monica | -0.243 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### sum - -Returns the sum of all values in the specified column. - -```sql -sum(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sum` query example" %}} - -```sql -SELECT - location, - sum(water_level) AS water_level_sum -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_sum | -| :----------- | -----------------: | -| santa_monica | 27024.070369358 | -| coyote_creek | 40750.918963991004 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - -## Statistical aggregate functions - -- [corr](#corr) -- [covar](#covar) -- [covar_pop](#covar_pop) -- [covar_samp](#covar_samp) -- [regr_avgx](#regr_avgx) -- [regr_avgy](#regr_avgy) -- [regr_count](#regr_count) -- [regr_intercept](#regr_intercept) -- [regr_r2](#regr_r2) -- [regr_slope](#regr_slope) -- [regr_sxx](#regr_sxx) -- [regr_syy](#regr_syy) -- [regr_sxy](#regr_sxy) -- [stddev](#stddev) -- [stddev_pop](#stddev_pop) -- [stddev_samp](#stddev_samp) -- [var](#var) -- [var_pop](#var_pop) -- [var_samp](#var_samp) - -### corr - -Returns the coefficient of correlation between two numeric values. - -```sql -corr(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `corr` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - corr(hum, temp) AS correlation -FROM home -GROUP BY room -``` - -| room | correlation | -| :---------- | ------------------: | -| Living Room | 0.43665270457835725 | -| Kitchen | 0.6741766954929539 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar - -Returns the covariance of a set of number pairs. - -```sql -covar(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar(hum, temp) AS covar -FROM home -GROUP BY room -``` - -| room | covar | -| :---------- | ------------------: | -| Living Room | 0.03346153846153959 | -| Kitchen | 0.11134615384615432 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar_pop - -Returns the population covariance of a set of number pairs. - -```sql -covar_pop(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar_pop(hum, temp) AS covar_pop -FROM home -GROUP BY room -``` - -| room | covar_pop | -| :---------- | -------------------: | -| Kitchen | 0.10278106508875783 | -| Living Room | 0.030887573964498087 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar_samp - -Returns the sample covariance of a set of number pairs. - -```sql -covar_samp(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar_samp(hum, temp) AS covar_samp -FROM home -GROUP BY room -``` - -| room | covar_samp | -| :---------- | ------------------: | -| Kitchen | 0.11134615384615432 | -| Living Room | 0.03346153846153959 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_avgx - -Computes the average of the independent variable (input), `expression_x`, for the -non-null dependent variable, `expression_y`. - -```sql -regr_avgx(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_avgx` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_avgx(temp_min, temp_max) AS temp_regr_avgx -FROM weather -GROUP BY location -``` - -| location | temp_regr_avgx | -| :------------ | ----------------: | -| Concord | 75.54379562043796 | -| Hayward | 69.14808043875686 | -| San Francisco | 67.59945255474454 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_avgy - -Computes the average of the dependent variable (output), `expression_y`, for the -non-null dependent variable, `expression_y`. - -```sql -regr_avgy(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_avgy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_avgy(temp_min, temp_max) AS temp_regr_avgy -FROM weather -GROUP BY location -``` - -| location | temp_regr_avgy | -| :------------ | -----------------: | -| Concord | 50.153284671532845 | -| Hayward | 50.913162705667276 | -| San Francisco | 51.52372262773722 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_count - -Counts the number of non-null paired data points. - -```sql -regr_count(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_count` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_count(temp_min, temp_max) AS temp_regr_count -FROM weather -GROUP BY location -``` - -| location | temp_regr_count | -| :------------ | --------------: | -| Concord | 1096 | -| Hayward | 1094 | -| San Francisco | 1096 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_intercept - -Computes the y-intercept of the linear regression line. -For the equation `(y = kx + b)`, this function returns `b`. - -```sql -regr_intercept(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_intercept` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_intercept(temp_min, temp_max) AS temp_regr_intercept -FROM weather -GROUP BY location -``` - -| location | temp_regr_intercept | -| :------------ | ------------------: | -| Concord | 11.636281392206769 | -| Hayward | 12.876956842745152 | -| San Francisco | 19.125237647086607 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_r2 - -Computes the square of the correlation coefficient between the independent and -dependent variables. - -```sql -regr_r2(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_r2` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_r2(temp_min, temp_max) AS temp_regr_r2 -FROM weather -GROUP BY location -``` - -| location | temp_regr_r2 | -| :------------ | -----------------: | -| Concord | 0.6474628308450441 | -| Hayward | 0.5166296626320914 | -| San Francisco | 0.5032317511200297 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_slope - -Returns the slope of the linear regression line for non-null pairs in aggregate columns. -Given input column `Y` and `X`: `regr_slope(Y, X)` returns the slope -(`k` in `Y = k*X + b`) using minimal RSS fitting. - -``` sql -regr_slope(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Y expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: X expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_slope` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_slope(temp_min, temp_max) AS temp_regr_slope -FROM weather -GROUP BY location -``` - -| location | temp_regr_slope | -| :------------ | -----------------: | -| Concord | 0.5098632252058237 | -| Hayward | 0.5500688612261629 | -| San Francisco | 0.4792714105844738 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_sxx - -Computes the sum of squares of the independent variable. - -```sql -regr_sxx(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_sxx` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_sxx(temp_min, temp_max) AS temp_regr_sxx -FROM weather -GROUP BY location -``` - -| location | temp_regr_sxx | -| :------------ | -----------------: | -| Concord | 210751.89781021897 | -| Hayward | 99644.01096892142 | -| San Francisco | 77413.15967153282 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_syy - -Computes the sum of squares of the dependent variable. - -```sql -regr_syy(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_syy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_syy(temp_min, temp_max) AS temp_regr_syy -FROM weather -GROUP BY location -``` - -| location | temp_regr_syy | -| :------------ | -----------------: | -| Concord | 84618.24817518248 | -| Hayward | 58358.750457038404 | -| San Francisco | 35335.38321167884 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_sxy - -Computes the sum of products of paired data points. - -```sql -regr_sxy(expression_y, expression_x) -``` - -#### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_sxy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_sxy(temp_min, temp_max) AS temp_regr_sxy -FROM weather -GROUP BY location -``` - -| location | temp_regr_sxy | -| :------------ | -----------------: | -| Concord | 107454.64233576645 | -| Hayward | 54811.06764168191 | -| San Francisco | 37101.914233576645 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev - -Returns the standard deviation of a set of numbers. - -```sql -stddev(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev(co) AS stddev -FROM home -GROUP BY room -``` - -| room | stddev | -| :---------- | ----------------: | -| Living Room | 5.885662718931967 | -| Kitchen | 9.321879418735037 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev_pop - -Returns the population standard deviation of a set of numbers. - -```sql -stddev_pop(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev_pop(co) AS stddev_pop -FROM home -GROUP BY room -``` - -| room | stddev_pop | -| :---------- | ----------------: | -| Kitchen | 8.956172047894082 | -| Living Room | 5.654761830612032 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev_samp - -Returns the sample standard deviation of a set of numbers. - -```sql -stddev_samp(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev_samp(co) AS stddev_samp -FROM home -GROUP BY room -``` - -| room | stddev_samp | -| :---------- | ----------------: | -| Living Room | 5.885662718931967 | -| Kitchen | 9.321879418735037 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var - -Returns the statistical variance of a set of numbers. - -```sql -var(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var(co) AS var -FROM home -GROUP BY room -``` - -| room | var | -| :---------- | ----------------: | -| Living Room | 34.64102564102564 | -| Kitchen | 86.89743589743587 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var_pop - -Returns the statistical population variance of a set of numbers. - -```sql -var_pop(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var_pop(co) AS var_pop -FROM home -GROUP BY room -``` - -| room | var_pop | -| :---------- | -----------------: | -| Living Room | 31.976331360946745 | -| Kitchen | 80.21301775147927 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var_samp - -Returns the statistical sample variance of a set of numbers. - -```sql -var_samp(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var_samp(co) AS var_samp -FROM home -GROUP BY room -``` - -| room | var_samp | -| :---------- | ----------------: | -| Kitchen | 86.89743589743587 | -| Living Room | 34.64102564102564 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Approximate aggregate functions - -- [approx_distinct](#approx_distinct) -- [approx_median](#approx_median) -- [approx_percentile_cont](#approx_percentile_cont) -- [approx_percentile_cont_with_weight](#approx_percentile_cont_with_weight) - -### approx_distinct - -Returns the approximate number of distinct input values calculated using the -HyperLogLog algorithm. - -```sql -approx_distinct(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `approx_distinct` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_distinct(co::string) AS approx_distinct -FROM home -GROUP BY room -``` - -| room | approx_distinct | -| :---------- | --------------: | -| Living Room | 7 | -| Kitchen | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_median - -Returns the approximate median (50th percentile) of input values. -It is an alias of `approx_percentile_cont(x, 0.5)`. - -```sql -approx_median(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `approx_median` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_median(temp) AS approx_median -FROM home -GROUP BY room -``` - -| room | approx_median | -| :---------- | ------------: | -| Kitchen | 22.7 | -| Living Room | 22.3 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_percentile_cont - -Returns the approximate percentile of input values using the t-digest algorithm. - -```sql -approx_percentile_cont(expression, percentile, centroids) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). -- **centroids**: Number of centroids to use in the t-digest algorithm. _Default is 100_. - - If there are this number or fewer unique values, you can expect an exact result. - A higher number of centroids results in a more accurate approximation, but - requires more memory to compute. - -{{< expand-wrapper >}} -{{% expand "View `approx_percentile_cont` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_percentile_cont(temp, 0.99) AS "99th_percentile" -FROM home -GROUP BY room -``` - -| room | 99th_percentile | -| :---------- | --------------: | -| Kitchen | 23.3 | -| Living Room | 22.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_percentile_cont_with_weight - -Returns the weighted approximate percentile of input values using the -t-digest algorithm. - -```sql -approx_percentile_cont_with_weight(expression, weight, percentile) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **weight**: Expression to use as weight. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). - -{{< expand-wrapper >}} -{{% expand "View `approx_percentile_cont_with_weight` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_percentile_cont_with_weight(temp, co, 0.99) AS "co_weighted_99th_percentile" -FROM home -GROUP BY room -``` - -| room | co_weighted_99th_percentile | -| :---------- | --------------------------: | -| Kitchen | 23.3 | -| Living Room | 22.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/conditional.md b/content/influxdb/cloud-serverless/reference/sql/functions/conditional.md index b51b81e69..5331b59c2 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/conditional.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/conditional.md @@ -8,137 +8,10 @@ menu: name: Conditional parent: sql-functions weight: 306 + +source: /content/shared/sql-reference/functions/conditional.md --- -The InfluxDB SQL implementation supports the following conditional functions for -conditionally handling _null_ values: - -- [coalesce](#coalesce) -- [ifnull](#ifnull) -- [nullif](#nullif) -- [nvl](#nvl) - -## coalesce - -Returns the first of its arguments that is not _null_. -Returns _null_ if all arguments are _null_. -This function is often used to substitute a default value for _null_ values. - -```sql -coalesce(expression1[, ..., expression_n]) -``` - -##### Arguments - -- **expression1, expression_n**: - Expression to use if previous expressions are _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. - Pass as many expression arguments as necessary. - -{{< expand-wrapper >}} -{{% expand "View `coalesce` query example" %}} - -```sql -SELECT - val1, - val2, - val3, - coalesce(val1, val2, val3, 'quz') AS coalesce -FROM - (values ('foo', 'bar', 'baz'), - (NULL, 'bar', 'baz'), - (NULL, NULL, 'baz'), - (NULL, NULL, NULL) - ) data(val1, val2, val3) -``` - -| val1 | val2 | val3 | coalesce | -| :--: | :--: | :--: | :------: | -| foo | bar | baz | foo | -| | bar | baz | bar | -| | | baz | baz | -| | | | quz | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ifnull - -_Alias of [nvl](#nvl)._ - -## nullif - -Returns _null_ if _expression1_ equals _expression2_; otherwise it returns _expression1_. -This can be used to perform the inverse operation of [`coalesce`](#coalesce). - -```sql -nullif(expression1, expression2) -``` - -##### Arguments - -- **expression1**: Expression to compare and return if equal to expression2. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression2**: Expression to compare to expression1. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nullif` query example" %}} - -```sql -SELECT - value, - nullif(value, 'baz') AS nullif -FROM - (values ('foo'), - ('bar'), - ('baz') - ) data(value) -``` - -| value | nullif | -| :---- | :----- | -| foo | foo | -| bar | bar | -| baz | | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## nvl - -Returns _expression2_ if _expression1_ is _null_; otherwise it returns _expression1_. - -```sql -nvl(expression1, expression2) -``` - -##### Arguments - -- **expression1**: Return this expression if not _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression2**: Return this expression if _expression1_ is _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nvl` query example" %}} - -```sql -SELECT - value, - nvl(value, 'baz') AS nvl -FROM - (values ('foo'), - ('bar'), - (NULL) - ) data(value) -``` - -| value | nvl | -| :---- | :-- | -| foo | foo | -| bar | bar | -| | baz | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/math.md b/content/influxdb/cloud-serverless/reference/sql/functions/math.md index 74e0f19e9..e9140905f 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/math.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/math.md @@ -8,1276 +8,10 @@ menu: name: Math parent: sql-functions weight: 306 + +source: /content/shared/sql-reference/functions/math.md --- -The InfluxDB SQL implementation supports the following math functions for -performing mathematic operations: - -- [abs](#abs) -- [acos](#acos) -- [acosh](#acosh) -- [asin](#asin) -- [asinh](#asinh) -- [atan](#atan) -- [atanh](#atanh) -- [atan2](#atan2) -- [cbrt](#cbrt) -- [ceil](#ceil) -- [cos](#cos) -- [cosh](#cosh) -- [degrees](#degrees) -- [exp](#exp) -- [factorial](#factorial) -- [floor](#floor) -- [gcd](#gcd) -- [isnan](#isnan) -- [iszero](#iszero) -- [lcm](#lcm) -- [ln](#ln) -- [log](#log) -- [log10](#log10) -- [log2](#log2) -- [nanvl](#nanvl) -- [pi](#pi) -- [power](#power) -- [pow](#pow) -- [radians](#radians) -- [random](#random) -- [round](#round) -- [signum](#signum) -- [sin](#sin) -- [sinh](#sinh) -- [sqrt](#sqrt) -- [tan](#tan) -- [tanh](#tanh) -- [trunc](#trunc) - -## abs - -Returns the absolute value of a number. - -```sql -abs(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `abs` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT abs(temp) AS abs FROM home LIMIT 3 -``` - -| abs | -| ---: | -| 21 | -| 23 | -| 22.7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## acos - -Returns the arc cosine or inverse cosine of a number. - -```sql -acos(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `acos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT acos(temp * .01) AS acos FROM home LIMIT 3 -``` - -| acos | -| -----------------: | -| 1.359221367036801 | -| 1.3387186439321834 | -| 1.3418001704498232 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## acosh - -Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. - -```sql -acosh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `acosh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT acosh(temp) AS acosh FROM home LIMIT 3 -``` - -| acosh | -| -----------------: | -| 3.737102242198924 | -| 3.8281684713331012 | -| 3.8150265878962055 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## asin - -Returns the arc sine or inverse sine of a number. - -```sql -asin(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `asin` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT asin(temp * .01) AS asin FROM home LIMIT 3 -``` - -| asin | -| ------------------: | -| 0.2115749597580956 | -| 0.23207768286271319 | -| 0.22899615634507337 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## asinh - -Returns the area hyperbolic sine or inverse hyperbolic sine of a number. - -```sql -asinh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `asinh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT asinh(temp) AS asinh FROM home LIMIT 3 -``` - -| asinh | -| -----------------: | -| 3.7382360302615427 | -| 3.8291136516208812 | -| 3.8159969160459988 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atan - -Returns the arc tangent or inverse tangent of a number. - -```sql -atan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atan` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atan(temp * .01) AS atan FROM home LIMIT 3 -``` - -| atan | -| ------------------: | -| 0.206992194219821 | -| 0.22606838799388393 | -| 0.22321725383717603 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atanh - -Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. - -```sql -atanh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atanh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atanh(temp * .01) AS atanh FROM home LIMIT 3 -``` - -| atanh | -| ------------------: | -| 0.21317134656485978 | -| 0.2341894667593668 | -| 0.23102419806174476 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atan2 - -Returns the arc tangent or inverse tangent of `expression_y / expression_x`. - -```sql -atan2(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: First numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Second numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atan2` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atan2(temp, hum) AS atan2 FROM home LIMIT 3 -``` - -| atan2 | -| -----------------: | -| 0.5292859396993504 | -| 0.5660139100632452 | -| 0.5613335864315844 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cbrt - -Returns the cube root of a number. - -```sql -cbrt(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cbrt` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cbrt(temp) AS cbrt FROM home LIMIT 3 -``` - -| cbrt | -| -----------------: | -| 2.7589241763811208 | -| 2.843866979851566 | -| 2.831448188528187 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ceil - -Returns the nearest integer greater than or equal to a number. - -```sql -ceil(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `ceil` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT ceil(temp) AS ceil FROM home LIMIT 3 -``` - -| ceil | -| ---: | -| 21 | -| 23 | -| 23 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cos - -Returns the cosine of a number. - -```sql -cos(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cos(temp) AS cos FROM home LIMIT 3 -``` - -| cos | -| ------------------: | -| -0.5477292602242684 | -| -0.5328330203333975 | -| -0.7591100556583898 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cosh - -Returns the hyperbolic cosine of a number. - -```sql -cosh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cosh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cosh(temp) AS cosh FROM home LIMIT 3 -``` - -| cosh | -| -----------------: | -| 659407867.2416073 | -| 4872401723.124452 | -| 3609563974.9715896 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## degrees - -Converts radians to degrees. - -```sql -degrees(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `degrees` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT degrees(a) AS degrees FROM numbers LIMIT 3 -``` - -| degrees | -| ------------------: | -| 19.428488139031185 | -| -44.403317464348774 | -| -52.771542485064785 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## exp - -Returns the base-e exponential of a number. - -```sql -exp(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to use as the exponent. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `exp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT exp(temp) AS exp FROM home LIMIT 3 -``` - -| exp | -| -----------------: | -| 1318815734.4832146 | -| 9744803446.248903 | -| 7219127949.943179 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## factorial - -Returns 1 if value is less than 2. - -```sql -factorial(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `factorial` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT factorial((b + 2)::BIGINT) AS factorial FROM numbers LIMIT 3 -``` - -| factorial | -| --------: | -| 1 | -| 2 | -| 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## floor - -Returns the nearest integer less than or equal to a number. - -```sql -floor(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `floor` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT floor(temp) AS floor FROM home LIMIT 3 -``` - -| floor | -| ----: | -| 21 | -| 23 | -| 22 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## gcd - -Returns the greatest common divisor of `expression_x` and `expression_y`. -Returns `0` if both inputs are zero. - -```sql -gcd(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: First numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Second numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `gcd` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT gcd((a * 5)::BIGINT, (b * 5)::BIGINT) AS gcd FROM numbers LIMIT 3 -``` - -| gcd | -| --------: | -| 1 | -| 3 | -| 2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## isnan - -Returns `true` if a given number is ±NaN, otherwise returns `false`. - -```sql -isnan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Must be a float (`DOUBLE`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `isnan` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/cloud-serverless/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT isnan(a) -FROM - (VALUES (4.56), - ('NaN'::DOUBLE), - (16.2) - ) AS data(a) -``` - -| isnan | -| ----: | -| false | -| true | -| false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## iszero - -Returns `true` if the given number is ±0.0, otherwise returns `false`. - -```sql -iszero(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `iszero` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/cloud-serverless/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT iszero(a) -FROM - (VALUES (0), - (1), - (2) - ) AS data(a) -``` - -| iszero | -| -----: | -| true | -| false | -| false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lcm - -Returns the least common multiple of `expression_x` and `expression_y`. -Returns `0` if either input is zero. - -```sql -lcm(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: First numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Second numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `lcm` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT lcm((a * 10)::BIGINT, (b * 10)::BIGINT) AS lcm FROM numbers LIMIT 3 -``` - -| lcm | -| --: | -| 3 | -| 7 | -| 36 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ln - -Returns the natural logarithm of a number. - -```sql -ln(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `ln` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT ln(temp) AS ln FROM home LIMIT 3 -``` - -| ln | -| -----------------: | -| 3.044522437723423 | -| 3.1354942159291497 | -| 3.122364924487357 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log - -Returns the base-x logarithm of a number. - -``` -log([base, ]numeric_expression) -``` - -#### Arguments - -- **base**: Base numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - Default is `10`. -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - temp, - log(2, temp) AS temp_log2, - log(4, temp) AS temp_log4, - log(temp) AS temp_log10 -FROM home -LIMIT 3 -``` - -| temp | temp_log2 | temp_log4 | temp_log10 | -| :--- | ----------------: | -----------------: | -----------------: | -| 21 | 4.392317422778761 | 2.1961587113893803 | 1.322219294733919 | -| 23 | 4.523561956057013 | 2.2617809780285065 | 1.3617278360175928 | -| 22.7 | 4.504620392403553 | 2.2523101962017766 | 1.3560258571931225 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log10 - -Returns the base-10 logarithm of a number. - -```sql -log10(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log10` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT log10(temp) AS log10 FROM home LIMIT 3 -``` - -| log10 | -| -----------------: | -| 1.3222192947339193 | -| 1.3617278360175928 | -| 1.3560258571931227 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log2 - -Returns the base-2 logarithm of a number. - -```sql -log2(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log2` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT log2(temp) AS log2 FROM home LIMIT 3 -``` - -| log2 | -| ----------------: | -| 4.392317422778761 | -| 4.523561956057013 | -| 4.504620392403552 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## nanvl - -Returns the first argument if it’s not `±NaN`. -Otherwise returns the second argument. - -```sql -nanvl(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: Numeric expression to return if it’s not `NaN`. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Numeric expression to return if the first expression is `NaN`. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nanvl` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/cloud-serverless/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT nanvl(a, 0.0) AS nanvl -FROM - (VALUES (4.56), - ('NaN'::DOUBLE), - (16.2) - ) AS data(a) -``` - -| nanvl | -| ----: | -| 4.56 | -| 0 | -| 16.2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## pi - -Returns an approximate value of π. - -```sql -pi() -``` - -{{< expand-wrapper >}} -{{% expand "View `pi` query example" %}} - -```sql -SELECT pi() AS pi -``` - -| pi | -| :---------------- | -| 3.141592653589793 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## power - -Returns a base expression raised to the power of an exponent. - -```sql -power(base, exponent) -``` - -##### Aliases - -- `pow` - -##### Arguments - -- **base**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **exponent**: Exponent numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `power` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT power(temp, hum * .1) AS power FROM home LIMIT 3 -``` - -| power | -| -----------------: | -| 55817.099910217476 | -| 85007.01501569824 | -| 78569.38332452129 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `pow` - -_Alias of [power](#power)._ - -## radians - -Converts degrees to radians. - -```sql -radians(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `radians` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT radians(b) AS radians FROM numbers LIMIT 3 -``` - -| radians | -| --------------------: | -| -0.0028561101762876 | -| 0.0023917008411179744 | -| -0.008428949313343818 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## random - -Returns a random float value between 0 and 1. -The random seed is unique to each row. - -```sql -random() -``` - -{{< expand-wrapper >}} -{{% expand "View `random` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT temp * random() AS random FROM home LIMIT 3 -``` - -{{% note %}} -Due to the nature of the function, your results will not match the results below. -{{% /note %}} - -| random | -| -----------------: | -| 0.5030770374815072 | -| 12.938847036567514 | -| 2.8204596545385385 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## round - -Rounds a number to the nearest integer. - -```sql -round(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `round` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT round(temp) AS round FROM home LIMIT 3 -``` - -| round | -| ----: | -| 21 | -| 23 | -| 23 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## signum - -Returns the sign of a number. -Negative numbers return `-1`. -Zero and positive numbers return `1`. - -```sql -signum(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `signum` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT signum(temp - 23) AS signum FROM home LIMIT 3 -``` - -| signum | -| -----: | -| -1 | -| 1 | -| -1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sin - -Returns the sine of a number. - -```sql -sin(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sin` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sin(temp) AS sin FROM home LIMIT 3 -``` - -| sin | -| ------------------: | -| 0.8366556385360561 | -| -0.8462204041751706 | -| -0.6509623056662469 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sinh - -Returns the hyperbolic sine of a number. - -```sql -sinh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sinh ` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sinh(temp) AS sinh FROM home LIMIT 3 -``` - -| sinh | -| -----------------: | -| 659407867.2416073 | -| 4872401723.124452 | -| 3609563974.9715896 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sqrt - -Returns the square root of a number. - -```sql -sqrt(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sqrt` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sqrt(temp) AS sqrt FROM home LIMIT 3 -``` - -| sqrt | -| ----------------: | -| 4.58257569495584 | -| 4.795831523312719 | -| 4.764451699828638 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## tan - -Returns the tangent of a number. - -```sql -tan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `tan` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT tan(temp) AS tan FROM home LIMIT 3 -``` - -| tan | -| ------------------: | -| -1.5274985276366035 | -| 1.5881530833912738 | -| 0.8575335036257101 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## tanh - -Returns the hyperbolic tangent of a number. - -```sql -tanh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `tanh` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT tanh(a) AS tanh FROM numbers LIMIT 3 -``` - -| tanh | -| ------------------: | -| 0.32666571332086836 | -| -0.6498182711525403 | -| -0.7263877015335474 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## trunc - -Truncates a number toward zero (at the decimal point). - -```sql -trunc(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `trunc` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT trunc(temp) AS trunc FROM home LIMIT 3 -``` - -| trunc | -| ----: | -| 21 | -| 23 | -| 22 | - -{{% /expand %}} -{{< /expand-wrapper >}} + \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/misc.md b/content/influxdb/cloud-serverless/reference/sql/functions/misc.md index 7996c011a..3e6ffc379 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/misc.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/misc.md @@ -8,239 +8,10 @@ menu: name: Miscellaneous parent: sql-functions weight: 310 + +source: /content/shared/sql-reference/functions/misc.md --- -The InfluxDB SQL implementation supports the following miscellaneous functions -for performing a variety of operations: - -- [arrow_cast](#arrow_cast) -- [arrow_typeof](#arrow_typeof) -- [interpolate](#interpolate) -- [locf](#locf) - - -## arrow_cast - -Casts a value to a specific Arrow data type. - -```sql -arrow_cast(expression, datatype) -``` - -#### Arguments - -- **expression**: Expression to cast. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. -- **datatype**: [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) - to cast to. - -{{< expand-wrapper >}} -{{% expand "View `arrow_cast` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - arrow_cast(time, 'Int64') AS time, - arrow_cast(temp, 'Utf8') AS temp, - arrow_cast(co, 'Float64')AS co -FROM home -LIMIT 1 -``` - -| time | temp | co | -| :------------------ | ---: | --: | -| 1641024000000000000 | 21.0 | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## arrow_typeof - -Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) -of the the expression: - -```sql -arrow_typeof(expression) -``` - -##### Arguments - -- **expression**: Expression to evaluate. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. - -{{< expand-wrapper >}} -{{% expand "View `arrow_typeof` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - arrow_typeof(time) AS time, - arrow_typeof(room) AS room, - arrow_typeof(temp) AS temp, - arrow_typeof(co) AS co -FROM home -LIMIT 1 -``` - -| time | room | temp | co | -| :-------------------------- | :---------------------- | :------ | :---- | -| Timestamp(Nanosecond, None) | Dictionary(Int32, Utf8) | Float64 | Int64 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## interpolate - -Fills null values in a specified aggregated column by interpolating values -from existing values. -Must be used with [`date_bin_gapfill`](/influxdb/cloud-serverless/reference/sql/functions/time-and-date/#date_bin_gapfill). - -```sql -interpolate(aggregate_expression) -``` - -##### Arguments - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/cloud-serverless/reference/sql/functions/aggregate/). - The expression can be a constant, column, or function, and any combination of - arithmetic operators supported by the aggregate function. - -##### Related functions - -[date_bin_gapfill](/influxdb/cloud-serverless/reference/sql/functions/time-and-date/#date_bin_gapfill), -[locf](#locf) - -{{< expand-wrapper >}} -{{% expand "View `interpolate` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - interpolate(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 22 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 22.85 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.25 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.6 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## locf - -Fills null values in a specified aggregated column by carrying the last observed -value forward. -Must be used with [`date_bin_gapfill`](/influxdb/cloud-serverless/reference/sql/functions/time-and-date/#date_bin_gapfill). - -_LOCF is an initialism of "last observation carried forward."_ - -```sql -locf(aggregate_expression) -``` - -##### Arguments - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/cloud-serverless/reference/sql/functions/aggregate/). - The expression can be a constant, column, or function, and any combination of - arithmetic operators supported by the aggregate function. - -##### Related functions - -[date_bin_gapfill](/influxdb/cloud-serverless/reference/sql/functions/time-and-date/#date_bin_gapfill), -[interpolate](#interpolate) - -{{< expand-wrapper >}} -{{% expand "View `locf` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - locf(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 21 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 23 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - - + \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/regular-expression.md b/content/influxdb/cloud-serverless/reference/sql/functions/regular-expression.md index d2711f680..f808d9fae 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/regular-expression.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/regular-expression.md @@ -9,145 +9,10 @@ menu: parent: sql-functions weight: 308 influxdb/cloud-serverless/tags: [regular expressions, sql] + +source: /content/shared/sql-reference/functions/regular-expression.md --- -The InfluxDB SQL implementation uses the -[PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions) -regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax) -(excluding some features such as look-around and back-references) and supports -the following regular expression functions: - -- [regexp_like](#regexp_like) -- [regexp_match](#regexp_match) -- [regexp_replace](#regexp_replace) - -## regexp_like - -True if a regular expression has at least one match in a string; -false otherwise. - -```sql -regexp_like(str, regexp[, flags]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to test against the string expression. - Can be a constant, column, or function. -- **flags**: Optional regular expression flags that control the behavior of the - regular expression. The following flags are supported: - - **i**: (insensitive) Ignore case when matching. - - **m**: (multi-line) `^` and `$` match the beginning and end of a line, respectively. - - **s**: (single-line) `.` matches newline (`\n`). - - **R**: (CRLF) When multi-line mode is enabled, `\r\n` is used to delimit lines. - - **U**: (ungreedy) Swap the meaning of `x*` and `x*?`. - -{{< expand-wrapper >}} -{{% expand "View `regexp_like` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - regexp_like(room::STRING, 'R', 'i') AS regexp_like -FROM home -``` - -| room | regexp_like | -| :---------- | :---------- | -| Kitchen | false | -| Living Room | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## regexp_match - -Returns a list of regular expression matches in a string. - -```sql -regexp_match(str, regexp, flags) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to match against. - Can be a constant, column, or function. -- **flags**: Regular expression flags that control the behavior of the - regular expression. The following flags are supported. - - **i**: (insensitive) Ignore case when matching. - -{{< expand-wrapper >}} -{{% expand "View `regexp_match` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -{{% note %}} -`regexp_match` returns a _list_ Arrow type, which is not supported by InfluxDB. -Use _bracket notation_ to reference a value in the list. -Lists use 1-based indexing. -{{% /note %}} - -```sql -SELECT DISTINCT - room, - regexp_match(room::STRING, '.{3}')[1] AS regexp_match -FROM home -``` - -| room | regexp_match | -| :---------- | :----------- | -| Kitchen | Kit | -| Living Room | Liv | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## regexp_replace - -Replaces substrings in a string that match a regular expression. - -```sql -regexp_replace(str, regexp, replacement, flags) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to match against. - Can be a constant, column, or function. -- **replacement**: Replacement string expression. - Can be a constant, column, or function, and any combination of string operators. -- **flags**: Regular expression flags that control the behavior of the - regular expression. The following flags are supported. - - **g**: (global) Search globally and don't return after the first match. - - **i**: (insensitive) Ignore case when matching. - -{{< expand-wrapper >}} -{{% expand "View `regexp_replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - regexp_replace(room::STRING, '\sRoom', '', 'gi') AS regexp_replace -FROM home -``` - -| room | regexp_replace | -| :---------- | :------------- | -| Kitchen | Kitchen | -| Living Room | Living | - -{{% /expand %}} -{{< /expand-wrapper >}} + \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/selector.md b/content/influxdb/cloud-serverless/reference/sql/functions/selector.md index ed344c556..d373d8fe7 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/selector.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/selector.md @@ -10,191 +10,10 @@ menu: weight: 302 related: - /influxdb/cloud-serverless/query-data/sql/aggregate-select/ + +source: /content/shared/sql-reference/functions/selector.md --- -SQL selector functions are designed to work with time series data. -They behave similarly to aggregate functions in that they take a collection of -data and return a single value. -However, selectors are unique in that they return a _struct_ that contains -a **time value** in addition to the computed value. - -- [How do selector functions work?](#how-do-selector-functions-work) -- [Selector functions](#selector-functions) - - [selector_min](#selector_min) - - [selector_max](#selector_max) - - [selector_first](#selector_first) - - [selector_last](#selector_last) - -## How do selector functions work? - -Each selector function returns an [Arrow _struct_](https://arrow.apache.org/docs/format/Columnar.html#struct-layout) -(similar to a JSON object) representing a single time and value from the -specified column in the each group. -What time and value get returned depend on the logic in the selector function. -For example, `selector_first` returns the value of specified column in the first row of the group. -`selector_max` returns the maximum value of the specified column in the group. - -### Selector struct schema - -The struct returned from a selector function has two properties: - -- **time**: `time` value in the selected row -- **value**: value of the specified column in the selected row - -```js -{time: 2023-01-01T00:00:00Z, value: 72.1} -``` - -### Selector functions in use - -In your `SELECT` statement, execute a selector function and use bracket notation -to reference properties of the [returned struct](#selector-struct-schema) to -populate the column value: - -```sql -SELECT - selector_first(temp, time)['time'] AS time, - selector_first(temp, time)['value'] AS temp, - room -FROM home -GROUP BY room -``` - -## Selector functions - -- [selector_min](#selector_min) -- [selector_max](#selector_max) -- [selector_first](#selector_first) -- [selector_last](#selector_last) - -### selector_min - -Returns the smallest value of a selected column and a timestamp. - -```sql -selector_min(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_min` query example" %}} - -```sql -SELECT - selector_min(water_level, time)['time'] AS time, - selector_min(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T14:30:00Z | -0.61 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_max - -Returns the largest value of a selected column and a timestamp. - -```sql -selector_max(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_max` query example" %}} - -```sql -SELECT - selector_max(water_level, time)['time'] AS time, - selector_max(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T07:24:00Z | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_first - -Returns the first value ordered by time ascending. - -```sql -selector_first(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_first` query example" %}} - -```sql -SELECT - selector_first(water_level, time)['time'] AS time, - selector_first(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T07:24:00Z | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_last - -Returns the last value ordered by time ascending. - -```sql -selector_last(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_last` query example" %}} - -```sql -SELECT - selector_last(water_level, time)['time'] AS time, - selector_last(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-09-17T21:42:00Z | 4.938 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/string.md b/content/influxdb/cloud-serverless/reference/sql/functions/string.md index 0f8261505..19f90e50a 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/string.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/string.md @@ -8,1498 +8,10 @@ menu: name: String parent: sql-functions weight: 307 + +source: /content/shared/sql-reference/functions/string.md --- -The InfluxDB SQL implementation supports the following string functions for -operating on string values: - -- [ascii](#ascii) -- [bit_length](#bit_length) -- [btrim](#btrim) -- [char_length](#char_length) -- [character_length](#character_length) -- [concat](#concat) -- [concat_ws](#concat_ws) -- [chr](#chr) -- [ends_with](#ends_with) -- [find_in_set](#find_in_set) -- [initcap](#initcap) -- [instr](#instr) -- [left](#left) -- [length](#length) -- [levenshtein](#levenshtein) -- [lower](#lower) -- [lpad](#lpad) -- [ltrim](#ltrim) -- [md5](#md5) -- [octet_length](#octet_length) -- [overlay](#overlay) -- [position](#position) -- [repeat](#repeat) -- [replace](#replace) -- [reverse](#reverse) -- [right](#right) -- [rpad](#rpad) -- [rtrim](#rtrim) -- [split_part](#split_part) -- [starts_with](#starts_with) -- [strpos](#strpos) -- [substr](#substr) -- [substr_index](#substr_index) -- [to_hex](#to_hex) -- [translate](#translate) -- [trim](#trim) -- [upper](#upper) -- [uuid](#uuid) - -## ascii - -Returns the ASCII value of the first character in a string. - -{{% note %}} -`ascii` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -ascii(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[chr](#chr) - -{{< expand-wrapper >}} -{{% expand "View `ascii` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - ascii(room)::BIGINT AS ascii -FROM home -``` - -| room | ascii | -| :---------- | ----: | -| Kitchen | 75 | -| Living Room | 76 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## bit_length - -Returns the bit length of a string. - -{{% note %}} -`bit_length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -bit_length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[length](#length), [octet_length](#octet_length) - -{{< expand-wrapper >}} -{{% expand "View `bit_length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - bit_length(room)::BIGINT AS bit_length -FROM home -``` - -| room | bit_length | -| :---------- | ---------: | -| Living Room | 88 | -| Kitchen | 56 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## btrim - -Trims the specified trim string from the start and end of a string. -If no trim string is provided, all whitespace is removed from the start and end -of the input string. - -```sql -btrim(str[, trim_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **trim_str**: String expression to trim from the beginning and end of the input string. - Can be a constant, column, or function, and any combination of arithmetic operators. - _Default is whitespace characters_. - -##### Related functions - -[ltrim](#ltrim), -[rtrim](#rtrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `btrim` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - btrim(room::STRING, ' Room') AS btrim -FROM home -``` - -| room | btrim | -| :---------- | :------ | -| Living Room | Living | -| Kitchen | Kitchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## char_length - -_Alias of [length](#length)._ - -## character_length - -_Alias of [length](#length)._ - -## concat - -Concatenates multiple strings together. - -```sql -concat(str[, ..., str_n]) -``` - -##### Arguments - -- **str**: String expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. -- **str_n**: Subsequent string expression to concatenate. - -##### Related functions - -[contcat_ws](#contcat_ws) - -{{< expand-wrapper >}} -{{% expand "View `concat` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - concat('At ', time::STRING, ', the ', room, ' was ', temp::STRING, '°C.') AS concat -FROM home -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| concat | -| :---------------------------------------------- | -| At 2022-01-01T08:00:00, the Kitchen was 21.0°C. | -| At 2022-01-01T09:00:00, the Kitchen was 23.0°C. | -| At 2022-01-01T10:00:00, the Kitchen was 22.7°C. | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## concat_ws - -Concatenates multiple strings together with a specified separator. - -```sql -concat_ws(separator, str[, ..., str_n]) -``` - -##### Arguments - -- **separator**: Separator to insert between concatenated strings. -- **str**: String expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. -- **str_n**: Subsequent string expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[concat](#concat) - -{{< expand-wrapper >}} -{{% expand "View `concat_ws` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - concat_ws(' -- ', time::STRING, room, temp::STRING) AS concat_ws -FROM home -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| concat_ws | -| :----------------------------------------- | -| 2022-01-01T08:00:00 \-\- Kitchen \-\- 21.0 | -| 2022-01-01T09:00:00 \-\- Kitchen \-\- 23.0 | -| 2022-01-01T10:00:00 \-\- Kitchen \-\- 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## chr - -Returns the character with the specified ASCII or Unicode code value. - -``` -chr(expression) -``` - -#### Arguments - -- **expression**: Expression containing the ASCII or Unicode code value to operate on. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. - -##### Related functions - -[ascii](#ascii) - -{{< expand-wrapper >}} -{{% expand "View `chr` query example" %}} - -```sql -SELECT - ascii, - chr(ascii) AS chr -FROM - (values (112), - (75), - (214) - ) data(ascii) -``` - -| ascii | chr | -| :---- | :-: | -| 112 | p | -| 75 | K | -| 214 | Ö | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ends_with - -Tests if a string ends with a substring. - -```sql -ends_with(str, substr) -``` - -##### Arguments - -- **str**: String expression to test. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to test for. - -{{< expand-wrapper >}} -{{% expand "View `ends_with` query example" %}} - -```sql -SELECT - string, - ends_with(string, 'USA') AS ends_with -FROM - (values ('New York, USA'), - ('London, UK'), - ('San Francisco, USA') - ) data(string) -``` - -| string | ends_with | -| :----------------- | :-------- | -| New York, USA | true | -| London, UK | false | -| San Francisco, USA | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## find_in_set - -Returns the position of a string in a comma-delimited list of substrings. -Returns 0 if the string is not in the list of substrings. - -```sql -find_in_set(str, strlist) -``` - -##### Arguments - -- **str**: String expression to find in `strlist`. -- **strlist**: A string containing a comma-delimited list of substrings. - -{{< expand-wrapper >}} -{{% expand "View `find_in_set` query example" %}} - -```sql -SELECT - string, - find_in_set(string, 'Isaac,John,Sara') AS find_in_set -FROM - (values ('John'), - ('Sarah'), - ('Isaac') - ) data(string) -``` - -| string | find_in_set | -| :----- | ----------: | -| John | 2 | -| Sarah | 0 | -| Isaac | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## initcap - -Capitalizes the first character in each word in the input string. -Words are delimited by non-alphanumeric characters. - -```sql -initcap(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[lower](#lower), -[upper](#upper) - -{{< expand-wrapper >}} -{{% expand "View `initcap` query example" %}} - -```sql -SELECT - string, - initcap(string) AS initcap -FROM - (values ('hello world'), - ('hello-world'), - ('hello_world') - ) data(string) -``` - -| string | initcap | -| :---------- | :---------- | -| hello world | Hello World | -| hello-world | Hello-World | -| hello_world | Hello_World | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## instr - -Returns the location where a substring first appears in a string (starting at 1). -If the substring is not in the string, the function returns 0. - -```sql -instr(str, substr) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `instr` query example" %}} - -```sql -SELECT - string, - instr(string, 'neighbor') AS instr -FROM - (values ('good neighbor'), - ('bad neighbor'), - ('next-door neighbor'), - ('friend') - ) data(string) -``` - -| string | instr | -| :----------------- | ----: | -| good neighbor | 6 | -| bad neighbor | 5 | -| next-door neighbor | 11 | -| friend | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## left - -Returns a specified number of characters from the left side of a string. - -```sql -left(str, n) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of characters to return. - -##### Related functions - -[right](#right) - -{{< expand-wrapper >}} -{{% expand "View `left` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - left(room::STRING, 3) AS left -FROM home -``` - -| room | left | -| :---------- | :--- | -| Kitchen | Kit | -| Living Room | Liv | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## length - -Returns the number of characters in a string. - -{{% note %}} -`char_length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Aliases - -- char\_length -- character\_length - -##### Related functions - -[bit_length](#bit_length), -[octet_length](#octet_length) - -{{< expand-wrapper >}} -{{% expand "View `length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - length(room)::BIGINT AS length -FROM home -``` - -| room | length | -| :---------- | -----: | -| Kitchen | 7 | -| Living Room | 11 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## levenshtein - -Returns the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) -between two strings. - -```sql -levenshtein(str1, str2) -``` - -##### Arguments -- **str1**: First string expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **str2**: Second string expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `levenshtein` query example" %}} - -```sql -SELECT - string1, - string2, - levenshtein(string1, string2) AS levenshtein -FROM - (values ('kitten', 'sitting'), - ('puppy', 'jumping'), - ('cow', 'lowing') - ) data(string1, string2) -``` - -| string1 | string2 | levenshtein | -| :------ | :------ | ----------: | -| kitten | sitting | 3 | -| puppy | jumping | 5 | -| cow | lowing | 4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lower - -Converts a string to lower-case. - -```sql -lower(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[initcap](#initcap), -[upper](#upper) - -{{< expand-wrapper >}} -{{% expand "View `lower` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - lower(room::STRING) AS lower -FROM home -``` - -| room | lower | -| :---------- | :---------- | -| Kitchen | kitchen | -| Living Room | living room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lpad - -Pads the left side of a string with another string to a specified string length. - -```sql -lpad(str, n[, padding_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: String length to pad to. -- **padding_str**: String expression to pad with. - Can be a constant, column, or function, and any combination of string operators. - _Default is a space._ - -##### Related functions - -[rpad](#rpad) - -{{< expand-wrapper >}} -{{% expand "View `lpad` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - lpad(room::STRING, 14, '-') AS lpad -FROM home -``` - -| room | lpad | -| :---------- | :-------------------- | -| Kitchen | \-\-\-\-\-\-\-Kitchen | -| Living Room | \-\-\-Living Room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ltrim - -Removes leading spaces from a string. - -```sql -ltrim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[rtrim](#rtrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `ltrim` query example" %}} - -```sql -SELECT - string, - ltrim(string) AS ltrim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | ltrim | -| :-------------------------------------- | :-------------------------------------- | -|   Leading spaces | Leading spaces | -| Trailing spaces   | Trailing spaces   | -| Leading and trailing spaces   | Leading and trailing spaces   | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## md5 - -Computes an MD5 128-bit checksum for a string expression. - -```sql -md5(str) -``` - -##### Arguments - -- **expression**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `md5` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - md5(room) AS md5 -FROM home -``` - -| room | md5 | -| :---------- | :------------------------------- | -| Kitchen | 33fa00a66f2edf0d1c5697a9f8693ba8 | -| Living Room | f45b0e6aec165544faccaf2cad820542 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## octet_length - -Returns the length of a string in bytes. - -{{% note %}} -`length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -octet_length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[bit_length](#bit_length), -[length](#length) - -{{< expand-wrapper >}} -{{% expand "View `octet_length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - octet_length(room)::BIGINT AS octet_length -FROM home -``` - -| room | octet_length | -| :---------- | -----------: | -| Living Room | 11 | -| Kitchen | 7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## overlay - -Replaces part of a string with another substring using a specified starting -position and number of characters to replace. - -```sql -overlay(str PLACING substr FROM pos [FOR count]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to use to replace part of the specified string (`str`). - Can be a constant, column, or function, and any combination of string operators. -- **pos**: Start position of the substring replacement (`substr`). -- **count**: Number of characters in the string (`str`) to replace with the - substring (`substr`) beginning from the start position (`pos`). - If not specified, the function uses the length of the substring. - -{{< expand-wrapper >}} -{{% expand "View `overlay` query example" %}} - -```sql -SELECT - string, - overlay(string PLACING '****' FROM 1 FOR 12) AS overlay -FROM - (values ('2223000048410010'), - ('2222420000001113'), - ('4917484589897107') - ) data(string) -``` - -| string | overlay | -| :--------------- | :------- | -| 2223000048410010 | ****0010 | -| 2222420000001113 | ****1113 | -| 4917484589897107 | ****7107 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## position - -Returns the position of a substring in a string. - -```sql -position(substr IN str) -``` - -##### Arguments - -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. -- **str**: String expression to search. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `position` query example" %}} - -```sql -SELECT - string, - position('oo' IN string) AS position -FROM - (values ('cool'), - ('scoop'), - ('ice cream') - ) data(string) -``` - -| string | position | -| :-------- | -------: | -| cool | 2 | -| scoop | 3 | -| ice cream | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## repeat - -Returns a string with an input string repeated a specified number of times. - -```sql -repeat(str, n) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of times to repeat the input string. - -{{< expand-wrapper >}} -{{% expand "View `repeat` query example" %}} - -```sql -SELECT - string, - repeat(string, 3) AS repeat -FROM - (values ('foo '), - ('bar '), - ('baz ') - ) data(string) -``` - -| string | repeat | -| :-------- | :---------- | -| foo  | foo foo foo | -| bar  | bar bar bar | -| baz  | baz baz baz | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## replace - -Replaces all occurrences of a specified substring in a string with a new substring. - -```sql -replace(str, substr, replacement) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to replace in the input string. - Can be a constant, column, or function, and any combination of string operators. -- **replacement**: Replacement substring expression. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - replace(room::STRING, ' ', '_') AS replace -FROM home -``` - -| room | replace | -| :---------- | :---------- | -| Kitchen | Kitchen | -| Living Room | Living_Room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## reverse - -Reverses the character order of a string. - -```sql -reverse(str) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `reverse` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - reverse(room::STRING) AS reverse -FROM home -``` - -| room | reverse | -| :---------- | :---------- | -| Kitchen | nehctiK | -| Living Room | mooR gniviL | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## right - -Returns a specified number of characters from the right side of a string. - -```sql -right(str, n) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of characters to return. - -##### Related functions - -[left](#left) - -{{< expand-wrapper >}} -{{% expand "View `right` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - right(room::STRING, 3) AS right -FROM home -``` - -| room | right | -| :---------- | :---- | -| Living Room | oom | -| Kitchen | hen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## rpad - -Pads the right side of a string with another string to a specified string length. - -```sql -rpad(str, n[, padding_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: String length to pad to. -- **padding_str**: String expression to pad with. - Can be a constant, column, or function, and any combination of string operators. - _Default is a space._ - -##### Related functions - -[lpad](#lpad) - -{{< expand-wrapper >}} -{{% expand "View `rpad` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - rpad(room::STRING, 14, '-') AS rpad -FROM home -``` - -| room | rpad | -| :---------- | :-------------------- | -| Kitchen | Kitchen\-\-\-\-\-\-\- | -| Living Room | Living Room\-\-\- | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## rtrim - -Removes trailing spaces from a string. - -```sql -rtrim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[ltrim](#ltrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `rtrim` query example" %}} - -```sql -SELECT - string, - rtrim(string) AS rtrim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | rtrim | -| :-------------------------------------- | :-------------------------------------- | -|   Leading spaces |   Leading spaces | -| Trailing spaces   | Trailing spaces | -| Leading and trailing spaces   |   Leading and trailing spaces | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## split_part - -Splits a string based on a specified delimiter and returns the substring in the -specified position. - -```sql -split_part(str, delimiter, pos) -``` - -##### Arguments - -- **str**: String expression to spit. - Can be a constant, column, or function, and any combination of string operators. -- **delimiter**: String or character to split on. -- **pos**: Position of the part to return. - -{{< expand-wrapper >}} -{{% expand "View `split_part` query example" %}} - -```sql -SELECT - url, - split_part(url, '.', 1) AS split_part -FROM - (values ('www.influxdata.com'), - ('docs.influxdata.com'), - ('community.influxdata.com') - ) data(url) -``` - -| url | split_part | -| :----------------------- | :--------- | -| www.influxdata.com | www | -| docs.influxdata.com | docs | -| community.influxdata.com | community | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## starts_with - -Tests if a string starts with a substring. - -```sql -starts_with(str, substr) -``` - -##### Arguments - -- **str**: String expression to test. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to test for. - -{{< expand-wrapper >}} -{{% expand "View `starts_with` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - starts_with(room::STRING, 'Kit') AS starts_with -FROM home -``` - -| room | starts_with | -| :---------- | :---------- | -| Kitchen | true | -| Living Room | false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## strpos - -Returns the starting position of a specified substring in a string. -Positions begin at 1. -If the substring does not exist in the string, the function returns 0. - -{{% note %}} -`strpos` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -strpos(str, substr) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `strpos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - strpos(room::STRING, 'Room')::BIGINT AS strpos -FROM home -``` - -| room | strpos | -| :---------- | -----: | -| Kitchen | 0 | -| Living Room | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## substr - -Extracts a substring of a specified number of characters from a specific -starting position in a string. - -```sql -substr(str, start_pos[, length]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **start_pos**: Character position to start the substring at. - The first character in the string has a position of 1. -- **length**: Number of characters to extract. - If not specified, returns the rest of the string after the start position. - -{{< expand-wrapper >}} -{{% expand "View `substr` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - substr(room::STRING, 3, 5) AS substr -FROM home -``` - -| room | substr | -| :---------- | :--------- | -| Living Room | ving  | -| Kitchen | tchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## substr_index - -Returns the substring that occurs before or after the specified number (`count`) -of delimiter (`delimiter`) occurrences in a string (`str`). -If the count is positive, the function returns everything to the left of the -final delimiter (counting from the left). -If the count is negative, the function returns everything to the right of the -final delimiter (counting from the right). - -```sql -substr_index(str, delimiter, count) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **delimiter**: String expression to use to delimit substrings in the string (`str`). - Can be a constant, column, or function, and any combination of string operators. -- **count**: The Nth occurrence of the delimiter (`delimiter`) to split on. - Can be a constant, column, or function, and any combination of arithmetic operators. - Supports positive and negative numbers. - -{{< expand-wrapper >}} -{{% expand "View `substr_index` query example" %}} - -```sql -SELECT - url, - substr_index(url, '.', 1) AS subdomain, - substr_index(url, '.', -1) AS tld -FROM - (values ('docs.influxdata.com'), - ('community.influxdata.com'), - ('cloud2.influxdata.com') - ) data(url) -``` - -| url | subdomain | tld | -| :----------------------- | :-------- | :-- | -| docs.influxdata.com | docs | com | -| community.influxdata.com | community | com | -| arrow.apache.org | arrow | org | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## translate - -Translates characters in a string to specified translation characters. - -```sql -translate(str, chars, translation) -``` - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **chars**: Characters to translate. -- **translation**: Translation characters. Translation characters replace only - characters at the same position in the **chars** string. - -{{< expand-wrapper >}} -{{% expand "View `translate` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - translate(room::STRING, 'Rom', 'sOn') AS translate -FROM home -``` - -| room | translate | -| :---------- | :---------- | -| Living Room | Living sOOn | -| Kitchen | Kitchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_hex - -Converts an integer to a hexadecimal string. - -```sql -to_hex(int) -``` - -##### Arguments - -- **int**: Integer expression to convert. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `to_hex` query example" %}} - -```sql -SELECT - int, - to_hex(int) AS to_hex -FROM - (values (123), - (345), - (678) - ) data(int) -``` - -| int | to_hex | -| :-- | -----: | -| 123 | 7b | -| 345 | 159 | -| 678 | 2a6 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## trim - -Removes leading and trailing spaces from a string. - -```sql -trim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[ltrim](#ltrim), -[rtrim](#rtrim) - -{{< expand-wrapper >}} -{{% expand "View `trim` query example" %}} - -```sql -SELECT - string, - trim(string) AS trim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | trim | -| :-------------------------------------- | :-------------------------- | -|   Leading spaces | Leading spaces | -| Trailing spaces   | Trailing spaces | -| Leading and trailing spaces   | Leading and trailing spaces | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## upper - -Converts a string to upper-case. - -```sql -upper(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[initcap](#initcap), -[lower](#lower) - -{{< expand-wrapper >}} -{{% expand "View `upper` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - upper(room::STRING) AS upper -FROM home -``` - -| room | upper | -| :---------- | :---------- | -| Living Room | LIVING ROOM | -| Kitchen | KITCHEN | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## uuid - -Returns a UUID v4 string value that is unique per row. - -```sql -uuid() -``` - -{{< expand-wrapper >}} -{{% expand "View `uuid` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - uuid() AS uuid -FROM (SELECT DISTINCT room FROM home) -``` - -| room | uuid | -| :---------- | :----------------------------------: | -| Kitchen | f0b41da9-e334-4b7d-b925-a54ca6b082f3 | -| Living Room | c31be90e-c4ed-4304-b633-47b969ef3ab6 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md index a3833aab0..22e9fba7f 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md @@ -8,822 +8,10 @@ menu: name: Time and date parent: sql-functions weight: 305 + +source: /content/shared/sql-reference/functions/time-and-date.md --- -InfluxDB's SQL implementation supports time and date functions that are useful when working with time series data. - -- [current_date](#current_date) -- [current_time](#current_time) -- [date_bin](#date_bin) -- [date_bin_gapfill](#date_bin_gapfill) -- [date_trunc](#date_trunc) -- [datetrunc](#datetrunc) -- [date_part](#date_part) -- [datepart](#datepart) -- [extract](#extract) -- [from_unixtime](#from_unixtime) -- [now](#now) -- [to_timestamp](#to_timestamp) -- [to_timestamp_millis](#to_timestamp_millis) -- [to_timestamp_micros](#to_timestamp_micros) -- [to_timestamp_seconds](#to_timestamp_seconds) - -## current_date - -Returns the current UTC date. - -{{% note %}} -`current_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a timestamp](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-a-timestamp-type). -{{% /note %}} - -The `current_date()` return value is determined at query time and will return -the same date, no matter when in the query plan the function executes. - -``` -current_date() -``` - -{{< expand-wrapper >}} -{{% expand "View `current_date` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - time, - temp, - current_date()::TIMESTAMP AS current_date -FROM home -WHERE - time > current_date()::TIMESTAMP - INTERVAL '5 years' -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| time | temp | current_date | -| :------------------- | ---: | :---------------------------- | -| 2022-01-01T08:00:00Z | 21 | {{< datetime/current-date >}} | -| 2022-01-01T09:00:00Z | 23 | {{< datetime/current-date >}} | -| 2022-01-01T10:00:00Z | 22.7 | {{< datetime/current-date >}} | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## current_time - -Returns the current UTC time. - -{{% note %}} -`current_date` returns a `TIME64` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a string](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-a-string-type). -{{% /note %}} - -The `current_time()` return value is determined at query time and will return the same time, -no matter when in the query plan the function executes. - -``` -current_time() -``` - -{{< expand-wrapper >}} -{{% expand "View `current_time` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - time, - temp, - current_time()::STRING AS current_time -FROM home -LIMIT 3 -``` - -| time | temp | current_time | -| :------------------- | ---: | :---------------------------- | -| 2022-01-01T08:00:00Z | 21 | {{< datetime/current-time >}} | -| 2022-01-01T09:00:00Z | 23 | {{< datetime/current-time >}} | -| 2022-01-01T10:00:00Z | 22.7 | {{< datetime/current-time >}} | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## date_bin - -Calculates time intervals and returns the start of the interval nearest to the specified timestamp. -Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" -and applying an aggregate or selector function to each window. - -For example, if you "bin" or "window" data into 15 minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 minute bin it is in: `2023-01-01T18:15:00Z`. - -```sql -date_bin(interval, expression[, origin_timestamp]) -``` - -##### Arguments: - -- **interval**: Bin interval. -- **expression**: Time expression to operate on. - Can be a constant, column, or function. -- **origin_timestamp**: Starting point used to determine bin boundaries. - _Default is the Unix epoch._ - -The following intervals are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks -- months -- years -- century - -{{< expand-wrapper >}} -{{% expand "View `date_bin` query example" %}} - -The following query returns the daily average of water levels in the queried time range. - -```sql -SELECT - date_bin(INTERVAL '1 day', time, TIMESTAMP '1970-01-01 00:00:00Z') AS time, - avg("water_level") AS water_level_avg -FROM "h2o_feet" -WHERE - time >= timestamp '2019-09-10T00:00:00Z' - AND time <= timestamp '2019-09-20T00:00:00Z' -GROUP BY 1 -ORDER BY time DESC -``` - -| time | water_level_avg | -| :----------------------- | :----------------- | -| 2019-09-17T00:00:00.000Z | 4.370175687443861 | -| 2019-09-16T00:00:00.000Z | 4.6034785848437485 | -| 2019-09-15T00:00:00.000Z | 4.680651501506248 | -| 2019-09-14T00:00:00.000Z | 4.857683652395836 | -| 2019-09-13T00:00:00.000Z | 4.911051520291668 | -| 2019-09-12T00:00:00.000Z | 4.763990784533338 | -| 2019-09-11T00:00:00.000Z | 4.6582452515041695 | -| 2019-09-10T00:00:00.000Z | 4.608425018785421 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## date_bin_gapfill - -Calculates time intervals and returns the start of the interval nearest to the specified timestamp. -If no rows exist in a time interval, a new row is inserted with a `time` value -set to the interval start time, all columns in the `GROUP BY` clause populated, -and null values in aggregate columns. - -Use `date_bin_gapfill` with [`interpolate`](/influxdb/cloud-serverless/reference/sql/functions/misc/#interpolate) -or [`locf`](/influxdb/cloud-serverless/reference/sql/functions/misc/#locf) to -[fill gaps in data]() -at specified time intervals. - -```sql -date_bin_gapfill(interval, expression[, origin_timestamp]) -``` - -{{% note %}} -`date_bin_gapfill` requires [time bounds](/influxdb/cloud-serverless/query-data/sql/basic-query/#query-data-within-time-boundaries) -in the `WHERE` clause. -{{% /note %}} - -##### Arguments: - -- **interval**: Bin interval. -- **expression**: Time expression to operate on. - Can be a constant, column, or function. -- **origin_timestamp**: Starting point used to determine bin boundaries. - _Default is the Unix epoch._ - -The following intervals are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks - - -The following intervals are not currently supported: -- months -- years -- century - - -##### Related functions - -[interpolate](/influxdb/cloud-serverless/reference/sql/functions/misc/#interpolate), -[locf](/influxdb/cloud-serverless/reference/sql/functions/misc/#locf) - -{{< expand-wrapper >}} -{{% expand "View `date_bin_gapfill` query examples" %}} - -_The following examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -- [Use date_bin_gapfill to insert rows when no rows exists](#use-date_bin_gapfill-to-insert-rows-when-no-rows-exists) -- [Use date_bin_gapfill to fill gaps in data](#use-date_bin_gapfill-to-fill-gaps-in-data) - -#### Use date_bin_gapfill to insert rows when no rows exists - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - avg(temp) as temp -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | temp | -| :------------------- | :---------- | ---: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -#### Use date_bin_gapfill to fill gaps in data - -Use `interpolate` and `locf` to fill the null values in rows inserted by -`date_bin_gapfill`. - -{{< tabs-wrapper >}} -{{% tabs "small" %}} -[interpolate](#) -[locf](#) -{{% /tabs %}} -{{% tab-content %}} - -The example below uses [`interpolate`](/influxdb/cloud-serverless/reference/sql/functions/misc/#interpolate) -to fill null values by interpolating values between non-null values. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - interpolate(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 22 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 22.85 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.25 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.6 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /tab-content %}} -{{% tab-content %}} - -The example below uses [`locf`](/influxdb/cloud-serverless/reference/sql/functions/misc/#locf) -to fill null values by carrying the last observed value forward. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - locf(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 21 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 23 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - -{{% /expand %}} -{{< /expand-wrapper >}} - - -## date_trunc - -Truncates a timestamp value to a specified precision. - -```sql -date_trunc(precision, expression) -``` - -##### Arguments: - -- **precision**: Time precision to truncate to. - The following precisions are supported: - - - year - - month - - week - - day - - hour - - minute - - second - -- **expression**: Time expression to operate on. - Can be a constant, column, or function. - -##### Aliases - -- `datetrunc` - -{{< expand-wrapper >}} -{{% expand "View `date_trunc` query examples" %}} - -#### Use date_trunc to return hourly averages - -```sql -SELECT - avg(water_level) AS level, - date_trunc('hour', time) AS hour -FROM h2o_feet -WHERE - time >= timestamp '2019-09-10T00:00:00Z' - AND time <= timestamp '2019-09-12T00:00:00Z' -GROUP BY hour -ORDER BY hour -``` - -| hour | level | -| :----------------------- | :----------------- | -| 2019-09-10T00:00:00.000Z | 3.7248000000000006 | -| 2019-09-10T01:00:00.000Z | 3.8561499999999995 | -| 2019-09-10T02:00:00.000Z | 4.5405999999999995 | -| 2019-09-10T03:00:00.000Z | 5.5548072072500005 | -| 2019-09-10T04:00:00.000Z | 6.433900000000001 | -| 2019-09-10T05:00:00.000Z | 6.810949999999998 | - -#### Use date_trunc to return weekly averages - -```sql -SELECT - mean(water_level) as level, - date_trunc('week',time) AS week -FROM h2o_feet -WHERE - time >= timestamp '2019-08-01T00:00:00Z' - AND time <= timestamp '2019-10-31T00:00:00Z' -GROUP BY week -ORDER BY week -``` - -| level | week | -| :----------------- | :----------------------- | -| 4.3314415259020835 | 2019-08-12T00:00:00.000Z | -| 4.234838403584523 | 2019-08-19T00:00:00.000Z | -| 4.4184818559633925 | 2019-08-26T00:00:00.000Z | -| 4.405153386766021 | 2019-09-02T00:00:00.000Z | -| 4.725866897257734 | 2019-09-09T00:00:00.000Z | -| 4.499938596774042 | 2019-09-16T00:00:00.000Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## datetrunc - -_Alias of [date_trunc](#date_trunc)._ - -## date_part - -Returns the specified part of the date as an integer. - -```sql -date_part(part, expression) -``` - -##### Arguments: - -- **part**: Part of the date to return. - The following date parts are supported: - - - year - - month - - week _(week of the year)_ - - day _(day of the month)_ - - hour - - minute - - second - - millisecond - - microsecond - - nanosecond - - dow _(day of the week)_ - - doy _(day of the year)_ - -- **expression**: Time expression to operate on. - Can be a constant, column, or function. - -##### Aliases - -- `datepart` - -{{< expand-wrapper >}} -{{% expand "View `date_part` query examples" %}} - -```sql -SELECT - date_part('hour', time) AS hour, - time, - "level description", - location -FROM h2o_feet -WHERE - time >= timestamp '2019-08-17T02:54:00Z' - AND time <= timestamp '2019-08-17T03:06:00Z' -ORDER BY time -``` - -| hour | time | level description | location | -| :--: | :------------------- | :------------------- | :----------- | -| 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | coyote_creek | -| 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | santa_monica | -| 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | coyote_creek | -| 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | santa_monica | -| 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | coyote_creek | -| 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | santa_monica | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## datepart - -_Alias of [date_part](#date_part)._ - -## extract - -Returns a sub-field from a time value as an integer. -Similar to `date_part`, but with different arguments. - -```sql -extract(field FROM source) -``` - -##### Arguments - -- **field**: Part or field of the date to return. - The following date fields are supported: - - - year - - month - - week _(week of the year)_ - - day _(day of the month)_ - - hour - - minute - - second - - millisecond - - microsecond - - nanosecond - - dow _(day of the week)_ - - doy _(day of the year)_ - -- **source**: Source time expression to operate on. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `extract` query example" %}} - -```sql -SELECT - extract(day from time) AS day -FROM - h2o_feet -LIMIT 1 -``` - -| day | -| :-- | -| 25 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## from_unixtime - -Converts an integer to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). -Input is parsed as a [Unix nanosecond timestamp](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) -and returns the corresponding RFC3339 timestamp. - -```sql -from_unixtime(expression) -``` - -##### Arguments: - -- **expression**: Integer expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `from_unixtime` query example" %}} - -```sql -SELECT - from_unixtime(1672531200000000000) AS RFC3339 -``` - -| RFC3339 | -| :------------------- | -| 2023-01-01T00:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## now - -Returns the current UTC timestamp. - -The `now()` return value is determined at query time and will return the same timestamp, -no matter when in the query plan the function executes. - -```sql -now() -``` - -{{< expand-wrapper >}} -{{% expand "View `now` query example" %}} - -```sql -SELECT - "water_level", - "time" -FROM h2o_feet -WHERE - time <= now() - interval '12 minutes' -``` - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp - -Converts a value to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix nanosecond timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp(expression) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp` query example" %}} - -```sql -SELECT to_timestamp(1704067200000000000) -``` - -| to_timestamp(Int64(1704067200000000000)) | -| :--------------------------------------- | -| 2024-01-01T00:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_millis - -Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix millisecond timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_millis(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_millis` query example" %}} - -```sql -SELECT to_timestamp_millis(1704067200001) AS time -``` - -Results -| to_timestamp_millis(Int64(1704067200001)) | -| :---------------------------------------- | -| 2024-01-01T00:00:00.001Z | - -{{% /expand %}} -{{% expand "View `to_timestamp_millis` example with string format parsing" %}} - -```sql -SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond -``` - -| millisecond | -| :----------------------- | -| 2024-01-01T01:01:59.123Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_micros - -Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix microsecond timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_micros(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_micros` query example" %}} - -```sql -SELECT to_timestamp_micros(1704067200000001) -``` - -| to_timestamp_micros(Int64(1704067200000001)) | -| :------------------------------------------- | -| 2024-01-01T00:00:00.000001Z | -{{% /expand %}} -{{% expand "View `to_timestamp_micros` example with string format parsing" %}} - -```sql -SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond -``` - -| microsecond | -| :-------------------------- | -| 2024-01-01T01:01:59.123456Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_nanos - -Converts a value to RFC3339 nanosecond timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix nanosecond timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_nanos(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_nanos` query example" %}} - -```sql -SELECT to_timestamp_nanos(1704067200000000001) -``` - -| to_timestamp_nanos(Int64(1704067200000000001)) | -| :--------------------------------------------- | -| 2024-01-01T00:00:00.000000001Z | -{{% /expand %}} -{{% expand "View `to_timestamp_nanos` example with string format parsing" %}} - -```sql -SELECT to_timestamp_nanos('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS nanosecond -``` - -| nanosecond | -| :----------------------------- | -| 2024-01-01T01:01:59.123456789Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_seconds - -Converts a value to RFC3339 second timestamp format (`YYYY-MM-DDT00:00:00Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix second timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_seconds(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_seconds` query example" %}} - -```sql -SELECT to_timestamp_seconds(1704067201) -``` - -| to_timestamp_seconds(Int64(1704067201)) | -| :-------------------------------------- | -| 2024-01-01T00:00:01Z | - -{{% /expand %}} -{{% expand "View `to_timestamp_seconds` example with string format parsing" %}} - -```sql -SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS second -``` - -| second | -| :------------------- | -| 2024-01-01T01:01:59Z | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/group-by.md b/content/influxdb/cloud-serverless/reference/sql/group-by.md index 58433b121..6cca0c32a 100644 --- a/content/influxdb/cloud-serverless/reference/sql/group-by.md +++ b/content/influxdb/cloud-serverless/reference/sql/group-by.md @@ -7,92 +7,10 @@ menu: name: GROUP BY clause parent: SQL reference weight: 203 + +source: /content/shared/sql-reference/group-by.md --- -Use the `GROUP BY` clause to group data by values. - -`GROUP BY` is an optional clause used to group rows that have the same values for all columns and expressions in the list. -To output an aggregation for each group, include an aggregate or selector function in the `SELECT` statement. -When `GROUP BY` appears in a query, the `SELECT` list can only use columns that appear in the `GROUP BY` list -or in aggregate expressions. - -`GROUP BY` can use column aliases that are defined in the `SELECT` clause. -`GROUP BY` can't use an alias named `time`. -In a `GROUP BY` list, `time` always refers to the measurement `time` column. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT - AGGREGATE_FN(field1), - tag1 -FROM measurement -GROUP BY tag1 -``` - -## Examples - -### Group data by tag values - -```sql -SELECT - AVG("water_level") AS "avg_water_level", - "location" -FROM "h2o_feet" -GROUP BY "location" -``` - -{{< expand-wrapper >}}} -{{% expand "View example results" %}} - -| avg_water_level | location | -| ----------------: | ------------ | -| 5.359142420303919 | coyote_creek | -| 3.530712094245885 | santa_monica | - -{{% /expand %}} -{{< /expand-wrapper >}} - -Group results in 15 minute time intervals by tag: - -```sql -SELECT - "location", - DATE_BIN(INTERVAL '15 minutes', time, TIMESTAMP '2022-01-01 00:00:00Z') AS _time, - COUNT("water_level") AS count -FROM "h2o_feet" -WHERE - time >= timestamp '2019-09-17T00:00:00Z' - AND time <= timestamp '2019-09-17T01:00:00Z' -GROUP BY - _time, - location -ORDER BY - location, - _time -``` - -{{< expand-wrapper >}}} -{{% expand "View example results" %}} - -The query uses the `COUNT()` function to count the number of `water_level` points per 15 minute interval. -Results are then ordered by location and time. - -| location | _time | count | -| :----------- | :-------------------- | ----: | -| coyote_creek | 2019-09-16T23:45:00Z | 1 | -| coyote_creek | 2019-09-17T00:00:00Z | 2 | -| coyote_creek | 2019-09-17T00:15:00Z | 3 | -| coyote_creek | 2019-09-17T00:30:00Z | 2 | -| coyote_creek | 2019-09-17T00:45:00Z | 3 | -| santa_monica | 2019-09-16T23:45:00Z | 1 | -| santa_monica | 2019-09-17T00:00:00Z | 2 | -| santa_monica | 2019-09-17T00:15:00Z | 3 | -| santa_monica | 2019-09-17T00:30:00Z | 2 | -| santa_monica | 2019-09-17T00:45:00Z | 3 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/having.md b/content/influxdb/cloud-serverless/reference/sql/having.md index f378fb0ea..bf9e771ea 100644 --- a/content/influxdb/cloud-serverless/reference/sql/having.md +++ b/content/influxdb/cloud-serverless/reference/sql/having.md @@ -10,78 +10,10 @@ menu: weight: 205 related: - /influxdb/cloud-serverless/reference/sql/subqueries/ + +source: /content/shared/sql-reference/having.md --- -The `HAVING` clause places conditions on results created by an aggregate operation on groups. -The `HAVING` clause must follow the `GROUP BY` clause and precede the `ORDER BY` clause. - -{{% note %}} -The `WHERE` clause filters rows based on specified conditions _before_ the aggregate operation. -The `HAVING` clause filters rows based on specified conditions _after_ the aggregate operation has taken place. -{{% /note %}} - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [HAVING_clause] [ORDER_BY_clause] -``` - -## Examples - -### Return rows with an aggregate value greater than a specified number - -```sql -SELECT - MEAN("water_level") AS "mean_water_level", "location" -FROM - "h2o_feet" -GROUP BY - "location" -HAVING - "mean_water_level" > 5 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns on rows with values in the `mean_water_level` greater than 5 _after_ the aggregate operation. - -| location | mean_water_level | -| :----------- | :---------------- | -| coyote_creek | 5.359142420303919 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Return the average result greater than a specified number from a specific time range - -```sql -SELECT - AVG("water_level") AS "avg_water_level", - "time" -FROM - "h2o_feet" -WHERE - time >= '2019-09-01T00:00:00Z' AND time <= '2019-09-02T00:00:00Z' -GROUP BY - "time" -HAVING - "avg_water_level" > 6.82 -ORDER BY - "time" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query calculates the average water level per time and only returns rows with an average greater than 6.82 during the specified time range. - -| time | avg_water_level | -| :------------------- | -----------------: | -| 2019-09-01T22:06:00Z | 6.8225 | -| 2019-09-01T22:12:00Z | 6.8405000000000005 | -| 2019-09-01T22:30:00Z | 6.8505 | -| 2019-09-01T22:36:00Z | 6.8325 | -{{% /expand %}} -{{< /expand-wrapper >}} \ No newline at end of file + diff --git a/content/influxdb/cloud-serverless/reference/sql/information-schema.md b/content/influxdb/cloud-serverless/reference/sql/information-schema.md index 9c7cbbfcc..e8d4bafa1 100644 --- a/content/influxdb/cloud-serverless/reference/sql/information-schema.md +++ b/content/influxdb/cloud-serverless/reference/sql/information-schema.md @@ -7,140 +7,10 @@ menu: influxdb_cloud_serverless: parent: SQL reference weight: 210 + +source: /content/shared/sql-reference/information-schema.md --- -The underlying query engine for the InfluxDB SQL implementation, -[DataFusion](https://arrow.apache.org/datafusion/index.html), provides commands -that return metadata related to your data schema. -To access this information, use the `SHOW TABLES`, `SHOW COLUMNS`, and -`SHOW ALL` commands or query views in the [ISO](https://www.iso.org/) SQL -`information_schema` schema. - -In the context of InfluxDB, a [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) -is represented as a table. Time, [tags](/influxdb/cloud-serverless/reference/glossary/#tag), -and [fields](/influxdb/cloud-serverless/reference/glossary/#field) are each represented -by columns in a table. - -- [SHOW TABLES](#show-tables) - - [Example SHOW TABLES output](#example-show-tables-output) -- [SHOW COLUMNS](#show-columns) - - [Example SHOW COLUMNS output](#example-show-columns-output) -- [SHOW ALL](#show-all) - - [Example SHOW ALL output](#view-show-all-example-output) - -## SHOW TABLES - -Returns information about tables (measurements) in an InfluxDB bucket. - -```sql -SHOW TABLES -``` - -You can also query the `information_schema.tables` view: - -```sql -SELECT * FROM information_schema.tables -``` - -#### Example SHOW TABLES output - -_Measurements are those that use the **`iox` table schema**._ - -| table_catalog | table_schema | table_name | table_type | -| :------------ | :----------------- | :---------- | :--------- | -| public | iox | home | BASE TABLE | -| public | system | queries | BASE TABLE | -| public | information_schema | tables | VIEW | -| public | information_schema | views | VIEW | -| public | information_schema | columns | VIEW | -| public | information_schema | df_settings | VIEW | - -## SHOW COLUMNS - -Returns information about the schema of a table (measurement) in an InfluxDB bucket. - -```sql -SHOW COLUMNS FROM example_table -``` - -You can also query the `information_schema.columns` view: - -```sql -SELECT - table_catalog, - table_schema, - table_name, - column_name, - data_type, - is_nullable -FROM information_schema.columns -WHERE table_name = 'example_table' -``` - -#### Example SHOW COLUMNS output - -| table_catalog | table_schema | table_name | column_name | data_type | is_nullable | -| :------------ | :----------- | :--------- | :---------- | :-------------------------- | :---------- | -| public | iox | home | co | Int64 | YES | -| public | iox | home | hum | Float64 | YES | -| public | iox | home | room | Dictionary(Int32, Utf8) | YES | -| public | iox | home | temp | Float64 | YES | -| public | iox | home | time | Timestamp(Nanosecond, None) | NO | - -## SHOW ALL - -Returns the configuration options of the current session. - -```sql -SHOW ALL -``` - -You can also query the `information_schema.df_settings` view: - -```sql -SELECT * FROM information_schema.df_settings -``` - -{{< expand-wrapper >}} -{{% expand "View `SHOW ALL` example output" %}} - -| name | setting | -| :-------------------------------------------------------- | :------- | -| datafusion.catalog.create_default_catalog_and_schema | true | -| datafusion.catalog.default_catalog | public | -| datafusion.catalog.default_schema | iox | -| datafusion.catalog.format | | -| datafusion.catalog.has_header | false | -| datafusion.catalog.information_schema | true | -| datafusion.catalog.location | | -| datafusion.execution.batch_size | 8192 | -| datafusion.execution.coalesce_batches | true | -| datafusion.execution.collect_statistics | false | -| datafusion.execution.parquet.enable_page_index | false | -| datafusion.execution.parquet.metadata_size_hint | | -| datafusion.execution.parquet.pruning | true | -| datafusion.execution.parquet.pushdown_filters | true | -| datafusion.execution.parquet.reorder_filters | true | -| datafusion.execution.parquet.skip_metadata | true | -| datafusion.execution.target_partitions | 4 | -| datafusion.execution.time_zone | +00:00 | -| datafusion.explain.logical_plan_only | false | -| datafusion.explain.physical_plan_only | false | -| datafusion.optimizer.enable_round_robin_repartition | true | -| datafusion.optimizer.filter_null_join_keys | false | -| datafusion.optimizer.hash_join_single_partition_threshold | 1048576 | -| datafusion.optimizer.max_passes | 3 | -| datafusion.optimizer.prefer_hash_join | true | -| datafusion.optimizer.repartition_aggregations | true | -| datafusion.optimizer.repartition_file_min_size | 10485760 | -| datafusion.optimizer.repartition_file_scans | true | -| datafusion.optimizer.repartition_joins | true | -| datafusion.optimizer.repartition_sorts | false | -| datafusion.optimizer.repartition_windows | true | -| datafusion.optimizer.skip_failed_rules | true | -| datafusion.optimizer.top_down_join_key_reordering | true | -| datafusion.sql_parser.enable_ident_normalization | true | -| datafusion.sql_parser.parse_float_as_decimal | false | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/join.md b/content/influxdb/cloud-serverless/reference/sql/join.md index 355305c0b..881c4539a 100644 --- a/content/influxdb/cloud-serverless/reference/sql/join.md +++ b/content/influxdb/cloud-serverless/reference/sql/join.md @@ -7,267 +7,10 @@ menu: name: JOIN clause parent: SQL reference weight: 202 + +source: /content/shared/sql-reference/join.md --- -Use the `JOIN` clause to join data from different tables together based on -logical relationships. - -- [Syntax](#syntax) -- [Join types](#join-types) - - [INNER JOIN](#inner-join) - - [LEFT [OUTER] JOIN](#left-outer-join) - - [RIGHT [OUTER] JOIN](#right-outer-join) - - [FULL [OUTER] JOIN](#full-outer-join) -- [Troubleshoot joins](#troubleshoot-joins) - -## Syntax - -```sql -SELECT_clause -FROM -[INNER | LEFT [OUTER] | RIGHT [OUTER] | FULL [OUTER]] JOIN -ON -[WHERE_clause] -[GROUP_BY_clause] -[HAVING_clause] -[ORDER_BY_clause] -``` - -### Arguments - -- **left_join_items**: One or more tables specified in the `FROM` clause that - represent the left side of the join. -- **right_join_items**: One or more tables specified in the `JOIN` clause that - represent the right side of the join. -- **join_condition**: A predicate expression in the `ON` clause that uses the - `=` (equal to) comparison operator to compare column values from the left side - of the join to column values on the right side of the join. Rows with values - that match the defined predicate are joined using the specified - [join type](#join-types). - - -
- -{{% note %}} -If both sides of the join include columns with the same name, you need to -use the fully-qualified reference to prevent ambiguity. -A _fully-qualified reference_ uses dot notation to reference both the table name -and the column name--for example: `table_name.column_name` -{{% /note %}} - -## Join types - -The following joins types are supported: - -{{< flex >}} -{{< flex-content "quarter" >}} - -

INNER JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="inner small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

LEFT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="left small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

RIGHT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="right small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

FULL [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="full small center" >}} -
-{{< /flex-content >}} -{{< /flex >}} - -#### Join sample tables - -The examples below illustrate join methods using the following tables: - -{{% influxdb/custom-timestamps %}} - -##### prod_line - -| time | station | produced | -| :------------------- | :-----: | -------: | -| 2022-01-01T08:00:00Z | B1 | 26 | -| 2022-01-01T09:00:00Z | B1 | 54 | -| 2022-01-01T10:00:00Z | B1 | 56 | -| 2022-01-01T11:00:00Z | B1 | | -| 2022-01-01T12:00:00Z | B1 | 82 | - -##### errors - -| time | station | level | message | -| :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### INNER JOIN - -Inner joins combine rows from tables on the left and right side of the join -based on common column values defined in the `ON` clause. Rows that don't have -matching column values are not included in the output table. - -{{% influxdb/custom-timestamps %}} - -#### Inner join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -RIGHT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` -##### Inner join results - -| time | station | produced | time | station | level | message | -| :------------------- | :-----: | -------: | :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### LEFT [OUTER] JOIN - -A left outer join returns all rows from the left side of the join and only -returns data from the right side of the join in rows with matching column values -defined in the `ON` clause. - -{{% influxdb/custom-timestamps %}} - -#### Left outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -LEFT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` - -##### Left outer join results - -| time | station | produced | time | station | level | message | -| -------------------- | ------- | -------- | -------------------- | ------- | ----- | -------------------- | -| 2022-01-01T08:00:00Z | B1 | 26 | | | | | -| 2022-01-01T09:00:00Z | B1 | 54 | | | | | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | -| 2022-01-01T12:00:00Z | B1 | 82 | | | | | - -{{% /influxdb/custom-timestamps %}} - - -### RIGHT [OUTER] JOIN - -A right outer join returns all rows from the right side of the join and only -returns data from the left side of the join in rows with matching column values -defined in the `ON` clause. - -{{% influxdb/custom-timestamps %}} - -#### Right outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -RIGHT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` - -##### Right outer join results - -| time | station | produced | time | station | level | message | -| :------------------- | :-----: | -------: | :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### FULL [OUTER] JOIN - -A full outer join returns all data from the left and right sides of the join and -combines rows with matching column values defined in the `ON` clause. -Data that is not available on each respective side of the join is NULL. - -{{% influxdb/custom-timestamps %}} - -#### Full outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -FULL JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - time -``` - -##### Full outer join results - -| time | station | produced | time | station | level | message | -| -------------------- | ------- | -------- | -------------------- | ------- | ----- | -------------------- | -| 2022-01-01T08:00:00Z | B1 | 26 | | | | | -| 2022-01-01T09:00:00Z | B1 | 54 | | | | | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | -| 2022-01-01T12:00:00Z | B1 | 82 | | | | | - -{{% /influxdb/custom-timestamps %}} - -## Troubleshoot joins - -### Ambiguous reference to unqualified field - -If a column exists on both sides of the join and is used in in the `SELECT`, -`ON`, `WHERE`, `HAVING`, `GROUP BY`, or `ORDER BY` clause, you must use a -[fully-qualified reference](#fully-qualified-reference). For example, if both -sides of the join have a `time` column and you want to explicitly select a -time column, you must specifiy which side of the join to use the time column from: - -{{% code-callout "prod_line.time" "green" %}} -``` -SELECT - prod_line.time, - produced, - message, -FROM - prod_line -INNER JOIN errors ON - -- ... -``` -{{% /code-callout %}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/limit.md b/content/influxdb/cloud-serverless/reference/sql/limit.md index c8ccff561..cfeb095da 100644 --- a/content/influxdb/cloud-serverless/reference/sql/limit.md +++ b/content/influxdb/cloud-serverless/reference/sql/limit.md @@ -7,70 +7,10 @@ menu: name: LIMIT clause parent: SQL reference weight: 206 + +source: /content/shared/sql-reference/limit.md --- -The `LIMIT` clause limits the number of rows returned by a query to a specified non-negative integer. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT -``` - -## Examples - -### Limit results to a maximum of five rows - -```sql -SELECT - "water_level","location", "time" -FROM - "h2o_feet" -LIMIT - 5 -``` -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns a maximum of 5 results. - -| location | time | water_level | -| :----------- | :----------------------- | ----------- | -| coyote_creek | 2019-08-28T00:00:00.000Z | 4.206 | -| coyote_creek | 2019-08-28T00:06:00.000Z | 4.052 | -| coyote_creek | 2019-08-28T00:12:00.000Z | 3.901 | -| coyote_creek | 2019-08-28T00:18:00.000Z | 3.773 | -| coyote_creek | 2019-08-28T00:24:00.000Z | 3.632 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Sort and limit results - -Use the `ORDER BY` and `LIMIT` clauses to first sort results by specified columns, -then limit the sorted results by a specified number. - -```sql -SELECT - "water_level", "location", "time" -FROM - "h2o_feet" -ORDER BY - "water_level" DESC -LIMIT - 3 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns the highest 3 `water_level` readings in the `h2o_feet` measurement. - -| location | time | water_level | -| :----------- | :----------------------- | ----------- | -| coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | -| coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | -| coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | -{{% /expand %}} -{{< /expand-wrapper >}} - + diff --git a/content/influxdb/cloud-serverless/reference/sql/operators/_index.md b/content/influxdb/cloud-serverless/reference/sql/operators/_index.md index 306f327a4..baa9f2507 100644 --- a/content/influxdb/cloud-serverless/reference/sql/operators/_index.md +++ b/content/influxdb/cloud-serverless/reference/sql/operators/_index.md @@ -8,11 +8,10 @@ menu: name: Operators parent: SQL reference weight: 211 + +source: /content/shared/sql-reference/operators/_index.md --- -SQL operators are reserved words or characters which perform certain operations, -including comparisons and arithmetic. - -{{< children type="anchored-list" >}} - -{{< children hlevel="h2" >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/operators/arithmetic.md b/content/influxdb/cloud-serverless/reference/sql/operators/arithmetic.md index 50f36d099..474091170 100644 --- a/content/influxdb/cloud-serverless/reference/sql/operators/arithmetic.md +++ b/content/influxdb/cloud-serverless/reference/sql/operators/arithmetic.md @@ -17,140 +17,10 @@ list_code_example: | | `*` | Multiplication | `2 * 3` | `6` | | `/` | Division | `6 / 3` | `2` | | `%` | Modulo | `7 % 2` | `1` | + +source: /content/shared/sql-reference/operators/arithmetic.md --- -Arithmetic operators take two numeric values (either literals or variables) -and perform a calculation that returns a single numeric value. - -| Operator | Description | | -| :------: | :------------- | :------------------------------------- | -| `+` | Addition | [{{< icon "link" >}}](#addition) | -| `-` | Subtraction | [{{< icon "link" >}}](#subtraction) | -| `*` | Multiplication | [{{< icon "link" >}}](#multiplication) | -| `/` | Division | [{{< icon "link" >}}](#division) | -| `%` | Modulo | [{{< icon "link" >}}](#modulo) | - -## + {#addition .monospace} - -The `+` operator adds two operands together and returns the sum. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 + 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(1) + int64(2) | -| ------------------: | -| 3 | - -{{% /flex-content %}} -{{< /flex >}} - -## - {#subtraction .monospace} - -The `-` operator subtracts the right operand from the left operand and returns -the difference. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 4 - 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(4) - int64(2) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -## * {#multiplication .monospace} - -The `*` operator multiplies two operands together and returns the product. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 2 * 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(2) * int64(3) | -| ------------------: | -| 6 | - -{{% /flex-content %}} -{{< /flex >}} - -## / {#division .monospace} - -The `/` operator divides the left operand by the right operand and returns the quotient. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 6 / 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(6) / int64(3) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -## % {#modulo .monospace} - -The `%` (modulo) operator divides the left operand by the right operand and returns the -remainder. If the left operand is not divisible by the right operand, it returns -the left operand. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 8 % 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(8) % Int64(3) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 % 8 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) % Int64(8) | -| ------------------: | -| 3 | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/operators/bitwise.md b/content/influxdb/cloud-serverless/reference/sql/operators/bitwise.md index af276723e..1c5630c43 100644 --- a/content/influxdb/cloud-serverless/reference/sql/operators/bitwise.md +++ b/content/influxdb/cloud-serverless/reference/sql/operators/bitwise.md @@ -16,137 +16,10 @@ list_code_example: | | `^` | Bitwise xor | `5 ^ 3` | `6` | | `>>` | Bitwise shift right | `5 >> 3` | `0` | | `<<` | Bitwise shift left | `5 << 3` | `40` | + +source: /content/shared/sql-reference/operators/bitwise.md --- -Bitwise operators perform bitwise operations on bit patterns or binary numerals. - -| Operator | Meaning | | -| :------: | :------------------ | :------------------------------------------ | -| `&` | Bitwise and | [{{< icon "link" >}}](#bitwise-and) | -| `\|` | Bitwise or | [{{< icon "link" >}}](#bitwise-or) | -| `^` | Bitwise xor | [{{< icon "link" >}}](#bitwise-xor) | -| `>>` | Bitwise shift right | [{{< icon "link" >}}](#bitwise-shift-right) | -| `<<` | Bitwise shift left | [{{< icon "link" >}}](#bitwise-shift-left) | - -## & {#bitwise-and .monospace} - -The `&` (bitwise AND) operator compares each bit of the left operand to the -corresponding bit of the right operand. -If both bits are 1, the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 & 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) & Int64(3) | -| ------------------: | -| 1 | - -{{% /flex-content %}} -{{< /flex >}} - -## \| {#bitwise-or .monospace} - -The `|` (bitwise OR or inclusive OR) operator compares each bit of the left -operand to the corresponding bit of the right operand. -If either bit is 1, the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 | 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \| Int64(3) | -| -------------------: | -| 7 | - -{{% /flex-content %}} -{{< /flex >}} - -## ^ {#bitwise-xor .monospace} - -The `^` (bitwise XOR or exclusive OR) operator compares each bit of the left -operand to the corresponding bit of the right operand. -If the bit in one of the operands is 0 and the bit in the other operand is 1, -the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 ^ 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) BIT_XOR Int64(3) | -| ------------------------: | -| 6 | - -{{% /flex-content %}} -{{< /flex >}} - -## \>\> {#bitwise-shift-right .monospace} - -The `>>` (bitwise shift right) operator shifts the bits in the left operand to -the right by the number of positions specified in the right operand. -For unsigned numbers, bit positions vacated by the shift operation are filled with 0. -For signed numbers, the sign bit is used to fill the vacated bit positions. -If the number is positive, the bit position is filled with 0. -If the number is negative, the bit position is filled with 1. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 >> 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \>\> Int64(3) | -| ---------------------: | -| 0 | - -{{% /flex-content %}} -{{< /flex >}} - -## \<\< {#bitwise-shift-left .monospace} - -The `<<` (bitwise shift left) operator shifts the bits in the left operand to -the left by the number of positions specified in the right operand. -Bit positions vacated by the shift operation are filled with 0. -Bits that shift off the end are discarded, including the sign bit. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 << 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \<\< Int64(3) | -| ---------------------: | -| 40 | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/operators/comparison.md b/content/influxdb/cloud-serverless/reference/sql/operators/comparison.md index 804912c06..313e8994d 100644 --- a/content/influxdb/cloud-serverless/reference/sql/operators/comparison.md +++ b/content/influxdb/cloud-serverless/reference/sql/operators/comparison.md @@ -23,267 +23,10 @@ list_code_example: | | `~*` | Matches a regular expression _(case-insensitive)_ | `'Abc' ~* 'A.*'` | | `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | | `!~*` | Does not match a regular expression _(case-insensitive)_ | `'Abc' !~* 'a.*'` | + +source: /content/shared/sql-reference/operators/comparison.md --- -Comparison operators evaluate the relationship between the left and right -operands and returns `true` or `false`. - - -| Operator | Meaning | | -| :------: | :------------------------------------------------------- | :------------------------------------------------------ | -| `=` | Equal to | [{{< icon "link" >}}](#equal-to) | -| `<>` | Not equal to | [{{< icon "link" >}}](#not-equal-to) | -| `!=` | Not equal to | [{{< icon "link" >}}](#not-equal-to) | -| `>` | Greater than | [{{< icon "link" >}}](#greater-than) | -| `>=` | Greater than or equal to | [{{< icon "link" >}}](#greater-than-or-equal) | -| `<` | Less than | [{{< icon "link" >}}](#less-than) | -| `<=` | Less than or equal to | [{{< icon "link" >}}](#less-than-or-equal) | -| `~` | Matches a regular expression | [{{< icon "link" >}}](#regexp-match) | -| `~*` | Matches a regular expression _(case-insensitive)_ | [{{< icon "link" >}}](#regexp-match-case-insensitive) | -| `!~` | Does not match a regular expression | [{{< icon "link" >}}](#regexp-nomatch) | -| `!~*` | Does not match a regular expression _(case-insensitive)_ | [{{< icon "link" >}}](#regexp-nomatch-case-insensitive) | - -## = {#equal-to .monospace} - -The `=` operator compares the left and right operands and, if equal, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 = 123 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) = Int64(123) | -| :---------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !=, <> {#not-equal-to .monospace} - -The `!=` and `<>` operators compare the left and right operands and, if not equal, -returns `true`. Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 != 456 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) != Int64(456) | -| :----------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 <> 456 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) != Int64(456) | -| :----------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## > {#greater-than .monospace} - -The `>` operator compares the left and right operands and, if the left operand -is greater than the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 > 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) > Int64(2) | -| :------------------ | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## >= {#greater-than-or-equal .monospace} - -The `>=` operator compares the left and right operands and, if the left operand -is greater than or equal to the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 >= 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) >= Int64(2) | -| :------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## < {#less-than .monospace} - -The `<` operator compares the left and right operands and, if the left operand -is less than the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 < 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int641(1) < Int64(2) | -| :------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## <= {#less-than-or-equal .monospace} - -The `<=` operator compares the left and right operands and, if the left operand -is less than or equal to the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 <= 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int641(1) <= Int64(2) | -| :-------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## ~ {#regexp-match .monospace} - -The `~` operator compares the left string operand to the right regular expression -operand and, if it matches (case-sensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'abc' ~ 'a.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("abc") ~ Utf8("a.*") | -| :------------------------ | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## ~* {#regexp-match-case-insensitive .monospace} - -The `~*` operator compares the left string operand to the right regular expression -operand and, if it matches (case-insensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Abc' ~* 'A.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("Abc") ~* Utf8("A.*") | -| :------------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !~ {#regexp-nomatch .monospace} - -The `!~` operator compares the left string operand to the right regular expression -operand and, if it does not match (case-sensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'abc' !~ 'd.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("abc") !~ Utf8("d.*") | -| :------------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !~* {#regexp-nomatch-case-insensitive .monospace} - -The `!~*` operator compares the left string operand to the right regular expression -operand and, if it does not match (case-insensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Abc' !~* 'a.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("Abc") !~* Utf8("a.*") | -| :-------------------------- | -| false | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/operators/logical.md b/content/influxdb/cloud-serverless/reference/sql/operators/logical.md index b3e21eb05..2dfbbc041 100644 --- a/content/influxdb/cloud-serverless/reference/sql/operators/logical.md +++ b/content/influxdb/cloud-serverless/reference/sql/operators/logical.md @@ -21,443 +21,10 @@ list_code_example: | | `LIKE` | Returns true if the left operand matches the right operand pattern string. | | `NOT` | Negates the subsequent expression. | | `OR` | Returns true if any operand is true. Otherwise, returns false. | + +source: /content/shared/sql-reference/operators/logical.md --- -Logical operators combine or manipulate conditions in a SQL query. - -| Operator | Meaning | | -| :-------: | :------------------------------------------------------------------------- | :------------------------------ | -| `AND` | Returns true if both operands are true. Otherwise, returns false. | [{{< icon "link" >}}](#and) | -| `BETWEEN` | Returns true if the left operand is within the range of the right operand. | [{{< icon "link" >}}](#between) | -| `EXISTS` | Returns true if the results of a subquery are not empty. | [{{< icon "link" >}}](#exists) | -| `IN` | Returns true if the left operand is in the right operand list. | [{{< icon "link" >}}](#in) | -| `LIKE` | Returns true if the left operand matches the right operand pattern string. | [{{< icon "link" >}}](#like) | -| `NOT` | Negates the subsequent expression. | [{{< icon "link" >}}](#not) | -| `OR` | Returns true if any operand is true. Otherwise, returns false. | [{{< icon "link" >}}](#or) | - -{{% note %}} -#### Sample data - -Query examples on this page use the following sample data sets: - -- [Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data) -- [Home sensor actions sample data](/influxdb/cloud-serverless/reference/sample-data/#home-sensor-actions-data) -{{% /note %}} - -## AND {.monospace} - -The `AND` operand returns `true` if both operands are `true`. Otherwise, it returns false. -This operator is typically used in the [`WHERE` clause](/influxdb/cloud-serverless/reference/sql/where/) -to combine multiple conditions. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT true AND false AS "AND condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| AND condition | -| :------------ | -| false | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`AND` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co > 10 - AND room = 'Kitchen' -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## BETWEEN {.monospace} - -The `BETWEEN` operator returns `true` if the left numeric operand is within the -range specified in the right operand. Otherwise, it returns `false` - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 6 BETWEEN 5 AND 8 AS "BETWEEN condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| BETWEEN condition | -| :---------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`BETWEEN` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co BETWEEN 5 AND 10 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## EXISTS {.monospace} - -The `EXISTS` operator returns `true` if result of a -[correlated subquery](/influxdb/cloud-serverless/reference/sql/subqueries/#correlated-subqueries) -is not empty. Otherwise it returns `false`. - -_See [SQL subquery operators](/influxdb/cloud-serverless/reference/sql/subqueries/#subquery-operators)._ - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`EXISTS` operator with a subquery in the `WHERE` clause" %}} - -```sql -SELECT * -FROM - home home_actions -WHERE EXISTS ( - SELECT * - FROM home - WHERE - home.co = home_actions.co - 1 -) -ORDER BY time -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | -| 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | -| 1 | 36.1 | Living Room | 22.3 | 2022-01-01T15:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## IN {.monospace} - -The `IN` operator returns `true` if the left operand is in the right operand -list or subquery result. Otherwise, it returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'John' IN ('Jane', 'John') AS "IN condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| IN condition | -| :----------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -_See [SQL subquery operators](/influxdb/cloud-serverless/reference/sql/subqueries/#subquery-operators)._ - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`IN` operator with a list in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room IN ('Bathroom', 'Bedroom', 'Kitchen') -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`IN` operator with a subquery in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room IN ( - SELECT DISTINCT room - FROM home_actions - ) -ORDER BY time -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## LIKE {.monospace} - -The `LIKE` operator returns `true` if the left operand matches the string pattern -specified in the right operand. -`LIKE` expressions support [SQL wildcard characters](#sql-wildcard-characters). - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'John' LIKE 'J_%n' AS "LIKE condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| LIKE condition | -| :------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -{{< expand-wrapper >}} -{{% expand "`LIKE` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room LIKE '%Room' -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -### SQL wildcard characters - -The InfluxDB SQL implementation supports the following wildcard characters when -using the `LIKE` operator to match strings to a pattern. - -| Character | Description | -| :-------: | :--------------------------------- | -| `%` | Represents zero or more characters | -| `_` | Represents any single character | - -## NOT {.monospace} - -The `NOT` operator negates the subsequent expression. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT NOT true AS "NOT condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| NOT condition | -| :------------ | -| false | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`NOT IN`" %}} - -```sql -SELECT * -FROM home -WHERE - room NOT IN ('Kitchen', 'Bathroom') -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "`NOT EXISTS`" %}} - -```sql -SELECT * -FROM - home home_actions -WHERE NOT EXISTS ( - SELECT * - FROM home - WHERE - home.co = home_actions.co + 4 -) -ORDER BY time -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "`NOT BETWEEN`" %}} - -```sql -SELECT * -FROM home -WHERE - co NOT BETWEEN 1 AND 22 - AND room = 'Kitchen' -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## OR {.monospace} - -The `OR` operator returns `true` if any operand is `true`. -Otherwise, it returns `false`. -This operator is typically used in the [`WHERE` clause](/influxdb/cloud-serverless/reference/sql/where/) -to combine multiple conditions. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT true OR false AS "OR condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| OR condition | -| :----------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`OR` in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co > 20 - OR temp > 23 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/operators/other.md b/content/influxdb/cloud-serverless/reference/sql/operators/other.md index cd4521194..4e268a36e 100644 --- a/content/influxdb/cloud-serverless/reference/sql/operators/other.md +++ b/content/influxdb/cloud-serverless/reference/sql/operators/other.md @@ -13,51 +13,10 @@ list_code_example: | | :------------: | :----------------------- | :-------------------------------------- | :------------ | | `\|\|` | Concatenate strings | `'Hello' \|\| ' world'` | `Hello world` | | `AT TIME ZONE` | Apply a time zone offset | _[View example](/influxdb/cloud-serverless/reference/sql/operators/other/#at-time-zone)_ | | + +source: /content/shared/sql-reference/operators/other.md --- -SQL supports miscellaneous operators that perform various operations. - -| Operator | Meaning | | -| :------: | :------------------ | :------------------------------------------ | -| `\|\|` | Concatenate strings | [{{< icon "link" >}}](#concatenate-strings) | - -## || {#concatenate-strings} - -The `||` operator concatenates two string operands into a single string. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Hello' || ' world' AS "Concatenated" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Concatenated | -| :----------- | -| Hello world | - -{{% /flex-content %}} -{{< /flex >}} - -## AT TIME ZONE - -The `AT TIME ZONE` operator applies the offset of the specified time zone to a -timestamp type and returns an updated UTC timestamp. Time zone offsets are -provided by the the operating system time zone database. - -{{% note %}} -Timestamp types in InfluxDB always represent a UTC time. The returned timestamp -is a UTC timestamp adjusted for the offset of the specified time zone. -{{% /note %}} - -```sql -SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'UTC with TZ offset' -``` - -| UTC with TZ offset | -| :----------------------- | -| 2024-01-01T08:00:00.000Z | + diff --git a/content/influxdb/cloud-serverless/reference/sql/order-by.md b/content/influxdb/cloud-serverless/reference/sql/order-by.md index 09a5c193a..fe6f921ac 100644 --- a/content/influxdb/cloud-serverless/reference/sql/order-by.md +++ b/content/influxdb/cloud-serverless/reference/sql/order-by.md @@ -8,91 +8,10 @@ menu: name: ORDER BY clause parent: SQL reference weight: 204 + +source: /content/shared/sql-reference/order-by.md --- -The `ORDER BY` clause sort results by specified columns and order. -Sort data based on fields, tags, and timestamps. -The following orders are supported: - -- `ASC`: ascending _(default)_ -- `DESC`: descending - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -[SELECT CLAUSE] [FROM CLAUSE] [ ORDER BY expression [ ASC | DESC ][, …] ] -``` - -{{% note %}} -**Note:** If your query includes a `GROUP BY` clause, the `ORDER BY` clause must appear **after** the `GROUP BY` clause. -{{% /note %}} - -## Examples - -### Sort data by time with the most recent first - -```sql -SELECT - "water_level", "time" -FROM - "h2o_feet" -WHERE - "location" = 'coyote_creek' -ORDER BY - time DESC -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -| time | water_level | -| :----------------------- | :----------- | -| 2019-09-17T16:24:00.000Z | 3.235 | -| 2019-09-17T16:18:00.000Z | 3.314 | -| 2019-09-17T16:12:00.000Z | 3.402 | -| 2019-09-17T16:06:00.000Z | 3.497 | -| 2019-09-17T16:00:00.000Z | 3.599 | -| 2019-09-17T15:54:00.000Z | 3.704 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Sort data by tag or field values - -```sql -SELECT - "water_level", "time", "location" -FROM - "h2o_feet" -ORDER BY - "location", "water_level" DESC -``` - -### Sort data by selection order - -```sql -SELECT - "location","water_level", "time" -FROM - "h2o_feet" -ORDER BY - 1, 2 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query sorts results the location of a column in the `SELECT` statement: -first by `location` (1), and second by `water_level` (2). - -| location | time | water_level | -| :----------- | :----------------------- | :---------- | -| coyote_creek | 2019-08-28T14:30:00.000Z | -0.61 | -| coyote_creek | 2019-08-29T15:18:00.000Z | -0.594 | -| coyote_creek | 2019-08-28T14:36:00.000Z | -0.591 | -| coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | -| coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | -| coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/select.md b/content/influxdb/cloud-serverless/reference/sql/select.md index 974fce1f2..82a3e2fc8 100644 --- a/content/influxdb/cloud-serverless/reference/sql/select.md +++ b/content/influxdb/cloud-serverless/reference/sql/select.md @@ -9,106 +9,10 @@ menu: weight: 201 related: - /influxdb/cloud-serverless/reference/sql/subqueries/ + +source: /content/shared/sql-reference/select.md --- -Use the `SELECT` statement to query data from an InfluxDB measurement. -The `SELECT` clause is required when querying data in SQL. - -- [Syntax](#syntax) -- [Examples](#examples) - -### Syntax - -```sql -SELECT a, b, "time" FROM -``` - -{{% note %}} -**Note:** When querying InfluxDB, the `SELECT` statement **always requires** a `FROM` clause. -{{% /note %}} - -The SELECT clause supports the following: - - - `SELECT *` - return all tags, fields and timestamps. - - `SELECT DISTINCT` to return all distinct (different) values. - - `SELECT <"field" or "tag">` - returns a specified field or tag. - - `SELECT <"field" or "tag">, <"field" or "tag">` - returns more than one tag or field. - - `SELECT <"field"> AS a `- return the field as the alias. - -## Examples - -The following examples use data from the NOAA database. -To download the NOAA test data see [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). - -### Select all fields and tags from a measurement - -```sql -SELECT * FROM h2o_feet LIMIT 10 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -| level description | location | time | water_level | -| :------------------------ | :----------- | :----------------------- | :---------- | -| at or greater than 9 feet | coyote_creek | 2019-09-01T00:00:00.000Z | 9.126144144 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T00:06:00.000Z | 9.009 | -| between 6 and 9 feet | coyote_creek | 2019-09-01T00:12:00.000Z | 8.862 | -| between 6 and 9 feet | coyote_creek | 2019-09-01T00:18:00.000Z | 8.714 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select specific tags and fields from a measurement - -```sql -SELECT "location", "water_level" FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "1" %}} -| location | water_level | -| :----------- | :---------- | -| coyote_creek | 9.126144144 | -| coyote_creek | 9.009 | -| coyote_creek | 8.862 | -| coyote_creek | 8.714 | -| coyote_creek | 8.547 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select a field, tag and timestamp from a measurement - -```sql -SELECT "water_level", "location", "time" FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "2" %}} -| location | time | water_level | -| :----------- | :----------------------- | :---------- | -| coyote_creek | 2019-08-20T00:00:00.000Z | 8.638 | -| coyote_creek | 2019-08-20T00:06:00.000Z | 8.658 | -| coyote_creek | 2019-08-20T00:12:00.000Z | 8.678 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select a field and perform basic arithmetic - -The following query takes the value of water_level, multiplies it by 3 and adds 5 to the result. - -```sql -SELECT ("water_level" * 3) + 5 FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "3" %}} -| water_level | -| :----------------- | -| 30.128 | -| 30.641000000000002 | -| 31.142000000000003 | -| 31.586 | -| 32.027 | -| 32.378432432 | -{{% /expand %}} -{{< /expand-wrapper >}} - + diff --git a/content/influxdb/cloud-serverless/reference/sql/subqueries.md b/content/influxdb/cloud-serverless/reference/sql/subqueries.md index 6d31d60fe..96c864753 100644 --- a/content/influxdb/cloud-serverless/reference/sql/subqueries.md +++ b/content/influxdb/cloud-serverless/reference/sql/subqueries.md @@ -13,747 +13,10 @@ related: - /influxdb/cloud-serverless/reference/sql/select/ - /influxdb/cloud-serverless/reference/sql/where/ - /influxdb/cloud-serverless/reference/sql/having/ + +source: /content/shared/sql-reference/subqueries.md --- -Subqueries (also known as inner queries or nested queries) are queries within -a query. -Subqueries can be used in `SELECT`, `FROM`, `WHERE`, and `HAVING` clauses. - -- [Subquery operators](#subquery-operators) - - [[ NOT ] EXISTS](#-not--exists) - - [[ NOT ] IN](#-not--in) -- [SELECT clause subqueries](#select-clause-subqueries) -- [FROM clause subqueries](#from-clause-subqueries) -- [WHERE clause subqueries](#where-clause-subqueries) -- [HAVING clause subqueries](#having-clause-subqueries) -- [Subquery categories](#subquery-categories) - - [Correlated subqueries](#correlated-subqueries) - - [Non-correlated subqueries](#non-correlated-subqueries) - - [Scalar subqueries](#scalar-subqueries) - - [Non-scalar subqueries](#non-scalar-subqueries) - -{{% note %}} -#### Sample data - -Query examples on this page use the following sample data sets: - -- [Get started home sensor sample data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data) -- [Home sensor actions sample data](/influxdb/cloud-serverless/reference/sample-data/#home-sensor-actions-data) -- [NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data) - -{{% /note %}} - -## Subquery operators - -- [[ NOT ] EXISTS](#-not--exists) -- [[ NOT ] IN](#-not--in) - -### [ NOT ] EXISTS - -The `EXISTS` operator returns all rows where a -_[correlated subquery](#correlated-subqueries)_ produces one or more matches for -that row. `NOT EXISTS` returns all rows where a _correlated subquery_ produces -zero matches for that row. Only _correlated subqueries_ are supported. - -#### Syntax {#-not-exists-syntax} - -```sql -[NOT] EXISTS (subquery) -``` - -### [ NOT ] IN - -The `IN` operator returns all rows where a given expression’s value can be found -in the results of a _[correlated subquery](#correlated-subqueries)_. -`NOT IN` returns all rows where a given expression’s value cannot be found in -the results of a subquery or list of values. - -#### Syntax {#-not-in-syntax} - -```sql -expression [NOT] IN (subquery|list-literal) -``` - -#### Examples {#-not-in-examples} - -{{< expand-wrapper >}} -{{% expand "View `IN` examples using a query" %}} -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[IN](#) -[NOT IN](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - room IN ( - SELECT - DISTINCT room - FROM - home_actions - ) -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - room NOT IN ( - SELECT - DISTINCT room - FROM - home_actions - ) -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} -{{% /expand %}} - -{{% expand "View `IN` examples using a list literal" %}} -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[IN](#) -[NOT IN](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM home -WHERE room IN ('Bathroom', 'Bedroom', 'Kitchen') -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM home -WHERE room NOT IN ('Bathroom', 'Bedroom', 'Kitchen') -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## SELECT clause subqueries - -`SELECT` clause subqueries use values returned from the inner query as part -of the outer query's `SELECT` list. -The `SELECT` clause only supports [scalar subqueries](#scalar-subqueries) that -return a single value per execution of the inner query. -The returned value can be unique per row. - -### Syntax {#select-subquery-syntax} - -```sql -SELECT [expression1[, expression2, ..., expressionN],] () -``` - -{{% note %}} -`SELECT` clause subqueries can be used as an alternative to `JOIN` operations. -{{% /note %}} - -### Examples {#select-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "`SELECT` clause with correlated subquery" %}} - -```sql -SELECT - time, - room, - co, - ( - SELECT - MAX(description) - FROM - home_actions - WHERE - time = home.time - AND room = home.room - AND level != 'ok' - ) AS "Alert Description" -FROM - home -ORDER BY - room, - time -``` - -#### Inner query results - -Because the inner query is a [correlated subquery](#correlated-subqueries), -the result depends on the values of `room` and `time` columns in the outer query. -The results below represent the action description for each `room` and `time` -combination with a `level` value that does not equal `ok`. - -{{% influxdb/custom-timestamps %}} -| time | room | MAX(home_actions.description) | -| :------------------- | :---------- | :------------------------------------------ | -| 2022-01-01T18:00:00Z | Kitchen | Carbon monoxide level above normal: 18 ppm. | -| 2022-01-01T19:00:00Z | Kitchen | Carbon monoxide level above normal: 22 ppm. | -| 2022-01-01T20:00:00Z | Kitchen | Carbon monoxide level above normal: 26 ppm. | -| 2022-01-01T19:00:00Z | Living Room | Carbon monoxide level above normal: 14 ppm. | -| 2022-01-01T20:00:00Z | Living Room | Carbon monoxide level above normal: 17 ppm. | -{{% /influxdb/custom-timestamps %}} - -#### Outer query results - -{{% influxdb/custom-timestamps %}} -| time | room | co | Alert Description | -| :------------------- | :---------- | --: | :------------------------------------------ | -| 2022-01-01T08:00:00Z | Kitchen | 0 | | -| 2022-01-01T09:00:00Z | Kitchen | 0 | | -| 2022-01-01T10:00:00Z | Kitchen | 0 | | -| 2022-01-01T11:00:00Z | Kitchen | 0 | | -| 2022-01-01T12:00:00Z | Kitchen | 0 | | -| 2022-01-01T13:00:00Z | Kitchen | 1 | | -| 2022-01-01T14:00:00Z | Kitchen | 1 | | -| 2022-01-01T15:00:00Z | Kitchen | 3 | | -| 2022-01-01T16:00:00Z | Kitchen | 7 | | -| 2022-01-01T17:00:00Z | Kitchen | 9 | | -| 2022-01-01T18:00:00Z | Kitchen | 18 | Carbon monoxide level above normal: 18 ppm. | -| 2022-01-01T19:00:00Z | Kitchen | 22 | Carbon monoxide level above normal: 22 ppm. | -| 2022-01-01T20:00:00Z | Kitchen | 26 | Carbon monoxide level above normal: 26 ppm. | -| 2022-01-01T08:00:00Z | Living Room | 0 | | -| 2022-01-01T09:00:00Z | Living Room | 0 | | -| 2022-01-01T10:00:00Z | Living Room | 0 | | -| 2022-01-01T11:00:00Z | Living Room | 0 | | -| 2022-01-01T12:00:00Z | Living Room | 0 | | -| 2022-01-01T13:00:00Z | Living Room | 0 | | -| 2022-01-01T14:00:00Z | Living Room | 0 | | -| 2022-01-01T15:00:00Z | Living Room | 1 | | -| 2022-01-01T16:00:00Z | Living Room | 4 | | -| 2022-01-01T17:00:00Z | Living Room | 5 | | -| 2022-01-01T18:00:00Z | Living Room | 9 | | -| 2022-01-01T19:00:00Z | Living Room | 14 | Carbon monoxide level above normal: 14 ppm. | -| 2022-01-01T20:00:00Z | Living Room | 17 | Carbon monoxide level above normal: 17 ppm. | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FROM clause subqueries - -`FROM` clause subqueries return a set of results that is then queried and -operated on by the outer query. - -### Syntax {#from-subquery-syntax} - -```sql -SELECT expression1[, expression2, ..., expressionN] FROM () -``` - -### Examples {#from-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "View `FROM` clause subquery example" %}} - -The following query returns the average of maximum values per room. -The inner query returns the maximum value for each field from each room. -The outer query uses the results of the inner query and returns the average -maximum value for each field. - -```sql -SELECT - AVG(max_co) AS avg_max_co, - AVG(max_hum) AS avg_max_hum, - AVG(max_temp) AS avg_max_temp -FROM - ( - SELECT - room, - MAX(co) AS max_co, - MAX(hum) AS max_hum, - MAX(temp) AS max_temp - FROM - home - GROUP BY - room - ) -``` - -#### Inner query results - -| room | max_co | max_hum | max_temp | -| :---------- | -----: | ------: | -------: | -| Living Room | 17 | 36.4 | 22.8 | -| Kitchen | 26 | 36.9 | 23.3 | - -#### Outer query results - -| avg_max_co | avg_max_hum | avg_max_temp | -| ---------: | ----------: | -----------: | -| 21.5 | 36.7 | 23.1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## WHERE clause subqueries - -[`WHERE` clause](/influxdb/cloud-serverless/reference/sql/where/) subqueries -compare an expression to the result of the subquery and return _true_ or _false_. -Rows that evaluate to _false_ or NULL are filtered from results. -The `WHERE` clause supports correlated and non-correlated subqueries -as well as scalar and non-scalar subqueries (depending on the the operator used -in the predicate expression). - -### Syntax {#where-subquery-syntax} - -```sql -SELECT - expression1[, expression2, ..., expressionN] -FROM - -WHERE - expression operator () -``` - -{{% note %}} -`WHERE` clause subqueries can be used as an alternative to `JOIN` operations. -{{% /note %}} - -### Examples {#where-subquery-examples} -{{< expand-wrapper >}} -{{% expand "`WHERE` clause with scalar subquery" %}} - -The following query returns all points with `temp` values above the average -of all `temp` values. The subquery returns the average `temp` value. - -```sql -SELECT - * -FROM - home -WHERE - temp > ( - SELECT - AVG(temp) - FROM - home - ) -``` - -#### Inner query result - -| AVG(home.temp) | -| :----------------- | -| 22.396153846153844 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | -| 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | -| 3 | 36.2 | Kitchen | 22.7 | 2022-01-01T15:00:00Z | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | -| 0 | 36 | Living Room | 22.4 | 2022-01-01T13:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`WHERE` clause with non-scalar subquery" %}} - -Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and -can only return a single column. -The values in the returned column are evaluated as a list. - -The following query returns all points in the `home` measurement associated with -the same timestamps as `warn` level alerts in the `home_actions` measurement. - -```sql -SELECT - * -FROM - home -WHERE - time IN ( - SELECT - DISTINCT time - FROM - home_actions - WHERE - level = 'warn' - ) -``` - -#### Inner query result - -{{% influxdb/custom-timestamps %}} -| time | -| :------------------- | -| 2022-01-01T18:00:00Z | -| 2022-01-01T19:00:00Z | -| 2022-01-01T20:00:00Z | -{{% /influxdb/custom-timestamps %}} - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | -| 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`WHERE` clause with correlated subquery" %}} - -The following query returns rows with temperature values greater than the median -temperature value for each room. The subquery in the `WHERE` clause uses the -`room` value from the outer query to return the median `temp` value for that -specific room. - -```sql -SELECT - time, - room, - temp -FROM - home outer_query -WHERE - temp > ( - SELECT - median(temp) AS temp - FROM - home - WHERE - room = outer_query.room - GROUP BY - room - ) -ORDER BY room, time -``` - -#### Inner query result - -The result of the inner query depends on the value of `room` in the outer query, -but the following table contains the median `temp` value for each room. - -| room | temp | -| :---------- | ---: | -| Living Room | 22.3 | -| Kitchen | 22.7 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| time | room | temp | -| :------------------- | :---------- | ---: | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T13:00:00Z | Kitchen | 22.8 | -| 2022-01-01T14:00:00Z | Kitchen | 22.8 | -| 2022-01-01T18:00:00Z | Kitchen | 23.3 | -| 2022-01-01T19:00:00Z | Kitchen | 23.1 | -| 2022-01-01T13:00:00Z | Living Room | 22.4 | -| 2022-01-01T16:00:00Z | Living Room | 22.4 | -| 2022-01-01T17:00:00Z | Living Room | 22.6 | -| 2022-01-01T18:00:00Z | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | Living Room | 22.5 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## HAVING clause subqueries - -[`HAVING` clause](/influxdb/cloud-serverless/reference/sql/having/) subqueries -compare an expression that uses aggregate values returned by aggregate functions -in the `SELECT` clause to the result of the subquery and return _true_ or _false_. -Rows that evaluate to _false_ or NULL are filtered from results. -The `HAVING` clause supports correlated and non-correlated subqueries -as well as scalar and non-scalar subqueries (depending on the the operator used -in the predicate expression). - -### Syntax {#having-subquery-syntax} - -```sql -SELECT - aggregate_expression1[, aggregate_expression2, ..., aggregate_expressionN] -FROM - -WHERE - -GROUP BY - column_expression1[, column_expression2, ..., column_expressionN] -HAVING - expression operator () -``` - -### Examples {#having-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "`HAVING` clause with scalar subquery" %}} - -The following query returns all two hour blocks of time with average `temp` values -greater then the median `temp` value. - -```sql -SELECT - DATE_BIN(INTERVAL '2 hours', time) AS "2-hour block", - AVG(temp) AS avg_temp -FROM - home -GROUP BY - 1 -HAVING - avg_temp > ( - SELECT - MEDIAN(temp) - FROM - home - ) -``` - -#### Inner query result - -| MEDIAN(home.temp) | -| :---------------- | -| 22.45 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | avg_temp | -| :------------------- | -------: | -| 2022-01-01T12:00:00Z | 22.475 | -| 2022-01-01T16:00:00Z | 22.525 | -| 2022-01-01T18:00:00Z | 22.925 | -| 2022-01-01T14:00:00Z | 22.525 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`HAVING` clause with non-scalar subquery" %}} - -Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and -can only return a single column. -The values in the returned column are evaluated as a list. - -The following query returns the maximum `co` and `temp` values within 2-hour -windows of time where the `time` value associated with time window is also -associated with a warning in the `home_actions` measurement. - -```sql -SELECT - date_bin(INTERVAL '2 hours', time) AS "2-hour block", - max(co) AS max_co, - max(temp) as max_temp -FROM - home -GROUP BY - 1, - room -HAVING - "2-hour block" IN ( - SELECT - DISTINCT time - FROM - home_actions - WHERE - level = 'warn' - ) -``` - -#### Inner query result - -{{% influxdb/custom-timestamps %}} -| time | -| :------------------- | -| 2022-01-01T18:00:00Z | -| 2022-01-01T19:00:00Z | -| 2022-01-01T20:00:00Z | -{{% /influxdb/custom-timestamps %}} - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | max_co | max_temp | -| :------------------- | -----: | -------: | -| 2022-01-01T18:00:00Z | 14 | 22.8 | -| 2022-01-01T18:00:00Z | 22 | 23.3 | -| 2022-01-01T20:00:00Z | 17 | 22.2 | -| 2022-01-01T20:00:00Z | 26 | 22.7 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`HAVING` clause with correlated subquery" %}} - -The following query returns 2-hour windows of time with average `temp` values -greater than the median `temp` value for each room. The subquery in the `HAVING` -clause uses the `room` value from the outer query to return the median `temp` value -for that specific room. - -```sql -SELECT - time, - room, - temp -FROM - home outer_query -WHERE - temp > ( - SELECT - median(temp) AS temp - FROM - home - WHERE - room = outer_query.room - GROUP BY - room - ) -ORDER BY room, time -``` - -#### Inner query result - -The result of the inner query depends on the value of `room` in the outer query, -but the following table contains the median `temp` value for each room. - -| room | temp | -| :---------- | ---: | -| Living Room | 22.3 | -| Kitchen | 22.7 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | room | avg_temp | -| :------------------- | :---------- | -----------------: | -| 2022-01-01T14:00:00Z | Kitchen | 22.75 | -| 2022-01-01T18:00:00Z | Kitchen | 23.200000000000003 | -| 2022-01-01T16:00:00Z | Living Room | 22.5 | -| 2022-01-01T18:00:00Z | Living Room | 22.65 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Subquery categories - -SQL subqueries can be categorized as one or more of the following based on the -behavior of the subquery: - -- [correlated](#correlated-subqueries) or [non-correlated](#non-correlated-subqueries) -- [scalar](#scalar-subqueries) or [non-scalar](#non-scalar-subqueries) - -### Correlated subqueries - -In a **correlated** subquery, the inner query depends on the outer query, using -values from the outer query for its results. -Correlated subqueries can return a maximum of one row, so -[aggregations](/influxdb/cloud-serverless/reference/sql/functions/aggregate/) may -be required in the inner query. - -In the query below, the inner query (`SELECT temp_avg FROM weather WHERE location = home.room`) -depends on data (`home.room`) from the outer query -(`SELECT time, room, temp FROM home`) and is therefore a _correlated_ subquery. - -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - temp = ( - SELECT - temp_avg - FROM - weather - WHERE - location = home.room - ) -``` - -{{% note %}} -#### Correlated subquery performance - -Because correlated subqueries depend on the outer query and typically must -execute for each row returned by the outer query, correlated subqueries are -**less performant** than non-correlated subqueries. -{{% /note %}} - -### Non-correlated subqueries - -In a **non-correlated** subquery, the inner query _doesn't_ depend on the outer -query and executes independently. -The inner query executes first, and then passes the results to the outer query. - -In the query below, the inner query (`SELECT MIN(temp_avg) FROM weather`) can -run independently from the outer query (`SELECT time, temp FROM home`) and is -therefore a _non-correlated_ subquery. - -```sql -SELECT - time, - temp -FROM - home -WHERE - temp < ( - SELECT - MIN(temp_avg) - FROM - weather - ) -``` - -### Scalar subqueries - -A **scalar** subquery returns a single value (one column of one row). -If no rows are returned, the subquery returns NULL. - -The example subquery below returns the average value of a specified column. -This value is a single scalar value. - -```sql -SELECT * FROM home WHERE co > (SELECT avg(co) FROM home) -``` - -### Non-scalar subqueries - -A **non-scalar** subquery returns 0, 1, or multiple rows, each of which may -contain 1 or multiple columns. For each column, if there is no value to return, -the subquery returns NULL. If no rows qualify to be returned, the subquery -returns 0 rows. - -The example subquery below returns all distinct values in a column. -Multiple values are returned. - -```sql -SELECT * FROM home WHERE room IN (SELECT DISTINCT room FROM home_actions) -``` \ No newline at end of file + diff --git a/content/influxdb/cloud-serverless/reference/sql/table-value-constructor.md b/content/influxdb/cloud-serverless/reference/sql/table-value-constructor.md index a4cbf3e7e..96119322a 100644 --- a/content/influxdb/cloud-serverless/reference/sql/table-value-constructor.md +++ b/content/influxdb/cloud-serverless/reference/sql/table-value-constructor.md @@ -7,115 +7,10 @@ menu: influxdb_cloud_serverless: parent: SQL reference weight: 220 + +source: /content/shared/sql-reference/table-value-constructor.md --- -The table value constructor (TVC) uses the `VALUES` keyword to specify a set of -row value expressions to construct into a table. -The TVC can be used in the `FROM` clause -to build an ad hoc table at query time. - -```sql -VALUES (row_value_list)[,...n] -``` - -##### Arguments - -- **row_value_list**: - Comma-delimited list of column values. - Enclose each list in parentheses and separate multiple lists with commas. - Each list must have the same number of values and values must be in the same - order as columns in the table. - Each list must contain a value for each column. - -## Usage - -```sql -SELECT - expression[,...n] -FROM - (VALUES (row_value_list)[,...n]) [AS] table_name(column_name[,...n]) -``` - -{{% note %}} -When using the TVC, the `AS` keyword is optional and implied when naming the -table and providing column names. -{{% /note %}} - -## Examples - -- [Select data from an ad hoc table](#select-data-from-an-ad-hoc-table) - - -### Select data from an ad hoc table - -```sql -SELECT * -FROM - (VALUES ('2023-01-01 12:00:00'::TIMESTAMP, 1.23, 4.56), - ('2023-01-01 13:00:00'::TIMESTAMP, 2.46, 8.1), - ('2023-01-01 13:00:00'::TIMESTAMP, 4.81, 16.2) - ) AS data(time, f1, f2) -``` - -| time | f1 | f2 | -| :------------------- | ---: | ---: | -| 2023-01-01T12:00:00Z | 1.23 | 4.56 | -| 2023-01-01T13:00:00Z | 2.46 | 8.1 | -| 2023-01-01T13:00:00Z | 4.81 | 16.2 | - - + diff --git a/content/influxdb/cloud-serverless/reference/sql/union.md b/content/influxdb/cloud-serverless/reference/sql/union.md index 5ca20bdcc..b42b1fb5a 100644 --- a/content/influxdb/cloud-serverless/reference/sql/union.md +++ b/content/influxdb/cloud-serverless/reference/sql/union.md @@ -8,161 +8,10 @@ menu: name: UNION clause parent: SQL reference weight: 206 + +source: /content/shared/sql-reference/union.md --- -The `UNION` clause combines the results of two or more `SELECT` statements into -a single result set. -By default, `UNION` only keeps unique rows. -To keep all rows, including duplicates, use `UNION ALL`. - -- [Syntax](#syntax) -- [Examples](#examples) - -**When using the `UNION` clause**: - -- The number of columns in each result set must be the same. -- Columns must be in the same order and of the same or compatible data types. - -## Syntax - -```sql -SELECT expression[,...n] -FROM measurement_1 -UNION [ALL] -SELECT expression[,...n] -FROM measurement_2 -``` - -## Examples - -- [Union results from different measurements](#union-results-from-different-measurements) -- [Return the highest and lowest three results in a single result set](#return-the-highest-and-lowest-three-results-in-a-single-result-set) -- [Union query results with custom data](#union-query-results-with-custom-data) - -### Union results from different measurements - -```sql -( - SELECT - 'h2o_pH' AS measurement, - time, - "pH" AS "water_pH" - FROM "h2o_pH" - LIMIT 4 -) -UNION -( - SELECT - 'h2o_quality' AS measurement, - time, - index - FROM h2o_quality - LIMIT 4 -) -``` -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| measurement | time | water_pH | -| :---------- | :------------------- | -------: | -| h2o_pH | 2019-08-27T00:12:00Z | 7 | -| h2o_pH | 2019-08-27T00:18:00Z | 8 | -| h2o_quality | 2019-09-11T01:06:00Z | 89 | -| h2o_pH | 2019-08-27T00:06:00Z | 7 | -| h2o_quality | 2019-09-11T00:00:00Z | 26 | -| h2o_quality | 2019-09-11T01:00:00Z | 19 | -| h2o_quality | 2019-09-11T00:48:00Z | 65 | -| h2o_pH | 2019-08-27T00:00:00Z | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Return the highest and lowest three results in a single result set - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol)._ - -```sql -( - SELECT - 'low' as type, - time, - co - FROM home - ORDER BY co ASC - LIMIT 3 -) -UNION -( - SELECT - 'high' as type, - time, - co - FROM home - ORDER BY co DESC - LIMIT 3 -) -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| type | time | co | -| :--- | :------------------- | --: | -| high | 2022-01-01T20:00:00Z | 26 | -| high | 2022-01-01T19:00:00Z | 22 | -| high | 2022-01-01T18:00:00Z | 18 | -| low | 2022-01-01T14:00:00Z | 0 | -| low | 2022-01-01T10:00:00Z | 0 | -| low | 2022-01-01T08:00:00Z | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Union query results with custom data - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/cloud-serverless/get-started/write/#construct-line-protocol). -It also uses the [table value constructor](/influxdb/cloud-serverless/reference/sql/table-value-constructor/) -to build a table with custom data._ - -```sql -SELECT * -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -UNION -SELECT * FROM - (VALUES (0, 34.2, 'Bedroom', 21.1, '2022-01-01T08:00:00Z'::TIMESTAMP), - (0, 34.5, 'Bedroom', 21.2, '2022-01-01T09:00:00Z'::TIMESTAMP), - (0, 34.6, 'Bedroom', 21.5, '2022-01-01T10:00:00Z'::TIMESTAMP), - (0, 34.5, 'Bedroom', 21.8, '2022-01-01T11:00:00Z'::TIMESTAMP), - (0, 33.9, 'Bedroom', 22.0, '2022-01-01T12:00:00Z'::TIMESTAMP) - ) newRoom(co, hum, room, temp, time) -ORDER BY room, time -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 34.2 | Bedroom | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 34.5 | Bedroom | 21.2 | 2022-01-01T09:00:00Z | -| 0 | 34.6 | Bedroom | 21.5 | 2022-01-01T10:00:00Z | -| 0 | 34.5 | Bedroom | 21.8 | 2022-01-01T11:00:00Z | -| 0 | 33.9 | Bedroom | 22 | 2022-01-01T12:00:00Z | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | -| 0 | 35.9 | Living Room | 22.2 | 2022-01-01T12:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/reference/sql/where.md b/content/influxdb/cloud-serverless/reference/sql/where.md index 0b5035baa..f4b9353f8 100644 --- a/content/influxdb/cloud-serverless/reference/sql/where.md +++ b/content/influxdb/cloud-serverless/reference/sql/where.md @@ -1,7 +1,7 @@ --- title: WHERE clause list_title: WHERE clause -description: > +description: > Use the `WHERE` clause to filter results based on fields, tags, or timestamps. menu: influxdb_cloud_serverless: @@ -10,124 +10,10 @@ menu: weight: 202 related: - /influxdb/cloud-serverless/reference/sql/subqueries/ + +source: /content/shared/sql-reference/where.md --- -Use the `WHERE` clause to filter results based on fields, tags, or timestamps. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause WHERE [(AND|OR) [...]] -``` - -{{% note %}} -**Note:** Unlike InfluxQL, SQL **supports** `OR` in the `WHERE` clause to specify multiple conditions, including time ranges. -{{% /note %}} - -## Examples - -Note that single quotes are required for string literals in the `WHERE` clause. - -### Filter data based on field values - -```sql -SELECT * -FROM "h2o_feet" -WHERE "water_level" >= 9.78 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns data from the `h2o_feet` measurement with `water_level` field values -that are greater than or equal to 9.78. - -| level description | location | time | water_level | -| :------------------------ | :----------- | :----------------------- | :---------- | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:06:00.000Z | 9.8 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:12:00.000Z | 9.829 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:18:00.000Z | 9.862 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:24:00.000Z | 9.892 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:30:00.000Z | 9.902 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:36:00.000Z | 9.898 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Filter data based on specific tag and field values - -```sql -SELECT * -FROM "h2o_feet" -WHERE "location" = 'santa_monica' and "level description" = 'below 3 feet' -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns all data from the `h2o_feet` measurement with the `location` tag key, `santa_monica`, -and a `level description` field value that equals `below 3 feet`. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | santa_monica | 2019-09-01T00:00:00.000Z | 1.529 | -| below 3 feet | santa_monica | 2019-09-01T00:06:00.000Z | 1.444 | -| below 3 feet | santa_monica | 2019-09-01T00:12:00.000Z | 1.335 | -| below 3 feet | santa_monica | 2019-09-01T00:18:00.000Z | 1.345 | -| below 3 feet | santa_monica | 2019-09-01T00:24:00.000Z | 1.27 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Filter data within a specific time period - -```sql -SELECT * -FROM h2o_feet -WHERE "location" = 'santa_monica' -AND "time" >= '2019-08-19T12:00:00Z'::timestamp AND "time" <= '2019-08-19T13:00:00Z'::timestamp -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns results with timestamps greater than or equal to `08-19-2019T12:00:00Z` and -less than or equal to `08-19-2019T13:00:00Z`. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | santa_monica | 2019-08-19T12:00:00.000Z | 2.533 | -| below 3 feet | santa_monica | 2019-08-19T12:06:00.000Z | 2.543 | -| below 3 feet | santa_monica | 2019-08-19T12:12:00.000Z | 2.385 | -| below 3 feet | santa_monica | 2019-08-19T12:18:00.000Z | 2.362 | -| below 3 feet | santa_monica | 2019-08-19T12:24:00.000Z | 2.405 | -| below 3 feet | santa_monica | 2019-08-19T12:30:00.000Z | 2.398 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Filter data using the OR operator - -```sql -SELECT * -FROM "h2o_feet" -WHERE "level description" = 'less than 3 feet' OR "water_level" < 2.5 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns results with a `level description` field value equal to `less than 3 feet` or a `water_level` field value less than 2.5. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | coyote_creek | 2019-08-25T10:06:00.000Z | 2.398 | -| below 3 feet | coyote_creek | 2019-08-25T10:12:00.000Z | 2.234 | -| below 3 feet | coyote_creek | 2019-08-25T10:18:00.000Z | 2.064 | -| below 3 feet | coyote_creek | 2019-08-25T10:24:00.000Z | 1.893 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/cloud-serverless/write-data/line-protocol/client-libraries.md b/content/influxdb/cloud-serverless/write-data/line-protocol/client-libraries.md index b7dd608a9..3b7e82f84 100644 --- a/content/influxdb/cloud-serverless/write-data/line-protocol/client-libraries.md +++ b/content/influxdb/cloud-serverless/write-data/line-protocol/client-libraries.md @@ -120,7 +120,7 @@ The following steps set up a Go project using the which provides the InfluxDB `influxdb3` Go client library module. ```sh - go get github.com/InfluxCommunity/influxdb3-go + go get github.com/InfluxCommunity/influxdb3-go/v2 ``` @@ -229,7 +229,7 @@ points. "os" "fmt" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" "github.com/influxdata/line-protocol/v2/lineprotocol" ) diff --git a/content/influxdb/cloud-serverless/write-data/troubleshoot.md b/content/influxdb/cloud-serverless/write-data/troubleshoot.md index dd85c6a9b..2c7a3b7cd 100644 --- a/content/influxdb/cloud-serverless/write-data/troubleshoot.md +++ b/content/influxdb/cloud-serverless/write-data/troubleshoot.md @@ -31,12 +31,12 @@ Learn how to avoid unexpected results and recover from errors when writing to {{ 1. Validates the request. 2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](#review-http-status-codes). - 3. Ingests or rejects the entire batch and returns one of the following HTTP status codes: + 3. Ingests or rejects data from the batch and returns one of the following HTTP status codes: - - `204 No Content`: some or all of the data is ingested and queryable - - `400 Bad Request`: all data is rejected + - `204 No Content`: All of the data is ingested and queryable. + - `400 Bad Request`: Some or all of the data has been rejected. Data that has not been rejected is ingested and queryable. - If points are rejected, the `204` or `400` response body contains error details about [rejected points](#troubleshoot-rejected-points), up to 100 points. + The response body contains error details about [rejected points](#troubleshoot-rejected-points), up to 100 points. Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable. @@ -49,18 +49,16 @@ InfluxDB uses conventional HTTP status codes to indicate the success or failure The `message` property of the response body may contain additional details about the error. {{< product-name >}} returns one the following HTTP status codes for a write request: -| HTTP response code | Response body | Description | -| :-------------------------------| :--------------------------------------------------------------- | :------------- | -| `201 "Created"` | error details about rejected points, up to 100 points, `line` contains the first rejected line, `message` describes rejections | If some of the data is ingested and some of the data is rejected | -| `204 "No Content"` | no response body | If InfluxDB ingested all of the data in the batch | -| `400 "Bad request"` | `line` contains the first malformed line, `message` describes rejected points | If request data is malformed | -| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-serverless/admin/tokens/) doesn't have [permission](/influxdb/cloud-serverless/admin/tokens/create-token/) to write to the bucket. See [examples using credentials](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb) in write requests. | -| `404 "Not found"` | requested **resource type** (for example, "organization" or "bucket"), and **resource name** | If a requested resource (for example, organization or bucket) wasn't found | -| `413 “Request too large”` | cannot read data: points in batch is too large | If a request exceeds the maximum [global limit](/influxdb/cloud-serverless/admin/billing/limits/) | -| `422 "Unprocessable Entity"` | `message` contains details about the error | If the data isn't allowed (for example, falls outside of the bucket's retention period). -| `429 “Too many requests”` | | If the number of requests exceeds the [adjustable service quota](/influxdb/cloud-serverless/admin/billing/limits/#adjustable-service-quotas). The `Retry-After` header contains the number of seconds to wait before trying the write again. | If a request exceeds your plan's [adjustable service quotas](/influxdb/cloud-serverless/admin/billing/limits/#adjustable-service-quotas) -| `500 "Internal server error"` | | Default status for an error | -| `503 "Service unavailable"` | | If the server is temporarily unavailable to accept writes. The `Retry-After` header contains the number of seconds to wait before trying the write again. +| HTTP response code | Response body | Description | +| :-------------------------------| :--------------------------------------------------------------- | :------------- | +| `204 "No Content"` | no response body | If InfluxDB ingested all of the data in the batch | +| `400 "Bad request"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections | If some or all request data isn't allowed (for example, is malformed or falls outside of the bucket's retention period)--the response body indicates whether a partial write has occurred or if all data has been rejected | +| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-serverless/admin/tokens/) doesn't have [permission](/influxdb/cloud-serverless/admin/tokens/create-token/) to write to the bucket. See [examples using credentials](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb) in write requests. | +| `404 "Not found"` | requested **resource type** (for example, "organization" or "bucket"), and **resource name** | If a requested resource (for example, organization or bucket) wasn't found | +| `413 “Request too large”` | cannot read data: points in batch is too large | If a request exceeds the maximum [global limit](/influxdb/cloud-serverless/admin/billing/limits/) | +| `429 “Too many requests”` | | If the number of requests exceeds the [adjustable service quota](/influxdb/cloud-serverless/admin/billing/limits/#adjustable-service-quotas). The `Retry-After` header contains the number of seconds to wait before trying the write again. | If a request exceeds your plan's [adjustable service quotas](/influxdb/cloud-serverless/admin/billing/limits/#adjustable-service-quotas) +| `500 "Internal server error"` | | Default status for an error | +| `503 "Service unavailable"` | | If the server is temporarily unavailable to accept writes. The `Retry-After` header contains the number of seconds to wait before trying the write again. The `message` property of the response body may contain additional details about the error. If your data did not write to the bucket, see how to [troubleshoot rejected points](#troubleshoot-rejected-points). diff --git a/content/influxdb/cloud/admin/buckets/bucket-schema.md b/content/influxdb/cloud/admin/buckets/bucket-schema.md index 69da046c0..051652bda 100644 --- a/content/influxdb/cloud/admin/buckets/bucket-schema.md +++ b/content/influxdb/cloud/admin/buckets/bucket-schema.md @@ -72,7 +72,7 @@ Use the [**`influx` CLI**](/influxdb/cloud/reference/cli/influx/) or [**InfluxDB #### Create a bucket schema using the influx CLI - 1. Use your text editor to create a schema columns file for each measurement you want to add. Format the file as CSV, JSON, or [Newline delimited JSON (NDJSON)](http://ndjson.org/), + 1. Use your text editor to create a schema columns file for each measurement you want to add. Format the file as CSV, JSON, or [Newline delimited JSON (NDJSON)](https://jsonlines.org/), as in the following examples: {{< code-tabs-wrapper >}} {{% code-tabs %}} diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/_index.md b/content/influxdb/cloud/api-guide/influxdb-1x/_index.md similarity index 82% rename from content/influxdb/cloud/reference/api/influxdb-1x/_index.md rename to content/influxdb/cloud/api-guide/influxdb-1x/_index.md index 1bddf757f..cdc3b5ea4 100644 --- a/content/influxdb/cloud/reference/api/influxdb-1x/_index.md +++ b/content/influxdb/cloud/api-guide/influxdb-1x/_index.md @@ -6,11 +6,13 @@ description: > menu: influxdb_cloud: name: v1 compatibility - parent: InfluxDB v2 API + parent: Develop with the API weight: 104 influxdb/cloud/tags: [influxql, query, write] related: - /influxdb/cloud/query-data/influxql +aliases: + - /influxdb/cloud/reference/api/influxdb-1x/ --- {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/dbrp.md b/content/influxdb/cloud/api-guide/influxdb-1x/dbrp.md similarity index 90% rename from content/influxdb/cloud/reference/api/influxdb-1x/dbrp.md rename to content/influxdb/cloud/api-guide/influxdb-1x/dbrp.md index ccc97e8a9..4c4645107 100644 --- a/content/influxdb/cloud/reference/api/influxdb-1x/dbrp.md +++ b/content/influxdb/cloud/api-guide/influxdb-1x/dbrp.md @@ -13,6 +13,8 @@ related: - /influxdb/cloud/reference/api/influxdb-1x/write - /influxdb/cloud/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint - /influxdb/cloud/query-data/influxql/ +aliases: + - /influxdb/cloud/reference/api/influxdb-1x/dbrp/ --- {{% duplicate-oss %}} diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/query.md b/content/influxdb/cloud/api-guide/influxdb-1x/query.md similarity index 88% rename from content/influxdb/cloud/reference/api/influxdb-1x/query.md rename to content/influxdb/cloud/api-guide/influxdb-1x/query.md index 29c903873..284c74072 100644 --- a/content/influxdb/cloud/reference/api/influxdb-1x/query.md +++ b/content/influxdb/cloud/api-guide/influxdb-1x/query.md @@ -15,6 +15,8 @@ list_code_example: | related: - /influxdb/cloud/query-data/influxql +aliases: + - /influxdb/cloud/reference/api/influxdb-1x/query/ --- {{% duplicate-oss %}} diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/write.md b/content/influxdb/cloud/api-guide/influxdb-1x/write.md similarity index 89% rename from content/influxdb/cloud/reference/api/influxdb-1x/write.md rename to content/influxdb/cloud/api-guide/influxdb-1x/write.md index c4fd2157b..871b51017 100644 --- a/content/influxdb/cloud/reference/api/influxdb-1x/write.md +++ b/content/influxdb/cloud/api-guide/influxdb-1x/write.md @@ -16,6 +16,8 @@ list_code_example: | related: - /influxdb/cloud/reference/syntax/line-protocol +aliases: + - /influxdb/cloud/reference/api/influxdb-1x/write/ --- {{% duplicate-oss %}} diff --git a/content/influxdb/cloud/query-data/influxql/functions/transformations.md b/content/influxdb/cloud/query-data/influxql/functions/transformations.md index 28f9d5fae..979ecfc59 100644 --- a/content/influxdb/cloud/query-data/influxql/functions/transformations.md +++ b/content/influxdb/cloud/query-data/influxql/functions/transformations.md @@ -1,6 +1,6 @@ --- title: InfluxQL transformation functions -list_title: Tranfsormation functions +list_title: Transformation functions description: > Use transformation functions modify and return values each row of queried data. menu: diff --git a/content/influxdb/cloud/reference/api/_index.md b/content/influxdb/cloud/reference/api/_index.md index e57a80f1b..5d876bcf4 100644 --- a/content/influxdb/cloud/reference/api/_index.md +++ b/content/influxdb/cloud/reference/api/_index.md @@ -1,11 +1,13 @@ --- -title: InfluxDB v2 API +title: InfluxDB HTTP API description: > - The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. + The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB, such as writing and querying data, + and managing resources within an InfluxDB instance. Access the InfluxDB API using the `/api/v2/` endpoint. menu: influxdb_cloud: parent: Reference + name: InfluxDB HTTP API weight: 3 influxdb/cloud/tags: [api] --- diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/_index.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/_index.md index 52b1eebef..9896b4d02 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/_index.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/_index.md @@ -10,10 +10,11 @@ weight: 101 influxdb/cloud/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). -{{% /cloud %}} +> [!IMPORTANT] +> +> #### Not supported in InfluxDB Cloud +> +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/create.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/create.md index f8ed70c81..3b24b4b59 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/create.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/create.md @@ -11,13 +11,12 @@ influxdb/cloud/tags: [authorization] updated_in: CLI v2.0.3 --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud Serverless - -**{{< product-name >}}** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth create` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use -[InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). -{{% /cloud %}} +> [!Important] +> #### Not supported in InfluxDB Cloud Serverless +> +> **{{< product-name >}}** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth create` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use +> [InfluxDB token authentication](/influxdb/cloud-serverless/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/delete.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/delete.md index dd63a9dd4..706659be8 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/delete.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/delete.md @@ -10,11 +10,11 @@ weight: 101 influxdb/cloud/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth delete` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth delete` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/list.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/list.md index 373aad88d..c986596af 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/list.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/list.md @@ -10,11 +10,11 @@ weight: 101 influxdb/cloud/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth list` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth list` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/set-active.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/set-active.md index de41d8b51..9ff704995 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/set-active.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/set-active.md @@ -10,11 +10,11 @@ weight: 101 influxdb/cloud/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth set-active` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth set-active` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/set-inactive.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/set-inactive.md index 357e54a98..3b8e8779e 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/set-inactive.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/set-inactive.md @@ -10,11 +10,11 @@ weight: 101 influxdb/cloud/tags: [authorization] --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth set-inactive` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth set-inactive` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/v1/auth/set-password.md b/content/influxdb/cloud/reference/cli/influx/v1/auth/set-password.md index 318a78b4f..cbe7d63be 100644 --- a/content/influxdb/cloud/reference/cli/influx/v1/auth/set-password.md +++ b/content/influxdb/cloud/reference/cli/influx/v1/auth/set-password.md @@ -11,11 +11,11 @@ influxdb/cloud/tags: [authorization] updated_in: CLI v2.0.3 --- -{{% cloud %}} -#### Not supported in InfluxDB Cloud -**InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. -Using the `influx v1 auth set-password` command with InfluxDB Cloud will result in an error. -To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). -{{% /cloud %}} +> [!Important] +> +> #### Not supported in InfluxDB Cloud +> **InfluxDB Cloud** does not support InfluxDB 1.x compatible authorizations. +> Using the `influx v1 auth set-password` command with InfluxDB Cloud will result in an error. +> To authenticate with InfluxDB Cloud, use [InfluxDB token authentication](/influxdb/cloud/admin/tokens/). {{< duplicate-oss >}} diff --git a/content/influxdb/cloud/sign-up.md b/content/influxdb/cloud/sign-up.md index d8156f0c3..cf556736e 100644 --- a/content/influxdb/cloud/sign-up.md +++ b/content/influxdb/cloud/sign-up.md @@ -12,11 +12,18 @@ aliases: - /influxdb/v2/cloud/get-started/ --- -InfluxDB Cloud is a fully managed and hosted version of InfluxDB 2.0, the time series -platform purpose-built to collect, store, process and visualize metrics and events. +InfluxDB Cloud is a fully managed and hosted version of InfluxDB, designed to collect, store, process, and visualize metrics and events. -{{< product-name >}} is API-compatible and functionally compatible with InfluxDB OSS 2.0. -The primary differences between InfluxDB OSS 2.0 and InfluxDB Cloud are: + > [!Note] + > #### New InfluxDB Cloud signups use InfluxDB 3 + > + > New InfluxDB Cloud signups are for [InfluxDB Cloud Serverless, powered by the InfluxDB 3 storage engine](/influxdata/cloud-serverless/). + > + > If you are looking to use InfluxDB v2 (TSM), consider self-hosting [InfluxDB OSS v2](/influxdata/v2/). + +{{< product-name >}} is API-compatible and functionally compatible with InfluxDB OSS v2. + +The primary differences between InfluxDB OSS v2 and InfluxDB Cloud are: - [InfluxDB scrapers](/influxdb/v2/write-data/no-code/scrape-data/) that collect data from specified targets are not available in {{< product-name "short" >}}. @@ -28,73 +35,20 @@ The primary differences between InfluxDB OSS 2.0 and InfluxDB Cloud are: - [Sign in](#sign-in) - [Get started working with data](#get-started-working-with-data) -## Start for free +### Other deployment options -Start using {{< product-name >}} at no cost with the [Free Plan](/influxdb/cloud/account-management/pricing-plans/#free-plan). -Use it as much and as long as you like within the plan's rate-limits. -[Limits](/influxdb/cloud/account-management/limits/) are designed to let you monitor 5-10 sensors, stacks or servers comfortably. - -{{% note %}} -Users on the Free Plan are limited to one organization. -{{% /note %}} +- **InfluxDB OSS v2 (single-node, self-hosted)**: Available for on-premises setups. +- **InfluxDB Cloud Serverless**: Managed, multi-tenant InfluxDB Cloud 3 instance. +- **InfluxDB Cloud Dedicated**: Managed, single-tenant InfluxDB Cloud 3 cluster. ## Sign up -1. Choose one of the following: - - #### Subscribe through InfluxData - - To subscribe to an InfluxDB Cloud **Free Plan** through InfluxData, - go to [InfluxDB Cloud](https://cloud2.influxdata.com/). - - - To use social sign-on, click **Google** or **Microsoft**. Note that social sign-on does not support email aliases. - - Sign up with email by entering your name, email address, and password, then click **Create Account**. - - If you originally signed up with email but want to enable social sign-on, you can do so by logging in through your cloud provider as long as you use the same email address. - - #### **Subscribe through a cloud provider** - To subscribe to an InfluxDB Cloud **Usage-Based** plan and pay through your - **Amazon Web Services (AWS)**, **Microsoft Azure**, or **Google Cloud Platform (GCP)** account: - - - **AWS** - Sign in to AWS, navigate to the [InfluxDB Cloud product on AWS Marketplace](https://aws.amazon.com/marketplace/pp/B08234JZPS/?href=_ptnr_web_docs_gettingstarted), - and follow the prompts to subscribe. After you click **Set Up Your Account**, - enter your credentials, and then click **Start Now**. - All usage charges will be paid through the subscribed AWS account. - - - **Microsoft** - Sign in to Microsoft Azure, navigate to the [InfluxDB Cloud product on Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/influxdata.influxdb-cloud?ocid=iflxdbcloud_influxdata_docs_gettingstarted), - and follow the prompts to subscribe. After you click **Set Up Your Account**, - enter your credentials, and then click **Start Now**. - All usage charges will be paid through the subscribed Microsoft account. - - - **GCP** - Sign in to GCP, navigate to the [InfluxDB Cloud product on GCP Marketplace](https://console.cloud.google.com/marketplace/details/influxdata-public/cloud2-gcp-marketplace-prod?utm_campaign=influxdb-cloud&utm_medium=docs&utm_source=influxdata), - and follow the prompts to subscribe. After you click **Set Up Your Account**, - enter your credentials, and then click **Start Now**. - All usage charges will be paid through the subscribed GCP account. - - {{%note%}} -Currently, we do **not support** using an existing InfluxDB Cloud account to sign up for an InfluxDB Cloud plan through AWS, Microsoft, or GCP Marketplaces. - {{%/note%}} - -2. If you signed up with your email address, InfluxDB Cloud requires email verification to complete the sign up process. - Verify your email address by opening the email sent to the address you provided and clicking **Verify Your Email**. -3. (If you subscribed through InfluxData) Choose your cloud provider. -4. Select a provider and region for your {{< product-name >}} instance. The following are available: - - {{< cloud_regions type="list" >}} - - _To suggest regions to add, click **Let us know** under Regions._ -5. Enter your company name. -6. (If you subscribed through InfluxData) Review the terms of the agreement, and then select **I have viewed and agree to InfluxDB Cloud Services Subscription Agreement and InfluxData Global Data Processing Agreement**. - For details on the agreements, see the [InfluxDB Cloud: Services Subscription Agreement](https://www.influxdata.com/legal/terms-of-use/) and the [InfluxData Global Data Processing Agreement](https://www.influxdata.com/legal/influxdata-global-data-processing-agreement/). - -7. Click **Continue**, and then choose your plan: - - To upgrade to a Usage-Based plan, click **Upgrade Now**, set your limits (you may opt to receive an email when your usage exceeds the amount you enter in the **Limit ($1 minimum)** field). Next, enter your payment information and billing address, and then click **Upgrade**. A Ready To Rock confirmation appears; click **Start building your team**. Your plan will be upgraded and {{< product-name >}} opens with a default organization and bucket (both created from your email address). To review your usage and billing details at any time, see how to [access billing details](/influxdb/cloud/account-management/billing/#access-billing-details). - - To keep the free plan, click **Keep**. {{< product-name >}} opens with a default organization and bucket (both created from your email address). _To update organization and bucket names, see [Update an organization](/influxdb/cloud/admin/organizations/update-org/) - and [Update a bucket](/influxdb/cloud/admin/buckets/update-bucket/#update-a-buckets-name-in-the-influxdb-ui)._ - - To upgrade to an Annual plan, click **Contact Sales**, enter your information, and then click **Send**. Our team will contact you as soon as possible. + > [!Note] + > #### New InfluxDB Cloud signups use InfluxDB 3 + > + > New InfluxDB Cloud signups are for [InfluxDB Cloud Serverless, powered by the InfluxDB 3 storage engine](/influxdata/cloud-serverless/). + > + > If you are looking to use InfluxDB v2 (TSM), consider self-hosting [InfluxDB OSS v2](/influxdata/v2/). ## (Optional) Download, install, and use the influx CLI diff --git a/content/influxdb/cloud/write-data/bulk-ingest-cloud.md b/content/influxdb/cloud/write-data/bulk-ingest-cloud.md index a3743e7bc..7d71f099b 100644 --- a/content/influxdb/cloud/write-data/bulk-ingest-cloud.md +++ b/content/influxdb/cloud/write-data/bulk-ingest-cloud.md @@ -9,11 +9,11 @@ menu: influxdb_cloud: name: Bulk ingest historical data parent: Write data -alias: +aliases: - /influxdb/v2/write-data/bulk-ingest-cloud --- -To upload a large amount **(10GB or greater)** of previously existing *historical* +To upload a large amount **(10 GB or greater)** of previously existing *historical* data into InfluxDB Cloud, contact [InfluxData Support](https://support.influxdata.com/) for assistance. We’ll review your ingest rate limits, volume, and existing [data schema](/influxdb/cloud/reference/key-concepts/data-schema) to ensure the diff --git a/content/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-cloud.md b/content/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-cloud.md index a708f403d..3b773d6ee 100644 --- a/content/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-cloud.md +++ b/content/influxdb/cloud/write-data/migrate-data/migrate-cloud-to-cloud.md @@ -25,10 +25,9 @@ The following guide provides instructions for setting up an InfluxDB task that queries data from an InfluxDB Cloud bucket in time-based batches and writes each batch to another InfluxDB Cloud bucket in another organization. -{{% cloud %}} -All query and write requests are subject to your InfluxDB Cloud organization's -[rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). -{{% /cloud %}} +> [!Important] +> All query and write requests are subject to your InfluxDB Cloud organization's +> [rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - [Set up the migration](#set-up-the-migration) - [Migration task](#migration-task) diff --git a/content/influxdb/clustered/admin/bypass-identity-provider.md b/content/influxdb/clustered/admin/bypass-identity-provider.md index 7d5c7ec3a..fa7ea43f9 100644 --- a/content/influxdb/clustered/admin/bypass-identity-provider.md +++ b/content/influxdb/clustered/admin/bypass-identity-provider.md @@ -7,7 +7,7 @@ description: > menu: influxdb_clustered: parent: Administer InfluxDB Clustered -weight: 208 +weight: 209 --- {{< product-name >}} generates a valid access token (known as the _admin token_) @@ -63,13 +63,13 @@ The only way to revoke the token is to do the following: {{% code-placeholders "INFLUXDB_NAMESPACE|KEY_GEN_JOB|001" %}} -1. Delete the `rsa-keys` secret from your InfluxDB cluster's context and namespace: +1. Delete the `rsa-keys` and `admin-token` secrets from your InfluxDB cluster's context and namespace: ```sh - kubectl delete secrets/rsa-keys --namespace INFLUXDB_NAMESPACE + kubectl delete secret rsa-keys admin-token --namespace INFLUXDB_NAMESPACE ``` -2. Rerun the `key-gen` job: +2. Rerun the `key-gen` and `create-amin-token` jobs: 1. List the jobs in your InfluxDB namespace to find the key-gen job pod: @@ -78,12 +78,11 @@ The only way to revoke the token is to do the following: kubectl get jobs --namespace INFLUXDB_NAMESPACE ``` - 2. Run the key-gen job and increment the job number as needed: - + 2. Delete the key-gen and create-admin-token jobs so they it will be re-created by kubit: + ```sh - kubectl create job \ - --from=job/KEY_GEN_JOB key-gen-001 \ - --namespace INFLUXDB_NAMESPACE + kubectl delete job/KEY_GEN_JOB job/CREATE_ADMIN_TOKEN_JOB \ + --namespace INFLUXDB_NAMESPACE ``` 3. Restart the `token-management` service: @@ -102,8 +101,6 @@ In the examples above, replace the following: The name of your InfluxDB namespace. - {{% code-placeholder-key %}}`KEY_GEN_JOB`{{% /code-placeholder-key %}}: The name of the key-gen job pod. -- {{% code-placeholder-key %}}`001`{{% /code-placeholder-key %}}: - A unique number used to increment the key-gen job. {{% note %}} To create a new admin token after revoking the existing one, rerun the diff --git a/content/influxdb/clustered/admin/custom-partitions/_index.md b/content/influxdb/clustered/admin/custom-partitions/_index.md index 2a39ba30b..dcfc533fd 100644 --- a/content/influxdb/clustered/admin/custom-partitions/_index.md +++ b/content/influxdb/clustered/admin/custom-partitions/_index.md @@ -11,405 +11,9 @@ weight: 104 influxdb/clustered/tags: [storage] related: - /influxdb/clustered/reference/internals/storage-engine/ +source: /shared/v3-distributed-admin-custom-partitions/_index.md --- -When writing data to {{< product-name >}}, the InfluxDB v3 storage engine stores -data in the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store) -in [Apache Parquet](https://parquet.apache.org/) format. -Each Parquet file represents a _partition_--a logical grouping of data. -By default, InfluxDB partitions each table by day. -{{< product-name >}} lets you customize the partitioning strategy and partition -by tag values and different time intervals. -Customize your partitioning strategy to optimize query performance for your -specific schema and workload. - -- [Advantages](#advantages) -- [Disadvantages](#disadvantages) -- [Limitations](#limitations) -- [How partitioning works](#how-partitioning-works) - - [Partition templates](#partition-templates) - - [Partition keys](#partition-keys) -- [Partitions in the query life cycle](#partitions-in-the-query-life-cycle) -- [Partition guides](#partition-guides) - {{< children type="anchored-list" >}} - -## Advantages - -The primary advantage of custom partitioning is that it lets you customize your -storage structure to improve query performance specific to your schema and workload. - -- **Optimized storage for improved performance on specific types of queries**. - For example, if queries often select data with a specific tag value, you can - partition by that tag to improve the performance of those queries. -- **Optimized storage for specific types of data**. For example, if the data you - store is sparse and the time ranges you query are often much larger than a day, - you could partition your data by week instead of by day. - -## Disadvantages - -Using custom partitioning may increase the load on other parts of the -[InfluxDB v3 storage engine](/influxdb/clustered/reference/internals/storage-engine/), -but each can be scaled individually to address the added load. - -{{% note %}} -_The following disadvantages assume that your custom partitioning strategy includes -additional tags to partition by or partition intervals smaller than a day._ -{{% /note %}} - -- **Increased load on the [Ingester](/influxdb/clustered/reference/internals/storage-engine/#ingester)** - as it groups data into smaller partitions and files. -- **Increased load on the [Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog)** - as more references to partition Parquet file locations are stored and queried. -- **Increased load on the [Compactor](/influxdb/clustered/reference/internals/storage-engine/#compactor)** - as more partition Parquet files need to be compacted. -- **Increased costs associated with [Object storage](/influxdb/clustered/reference/internals/storage-engine/#object-storage)** - as more partition Parquet files are created and stored. -- **Risk of decreased performance for queries that don't use tags in the WHERE clause**. - These queries may end up reading many partitions and smaller files, degrading performance. - -## Limitations - -Custom partitioning has the following limitations: - -- Database and table partitions can only be defined on create. - You cannot update the partition strategy of a database or table after it has - been created. -- You can partition by up to eight dimensions (seven tags and a time interval). - -## How partitioning works - -### Partition templates - -A partition template defines the pattern used for _[partition keys](#partition-keys)_ -and determines the time interval that data is partitioned by. -Partition templates use tag values and -[Rust strftime date and time formatting syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). - -_For more detailed information, see [Partition templates](/influxdb/clustered/admin/custom-partitions/partition-templates/)._ - -### Partition keys - -A partition key uniquely identifies a partition. The structure of partition keys -is defined by a _[partition template](#partition-templates)_. Partition keys are -composed of up to eight parts or dimensions (tags, tag buckets, and time). -Each part is delimited by the partition key separator (`|`). - -{{< expand-wrapper >}} -{{% expand "View example partition templates and keys" %}} - -Given the following line protocol with the following timestamps: - -- 2023-12-31T23:00:00Z -- 2024-01-01T00:00:00Z -- 2024-01-01T01:00:00Z - -```text -production,line=A,station=cnc temp=81.2,qty=35i 1704063600000000000 -production,line=A,station=wld temp=92.8,qty=35i 1704063600000000000 -production,line=B,station=cnc temp=101.1,qty=43i 1704063600000000000 -production,line=B,station=wld temp=102.4,qty=43i 1704063600000000000 -production,line=A,station=cnc temp=81.9,qty=36i 1704067200000000000 -production,line=A,station=wld temp=110.0,qty=22i 1704067200000000000 -production,line=B,station=cnc temp=101.8,qty=44i 1704067200000000000 -production,line=B,station=wld temp=105.7,qty=44i 1704067200000000000 -production,line=A,station=cnc temp=82.2,qty=35i 1704070800000000000 -production,line=A,station=wld temp=92.1,qty=30i 1704070800000000000 -production,line=B,station=cnc temp=102.4,qty=43i 1704070800000000000 -production,line=B,station=wld temp=106.5,qty=43i 1704070800000000000 -``` - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `%Y-%m-%d` time (by day, default format) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `2023-12-31` -- `2024-01-01` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `%d %b %Y` time (by day, non-default format) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | 31 Dec 2023` -- `B | 31 Dec 2023` -- `A | 01 Jan 2024` -- `B | 01 Jan 2024` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `station` tag -- `%Y-%m-%d` time (by day, default format) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | cnc | 2023-12-31` -- `A | wld | 2023-12-31` -- `B | cnc | 2023-12-31` -- `B | wld | 2023-12-31` -- `A | cnc | 2024-01-01` -- `A | wld | 2024-01-01` -- `B | cnc | 2024-01-01` -- `B | wld | 2024-01-01` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `station,3` tag bucket -- `%Y-%m-%d` time (by day, default format) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | 0 | 2023-12-31` -- `B | 0 | 2023-12-31` -- `A | 0 | 2024-01-01` -- `B | 0 | 2024-01-01` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `station` tag -- `%Y-%m-%d %H:00` time (by hour) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | cnc | 2023-12-31 23:00` -- `A | wld | 2023-12-31 23:00` -- `B | cnc | 2023-12-31 23:00` -- `B | wld | 2023-12-31 23:00` -- `A | cnc | 2024-01-01 00:00` -- `A | wld | 2024-01-01 00:00` -- `B | cnc | 2024-01-01 00:00` -- `B | wld | 2024-01-01 00:00` -- `A | cnc | 2024-01-01 01:00` -- `A | wld | 2024-01-01 01:00` -- `B | cnc | 2024-01-01 01:00` -- `B | wld | 2024-01-01 01:00` - -{{% /flex-content %}} - - - -{{% /flex %}} - ---- - -{{% flex %}} - - - -{{% flex-content "half" %}} - -##### Partition template parts - -- `line` tag -- `station,50` tag bucket -- `%Y-%m-%d %H:00` time (by hour) - -{{% /flex-content %}} -{{% flex-content %}} - -##### Partition keys - -- `A | 47 | 2023-12-31 23:00` -- `A | 9 | 2023-12-31 23:00` -- `B | 47 | 2023-12-31 23:00` -- `B | 9 | 2023-12-31 23:00` -- `A | 47 | 2024-01-01 00:00` -- `A | 9 | 2024-01-01 00:00` -- `B | 47 | 2024-01-01 00:00` -- `B | 9 | 2024-01-01 00:00` -- `A | 47 | 2024-01-01 01:00` -- `A | 9 | 2024-01-01 01:00` -- `B | 47 | 2024-01-01 01:00` -- `B | 9 | 2024-01-01 01:00` - -{{% /flex-content %}} - - - -{{% /flex %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Partitions in the query life cycle - -When querying data: - -1. The [Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog) - provides the v3 query engine ([Querier](/influxdb/clustered/reference/internals/storage-engine/#querier)) - with the locations of partitions that contain the queried time series data. -2. The query engine reads all rows in the returned partitions to identify what - rows match the logic in the query and should be included in the query result. - -The faster the query engine can identify what partitions to read and then read -the data in those partitions, the more performant queries are. - -_For more information about the query lifecycle, see -[InfluxDB v3 query life cycle](/influxdb/clustered/reference/internals/storage-engine/#query-life-cycle)._ - -##### Query example - -Consider the following query that selects everything in the `production` table -where the `line` tag is `A` and the `station` tag is `1`: - -```sql -SELECT * -FROM production -WHERE - time >= now() - INTERVAL '1 week' - AND line = 'A' - AND station = 'cnc' -``` - -Using the default partitioning strategy (by day), the query engine -reads eight separate partitions (one partition for today and one for each of the -last seven days): - -- {{< datetime/current-date trimTime=true >}} -- {{< datetime/current-date offset=-1 trimTime=true >}} -- {{< datetime/current-date offset=-2 trimTime=true >}} -- {{< datetime/current-date offset=-3 trimTime=true >}} -- {{< datetime/current-date offset=-4 trimTime=true >}} -- {{< datetime/current-date offset=-5 trimTime=true >}} -- {{< datetime/current-date offset=-6 trimTime=true >}} -- {{< datetime/current-date offset=-7 trimTime=true >}} - -The query engine must scan _all_ rows in the partitions to identify rows -where `line` is `A` and `station` is `cnc`. This process takes valuable time -and results in less performant queries. - -However, if you partition by other tags, InfluxDB can identify partitions that -contain only the tag values your query needs and spend less time -scanning rows to see if they contain the tag values. - -For example, if data is partitioned by `line`, `station`, and day, although -there are more partition files, the query engine can quickly identify and read -only those with data relevant to the query: - -{{% columns 4 %}} - -- A | cnc | {{< datetime/current-date trimTime=true >}} -- A | wld | {{< datetime/current-date trimTime=true >}} -- B | cnc | {{< datetime/current-date trimTime=true >}} -- B | wld | {{< datetime/current-date trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-1 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-1 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-1 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-1 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-2 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-2 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-2 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-2 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-3 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-3 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-3 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-3 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-4 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-4 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-4 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-4 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-5 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-5 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-5 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-5 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-6 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-6 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-6 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-6 trimTime=true >}} -- A | cnc | {{< datetime/current-date offset=-7 trimTime=true >}} -- A | wld | {{< datetime/current-date offset=-7 trimTime=true >}} -- B | cnc | {{< datetime/current-date offset=-7 trimTime=true >}} -- B | wld | {{< datetime/current-date offset=-7 trimTime=true >}} - -{{% /columns %}} - ---- - -## Partition guides - -{{< children >}} + diff --git a/content/influxdb/clustered/admin/custom-partitions/best-practices.md b/content/influxdb/clustered/admin/custom-partitions/best-practices.md index 8429eaaa5..dcbb11b08 100644 --- a/content/influxdb/clustered/admin/custom-partitions/best-practices.md +++ b/content/influxdb/clustered/admin/custom-partitions/best-practices.md @@ -8,52 +8,9 @@ menu: name: Best practices parent: Manage data partitioning weight: 202 +source: /shared/v3-distributed-admin-custom-partitions/best-practices.md --- -Use the following best practices when defining custom partitioning strategies -for your data stored in {{< product-name >}}. - -- [Partition by tags that you commonly query for a specific value](#partition-by-tags-that-you-commonly-query-for-a-specific-value) -- [Only partition by tags that _always_ have a value](#only-partition-by-tags-that-always-have-a-value) -- [Avoid over-partitioning](#avoid-over-partitioning) - -## Partition by tags that you commonly query for a specific value - -Custom partitioning primarily benefits queries that look for a specific tag -value in the `WHERE` clause. For example, if you often query data related to a -specific ID, partitioning by the tag that stores the ID helps the InfluxDB -query engine to more quickly identify what partitions contain the relevant data. - -{{% note %}} - -#### Use tag buckets for high-cardinality tags - -Partitioning using distinct values of tags with many (10K+) unique values can -actually hurt query performance as partitions are created for each unique tag value. -Instead, use [tag buckets](/influxdb/clustered/admin/custom-partitions/partition-templates/#tag-bucket-part-templates) -to partition by high-cardinality tags. -This method of partitioning groups tag values into "buckets" and partitions by bucket. -{{% /note %}} - -## Only partition by tags that _always_ have a value - -You should only partition by tags that _always_ have a value. -If points don't have a value for the tag, InfluxDB can't store them in the correct partitions and, at query time, must read all the partitions. - -## Avoid over-partitioning - -As you plan your partitioning strategy, keep in mind that data can be -"over-partitioned"--meaning partitions are so granular that queries end up -having to retrieve and read many partitions from the object store, which -hurts query performance. - -- Avoid using partition time intervals that are **less than one day**. - - The partition time interval should be balanced with the actual amount of data - written during each interval. If a single interval doesn't contain a lot of data, - it is better to partition by larger time intervals. - -- Don't partition by tags that you typically don't use in your query workload. -- Don't partition by distinct values of high-cardinality tags. - Instead, [use tag buckets](#use-tag-buckets-for-high-cardinality-tags) to - partition by these tags. + diff --git a/content/influxdb/clustered/admin/custom-partitions/define-custom-partitions.md b/content/influxdb/clustered/admin/custom-partitions/define-custom-partitions.md index ffd7d61c0..be9c94f0b 100644 --- a/content/influxdb/clustered/admin/custom-partitions/define-custom-partitions.md +++ b/content/influxdb/clustered/admin/custom-partitions/define-custom-partitions.md @@ -10,162 +10,9 @@ weight: 202 related: - /influxdb/clustered/reference/cli/influxctl/database/create/ - /influxdb/clustered/reference/cli/influxctl/table/create/ +source: /shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md --- -Use the [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/) -to define custom partition strategies when creating a database or table. -By default, {{< product-name >}} partitions data by day. - -The partitioning strategy of a database or table is determined by a -[partition template](/influxdb/clustered/admin/custom-partitions/#partition-templates) -which defines the naming pattern for [partition keys](/influxdb/clustered/admin/custom-partitions/#partition-keys). -Partition keys uniquely identify each partition. -When a partition template is applied to a database, it becomes the default template -for all tables in that database, but can be overridden when creating a -table. - -- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template) -- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template) -- [Example partition templates](#example-partition-templates) - -{{% note %}} - -#### Partition templates can only be applied on create - -You can only apply a partition template when creating a database or table. -You can't update a partition template on an existing resource. -{{% /note %}} - -Use the following command flags to identify -[partition template parts](/influxdb/clustered/admin/custom-partitions/partition-templates/#tag-part-templates): - -- `--template-tag`: An [InfluxDB tag](/influxdb/clustered/reference/glossary/#tag) - to use in the partition template. -- `--template-tag-bucket`: An [InfluxDB tag](/influxdb/clustered/reference/glossary/#tag) - and number of "buckets" to group tag values into. - Provide the tag key and the number of buckets to bucket tag values into - separated by a comma: `tagKey,N`. -- `--template-timeformat`: A [Rust strftime date and time](/influxdb/clustered/admin/custom-partitions/partition-templates/#time-part-templates) - string that specifies the time format in the partition template and determines - the time interval to partition by. - -{{% note %}} -A partition template can include up to 7 total tag and tag bucket parts -and only 1 time part. -{{% /note %}} - -_View [partition template part restrictions](/influxdb/clustered/admin/custom-partitions/partition-templates/#restrictions)._ - -{{% note %}} -#### Always provide a time format when using custom partitioning - -When defining a custom partition template for your database or table using any -of the `influxctl` `--template-*` flags, always include the `--template-timeformat` -flag with a time format to use in your partition template. -Otherwise, InfluxDB omits time from the partition template and won't compact partitions. -{{% /note %}} - -## Create a database with a custom partition template - -The following example creates a new `example-db` database and applies a partition -template that partitions by distinct values of two tags (`room` and `sensor-type`), -bucketed values of the `customerID` tag, and by week using the time format `%Y wk:%W`: - - - - -```sh -influxctl database create \ - --template-tag room \ - --template-tag sensor-type \ - --template-tag-bucket customerID,500 \ - --template-timeformat '%Y wk:%W' \ - example-db -``` - -## Create a table with a custom partition template - -The following example creates a new `example-table` table in the specified -database and applies a partition template that partitions by distinct values of -two tags (`room` and `sensor-type`), bucketed values of the `customerID` tag, -and by month using the time format `%Y-%m`: - - - - -{{% code-placeholders "DATABASE_NAME" %}} - -```sh -influxctl table create \ - --template-tag room \ - --template-tag sensor-type \ - --template-tag-bucket customerID,500 \ - --template-timeformat '%Y-%m' \ - DATABASE_NAME \ - example-table -``` - -{{% /code-placeholders %}} - -Replace the following in your command: - -- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb/clustered/admin/databases/) - - - -## Example partition templates - -Given the following [line protocol](/influxdb/clustered/reference/syntax/line-protocol/) -with a `2024-01-01T00:00:00Z` timestamp: - -```text -prod,line=A,station=weld1 temp=81.9,qty=36i 1704067200000000000 -``` - -##### Partitioning by distinct tag values - -| Description | Tag parts | Time part | Resulting partition key | -| :---------------------- | :---------------- | :--------- | :----------------------- | -| By day (default) | | `%Y-%m-%d` | 2024-01-01 | -| By day (non-default) | | `%d %b %Y` | 01 Jan 2024 | -| By week | | `%Y wk:%W` | 2024 wk:01 | -| By month | | `%Y-%m` | 2024-01 | -| Single tag, by day | `line` | `%F` | A \| 2024-01-01 | -| Single tag, by week | `line` | `%Y wk:%W` | A \| 2024 wk:01 | -| Single tag, by month | `line` | `%Y-%m` | A \| 2024-01 | -| Multiple tags, by day | `line`, `station` | `%F` | A \| weld1 \| 2024-01-01 | -| Multiple tags, by week | `line`, `station` | `%Y wk:%W` | A \| weld1 \| 2024 wk:01 | -| Multiple tags, by month | `line`, `station` | `%Y-%m` | A \| weld1 \| 2024-01 | - -##### Partition by tag buckets - -| Description | Tag part | Tag bucket part | Time part | Resulting partition key | -| :--------------------------------- | :------- | :-------------- | :--------- | :---------------------- | -| Distinct tag, tag buckets, by day | `line` | `station,100` | `%F` | A \| 3 \| 2024-01-01 | -| Distinct tag, tag buckets, by week | `line` | `station,500` | `%Y wk:%W` | A \| 303 \| 2024 wk:01 | diff --git a/content/influxdb/clustered/admin/custom-partitions/partition-templates.md b/content/influxdb/clustered/admin/custom-partitions/partition-templates.md index 8d0b6daae..b3b418a14 100644 --- a/content/influxdb/clustered/admin/custom-partitions/partition-templates.md +++ b/content/influxdb/clustered/admin/custom-partitions/partition-templates.md @@ -8,276 +8,9 @@ menu: influxdb_clustered: parent: Manage data partitioning weight: 202 +source: /shared/v3-distributed-admin-custom-partitions/partition-templates.md --- -Use partition templates to define the patterns used to generate partition keys. -A partition key uniquely identifies a partition and is used to name the partition -Parquet file in the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store). - -A partition template consists of 1-8 _template parts_---dimensions to partition data by. -There are three types of template parts: - -- **tag**: An [InfluxDB tag](/influxdb/clustered/reference/glossary/#tag) - to partition by. -- **tag bucket**: An [InfluxDB tag](/influxdb/clustered/reference/glossary/#tag) - and number of "buckets" to group tag values into. Data is partitioned by the - tag bucket rather than each distinct tag value. -- **time**: A Rust strftime date and time string that specifies the time interval - to partition data by. The smallest unit of time included in the time part - template is the interval used to partition data. - -{{% note %}} -A partition template can include up to 7 total tag and tag bucket parts -and only 1 time part. -{{% /note %}} - - -- [Restrictions](#restrictions) - - [Template part size limit](#template-part-size-limit) - - [Reserved keywords](#reserved-keywords) - - [Reserved Characters](#reserved-characters) -- [Tag part templates](#tag-part-templates) -- [Tag bucket part templates](#tag-bucket-part-templates) -- [Time part templates](#time-part-templates) - - [Date specifiers](#date-specifiers) - - [Time specifiers](#time-specifiers) - - [Time zone specifiers](#time-zone-specifiers) - - [Date and time specifiers](#date-and-time-specifiers) - - [Special specifiers](#special-specifiers) - - -## Restrictions - -### Template part size limit - -Each template part is limited to 200 bytes in length. -Anything longer will be truncated at 200 bytes and appended with `#`. - -### Partition key size limit - -With the truncation of template parts, the maximum length of a partition key is -1,607 bytes (1.57 KiB). - -### Reserved keywords - -The following reserved keywords cannot be used in partition templates: - -- `time` - -### Reserved Characters - -If used in template parts, non-ASCII characters and the following reserved -characters must be [percent encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding): - -- `|`: Partition key part delimiter -- `!`: Null or missing partition key part -- `^`: Empty string partition key part -- `#`: Key part truncation marker -- `%`: Required for unambiguous reversal of percent encoding - -## Tag part templates - -Tag part templates consist of a _tag key_ to partition by. -Generated partition keys include the unique _tag value_ specific to each partition. - -## Tag bucket part templates - -Tag bucket part templates consist of a _tag key_ to partition by and the -_number of "buckets" to partition tag values into_--for example: - -``` -customerID,500 -``` - -Values of the `customerID` tag are bucketed into 500 distinct "buckets." -Each bucket is identified by the remainder of the tag value hashed into a 32bit -integer divided by the specified number of buckets: - -```rust -hash(tagValue) % N -``` - -Generated partition keys include the unique _tag bucket identifier_ specific to -each partition. - -**Supported number of tag buckets**: 1-1,000 - -{{% note %}} -Tag buckets should be used to partition by high cardinality tags or tags with an -unknown number of distinct values. -{{% /note %}} - -## Time part templates - -Time part templates use [Rust strftime date and time formatting syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) -to specify time format in partition keys. -The smallest unit of time included in the time part template is the interval -used to partition data. - -{{% warn %}} -#### Avoid partitioning by less than one day - -We do not recommend using time intervals less than one day to partition data. -This can result in [over-partitioned data](/influxdb/clustered/admin/custom-partitions/best-practices/#avoid-over-partitioning) -and may hurt query performance. -{{% /warn %}} - -- [Date specifiers](#date-specifiers) -- [Time specifiers](#time-specifiers) -- [Time zone specifiers](#time-zone-specifiers) -- [Date and time specifiers](#date-and-time-specifiers) -- [Special specifiers](#special-specifiers) - -{{% note %}} -The following is adapted from the -[Rust strftime source code](https://docs.rs/chrono/latest/src/chrono/format/strftime.rs.html). -{{% /note %}} - -### Date specifiers - -| Variable | Example | Description | -| :------: | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `%Y` | `2001` | The full proleptic Gregorian year, zero-padded to 4 digits. chrono supports years from -262144 to 262143. Note: years before 1 BCE or after 9999 CE, require an initial sign (+/-). | -| `%C` | `20` | The proleptic Gregorian year divided by 100, zero-padded to 2 digits. [^1] | -| `%y` | `01` | The proleptic Gregorian year modulo 100, zero-padded to 2 digits. [^1] | -| `%m` | `07` | Month number (01--12), zero-padded to 2 digits. | -| `%b` | `Jul` | Abbreviated month name. Always 3 letters. | -| `%B` | `July` | Full month name. Also accepts corresponding abbreviation in parsing. | -| `%h` | `Jul` | Same as `%b`. | -| `%d` | `08` | Day number (01--31), zero-padded to 2 digits. | -| `%e` | ` 8` | Same as `%d` but space-padded. Same as `%_d`. | -| `%a` | `Sun` | Abbreviated weekday name. Always 3 letters. | -| `%A` | `Sunday` | Full weekday name. Also accepts corresponding abbreviation in parsing. | -| `%w` | `0` | Sunday = 0, Monday = 1, ..., Saturday = 6. | -| `%u` | `7` | Monday = 1, Tuesday = 2, ..., Sunday = 7. (ISO 8601) | -| `%U` | `28` | Week number starting with Sunday (00--53), zero-padded to 2 digits. [^2] | -| `%W` | `27` | Same as `%U`, but week 1 starts with the first Monday in that year instead. | -| `%G` | `2001` | Same as `%Y` but uses the year number in ISO 8601 week date. [^3] | -| `%g` | `01` | Same as `%y` but uses the year number in ISO 8601 week date. [^3] | -| `%V` | `27` | Same as `%U` but uses the week number in ISO 8601 week date (01--53). [^3] | -| `%j` | `189` | Day of the year (001--366), zero-padded to 3 digits. | -| `%D` | `07/08/01` | Month-day-year format. Same as `%m/%d/%y`. | -| `%x` | `07/08/01` | Locale's date representation (e.g., 12/31/99). | -| `%F` | `2001-07-08` | Year-month-day format (ISO 8601). Same as `%Y-%m-%d`. | -| `%v` | ` 8-Jul-2001` | Day-month-year format. Same as `%e-%b-%Y`. | - -### Time specifiers - -| Variable | Example | Description | -| :------: | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | -| `%H` | `00` | Hour number (00--23), zero-padded to 2 digits. | -| `%k` | ` 0` | Same as `%H` but space-padded. Same as `%_H`. | -| `%I` | `12` | Hour number in 12-hour clocks (01--12), zero-padded to 2 digits. | -| `%l` | `12` | Same as `%I` but space-padded. Same as `%_I`. | -| `%P` | `am` | `am` or `pm` in 12-hour clocks. | -| `%p` | `AM` | `AM` or `PM` in 12-hour clocks. | -| `%M` | `34` | Minute number (00--59), zero-padded to 2 digits. | -| `%S` | `60` | Second number (00--60), zero-padded to 2 digits. [^4] | -| `%f` | `26490000` | Number of nanoseconds since last whole second. [^7] | -| `%.f` | `.026490` | Decimal fraction of a second. Consumes the leading dot. [^7] | -| `%.3f` | `.026` | Decimal fraction of a second with a fixed length of 3. | -| `%.6f` | `.026490` | Decimal fraction of a second with a fixed length of 6. | -| `%.9f` | `.026490000` | Decimal fraction of a second with a fixed length of 9. | -| `%3f` | `026` | Decimal fraction of a second like `%.3f` but without the leading dot. | -| `%6f` | `026490` | Decimal fraction of a second like `%.6f` but without the leading dot. | -| `%9f` | `026490000` | Decimal fraction of a second like `%.9f` but without the leading dot. | -| `%R` | `00:34` | Hour-minute format. Same as `%H:%M`. | -| `%T` | `00:34:60` | Hour-minute-second format. Same as `%H:%M:%S`. | -| `%X` | `00:34:60` | Locale's time representation (e.g., 23:13:48). | -| `%r` | `12:34:60 AM` | Locale's 12 hour clock time. (e.g., 11:11:04 PM). Falls back to `%X` if the locale does not have a 12 hour clock format. | - -### Time zone specifiers - -| Variable | Example | Description | -| :------: | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------- | -| `%Z` | `ACST` | Local time zone name. Skips all non-whitespace characters during parsing. Identical to `%:z` when formatting. [^8] | -| `%z` | `+0930` | Offset from the local time to UTC (with UTC being `+0000`). | -| `%:z` | `+09:30` | Same as `%z` but with a colon. | -| `%::z` | `+09:30:00` | Offset from the local time to UTC with seconds. | -| `%:::z` | `+09` | Offset from the local time to UTC without minutes. | -| `%#z` | `+09` | *Parsing only:* Same as `%z` but allows minutes to be missing or present. | - -### Date and time specifiers - -| Variable | Example | Description | -| :------: | :--------------------------------- | :--------------------------------------------------------------------- | -| `%c` | `Sun Jul 8 00:34:60 2001` | Locale's date and time (e.g., Thu Mar 3 23:05:25 2005). | -| `%+` | `2001-07-08T00:34:60.026490+09:30` | ISO 8601 / RFC 3339 date & time format. [^5] | -| `%s` | `994518299` | UNIX timestamp, the number of seconds since 1970-01-01 00:00 UTC. [^6] | - -### Special specifiers - -| Variable | Example | Description | -| :------: | :------ | :---------------------- | -| `%t` | | Literal tab (`\t`). | -| `%n` | | Literal newline (`\n`). | -| `%%` | | Literal percent sign. | - -It is possible to override the default padding behavior of numeric specifiers `%?`. -This is not allowed for other specifiers and results in the `BAD_FORMAT` error. - -Modifier | Description --------- | ----------- -`%-?` | Suppresses any padding including spaces and zeroes. (e.g. `%j` = `012`, `%-j` = `12`) -`%_?` | Uses spaces as a padding. (e.g. `%j` = `012`, `%_j` = ` 12`) -`%0?` | Uses zeroes as a padding. (e.g. `%e` = ` 9`, `%0e` = `09`) - -Notes: - -[^1]: `%C`, `%y`: - This is floor division, so 100 BCE (year number -99) will print `-1` and `99` respectively. -[^2]: `%U`: - Week 1 starts with the first Sunday in that year. - It is possible to have week 0 for days before the first Sunday. - -[^3]: `%G`, `%g`, `%V`: - Week 1 is the first week with at least 4 days in that year. - Week 0 does not exist, so this should be used with `%G` or `%g`. - -[^4]: `%S`: - It accounts for leap seconds, so `60` is possible. - -[^5]: `%+`: Same as `%Y-%m-%dT%H:%M:%S%.f%:z`, i.e. 0, 3, 6 or 9 fractional - digits for seconds and colons in the time zone offset. -
-
- This format also supports having a `Z` or `UTC` in place of `%:z`. They - are equivalent to `+00:00`. -
-
- Note that all `T`, `Z`, and `UTC` are parsed case-insensitively. -
-
- The typical `strftime` implementations have different (and locale-dependent) - formats for this specifier. While Chrono's format for `%+` is far more - stable, it is best to avoid this specifier if you want to control the exact - output. - -[^6]: `%s`: - This is not padded and can be negative. - For the purpose of Chrono, it only accounts for non-leap seconds - so it slightly differs from ISO C `strftime` behavior. - -[^7]: `%f`, `%.f`: -
- `%f` and `%.f` are notably different formatting specifiers.
- `%f` counts the number of nanoseconds since the last whole second, while `%.f` is a fraction of a - second.
- Example: 7μs is formatted as `7000` with `%f`, and formatted as `.000007` with `%.f`. - -[^8]: `%Z`: - Since `chrono` is not aware of timezones beyond their offsets, this specifier - **only prints the offset** when used for formatting. The timezone abbreviation - will NOT be printed. See [this issue](https://github.com/chronotope/chrono/issues/960) - for more information. -
-
- Offset will not be populated from the parsed data, nor will it be validated. - Timezone is completely ignored. Similar to the glibc `strptime` treatment of - this format code. -
-
- It is not possible to reliably convert from an abbreviation to an offset, - for example CDT can mean either Central Daylight Time (North America) or - China Daylight Time. -*/ \ No newline at end of file + diff --git a/content/influxdb/clustered/admin/custom-partitions/view-partitions.md b/content/influxdb/clustered/admin/custom-partitions/view-partitions.md new file mode 100644 index 000000000..b20086630 --- /dev/null +++ b/content/influxdb/clustered/admin/custom-partitions/view-partitions.md @@ -0,0 +1,22 @@ +--- +title: View partition information +description: > + Query partition information from InfluxDB v3 system tables to view partition + templates and verify partitions are working as intended. +menu: + influxdb_clustered: + name: View partitions + parent: Manage data partitioning +weight: 202 +list_code_example: | + ```sql + SELECT * FROM system.partitions WHERE table_name = 'example-table' + ``` +related: + - /influxdb/clustered/admin/query-system-data/ +source: /shared/v3-distributed-admin-custom-partitions/view-partitions.md +--- + + diff --git a/content/influxdb/clustered/admin/databases/create.md b/content/influxdb/clustered/admin/databases/create.md index 9b1d7a8b7..96c71dfc5 100644 --- a/content/influxdb/clustered/admin/databases/create.md +++ b/content/influxdb/clustered/admin/databases/create.md @@ -230,9 +230,9 @@ Use the `--template-tag`, `--template-tag-bucket, and `--template-timeformat` flags to define partition template parts used to generate partition keys for the database. For more information, see [Manage data partitioning](/influxdb/clustered/admin/custom-partitions/). -{{% note %}} +{{% warn %}} #### Partition templates can only be applied on create You can only apply a partition template when creating a database. You can't update a partition template on an existing database. -{{% /note %}} +{{% /warn %}} diff --git a/content/influxdb/clustered/admin/env-vars.md b/content/influxdb/clustered/admin/env-vars.md new file mode 100644 index 000000000..f74211755 --- /dev/null +++ b/content/influxdb/clustered/admin/env-vars.md @@ -0,0 +1,284 @@ +--- +title: Manage environment variables in your InfluxDB Cluster +description: > + Use environment variables to define settings for individual components in your + InfluxDB cluster. +menu: + influxdb_clustered: + parent: Administer InfluxDB Clustered + name: Manage environment variables +weight: 208 +--- + +Use environment variables to define settings for individual components in your +InfluxDB cluster and adjust your cluster's running configuration. +Define environment variables for each component in your `AppInstance` resource. + +InfluxDB Clustered components support various environment variables. +While many of these variables have default settings, you can customize them by +setting your own values. + +{{% warn %}} +#### Overriding default settings may affect overall cluster performance + +{{% product-name %}} components have complex interactions that can be affected +when overriding default configuration settings. +Changing these settings may impact overall cluster performance. +Before making configuration changes using environment variables, consider +consulting [InfluxData Support](https://support.influxdata.com/) to identify any +potential unintended consequences. +{{% /warn %}} + +## AppInstance component schema + +In your `AppInstance` resource, configure individual component settings in the +`spec.package.spec.components` property if configuring your `AppInstance` resource +directly or, if using Helm, use the `components` property in your `values.yaml`. +This property supports the following InfluxDB Clustered component keys: + +- `ingester` +- `querier` +- `router` +- `compactor` +- `garbage-collector` + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + # ... + spec: + components: + ingester: + # Ingester settings ... + querier: + # Querier settings ... + router: + # Router settings. ... + compactor: + # Compactor settings ... + garbage-collector: + # Garbage collector settings ... +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +components: + ingester: + # Ingester settings ... + querier: + # Querier settings ... + router: + # Router settings. ... + compactor: + # Compactor settings ... + garbage-collector: + # Garbage collector settings ... +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +_For more information about components in the InfluxDB v3 storage engine, see +the [InfluxDB v3 storage engine architecture](/influxdb/clustered/reference/internals/storage-engine/)._ + +## Set environment variables for a component + +1. Under the specific component property, use the + `.template.containers.iox.env` property to define environment + variables. +2. In the `env` property, structure each environment variable as a key-value + pair where the key is the environment variable name and the value is the + environment variable value (string-formatted). + For example, to configure environment variables for the Garbage collector: + + {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + # ... + spec: + components: + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +components: + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' +``` +{{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +3. Apply the configuration changes to your cluster and add or update + environment variables in each component. + + {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +{{% note %}} +#### Update environment variables instead of removing them + +Most configuration settings that can be overridden by environment variables have +default values that are used if the environment variable is unset. Removing +environment variables from your `AppInstance` resource configuration will not +remove those environment variables entirely; instead, they will revert to their +default settings. To revert to the default settings, simply unset the +environment variable or update the value in your `AppInstance` resource to the +default value. + +In the preceding example, the `INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF` environment +variable is set to `6h`. If you remove `INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF` from +the `env` property, the cutoff reverts to its default setting of `30d`. +{{% /note %}} + +{{< expand-wrapper >}} +{{% expand "View example of environment variables in all components" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + # ... + spec: + components: + ingester: + template: + containers: + iox: + env: + INFLUXDB_IOX_WAL_ROTATION_PERIOD_SECONDS: '360' + querier: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_BYTES: '10737418240' # 10GiB + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '5000' + compactor: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_PERCENT: '80' + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +components: + ingester: + template: + containers: + iox: + env: + INFLUXDB_IOX_WAL_ROTATION_PERIOD_SECONDS: '360' + querier: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_BYTES: '10737418240' # 10GiB + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '5000' + compactor: + template: + containers: + iox: + env: + INFLUXDB_IOX_EXEC_MEM_POOL_PERCENT: '80' + garbage-collector: + template: + containers: + iox: + env: + INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF: '6h' + INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF: '6h' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/admin/licensing.md b/content/influxdb/clustered/admin/licensing.md index 90f716bbe..174ec4911 100644 --- a/content/influxdb/clustered/admin/licensing.md +++ b/content/influxdb/clustered/admin/licensing.md @@ -10,7 +10,7 @@ menu: weight: 101 influxdb/clustered/tags: [licensing] related: - - /influxdb/clustered/install/licensing/ + - /influxdb/clustered/install/set-up-cluster/licensing/ - /influxdb/clustered/admin/upgrade/ --- @@ -18,6 +18,10 @@ Install and manage your InfluxDB Clustered license to authorize the use of the InfluxDB Clustered software. - [Install your InfluxDB license](#install-your-influxdb-license) +- [Verify your license](#verify-your-license) + - [Verify database components](#verify-database-components) + - [Verify the Secret exists ](#verify-the-secret-exists) + - [View license controller logs](#view-license-controller-logs) - [Recover from a license misconfiguration](#recover-from-a-license-misconfiguration) - [Renew your license](#renew-your-license) - [License enforcement](#license-enforcement) @@ -27,27 +31,13 @@ the InfluxDB Clustered software. - [License expiry logs](#license-expiry-logs) - [Query brownout](#query-brownout) -{{% note %}} -#### License enforcement is currently an opt-in feature - -In currently available versions of InfluxDB Clustered, license enforcement is an -opt-in feature that allows InfluxData to introduce license enforcement to -customers, and allows customers to deactivate the feature if issues arise. -In the future, all releases of InfluxDB Clustered will require customers to -configure an active license before they can use the product. - -To opt into license enforcement, include the `useLicensedBinaries` feature flag -in your `AppInstance` resource _([See the example below](#enable-feature-flag))_. -To deactivate license enforcement, remove the `useLicensedBinaries` feature flag. -{{% /note %}} - ## Install your InfluxDB license {{% note %}} If setting up an InfluxDB Clustered deployment for the first time, first -[set up the prerequisites](/influxdb/clustered/install/licensing/) and -[configure your cluster](/influxdb/clustered/install/configure-cluster/). -After your InfluxDB namespace is created and prepared, you will be able to +[set up the prerequisites](/influxdb/clustered/install/set-up-cluster/licensing/) and +[configure your cluster](/influxdb/clustered/install/set-up-cluster/configure-cluster/). +After your InfluxDB namespace is created and prepared, you can install your license. {{% /note %}} @@ -64,30 +54,77 @@ install your license. kubectl apply --filename license.yml --namespace influxdb ``` -4. - Update your `AppInstance` resource to include the `useLicensedBinaries` feature flag. - Add the `useLicensedBinaries` entry to the `.spec.package.spec.featureFlags` - property--for example: - - ```yml - apiVersion: kubecfg.dev/v1alpha1 - kind: AppInstance - # ... - spec: - package: - spec: - featureFlags: - - useLicensedBinaries - ``` - InfluxDB Clustered detects the `License` resource and extracts the credentials into a secret required by InfluxDB Clustered Kubernetes pods. Pods validate the license secret both at startup and periodically (roughly once per hour) while running. +## Verify your license + +After you have activated your license, use the following signals to verify the +license is active and functioning. + +In your commands, replace the following: + +- {{% code-placeholder-key %}}`NAMESPACE`{{% /code-placeholder-key %}}: + your [InfluxDB namespace](/influxdb/clustered/install/set-up-cluster/configure-cluster/#create-a-namespace-for-influxdb) +- {{% code-placeholder-key %}}`POD_NAME`{{% /code-placeholder-key %}}: + your [InfluxDB Kubernetes pod](/influxdb/clustered/install/set-up-cluster/deploy/#inspect-cluster-pods) + +### Verify database components + +After you [install your license](#install-your-influxdb-license), +run the following command to check that database pods start up and are in the +`Running` state: + + + +```bash +kubectl get pods -l app=iox --namespace influxdb +``` + +If a `Pod` fails to start, run the following command to view pod information: + + + +{{% code-placeholders "POD_NAME" %}} + +```sh +kubectl describe pod POD_NAME --namespace influxdb +``` + +{{% /code-placeholders %}} + +### Verify the `Secret` exists + +Run the following command to verify that the licensing activation created a +`iox-license` secret: + + + +```sh +kubectl get secret iox-license --namespace influxdb +``` + +If the secret doesn't exist, +[view `license-controller` logs](#view-license-controller-logs) for more +information or errors. + +### View `license controller` logs + +The `license controller` component creates a `Secret` named `iox-license` from +your `License`. To view `license controller` logs for troubleshooting, run the +following command: + + + +```sh +kubectl logs deployment/license-controller --namespace influxdb +``` + ## Recover from a license misconfiguration -If you deploy a licensed release of InfluxDB Clustered with an invalid or +If you deploy a licensed release of {{% product-name %}} with an invalid or expired license, many of the pods in your cluster will crash on startup and will likely enter a `CrashLoopBackoff` state without ever running or becoming healthy. Because InfluxDB stores the license in a volume-mounted Kubernetes secret, invalid @@ -115,7 +152,6 @@ license enforcement. ### A valid license is required -_When you include the `useLicensedBinaries` feature flag_, Kubernetes pods running in your InfluxDB cluster must have a valid `License` resource to run. Licenses are issued by InfluxData. If there is no `License` resource installed in your cluster, one of two things may happen: diff --git a/content/influxdb/clustered/admin/query-system-data.md b/content/influxdb/clustered/admin/query-system-data.md new file mode 100644 index 000000000..b6e35dcda --- /dev/null +++ b/content/influxdb/clustered/admin/query-system-data.md @@ -0,0 +1,640 @@ +--- +title: Query system data +description: > + Query system tables in your InfluxDB cluster to see data related + to queries, tables, partitions, and compaction in your cluster. +menu: + influxdb_clustered: + parent: Administer InfluxDB Clustered + name: Query system data +weight: 105 +related: + - /influxdb/clustered/reference/cli/influxctl/query/ + - /influxdb/clustered/reference/internals/system-tables/ +--- + +{{< product-name >}} stores data related to queries, tables, partitions, and +compaction in _system tables_ within your cluster. +System tables contain time series data used by and generated from the +{{< product-name >}} internal monitoring system. +You can query the cluster system tables for information about your cluster. + +- [Query system tables](#query-system-tables) + - [Optimize queries to reduce impact to your cluster](#optimize-queries-to-reduce-impact-to-your-cluster) +- [System tables](#system-tables) + - [Understanding system table data distribution](#understanding-system-table-data-distribution) + - [system.queries](#systemqueries) + - [system.tables](#systemtables) + - [system.partitions](#systempartitions) + - [system.compactor](#systemcompactor) +- [System query examples](#system-query-examples) + - [Query logs](#query-logs) + - [Partitions](#partitions) + - [Storage usage](#storage-usage) + - [Compaction](#compaction) + +{{% warn %}} +#### May impact cluster performance + +Querying InfluxDB v3 system tables may impact write and query +performance of your {{< product-name omit=" Clustered" >}} cluster. +Use filters to [optimize queries to reduce impact to your cluster](#optimize-queries-to-reduce-impact-to-your-cluster). + + + +#### System tables are subject to change + +System tables are not part of InfluxDB's stable API and may change with new releases. +The provided schema information and query examples are valid as of **September 18, 2024**. +If you detect a schema change or a non-functioning query example, please +[submit an issue](https://github.com/influxdata/docs-v2/issues/new/choose). + + +{{% /warn %}} + +## Query system tables + +{{% note %}} +Querying system tables with `influxctl` requires **`influxctl` v2.8.0 or newer**. +{{% /note %}} + +Use the [`influxctl query` command](/influxdb/clustered/reference/cli/influxctl/query/) +and SQL to query system tables. +Provide the following: + +- **Enable system tables** with the `--enable-system-tables` command flag. +- **Database token**: A [database token](/influxdb/clustered/admin/tokens/#database-tokens) + with read permissions on the specified database. Uses the `token` setting from + the [`influxctl` connection profile](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) + or the `--token` command flag. +- **Database name**: The name of the database to query information about. + Uses the `database` setting from the + [`influxctl` connection profile](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) + or the `--database` command flag. +- **SQL query**: The SQL query to execute. + + Pass the query in one of the following ways: + + - a string on the command line + - a path to a file that contains the query + - a single dash (`-`) to read the query from stdin + +{{% code-placeholders "DATABASE_(TOKEN|NAME)|SQL_QUERY" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[string](#) +[file](#) +[stdin](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +influxctl query \ + --enable-system-tables \ + --database DATABASE_NAME \ + --token DATABASE_TOKEN \ + "SQL_QUERY" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +influxctl query \ + --enable-system-tables \ + --database DATABASE_NAME \ + --token DATABASE_TOKEN \ + /path/to/query.sql +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +cat ./query.sql | influxctl query \ + --enable-system-tables \ + --database DATABASE_NAME \ + --token DATABASE_TOKEN \ + - +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: + A database token with read access to the specified database +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + The name of the database to query information about. +- {{% code-placeholder-key %}}`SQL_QUERY`{{% /code-placeholder-key %}}: + The SQL query to execute. For examples, see + [System query examples](#system-query-examples). + +When prompted, enter `y` to acknowledge the potential impact querying system +tables may have on your cluster. + +### Optimize queries to reduce impact to your cluster + +Querying InfluxDB v3 system tables may impact the performance of your +{{< product-name omit=" Clustered" >}} cluster. +As you write data to a cluster, the number of partitions and Parquet files +can increase to a point that impacts system table performance. +Queries that took milliseconds with fewer files and partitions might take 10 +seconds or longer as files and partitions increase. + +Use the following filters to optimize your system table queries and reduce the impact on your +cluster's performance. + +In your queries, replace the following: + +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the table to retrieve partitions for +- {{% code-placeholder-key %}}`PARTITION_ID`{{% /code-placeholder-key %}}: a [partition ID](#retrieve-a-partition-id) (int64) +- {{% code-placeholder-key %}}`PARTITION_KEY`{{% /code-placeholder-key %}}: a [partition key](/influxdb/clustered/admin/custom-partitions/#partition-keys) + derived from the table's partition template. + The default format is `%Y-%m-%d` (for example, `2024-01-01`). + +##### Filter by table name + +When querying the `system.tables`, `system.partitions`, or `system.compactor` tables, use the +`WHERE` clause to filter by `table_name` . + +{{% code-placeholders "TABLE_NAME" %}} +```sql +SELECT * FROM system.partitions WHERE table_name = 'TABLE_NAME' +``` +{{% /code-placeholders%}} + +##### Filter by partition key + +When querying the `system.partitions` or `system.compactor` tables, use the `WHERE` clause to +filter by `partition_key`. + +{{% code-placeholders "PARTITION_KEY" %}} +```sql +SELECT * FROM system.partitions WHERE partition_key = 'PARTITION_KEY' +``` +{{% /code-placeholders %}} + +To further improve performance, use `AND` to pair `partition_key` with `table_name`--for example: + +{{% code-placeholders "TABLE_NAME|PARTITION_KEY" %}} +```sql +SELECT * +FROM system.partitions +WHERE + table_name = 'TABLE_NAME' + AND partition_key = 'PARTITION_KEY'; +``` +{{% /code-placeholders %}} + +{{% code-placeholders "TABLE_NAME|PARTITION_KEY" %}} +```sql +SELECT * +FROM system.compactor +WHERE + table_name = 'TABLE_NAME' + AND partition_key = 'PARTITION_KEY'; +``` +{{% /code-placeholders %}} + +##### Filter by partition ID + +When querying the `system.partitions` or `system.compactor` table, use the `WHERE` clause to +filter by `partition_id` . + +{{% code-placeholders "PARTITION_ID" %}} +```sql +SELECT * FROM system.partitions WHERE partition_id = PARTITION_ID +``` +{{% /code-placeholders %}} + +For the most optimized approach, use `AND` to pair `partition_id` with `table_name`--for example: + +{{% code-placeholders "TABLE_NAME|PARTITION_ID" %}} +```sql +SELECT * +FROM system.partitions +WHERE + table_name = 'TABLE_NAME' + AND partition_id = PARTITION_ID; +``` +{{% /code-placeholders %}} + +Although you don't need to pair `partition_id` with `table_name` (because a partition ID is unique within a cluster), +it's the most optimized approach, _especially when you have many tables in a database_. + +###### Retrieve a partition ID + +To retrieve a partition ID, query `system.partitions` for a `table_name` and `partition_key` pair--for example: + +{{% code-placeholders "TABLE_NAME|PARTITION_KEY" %}} +```sql +SELECT + table_name, + partition_key, + partition_id +FROM system.partitions +WHERE + table_name = 'TABLE_NAME' + AND partition_key = 'PARTITION_KEY'; +``` +{{% /code-placeholders %}} + +The result contains the `partition_id`: + +| table_name | partition_key | partition_id | +| :--------- | :---------------- | -----------: | +| weather | 43 \| 2020-05-27 | 1362 | + +##### Combine filters for performance improvement + +Use the `AND`, `OR`, or `IN` keywords to combine filters in your query. + +- **Use `OR` or `IN` conditions when filtering for different values in the same column**--for example: + + ```sql + WHERE partition_id = 1 OR partition_id = 2 + ``` + + Use `IN` to make multiple `OR` conditions more readable--for example: + + ```sql + WHERE table_name IN ('foo', 'bar', 'baz') + ``` + +- **Avoid mixing different columns in `OR` conditions**, as this won't improve performance--for example: + + ```sql + WHERE table_name = 'foo' OR partition_id = 2 -- This will not improve performance + ``` + +## System tables + +{{% warn %}} +_System tables are [subject to change](#system-tables-are-subject-to-change)._ +{{% /warn %}} + +### Understanding system table data distribution + +Data in `system.tables`, `system.partitions`, and `system.compactor` includes +data for all [InfluxDB Queriers](/influxdb/clustered/reference/internals/storage-engine/#querier) in your cluster. +The data comes from the catalog, and because all the queriers share one catalog, +the results from these three tables derive from the same source data, +regardless of which querier you connect to. + +However, the `system.queries` table is different--data is local to each Querier. +`system.queries` contains a non-persisted log of queries run against the current +querier to which your query is routed. +The query log is specific to the current Querier and isn't shared across +queriers in your cluster. +Logs are scoped to the specified database. + +- [system.queries](#systemqueries) +- [system.tables](#systemtables) +- [system.partitions](#systempartitions) +- [system.compactor](#systemcompactor) + +### system.queries + +The `system.queries` table stores log entries for queries executed for the provided namespace (database) on the node that is _currently handling queries_. +`system.queries` reflects a process-local, in-memory, namespace-scoped query log. + +While this table may be useful for debugging and monitoring queries, keep the following in mind: + +- Records stored in `system.queries` are transient and volatile + - InfluxDB deletes `system.queries` records during pod restarts. + - Queries for one namespace can evict records from another namespace. +- Data reflects the state of a specific pod answering queries for the namespace. + - Data isn't shared across queriers in your cluster. + - A query for records in `system.queries` can return different results + depending on the pod the request was routed to. + +{{< expand-wrapper >}} +{{% expand "View `system.queries` schema" %}} + +The `system.queries` table contains the following columns: + +- id +- phase +- **issue_time**: timestamp when the query was issued +- **query_type**: type (syntax: `sql`, `flightsql`, or `influxql`) of the query +- **query_text**: query statement text +- partitions +- parquet_files +- plan_duration +- permit_duration +- execute_duration +- end2end_duration +- compute_duration +- max_memory +- **success**: execution status (boolean) of the query +- running +- cancelled +- **trace_id**: trace ID for debugging and monitoring events + +{{% /expand %}} +{{< /expand-wrapper >}} + +{{% note %}} +_When listing measurements (tables) available within a namespace, +some clients and query tools may include the `queries` table in the list of +namespace tables._ +{{% /note %}} + +### system.tables + +The `system.tables` table contains information about tables in the specified database. + +{{< expand-wrapper >}} +{{% expand "View `system.tables` schema" %}} + +The `system.tables` table contains the following columns: + +- table_name +- partition_template + +{{% /expand %}} +{{< /expand-wrapper >}} + +### system.partitions + +The `system.partitions` table contains information about partitions associated +with the specified database. + +{{< expand-wrapper >}} +{{% expand "View `system.partitions` schema" %}} + +The `system.partitions` table contains the following columns: + +- partition_id +- table_name +- partition_key +- last_new_file_created_at +- num_files +- total_size_mb + +{{% /expand %}} +{{< /expand-wrapper >}} + +### system.compactor + +The `system.compactor` table contains information about compacted partition Parquet +files associated with the specified database. + +{{< expand-wrapper >}} +{{% expand "View `system.compactor` schema" %}} + +The `system.compactor` table contains the following columns: + +- partition_id +- table_name +- partition_key +- total_l0_files +- total_l1_files +- total_l2_files +- total_l0_bytes +- total_l1_bytes +- total_l2_bytes +- skipped_reason + +{{% /expand %}} +{{< /expand-wrapper >}} + +## System query examples + +{{% warn %}} +#### May impact cluster performance + +Querying InfluxDB v3 system tables may impact write and query +performance of your {{< product-name omit=" Clustered" >}} cluster. + +The examples in this section include `WHERE` filters to [optimize queries and reduce impact to your cluster](#optimize-queries-to-reduce-impact-to-your-cluster). +{{% /warn %}} + +- [Query logs](#query-logs) + - [View all stored query logs](#view-all-stored-query-logs) + - [View query logs for queries with end-to-end durations above a threshold](#view-query-logs-for-queries-with-end-to-end-durations-above-a-threshold) + - [View query logs for a specific query within a time interval](#view-query-logs-for-a-specific-query-within-a-time-interval) +- [Partitions](#partitions) + - [View the partition template of a specific table](#view-the-partition-template-of-a-specific-table) + - [View all partitions for a table](#view-all-partitions-for-a-table) + - [View the number of partitions per table](#view-the-number-of-partitions-per-table) + - [View the number of partitions for a specific table](#view-the-number-of-partitions-for-a-specific-table) +- [Storage usage](#storage-usage) + - [View the size in megabytes of a specific table](#view-the-size-in-megabytes-of-a-specific-table) + - [View the size in megabytes per table](#view-the-size-in-megabytes-per-table) + - [View the total size in bytes of compacted partitions per table](#view-the-total-size-in-bytes-of-compacted-partitions-per-table) + - [View the total size in bytes of compacted partitions for a specific table](#view-the-total-size-in-bytes-of-compacted-partitions-for-a-specific-table) +- [Compaction](#compaction) + - [View compaction totals for each table](#view-compaction-totals-for-each-table) + - [View compaction totals for a specific table](#view-compaction-totals-for-a-specific-table) + +In the examples below, replace {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}} +with the name of the table you want to query information about. + +--- + +{{% code-placeholders "TABLE_NAME" %}} + +### Query logs + +#### View all stored query logs + +```sql +SELECT * FROM system.queries +``` + +#### View query logs for queries with end-to-end durations above a threshold + +The following returns query logs for queries with an end-to-end duration greater +than 50 milliseconds. + +```sql +SELECT * +FROM + system.queries +WHERE + end2end_duration::BIGINT > (50 * 1000000) +``` + +### View query logs for a specific query within a time interval + +{{< code-tabs >}} +{{% tabs %}} +[SQL](#) +[Python](#) +{{% /tabs %}} +{{% code-tab-content %}} + +```sql +SELECT * +FROM system.queries +WHERE issue_time >= now() - INTERVAL '1 day' + AND query_text LIKE '%select * from home%' +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```python +from influxdb_client_3 import InfluxDBClient3 +client = InfluxDBClient3(token = DATABASE_TOKEN, + host = HOSTNAME, + org = '', + database=DATABASE_NAME) +client.query('select * from home') +reader = client.query(''' + SELECT * + FROM system.queries + WHERE issue_time >= now() - INTERVAL '1 day' + AND query_text LIKE '%select * from home%' + ''', + language='sql', + headers=[(b"iox-debug", b"true")], + mode="reader") +``` + +{{% /code-tab-content %}} +{{< /code-tabs >}} + +--- + +### Partitions + +#### View the partition template of a specific table + +```sql +SELECT * +FROM + system.tables +WHERE + table_name = 'TABLE_NAME' +``` + +#### View all partitions for a table + +```sql +SELECT * +FROM + system.partitions +WHERE + table_name = 'TABLE_NAME' +``` + +#### View the number of partitions per table + +```sql +SELECT + table_name, + COUNT(*) AS partition_count +FROM + system.partitions +WHERE + table_name IN ('foo', 'bar', 'baz') +GROUP BY + table_name +``` + +#### View the number of partitions for a specific table + +```sql +SELECT + COUNT(*) AS partition_count +FROM + system.partitions +WHERE + table_name = 'TABLE_NAME' +``` + +--- + +### Storage usage + +#### View the size in megabytes of a specific table + +```sql +SELECT + SUM(total_size_mb) AS total_size_mb +FROM + system.partitions +WHERE + table_name = 'TABLE_NAME' +``` + +#### View the size in megabytes per table + +```sql +SELECT + table_name, + SUM(total_size_mb) AS total_size_mb +FROM + system.partitions +WHERE + table_name IN ('foo', 'bar', 'baz') +GROUP BY + table_name +``` + +#### View the total size in bytes of compacted partitions per table + +```sql +SELECT + table_name, + SUM(total_l0_bytes) + SUM(total_l1_bytes) + SUM(total_l2_bytes) AS total_bytes +FROM + system.compactor +WHERE + table_name IN ('foo', 'bar', 'baz') +GROUP BY + table_name +``` + +#### View the total size in bytes of compacted partitions for a specific table + +```sql +SELECT + SUM(total_l0_bytes) + SUM(total_l1_bytes) + SUM(total_l2_bytes) AS total_bytes +FROM + system.compactor +WHERE + table_name = 'TABLE_NAME' +``` + +--- + +### Compaction + +#### View compaction totals for each table + +```sql +SELECT + table_name, + SUM(total_l0_files) AS total_l0_files, + SUM(total_l1_files) AS total_l1_files, + SUM(total_l2_files) AS total_l2_files, + SUM(total_l0_bytes) AS total_l0_bytes, + SUM(total_l1_bytes) AS total_l1_bytes, + SUM(total_l2_bytes) AS total_l2_bytes +FROM + system.compactor +WHERE + table_name IN ('foo', 'bar', 'baz') +GROUP BY + table_name +``` + +#### View compaction totals for a specific table + +```sql +SELECT + SUM(total_l0_files) AS total_l0_files, + SUM(total_l1_files) AS total_l1_files, + SUM(total_l2_files) AS total_l2_files, + SUM(total_l0_bytes) AS total_l0_bytes, + SUM(total_l1_bytes) AS total_l1_bytes, + SUM(total_l2_bytes) AS total_l2_bytes +FROM + system.compactor +WHERE + table_name = 'TABLE_NAME' +``` + +{{% /code-placeholders %}} diff --git a/content/influxdb/clustered/admin/scale-cluster.md b/content/influxdb/clustered/admin/scale-cluster.md index 31aa9042f..3607b6c67 100644 --- a/content/influxdb/clustered/admin/scale-cluster.md +++ b/content/influxdb/clustered/admin/scale-cluster.md @@ -32,6 +32,7 @@ resources available to each component. - [Querier](#querier) - [Router](#router) - [Compactor](#compactor) + - [Garbage collector](#garbage-collector) - [Catalog](#catalog) - [Object store](#object-store) @@ -67,6 +68,7 @@ properties in your `AppInstance` resource: - Querier - Compactor - Router +- Garbage collector {{% note %}} #### Scale your Catalog and Object store @@ -77,6 +79,16 @@ are managed outside of your `AppInstance` resource. Scaling mechanisms for these components depend on the technology and underlying provider used for each. {{% /note %}} +{{< tabs-wrapper >}} +{{% tabs "small" %}} +[AppInstance](#) +[Helm](#) +{{% /tabs %}} + +{{% tab-content %}} + + + Use the `spec.package.spec.resources` property in your `AppInstance` resource defined in your `influxdb.yml` to define system resource minimums and limits for each pod and the number of replicas per component. @@ -119,11 +131,18 @@ resource minimums and limits per pod and replicas per component: - `limits` - `cpu`: Maximum CPU Resource units to assign to routers - `memory`: Maximum memory resource units to assign to routers + - `garbage-collector` + - `requests` + - `cpu`: Minimum CPU resource units to assign to the garbage collector + - `memory`: Minimum memory resource units to assign to the garbage collector + - `limits` + - `cpu`: Maximum CPU Resource units to assign to the garbage collector + - `memory`: Maximum memory resource units to assign to the garbage collector {{< expand-wrapper >}} {{% expand "View example `AppInstance` with resource requests and limits" %}} -{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} +{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER|GC)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} ```yml apiVersion: kubecfg.dev/v1alpha1 @@ -168,6 +187,13 @@ spec: limits: cpu: ROUTER_CPU_MAX memory: ROUTER_MEMORY_MAX + garbage-collector: + requests: + cpu: GC_CPU_MIN + memory: GC_MEMORY_MIN + limits: + cpu: GC_CPU_MAX + memory: GC_MEMORY_MAX ``` {{% /code-placeholders %}} @@ -175,6 +201,121 @@ spec: {{% /expand %}} {{< /expand-wrapper >}} + + +{{% /tab-content %}} +{{% tab-content %}} + + + +Use the `resources` property in your `values.yaml` to define system resource +minimums and limits for each pod and the number of replicas per component. +`requests` are the minimum that the Kubernetes scheduler should reserve for a pod. +`limits` are the maximum that a pod should be allowed to use. + +Use the following properties to define resource minimums and limits per pod and +replicas per component: + +- `resources` + - `ingester` + - `requests` + - `cpu`: Minimum CPU resource units to assign to ingesters + - `memory`: Minimum memory resource units to assign to ingesters + - `replicas`: Number of ingester replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to ingesters + - `memory`: Maximum memory resource units to assign to ingesters + - `compactor` + - `requests` + - `cpu`: Minimum CPU resource units to assign to compactors + - `memory`: Minimum memory resource units to assign to compactors + - `replicas`: Number of compactor replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to compactors + - `memory`: Maximum memory resource units to assign to compactors + - `querier` + - `requests` + - `cpu`: Minimum CPU resource units to assign to queriers + - `memory`: Minimum memory resource units to assign to queriers + - `replicas`: Number of querier replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to queriers + - `memory`: Maximum memory resource units to assign to queriers + - `router` + - `requests` + - `cpu`: Minimum CPU resource units to assign to routers + - `memory`: Minimum memory resource units to assign to routers + - `replicas`: Number of router replicas to provision + - `limits` + - `cpu`: Maximum CPU Resource units to assign to routers + - `memory`: Maximum memory resource units to assign to routers + - `garbage-collector` + - `requests` + - `cpu`: Minimum CPU resource units to assign to the garbage collector + - `memory`: Minimum memory resource units to assign to the garbage collector + - `limits` + - `cpu`: Maximum CPU Resource units to assign to the garbage collector + - `memory`: Maximum memory resource units to assign to the garbage collector + +{{< expand-wrapper >}} +{{% expand "View example `values.yaml` with resource requests and limits" %}} + +{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER|GC)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} + +```yml +# ... + resources: + ingester: + requests: + cpu: INGESTER_CPU_MIN + memory: INGESTER_MEMORY_MIN + replicas: INGESTER_REPLICAS # Default is 3 + limits: + cpu: INGESTER_CPU_MAX + memory: INGESTER_MEMORY_MAX + compactor: + requests: + cpu: COMPACTOR_CPU_MIN + memory: COMPACTOR_MEMORY_MIN + replicas: COMPACTOR_REPLICAS # Default is 1 + limits: + cpu: COMPACTOR_CPU_MAX + memory: COMPACTOR_MEMORY_MAX + querier: + requests: + cpu: QUERIER_CPU_MIN + memory: QUERIER_MEMORY_MIN + replicas: QUERIER_REPLICAS # Default is 1 + limits: + cpu: QUERIER_CPU_MAX + memory: QUERIER_MEMORY_MAX + router: + requests: + cpu: ROUTER_CPU_MIN + memory: ROUTER_MEMORY_MIN + replicas: ROUTER_REPLICAS # Default is 1 + limits: + cpu: ROUTER_CPU_MAX + memory: ROUTER_MEMORY_MAX + garbage-collector: + requests: + cpu: GC_CPU_MIN + memory: GC_MEMORY_MIN + limits: + cpu: GC_CPU_MAX + memory: GC_MEMORY_MAX +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + {{% note %}} Applying resource limits to pods is optional, but provides better resource isolation and protects against pods using more resources than intended. For @@ -189,8 +330,7 @@ information, see [Kubernetes resource requests and limits](https://kubernetes.io ### Horizontally scale a component To horizontally scale a component in your InfluxDB cluster, increase or decrease -the number of replicas for the component in the `spec.package.spec.resources` -property in your `AppInstance` resource and [apply the change](#apply-your-changes). +the number of replicas for the component and [apply the change](#apply-your-changes). {{% warn %}} #### Only use the AppInstance to scale component replicas @@ -202,6 +342,12 @@ Manually scaling replicas may cause errors. For example--to horizontally scale your [Ingester](/influxdb/clustered/reference/internals/storage-engine/#ingester): +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```yaml apiVersion: kubecfg.dev/v1alpha1 kind: AppInstance @@ -215,14 +361,31 @@ spec: # ... replicas: 6 ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +resources: + ingester: + requests: + # ... + replicas: 6 +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} ### Vertically scale a component To vertically scale a component in your InfluxDB cluster, increase or decrease -the CPU and memory resource units to assign to component pods in the -`spec.package.spec.resources` property in your `AppInstance` resource and +the CPU and memory resource units to assign to component pods and [apply the change](#apply-your-changes). +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```yaml apiVersion: kubecfg.dev/v1alpha1 kind: AppInstance @@ -240,17 +403,53 @@ spec: cpu: "1000m" memory: "1024MiB" ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +# ... +resources: + ingester: + requests: + cpu: "500m" + memory: "512MiB" + # ... + limits: + cpu: "1000m" + memory: "1024MiB" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} ### Apply your changes After modifying the `AppInstance` resource, use `kubectl apply` to apply the configuration changes to your cluster and scale the updated components. -```sh +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash kubectl apply \ --filename myinfluxdb.yml \ --namespace influxdb ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} ## Scale your cluster as a whole @@ -266,6 +465,7 @@ to automatically scale your cluster as needed. - [Ingester](#ingester) - [Querier](#querier) - [Compactor](#compactor) +- [Garbage collector](#garbage-collector) - [Catalog](#catalog) - [Object store](#object-store) @@ -294,13 +494,20 @@ improves query performance and reduces pressure on the Compactor. Storage speed also helps with query performance. Configure the storage volume attached to Ingester pods in the -`spec.package.spec.ingesterStorage` property of your `AppInstance` resource. +`spec.package.spec.ingesterStorage` property of your `AppInstance` resource or, +if using Helm, the `ingesterStorage` property of your `values.yaml`. {{< expand-wrapper >}} {{% expand "View example Ingester storage configuration" %}} {{% code-placeholders "STORAGE_(CLASS|SIZE)" %}} +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} ```yml apiVersion: kubecfg.dev/v1alpha1 kind: AppInstance @@ -317,6 +524,20 @@ spec: # Set the storage size (minimum 2Gi recommended) storage: STORAGE_SIZE ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yml +# ... +ingesterStorage: + # (Optional) Set the storage class. This will differ based on the K8s + #environment and desired storage characteristics. + # If not set, the default storage class is used. + storageClassName: STORAGE_CLASS + # Set the storage size (minimum 2Gi recommended) + storage: STORAGE_SIZE +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} {{% /code-placeholders %}} @@ -340,6 +561,13 @@ increasing the available CPU) is the most effective scaling strategy for the Compactor. Horizontal scaling increases compaction throughput, but not as efficiently as vertical scaling. +### Garbage collector + +The Garbage collector can be scaled [vertically](#vertical-scaling). It is a +light-weight process that typically doesn't require many system resources, but +if you begin to see high resource consumption on the garbage collector, you can +scale it vertically to address the added workload. + ### Catalog Scaling strategies available for the Catalog depend on the PostgreSQL-compatible diff --git a/content/influxdb/clustered/admin/tables/create.md b/content/influxdb/clustered/admin/tables/create.md index cf0ee0c4e..e241a92cb 100644 --- a/content/influxdb/clustered/admin/tables/create.md +++ b/content/influxdb/clustered/admin/tables/create.md @@ -71,9 +71,9 @@ If no template flags are provided, the table uses the partition template of the target database. For more information, see [Manage data partitioning](/influxdb/clustered/admin/custom-partitions/). -{{% note %}} +{{% warn %}} #### Partition templates can only be applied on create You can only apply a partition template when creating a table. There is no way to update a partition template on an existing table. -{{% /note %}} +{{% /warn %}} diff --git a/content/influxdb/clustered/admin/upgrade.md b/content/influxdb/clustered/admin/upgrade.md index 16c3cb587..6c38f1959 100644 --- a/content/influxdb/clustered/admin/upgrade.md +++ b/content/influxdb/clustered/admin/upgrade.md @@ -11,14 +11,14 @@ weight: 206 influxdb/clustered/tags: [upgrade] related: - /influxdb/clustered/install/ - - /influxdb/clustered/install/configure-cluster/ - - /influxdb/clustered/install/deploy/ + - /influxdb/clustered/install/set-up-cluster/configure-cluster/ + - /influxdb/clustered/install/set-up-cluster/deploy/ --- Use Kubernetes to upgrade your InfluxDB Clustered version. InfluxDB Clustered versioning is defined in the `AppInstance` `CustomResourceDefinition` (CRD) in your -[`myinfluxdb.yml`](/influxdb/clustered/install/configure-cluster/). +[`myinfluxdb.yml`](/influxdb/clustered/install/set-up-cluster/configure-cluster/). - [Version format](#version-format) - [Upgrade your InfluxDB Clustered version](#upgrade-your-influxdb-clustered-version) diff --git a/content/influxdb/clustered/admin/users/_index.md b/content/influxdb/clustered/admin/users/_index.md index f08e5ae98..6c16b57d4 100644 --- a/content/influxdb/clustered/admin/users/_index.md +++ b/content/influxdb/clustered/admin/users/_index.md @@ -10,12 +10,12 @@ menu: weight: 102 cascade: related: - - /influxdb/clustered/install/auth/ - - /influxdb/clustered/install/configure-cluster/ + - /influxdb/clustered/install/secure-cluster/auth/ + - /influxdb/clustered/install/set-up-cluster/configure-cluster/ --- Manage users with administrative access to your InfluxDB cluster through your -[identity provider](/influxdb/clustered/install/auth/) and your InfluxDB +[identity provider](/influxdb/clustered/install/secure-cluster/auth/) and your InfluxDB `AppInstance` resource. Administrative access lets users perform actions like creating databases and tokens. diff --git a/content/influxdb/clustered/admin/users/add.md b/content/influxdb/clustered/admin/users/add.md index e4ed4859c..6cbefa63c 100644 --- a/content/influxdb/clustered/admin/users/add.md +++ b/content/influxdb/clustered/admin/users/add.md @@ -12,7 +12,7 @@ weight: 201 --- Add a user with administrative access to your InfluxDB cluster through your -[identity provider](/influxdb/clustered/install/auth/) and your InfluxDB +[identity provider](/influxdb/clustered/install/secure-cluster/auth/) and your InfluxDB `AppInstance` resource: 1. Use your identity provider to create an OAuth2 account for the user that @@ -97,7 +97,7 @@ Replace the following: Keycloak realm - {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: Keycloak user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Keycloak](/influxdb/clustered/install/auth/#find-user-ids-with-keycloak))_ + _(See [Find user IDs with Keycloak](/influxdb/clustered/install/secure-cluster/auth/#find-user-ids-with-keycloak))_ --- @@ -119,7 +119,12 @@ spec: jwksEndpoint: |- https://AUTH0_HOST/.well-known/openid-configuration users: - - AUTH0_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -152,7 +157,12 @@ spec: jwksEndpoint: |- https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys users: - - AZURE_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Azure. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -164,7 +174,7 @@ Replace the following: Microsoft Entra tenant ID - {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: Microsoft Entra user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ + _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/secure-cluster/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ --- @@ -249,7 +259,12 @@ admin: https://AUTH0_HOST/.well-known/openid-configuration # The list of users to grant access to Clustered via influxctl users: - - AUTH0_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -280,7 +295,12 @@ admin: https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys # The list of users to grant access to Clustered via influxctl users: - - AZURE_USER_ID + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Azure. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com ``` {{% /code-placeholders %}} @@ -292,7 +312,7 @@ Replace the following: Microsoft Entra tenant ID - {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: Microsoft Entra user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ + _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/secure-cluster/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ --- @@ -303,7 +323,7 @@ Replace the following: {{% /tab-content %}} {{< /tabs-wrapper >}} -3. Apply the change to your InfluxDB cluster. +3. Apply the change to your InfluxDB cluster. - If updating the `AppInstance` resource directly, use `kubectl` to apply the change. @@ -342,6 +362,6 @@ helm upgrade \ Once applied, the added user is granted administrative access to your InfluxDB cluster and can use `influxctl` to perform administrative actions. -See [Set up Authorization--Configure influxctl](/influxdb/clustered/install/auth/#configure-influxctl) +See [Set up Authorization--Configure influxctl](/influxdb/clustered/install/secure-cluster/auth/#configure-influxctl) for information about configuring the new user's `influxctl` client to communicate and authenticate with your InfluxDB cluster's identity provider. diff --git a/content/influxdb/clustered/get-started/query.md b/content/influxdb/clustered/get-started/query.md index 530c5551a..0d0de30c2 100644 --- a/content/influxdb/clustered/get-started/query.md +++ b/content/influxdb/clustered/get-started/query.md @@ -585,8 +585,7 @@ _If your project's virtual environment is already running, skip to step 3._ "time" "text/tabwriter" - "github.com/apache/arrow/go/v13/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -630,10 +629,9 @@ _If your project's virtual environment is already running, skip to step 3._ // Iterate over rows and prints column values in table format. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339). - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) @@ -653,8 +651,7 @@ _If your project's virtual environment is already running, skip to step 3._ - `io` - `os` - `text/tabwriter` - - `github.com/apache/arrow/go/v13/arrow` - - `github.com/InfluxCommunity/influxdb3-go/influxdb3` + - `github.com/InfluxCommunity/influxdb3-go/v2/influxdb3` 2. Defines a `Query()` function that does the following: diff --git a/content/influxdb/clustered/get-started/write.md b/content/influxdb/clustered/get-started/write.md index 18dd81f20..90032a744 100644 --- a/content/influxdb/clustered/get-started/write.md +++ b/content/influxdb/clustered/get-started/write.md @@ -840,7 +840,7 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 "fmt" "log" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) // Write line protocol data to InfluxDB diff --git a/content/influxdb/clustered/guides/api-compatibility/v1/_index.md b/content/influxdb/clustered/guides/api-compatibility/v1/_index.md index 23330633b..520f2a25c 100644 --- a/content/influxdb/clustered/guides/api-compatibility/v1/_index.md +++ b/content/influxdb/clustered/guides/api-compatibility/v1/_index.md @@ -456,7 +456,8 @@ For {{% product-name %}} v1 API `/query` requests, set parameters as listed in t Parameter | Allowed in | Ignored | Value ----------|------------|---------|------------------------------------------------------------------------- -`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_ +`chunked` | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. +`chunked_size` | Query string | Honored | **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. `db` | Query string | Honored | Database name | `epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision) | `p` | Query string | Honored | Database token diff --git a/content/influxdb/clustered/guides/migrate-data/migrate-tsm-to-clustered.md b/content/influxdb/clustered/guides/migrate-data/migrate-tsm-to-clustered.md index 72e0191ed..4dbfea761 100644 --- a/content/influxdb/clustered/guides/migrate-data/migrate-tsm-to-clustered.md +++ b/content/influxdb/clustered/guides/migrate-data/migrate-tsm-to-clustered.md @@ -27,10 +27,9 @@ that queries data from an InfluxDB Cloud TSM-powered bucket in time-based batche and writes each batch to an {{< product-name >}} (InfluxDB v3) database in another organization. -{{% cloud %}} -All query requests are subject to your InfluxDB Cloud organization's -[rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). -{{% /cloud %}} +> [!Important] +> All query requests are subject to your InfluxDB Cloud organization's +> [rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - [Before you migrate](#before-you-migrate) - [Set up the migration](#set-up-the-migration) diff --git a/content/influxdb/clustered/install/_index.md b/content/influxdb/clustered/install/_index.md index 8fe1cac7f..edcf2708f 100644 --- a/content/influxdb/clustered/install/_index.md +++ b/content/influxdb/clustered/install/_index.md @@ -7,11 +7,30 @@ weight: 2 --- InfluxDB Clustered is deployed and managed using Kubernetes. -This multi-page guide walks through setting up prerequisites and configuring -your InfluxDB cluster deployment. +This installation guide walks you through the following four installation phases and +the goal of each phase. +This process helps you set up and run your cluster and ensure it +performs well with your expected production workload. + +1. **[Set up your cluster](/influxdb/clustered/install/set-up-cluster/)**: + Get a basic InfluxDB cluster up and running with as few external + dependencies as possible and confirm you can write and query data. +2. **[Customize your cluster](/influxdb/clustered/install/customize-cluster/)**: + Review and customize the available configuration options specific to your workload. +3. **[Optimize your cluster](/influxdb/clustered/install/optimize-cluster/)**: + Scale and load test your InfluxDB cluster to confirm that it will satisfy + your scalability and performance needs. Work with InfluxData to review your + schema and determine how best to organize your data and develop queries + representative of your workload to ensure queries meet performance requirements. +4. **[Secure your cluster](/influxdb/clustered/install/secure-cluster/)**: + Integrate InfluxDB with your identity provider to manage access to your + cluster. Install TLS certificates and enable TLS access. + Prepare your cluster for production use. + +## InfluxDB Clustered license InfluxDB Clustered is a commercial product offered by InfluxData, the creators -of InfluxDB. Please contact InfluxData Sales to obtain a license before +of InfluxDB. Please contact InfluxData Sales to obtain a license _before_ installing InfluxDB Clustered. Contact InfluxData Sales @@ -47,4 +66,4 @@ The Catalog and Object store contain all of the important state for Influxdb 3.0 After recovering the catalog and object store, you will need to update the dsn in myinfluxdb.yml and re-apply. --> -{{< page-nav next="/influxdb/clustered/install/prerequisites/" >}} +{{< page-nav next="/influxdb/clustered/install/set-up-cluster/prerequisites/" >}} diff --git a/content/influxdb/clustered/install/auth.md b/content/influxdb/clustered/install/auth.md deleted file mode 100644 index d45f45720..000000000 --- a/content/influxdb/clustered/install/auth.md +++ /dev/null @@ -1,394 +0,0 @@ ---- -title: Set up administrative authentication -description: > - Manage administrative access to your InfluxDB cluster through your identity provider. -menu: - influxdb_clustered: - name: Set up authentication - parent: Install InfluxDB Clustered -weight: 120 ---- - -Administrative access to your InfluxDB cluster is managed through your identity -provider. Use your identity provider to create OAuth2 accounts for all users -who need administrative access to your InfluxDB cluster. Administrative access -lets user perform actions like creating databases and tokens. - -{{% note %}} -Identity providers can be deployed with your InfluxDB cluster or run externally. -If you choose to deploy your provider with your InfluxDB cluster, the process -outlined below should be done _after_ your initial InfluxDB cluster deployment. -{{% /note %}} - -{{% note %}} -#### Bypass your identity provider for development and testing - -If running in a development or testing environment and you do not want to -authorize with an OAuth2 identity provider, {{< product-name >}} provides an -_admin token_ in your cluster's namespace that can be used to bypass your -identity provider. - -For more information, see -[Bypass your identity provider](/influxdb/clustered/admin/bypass-identity-provider/). -{{% /note %}} - -InfluxDB Clustered requires that your OAuth2 identity provider supports -[Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow). -InfluxData has tested with the following identity providers: - -- [Keycloak](https://www.keycloak.org/) -- [Microsoft Entra ID _(formerly Azure Active Directory)_](https://www.microsoft.com/en-us/security/business/microsoft-entra) -- [Auth0](https://auth0.com/) - -Setup instructions are provided for the following: - -{{< tabs-wrapper >}} -{{% tabs %}} -[Keycloak](#) -[Microsoft Entra ID](#) - - - -{{% /tabs %}} - -{{% tab-content %}} - - - -## Keycloak - -To use Keycloak as your identity provider: - -1. [Create a Keycloak realm](#create-a-keycloak-realm) -2. [Create a Keycloak client with device flow enabled](#create-a-keycloak-client-with-device-flow-enabled) -3. [Create users that need administrative access to your InfluxDB cluster](#create-users) -4. [Configure InfluxDB Clustered to use Keycloak](#configure-influxdb-clustered-to-use-keycloak) - -### Create a Keycloak realm - -See [Creating a realm](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-a-realm_server_administration_guide) -in the Keycloak documentation. - -### Create a Keycloak client with device flow enabled - -1. In the **Keycloak Admin Console**, navigate to **Clients** and then click - **Create Client**. -2. In the **General Settings** configuration step: - - 1. Set the **Client type** to **OpenID Connect**. - 2. Enter a **Client ID**, Save your client ID to be used later. - 3. _Optional:_ Enter a **Name** and **Description** for the client. - 4. Click **Next**. - -3. In the **Capability** configuration step, enable the - **OAuth 2.0 Device Authorization Grant** authentication flow, and then click - **Next**. -4. In the **Login settings** step, you don’t need to change anything. - Click **Save**. - -### Create users - -See [Creating users](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-user_server_administration_guide) -in the Keycloak documentation. - -#### Find user IDs with Keycloak - -To find the user IDs with Keycloak, use the Keycloak Admin Console or the Keycloak REST API. - -##### Keycloak Admin Console - -1. In the Keycloak Admin Console, navigate to your realm -2. Select **Users** in the left navigation. -3. Select the user you want to find the ID for. -4. Select the **Details** tab. The user ID is listed here. - -##### Keycloak REST API - -Send a GET request to the Keycloak REST API `/users` endpoint to fetch -the ID of a specific user. Provide the following: - -- **Query parameters** - - **username**: Username to retrieve information about - -{{% code-placeholders "KEYCLOAK_(HOST|REALM|USERNAME)" %}} - -```sh -curl https://KEYCLOAK_HOST/auth/admin/realms/KEYCLOAK_REALM/users?username=KEYCLOAK_USERNAME -``` - -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: - the Keycloak host and port (`host:port`) -- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: - the Keycloak realm -- {{% code-placeholder-key %}}`KEYCLOAK_USERNAME`{{% /code-placeholder-key %}}: - the Keycloak username to retrieve - ---- - -### Configure InfluxDB Clustered to use Keycloak - -Run the following command to retrieve a JSON object that contains the OpenID configuration -of your Keycloak realm: - -{{% code-placeholders "KEYCLOAK_(HOST|REALM)" %}} - -```sh -curl https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/.well-known/openid-configuration -``` - -{{% /code-placeholders %}} - -{{< expand-wrapper >}} -{{% expand "View example response body" %}} - -{{% code-placeholders "KEYCLOAK_(HOST|REALM)" %}} - -```json -{ - "issuer": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM", - "authorization_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/auth", - "token_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/token", - "device_authorization_endpoint": "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/auth/device", - "userinfo_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/userinfo", - "end_session_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/logout", - "jwks_uri": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs", - "grant_types_supported": ["authorization_code", "refresh_token", "password"], - "response_types_supported": ["code"], - "subject_types_supported": ["public"], - "id_token_signing_alg_values_supported": ["RS256"], - "response_modes_supported": ["query"] -} -``` - -{{% /code-placeholders %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -The following are important fields in the JSON object that are necessary to -connect your InfluxDB cluster and administrative tools to Keycloak: - -- **jwks_uri**: Used in your InfluxDB cluster configuration file. - _See [Configure your cluster--Configure your OAuth2 provider](/influxdb/clustered/install/configure-cluster/#configure-your-oauth2-provider)_. -- **device_authorization_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.device_url`) -- **token_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.token_url`) - - - -{{% /tab-content %}} -{{% tab-content %}} - - - -## Microsoft Entra ID - -To use Microsoft Entra ID as your identity provider: - -1. [Create a new tenant in Microsoft Entra ID](#create-a-new-tenant-in-microsoft-entra-id) -2. [Add users that need administrative access to your InfluxDB cluster](#add-users-that-need-administrative-access-to-your-influxdb-cluster) -3. [Register a new application with device code flow enabled](#register-a-new-application-with-device-code-flow-enabled) -4. Configure InfluxDB Clustered to use Microsoft Entra ID - -### Create a new tenant in Microsoft Entra ID - -See [Create a new tenant in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/create-new-tenant) -in the Microsoft Azure documentation. -_Copy and store your **Microsoft Entra Tenant ID**_. - -### Add users that need administrative access to your InfluxDB cluster - -See [Add or delete users](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/add-users) -in the Microsoft Azure documentation. - -#### Find user IDs with Microsoft Entra ID - -For Microsoft Entra ID, the unique user ID is the Microsoft ObjectId (OID). -To download a list of user OIDs: - -1. In the **Microsoft Azure Portal**, select **Users** in the left navigation. -2. Select users you want OIDs for and click **Download Users**. - -In the downloaded CSV file, user OIDs are provided in the `id` column. - -### Register a new application with device code flow enabled - -1. In the **Microsoft Azure Portal**, select **App Registrations** in the left navigation. -2. Click **New Registration** and enter a name for a new application to handle - authentication requests. -3. Click **Register Application**. _Copy and store your **Application (Client) ID**_. -4. In your registered application, click **Authentication** in the left navigation. -5. Under **Advanced Settings**, set **Allow public client flows** to **Yes**. - This enables the use of the [device code flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code) - for logging in to your InfluxDB cluster. - -### Configure InfluxDB Clustered to use Microsoft Entra ID - -Use the following command to retrieve a JSON object that contains the OpenID configuration -of your Microsoft Entra tenant: - -{{% code-placeholders "AZURE_TENANT_ID" %}} - -```sh -curl https://login.microsoftonline.com/AZURE_TENANT_ID/v2.0/.well-known/openid-configuration -``` - -{{% /code-placeholders %}} - -Replace {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}} -with your [Microsoft Entra tenant ID](#create-a-new-tenant-in-microsoft-entra-id). - -{{< expand-wrapper >}} -{{% expand "View example response body" %}} - -{{% code-placeholders "AZURE_TENANT_ID" %}} - -```js -{ - "issuer": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/", - "authorization_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/authorize", - "token_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/token", - "device_authorization_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/devicecode", - "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo", - "jwks_uri": "https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys", - "grant_types_supported": [ - "authorization_code", - "refresh_token", - "password" - ], - "response_types_supported": [ - "code" - ], - "subject_types_supported": [ - "public" - ], - "id_token_signing_alg_values_supported": [ - "RS256" - ], - "response_modes_supported": [ - "query" - ] -} -``` - -{{% /code-placeholders %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -The following are important fields in the JSON object that are necessary to -connect your InfluxDB cluster and administrative tools to Keycloak: - -- **jwks_uri**: Used in your InfluxDB cluster configuration file. - _See [Configure your cluster--Configure your OAuth2 provider](/influxdb/clustered/install/configure-cluster/?t=Microsoft+Entra+ID#configure-your-oauth2-provider)_. -- **device_authorization_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.device_url`) -- **token_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.token_url`) - - - -{{% /tab-content %}} - - - - - - - -{{< /tabs-wrapper >}} - -## Configure influxctl - -The [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/) is used to -perform administrative actions such as creating databases or database tokens. -All `influxctl` commands are first authorized using your identity provider. -Update your [`influxctl` configuration file](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) -to connect to your identity provider. - -The following examples show how to configure `influxctl` for various identity providers: - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Keycloak](#) -[Auth0](#) -[Microsoft Entra ID](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - - - -{{% code-placeholders "KEYCLOAK_(CLIENT_ID|PORT|REALM)" %}} - -```toml -[[profile]] - name = "default" - product = "clustered" - host = "{{< influxdb/host >}}" # InfluxDB cluster host - port = "8086" # InfluxDB cluster port - - [profile.auth.oauth2] - client_id = "KEYCLOAK_CLIENT_ID" - device_url = "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/auth/device" - token_url = "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/token" -``` - -{{% /code-placeholders %}} - - - -{{% /code-tab-content %}} -{{% code-tab-content %}} - - - -{{% code-placeholders "AUTH0_(CLIENT_)*(ID|SECRET|HOST)" %}} - -```toml -[[profile]] - name = "default" - product = "clustered" - host = "{{< influxdb/host >}}" # InfluxDB cluster host - port = "8086" # InfluxDB cluster port - - [profile.auth.oauth2] - client_id = "AUTH0_CLIENT_ID" - client_secret = "AUTH0_CLIENT_SECRET" - device_url = "https://AUTH0_HOST/oauth/device/code" - token_url = "https://AUTH0_HOST/oauth/token" -``` - -{{% /code-placeholders %}} - - - -{{% /code-tab-content %}} -{{% code-tab-content %}} - - - -{{% code-placeholders "AZURE_(CLIENT|TENANT)_ID" %}} - -```toml -[[profile]] - name = "default" - product = "clustered" - host = "{{< influxdb/host >}}" # InfluxDB cluster host - port = "8086" # InfluxDB cluster port - - [profile.auth.oauth2] - client_id = "AZURE_CLIENT_ID" - scopes = ["AZURE_CLIENT_ID/.default"] - device_url = "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/devicecode" - token_url = "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/token" -``` - -{{% /code-placeholders %}} - - - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -{{< page-nav prev="/influxdb/clustered/install/prerequisites/" next="/influxdb/clustered/install/configure-cluster/" nextText="Configure your cluster" >}} diff --git a/content/influxdb/clustered/install/configure-cluster/_index.md b/content/influxdb/clustered/install/configure-cluster/_index.md deleted file mode 100644 index f36a260ec..000000000 --- a/content/influxdb/clustered/install/configure-cluster/_index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Configure your InfluxDB cluster -description: > - InfluxDB Clustered deployments are managed using Kubernetes and configured using - a YAML configuration file. -menu: - influxdb_clustered: - name: Configure your cluster - parent: Install InfluxDB Clustered -weight: 130 -related: - - /influxdb/clustered/admin/upgrade/ ---- - -InfluxDB Clustered deployments are managed using Kubernetes and configured using -a YAML configuration file. -Apply configuration settings to your cluster by editing and applying a -Kubernetes custom resource (CRD) called `AppInstance`. -The AppInstance CRD is defined in a YAML file (use example-customer.yml as a -template) or, if using the InfluxDB Clustered Helm chart, is provided by the -chart and configured in a `values.yaml` file. - -Use one of the following methods to configure your InfluxDB cluster: - -{{< children type="anchored-list" >}} - -{{< children >}} diff --git a/content/influxdb/clustered/install/configure-cluster/directly.md b/content/influxdb/clustered/install/configure-cluster/directly.md deleted file mode 100644 index fca4952d4..000000000 --- a/content/influxdb/clustered/install/configure-cluster/directly.md +++ /dev/null @@ -1,911 +0,0 @@ ---- -title: Use the InfluxDB AppInstance resource configuration -list_title: Configure your InfluxDB AppInstance resource directly -description: > - Configure your InfluxDB cluster by editing configuration options in - the provided `AppInstance` resource. -menu: -menu: - influxdb_clustered: - name: Configure AppInstance - parent: Configure your cluster -weight: 220 ---- - -Manage your InfluxDB Clustered deployments using Kubernetes and apply configuration settings using -a YAML configuration file. - -- **`influxdb-docker-config.json`**: an authenticated Docker configuration file. - The InfluxDB Clustered software is in a secure container registry. - This file grants access to the collection of container images required to - install InfluxDB Clustered. -- **A tarball that contains the following files**: - - - **`app-instance-schema.json`**: Defines the schema for `example-customer.yml` - to be used with [Visual Studio Code (VS Code)](https://code.visualstudio.com/). - - **`example-customer.yml`**: Configuration for your InfluxDB cluster that includes - information about [prerequisites](/influxdb/clustered/install/prerequisites/). - - {{% note %}} - -This documentation refers to a `myinfluxdb.yml` file that you copy from -`example-customer.yml` and edit for your InfluxDB cluster. - - {{% /note %}} - -## Configuration data - -When ready to install InfluxDB, have the following information available: - -- **InfluxDB cluster hostname**: the hostname Kubernetes uses to expose InfluxDB API endpoints -- **PostgreSQL-style data source name (DSN)**: used to access your - PostgreSQL-compatible database that stores the InfluxDB Catalog. -- **Object store credentials** _(AWS S3 or S3-compatible)_ - - Endpoint URL - - Access key - - Bucket name - - Region (required for S3, may not be required for other object stores) -- **Local storage information** _(for ingester pods)_ - - Storage class - - Storage size -- **OAuth2 provider credentials** - - Client ID - - JWKS endpoint - - Device authorization endpoint - - Token endpoint - -InfluxDB is deployed to a Kubernetes namespace which, throughout the following -installation procedure, is referred to as the _target_ namespace. -For simplicity, we assume this namespace is `influxdb`, however -you may use any name you like. - -The InfluxDB installation, update, and upgrade processes are driven by editing -and applying a [Kubernetes custom resource (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) -called `AppInstance`. -The `AppInstance` CRD is defined in a YAML file (use `example-customer.yml` as a -template). - -The `AppInstance` resource contains key information, such as: - -- Name of the target namespace -- Version of the InfluxDB package -- Reference to the InfluxDB container registry pull secrets -- Hostname where the InfluxDB API is exposed -- Parameters to connect to [external prerequisites](/influxdb/clustered/install/prerequisites/) - -## Configure your cluster - -1. [Create a cluster configuration file](#create-a-cluster-configuration-file) -2. [Create a namespace for InfluxDB](#create-a-namespace-for-influxdb) -3. [Install kubecfg kubit operator](#install-kubecfg-kubit-operator) -4. [Configure access to the InfluxDB container registry](#configure-access-to-the-influxdb-container-registry) -5. [Set up cluster ingress](#set-up-cluster-ingress) -6. [Modify the configuration file to point to prerequisites](#modify-the-configuration-file-to-point-to-prerequisites) -7. [Provide a custom certificate authority bundle](#provide-a-custom-certificate-authority-bundle) - (Optional) - -### Create a cluster configuration file - -Copy the provided `example-customer.yml` file to create a new configuration file -specific to your InfluxDB cluster. For example, `myinfluxdb.yml`. - - - -```sh -cp example-customer.yml myinfluxdb.yml -``` - -{{% note %}} - -#### Use VS Code to edit your configuration file - -We recommend using [Visual Studio Code (VS Code)](https://code.visualstudio.com/) to edit your `myinfluxdb.yml` configuration file due -to its JSON Schema support, autocompletion, and validation features that ensure the best experience when editing your InfluxDB configuration. -InfluxData provides an `app-instance-schema.json` JSON schema file that VS Code can use to validate your configuration settings. -{{% /note %}} - -### Create a namespace for InfluxDB - -Create a namespace for InfluxDB--for example, enter the following `kubectl` command in your terminal: - - - -```sh -kubectl create namespace influxdb -``` - -If you use a namespace name other than `influxdb`, update the `.metadata.namespace` -field in your `myinfluxdb.yml` to use your custom namespace name. - -### Install kubecfg kubit operator - -The [`kubecfg kubit` operator](https://github.com/kubecfg/kubit) (maintained by InfluxData) -simplifies the installation and management of the InfluxDB Clustered package. -It manages the application of the jsonnet templates used to install, manage, and -update an InfluxDB cluster. - -Use `kubectl` to install the [kubecfg kubit](https://github.com/kubecfg/kubit) operator. - - - -```sh -kubectl apply -k 'https://github.com/kubecfg/kubit//kustomize/global?ref=v0.0.15' -``` - -### Configure access to the InfluxDB container registry - -The provided `influxdb-docker-config.json` grants access to a collection of -container images required to run InfluxDB Clustered. -Your Kubernetes Cluster needs access to the container registry to pull down and -install InfluxDB. - -When pulling InfluxDB Clustered images, there are two main scenarios: - -- You have a Kubernetes cluster that can pull from the InfluxData container registry. -- You run in an environment with no network interfaces ("air-gapped") and you - can only access a private container registry. - -In both scenarios, you need a valid container registry secret file. -Use [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane) to create a container registry secret file. - -1. [Install crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane#installation) -2. Use the following command to create a container registry secret file and - retrieve the necessary secrets: - -{{% code-placeholders "PACKAGE_VERSION" %}} - - - -```sh -mkdir /tmp/influxdbsecret -cp influxdb-docker-config.json /tmp/influxdbsecret/config.json -DOCKER_CONFIG=/tmp/influxdbsecret \ - crane manifest \ - us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION -``` - -{{% /code-placeholders %}} - ---- - -Replace {{% code-placeholder-key %}}`PACKAGE_VERSION`{{% /code-placeholder-key %}} -with your InfluxDB Clustered package version. - ---- - -If your Docker configuration is valid and you’re able to connect to the container -registry, the command succeeds and the output is the JSON manifest for the Docker -image, similar to the following: - -{{< expand-wrapper >}} -{{% expand "View JSON manifest" %}} - -```json -{ - "schemaVersion": 2, - "config": { - "mediaType": "application/vnd.kubecfg.bundle.config.v1+json", - "digest": "sha256:6900d2f248e678176c68f3768e7e48958bb96a59232070ff31b3b018cf299aa7", - "size": 8598 - }, - "layers": [ - { - "mediaType": "application/vnd.kubecfg.bundle.tar+gzip", - "digest": "sha256:7c1d62e76287035a9b22b2c155f328fae9beff2c6aa7a09a2dd2697539f41d98", - "size": 404059 - } - ], - "annotations": { - "org.opencontainers.image.created": "1970-01-01T00:00:00Z", - "org.opencontainers.image.revision": "unknown", - "org.opencontainers.image.source": "kubecfg pack" - } -} -``` - -{{% /expand %}} -{{< /expand-wrapper >}} - -If there’s a problem with the Docker configuration, crane won't retrieve the manifest and the output is similar to the following error: - -```sh -Error: fetching manifest us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:: GET https://us-docker.pkg.dev/v2/token?scope=repository%3Ainfluxdb2-artifacts%2Fclustered%2Finfluxdb%3Apull&service=: DENIED: Permission "artifactregistry.repositories.downloadArtifacts" denied on resource "projects/influxdb2-artifacts/locations/us/repositories/clustered" (or it may not exist) -``` - -{{< tabs-wrapper >}} -{{% tabs %}} -[Public registry (non-air-gapped)](#) -[Private registry (air-gapped)](#) -{{% /tabs %}} - -{{% tab-content %}} - - - -#### Public registry (non-air-gapped) - -To pull from the InfluxData registry, you need to create a Kubernetes secret in the target namespace. - -```sh -kubectl create secret docker-registry gar-docker-secret \ - --from-file=.dockerconfigjson=influxdb-docker-config.json \ - --namespace influxdb -``` - -If successful, the output is the following: - -```text -secret/gar-docker-secret created -``` - -By default, this secret is named `gar-docker-secret`. -If you change the name of this secret, you must also change the value of the -`imagePullSecret` field in the `AppInstance` custom resource to match. - - - -{{% /tab-content %}} -{{% tab-content %}} - - - -#### Private registry (air-gapped) - -If your Kubernetes cluster can't use a public network to download container images -from our container registry, do the following: - -1. Copy the images from the InfluxDB registry to your own private registry. -2. Configure your `AppInstance` resource with a reference to your private - registry name. -3. Provide credentials to your private registry. - -The list of images that you need to copy is included in the package metadata. -You can obtain it with any standard OCI image inspection tool. For example: - -{{% code-placeholders "PACKAGE_VERSION" %}} - - - -```sh -DOCKER_CONFIG=/tmp/influxdbsecret \ -crane config \ - us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION \ - | jq -r '.metadata["oci.image.list"].images[]' \ - > /tmp/images.txt -``` - -{{% /code-placeholders %}} - -The output is a list of image names, similar to the following: - -``` -us-docker.pkg.dev/influxdb2-artifacts/idpe/idpe-cd-ioxauth@sha256:5f015a7f28a816df706b66d59cb9d6f087d24614f485610619f0e3a808a73864 -us-docker.pkg.dev/influxdb2-artifacts/iox/iox@sha256:b59d80add235f29b806badf7410239a3176bc77cf2dc335a1b07ab68615b870c -... -``` - -Use `crane` to copy the images to your private registry: - -{{% code-placeholders "REGISTRY_HOSTNAME" %}} - - - -```sh - - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - -### Set up cluster ingress - -{{% note %}} -InfluxDB Clustered components use gRPC/HTTP2 protocols. If using an external load balancer, -you may need to explicitly enable these protocols on your load balancers. -{{% /note %}} - -[Kubernetes ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) routes HTTP/S requests to services within the cluster and requires deploying an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). - -You can provide your own ingress or you can install [Nginx Ingress Controller](https://github.com/kubernetes/ingress-nginx) to use the InfluxDB-defined ingress. - -If using the InfluxDB-defined ingress, add a valid TLS Certificate to the -cluster as a secret. Provide the paths to the TLS certificate file and key file: - -{{% code-placeholders "TLS_(CERT|KEY)_PATH" %}} - - - -```sh -kubectl create secret tls ingress-tls \ - --namespace influxdb \ - --cert TLS_CERT_PATH \ - --key TLS_KEY_PATH -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- _{{% code-placeholder-key %}}`TLS_CERT_PATH`{{% /code-placeholder-key %}}: - Path to the certificate file on your local machine._ -- _{{% code-placeholder-key %}}`TLS_KEY_PATH`{{% /code-placeholder-key %}}: - Path to the certificate secret key file on your local machine._ - ---- - -Provide the TLS certificate secret to the InfluxDB configuration in the -[Configure ingress step](#configure-ingress). - -### Modify the configuration file to point to prerequisites - -Update your `myinfluxdb.yml` configuration file with credentials necessary to -connect your cluster to your prerequisites. - -- [Configure ingress](#configure-ingress) -- [Configure the object store](#configure-the-object-store) -- [Configure the catalog database](#configure-the-catalog-database) -- [Configure local storage for ingesters](#configure-local-storage-for-ingesters) -- [Configure your OAuth2 provider](#configure-your-oauth2-provider) -- [Configure the size of your cluster](#configure-the-size-of-your-cluster) - -#### Configure ingress - -To configure ingress, provide values for the following fields in your -`myinfluxdb.yml` configuration file: - -- **`spec.package.spec.ingress.hosts`: Cluster hostnames** - - Provide the hostnames that Kubernetes should - use to expose the InfluxDB API endpoints. - For example: `{{< influxdb/host >}}`. - - _You can provide multiple hostnames. The ingress layer accepts incoming - requests for all listed hostnames. This can be useful if you want to have - distinct paths for your internal and external traffic._ - - {{% note %}} - You are responsible for configuring and managing DNS. Options include: - -- Manually managing DNS records -- Using [external-dns](https://github.com/kubernetes-sigs/external-dns) to - synchronize exposed Kubernetes services and ingresses with DNS providers. - {{% /note %}} - -- **`spec.package.spec.ingress.tlsSecretName`: TLS certificate secret name** - - Provide the name of the secret that - [contains your TLS certificate and key](#set-up-cluster-ingress). - The examples in this guide use the name `ingress-tls`. - - _The `tlsSecretName` field is optional. You may want to use it if you already have a TLS certificate for your DNS name._ - - {{< expand-wrapper >}} - {{% expand "Use cert-manager and Let's Encrypt to manage TLS certificates" %}} - -If you instead want to automatically create an [ACME](https://datatracker.ietf.org/doc/html/rfc8555) -certificate (for example, using [Let's Encrypt](https://letsencrypt.org/)), refer -to the [cert-manager documentation](https://cert-manager.io/docs/usage/ingress/) -for more details on how to annotate the `Ingress` resource produced by the -InfluxDB installer operator. The operator lets you to add annotations -(with `kubectl annotate`) and preserves them as it operates on resources. - -{{% note %}} -If you choose to use cert-manager, it's your responsibility to install and configure it. -{{% /note %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -{{% code-callout "ingress-tls|cluster-host\.com" "green" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: -# ... -ingress: - hosts: - - {{< influxdb/host >}} - tlsSecretName: ingress-tls -``` - -{{% /code-callout %}} - -#### Configure the object store - -To connect your InfluxDB cluster to your object store, provide values for the -following fields in your `myinfluxdb.yml` configuration file: - -- `spec.package.spec.objectStore` - - `.endpoint`: Object storage endpoint URL - - `.allowHttp`: _Set to `true` to allow unencrypted HTTP connections_ - - `.accessKey.value`: Object storage access key - - `.secretKey.value`: Object storage secret key - - `.bucket`: Object storage bucket name - - `.region`: Object storage region - -{{% code-placeholders "S3_(URL|ACCESS_KEY|SECRET_KEY|BUCKET_NAME|REGION)" %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - objectStore: - # URL for S3 Compatible object store - endpoint: S3_URL - - # Set to true to allow communication over HTTP (instead of HTTPS) - allowHttp: 'false' - - # S3 Access Key - # This can also be provided as a valueFrom: secretKeyRef: - accessKey: - value: S3_ACCESS_KEY - - # S3 Secret Key - # This can also be provided as a valueFrom: secretKeyRef: - secretKey: - value: S3_SECRET_KEY - - # Bucket that the Parquet files will be stored in - bucket: S3_BUCKET_NAME - - # This value is required for AWS S3, it may or may not be required for other providers. - region: S3_REGION -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`S3_URL`{{% /code-placeholder-key %}}: Object storage endpoint URL -- {{% code-placeholder-key %}}`S3_ACCESS_KEY`{{% /code-placeholder-key %}}: Object storage access key -- {{% code-placeholder-key %}}`S3_SECRET_KEY`{{% /code-placeholder-key %}}: Object storage secret key -- {{% code-placeholder-key %}}`S3_BUCKET_NAME`{{% /code-placeholder-key %}}: Object storage bucket name -- {{% code-placeholder-key %}}`S3_REGION`{{% /code-placeholder-key %}}: Object storage region - ---- - -#### Configure the catalog database - -The InfluxDB catalog is a PostgreSQL-compatible relational database that stores -metadata about your time series data. -To connect your InfluxDB cluster to your PostgreSQL-compatible database, -provide values for the following fields in your `myinfluxdb.yml` configuration file: - -{{% note %}} -We recommend storing sensitive credentials, such as your PostgreSQL-compatible DSN, -as secrets in your Kubernetes cluster. -{{% /note %}} - -- `spec.package.spec.catalog.dsn.valueFrom.secretKeyRef` - - `.name`: Secret name - - `.key`: Key in the secret that contains the DSN - -{{% code-placeholders "SECRET_(NAME|KEY)" %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - catalog: - # A postgresql style DSN that points to a postgresql compatible database. - # postgres://[user[:password]@][netloc][:port][/dbname][?param1=value1&...] - dsn: - valueFrom: - secretKeyRef: - name: SECRET_NAME - key: SECRET_KEY -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`SECRET_NAME`{{% /code-placeholder-key %}}: - Name of the secret containing your PostgreSQL-compatible DSN -- {{% code-placeholder-key %}}`SECRET_KEY`{{% /code-placeholder-key %}}: - Key in the secret that references your PostgreSQL-compatible DSN - ---- - -{{% note %}} - -##### PostgreSQL instances without TLS or SSL - -If your PostgreSQL-compatible instance runs without TLS or SSL, you must include -the `sslmode=disable` parameter in the DSN. For example: - -{{% code-callout "sslmode=disable" %}} - -``` -postgres://username:passw0rd@mydomain:5432/influxdb?sslmode=disable -``` - -{{% /code-callout %}} -{{% /note %}} - -#### Configure local storage for ingesters - -InfluxDB ingesters require local storage to store the Write Ahead Log (WAL) for -incoming data. -To connect your InfluxDB cluster to local storage, provide values for the -following fields in your `myinfluxdb.yml` configuration file: - -- `spec.package.spec.ingesterStorage` - - `.storageClassName`: [Kubernetes storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/). - This differs based on the Kubernetes environment and desired storage characteristics. - - `storage`: Storage size. We recommend a minimum of 2 gibibytes (`2Gi`). - -{{% code-placeholders "STORAGE_(CLASS|SIZE)" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - ingesterStorage: - storageClassName: STORAGE_CLASS - storage: STORAGE_SIZE -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`STORAGE_CLASS`{{% /code-placeholder-key %}}: - [Kubernetes storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) -- {{% code-placeholder-key %}}`STORAGE_SIZE`{{% /code-placeholder-key %}}: - Storage size (example: `2Gi`) - ---- - -#### Configure your OAuth2 provider - -InfluxDB Clustered uses OAuth2 to authenticate administrative access to your cluster. -To connect your InfluxDB cluster to your OAuth2 provide, provide values for the -following fields in your `myinfluxdb.yml` configuration file: - -- `spec.package.spec.admin` - - `identityProvider`: Identity provider name. - _If using Microsoft Entra ID (formerly Azure Active Directory), set the name - to `azure`_. - - `jwksEndpoint`: JWKS endpoint provide by your identity provider. - - `users`: List of OAuth2 users to grant administrative access to your - InfluxDB cluster. IDs are provided by your identity provider. - -Below are examples for **Keycloak**, **Auth0**, and **Microsoft Entra ID**, but -other OAuth2 providers should work as well: - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Keycloak](#) -[Auth0](#) -[Microsoft Entra ID](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - -{{% code-callout "keycloak" "green" %}} -{{% code-placeholders "KEYCLOAK_(HOST|REALM|USER_ID)" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - admin: - identityProvider: keycloak - jwksEndpoint: |- - https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs - users: - # All fields are required but `firstName`, `lastName`, and `email` can be - # arbitrary values. However, `id` must match the user ID provided by Keycloak. - - id: KEYCLOAK_USER_ID - firstName: Marty - lastName: McFly - email: mcfly@influxdata.com -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: - Host and port of your Keycloak server -- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: - Keycloak realm -- {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: - Keycloak user ID to grant InfluxDB administrative access to - ---- - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-callout "auth0" "green" %}} -{{% code-placeholders "AUTH0_(HOST|USER_ID)" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - admin: - identityProvider: auth0 - jwksEndpoint: |- - https://AUTH0_HOST/.well-known/openid-configuration - users: - - AUTH0_USER_ID -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`AUTH0_HOST`{{% /code-placeholder-key %}}: - Host and port of your Auth0 server -- {{% code-placeholder-key %}}`AUTH0_USER_ID`{{% /code-placeholder-key %}}: - Auth0 user ID to grant InfluxDB administrative access to - ---- - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-callout "azure" "green" %}} -{{% code-placeholders "AZURE_(USER|TENANT)_ID" %}} - -```yaml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - admin: - identityProvider: azure - jwksEndpoint: |- - https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys - users: - - AZURE_USER_ID -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}}: - Microsoft Entra tenant ID -- {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: - Microsoft Entra user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ - ---- - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -##### Add users - -Finally, to give users access to use `influxctl`, add the list of users to the -`spec.package.spec.admin.users` field. -See [Manage users](/influxdb/clustered/admin/users/) for more details. - -#### Configure the size of your cluster - -##### Default scale settings - -- **3 ingesters**: - Ensures redundancy on the write path. -- **1 compactor**: - While you can have multiple compactors, it is more efficient to scale the - compactor vertically (assign more CPU and memory) rather than horizontally - (increase the number of compactors). -- **1 querier**: - The optimal number of queriers depends on the number of concurrent queries you are - likely to have and how long they take to execute. - -The default values provide a good starting point for testing. -Once you have your cluster up and running and are looking for scaling recommendations -for your anticipated workload, -please [contact the InfluxData Support team](https://support.influxdata.com). - -##### Customize scale settings - -**To use custom scale settings for your InfluxDB cluster**, edit values for the following fields -in your `myinfluxdb.yml`. If omitted, your cluster uses the default scale settings. - -- `spec.package.spec.resources` - - `ingester.requests` - - `cpu`: CPU resource units to assign to ingesters - - `memory`: Memory resource units to assign to ingesters - - `replicas`: Number of ingester replicas to provision - - `compactor.requests` - - `cpu`: CPU resource units to assign to compactors - - `memory`: Memory resource units to assign to compactors - - `replicas`: Number of compactor replicas to provision - - `querier.requests` - - `cpu`: CPU resource units to assign to queriers - - `memory`: Memory resource units to assign to queriers - - `replicas`: Number of querier replicas to provision - - `router.requests` - - `cpu`: CPU resource units to assign to routers - - `memory`: Memory resource units to assign to routers - - `replicas`: Number of router replicas to provision - -###### Related Kubernetes documentation - -- [CPU resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) -- [Memory resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory) - -{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(CPU|MEMORY|REPLICAS)" %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - # The following settings tune the various pods for their cpu/memory/replicas - # based on workload needs. Only uncomment the specific resources you want - # to change. Anything left commented will use the package default. - resources: - # The ingester handles data being written - ingester: - requests: - cpu: INGESTER_CPU - memory: INGESTER_MEMORY - replicas: INGESTER_REPLICAS # Default is 3 - - # The compactor reorganizes old data to improve query and storage efficiency. - compactor: - requests: - cpu: COMPACTOR_CPU - memory: COMPACTOR_MEMORY - replicas: COMPACTOR_REPLICAS # Default is 1 - - # The querier handles querying data. - querier: - requests: - cpu: QUERIER_CPU - memory: QUERIER_MEMORY - replicas: QUERIER_REPLICAS # Default is 1 - - # The router performs some api routing. - router: - requests: - cpu: ROUTER_CPU - memory: ROUTER_MEMORY - replicas: ROUTER_REPLICAS # Default is 1 -``` - -{{% /code-placeholders %}} - -### Provide a custom certificate authority bundle {note="Optional"} - -InfluxDB attempts to make TLS connections to the services it depends on--notably, -the [Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog) -and the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store). -InfluxDB validates certificates for all connections. - -_If you host dependent services yourself and you use a private or otherwise not -well-known certificate authority to issue certificates to them, -InfluxDB won't recognize the issuer and can't validate the certificates._ -To allow InfluxDB to validate the certificates from your custom CA, -configure the `AppInstance` resource to use a **PEM certificate -bundle** that contains your custom certificate authority chain. - -1. Use `kubectl` to create a config map that contains your PEM-formatted - certificate bundle file. - Your certificate authority administrator should provide you with a - PEM-formatted bundle file. - - {{% note %}} -This PEM bundle file establishes a chain of trust for the -external services that InfluxDB depends on. -It's *not* the certificate that InfluxDB uses to -host its own TLS endpoints. - {{% /note %}} - - In the example, replace `/path/to/private_ca.pem` with the path to your PEM-formatted certificate bundle file: - - - - ```sh - kubectl --namespace influxdb create configmap custom-ca --from-file=certs.pem=/path/to/private_ca.pem - ``` - - {{% note %}} -#### Bundle multiple certificates - -You can append multiple certificates into the same bundle. -This approach helps when you need to include intermediate certificates or explicitly include leaf certificates. - -Include certificates in the bundle in the following order: - -1. Leaf certificates -2. Intermediate certificates required by leaf certificates -3. Root certificate - {{% /note %}} - -2. In `myinfluxdb.yml`, update the `.spec.package.spec.egress` field to refer - to the config map that you generated in the preceding step--for example: - - ```yml - spec: - package: - spec: - egress: - customCertificates: - valueFrom: - configMapKeyRef: - key: ca.pem - name: custom-ca - ``` - -{{< page-nav prev="/influxdb/clustered/install/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/licensing/" nextText="Install your license" >}} diff --git a/content/influxdb/clustered/install/customize-cluster/_index.md b/content/influxdb/clustered/install/customize-cluster/_index.md new file mode 100644 index 000000000..1a9f92e45 --- /dev/null +++ b/content/influxdb/clustered/install/customize-cluster/_index.md @@ -0,0 +1,29 @@ +--- +title: Customize your InfluxDB cluster +description: > + Customize the scale and configuration of your cluster to best suit your workload. +menu: + influxdb_clustered: + name: Customize your cluster + parent: Install InfluxDB Clustered +weight: 102 +cascade: + metadata: + - Install InfluxDB Clustered + - 'Phase 2: Customize your cluster' +metadata: + - Install InfluxDB Clustered + - Phase 2 +related: + - /influxdb/clustered/admin/scale-cluster/ + - /influxdb/clustered/admin/env-vars/ +--- + +This phase of the installation process customizes the scale and configuration of +your InfluxDB cluster to meet the needs of your specific workload. + +## Phase 2 steps + +{{< children type="ordered-list" >}} + +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/test-cluster/" prevText="Test your cluster" next="/influxdb/clustered/install/customize-cluster/scale/" nextText="Customize cluster scale" >}} diff --git a/content/influxdb/clustered/install/customize-cluster/config.md b/content/influxdb/clustered/install/customize-cluster/config.md new file mode 100644 index 000000000..9d5f37cee --- /dev/null +++ b/content/influxdb/clustered/install/customize-cluster/config.md @@ -0,0 +1,148 @@ +--- +title: Customize your cluster configuration +seotitle: Customize the configuration of your InfluxDB cluster +description: > + Customize the configuration of your InfluxDB cluster to best suit your workload. +menu: + influxdb_clustered: + name: Customize cluster configuration + parent: Customize your cluster +weight: 202 +related: + - /influxdb/clustered/admin/env-vars/ +--- + +Use environment variables to customize configuration options for components in +your InfluxDB cluster. + +{{< tabs-wrapper >}} +{{% tabs "medium" %}} +[AppInstance](#) +[Helm](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +In your `AppInstance` resource, configure environment variables for individual +components in the +`spec.package.spec.components..template.containers.iox.env` property. +The following InfluxDB Clustered components are configurable: + +- `ingester` +- `querier` +- `router` +- `compactor` +- `garbage-collector` + +In the `env` property, structure each environment variable as a key-value pair +where the key is the environment variable name and the value is the environment +variable value (string-formatted)--for example: + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + # ... + spec: + components: + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '4500' + INFLUXDB_IOX_MAX_HTTP_REQUEST_SIZE: '52428800' +``` + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +In your `values.yaml`, configure environment variables for individual components +in the `components..template.containers.iox.env` property. +The following InfluxDB Clustered components are configurable: + +- `ingester` +- `querier` +- `router` +- `compactor` +- `garbage-collector` + +In the `env` property, structure each environment variable as a key-value pair +where the key is the environment variable name and the value is the environment +variable value (string-formatted)--for example: + +```yaml +components: + router: + template: + containers: + iox: + env: + INFLUXDB_IOX_MAX_HTTP_REQUESTS: '4500' + INFLUXDB_IOX_MAX_HTTP_REQUEST_SIZE: '52428800' +``` + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +For more information, see +[Manage environment variables in your InfluxDB Cluster](/influxdb/clustered/admin/env-vars/). + +{{% note %}} +#### Configurable settings + +For information about what settings are configurable and their associated +environment variables, [contact InfluxData Support](https://support.influxdata.com). +{{% /note %}} + + + +## Apply the changes to your cluster + +Use `kubectl` or `helm` (if using the InfluxDB Clustered Helm chart), to apply +the changes to your cluster: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[kubectl](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{< page-nav prev="content/influxdb/clustered/install/customize-cluster/scale/" prevText="Customize cluster scale" next="/influxdb/clustered/install/optimize-cluster/" nextText="Phase 3: Optimize your cluster" >}} diff --git a/content/influxdb/clustered/install/customize-cluster/scale.md b/content/influxdb/clustered/install/customize-cluster/scale.md new file mode 100644 index 000000000..d745ca7ae --- /dev/null +++ b/content/influxdb/clustered/install/customize-cluster/scale.md @@ -0,0 +1,343 @@ +--- +title: Customize your cluster scale +seotitle: Customize the scale of your InfluxDB cluster +description: > + Customize the scale of your cluster to best suit your workload. +menu: + influxdb_clustered: + name: Customize cluster scale + parent: Customize your cluster +weight: 201 +related: + - /influxdb/clustered/admin/scale-cluster/ +--- + +InfluxDB Clustered lets you scale each component in your cluster individually, +so you can customize your cluster's scale to address the specific the specific +needs of your workload. +For example, if you have a heavy write workload, but not a heavy query workload, +you can scale your Router and Ingester both [vertically](/influxdb/clustered/admin/scale-cluster/#vertical-scaling) +and [horizontally](/influxdb/clustered/admin/scale-cluster/#horizontal-scaling) +to increase your write throughput and latency. + +## Default scale settings + +- **1 router**: + Additional routers increase your cluster's ability to handle concurrent write + requests. +- **3 ingesters**: + Ensures redundancy on the write path. +- **1 querier**: + The optimal number of queriers depends on the number of concurrent queries you + are likely to have and how long they take to execute. +- **1 compactor**: + While you can have multiple compactors, it is more efficient to scale the + compactor vertically (assign more CPU and memory) rather than horizontally + (increase the number of compactors). +- **1 garbage collector**: + The garbage collector is a light-weight process that only needs to be scaled + vertically when you observe high resource usage by the garbage collector. + _The garbage collector cannot be scaled horizontally._ + +The default values provide a good starting point for testing. +Once you have your cluster up and running and are looking for scaling +recommendations for your anticipated workload, please +[contact the InfluxData Support team](https://support.influxdata.com) to help you +identify appropriate scale settings based on +your anticipated workload. + +## Customize scale settings + +Your `AppInstance` resource controls the scale of components in your InfluxDB +cluster. You can edit the `AppInstance` resource directly or, if using the +[InfluxDB Clustered Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-clustered) +to manage your deployment, you can edit resource settings in your `values.yaml`. + +{{% note %}} +_For specific scaling recommendations and guidelines, see +[Scale your cluster](/influxdb/clustered/admin/scale-cluster/)._ +{{% /note %}} + +With Kubernetes, you can define the minimum resources and the resource limits for each component. + +{{< tabs-wrapper >}} +{{% tabs "medium" %}} +[AppInstance](#) +[Helm](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +**To use custom scale settings for your InfluxDB cluster**, edit values for the +following fields in your `myinfluxdb.yml`. +If omitted, your cluster uses the default scale settings. + +- `spec.package.spec.resources` + - `ingester` + - `requests` + - `cpu`: Minimum CPU resource units to assign to ingesters + - `memory`: Minimum memory resource units to assign to ingesters + - `replicas`: Number of ingester replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to ingesters + - `memory`: Maximum memory resource units to assign to ingesters + - `compactor` + - `requests` + - `cpu`: Minimum CPU resource units to assign to compactors + - `memory`: Minimum memory resource units to assign to compactors + - `replicas`: Number of compactor replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to compactors + - `memory`: Maximum memory resource units to assign to compactors + - `querier` + - `requests` + - `cpu`: Minimum CPU resource units to assign to queriers + - `memory`: Minimum memory resource units to assign to queriers + - `replicas`: Number of querier replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to queriers + - `memory`: Maximum memory resource units to assign to queriers + - `router` + - `requests` + - `cpu`: Minimum CPU resource units to assign to routers + - `memory`: Minimum memory resource units to assign to routers + - `replicas`: Number of router replicas to provision + - `limits` + - `cpu`: Maximum CPU Resource units to assign to routers + - `memory`: Maximum memory resource units to assign to routers + - `garbage-collector` + - `requests` + - `cpu`: Minimum CPU resource units to assign to the garbage collector + - `memory`: Minimum memory resource units to assign to the garbage collector + - `limits` + - `cpu`: Maximum CPU Resource units to assign to the garbage collector + - `memory`: Maximum memory resource units to assign to the garbage collector + - `prometheus` + - `requests` + - `cpu`: Minimum CPU resource units to assign to prometheus + - `memory`: Minimum memory resource units to assign to prometheus + - `limits` + - `cpu`: Maximum CPU Resource units to assign to prometheus + - `memory`: Maximum memory resource units to assign to prometheus + +{{< expand-wrapper >}} +{{% expand "View example `AppInstance` with resource requests and limits" %}} + +{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER|GC)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + # The following settings tune the various pods for their cpu/memory/replicas + # based on workload needs. Only uncomment the specific resources you want + # to change. Anything left commented will use the package default. + resources: + ingester: + requests: + cpu: INGESTER_CPU_MIN + memory: INGESTER_MEMORY_MIN + replicas: INGESTER_REPLICAS # Default is 3 + limits: + cpu: INGESTER_CPU_MAX + memory: INGESTER_MEMORY_MAX + compactor: + requests: + cpu: COMPACTOR_CPU_MIN + memory: COMPACTOR_MEMORY_MIN + replicas: COMPACTOR_REPLICAS # Default is 1 + limits: + cpu: COMPACTOR_CPU_MAX + memory: COMPACTOR_MEMORY_MAX + querier: + requests: + cpu: QUERIER_CPU_MIN + memory: QUERIER_MEMORY_MIN + replicas: QUERIER_REPLICAS # Default is 1 + limits: + cpu: QUERIER_CPU_MAX + memory: QUERIER_MEMORY_MAX + router: + requests: + cpu: ROUTER_CPU_MIN + memory: ROUTER_MEMORY_MIN + replicas: ROUTER_REPLICAS # Default is 1 + limits: + cpu: ROUTER_CPU_MAX + memory: ROUTER_MEMORY_MAX + garbage-collector: + requests: + cpu: GC_CPU_MIN + memory: GC_MEMORY_MIN + limits: + cpu: GC_CPU_MAX + memory: GC_MEMORY_MAX +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +**To use custom scale settings for your InfluxDB cluster**, modify the following fields +in your `values.yaml`. If omitted, your cluster will use the default scale settings. + +- `resources` + - `ingester` + - `requests` + - `cpu`: Minimum CPU resource units to assign to ingesters + - `memory`: Minimum memory resource units to assign to ingesters + - `replicas`: Number of ingester replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to ingesters + - `memory`: Maximum memory resource units to assign to ingesters + - `compactor` + - `requests` + - `cpu`: Minimum CPU resource units to assign to compactors + - `memory`: Minimum memory resource units to assign to compactors + - `replicas`: Number of compactor replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to compactors + - `memory`: Maximum memory resource units to assign to compactors + - `querier` + - `requests` + - `cpu`: Minimum CPU resource units to assign to queriers + - `memory`: Minimum memory resource units to assign to queriers + - `replicas`: Number of querier replicas to provision + - `limits` + - `cpu`: Maximum CPU resource units to assign to queriers + - `memory`: Maximum memory resource units to assign to queriers + - `router` + - `requests` + - `cpu`: Minimum CPU resource units to assign to routers + - `memory`: Minimum memory resource units to assign to routers + - `replicas`: Number of router replicas to provision + - `limits` + - `cpu`: Maximum CPU Resource units to assign to routers + - `memory`: Maximum memory resource units to assign to routers + - `garbage-collector` + - `requests` + - `cpu`: Minimum CPU resource units to assign to the garbage collector + - `memory`: Minimum memory resource units to assign to the garbage collector + - `limits` + - `cpu`: Maximum CPU Resource units to assign to the garbage collector + - `memory`: Maximum memory resource units to assign to the garbage collector + +{{< expand-wrapper >}} +{{% expand "View example `values.yaml` with resource requests and limits" %}} + +{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER|GC)_(CPU_(MAX|MIN)|MEMORY_(MAX|MIN)|REPLICAS)" %}} + +```yml +# The following settings tune the various pods for their cpu/memory/replicas +# based on workload needs. Only uncomment the specific resources you want +# to change. Anything left commented will use the package default. +resources: + # The ingester handles data being written + ingester: + requests: + cpu: INGESTER_CPU_MIN + memory: INGESTER_MEMORY_MIN + replicas: INGESTER_REPLICAS # Default is 3 + limits: + cpu: INGESTER_CPU_MAX + memory: INGESTER_MEMORY_MAX + + # The compactor reorganizes old data to improve query and storage efficiency. + compactor: + requests: + cpu: COMPACTOR_CPU_MIN + memory: COMPACTOR_MEMORY_MIN + replicas: COMPACTOR_REPLICAS # Default is 1 + limits: + cpu: COMPACTOR_CPU_MAX + memory: COMPACTOR_MEMORY_MAX + + # The querier handles querying data. + querier: + requests: + cpu: QUERIER_CPU_MIN + memory: QUERIER_MEMORY_MIN + replicas: QUERIER_REPLICAS # Default is 1 + limits: + cpu: QUERIER_CPU_MAX + memory: QUERIER_MEMORY_MAX + + # The router performs some API routing. + router: + requests: + cpu: ROUTER_CPU_MIN + memory: ROUTER_MEMORY_MIN + replicas: ROUTER_REPLICAS # Default is 1 + limits: + cpu: ROUTER_CPU_MAX + memory: ROUTER_MEMORY_MAX + + # The garbage collector evicts obsolete data and files + garbage-collector: + requests: + cpu: GC_CPU_MIN + memory: GC_MEMORY_MIN + limits: + cpu: GC_CPU_MAX + memory: GC_MEMORY_MAX +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +##### Related Kubernetes documentation + +- [CPU resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) +- [Memory resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory) + +## Apply the changes to your cluster + +Use `kubectl` or `helm` (if using the InfluxDB Clustered Helm chart), to apply +the changes to your cluster: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[kubectl](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{< page-nav prev="content/influxdb/clustered/install/customize-cluster/" prevText="Customize your cluster" next="/influxdb/clustered/install/customize-cluster/config/" nextText="Customize cluster configuration" >}} diff --git a/content/influxdb/clustered/install/licensing.md b/content/influxdb/clustered/install/licensing.md deleted file mode 100644 index df245008f..000000000 --- a/content/influxdb/clustered/install/licensing.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: Install your InfluxDB Clustered license -description: > - Install your InfluxDB Clustered license to authorize the use of the InfluxDB - Clustered software. -menu: - influxdb_clustered: - name: Install your license - parent: Install InfluxDB Clustered -weight: 135 -influxdb/clustered/tags: [licensing] -related: - - /influxdb/clustered/admin/licensing/ - - /influxdb/clustered/admin/upgrade/ ---- - -Install your InfluxDB Clustered license in your cluster to authorize the use -of the InfluxDB Clustered software. - -{{% note %}} -#### License enforcement is currently an opt-in feature - -In currently available versions of InfluxDB Clustered, license enforcement is an -opt-in feature that allows InfluxData to introduce license enforcement to -customers, and allows customers to deactivate the feature if issues arise. -In the future, all releases of InfluxDB Clustered will require customers to -configure an active license before they can use the product. - -To opt into license enforcement, include the `useLicensedBinaries` feature flag -in your `AppInstance` resource _([See the example below](#enable-feature-flag))_. -To deactivate license enforcement, remove the `useLicensedBinaries` feature flag. -{{% /note %}} - -## Install your InfluxDB license - -1. If you haven't already, - [request an InfluxDB Clustered license](https://influxdata.com/contact-sales). -2. InfluxData provides you with a `license.yml` file that encapsulates your - license token as a custom Kubernetes resource. -3. Use `kubectl` to apply and create the `License` resource in your InfluxDB - namespace: - - - - ```sh - kubectl apply --filename license.yml --namespace influxdb - ``` - -4. - Update your `AppInstance` resource to activate the `useLicensedBinaries` feature flag: - - - If configuring the `AppInstance` resource directly, add the - `useLicensedBinaries` entry to the `.spec.package.spec.featureFlags` - property. - - If using the [InfluxDB Clustered Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-clustered), add the `useLicensedBinaries` entry to the - `featureFlags` property in your `values.yaml`. - - {{< code-tabs-wrapper >}} -{{% code-tabs %}} -[AppInstance](#) -[Helm](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - spec: - featureFlags: - - useLicensedBinaries -``` - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -```yml -# values.yaml - -featureFlags: - - useLicensedBinaries -``` - -{{% /code-tab-content %}} - {{< /code-tabs-wrapper >}} - -InfluxDB Clustered detects the `License` resource and extracts the credentials -into a secret required by InfluxDB Clustered Kubernetes pods. -Pods validate the license secret both at startup and periodically (roughly once -per hour) while running. - -## Upgrade from a non-licensed release - -If you are currently using a non-licensed preview release of InfluxDB Clustered -and want to upgrade to a licensed release, do the following: - -1. [Install an InfluxDB license](#install-your-influxdb-license) -2. If you [use the `AppInstance` resource configuration](/influxdb/clustered/install/configure-cluster/directly/) to configure your cluster, in your `myinfluxdb.yml`, - update the package version defined in `spec.package.image` to use a licensed - release. - - If using the InfluxDB Clustered Helm chart, update the `image.tag` property - in your `values.yaml`to use a licensed release. - - {{% warn %}} -#### Upgrade to checkpoint releases first - -When upgrading InfluxDB Clustered, always upgrade to each -[checkpoint release](/influxdb/clustered/admin/upgrade/#checkpoint-releases) -first, before proceeding to newer versions. -Upgrading past a checkpoint release without first upgrading to it may result in -corrupt or lost data. - {{% /warn %}} - -{{% code-placeholders "PACKAGE_VERSION" %}} - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[AppInstance](#) -[Helm](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - -```yml -apiVersion: kubecfg.dev/v1alpha1 -kind: AppInstance -# ... -spec: - package: - # ... - image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION -``` - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -```yml -# values.yaml - -image: - tag: PACKAGE_VERSION -``` - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -{{% /code-placeholders %}} - -Replace {{% code-placeholder-key %}}`PACKAGE_VERSION`{{% /code-placeholder-key %}} with -the version number to upgrade to. - -## Troubleshoot licensing - -After you have activated licensing, use the following signals to verify licensing -and troubleshoot issues with your {{< product-name omit="Clustered" >}} -cluster. - -In your commands, replace the following: - -- {{% code-placeholder-key %}}`NAMESPACE`{{% /code-placeholder-key %}}: - your [InfluxDB namespace](/influxdb/clustered/install/configure-cluster/#create-a-namespace-for-influxdb) -- {{% code-placeholder-key %}}`POD_NAME`{{% /code-placeholder-key %}}: - your [InfluxDB Kubernetes pod](/influxdb/clustered/install/deploy/#inspect-cluster-pods) - -### Verify database components - -After you [install your license](#install-your-influxdb-license), -run the following command to check that database pods start up and are in the -`Running` state: - - - -{{% code-placeholders "NAMESPACE" %}} - -```sh -kubectl get pods -l app=iox --namespace NAMESPACE -``` - -{{% /code-placeholders %}} - -If a `Pod` fails to start, run the following command to view pod information: - - - -{{% code-placeholders "POD_NAME|NAMESPACE" %}} - -```sh -kubectl describe pod POD_NAME --namespace NAMESPACE -``` - -{{% /code-placeholders %}} - -### Verify the `Secret` exists - -Run the following command to verify that the licensing activation created a -`iox-license` secret: - - - -{{% code-placeholders "NAMESPACE" %}} - -```sh -kubectl get secret iox-license --namespace NAMESPACE -``` - -If the secret doesn't exist, -[view `license-controller` logs](#view-license-controller-logs) for -more information or errors. - -{{% /code-placeholders %}} - -### View `license controller` logs - -The `license controller` component creates a `Secret` named `iox-license` from your -`License`. - -To view `license controller` logs for troubleshooting, run the following -command: - - - -{{% code-placeholders "NAMESPACE" %}} - -```sh -kubectl logs deployment/license-controller --namespace NAMESPACE -``` - -{{% /code-placeholders %}} - - -{{< page-nav prev="/influxdb/clustered/install/configure-cluster/" prevText="Configure your cluster" next="/influxdb/clustered/install/deploy/" nextText="Deploy your cluster" keepTab=true >}} diff --git a/content/influxdb/clustered/install/optimize-cluster/_index.md b/content/influxdb/clustered/install/optimize-cluster/_index.md new file mode 100644 index 000000000..1011202a8 --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/_index.md @@ -0,0 +1,46 @@ +--- +title: Optimize your InfluxDB cluster +description: > + Test your cluster with a production-like workload and optimize your cluster + for your workload. +menu: + influxdb_clustered: + name: Optimize your cluster + parent: Install InfluxDB Clustered +weight: 103 +cascade: + metadata: + - Install InfluxDB Clustered + - 'Phase 3: Optimize your cluster' +metadata: + - Install InfluxDB Clustered + - Phase 3 +--- + +The goal of this phase of the installation process is to simulate a +production-like workload against your InfluxDB cluster and make changes to +optimize your cluster for your workload. + +{{% note %}} +Depending on your requirements, this phase is likely to take the longest of all +the installation phases. +{{% /note %}} + +## Identify performance requirements {note="Recommended"} + +Before beginning this process, we recommend identifying performance requirements +and goals--for example: + +- Writes per second +- Query concurrency +- Query response time + +This gives specific metrics to test for and make adjustments towards. +Consult with [InfluxData support](https://support.influxdata.com) as you make +changes to meet these requirements and goals. + +## Phase 3 process + +{{< children type="ordered-list" >}} + +{{< page-nav prev="/influxdb/clustered/install/customize-cluster/config/" prevText="Customize cluster configuration" next="/influxdb/clustered/install/optimize-cluster/design-schema/" nextText="Design your schema" >}} diff --git a/content/influxdb/clustered/install/optimize-cluster/design-schema.md b/content/influxdb/clustered/install/optimize-cluster/design-schema.md new file mode 100644 index 000000000..89c9ecf01 --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/design-schema.md @@ -0,0 +1,87 @@ +--- +title: Design your schema +description: > + Use schema design guidelines to improve write and query performance in your + InfluxDB cluster. +menu: + influxdb_clustered: + name: Design your schema + parent: Optimize your cluster +weight: 201 +related: + - /influxdb/clustered/write-data/best-practices/schema-design/ +--- + +Schema design can have a significant impact on both write and query performance +in your InfluxDB cluster. The items below cover high-level considerations and +recommendation. For detailed recommendations, see +[Schema design recommendations](/influxdb/clustered/write-data/best-practices/schema-design/). + +## Understand the difference between tags and fields + +In the [InfluxDB data structure](/influxdb/clustered/write-data/best-practices/schema-design/#influxdb-data-structure), +there are three main "categories" of information--timestamps, tags, and fields. +Understanding the difference between what should be a tag and what should be a +field is important when designing your schema. + +Use the following guidelines to determine what should be tags versus fields: + +- Use tags to store metadata that provides information about the source or + context of the data. +- Use fields to store measured values. +- Field values typically change over time. Tag values do not. +- Tag values can only be strings. +- Field values can be any of the following data types: + - Integer + - Unsigned integer + - Float + - String + - Boolean + +For more information, see [Tags versus fields](/influxdb/clustered/write-data/best-practices/schema-design/#tags-versus-fields). + +## Schema restrictions + +InfluxDB enforces the following schema restrictions: + +- You cannot use the same name for a tag and a field in the same table. +- By default, a table can have up to 250 columns. + +For more information, see [InfluxDB schema restrictions](/influxdb/clustered/write-data/best-practices/schema-design/#schema-restrictions). + +## Design for performance + +The following guidelines help to ensure write and query performance: + +{{% caption %}} +Follow the links below for more detailed information. +{{% /caption %}} + +- [Avoid wide schemas](/influxdb/clustered/write-data/best-practices/schema-design/#avoid-wide-schemas): + A wide schema is one with a large number of columns (tags and fields). +- [Avoid sparse schemas](/influxdb/clustered/write-data/best-practices/schema-design/#avoid-sparse-schemas): + A sparse schema is one where, for many rows, columns contain null values. +- [Keep table schemas homogenous](/influxdb/clustered/write-data/best-practices/schema-design/#table-schemas-should-be-homogenous): + A homogenous table schema is one where every row has values for all tags and fields. +- [Use the best data type for your data](/influxdb/clustered/write-data/best-practices/schema-design/#use-the-best-data-type-for-your-data): + Write integers as integers, decimals as floats, and booleans as booleans. + Queries against a field that stores integers outperforms a query against string data. + +## Design for query simplicity + +The following guidelines help to ensure that, when querying data, the schema +makes it easy to write queries: + +{{% caption %}} +Follow the links below for more detailed information. +{{% /caption %}} + +- [Keep table names, tags, and fields simple](/influxdb/clustered/write-data/best-practices/schema-design/#keep-table-names-tags-and-fields-simple): + Use one tag or one field for each data attribute. + If your source data contains multiple data attributes in a single parameter, + split each attribute into its own tag or field. +- [Avoid keywords and special characters](/influxdb/clustered/write-data/best-practices/schema-design/#avoid-keywords-and-special-characters): + Reserved keywords or special characters in table names, tag keys, and field + keys makes writing queries more complex. + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/" prevText="Optimize your cluster" next="/influxdb/clustered/install/optimize-cluster/write-methods/" nextText="Identify write methods" >}} \ No newline at end of file diff --git a/content/influxdb/clustered/install/optimize-cluster/optimize-querying.md b/content/influxdb/clustered/install/optimize-cluster/optimize-querying.md new file mode 100644 index 000000000..08efb3156 --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/optimize-querying.md @@ -0,0 +1,93 @@ +--- +title: Optimize querying +seotitle: Optimize querying in your InfluxDB cluster +description: > + Define your typical query patterns and employ optimizations to ensure query + performance. +menu: + influxdb_clustered: + name: Optimize querying + parent: Optimize your cluster +weight: 204 +related: + - /influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/ + - /influxdb/clustered/admin/custom-partitions/ + - /influxdb/clustered/query-data/troubleshoot-and-optimize/troubleshoot/ + - /influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/ + - /influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues/ +--- + +With data written to your cluster, you can now begin to define and test your +typical query patterns and employ optimizations to ensure query performance. + +## Define your query patterns + +Understanding your typical query patterns helps prioritize optimizations to meet your query performance requirements. + +For example, consider the following questions: + +- **Do you typically query data by a specific tag values?** + [Apply custom partitioning](/influxdb/clustered/admin/custom-partitions/) to + your target database or table to partition by those tags. Partitioning by + commonly queried tags helps InfluxDB to quickly identify where the relevant + data is in storage and improves query performance. +- **Do you query tables with [wide schemas](/influxdb/clustered/write-data/best-practices/schema-design/#avoid-wide-schemas)?** + Avoid using wildcards (`*`) in your `SELECT` statement. Select specific + columns you want returned in your query results. The more columns queried, the + less performant the query. +- **Do you query large, historical time ranges?** + Use [time-based aggregation methods to downsample your data](/influxdb/clustered/query-data/sql/aggregate-select/#downsample-data-by-applying-interval-based-aggregates) and return aggregate + values per interval of time instead of all the data. + +## Decide on your query language + +InfluxDB Clustered supports both [SQL](/influxdb/clustered/reference/sql/) and +[InfluxQL](/influxdb/clustered/reference/influxql/)--a SQL-like query language +designed for InfluxDB v1 and specifically querying time series data. + +### SQL + +The InfluxDB SQL implementation is a full-featured SQL query engine powered by +[Apache DataFusion](https://datafusion.apache.org/). It benefits from a robust +upstream community that is constantly improving the features and performance +of the engine. Some time series-specific queries (such as time-based aggregates) +are more verbose in SQL than in InfluxQL, but they are still possible. + +### InfluxQL + +InfluxQL is designed specifically for time series data and simplifies many +time series-related operations like aggregating based on time, technical +analysis, and forecasting. It isn't as full-featured as SQL and requires some +understanding of the InfluxDB v1 data model. + +## Optimize your queries + +View the [query optimization and troubleshooting documentation](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/) +for guidance and information on how to troubleshoot and optimize queries that do +not perform as expected. + +### Analyze queries + +Both SQL and InfluxQL support the `EXPLAIN` and `EXPLAIN ANALYZE` statements +that return detailed information about your query's planning and execution. +This can provide insight into possible optimizations you can make for a specific +query. For more information, see +[Analyze a query plan](/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/). + +## Custom-partition data + +InfluxDB Clustered lets you define how data is stored to ensure queries are +performant. [Custom partitioning](/influxdb/clustered/admin/custom-partitions/) +lets you define how InfluxDB partitions data and can be used to structure your +data so it's easier for InfluxDB to identify where the data you typically query +is in storage. For more information, see +[Manage data partitioning](/influxdb/clustered/admin/custom-partitions/). + +## Report query performance issues + +If you've followed steps to [optimize and +troubleshoot a query](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/), +but it still doesn't meet performance requirements, +see how to [report query performance issues](/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues/). + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/simulate-load/" prevText="Simulate load" next="/influxdb/clustered/install/secure-cluster/" nextText="Phase 4: Secure your cluster" >}} diff --git a/content/influxdb/clustered/install/optimize-cluster/simulate-load.md b/content/influxdb/clustered/install/optimize-cluster/simulate-load.md new file mode 100644 index 000000000..bb3fb19d3 --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/simulate-load.md @@ -0,0 +1,36 @@ +--- +title: Simulate a production-like load +description: > + Simulate a production-like load that writes data to your InfluxDB cluster. +menu: + influxdb_clustered: + name: Simulate load + parent: Optimize your cluster +weight: 203 +--- + +With your schema defined you can begin to simulate a production-like load that +writes data to your InfluxDB cluster. This process helps to ensure that your +schema works as designed and that both your cluster's scale and configuration +are able to meet your cluster's write requirements. + +{{% warn %}} +We do not recommend writing production data to your InfluxDB cluster at this point. +{{% /warn %}} + +## Load testing tools + +Contact your [InfluxData sales representative](https://influxdata.com/contact-sales) +for information about load testing tools. +These tools can simulate your schema and +desired write concurrency to ensure your cluster performs under production-like load. + + + +## Use your own tools + +You can also build and use your own tools to load test a production-like workload. +Use Telegraf, client libraries, or the InfluxDB API to build out tests that +simulate writes to your cluster. + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/write-methods/" prevText="Identify write methods" next="/influxdb/clustered/install/optimize-cluster/optimize-querying/" nextText="Optimize querying" >}} diff --git a/content/influxdb/clustered/install/optimize-cluster/write-methods.md b/content/influxdb/clustered/install/optimize-cluster/write-methods.md new file mode 100644 index 000000000..3120c0a3b --- /dev/null +++ b/content/influxdb/clustered/install/optimize-cluster/write-methods.md @@ -0,0 +1,125 @@ +--- +title: Identify write methods +seotitle: Identify methods for writing to your InfluxDB cluster +description: + Identify the most appropriate and useful tools and methods for writing data to + your InfluxDB cluster. +menu: + influxdb_clustered: + name: Identify write methods + parent: Optimize your cluster +weight: 202 +related: + - /telegraf/v1/ + - /telegraf/v1/plugins/ + - /influxdb/clustered/write-data/use-telegraf/configure/ + - /influxdb/clustered/reference/client-libraries/ + - /influxdb/clustered/write-data/best-practices/optimize-writes/ +--- + +Many different tools are available for writing data into your InfluxDB cluster. +Based on your use case, you should identify the most appropriate tools and +methods to use. Below is a summary of some of the tools that are available +(this list is not exhaustive). + +## Telegraf + +[Telegraf](/telegraf/v1/) is a data collection agent that collects data from +various sources, parses the data into +[line protocol](/influxdb/clustered/reference/syntax/line-protocol/), and then +writes the data to InfluxDB. +Telegraf is plugin-based and provides hundreds of +[plugins that collect, aggregate, process, and write data](/telegraf/v1/plugins/). + +If you need to collect data from well-established systems and technologies, +Telegraf likely already supports a plugin for collecting that data. +Some of the most common use cases are: + +- Monitoring system metrics (memory, CPU, disk usage, etc.) +- Monitoring Docker containers +- Monitoring network devices via SNMP +- Collecting data from a Kafka queue +- Collecting data from an MQTT broker +- Collecting data from HTTP endpoints +- Scraping data from a Prometheus exporter +- Parsing logs + +For more information about using Telegraf with InfluxDB Clustered, see +[Use Telegraf to write data to InfluxDB Clustered](/influxdb/clustered/write-data/use-telegraf/configure/). + +## InfluxDB client libraries + +[InfluxDB client libraries](/influxdb/clustered/reference/client-libraries/) are +language-specific packages that integrate with InfluxDB APIs. They simplify +integrating InfluxDB with your own custom application and standardize +interactions between your application and your InfluxDB cluster. +With client libraries, you can collect and write whatever time series data is +useful for your application. + +InfluxDB Clustered includes backwards compatible write APIs, so if you are +currently using an InfluxDB v1 or v2 client library, you can continue to use the +same client library to write data to your cluster. + +{{< expand-wrapper >}} +{{% expand "View available InfluxDB client libraries" %}} + + + +- [InfluxDB v3 client libraries](/influxdb/clustered/reference/client-libraries/v3/) + - [C# .NET](/influxdb/clustered/reference/client-libraries/v3/csharp/) + - [Go](/influxdb/clustered/reference/client-libraries/v3/go/) + - [Java](/influxdb/clustered/reference/client-libraries/v3/java/) + - [JavaScript](/influxdb/clustered/reference/client-libraries/v3/javascript/) + - [Python](/influxdb/clustered/reference/client-libraries/v3/python/) +- [InfluxDB v2 client libraries](/influxdb/clustered/reference/client-libraries/v2/) + - [Arduino](/influxdb/clustered/reference/client-libraries/v2/arduino/) + - [C#](/influxdb/clustered/reference/client-libraries/v2/csharp/) + - [Dart](/influxdb/clustered/reference/client-libraries/v2/dart/) + - [Go](/influxdb/clustered/reference/client-libraries/v2/go/) + - [Java](/influxdb/clustered/reference/client-libraries/v2/java/) + - [JavaScript](/influxdb/clustered/reference/client-libraries/v2/javascript/) + - [Kotlin](/influxdb/clustered/reference/client-libraries/v2/kotlin/) + - [PHP](/influxdb/clustered/reference/client-libraries/v2/php/) + - [Python](/influxdb/clustered/reference/client-libraries/v2/python/) + - [R](/influxdb/clustered/reference/client-libraries/v2/r/) + - [Ruby](/influxdb/clustered/reference/client-libraries/v2/ruby/) + - [Scala](/influxdb/clustered/reference/client-libraries/v2/scala/) + - [Swift](/influxdb/clustered/reference/client-libraries/v2/swift/) +- [InfluxDB v1 client libraries](/influxdb/clustered/reference/client-libraries/v1/) + +{{% /expand %}} +{{< /expand-wrapper >}} + +## InfluxDB HTTP write APIs + +InfluxDB Clustered provides backwards-compatible HTTP write APIs for writing +data to your cluster. The [InfluxDB client libraries](#influxdb-client-libraries) +use these APIs, but if you choose not to use a client library, you can integrate +directly with the API. Because these APIs are backwards compatible, you can use +existing InfluxDB API integrations with your InfluxDB cluster. + +- [InfluxDB v2 API for InfluxDB Clustered](/influxdb/clustered/api/v2/) +- [InfluxDB v1 API for InfluxDB Clustered](/influxdb/clustered/api/v1/) + +## Write optimizations + +As you decide on and integrate tooling to write data to your InfluxDB cluster, +there are things you can do to ensure your write pipeline is as performant as +possible. The list below provides links to more detailed descriptions of these +optimizations in the [Optimize writes](/influxdb/clustered/write-data/best-practices/optimize-writes/) +documentation: + +- [Batch writes](/influxdb/clustered/write-data/best-practices/optimize-writes/#batch-writes) +- [Sort tags by key](/influxdb/clustered/write-data/best-practices/optimize-writes/#sort-tags-by-key) +- [Use the coarsest time precision possible](/influxdb/clustered/write-data/best-practices/optimize-writes/#use-the-coarsest-time-precision-possible) +- [Use gzip compression](/influxdb/clustered/write-data/best-practices/optimize-writes/#use-gzip-compression) +- [Synchronize hosts with NTP](/influxdb/clustered/write-data/best-practices/optimize-writes/#synchronize-hosts-with-ntp) +- [Write multiple data points in one request](/influxdb/clustered/write-data/best-practices/optimize-writes/#write-multiple-data-points-in-one-request) +- [Pre-process data before writing](/influxdb/clustered/write-data/best-practices/optimize-writes/#pre-process-data-before-writing) + +{{% note %}} +[Telegraf](#telegraf) and [InfluxDB client libraries](#influxdb-client-libraries) +leverage many of these optimizations by default. +{{% /note %}} + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/design-schema" prevText="Design your schema" next="/influxdb/clustered/install/optimize-cluster/simulate-load/" nextText="Simulate load" >}} diff --git a/content/influxdb/clustered/install/prerequisites.md b/content/influxdb/clustered/install/prerequisites.md deleted file mode 100644 index 5cd4b0a9c..000000000 --- a/content/influxdb/clustered/install/prerequisites.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Set up prerequisites -description: > - InfluxDB Clustered requires prerequisites such as a Kubernetes cluster, object storage, - a PostgreSQL-compatitble database and more. Learn how to set up and configure the - necessary prerequisites. -menu: - influxdb_clustered: - name: Prerequisites - parent: Install InfluxDB Clustered -weight: 110 ---- - -InfluxDB Clustered requires the following prerequisites: - -- **Kubernetes cluster**: version 1.25 or higher -- **Object storage**: AWS S3 or S3-compatible storage used to store the InfluxDB Parquet files. - - {{% note %}} -We **strongly** recommend that you enable object versioning in your object store. - {{% /note %}} - -- **PostgreSQL-compatible database** _(AWS Aurora, hosted Postgres, etc.)_: - Used to store the InfluxDB catalog - - Supported PostgreSQL versions: **13.8–14.6** - - Ensure that the PostgreSQL-compatible instance is dedicated exclusively to InfluxDB. This avoids conflicts and prevents issues caused by shared usage with other applications. - -- **OAuth 2.0 provider**: - - Must support [Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow) - - Tested and supported providers: - - [Microsoft Entra ID _(formerly Azure Active Directory)_](https://www.microsoft.com/en-us/security/business/microsoft-entra) - - [Keycloak](https://www.keycloak.org/) - - [Auth0](https://auth0.com/) -- **TLS certificate**: for ingress to the cluster - -## Set up a Kubernetes cluster - -1. Deploy a Kubernetes cluster. Kubernetes v1.25 or later is required. -2. Create two namespaces--`influxdb` and `kubit`. -3. Install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) in the cluster and a mechanism to obtain a - valid TLS certificate (for example: [cert-manager](https://cert-manager.io/) - or provide the certificate PEM manually out of band). - To use the InfluxDB-specific ingress controller, install [Ingress NGINX](https://github.com/kubernetes/ingress-nginx). -4. Ensure your Kubernetes cluster can access the InfluxDB container registry, - or, if running in an air-gapped environment, a local container registry to - which you can copy the InfluxDB images. - -{{% note %}} -It is strongly recommended that you run the PostgreSQL-compatible database -(that stores the InfluxDB Catalog) and the Object Store (that stores InfluxDB Parquet files) -in a separate namespace from InfluxDB or external to Kubernetes entirely. - -Running the Catalog database and Object Store in a separate namespace or outside -of Kubernetes makes management of the InfluxDB instance easier and helps to -prevents accidental data loss. - -While deploying everything in the same namespace is possible for testing or initial setup, it is not recommended for production environments. -{{% /note %}} - -### Cluster sizing recommendation - -For a [medium-size workload](https://www.influxdata.com/resources/influxdb-3-0-vs-oss/), -InfluxData has tested InfluxDB Clustered using the following AWS products -and sizing: - -- S3 for the object store (size is determined by how much data you write) -- Aurora Postgresql - serverless v2 scaling configuration (2-64 ACUs) -- EC2 instances - primarily m6i.2xlarge (8 CPU, 32GB RAM) - - 3 m6i.2xlarge instances for ingesters and routers (with minimum of 2Gi of local storage) - - 3 m6i.2xlarge instances for queriers - - 1 m6i.2xlarge instance for compactors - - 1 t3.large for the Kubernetes control plane - -Your sizing may need to be different based on your environment and workload, -but this is a reasonable starting size for your initial testing. - -## Set up local storage - -The InfluxDB ingester pods need local storage to store the Write-Ahead Log (WAL). -The recommended minimum size of the local storage is 2 gibibytes (`2Gi`). - -## Set up an OAuth2 provider - -InfluxDB requires access to an OAuth2 authentication service to authenticate user access. -InfluxDB Clustered requires that the OAuth2 service supports -[Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow). -InfluxData has tested with [Microsoft Entra ID _(formerly Azure Active Directory)_](https://www.microsoft.com/en-us/security/business/microsoft-entra), [Keycloak](https://www.keycloak.org/), and -[Auth0](https://auth0.com/), but any OAuth2 provider should work. -To access the OAuth2 server, InfluxDB requires the following OAuth2 connection credentials: - - - Client ID - - JWKS endpoint - - Device authorization endpoint - - Token endpoint. - -## Set up client Software - -On the system used to configure the cluster (not the cluster itself), install -the following: - -- [kubectl _(v1.27)_](https://kubernetes.io/docs/reference/kubectl/kubectl/) -- [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) - -## Configure object storage permissions - -Ensure the identity you use to connect to your S3-compatible object store has the correct -permissions to allow InfluxDB to perform all the actions it needs to. - -{{< expand-wrapper >}} -{{% expand "View example AWS S3 access policy" %}} - -The IAM role that you use to access AWS S3 should have the following policy: - -{{% code-placeholders "S3_BUCKET_NAME" %}} -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "", - "Effect": "Allow", - "Action": [ - "s3:PutObjectAcl", - "s3:PutObject", - "s3:ListMultipartUploadParts", - "s3:GetObjectAcl", - "s3:GetObject", - "s3:DeleteObject", - "s3:AbortMultipartUpload" - ], - "Resource": "arn:aws:s3:::S3_BUCKET_NAME/*", - }, - { - "Sid": "", - "Effect": "Allow", - "Action": [ - "s3:ListBucket", - "s3:GetBucketLocation" - ], - "Resource": "arn:aws:s3:::S3_BUCKET_NAME", - }, - { - "Sid": "", - "Effect": "Allow", - "Action": "s3:ListAllMyBuckets", - "Resource": "*", - } - ] -} -``` -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`S3_BUCKET_NAME`{{% /code-placeholder-key %}}: Name of your AWS S3 bucket - -{{% /expand %}} - -{{% expand "View the requirements for Google Cloud Storage" %}} - -To use Google Cloud Storage (GCS) as your object store, your [IAM principal](https://cloud.google.com/iam/docs/overview) should be granted the `roles/storage.objectUser` role. -For example, if using [Google Service Accounts](https://cloud.google.com/iam/docs/service-account-overview): - -{{% code-placeholders "GCP_SERVICE_ACCOUNT|GCP_BUCKET" %}} -```bash -gcloud storage buckets add-iam-policy-binding \ - gs://GCP_BUCKET \ - --member="serviceAccount:GCP_SERVICE_ACCOUNT" \ - --role="roles/storage.objectUser" -``` -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`GCP_SERVICE_ACCOUNT`{{% /code-placeholder-key %}}: Google Service Account name -- {{% code-placeholder-key %}}`GCP_BUCKET`{{% /code-placeholder-key %}}: GCS bucket name - -{{% /expand %}} - -{{% expand "View the requirements for Azure Blob Storage" %}} - -To use Azure Blob Storage as your object store, your [service principal](https://learn.microsoft.com/en-us/entra/architecture/service-accounts-principal) -should be granted the `Storage Blob Data Contributor` role. -This is a built-in role for Azure which encompasses common permissions. -You can assign it using the following command: - -{{% code-placeholders "PRINCIPAL|AZURE_SUBSCRIPTION|AZURE_RESOURCE_GROUP|AZURE_STORAGE_ACCOUNT|AZURE_STORAGE_CONTAINER" %}} -```bash -az role assignment create \ - --role "Storage Blob Data Contributor" \ - --assignee PRINCIPAL \ - --scope "/subscriptions/AZURE_SUBSCRIPTION/resourceGroups/AZURE_RESOURCE_GROUP/providers/Microsoft.Storage/storageAccounts/AZURE_STORAGE_ACCOUNT/blobServices/default/containers/AZURE_STORAGE_CONTAINER" -``` -{{% /code-placeholders %}} - -Replace the following: - -- {{% code-placeholder-key %}}`PRINCIPAL`{{% /code-placeholder-key %}}: A user, group, or service principal that the role should be assigned to -- {{% code-placeholder-key %}}`AZURE_SUBSCRIPTION`{{% /code-placeholder-key %}}: Your Azure subscription -- {{% code-placeholder-key %}}`AZURE_RESOURCE_GROUP`{{% /code-placeholder-key %}}: The resource group that your Azure Blob storage account belongs to -- {{% code-placeholder-key %}}`AZURE_STORAGE_ACCOUNT`{{% /code-placeholder-key %}}: Azure Blob storage account name -- {{% code-placeholder-key %}}`AZURE_STORAGE_CONTAINER`{{% /code-placeholder-key %}}: Container name in your Azure Blob storage account - -{{% /expand %}} - -{{< /expand-wrapper >}} - -{{< page-nav next="/influxdb/clustered/install/auth/" nextText="Set up authentication" >}} diff --git a/content/influxdb/clustered/install/secure-cluster/_index.md b/content/influxdb/clustered/install/secure-cluster/_index.md new file mode 100644 index 000000000..924795c7e --- /dev/null +++ b/content/influxdb/clustered/install/secure-cluster/_index.md @@ -0,0 +1,27 @@ +--- +title: Secure your InfluxDB cluster +description: > + Prepare your InfluxDB cluster for production use by enabling TLS and + authentication to ensure your cluster is secure. +menu: + influxdb_clustered: + name: Secure your cluster + parent: Install InfluxDB Clustered +weight: 104 +cascade: + metadata: + - Install InfluxDB Clustered + - 'Phase 4: Secure your cluster' +metadata: + - Install InfluxDB Clustered + - Phase 4 +--- + +This phase of the installation process prepares your InfluxDB cluster for +production use by enabling security options to ensure your cluster is secured. + +## Phase 4 process + +{{< children type="ordered-list" >}} + +{{< page-nav prev="/influxdb/clustered/install/optimize-cluster/optimize-querying/" prevText="Optimize querying" next="/influxdb/clustered/install/secure-cluster/tls/" nextText="Set up TLS" >}} diff --git a/content/influxdb/clustered/install/secure-cluster/auth.md b/content/influxdb/clustered/install/secure-cluster/auth.md new file mode 100644 index 000000000..1b5e62f77 --- /dev/null +++ b/content/influxdb/clustered/install/secure-cluster/auth.md @@ -0,0 +1,793 @@ +--- +title: Set up administrative authentication +description: > + Set up an OAuth 2.0 identity provider to manage administrative access to your + InfluxDB cluster. +menu: + influxdb_clustered: + name: Set up authentication + parent: Secure your cluster +weight: 220 +aliases: + - /influxdb/clustered/install/auth/ +related: + - /influxdb/clustered/admin/users/ + - /influxdb/clustered/admin/bypass-identity-provider/ +--- + +To manage administrative access to your InfluxDB cluster, integrate your cluster +with an OAuth 2.0 identity provider. Use your identity provider to create OAuth2 +accounts for all users who need administrative access to your InfluxDB cluster. +Administrative access lets users perform actions like creating databases and +database tokens (which provide read and write access to databases). + +- [Identity provider requirements](#identity-provider-requirements) +- [Identity provider credentials](#identity-provider-credentials) +- [Set up your identity provider](#set-up-your-identity-provider) +- [Configure your cluster to connect to your identity provider](#configure-your-cluster-to-connect-to-your-identity-provider) +- [Apply your configuration changes](#apply-your-configuration-changes) +- [Configure influxctl](#configure-influxctl) +- [Test your authorization flow](#test-your-authorization-flow) + +InfluxData has tested with the following identity providers, but any provider +that [meets the requirements](#identity-provider-requirements) +should work: + +- [Microsoft Entra ID _(formerly Azure Active Directory)_](https://www.microsoft.com/en-us/security/business/microsoft-entra) +- [Keycloak](https://www.keycloak.org/) +- [Auth0](https://auth0.com/) + +{{% note %}} +Identity providers can be deployed with your InfluxDB cluster or run externally. +If you choose to deploy your provider with your InfluxDB cluster, the process +outlined below should be done _after_ your initial InfluxDB cluster deployment. +{{% /note %}} + +## Identity provider requirements + +To integrate an identity provider with your InfluxDB Cluster, it must meet the +following requirements: + +- Supports OAuth 2.0 +- Supports [Device Authorization Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow) + +## Identity provider credentials + +To access the OAuth2 server, InfluxDB requires the following OAuth2 connection +credentials: + +- Client ID +- JWKS endpoint +- Device authorization endpoint +- Token endpoint + +## Set up your identity provider + +Setup instructions are provided for the following: + +{{< tabs-wrapper >}} +{{% tabs %}} +[Keycloak](#) +[Microsoft Entra ID](#) + + + +{{% /tabs %}} + +{{% tab-content %}} + + + +### Keycloak + +To use Keycloak as your identity provider: + +1. [Create a Keycloak realm](#create-a-keycloak-realm) +2. [Create a Keycloak client with device flow enabled](#create-a-keycloak-client-with-device-flow-enabled) +3. [Create users that need administrative access to your InfluxDB cluster](#create-users) +4. [Configure InfluxDB Clustered to use Keycloak](#configure-influxdb-clustered-to-use-keycloak) + +#### Create a Keycloak realm + +See [Creating a realm](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-a-realm_server_administration_guide) +in the Keycloak documentation. + +#### Create a Keycloak client with device flow enabled + +1. In the **Keycloak Admin Console**, navigate to **Clients** and then click + **Create Client**. +2. In the **General Settings** configuration step: + + 1. Set the **Client type** to **OpenID Connect**. + 2. Enter a **Client ID**, Save your client ID to be used later. + 3. _Optional:_ Enter a **Name** and **Description** for the client. + 4. Click **Next**. + +3. In the **Capability** configuration step, enable the + **OAuth 2.0 Device Authorization Grant** authentication flow, and then click + **Next**. +4. In the **Login settings** step, you don’t need to change anything. + Click **Save**. + +#### Create users + +See [Creating users](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-user_server_administration_guide) +in the Keycloak documentation. + +##### Find user IDs with Keycloak + +To find the user IDs with Keycloak, use the Keycloak Admin Console or the Keycloak REST API. + +###### Keycloak Admin Console + +1. In the Keycloak Admin Console, navigate to your realm +2. Select **Users** in the left navigation. +3. Select the user you want to find the ID for. +4. Select the **Details** tab. The user ID is listed here. + +###### Keycloak REST API + +Send a GET request to the Keycloak REST API `/users` endpoint to fetch +the ID of a specific user. Provide the following: + +- **Query parameters** + - **username**: Username to retrieve information about + +{{% code-placeholders "KEYCLOAK_(HOST|REALM|USERNAME)" %}} + +```sh +curl https://KEYCLOAK_HOST/auth/admin/realms/KEYCLOAK_REALM/users?username=KEYCLOAK_USERNAME +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: + the Keycloak host and port (`host:port`) +- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: + the Keycloak realm +- {{% code-placeholder-key %}}`KEYCLOAK_USERNAME`{{% /code-placeholder-key %}}: + the Keycloak username to retrieve + +--- + +#### Configure InfluxDB Clustered to use Keycloak + +Run the following command to retrieve a JSON object that contains the OpenID configuration +of your Keycloak realm: + +{{% code-placeholders "KEYCLOAK_(HOST|REALM)" %}} + +```sh +curl https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/.well-known/openid-configuration +``` + +{{% /code-placeholders %}} + +{{< expand-wrapper >}} +{{% expand "View example response body" %}} + +{{% code-placeholders "KEYCLOAK_(HOST|REALM)" %}} + +```json +{ + "issuer": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM", + "authorization_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/auth", + "token_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/token", + "device_authorization_endpoint": "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/auth/device", + "userinfo_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/userinfo", + "end_session_endpoint": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/logout", + "jwks_uri": "https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs", + "grant_types_supported": ["authorization_code", "refresh_token", "password"], + "response_types_supported": ["code"], + "subject_types_supported": ["public"], + "id_token_signing_alg_values_supported": ["RS256"], + "response_modes_supported": ["query"] +} +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +The following are important fields in the JSON object that are necessary to +connect your InfluxDB cluster and administrative tools to Keycloak: + +- **jwks_uri**: Used in your InfluxDB cluster configuration file. + _See [Configure your cluster to connect to your identity provider](#configure-your-cluster-to-connect-to-your-identity-provider)_. +- **device_authorization_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.device_url`) +- **token_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.token_url`) + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +### Microsoft Entra ID + +To use Microsoft Entra ID as your identity provider: + +1. [Create a new tenant in Microsoft Entra ID](#create-a-new-tenant-in-microsoft-entra-id) +2. [Add users that need administrative access to your InfluxDB cluster](#add-users-that-need-administrative-access-to-your-influxdb-cluster) +3. [Register a new application with device code flow enabled](#register-a-new-application-with-device-code-flow-enabled) +4. Configure InfluxDB Clustered to use Microsoft Entra ID + +#### Create a new tenant in Microsoft Entra ID + +See [Create a new tenant in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/create-new-tenant) +in the Microsoft Azure documentation. +_Copy and store your **Microsoft Entra Tenant ID**_. + +#### Add users that need administrative access to your InfluxDB cluster + +See [Add or delete users](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/add-users) +in the Microsoft Azure documentation. + +##### Find user IDs with Microsoft Entra ID + +For Microsoft Entra ID, the unique user ID is the Microsoft ObjectId (OID). +To download a list of user OIDs: + +1. In the **Microsoft Azure Portal**, select **Users** in the left navigation. +2. Select users you want OIDs for and click **Download Users**. + +In the downloaded CSV file, user OIDs are provided in the `id` column. + +#### Register a new application with device code flow enabled + +1. In the **Microsoft Azure Portal**, select **App Registrations** in the left navigation. +2. Click **New Registration** and enter a name for a new application to handle + authentication requests. +3. Click **Register Application**. _Copy and store your **Application (Client) ID**_. +4. In your registered application, click **Authentication** in the left navigation. +5. Under **Advanced Settings**, set **Allow public client flows** to **Yes**. + This enables the use of the [device code flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code) + for logging in to your InfluxDB cluster. + +#### Configure InfluxDB Clustered to use Microsoft Entra ID + +Use the following command to retrieve a JSON object that contains the OpenID configuration +of your Microsoft Entra tenant: + +{{% code-placeholders "AZURE_TENANT_ID" %}} + +```sh +curl https://login.microsoftonline.com/AZURE_TENANT_ID/v2.0/.well-known/openid-configuration +``` + +{{% /code-placeholders %}} + +Replace {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}} +with your [Microsoft Entra tenant ID](#create-a-new-tenant-in-microsoft-entra-id). + +{{< expand-wrapper >}} +{{% expand "View example response body" %}} + +{{% code-placeholders "AZURE_TENANT_ID" %}} + +```js +{ + "issuer": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/", + "authorization_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/authorize", + "token_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/token", + "device_authorization_endpoint": "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/devicecode", + "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo", + "jwks_uri": "https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys", + "grant_types_supported": [ + "authorization_code", + "refresh_token", + "password" + ], + "response_types_supported": [ + "code" + ], + "subject_types_supported": [ + "public" + ], + "id_token_signing_alg_values_supported": [ + "RS256" + ], + "response_modes_supported": [ + "query" + ] +} +``` + +{{% /code-placeholders %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +The following are important fields in the JSON object that are necessary to +connect your InfluxDB cluster and administrative tools to Keycloak: + +- **jwks_uri**: Used in your InfluxDB cluster configuration file. + _See [Configure your cluster to connect to your identity provider](#configure-your-cluster-to-connect-to-your-identity-provider)_. +- **device_authorization_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.device_url`) +- **token_endpoint**: Used in your [`influxctl` configuration file](#configure-influxctl) (`profile.auth.oauth2.token_url`) + + + +{{% /tab-content %}} + + + + + + + +{{< /tabs-wrapper >}} + +## Configure your cluster to connect to your identity provider + +To connect your InfluxDB cluster to your OAuth2 provider, update your +`AppInstance` resource with the required credentials. Modify your `AppInstance` +resource directly or, if using the +[InfluxDB Clustered Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-clustered), +update your `values.yaml`. + +{{< tabs-wrapper >}} +{{% tabs %}} +[AppInstance](#) +[Helm](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +Provide values for the following fields in your `AppInstance` resource: + +- `spec.package.spec.admin` + - `identityProvider`: Identity provider name. + _If using Microsoft Entra ID (formerly Azure Active Directory), set the name + to `azure`_. + - `jwksEndpoint`: JWKS endpoint provide by your identity provider. + - `users`: List of OAuth2 users to grant administrative access to your + InfluxDB cluster. IDs are provided by your identity provider. + +Below are examples for **Keycloak**, **Auth0**, and **Microsoft Entra ID**, but +other OAuth2 providers should work as well: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Keycloak](#) +[Auth0](#) +[Microsoft Entra ID](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% code-callout "keycloak" "green" %}} +{{% code-placeholders "KEYCLOAK_(HOST|REALM|USER_ID)" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + admin: + identityProvider: keycloak + jwksEndpoint: |- + https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Keycloak. + - id: KEYCLOAK_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: + Host and port of your Keycloak server +- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: + Keycloak realm +- {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: + Keycloak user ID to grant InfluxDB administrative access to + +--- + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-callout "auth0" "green" %}} +{{% code-placeholders "AUTH0_(HOST|USER_ID)" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + admin: + identityProvider: auth0 + jwksEndpoint: |- + https://AUTH0_HOST/.well-known/openid-configuration + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AUTH0_HOST`{{% /code-placeholder-key %}}: + Host and port of your Auth0 server +- {{% code-placeholder-key %}}`AUTH0_USER_ID`{{% /code-placeholder-key %}}: + Auth0 user ID to grant InfluxDB administrative access to + +--- + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-callout "azure" "green" %}} +{{% code-placeholders "AZURE_(USER|TENANT)_ID" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + admin: + identityProvider: azure + jwksEndpoint: |- + https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}}: + Microsoft Entra tenant ID +- {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: + Microsoft Entra user ID to grant InfluxDB administrative access to + _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/secure-cluster/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ + +--- + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +Provide values for the following fields in your `values.yaml`: + +- `admin` + - `identityProvider`: Identity provider name. + _If using Microsoft Entra ID (formerly Azure Active Directory), set the name + to `azure`_. + - `jwksEndpoint`: JWKS endpoint provide by your identity provider. + - `users`: List of OAuth2 users to grant administrative access to your + InfluxDB cluster. IDs are provided by your identity provider. + +Below are examples for **Keycloak**, **Auth0**, and **Microsoft Entra ID**, but +other OAuth2 providers should work as well: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Keycloak](#) +[Auth0](#) +[Microsoft Entra ID](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% code-callout "keycloak" "green" %}} +{{% code-placeholders "KEYCLOAK_(HOST|REALM|USER_ID)" %}} + +```yaml +admin: + # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc + # Note for Azure Active Directory it must be exactly "azure" + identityProvider: keycloak + # The JWKS endpoint provided by the Identity Provider + jwksEndpoint: |- + https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs + # The list of users to grant access to Clustered via influxctl + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Keycloak. + - id: KEYCLOAK_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: + Host and port of your Keycloak server +- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: + Keycloak realm +- {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: + Keycloak user ID to grant InfluxDB administrative access to + +--- + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-callout "auth0" "green" %}} +{{% code-placeholders "AUTH0_(HOST|USER_ID)" %}} + +```yaml +admin: + # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc + # Note for Azure Active Directory it must be exactly "azure" + identityProvider: auth0 + # The JWKS endpoint provided by the Identity Provider + jwksEndpoint: |- + https://AUTH0_HOST/.well-known/openid-configuration + # The list of users to grant access to Clustered via influxctl + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AUTH0_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AUTH0_HOST`{{% /code-placeholder-key %}}: + Host and port of your Auth0 server +- {{% code-placeholder-key %}}`AUTH0_USER_ID`{{% /code-placeholder-key %}}: + Auth0 user ID to grant InfluxDB administrative access to + +--- + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-callout "azure" "green" %}} +{{% code-placeholders "AZURE_(USER|TENANT)_ID" %}} + +```yaml +admin: + # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc + # Note for Azure Active Directory it must be exactly "azure" + identityProvider: azure + # The JWKS endpoint provided by the Identity Provider + jwksEndpoint: |- + https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys + # The list of users to grant access to Clustered via influxctl + users: + # All fields are required but `firstName`, `lastName`, and `email` can be + # arbitrary values. However, `id` must match the user ID provided by Auth0. + - id: AZURE_USER_ID + firstName: Marty + lastName: McFly + email: mcfly@influxdata.com +``` + +{{% /code-placeholders %}} +{{% /code-callout %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}}: + Microsoft Entra tenant ID +- {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: + Microsoft Entra user ID to grant InfluxDB administrative access to + _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/secure-cluster/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ + +--- + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +{{% note %}} +For more information about managing users in your InfluxDB Cluster, see +[Manage users](/influxdb/clustered/admin/users/). +{{% /note %}} + +## Apply your configuration changes + +Use `kubectl` or `helm` to apply your configuration changes and connect your +InfluxDB cluster to your identity provider. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[kubectl](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Configure influxctl + +The [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/) lets you +perform administrative actions such as creating databases or database tokens. +All `influxctl` commands are first authorized using your identity provider. +Update your [`influxctl` configuration file](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) +to connect to your identity provider. + +The following examples show how to configure `influxctl` for various identity providers: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Keycloak](#) +[Auth0](#) +[Microsoft Entra ID](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + + +{{% code-placeholders "KEYCLOAK_(CLIENT_ID|PORT|REALM)" %}} + +```toml +[[profile]] + name = "default" + product = "clustered" + host = "{{< influxdb/host >}}" # InfluxDB cluster host + port = "8086" # InfluxDB cluster port + + [profile.auth.oauth2] + client_id = "KEYCLOAK_CLIENT_ID" + device_url = "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/auth/device" + token_url = "https://KEYCLOAK_HOST/realms/KEYCLOAK_REALM/protocol/openid-connect/token" +``` + +{{% /code-placeholders %}} + + + +{{% /code-tab-content %}} +{{% code-tab-content %}} + + + +{{% code-placeholders "AUTH0_(CLIENT_)*(ID|SECRET|HOST)" %}} + +```toml +[[profile]] + name = "default" + product = "clustered" + host = "{{< influxdb/host >}}" # InfluxDB cluster host + port = "8086" # InfluxDB cluster port + + [profile.auth.oauth2] + client_id = "AUTH0_CLIENT_ID" + client_secret = "AUTH0_CLIENT_SECRET" + device_url = "https://AUTH0_HOST/oauth/device/code" + token_url = "https://AUTH0_HOST/oauth/token" +``` + +{{% /code-placeholders %}} + + + +{{% /code-tab-content %}} +{{% code-tab-content %}} + + + +{{% code-placeholders "AZURE_(CLIENT|TENANT)_ID" %}} + +```toml +[[profile]] + name = "default" + product = "clustered" + host = "{{< influxdb/host >}}" # InfluxDB cluster host + port = "8086" # InfluxDB cluster port + + [profile.auth.oauth2] + client_id = "AZURE_CLIENT_ID" + scopes = ["AZURE_CLIENT_ID/.default"] + device_url = "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/devicecode" + token_url = "https://login.microsoftonline.com/AZURE_TENANT_ID/oauth2/v2.0/token" +``` + +{{% /code-placeholders %}} + + + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% warn %}} +### Refresh your admin token {note="Recommended"} + +In preparation for moving into production, we strongly recommend revoking your +cluster's _admin_ token used to authorize with your cluster in the earlier phases +of the InfluxDB Clustered installation process and generate a new admin token. + +For detailed instructions, see +[Revoke an admin token](/influxdb/clustered/admin/bypass-identity-provider/#revoke-an-admin-token). +{{% /warn %}} + +## Test your authorization flow + +To test your identity provider integration and ensure administrative access is +correctly authorized, run any `influxctl` command that +_requires administrative authentication_--for example: + + + +```bash +influxctl token list +``` + +Before executing, the command directs you to authorize with +your identity provider. +After you authorize successfully, the command runs and returns results. +successfully. + +{{< page-nav prev="/influxdb/clustered/install/secure-cluster/tls/" prevText="Set up TLS" >}} diff --git a/content/influxdb/clustered/install/secure-cluster/tls.md b/content/influxdb/clustered/install/secure-cluster/tls.md new file mode 100644 index 000000000..8c12ad819 --- /dev/null +++ b/content/influxdb/clustered/install/secure-cluster/tls.md @@ -0,0 +1,309 @@ +--- +title: Set up TLS in your InfluxDB cluster +description: > + Set up TLS in your InfluxDB to ensure both incoming and outgoing data is + encrypted and secure. +menu: + influxdb_clustered: + name: Set up TLS + parent: Secure your cluster +weight: 210 +--- + +Set up TLS in your InfluxDB cluster to ensure both incoming and outgoing data is +encrypted and secure. +We recommend using TLS to encrypt communication for the +following: + +- Ingress to your cluster +- Connection to your Object store +- Connection to your Catalog (PostgreSQL-compatible) database + +{{% note %}} +If using self-signed certs, +[provide a custom certificate authority (CA) bundle](#provide-a-custom-certificate-authority-bundle). +{{% /note %}} + +- [Set up ingress TLS](#set-up-ingress-tls) +- [Require HTTPS on the object store](#require-https-on-the-object-store) +- [Require TLS on your catalog database](#require-tls-on-your-catalog-database) +- [Provide a custom certificate authority bundle](#provide-a-custom-certificate-authority-bundle) +- [Apply the changes to your cluster](#apply-the-changes-to-your-cluster) + +## Set up ingress TLS + +Kubernetes support many different ingress controllers, some of which provide +simple mechanisms for creating and managing TLS certificates. +If using the [InfluxDB-defined ingress and the Nginx Ingress Controller](/influxdb/clustered/install/set-up-cluster/prerequisites/#set-up-a-kubernetes-ingress-controller), +add a valid TLS Certificate to the cluster as a secret. +Provide the paths to the TLS certificate file and key file: + +{{% code-placeholders "TLS_(CERT|KEY)_PATH" %}} + + + +```bash +kubectl create secret tls ingress-tls \ + --namespace influxdb \ + --cert TLS_CERT_PATH \ + --key TLS_KEY_PATH +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- _{{% code-placeholder-key %}}`TLS_CERT_PATH`{{% /code-placeholder-key %}}: + Path to the certificate file on your local machine._ +- _{{% code-placeholder-key %}}`TLS_KEY_PATH`{{% /code-placeholder-key %}}: + Path to the certificate secret key file on your local machine._ + +--- + +Provide the TLS certificate secret to the InfluxDB configuration in the +[Configure ingress step](#configure-ingress). + +### Configure ingress + +Update your `AppInstance` resource to reference the secret that +[contains your TLS certificate and key](#set-up-ingress-tls). +The examples below use the name `ingress-tls`. + +- **If modifying the `AppInstance` resource directly**, reference the TLS secret + in the `spec.package.spec.ingress.tlsSecretName` property. +- **If using the InfluxDB Clustered Helm chart**, reference the TLS secret in + the `ingress.tlsSecretName` property in your `values.yaml`. + +_The `tlsSecretName` field is optional. You may want to use it if you already have a TLS certificate for your DNS name._ + +{{< expand-wrapper >}} +{{% expand "Use cert-manager and Let's Encrypt to manage TLS certificates" %}} + +If you instead want to automatically create an [ACME](https://datatracker.ietf.org/doc/html/rfc8555) +certificate (for example, using [Let's Encrypt](https://letsencrypt.org/)), refer +to the [cert-manager documentation](https://cert-manager.io/docs/usage/ingress/) +for more details on how to annotate the `Ingress` resource produced by the +InfluxDB installer operator. The operator lets you to add annotations +(with `kubectl annotate`) and preserves them as it operates on resources. + +{{% note %}} +If you choose to use cert-manager, it's your responsibility to install and configure it. +{{% /note %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +{{% code-callout "ingress-tls|cluster-host\.com" "green" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + # ... + ingress: + hosts: + - {{< influxdb/host >}} + tlsSecretName: ingress-tls +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yaml +ingress: + hosts: + - {{< influxdb/host >}} + tlsSecretName: ingress-tls +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-callout %}} + +## Require HTTPS on the object store + +Some object store providers allow unsecure connections when accessing the object +store. Refer to your object store provider's documentation for information about +installing TLS certificates and ensuring all connections are secure. + +If using **AWS S3 or an S3-compatible** object store, set following property +in your `AppInstance` resources to `false` to disallow unsecure connections to +your object store: + +- **If modifying the `AppIsntance` resource directly**: + `spec.package.spec.objectStore.s3.allowHttp` +- **If using the InfluxDB Clustered Helm chart**: + `objectStore.s3.allowHttp` in your `values.yaml` + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + objectStore: + s3: + # ... + allowHttp: 'false' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yml +objectStore: + s3: + # ... + allowHttp: 'false' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Require TLS on your catalog database + +Refer to your PostreSQL-compatible database provider's documentation for +installing TLS certificates and ensuring secure connections. + +If currently using an unsecure connection to your Catalog database, update your +Catalog data source name (DSN) to **remove the `sslmode=disable` query parameter**: + +{{% code-callout "\?sslmode=disable" "magenta delete" %}} +```txt +postgres://username:passw0rd@mydomain:5432/influxdb?sslmode=disable +``` +{{% /code-callout %}} + +## Provide a custom certificate authority bundle {note="Optional"} + +InfluxDB attempts to make TLS connections to the services it depends on--notably, +the [Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog) +and the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store). +InfluxDB validates certificates for all connections. + +_If you host dependent services yourself and you use a private or otherwise not +well-known certificate authority to issue certificates to them, +InfluxDB won't recognize the issuer and can't validate the certificates._ +To allow InfluxDB to validate the certificates from your custom CA, +configure the `AppInstance` resource to use a **PEM certificate +bundle** that contains your custom certificate authority chain. + +1. Use `kubectl` to create a config map that contains your PEM-formatted + certificate bundle file. + Your certificate authority administrator should provide you with a + PEM-formatted bundle file. + + {{% note %}} +This PEM bundle file establishes a chain of trust for the +external services that InfluxDB depends on. +It's _not_ the certificate that InfluxDB uses to +host its own TLS endpoints. + {{% /note %}} + + In the example, replace `/path/to/private_ca.pem` with the path to your PEM-formatted certificate bundle file: + + + + ```bash + kubectl --namespace influxdb create configmap custom-ca --from-file=certs.pem=/path/to/private_ca.pem + ``` + + {{% note %}} +#### Bundle multiple certificates + +You can append multiple certificates into the same bundle. +This approach helps when you need to include intermediate certificates or explicitly include leaf certificates. + +Include certificates in the bundle in the following order: + +1. Leaf certificates +2. Intermediate certificates required by leaf certificates +3. Root certificate + {{% /note %}} + +2. Update your `AppInstance` resource to refer to the `custom-ca` config map. + + - **If modifying the `AppInstance` resource directly**: + Add the config map to the `.spec.package.spec.egress` property. + - **If using the InfluxDB Clustered Helm chart**: + Set `useCustomEgress` to `true` and update the `egress` property to refer + to the config map. + + {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + egress: + customCertificates: + valueFrom: + configMapKeyRef: + key: ca.pem + name: custom-ca +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```yml +useCustomEgress: true +egress: + customCertificates: + valueFrom: + configMapKeyRef: + key: ca.pem + name: custom-ca +``` +{{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +## Apply the changes to your cluster + +Use `kubectl` or `helm` (if using the InfluxDB Clustered Helm chart), to apply +the configuration changes to your cluster: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[kubectl](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + + +```bash +kubectl apply \ + --filename myinfluxdb.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```bash +helm upgrade \ + influxdata/influxdb3-clustered \ + -f ./values.yml \ + --namespace influxdb +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{< page-nav prev="/influxdb/clustered/install/secure-cluster/" prevText="Secure your cluster" next="/influxdb/clustered/install/secure-cluster/auth/" nextText="Set up authentication" >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/_index.md b/content/influxdb/clustered/install/set-up-cluster/_index.md new file mode 100644 index 000000000..6ed86b7c6 --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/_index.md @@ -0,0 +1,28 @@ +--- +title: Set up your InfluxDB cluster +description: > + Get a basic InfluxDB cluster up and running with as few external + dependencies as possible and confirm you can write and query data. +menu: + influxdb_clustered: + name: Set up your cluster + parent: Install InfluxDB Clustered +weight: 101 +cascade: + metadata: + - Install InfluxDB Clustered + - 'Phase 1: Set up your cluster' +metadata: + - Install InfluxDB Clustered + - Phase 1 +--- + +The first phase of installing InfluxDB Clustered is to get a basic InfluxDB +cluster up and running with as few external dependencies as possible and confirm +you can write and query data. + +## Phase 1 steps + +{{< children type="ordered-list" >}} + +{{< page-nav next="/influxdb/clustered/install/set-up-cluster/prerequisites/" nextText="Set up prerequisites" >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/configure-cluster/_index.md b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/_index.md new file mode 100644 index 000000000..d774ef5a4 --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/_index.md @@ -0,0 +1,28 @@ +--- +title: Configure your InfluxDB cluster +description: > + InfluxDB Clustered deployments are managed using Kubernetes and configured using + a YAML configuration file. +menu: + influxdb_clustered: + name: Configure your cluster + parent: Set up your cluster +weight: 220 +aliases: + - /influxdb/clustered/install/configure-cluster/ +--- + +InfluxDB Clustered deployments are managed using Kubernetes and configured using +a YAML configuration file. +Apply configuration settings to your cluster by editing and applying a +Kubernetes custom resource (CRD) called `AppInstance`. +The AppInstance CRD is defined in a YAML file (use the `example-customer.yml` +provided by InfluxData as a template). + +We recommend editing the `AppInstance` resource directly as the primary method +for configuring and managing your InfluxDB cluster. If you are required to use +[Helm](https://helm.sh/), there is a InfluxDB Clustered Helm chart available +that acts as a wrapper for the `AppInstance` resource and lets you use Helm to +manage configuration changes in your InfluxDB cluster. + +{{< children >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/configure-cluster/directly.md b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/directly.md new file mode 100644 index 000000000..6e455ba74 --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/directly.md @@ -0,0 +1,741 @@ +--- +title: Use the InfluxDB AppInstance resource configuration +list_title: Configure your InfluxDB AppInstance resource directly +description: > + Configure your InfluxDB cluster by editing configuration options in + the provided `AppInstance` resource. +menu: +menu: + influxdb_clustered: + name: Configure AppInstance + parent: Configure your cluster +weight: 220 +list_code_example: | + Configure AppInstance directly Recommended +aliases: + - /influxdb/clustered/install/configure-cluster/directly/ +--- + +Configure your InfluxDB cluster by editing configuration options in +the `AppInstance` resource provided by InfluxData. +Resource configuration for your cluster includes the following: + +- **`influxdb-docker-config.json`**: an authenticated Docker configuration file. + The InfluxDB Clustered software is in a secure container registry. + This file grants access to the collection of container images required to + install InfluxDB Clustered. +- **A tarball that contains the following files**: + + - **`app-instance-schema.json`**: Defines the schema + that you can use to validate `example-customer.yml` and your cluster configuration in tools like [Visual Studio Code (VS Code)](https://code.visualstudio.com/). + - **`example-customer.yml`**: Configuration for your InfluxDB cluster that includes + information about [prerequisites](/influxdb/clustered/install/set-up-cluster/prerequisites/). + + {{% note %}} + +The following sections refer to a `myinfluxdb.yml` file that you copy from +`example-customer.yml` and edit for your InfluxDB cluster. + + {{% /note %}} + +## Configuration data + +When ready to configure your InfluxDB cluster, have the following information +available: + +- **InfluxDB cluster hostname**: the hostname Kubernetes uses to expose InfluxDB + API endpoints +- **PostgreSQL-style data source name (DSN)**: used to access your + PostgreSQL-compatible database that stores the InfluxDB Catalog. +- **Object store credentials** _(AWS S3 or S3-compatible)_ + - Endpoint URL + - Access key + - Bucket name + - Region (required for S3, might not be required for other object stores) +- **Local or attached storage information** _(for ingester pods)_ + - Storage class + - Storage size + +You deploy {{% product-name %}} to a Kubernetes namespace, referred to as the +_target_ namespace in the following procedures. +For simplicity, we assume this namespace is `influxdb`--you can use any name you like. + +To manage {{% product-name %}} installation, updates, and upgrades, you edit +and apply a [Kubernetes custom resource (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +(`AppInstance`), which you define in a YAML file that conforms to the `app-instance-schema.json` schema. + +{{% product-name %}} includes `example-customer.yml` as a configuration template. + +The `AppInstance` resource contains key information, such as: + +- Name of the target namespace +- Version of the InfluxDB package +- Reference to the InfluxDB container registry pull secrets +- Hostname of your cluster's InfluxDB API +- Parameters to connect to [external prerequisites](/influxdb/clustered/install/set-up-cluster/prerequisites/) + +{{% note %}} +#### Update your namespace if using a namespace other than influxdb + +If you use a namespace name other than `influxdb`, update the +`metadata.namespace` property in your `myinfluxdb.yml` to use your custom +namespace name. +{{% /note %}} + +## Configure your cluster + +1. [Create a cluster configuration file](#create-a-cluster-configuration-file) +2. [Configure access to the InfluxDB container registry](#configure-access-to-the-influxdb-container-registry) +3. [Modify the configuration file to point to prerequisites](#modify-the-configuration-file-to-point-to-prerequisites) + +### Create a cluster configuration file + +Copy the provided `example-customer.yml` file to create a new configuration file +specific to your InfluxDB cluster. For example, `myinfluxdb.yml`. + + + +```bash +cp example-customer.yml myinfluxdb.yml +``` + +{{% note %}} + +#### Use VS Code to edit your configuration file + +We recommend using [Visual Studio Code (VS Code)](https://code.visualstudio.com/) +to edit your `myinfluxdb.yml` configuration file due to its JSON Schema support, +including autocompletion and validation features that help when +editing your InfluxDB configuration. InfluxData provides an +`app-instance-schema.json` JSON schema file that VS Code can use to validate +your configuration settings. +{{% /note %}} + +### Configure access to the InfluxDB container registry + +The provided `influxdb-docker-config.json` grants access to a collection of +container images required to run {{% product-name %}}. +Your Kubernetes Cluster needs access to the container registry to pull and +install InfluxDB. + +When pulling the {{% product-name %}} image, you're likely in one of two scenarios: + +- Your Kubernetes cluster can pull from the InfluxData container registry. +- Your cluster runs in an environment without network interfaces ("air-gapped") and + can only access a private container registry. + +In both scenarios, you need a valid _pull secret_. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Public registry (non-air-gapped)](#) +[Private registry (air-gapped)](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +#### Public registry (non-air-gapped) + +To pull from the InfluxData registry, you need to create a Kubernetes secret in the target namespace. + +```bash +kubectl create secret docker-registry gar-docker-secret \ + --from-file=.dockerconfigjson=influxdb-docker-config.json \ + --namespace influxdb +``` + +If successful, the output is the following: + +```text +secret/gar-docker-secret created +``` + +By default, the name of the secret is `gar-docker-secret`. +If you change the name of the secret, you must also change the value of the +`imagePullSecret` field in the `AppInstance` custom resource to match. + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +#### Private registry (air-gapped) + +If your Kubernetes cluster can't use a public network to download container images +from the InfluxData container registry, do the following: + +1. Copy the images from the InfluxData registry to your own private registry. +2. Configure your `AppInstance` resource with a reference to your private + registry name. +3. Provide credentials to your private registry. + +##### Copy the images + +We recommend using [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane) +to copy images into your private registry. + +1. [Install crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane#installation) + for your system. +2. Use the following command to create a container registry secret file and + retrieve the necessary secrets: + +{{% code-placeholders "PACKAGE_VERSION" %}} + + + +```bash +mkdir /tmp/influxdbsecret +cp influxdb-docker-config.json /tmp/influxdbsecret/config.json +DOCKER_CONFIG=/tmp/influxdbsecret \ + crane manifest \ + us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION +``` + +{{% /code-placeholders %}} + +--- + +Replace {{% code-placeholder-key %}}`PACKAGE_VERSION`{{% /code-placeholder-key %}} +with your InfluxDB Clustered package version. + +--- + +If your Docker configuration is valid and you’re able to connect to the container +registry, the command succeeds and the output is the JSON manifest for the Docker +image, similar to the following: + +{{< expand-wrapper >}} +{{% expand "View JSON manifest" %}} + +```json +{ + "schemaVersion": 2, + "config": { + "mediaType": "application/vnd.kubecfg.bundle.config.v1+json", + "digest": "sha256:6900d2f248e678176c68f3768e7e48958bb96a59232070ff31b3b018cf299aa7", + "size": 8598 + }, + "layers": [ + { + "mediaType": "application/vnd.kubecfg.bundle.tar+gzip", + "digest": "sha256:7c1d62e76287035a9b22b2c155f328fae9beff2c6aa7a09a2dd2697539f41d98", + "size": 404059 + } + ], + "annotations": { + "org.opencontainers.image.created": "1970-01-01T00:00:00Z", + "org.opencontainers.image.revision": "unknown", + "org.opencontainers.image.source": "kubecfg pack" + } +} +``` + +{{% /expand %}} +{{< /expand-wrapper >}} + +If there’s a problem with the Docker configuration, crane won't retrieve the +manifest and the output is similar to the following error: + +```bash +Error: fetching manifest us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:: GET https://us-docker.pkg.dev/v2/token?scope=repository%3Ainfluxdb2-artifacts%2Fclustered%2Finfluxdb%3Apull&service=: DENIED: Permission "artifactregistry.repositories.downloadArtifacts" denied on resource "projects/influxdb2-artifacts/locations/us/repositories/clustered" (or it may not exist) +``` + +The list of images that you need to copy is included in the package metadata. +You can obtain it with any standard OCI image inspection tool--for example: + +{{% code-placeholders "PACKAGE_VERSION" %}} + + + +```bash +DOCKER_CONFIG=/tmp/influxdbsecret \ +crane config \ + us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION \ + | jq -r '.metadata["oci.image.list"].images[]' \ + > /tmp/images.txt +``` + +{{% /code-placeholders %}} + +The output is a list of image names, similar to the following: + +``` +us-docker.pkg.dev/influxdb2-artifacts/idpe/idpe-cd-ioxauth@sha256:5f015a7f28a816df706b66d59cb9d6f087d24614f485610619f0e3a808a73864 +us-docker.pkg.dev/influxdb2-artifacts/iox/iox@sha256:b59d80add235f29b806badf7410239a3176bc77cf2dc335a1b07ab68615b870c +... +``` + +Use `crane` to copy the images to your private registry: + +{{% code-placeholders "REGISTRY_HOSTNAME" %}} + + + +```bash + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +### Modify the configuration file to point to prerequisites + +Update your `myinfluxdb.yml` configuration file with credentials necessary to +connect your cluster to your prerequisites. + +- [Configure ingress](#configure-ingress) +- [Configure the object store](#configure-the-object-store) +- [Configure the catalog database](#configure-the-catalog-database) +- [Configure local storage for ingesters](#configure-local-storage-for-ingesters) + +#### Configure ingress + +To configure ingress, provide values for the following fields in your +`myinfluxdb.yml` configuration file: + +- **`spec.package.spec.ingress.hosts`: Cluster hostnames** + + Provide the hostnames that Kubernetes should + use to expose the InfluxDB API endpoints. + For example: `{{< influxdb/host >}}`. + + _You can provide multiple hostnames. The ingress layer accepts incoming + requests for all listed hostnames. This can be useful if you want to have + distinct paths for your internal and external traffic._ + + {{% note %}} +You are responsible for configuring and managing DNS. Options include: + +- Manually managing DNS records +- Using [external-dns](https://github.com/kubernetes-sigs/external-dns) to + synchronize exposed Kubernetes services and ingresses with DNS providers. + {{% /note %}} + +- **`spec.package.spec.ingress.tlsSecretName`: TLS certificate secret name** + + (Optional): Provide the name of the secret that contains your TLS certificate + and key. The examples in this guide use the name `ingress-tls`. + + {{% note %}} +Writing to and querying data from InfluxDB does not require TLS. +For simplicity, you can wait to enable TLS before moving into production. +For more information, see Phase 4 of the InfluxDB Clustered installation +process, [Secure your cluster](/influxdb/clustered/install/secure-cluster/). + {{% /note %}} + +{{% code-callout "ingress-tls|cluster-host\.com" "green" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: +# ... +ingress: + hosts: + - {{< influxdb/host >}} + tlsSecretName: ingress-tls +``` + +{{% /code-callout %}} + +#### Configure the object store + +To connect your InfluxDB cluster to your object store, provide the required +credentials in your `myinfluxdb.yml`. The credentials required depend on your +object storage provider. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Amazon S3 or S3-compatible](#) +[Azure Blob Storage](#) +[Google Cloud Storage](#) +{{% /tabs %}} + +{{% tab-content %}} + + + +If using Amazon S3 or an S3-compatible object store, provide values for the +following fields in your `myinfluxdb.yml`: + +- `spec.package.spec.objectStore` + - `bucket`: Object storage bucket name + - `s3` + - `endpoint`: Object storage endpoint URL + - `allowHttp`: _Set to `true` to allow unencrypted HTTP connections_ + - `accessKey.value`: Object storage access key + - `secretKey.value`: Object storage secret key + - `region`: Object storage region + +{{% code-placeholders "S3_(URL|ACCESS_KEY|SECRET_KEY|BUCKET_NAME|REGION)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + objectStore: + s3: + # URL for S3 Compatible object store + endpoint: S3_URL + + # Set to true to allow communication over HTTP (instead of HTTPS) + allowHttp: 'true' + + # S3 Access Key + # This can also be provided as a valueFrom: secretKeyRef: + accessKey: + value: S3_ACCESS_KEY + + # S3 Secret Key + # This can also be provided as a valueFrom: secretKeyRef: + secretKey: + value: S3_SECRET_KEY + + # Bucket that the Parquet files will be stored in + bucket: S3_BUCKET_NAME + + # This value is required for AWS S3, it may or may not be required for other providers. + region: S3_REGION +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`S3_URL`{{% /code-placeholder-key %}}: Object storage endpoint URL +- {{% code-placeholder-key %}}`S3_ACCESS_KEY`{{% /code-placeholder-key %}}: Object storage access key +- {{% code-placeholder-key %}}`S3_SECRET_KEY`{{% /code-placeholder-key %}}: Object storage secret key +- {{% code-placeholder-key %}}`S3_BUCKET_NAME`{{% /code-placeholder-key %}}: Object storage bucket name +- {{% code-placeholder-key %}}`S3_REGION`{{% /code-placeholder-key %}}: Object storage region + +--- + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +If using Azure Blob Storage as your object store, provide values for the +following fields in your `myinfluxdb.yml`: + +- `spec.package.spec.objectStore` + - `bucket`: Azure Blob Storage bucket name + - `azure`: + - `accessKey.value`: Azure Blob Storage access key + _(can use a `value` literal or `valueFrom` to retrieve the value from a secret)_ + - `account.value`: Azure Blob Storage account ID + _(can use a `value` literal or `valueFrom` to retrieve the value from a secret)_ + +{{% code-placeholders "AZURE_(BUCKET_NAME|ACCESS_KEY|STORAGE_ACCOUNT)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + objectStore: + # Bucket that the Parquet files will be stored in + bucket: AZURE_BUCKET_NAME + + azure: + # Azure Blob Storage Access Key + # This can also be provided as a valueFrom: + accessKey: + value: AZURE_ACCESS_KEY + + # Azure Blob Storage Account + # This can also be provided as a valueFrom: secretKeyRef: + account: + value: AZURE_STORAGE_ACCOUNT +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`AZURE_BUCKET_NAME`{{% /code-placeholder-key %}}: Object storage bucket name +- {{% code-placeholder-key %}}`AZURE_ACCESS_KEY`{{% /code-placeholder-key %}}: Azure Blob Storage access key +- {{% code-placeholder-key %}}`AZURE_STORAGE_ACCOUNT`{{% /code-placeholder-key %}}: Azure Blob Storage account ID + +--- + + + +{{% /tab-content %}} +{{% tab-content %}} + + + +If using Google Cloud Storage as your object store, provide values for the +following fields in your `myinfluxdb.yml`: + +- `spec.package.spec.objectStore` + - `bucket`: Google Cloud Storage bucket name + - `google`: + - `serviceAccountSecret.name`: the Kubernetes Secret name that contains your + Google IAM service account credentials + - `serviceAccountSecret.key`: the key inside of your Google IAM secret that + contains your Google IAM account credentials + +{{% code-placeholders "GOOGLE_(BUCKET_NAME|IAM_SECRET|CREDENTIALS_KEY)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + objectStore: + # Bucket that the Parquet files will be stored in + bucket: GOOGLE_BUCKET_NAME + + google: + # This section is not needed if you are using GKE Workload Identity. + # It is only required to use explicit service account secrets (JSON files) + serviceAccountSecret: + # Kubernetes Secret name containing the credentials for a Google IAM + # Service Account. + name: GOOGLE_IAM_SECRET + # The key within the Secret containing the credentials. + key: GOOGLE_CREDENTIALS_KEY +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`GOOGLE_BUCKET_NAME`{{% /code-placeholder-key %}}: + Google Cloud Storage bucket name +- {{% code-placeholder-key %}}`GOOGLE_IAM_SECRET`{{% /code-placeholder-key %}}: + the Kubernetes Secret name that contains your Google IAM service account + credentials +- {{% code-placeholder-key %}}`GOOGLE_CREDENTIALS_KEY`{{% /code-placeholder-key %}}: + the key inside of your Google IAM secret that contains your Google IAM account + credentials + +--- + + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +#### Configure the catalog database + +The InfluxDB catalog is a PostgreSQL-compatible relational database that stores +metadata about your time series data. +To connect your InfluxDB cluster to your PostgreSQL-compatible database, +provide values for the following fields in your `myinfluxdb.yml` configuration file: + +{{% note %}} +We recommend storing sensitive credentials, such as your PostgreSQL-compatible DSN, +as secrets in your Kubernetes cluster. +{{% /note %}} + +- `spec.package.spec.catalog.dsn.valueFrom.secretKeyRef` + - `.name`: Secret name + - `.key`: Key in the secret that contains the DSN + +{{% code-placeholders "SECRET_(NAME|KEY)" %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + catalog: + # A postgresql style DSN that points to a postgresql compatible database. + # postgres://[user[:password]@][netloc][:port][/dbname][?param1=value1&...] + dsn: + valueFrom: + secretKeyRef: + name: SECRET_NAME + key: SECRET_KEY +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`SECRET_NAME`{{% /code-placeholder-key %}}: + Name of the secret containing your PostgreSQL-compatible DSN +- {{% code-placeholder-key %}}`SECRET_KEY`{{% /code-placeholder-key %}}: + Key in the secret that references your PostgreSQL-compatible DSN + +--- + +{{% warn %}} +##### Percent-encode special symbols in PostgreSQL DSNs + +Percent-encode special symbols in PostgreSQL DSNs to ensure +{{% product-name %}} parses them correctly. +Consider this when using DSNs with auto-generated passwords that include special +symbols for added security. + +If a DSN contains special characters that aren't percent-encoded, +you might encounter an error similar to the following: + +```txt +Catalog DSN error: A catalog error occurred: unhandled external error: error with configuration: invalid port number +``` + +{{< expand-wrapper >}} +{{% expand "View percent-encoded DSN example" %}} +To use the following DSN containing special characters: + +{{% code-callout "#" %}} +```txt +postgresql://postgres:meow#meow@my-fancy.cloud-database.party:5432/postgres +``` +{{% /code-callout %}} + +You must percent-encode the special characters in the connection string: + +{{% code-callout "%23" %}} +```txt +postgresql://postgres:meow%23meow@my-fancy.cloud-database.party:5432/postgres +``` +{{% /code-callout %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +For more information, see the [PostgreSQL Connection URI +docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS). +{{% /warn %}} + +{{% note %}} + +##### PostgreSQL instances without TLS or SSL + +If your PostgreSQL-compatible instance runs without TLS or SSL, you must include +the `sslmode=disable` parameter in the DSN. For example: + +{{% code-callout "sslmode=disable" %}} + +``` +postgres://username:passw0rd@mydomain:5432/influxdb?sslmode=disable +``` + +{{% /code-callout %}} +{{% /note %}} + +#### Configure local storage for ingesters + +InfluxDB ingesters require local storage to store the Write Ahead Log (WAL) for +incoming data. +To connect your InfluxDB cluster to local storage, provide values for the +following fields in your `myinfluxdb.yml` configuration file: + +- `spec.package.spec.ingesterStorage` + - `.storageClassName`: [Kubernetes storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/). + This differs based on the Kubernetes environment and desired storage characteristics. + - `storage`: Storage size. We recommend a minimum of 2 gibibytes (`2Gi`). + +{{% code-placeholders "STORAGE_(CLASS|SIZE)" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + spec: + ingesterStorage: + storageClassName: STORAGE_CLASS + storage: STORAGE_SIZE +``` + +{{% /code-placeholders %}} + +--- + +Replace the following: + +- {{% code-placeholder-key %}}`STORAGE_CLASS`{{% /code-placeholder-key %}}: + [Kubernetes storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) +- {{% code-placeholder-key %}}`STORAGE_SIZE`{{% /code-placeholder-key %}}: + Storage size (example: `2Gi`) + +--- + +{{< page-nav prev="/influxdb/clustered/install/secure-cluster/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/set-up-cluster/licensing/" nextText="Install your license" >}} diff --git a/content/influxdb/clustered/install/configure-cluster/use-helm.md b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/use-helm.md similarity index 60% rename from content/influxdb/clustered/install/configure-cluster/use-helm.md rename to content/influxdb/clustered/install/set-up-cluster/configure-cluster/use-helm.md index e85c4acb3..1ac916240 100644 --- a/content/influxdb/clustered/install/configure-cluster/use-helm.md +++ b/content/influxdb/clustered/install/set-up-cluster/configure-cluster/use-helm.md @@ -7,8 +7,12 @@ menu: name: Use Helm parent: Configure your cluster weight: 230 +list_code_example: | + Use Helm to configure AppInstance related: - /influxdb/clustered/admin/users/ +aliases: + - /influxdb/clustered/install/configure-cluster/use-helm/ --- Manage your InfluxDB Clustered deployments using Kubernetes and apply configuration settings using a YAML configuration file. @@ -29,9 +33,11 @@ a `values.yaml` on your local machine. ## Configuration data -When ready to install InfluxDB, have the following information available: +When ready to configure your InfluxDB cluster, have the following information +available: -- **InfluxDB cluster hostname**: the hostname Kubernetes uses to expose InfluxDB API endpoints +- **InfluxDB cluster hostname**: the hostname Kubernetes uses to expose InfluxDB + API endpoints - **PostgreSQL-style data source name (DSN)**: used to access your PostgreSQL-compatible database that stores the InfluxDB Catalog. - **Object store credentials** _(AWS S3 or S3-compatible)_ @@ -42,17 +48,19 @@ When ready to install InfluxDB, have the following information available: - **Local storage information** _(for ingester pods)_ - Storage class - Storage size -- **OAuth2 provider credentials** - - Client ID - - JWKS endpoint - - Device authorization endpoint - - Token endpoint InfluxDB is deployed to a Kubernetes namespace which, throughout the following installation procedure, is referred to as the _target_ namespace. For simplicity, we assume this namespace is `influxdb`, however you may use any name you like. +{{% note %}} +#### Set namespaceOverride if using a namespace other than influxdb + +If you use a namespace name other than `influxdb`, update the `namespaceOverride` +field in your `values.yaml` to use your custom namespace name. +{{% /note %}} + ### AppInstance resource The InfluxDB installation, update, and upgrade processes are driven by editing @@ -68,9 +76,9 @@ The `AppInstance` resource contains key information, such as: - Version of the InfluxDB package - Reference to the InfluxDB container registry pull secrets - Hostname where the InfluxDB API is exposed -- Parameters to connect to [external prerequisites](/influxdb/clustered/install/prerequisites/) +- Parameters to connect to [external prerequisites](/influxdb/clustered/install/set-up-cluster/prerequisites/) -### Kubit operator +### kubecfg kubit operator The InfluxDB Clustered Helm chart also includes the [`kubecfg kubit` operator](https://github.com/kubecfg/kubit) (maintained by InfluxData) @@ -78,16 +86,22 @@ which simplifies the installation and management of the InfluxDB Clustered packa It manages the application of the jsonnet templates used to install, manage, and update an InfluxDB cluster. +{{% note %}} +If you already installed the `kubecfg kubit` operator separately when +[setting up prerequisites](/influxdb/clustered/install/set-up-cluster/prerequisites/#install-the-kubecfg-kubit-operator) +for your cluster, in your `values.yaml`, set `skipOperator` to `true`. + +```yaml +skipOperator: true +``` +{{% /note %}} + ## Configure your cluster 1. [Install Helm](#install-helm) 2. [Create a values.yaml file](#create-a-valuesyaml-file) -3. [Create a namespace for InfluxDB](#create-a-namespace-for-influxdb) -4. [Configure access to the InfluxDB container registry](#configure-access-to-the-influxdb-container-registry) -5. [Set up cluster ingress](#set-up-cluster-ingress) -6. [Modify the configuration file to point to prerequisites](#modify-the-configuration-file-to-point-to-prerequisites) -7. [Provide a custom certificate authority bundle](#provide-a-custom-certificate-authority-bundle) - (Optional) +3. [Configure access to the InfluxDB container registry](#configure-access-to-the-influxdb-container-registry) +4. [Modify the configuration file to point to prerequisites](#modify-the-configuration-file-to-point-to-prerequisites) ### Install Helm @@ -107,17 +121,6 @@ Or you can copy the default `values.yaml` from GitHub: View values.yaml on GitHub -### Create a namespace for InfluxDB - -Create a namespace for InfluxDB. For example, using `kubectl`: - -```sh -kubectl create namespace influxdb -``` - -If you use a namespace name other than `influxdb`, update the `namespaceOverride` -field in your `values.yaml` to use your custom namespace name. - ### Configure access to the InfluxDB container registry The provided `influxdb-docker-config.json` grants access to a collection of @@ -307,43 +310,6 @@ images: {{% /tab-content %}} {{< /tabs-wrapper >}} -### Set up cluster ingress - -{{% note %}} -InfluxDB Clustered components use gRPC/HTTP2 protocols. If using an external load balancer, -you may need to explicitly enable these protocols on your load balancers. -{{% /note %}} - -The InfluxDB Clustered Helm chart includes the -[Kubernetes Nginx Ingress Controller](https://github.com/kubernetes/ingress-nginx). -Add a valid TLS Certificate to the cluster as a secret. -Provide the paths to the TLS certificate file and key file: - -{{% code-placeholders "TLS_(CERT|KEY)_PATH" %}} - -```sh -kubectl create secret tls ingress-tls \ - --namespace influxdb \ - --cert TLS_CERT_PATH \ - --key TLS_KEY_PATH -``` - -{{% /code-placeholders %}} - ---- - -Replace the following: - -- _{{% code-placeholder-key %}}`TLS_CERT_PATH`{{% /code-placeholder-key %}}: - Path to the certificate file on your local machine._ -- _{{% code-placeholder-key %}}`TLS_KEY_PATH`{{% /code-placeholder-key %}}: - Path to the certificate secret key file on your local machine._ - ---- - -Provide the TLS certificate secret to the InfluxDB configuration in the -[Configure ingress step](#configure-ingress). - ### Modify the configuration file to point to prerequisites Update your `values.yaml` file with credentials necessary to connect your @@ -353,8 +319,6 @@ cluster to your prerequisites. - [Configure the object store](#configure-the-object-store) - [Configure the catalog database](#configure-the-catalog-database) - [Configure local storage for ingesters](#configure-local-storage-for-ingesters) -- [Configure your OAuth2 provider](#configure-your-oauth2-provider) -- [Configure the size of your cluster](#configure-the-size-of-your-cluster) #### Configure ingress @@ -371,7 +335,7 @@ To configure ingress, provide values for the following fields in your distinct paths for your internal and external traffic._ {{% note %}} - You are responsible for configuring and managing DNS. Options include: +You are responsible for configuring and managing DNS. Options include: - Manually managing DNS records - Using [external-dns](https://github.com/kubernetes-sigs/external-dns) to @@ -380,28 +344,20 @@ To configure ingress, provide values for the following fields in your - **`ingress.tlsSecretName`: TLS certificate secret name** - Provide the name of the secret that - [contains your TLS certificate and key](#set-up-cluster-ingress). - The examples in this guide use the name `ingress-tls`. + (Optional): Provide the name of the secret that contains your TLS certificate + and key. The examples in this guide use the name `ingress-tls`. _The `tlsSecretName` field is optional. You may want to use it if you already have a TLS certificate for your DNS name._ - {{< expand-wrapper >}} - {{% expand "Use cert-manager and Let's Encrypt to manage TLS certificates" %}} + {{% note %}} +Writing to and querying data from InfluxDB does not require TLS. +For simplicity, you can wait to enable TLS before moving into production. +For more information, see Phase 4 of the InfluxDB Clustered installation +process, [Secure your cluster](/influxdb/clustered/install/secure-cluster/). + {{% /note %}} -If you instead want to automatically create an [ACME](https://datatracker.ietf.org/doc/html/rfc8555) -certificate (for example, using [Let's Encrypt](https://letsencrypt.org/)), refer -to the [cert-manager documentation](https://cert-manager.io/docs/usage/ingress/). -In `ingress.tlsSecretName`, provide a name for the secret it should create. - -{{% note %}} -If you choose to use cert-manager, it's your responsibility to install and configure it. -{{% /note %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -{{% code-callout "ingress-tls|cluster-host\.com" "green" %}} + {{% code-callout "ingress-tls|cluster-host\.com" "green" %}} ```yaml ingress: @@ -414,8 +370,9 @@ ingress: #### Configure the object store -To connect your InfluxDB cluster to your object store. The information required -to connect to your object store depends on your object storage provider. +To connect your InfluxDB cluster to your object store, provide the required +credentials in your `values.yaml`. The credentials required depend on your +object storage provider. {{< tabs-wrapper >}} {{% tabs %}} @@ -454,7 +411,7 @@ objectStore: endpoint: S3_URL # Set to true to allow communication over HTTP (instead of HTTPS) - allowHttp: 'false' + allowHttp: 'true' # S3 Access Key # This can also be provided as a valueFrom: secretKeyRef: @@ -633,6 +590,46 @@ Replace the following: --- +{{% warn %}} +##### Percent-encode special symbols in PostgreSQL DSNs + +Special symbols in PostgreSQL DSNs should be percent-encoded to ensure they +are parsed correctly by InfluxDB Clustered. This is important to consider when +using DSNs containing auto-generated passwords which may include special +symbols to make passwords more secure. + +A DSN with special characters that are not percent-encoded result in an error +similar to: + +```txt +Catalog DSN error: A catalog error occurred: unhandled external error: error with configuration: invalid port number +``` + +{{< expand-wrapper >}} +{{% expand "View percent-encoded DSN example" %}} +To use the following DSN containing special characters: + +{{% code-callout "#" %}} +```txt +postgresql://postgres:meow#meow@my-fancy.cloud-database.party:5432/postgres +``` +{{% /code-callout %}} + +You must percent-encode the special characters in the connection string: + +{{% code-callout "%23" %}} +```txt +postgresql://postgres:meow%23meow@my-fancy.cloud-database.party:5432/postgres +``` +{{% /code-callout %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +For more information, see the [PostgreSQL Connection URI +docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS). +{{% /warn %}} + {{% note %}} ##### PostgreSQL instances without TLS or SSL @@ -686,281 +683,4 @@ Replace the following: --- -#### Configure your OAuth2 provider - -InfluxDB Clustered uses OAuth2 to authenticate administrative access to your cluster. -To connect your InfluxDB cluster to your OAuth2 provide, provide values for the -following fields in your `values.yaml`: - -- `admin` - - `identityProvider`: Identity provider name. - _If using Microsoft Entra ID (formerly Azure Active Directory), set the name - to `azure`_. - - `jwksEndpoint`: JWKS endpoint provide by your identity provider. - - `users`: List of OAuth2 users to grant administrative access to your - InfluxDB cluster. IDs are provided by your identity provider. - -Below are examples for **Keycloak**, **Auth0**, and **Microsoft Entra ID**, but -other OAuth2 providers should work as well: - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Keycloak](#) -[Auth0](#) -[Microsoft Entra ID](#) -{{% /code-tabs %}} -{{% code-tab-content %}} - -{{% code-callout "keycloak" "green" %}} -{{% code-placeholders "KEYCLOAK_(HOST|REALM|USER_ID)" %}} - -```yaml -admin: - # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc - # Note for Azure Active Directory it must be exactly "azure" - identityProvider: keycloak - # The JWKS endpoint provided by the Identity Provider - jwksEndpoint: |- - https://KEYCLOAK_HOST/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs - # The list of users to grant access to Clustered via influxctl - users: - # All fields are required but `firstName`, `lastName`, and `email` can be - # arbitrary values. However, `id` must match the user ID provided by Keycloak. - - id: KEYCLOAK_USER_ID - firstName: Marty - lastName: McFly - email: mcfly@influxdata.com -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`KEYCLOAK_HOST`{{% /code-placeholder-key %}}: - Host and port of your Keycloak server -- {{% code-placeholder-key %}}`KEYCLOAK_REALM`{{% /code-placeholder-key %}}: - Keycloak realm -- {{% code-placeholder-key %}}`KEYCLOAK_USER_ID`{{% /code-placeholder-key %}}: - Keycloak user ID to grant InfluxDB administrative access to - ---- - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-callout "auth0" "green" %}} -{{% code-placeholders "AUTH0_(HOST|USER_ID)" %}} - -```yaml -admin: - # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc - # Note for Azure Active Directory it must be exactly "azure" - identityProvider: auth0 - # The JWKS endpoint provided by the Identity Provider - jwksEndpoint: |- - https://AUTH0_HOST/.well-known/openid-configuration - # The list of users to grant access to Clustered via influxctl - users: - - AUTH0_USER_ID -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`AUTH0_HOST`{{% /code-placeholder-key %}}: - Host and port of your Auth0 server -- {{% code-placeholder-key %}}`AUTH0_USER_ID`{{% /code-placeholder-key %}}: - Auth0 user ID to grant InfluxDB administrative access to - ---- - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -{{% code-callout "azure" "green" %}} -{{% code-placeholders "AZURE_(USER|TENANT)_ID" %}} - -```yaml -admin: - # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc - # Note for Azure Active Directory it must be exactly "azure" - identityProvider: azure - # The JWKS endpoint provided by the Identity Provider - jwksEndpoint: |- - https://login.microsoftonline.com/AZURE_TENANT_ID/discovery/v2.0/keys - # The list of users to grant access to Clustered via influxctl - users: - - AZURE_USER_ID -``` - -{{% /code-placeholders %}} -{{% /code-callout %}} - ---- - -Replace the following: - -- {{% code-placeholder-key %}}`AZURE_TENANT_ID`{{% /code-placeholder-key %}}: - Microsoft Entra tenant ID -- {{% code-placeholder-key %}}`AZURE_USER_ID`{{% /code-placeholder-key %}}: - Microsoft Entra user ID to grant InfluxDB administrative access to - _(See [Find user IDs with Microsoft Entra ID](/influxdb/clustered/install/auth/?t=Microsoft+Entra+ID#find-user-ids-with-microsoft-entra-id))_ - ---- - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -##### Add users - -Finally, add the users you wish to have access to use `influxctl`. -Update the `admin.users` field with a list of the users. -See [Manage users](/influxdb/clustered/admin/users/) for more details. - -#### Configure the size of your cluster - -By default, an InfluxDB cluster is configured with the following: - -- **3 ingesters**: - Ensures redundancy on the write path. -- **1 compactor**: - While you can have multiple compactors, it is more efficient to scale the - compactor vertically (assign more CPU and memory) rather than horizontally - (increase the number of compactors). -- **1 querier**: - The optimal number of queriers depends on the number of concurrent queries you are - likely to have and how long they take to execute. - -The default values provide a good starting point for testing. -Once you have your cluster up and running and are looking for scaling recommendations, -please [contact the InfluxData Support team](https://support.influxdata.com). -We are happy to work with you to identify appropriate scale settings based on -your anticipated workload. - -**To use custom scale settings for your InfluxDB cluster**, modify the following fields -in your values.yaml`. If omitted, your cluster will use the default scale settings. - -- `resources` - - `ingester.requests` - - `cpu`: CPU resource units to assign to ingesters - - `memory`: Memory resource units to assign to ingesters - - `replicas`: Number of ingester replicas to provision - - `compactor.requests` - - `cpu`: CPU resource units to assign to compactors - - `memory`: Memory resource units to assign to compactors - - `replicas`: Number of compactor replicas to provision - - `querier.requests` - - `cpu`: CPU resource units to assign to queriers - - `memory`: Memory resource units to assign to queriers - - `replicas`: Number of querier replicas to provision - - `router.requests` - - `cpu`: CPU resource units to assign to routers - - `memory`: Memory resource units to assign to routers - - `replicas`: Number of router replicas to provision - -###### Related Kubernetes documentation - -- [CPU resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) -- [Memory resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory) - -{{% code-placeholders "(INGESTER|COMPACTOR|QUERIER|ROUTER)_(CPU|MEMORY|REPLICAS)" %}} - -```yml -# The following settings tune the various pods for their cpu/memory/replicas -# based on workload needs. Only uncomment the specific resources you want -# to change. Anything left commented will use the package default. -resources: - # The ingester handles data being written - ingester: - requests: - cpu: INGESTER_CPU - memory: INGESTER_MEMORY - replicas: INGESTER_REPLICAS # Default is 3 - - # The compactor reorganizes old data to improve query and storage efficiency. - compactor: - requests: - cpu: COMPACTOR_CPU - memory: COMPACTOR_MEMORY - replicas: COMPACTOR_REPLICAS # Default is 1 - - # The querier handles querying data. - querier: - requests: - cpu: QUERIER_CPU - memory: QUERIER_MEMORY - replicas: QUERIER_REPLICAS # Default is 1 - - # The router performs some api routing. - router: - requests: - cpu: ROUTER_CPU - memory: ROUTER_MEMORY - replicas: ROUTER_REPLICAS # Default is 1 -``` - -{{% /code-placeholders %}} - -### Provide a custom certificate authority bundle {note="Optional"} - -InfluxDB attempts to make TLS connections to the services it depends on; notably -the [Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog), -and the [Object store](/influxdb/clustered/reference/internals/storage-engine/#object-store). -InfluxDB validates the certificates for all of the connections it makes. - -**If you host these services yourself and you use a private or otherwise not -well-known certificate authority to issue certificates to theses services**, -InfluxDB will not recognize the issuer and will be unable to validate the certificates. -To allow InfluxDB to validate these certificates, provide a PEM certificate -bundle containing your custom certificate authority chain. - -1. Use `kubectl` to create a config map containing your PEM bundle. - Your certificate authority administrator should provide you with a - PEM-formatted certificate bundle file. - - {{% note %}} -This PEM-formatted bundle file is *not* the certificate that InfluxDB uses to -host its own TLS endpoints. This bundle establishes a chain of trust for the -external services that InfluxDB depends on. - {{% /note %}} - - In the example below, `private_ca.pem` is the certificate bundle file. - - ```sh - kubectl --namespace influxdb create configmap custom-ca --from-file=certs.pem=/path/to/private_ca.pem - ``` - - {{% note %}} -It's possible to append multiple certificates into the same bundle. -This can help if you need to include intermediate certificates or explicitly -include leaf certificates. Leaf certificates should be included before any -intermediate certificates they depend on. The root certificate should -be last in the bundle. - {{% /note %}} - -2. Update your `values.yaml` to enable custom egress and refer to your - certificate authority config map. Set `useCustomEgress` to `true` and update - the `egress` property to refer to that config map. For example: - - ```yml - useCustomEgress: true - egress: - # # If you're using a custom CA you will need to specify the full custom CA bundle here. - # # - # # NOTE: the custom CA is currently only honoured for outbound requests used to obtain - # # the JWT public keys from your identiy provider (see `jwksEndpoint`). - customCertificates: - valueFrom: - configMapKeyRef: - key: ca.pem - name: custom-ca - ``` - -{{< page-nav prev="/influxdb/clustered/install/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/licensing" nextText="Install your license" tab="Helm" >}} +{{< page-nav prev="/influxdb/clustered/install/secure-cluster/auth/" prevText="Set up authentication" next="/influxdb/clustered/install/set-up-cluster/licensing" nextText="Install your license" tab="Helm" >}} diff --git a/content/influxdb/clustered/install/deploy.md b/content/influxdb/clustered/install/set-up-cluster/deploy.md similarity index 95% rename from content/influxdb/clustered/install/deploy.md rename to content/influxdb/clustered/install/set-up-cluster/deploy.md index 67903c252..f9ae3707e 100644 --- a/content/influxdb/clustered/install/deploy.md +++ b/content/influxdb/clustered/install/set-up-cluster/deploy.md @@ -5,11 +5,13 @@ description: > menu: influxdb_clustered: name: Deploy your cluster - parent: Install InfluxDB Clustered -weight: 140 + parent: Set up your cluster +weight: 240 related: - /influxdb/clustered/admin/upgrade/ - - /influxdb/clustered/install/licensing/ + - /influxdb/clustered/install/set-up-cluster/licensing/ +aliases: + - /influxdb/clustered/install/deploy/ --- Use Kubernetes and related tools to deploy your InfluxDB cluster. @@ -202,4 +204,4 @@ influxdb iox-shared-querier-7f5998b9b-fpt62 4/4 Running 1 (6 influxdb kubit-apply-influxdb-g6qpx 0/1 Completed 0 8s ``` -{{< page-nav prev="/influxdb/clustered/install/licensing/" prevText="Install your license" next="/influxdb/clustered/install/use-your-cluster/" nextText="Use your cluster" >}} +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/licensing/" prevText="Install your license" next="/influxdb/clustered/install/set-up-cluster/test-cluster/" nextText="Test your cluster" >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/licensing.md b/content/influxdb/clustered/install/set-up-cluster/licensing.md new file mode 100644 index 000000000..0baecba07 --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/licensing.md @@ -0,0 +1,137 @@ +--- +title: Install your InfluxDB Clustered license +description: > + Install your InfluxDB Clustered license to authorize the use of the InfluxDB + Clustered software. +menu: + influxdb_clustered: + name: Install your license + parent: Set up your cluster +weight: 235 +influxdb/clustered/tags: [licensing] +related: + - /influxdb/clustered/admin/licensing/ + - /influxdb/clustered/admin/upgrade/ +aliases: + - /influxdb/clustered/install/licensing/ +--- + +Install your InfluxDB Clustered license in your cluster to authorize the use +of the InfluxDB Clustered software. + +## Install your InfluxDB license + +1. If you haven't already, + [request an InfluxDB Clustered license](https://influxdata.com/contact-sales). +2. InfluxData provides you with a `license.yml` file that encapsulates your + license token as a custom Kubernetes resource. +3. Use `kubectl` to apply and create the `License` resource in your InfluxDB + namespace: + + + + ```bash + kubectl apply --filename license.yml --namespace influxdb + ``` + +InfluxDB Clustered detects the `License` resource and extracts the credentials +into a secret required by InfluxDB Clustered Kubernetes pods. +Pods validate the license secret both at startup and periodically (roughly once +per hour) while running. + +## Upgrade from a non-licensed release + +If you are currently using a non-licensed preview release of InfluxDB Clustered +and want to upgrade to a licensed release, do the following: + +1. [Install an InfluxDB license](#install-your-influxdb-license) +2. If you [use the `AppInstance` resource configuration](/influxdb/clustered/install/set-up-cluster/configure-cluster/directly/) + to configure your cluster, in your `myinfluxdb.yml`, update the package + version defined in `spec.package.image` to use a licensed release. + + If using the InfluxDB Clustered Helm chart, update the `image.tag` property + in your `values.yaml`to use a licensed release. + + {{% warn %}} +#### Upgrade to checkpoint releases first + +When upgrading InfluxDB Clustered, always upgrade to each +[checkpoint release](/influxdb/clustered/admin/upgrade/#checkpoint-releases) +first, before proceeding to newer versions. +Upgrading past a checkpoint release without first upgrading to it may result in +corrupt or lost data. + {{% /warn %}} + +{{% code-placeholders "PACKAGE_VERSION" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[AppInstance](#) +[Helm](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```yml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +# ... +spec: + package: + # ... + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```yml +# values.yaml + +image: + tag: PACKAGE_VERSION +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-placeholders %}} + +Replace {{% code-placeholder-key %}}`PACKAGE_VERSION`{{% /code-placeholder-key %}} with +the version number to upgrade to. + +## Verify your license + +After you have activated your license, use the following signals to verify the +license is active and functioning. + +### Verify the `Secret` exists + +Run the following command to verify that the licensing activation created a +`iox-license` secret: + + + +```sh +kubectl get secret iox-license --namespace influxdb +``` + +If the secret doesn't exist, +[view `license-controller` logs](#view-license-controller-logs) for more +information or errors. + +### View `license controller` logs + +The `license controller` component creates a `Secret` named `iox-license` from +your `License`. To view `license controller` logs for troubleshooting, run the +following command: + + + +```sh +kubectl logs deployment/license-controller --namespace influxdb +``` + +For more information about InfluxDB Clustered licensing, see +[Manage your InfluxDB Clustered license](/influxdb/clustered/admin/licensing/) + +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/configure-cluster/" prevText="Configure your cluster" next="/influxdb/clustered/install/set-up-cluster/deploy/" nextText="Deploy your cluster" keepTab=true >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/prerequisites.md b/content/influxdb/clustered/install/set-up-cluster/prerequisites.md new file mode 100644 index 000000000..830dc562c --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/prerequisites.md @@ -0,0 +1,405 @@ +--- +title: Set up prerequisites +description: > + InfluxDB Clustered requires prerequisites such as a Kubernetes cluster, object storage, + a PostgreSQL-compatitble database and more. Learn how to set up and configure the + necessary prerequisites. +menu: + influxdb_clustered: + name: Prerequisites + parent: Set up your cluster +weight: 201 +aliases: + - /influxdb/clustered/install/prerequisites/ +--- + +InfluxDB Clustered requires the following prerequisite external dependencies: + +- **kubectl command line tool** +- **Kubernetes cluster** +- **kubecfg kubit operator** +- **Kubernetes ingress controller** +- **Object storage**: AWS S3 or S3-compatible storage (including Google Cloud Storage + or Azure Blob Storage) to store the InfluxDB Parquet files. +- **PostgreSQL-compatible database** _(AWS Aurora, hosted PostgreSQL, etc.)_: + Stores the [InfluxDB Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog). +- **Local or attached storage**: + Stores the Write-Ahead Log (WAL) for + [InfluxDB Ingesters](/influxdb/clustered/reference/internals/storage-engine/#ingester). + +The following walks through preparing these prerequisites. + +- [Install kubectl](#install-kubectl) +- [Set up your Kubernetes cluster](#set-up-your-kubernetes-cluster) +- [Install the kubecfg kubit operator](#install-the-kubecfg-kubit-operator) +- [Set up a Kubernetes ingress controller](#set-up-a-kubernetes-ingress-controller) +- [Set up your object store](#set-up-your-object-store) +- [Set up your PostgreSQL-compatible database](#set-up-your-postgresql-compatible-database) +- [Set up local or attached storage](#set-up-local-or-attached-storage) + +## Install kubectl + +Kubernetes provides the `kubectl` command line tool for communicating with a +Kubernetes cluster's control plane. `kubectl` is used to manage your InfluxDB +cluster. + +Follow instructions to install `kubectl` on your local machine: + +{{% note %}} +InfluxDB Clustered Kubernetes deployments require `kubectl` 1.27 or higher. +{{% /note %}} + +- [Install kubectl on Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) +- [Install kubectl on macOS](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/) +- [Install kubectl on Windows](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/) + +## Set up your Kubernetes cluster + +1. Deploy a Kubernetes cluster. The deployment process depends on your + Kubernetes environment or Kubernetes cloud provider. Refer to the + [Kubernetes documentation](https://kubernetes.io/docs/home/) or your cloud + provider's documentation for information about deploying a Kubernetes cluster. + +2. Ensure `kubectl` can connect to your Kubernetes cluster. + Your Manage [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) + defines cluster connection credentials. + +3. Create two namespaces--`influxdb` and `kubit`. Use + [`kubectl create namespace`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_namespace/) to create the + namespaces: + + + + ```bash + kubectl create namespace influxdb && \ + kubectl create namespace kubit + ``` + +4. Install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) + in the cluster and a mechanism to obtain a valid TLS certificate + (for example: [cert-manager](https://cert-manager.io/) or provide the + certificate PEM manually out of band). + To use the InfluxDB-specific ingress controller, install [Ingress NGINX](https://github.com/kubernetes/ingress-nginx). + +5. Ensure your Kubernetes cluster can access the InfluxDB container registry, + or, if running in an air-gapped environment, a local container registry to + which you can copy the InfluxDB images. + +### Cluster sizing recommendation + +As a starting point for a production workload, InfluxData recommends the +following sizing for {{% product-name %}} components: + +{{< tabs-wrapper >}} +{{% tabs %}} +[AWS](#) +[Google Cloud Platform](#) +[Microsoft Azure](#) +[On-Prem](#) +{{% /tabs %}} +{{% tab-content %}} + + +- **Catalog (PostgreSQL-compatible database) (x1):** + - _[See below](#postgresql-compatible-database-requirements)_ +- **Ingesters and Routers (x3):** + - EC2 m6i.2xlarge (8 CPU, 32 GB RAM) + - Local storage: minimum of 2 GB (high-speed SSD) +- **Queriers (x3):** + - EC2 m6i.2xlarge (8 CPU, 32 GB RAM) +- **Compactors (x1):** + - EC2 m6i.2xlarge (8 CPU, 32 GB RAM) +- **Kubernetes Control Plane (x1):** + - EC2 t3.large (2 CPU, 8 GB RAM) + + +{{% /tab-content %}} +{{% tab-content %}} + + +- **Catalog (PostgreSQL-compatible database) (x1):** + - _[See below](#postgresql-compatible-database-requirements)_ +- **Ingesters and Routers (x3):** + - GCE c2-standard-8 (8 CPU, 32 GB RAM) + - Local storage: minimum of 2 GB (high-speed SSD) +- **Queriers (x3):** + - GCE c2-standard-8 (8 CPU, 32 GB RAM) +- **Compactors (x1):** + - GCE c2-standard-8 (8 CPU, 32 GB RAM) +- **Kubernetes Control Plane (x1):** + - GCE c2d-standard-2 (2 CPU, 8 GB RAM) + + +{{% /tab-content %}} +{{% tab-content %}} + + +- **Catalog (PostgreSQL-compatible database) (x1):** + - _[See below](#postgresql-compatible-database-requirements)_ +- **Ingesters and Routers (x3):** + - Standard_D8s_v3 (8 CPU, 32 GB RAM) + - Local storage: minimum of 2 GB (high-speed SSD) +- **Queriers (x3):** + - Standard_D8s_v3 (8 CPU, 32 GB RAM) +- **Compactors (x1):** + - Standard_D8s_v3 (8 CPU, 32 GB RAM) +- **Kubernetes Control Plane (x1):** + - Standard_B2ms (2 CPU, 8 GB RAM) + + +{{% /tab-content %}} +{{% tab-content %}} + + +- **Catalog (PostgreSQL-compatible database) (x1):** + - CPU: 4-8 cores + - RAM: 16-32 GB +- **Ingesters and Routers (x3):** + - CPU: 8 cores + - RAM: 32 GB + - Local storage: 2 GB (high-speed SSD) +- **Queriers (x3):** + - CPU: 8 cores + - RAM: 32 GB +- **Compactors (x1):** + - CPU: 8 cores + - RAM: 32 GB +- **Kubernetes Control Plane (x1):** + - CPU: 2 cores + - RAM: 8 GB + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +Your sizing may need to be different based on your environment, cloud provider, +and workload, but this is a reasonable starting size for your initial testing. + +## Install the kubecfg kubit operator + +The [`kubecfg kubit` operator](https://github.com/kubecfg/kubit) (maintained by InfluxData) +simplifies the installation and management of the InfluxDB Clustered package. +It manages the application of the jsonnet templates used to install, manage, and +update an InfluxDB cluster. + +{{% note %}} +#### The InfluxDB Clustered Helm chart includes the kubit operator + +If using the [InfluxDB Clustered Helm chart](https://github.com/influxdata/helm-charts/tree/master/charts/influxdb3-clustered) +to deploy your InfluxDB cluster, you do not need to install the kubit operator +separately. The Helm chart installs the kubit operator. +{{% /note %}} + +Use `kubectl` to install the [kubecfg kubit](https://github.com/kubecfg/kubit) +operator **v0.0.18 or later**. + + + +```bash +kubectl apply -k 'https://github.com/kubecfg/kubit//kustomize/global?ref=v0.0.19' +``` + +## Set up a Kubernetes ingress controller + +[Kubernetes ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) +routes HTTP/S requests to services within the cluster and requires deploying an +[ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). +You can provide your own ingress or you can install +[Nginx Ingress Controller](https://github.com/kubernetes/ingress-nginx) to use +the InfluxDB-defined ingress. + +{{% note %}} +InfluxDB Clustered components use gRPC/HTTP2 protocols. If using an external +load balancer, you may need to explicitly enable these protocols on your load +balancers. +{{% /note %}} + +## Set up your object store + +InfluxDB Clustered supports AWS S3 or S3-compatible storage (including Google +Cloud Storage, Azure Blob Storage, and MinIO) for storing +[InfluxDB Parquet files](/influxdb/clustered/reference/internals/storage-engine/#object-store). +Refer to your object storage provider's documentation for information about +setting up an object store: + +- [Create an AWS S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) +- [Create a Google Cloud Storage bucket](https://cloud.google.com/storage/docs/creating-buckets) +- [Create an Azure Blog Storage container](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container) +- [Create a MinIO bucket](https://min.io/docs/minio/linux/reference/minio-mc/mc-mb.html) + +{{% caption %}} +\* This list does not represent all S3-compatible object stores +that work with InfluxDB Clustered. Other S3-compatible object stores should work +as well. +{{% /caption %}} + +{{% note %}} +#### Object storage recommendations + +We **strongly** recommend the following: + +- ##### Enable object versioning + + Enable object versioning in your object store. + Refer to your object storage provider's documentation for information about + enabling object versioning. + +- ##### Run the object store in a separate namespace or outside of Kubernetes + + Run the Object store in a separate namespace from InfluxDB or external to + Kubernetes entirely. Doing so makes management of the InfluxDB cluster easier + and helps to prevent accidental data loss. While deploying everything in the + same namespace is possible, we do not recommend it for production environments. +{{% /note %}} + +### Configure object storage permissions + +Ensure the identity you use to connect to your S3-compatible object store has +the correct permissions to allow InfluxDB to perform all the actions it needs to. + +{{< expand-wrapper >}} +{{% expand "View example AWS S3 access policy" %}} + +The IAM role that you use to access AWS S3 should have the following policy: + +{{% code-placeholders "S3_BUCKET_NAME" %}} +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "", + "Effect": "Allow", + "Action": [ + "s3:PutObjectAcl", + "s3:PutObject", + "s3:ListMultipartUploadParts", + "s3:GetObjectAcl", + "s3:GetObject", + "s3:DeleteObject", + "s3:AbortMultipartUpload" + ], + "Resource": "arn:aws:s3:::S3_BUCKET_NAME/*", + }, + { + "Sid": "", + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation" + ], + "Resource": "arn:aws:s3:::S3_BUCKET_NAME", + }, + { + "Sid": "", + "Effect": "Allow", + "Action": "s3:ListAllMyBuckets", + "Resource": "*", + } + ] +} +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`S3_BUCKET_NAME`{{% /code-placeholder-key %}}: Name of your AWS S3 bucket + +{{% /expand %}} + +{{% expand "View the requirements for Google Cloud Storage" %}} + +To use Google Cloud Storage (GCS) as your object store, your [IAM principal](https://cloud.google.com/iam/docs/overview) should be granted the `roles/storage.objectUser` role. +For example, if using [Google Service Accounts](https://cloud.google.com/iam/docs/service-account-overview): + +{{% code-placeholders "GCP_SERVICE_ACCOUNT|GCP_BUCKET" %}} +```bash +gcloud storage buckets add-iam-policy-binding \ + gs://GCP_BUCKET \ + --member="serviceAccount:GCP_SERVICE_ACCOUNT" \ + --role="roles/storage.objectUser" +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`GCP_SERVICE_ACCOUNT`{{% /code-placeholder-key %}}: Google Service Account name +- {{% code-placeholder-key %}}`GCP_BUCKET`{{% /code-placeholder-key %}}: GCS bucket name + +{{% /expand %}} + +{{% expand "View the requirements for Azure Blob Storage" %}} + +To use Azure Blob Storage as your object store, your [service principal](https://learn.microsoft.com/en-us/entra/architecture/service-accounts-principal) +should be granted the `Storage Blob Data Contributor` role. +This is a built-in role for Azure which encompasses common permissions. +You can assign it using the following command: + +{{% code-placeholders "PRINCIPAL|AZURE_SUBSCRIPTION|AZURE_RESOURCE_GROUP|AZURE_STORAGE_ACCOUNT|AZURE_STORAGE_CONTAINER" %}} +```bash +az role assignment create \ + --role "Storage Blob Data Contributor" \ + --assignee PRINCIPAL \ + --scope "/subscriptions/AZURE_SUBSCRIPTION/resourceGroups/AZURE_RESOURCE_GROUP/providers/Microsoft.Storage/storageAccounts/AZURE_STORAGE_ACCOUNT/blobServices/default/containers/AZURE_STORAGE_CONTAINER" +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`PRINCIPAL`{{% /code-placeholder-key %}}: A user, group, or service principal that the role should be assigned to +- {{% code-placeholder-key %}}`AZURE_SUBSCRIPTION`{{% /code-placeholder-key %}}: Your Azure subscription +- {{% code-placeholder-key %}}`AZURE_RESOURCE_GROUP`{{% /code-placeholder-key %}}: The resource group that your Azure Blob storage account belongs to +- {{% code-placeholder-key %}}`AZURE_STORAGE_ACCOUNT`{{% /code-placeholder-key %}}: Azure Blob storage account name +- {{% code-placeholder-key %}}`AZURE_STORAGE_CONTAINER`{{% /code-placeholder-key %}}: Container name in your Azure Blob storage account + +{{% /expand %}} + +{{< /expand-wrapper >}} + +{{% note %}} +To configure permissions with MinIO, use the +[example AWS access policy](#view-example-aws-s3-access-policy). +{{% /note %}} + +## Set up your PostgreSQL-compatible database + +The [InfluxDB Catalog](/influxdb/clustered/reference/internals/storage-engine/#catalog) +that stores metadata related to your time series data requires a PostgreSQL or +PostgreSQL-compatible database _(AWS Aurora, hosted PostgreSQL, etc.)_. +The process for installing and setting up your PostgreSQL-compatible database +depends on the database and database provider you use. +Refer to your database's or provider's documentation for setting up your +PostgreSQL-compatible database. + +### PostgreSQL-compatible database requirements + +- PostgreSQL version **13 or 14**. +- **Minimum of 4 GB of memory** or equivalent provider-specific units. +- To avoid conflicts and prevent issues caused by shared usage with other + applications, ensure that your PostgreSQL-compatible instance is dedicated + exclusively to InfluxDB. + +{{% note %}} +We **strongly** recommended running the PostgreSQL-compatible database +in a separate namespace from InfluxDB or external to Kubernetes entirely. +Doing so makes management of the InfluxDB cluster easier and helps to prevent +accidental data loss. + +While deploying everything in the same namespace is possible, we do not +recommend it for production environments. +{{% /note %}} + +## Set up local or attached storage + +The [InfluxDB Ingester](/influxdb/clustered/reference/internals/storage-engine/#ingester) +needs local or attached storage to store the Write-Ahead Log (WAL). +The read and write speed of the attached storage affects the write performance +of the Ingester, so the faster the storage device, the better your write +performance will be. +The recommended minimum size of the local storage is 2 gibibytes (`2Gi`). + +Installation and setup of local or attached storage depends on your underlying +hardware or cloud provider. Refer to your provider's documentation for +information about installing and configuring local storage. + +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/" prevText="Back" next="/influxdb/clustered/install/set-up-cluster/configure-cluster" nextText="Configure your cluster" >}} diff --git a/content/influxdb/clustered/install/set-up-cluster/test-cluster.md b/content/influxdb/clustered/install/set-up-cluster/test-cluster.md new file mode 100644 index 000000000..0bda6c511 --- /dev/null +++ b/content/influxdb/clustered/install/set-up-cluster/test-cluster.md @@ -0,0 +1,176 @@ +--- +title: Test your InfluxDB Cluster +description: > + Test to ensure your InfluxDB cluster can write and query data successfully. +menu: + influxdb_clustered: + name: Test your cluster + parent: Set up your cluster +weight: 250 +--- + +With your InfluxDB cluster deployed and running, test to ensure you can +successfully write and query data from InfluxDB. + +1. [Download and install influxctl](#download-and-install-influxctl) +1. [Retrieve your cluster's admin token](#retrieve-your-clusters-admin-token) +1. [Configure influxctl to connect to your cluster](#configure-influxctl-to-connect-to-your-cluster) +1. [Create a new database](#create-a-new-database) +1. [Write test data to the new database](#write-test-data-to-the-new-database) +1. [Query the test data from your database](#query-the-test-data-from-your-database) + +## Download and install influxctl + +[`influxctl`](/influxdb/clustered/reference/cli/influxctl/) is a command line tool +that lets you manage, write data to, and query data from your InfluxDB cluster +from your local machine. + +Download and install influxctl + +## Retrieve your cluster's admin token + +InfluxDB Clustered generates a valid access token (known as the _admin token_) +and stores it as a secret in your cluster's `influxdb` namespace. +During this phase of the installation process, use the admin token with +`influxctl` in lieu of configuring and using an identity provider. + +Use `kubectl` to retrieve the admin token from your `influxdb` namespace secret +store and copy it to a file: + +```sh +kubectl get secrets/admin-token \ + --template={{.data.token}} \ + --namespace influxdb | base64 -d > token.json +``` + +## Configure influxctl to connect to your cluster + +Create an [`influxctl` connection profile](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) +for your InfluxDB cluster. Connection profiles are stored in a `config.toml` +file on your local machine and contain the credentials necessary to connect to +and authorize with your InfluxDB cluster. + +1. Create a file named `config.toml` with the following contents: + + {{< code-placeholders "INFLUXDB_(HOST|PORT)|DIRECTORY_PATH" >}} +```toml +[[profile]] + name = "default" + product = "clustered" + host = "{{< influxdb/host >}}" + port = "INFLUXDB_PORT" + + [profile.auth.token] + token_file = "/DIRECTORY_PATH/token.json" +``` + {{< /code-placeholders >}} + + In the example above, replace the following: + + - {{% code-placeholder-key %}}`INFLUXDB_PORT`{{% /code-placeholder-key %}}: + The port to use to connect to your InfluxDB cluster. + - {{% code-placeholder-key %}}`DIRECTORY_PATH`{{% /code-placeholder-key %}}: + The directory path to your admin token file, `token.json`. + + {{% note %}} +To set your InfluxDB cluster host, click +**{{< icon "cog" "v2" >}} Set InfluxDB cluster URL** below the codeblock above +and provide your cluster's host. This will update your cluster's host in all +code examples. + {{% /note %}} + +2. Make this configuration file available to `influxctl` in one of the following + ways: + + - Include the `--config` flag with all `influxctl` commands to specify the + filepath of your `config.toml`. + - Store the `config.toml` file at the + [default location](/influxdb/clustered/reference/cli/influxctl/#default-connection-profile-store-location) + that `influxctl` expects to find connection profiles based on your + operating system. If your connection profile is in the default location, + you do not need to include the `--config` flag with your `influxctl` commands. + +{{% note %}} +#### Connection configuration examples + +In the examples below, replace {{% code-placeholder-key %}}`CONFIG_PATH`{{% /code-placeholder-key %}} +with the directory path to your connection configuration file. If you placed +your configuration file in the default location for your operating system, remove +`--config /CONFIG_PATH/config.toml` from the example commands before running them. +{{% /note %}} + +## Create a new database + +Use [`influxctl database create`](/influxdb/clustered/reference/cli/influxctl/database/create/) +to create a new database named `testdb`. Include the following: + +- _(Optional)_ The path to your connection profile configuration file. +- The database name--`testdb`. + +{{% code-placeholders "CONFIG_PATH" %}} +```sh +influxctl --config /CONFIG_PATH/config.toml database create testdb +``` +{{% /code-placeholders %}} + +## Write test data to the new database + +Use [`influxctl write`](/influxdb/clustered/reference/cli/influxctl/write/) to +write the following test data to your `testdb` database. Provide the following: + +- _(Optional)_ The path to your connection profile configuration file. +- The database name--`testdb`. +- [Line protocol](/influxdb/clustered/reference/syntax/line-protocol/) to write + to InfluxDB. + +{{% influxdb/custom-timestamps %}} + +{{% code-placeholders "CONFIG_PATH" %}} +```bash +influxctl --config /CONFIG_PATH/config.toml write \ + --database testdb \ + "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000000000000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000000000000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600000000000 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600000000000 +" +``` +{{% /code-placeholders %}} + +{{% /influxdb/custom-timestamps %}} + +## Query the test data from your database + +Use [`influxctl query`](/influxdb/clustered/reference/cli/influxctl/query/) to +query the test data from your `testdb` database. Provide the following: + +- _(Optional)_ The path to your connection profile configuration file. +- The database name--`testdb`. +- The SQL query to execute. + +{{% code-placeholders "CONFIG_PATH" %}} +```bash +influxctl --config /CONFIG_PATH/config.toml query \ + --database testdb \ + "SELECT * FROM home" +``` +{{% /code-placeholders %}} + + +This should return results similar to: + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | +| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | +| 0 | 21.4 | Living Room | 21.4 | 2022-01-01T09:00:00Z | +| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | + +{{% /influxdb/custom-timestamps %}} + +If the query successfully returns data, your InfluxDB cluster is set up and functional. + +{{< page-nav prev="/influxdb/clustered/install/set-up-cluster/test-cluster/" prevText="Test your cluster" next="/influxdb/clustered/install/customize-cluster/" nextText="Phase 2: Customize your cluster">}} + diff --git a/content/influxdb/clustered/install/use-your-cluster.md b/content/influxdb/clustered/install/use-your-cluster.md index 9e7debdbe..ae7e5bf3e 100644 --- a/content/influxdb/clustered/install/use-your-cluster.md +++ b/content/influxdb/clustered/install/use-your-cluster.md @@ -7,9 +7,11 @@ menu: name: Use your cluster parent: Install InfluxDB Clustered weight: 150 +draft: true --- -Now that your InfluxDB cluster is deployed, you can use and test it. +Now that you have deployed your InfluxDB cluster, it's ready for you to use +and test. Use the [Get started with InfluxDB clustered guide](/influxdb/clustered/get-started/setup/) to test your new InfluxDB cluster. diff --git a/content/influxdb/clustered/query-data/execute-queries/client-libraries/go.md b/content/influxdb/clustered/query-data/execute-queries/client-libraries/go.md index 5d30caf43..e7ac09109 100644 --- a/content/influxdb/clustered/query-data/execute-queries/client-libraries/go.md +++ b/content/influxdb/clustered/query-data/execute-queries/client-libraries/go.md @@ -21,7 +21,7 @@ list_code_example: | ```go import ( "context" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -94,7 +94,7 @@ to install a recent version of the Go programming language for your system. In your terminal, enter the following command to download and install the client library: ```sh -go get github.com/InfluxCommunity/influxdb3-go +go get github.com/InfluxCommunity/influxdb3-go/v2 ``` - [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go) {{< req text="\* " color="magenta" >}}: Provides the `influxdb3` package and also installs the [Apache `arrow` module](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries. @@ -137,8 +137,7 @@ import ( "text/tabwriter" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" - "github.com/apache/arrow/go/v13/arrow" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query() error { @@ -185,10 +184,9 @@ func Query() error { fmt.Fprintln(w, "Process each row as key-value pairs:") for iterator2.Next() { row := iterator2.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) @@ -234,8 +232,7 @@ import ( "text/tabwriter" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" - "github.com/apache/arrow/go/v13/arrow" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func InfluxQL() error { @@ -287,10 +284,9 @@ func InfluxQL() error { fmt.Fprintln(w, "Process each row as key-value pairs:") for iterator2.Next() { row := iterator2.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.TimeUnit(arrow.Nanosecond)). + time := (row["time"].(time.Time)). Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/clustered/query-data/influxql/parameterized-queries.md b/content/influxdb/clustered/query-data/influxql/parameterized-queries.md index 40d5f52c5..6147ca0c5 100644 --- a/content/influxdb/clustered/query-data/influxql/parameterized-queries.md +++ b/content/influxdb/clustered/query-data/influxql/parameterized-queries.md @@ -257,8 +257,7 @@ import ( "os" "text/tabwriter" "time" - "github.com/apache/arrow/go/v14/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query(query string, parameters influxdb3.QueryParameters, @@ -301,10 +300,10 @@ func Query(query string, parameters influxdb3.QueryParameters, // Process each row as key-value pairs. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339 format) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.Nanosecond).Format(time.RFC3339) + time := (row["time"].(time.Time)). + Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/clustered/query-data/sql/parameterized-queries.md b/content/influxdb/clustered/query-data/sql/parameterized-queries.md index bceca9d89..0458658ce 100644 --- a/content/influxdb/clustered/query-data/sql/parameterized-queries.md +++ b/content/influxdb/clustered/query-data/sql/parameterized-queries.md @@ -254,8 +254,7 @@ import ( "os" "text/tabwriter" "time" - "github.com/apache/arrow/go/v14/arrow" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func Query(query string, parameters influxdb3.QueryParameters) error { @@ -297,10 +296,10 @@ func Query(query string, parameters influxdb3.QueryParameters) error { // Process each row as key-value pairs. for iterator.Next() { row := iterator.Value() - // Use Go arrow and time packages to format unix timestamp + // Use Go time package to format unix timestamp // as a time with timezone layout (RFC3339 format) - time := (row["time"].(arrow.Timestamp)). - ToTime(arrow.Nanosecond).Format(time.RFC3339) + time := (row["time"].(time.Time)). + Format(time.RFC3339) fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", time, row["room"], row["co"], row["hum"], row["temp"]) diff --git a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan.md b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan.md index 898b01496..c5c347183 100644 --- a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan.md +++ b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan.md @@ -25,7 +25,7 @@ By learning how to generate and interpret reports for the query plan, you can better understand how the query is executed and identify bottlenecks that affect the performance of your query. For example, if the query plan reveals that your query reads a large number of Parquet files, -you can then take steps to [optimize your query](/influxdb/clustered/query-data/optimize-queries/), such as add filters to read less data or +you can then take steps to [optimize your query](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/), such as add filters to read less data or configure your cluster to store fewer and larger files. - [Use EXPLAIN keywords to view a query plan](#use-explain-keywords-to-view-a-query-plan) @@ -113,7 +113,7 @@ Plans are in _tree format_--each plan is an upside-down tree in which execution and data flow from _leaf nodes_, the innermost steps in the plan, to outer _branch nodes_. Whether reading a logical or physical plan, keep the following in mind: -- Start at the the _leaf nodes_ and read upward. +- Start at the _leaf nodes_ and read upward. - At the top of the plan, the _root node_ represents the final, encompassing step. In a [physical plan](/influxdb/clustered/reference/internals/query-plan/#physical-plan), each step is an [`ExecutionPlan` node](/influxdb/clustered/reference/internals/query-plan/#executionplan-nodes) that receives expressions for input data and output requirements, and computes a partition of data. @@ -770,4 +770,4 @@ Operator structure for aggregating, sorting, and final output. - `SortPreservingMergeExec: [city@0 ASC NULLS LAST]`: Merges and sorts the four sorted streams for the final output. In the preceding examples, the `EXPLAIN` report shows the query plan without executing the query. -To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/clustered/reference/sql/explain/#explain-analyze) to generate the report and use [tracing](/influxdb/clustered/query-data/optimize-queries/#enable-trace-logging) for further debugging, if necessary. +To view runtime metrics, such as execution time for a plan and its operators, use [`EXPLAIN ANALYZE`](/influxdb/clustered/reference/sql/explain/#explain-analyze) to generate the report and use [tracing](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/#enable-trace-logging) for further debugging, if necessary. diff --git a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries.md b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries.md index b7751578e..1877840c7 100644 --- a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries.md +++ b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries.md @@ -16,6 +16,7 @@ related: aliases: - /influxdb/clustered/query-data/execute-queries/optimize-queries/ - /influxdb/clustered/query-data/execute-queries/analyze-query-plan/ + - /influxdb/clustered/query-data/optimize-queries/ --- Optimize SQL and InfluxQL queries to improve performance and reduce their memory and compute (CPU) requirements. @@ -24,38 +25,26 @@ Learn how to use observability tools to analyze query execution and view metrics - [Why is my query slow?](#why-is-my-query-slow) - [Strategies for improving query performance](#strategies-for-improving-query-performance) - [Query only the data you need](#query-only-the-data-you-need) -- [Analyze and troubleshoot queries](#analyze-and-troubleshoot-queries) +- [Recognize and address bottlenecks](#recognize-and-address-bottlenecks) + ## Why is my query slow? -Query performance depends on time range and complexity. -If a query is slower than you expect, it might be due to the following reasons: +Query performance depends on factors like the time range and query complexity. +If a query is slower than expected, consider the following potential causes: -- It queries data from a large time range. -- It includes intensive operations, such as querying many string values or `ORDER BY` sorting or re-sorting large amounts of data. +- The query spans a large time range, which increases the amount of data being processed. +- The query performs intensive operations, such as: + - Sorting or re-sorting large datasets with `ORDER BY`. + - Querying many string values, which can be computationally expensive. ## Strategies for improving query performance -The following design strategies generally improve query performance and resource use: +The following design strategies generally improve query performance and resource usage: -- Follow [schema design best practices](/influxdb/clustered/write-data/best-practices/schema-design/) to make querying easier and more performant. -- [Query only the data you need](#query-only-the-data-you-need). -- [Downsample data](/influxdb/clustered/process-data/downsample/) to reduce the amount of data you need to query. - -Some bottlenecks may be out of your control and are the result of a suboptimal execution plan, such as: - -- Applying the same sort (`ORDER BY`) to already sorted data. -- Retrieving many Parquet files from the Object store--the same query performs better if it retrieves fewer - though, larger - files. -- Querying many overlapped Parquet files. -- Performing a large number of table scans. - -{{% note %}} -#### Analyze query plans to view metrics and recognize bottlenecks - -To view runtime metrics for a query, such as the number of files scanned, use -the [`EXPLAIN ANALYZE` keywords](/influxdb/clustered/reference/sql/explain/#explain-analyze) -and learn how to [analyze a query plan](/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/). -{{% /note %}} +- Follow [schema design best practices](/influxdb/clustered/write-data/best-practices/schema-design/) to simplify and improve queries. +- [Query only the data you need](#query-only-the-data-you-need) to reduce unnecessary processing. +- [Downsample data](/influxdb/clustered/process-data/downsample/) to decrease the volume of data queried. ### Query only the data you need @@ -87,7 +76,30 @@ two queries is minimal. In a table with over 1000 columns, the `SELECT *` query is slower and less efficient. -## Analyze and troubleshoot queries +## Recognize and address bottlenecks -Learn how to [analyze a query plan](/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/) -to troubleshoot queries and find performance bottlenecks. +To identify performance bottlenecks, learn how to [analyze a query plan](/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/). +Query plans provide runtime metrics, such as the number of files scanned, that may reveal inefficiencies in query execution. + +> [!Note] +> +> #### Request help to troubleshoot queries +> +> Some bottlenecks may result from suboptimal query [execution plans](/influxdb/clustered/reference/internals/query-plan/#physical-plan) and are outside your control--for example: +> +> - Sorting (`ORDER BY`) data that is already sorted. +> - Retrieving numerous small Parquet files from the object store instead of fewer, larger files. +> - Querying many overlapped Parquet files. +> - Performing a high number of table scans. +> +> If you've followed steps to [optimize](#why-is-my-query-slow) and +> [troubleshoot a query](/influxdb/clustered/query-data/troubleshoot-and-optimize/troubleshoot/), +> but it still doesn't meet performance requirements, +> see how to [report query performance issues](/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues/). +> +> #### Query trace logging +> +> Currently, customers cannot enable trace logging for {{% product-name omit="Clustered" %}} clusters. +> InfluxData engineers can use query plans and trace logging to help pinpoint performance bottlenecks in a query. +> +> See how to [report query performance issues](/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues/). diff --git a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues.md b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues.md index 0bd923a5b..9b4dfafc9 100644 --- a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues.md +++ b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues.md @@ -1,19 +1,25 @@ --- title: Report query performance issues description: > - A comprehensive guide on ensuring a quick turnaround when troubleshooting query performance. + Follow guidelines to help InfluxData engineers troubleshoot and resolve query performance issues. menu: influxdb_clustered: name: Report query performance issues parent: Troubleshoot and optimize queries weight: 402 +related: + - /influxdb/clustered/admin/query-system-data/ + - /influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/ --- -These guidelines are intended to faciliate collaboration between InfluxData -engineers and you. They allow engineers to conduct timely analyses of any performance -issues that you have not been able to resolve following our [guide on -troubleshooting and optimizing -queries](/influxdb/clustered/query-data//troubleshoot-and-optimize). +Use these guidelines to work with InfluxData engineers to troubleshoot and resolve query performance issues. + +> [!Note] +> #### Optimize your query +> +> Before reporting a query performance problem, +> see the [troubleshooting and optimization guide](/influxdb/clustered/query-data/troubleshoot-and-optimize) +> to learn how to optimize your query and reduce compute and memory requirements. 1. [Send InfluxData output artifacts](#send-influxdata-output-artifacts) 2. [Document your test process](#document-your-test-process) @@ -23,13 +29,17 @@ queries](/influxdb/clustered/query-data//troubleshoot-and-optimize). 6. [Reduce query noise](#reduce-query-noise) 7. [Establish baseline single-query performance](#establish-baseline-single-query-performance) 8. [Run queries at multiple load scales](#run-queries-at-multiple-load-scales) -9. [Gather debug info](#gather-debug-info) +9. [Gather debug information](#gather-debug-information) 1. [Kubernetes-specific information](#kubernetes-specific-information) 2. [Clustered-specific information](#clustered-specific-information) 3. [Query analysis](#query-analysis) 1. [EXPLAIN](#explain) 2. [EXPLAIN VERBOSE](#explain-verbose) 3. [EXPLAIN ANALYZE](#explain-analyze) +10. [Gather system information](#gather-system-information) + - [Collect table information](#collect-table-information) + - [Collect compaction information for the table](#collect-compaction-information-for-the-table) + - [Collect partition information for multiple tables](#collect-partition-information-for-multiple-tables) {{% note %}} Please note that this document may change from one support engagement to the @@ -48,12 +58,13 @@ Send InfluxData engineers all produced artifacts for analysis. ### Document your test process -There currently is no standardized performance test suite that you can run in -your environment, so please document your process so it can be replicated. -Include the following: +Currently, {{% product-name %}} doesn't provide a standardized performance test +suite that you can run in your cluster. +Please document your test process so that InfluxData engineers can replicate +it--include the following: - The steps you take when performance testing. -- Timestamps of the tests you perform so they can be correlated with associated logs. +- Timestamps of your test runs, to correlate tests with logs. ### Document your environment @@ -75,7 +86,7 @@ including the following: {{% note %}} #### If possible, provide a synthetic dataset -If you can reproduce the performance issue with a synthetic dataset and your +If you can reproduce the performance issue with a synthetic dataset, and your process and environment are well-documented, InfluxData engineers _may_ be able to reproduce the issue, shorten the feedback cycle, and resolve the issue sooner. @@ -89,8 +100,8 @@ conditions that reproduce your issue. ### Establish query performance degradation conditions The most effective way to investigate query performance is to have a good understanding of -the conditions in which you don't see the expected performance. Things to think about -and provide: +the conditions in which you don't see the expected performance. +Consider the following: - Does this always happen, or only sometimes? - If only sometimes, is it at a consistent time of day or over a consistent period? @@ -103,37 +114,25 @@ and provide: ### Reduce query noise -To get a sense of the baseline performance of your system without the -noise of additional queries, test in an environment that doesn't have periodic -or intermittent queries running concurrently. +Test in an environment without periodic or intermittent queries to measure baseline system performance without additional query noise. -Additionally, when running multiple tests with different queries, let the system -recover between tests by waiting at least a minute after receiving a query result -before executing the next query. +When running multiple tests with different queries, allow the system to recover between tests. +Wait at least one minute after receiving a query result before executing the next query. ### Establish baseline single-query performance -To get a sense of the baseline performance of your system without the -noise of additional queries, perform at least some of your testing with -single queries in isolation from one another. - -This is may be useful for the purposes of analysis by InfluxData engineers even if a -single query in isolation isn't enough to reproduce the issue you are having. +Perform some tests with single queries in isolation to measure baseline performance. +This approach may not always reproduce your issue but can provide useful data for analysis by InfluxData engineers. ### Run queries at multiple load scales -Once you've established baseline performance with a single query and your -performance issue can't be replicated with a single query, use a systematic -approach to identify the scale at which it does become a problem. -This involves systematic incremental increases to your query -concurrency until you identify a threshold at which the issue can be -reproduced. +If the issue isn't replicated after [reducing query noise](#reduce-query-noise) +and [establishing baseline single-query performance](#establish-baseline-single-query-performance), +systematically increase query concurrency to reproduce the problem and identify +the scale at which it occurs--for example, run the following test plan. -This, along with information about your Kubernetes environment, can provide -insight necessary to recommend changes to your configuration to improve -query performance characteristis as your usage scales. - -As an example, consider the following test plan outline: +> [!Note] +> You might need to scale the example plan up or down, as necessary, to reproduce the problem. 1. Turn off intermittent or periodic InfluxDB queries and allow the cluster to recover. 2. Run Query A and allow the cluster to recover for 1 minute. @@ -141,17 +140,26 @@ As an example, consider the following test plan outline: 4. Run 10 concurrent instances of Query A and allow the cluster to recover for 1 minute. 5. Run 20 concurrent instances of Query A and allow the cluster to recover for 1 minute. 6. Run 40 concurrent instances of Query A and allow the cluster to recover for 1 minute. -7. Provide InfluxData the debug information [described below](#gather-debug-info). +7. Provide InfluxData the [debug information](#gather-debug-information) associated + with each test run. -{{% note %}} -This is just an example. You don't have to go beyond the scale where queries get slower -but you may also need to go further than what's outlined here. -{{% /note %}} +Your test findings and associated debug information +from your Kubernetes environment can help recommend configuration changes to +improve query performance as your usage scales. -### Gather debug info + + +### Gather debug information + +Shortly after testing a problematic query against your InfluxDB cluster, +collect the following debug information. #### Kubernetes-specific information @@ -165,7 +173,7 @@ kubectl cluster-info dump --namespace influxdb --output-directory "${DATETIME}-c tar -czf "${DATETIME}-cluster-info.tar.gz" "${DATETIME}-cluster-info/" ``` -#### Clustered-Specific Info +#### Clustered-specific information **Outputs:** @@ -173,6 +181,9 @@ tar -czf "${DATETIME}-cluster-info.tar.gz" "${DATETIME}-cluster-info/" #### Query analysis +[Use `EXPLAIN` commands](/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/#use-explain-keywords-to-view-a-query-plan) + to output query plan information for a long-running query. + **Outputs (InfluxQL):** - `explain.csv` @@ -185,9 +196,6 @@ tar -czf "${DATETIME}-cluster-info.tar.gz" "${DATETIME}-cluster-info/" - `explain-verbose.txt` - `explain-analyze.txt` -For any known long-running queries, it may be helpful to execute variations of -the `EXPLAIN` command on them. - In the examples below, replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: @@ -310,3 +318,97 @@ curl --get "https://{{< influxdb/host >}}/query" \ {{< /code-tabs-wrapper >}} {{% /code-placeholders %}} + +### Gather system information + +> [!Warn] +> +> #### May impact cluster performance +> +> Querying InfluxDB v3 system tables may impact write and query +> performance of your {{< product-name omit=" Clustered" >}} cluster. +> Use filters to [optimize queries to reduce impact to your cluster](/influxdb/clustered/admin/query-system-data/#optimize-queries-to-reduce-impact-to-your-cluster). +> +> +> +> #### System tables are subject to change +> +> System tables are not part of InfluxDB's stable API and may change with new releases. +> The provided schema information and query examples are valid as of **September 20, 2024**. +> If you detect a schema change or a non-functioning query example, please +> [submit an issue](https://github.com/influxdata/docs-v2/issues/new/choose). +> +> + +If queries are slow for a specific table, run the following system queries to +collect information for troubleshooting: + +- [Collect table information](#collect-table-information) +- [Collect compaction information for the table](#collect-compaction-information-for-the-table) +- [Collect partition information for multiple tables](#collect-partition-information-for-multiple-tables) + +To [optimize system queries](/influxdb/clustered/admin/query-system-data/#optimize-queries-to-reduce-impact-to-your-cluster), use `table_name`, `partition_key`, and +`partition_id` filters. +In your queries, replace the following: + +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the table to retrieve partitions for +- {{% code-placeholder-key %}}`PARTITION_ID`{{% /code-placeholder-key %}}: a [partition ID](/influxdb/clustered/admin/query-system-data/#retrieve-a-partition-id) (int64) +- {{% code-placeholder-key %}}`PARTITION_KEY`{{% /code-placeholder-key %}}: a [partition key](/influxdb/clustered/admin/custom-partitions/#partition-keys) + derived from the table's partition template. + The default format is `%Y-%m-%d` (for example, `2024-01-01`). + +#### Collect table information + +{{% code-placeholders "TABLE_NAME" %}} +```sql +SELECT * +FROM system.tables +WHERE table_name = 'TABLE_NAME'; +``` +{{% /code-placeholders%}} + +#### Collect compaction information for the table + +Query the `system.compactor` table to collect compaction information--for example, run one of the following +queries: + +{{% code-placeholders "TABLE_NAME|PARTITION_KEY" %}} + +```sql +SELECT * +FROM system.compactor +WHERE + table_name = 'TABLE_NAME' + AND partition_key = 'PARTITION_KEY'; +``` + +{{% /code-placeholders %}} + +{{% code-placeholders "TABLE_NAME|PARTITION_ID" %}} + +```sql +SELECT * +FROM system.compactor +WHERE + table_name = 'TABLE_NAME' + AND partition_id = 'PARTITION_ID'; +``` + +{{% /code-placeholders %}} + +#### Collect partition information for multiple tables + +If the same queries are slow on more than 1 table, also run the following query to collect the size and +number of partitions for all tables: + +{{% code-placeholders "TABLE_NAME" %}} +```sql +SELECT table_name, + COUNT(*) as partition_count, + MAX(last_new_file_created_at) as last_new_file_created_at, + SUM(total_size_mb) as total_size_mb +FROM system.partitions +WHERE table_name IN ('foo', 'bar', 'baz') +GROUP BY table_name; +``` +{{% /code-placeholders%}} diff --git a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/troubleshoot.md b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/troubleshoot.md index ce6ac0473..f1d35b68a 100644 --- a/content/influxdb/clustered/query-data/troubleshoot-and-optimize/troubleshoot.md +++ b/content/influxdb/clustered/query-data/troubleshoot-and-optimize/troubleshoot.md @@ -20,6 +20,8 @@ Troubleshoot SQL and InfluxQL queries that return unexpected results. - [Why doesn't my query return data?](#why-doesnt-my-query-return-data) - [Optimize slow or expensive queries](#optimize-slow-or-expensive-queries) +- [Analyze your queries](#analyze-your-queries) +- [Request help to troubleshoot queries](#request-help-to-troubleshoot-queries) ## Why doesn't my query return data? @@ -48,4 +50,34 @@ If a query times out or returns an error, it might be due to the following: If a query is slow or uses too many compute resources, limit the amount of data that it queries. -See how to [optimize queries](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/) and use tools to view runtime metrics, identify bottlenecks, and debug queries. +See how to [optimize queries](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/). + +## Analyze your queries + +Use the following tools to retrieve system query information, analyze query execution, +and find performance bottlenecks: + +- [Analyze a query plan](/influxdb/clustered/query-data/troubleshoot-and-optimize/analyze-query-plan/) +- [Retrieve `system.queries` information for a query](/influxdb/clustered/query-data/troubleshoot-and-optimize/system-information/) + +#### Request help to troubleshoot queries + +Some bottlenecks may result from suboptimal query [execution plans](/influxdb/clustered/reference/internals/query-plan/#physical-plan) and are outside your control--for example: + +- Sorting (`ORDER BY`) data that is already sorted +- Retrieving numerous small Parquet files from the object store, instead of fewer, larger files +- Querying many overlapped Parquet files +- Performing a high number of table scans + +If you have followed steps to [optimize](/influxdb/clustered/query-data/troubleshoot-and-optimize/optimize-queries/) and [troubleshoot a query](#why-doesnt-my-query-return-data), +and it isn't meeting your performance requirements, +see how to [report query performance issues](/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues/). + +> [!Note] +> +> #### Query trace logging +> +> Currently, customers cannot enable trace logging for {{% product-name omit="Clustered" %}} clusters. +> InfluxData engineers can use query plans and trace logging to help pinpoint performance bottlenecks in a query. +> +> See how to [report query performance issues](/influxdb/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues/). diff --git a/content/influxdb/clustered/reference/cli/influxctl/_index.md b/content/influxdb/clustered/reference/cli/influxctl/_index.md index a7c0bc8ee..6fda5d1c0 100644 --- a/content/influxdb/clustered/reference/cli/influxctl/_index.md +++ b/content/influxdb/clustered/reference/cli/influxctl/_index.md @@ -17,7 +17,7 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster. - [Usage](#usage) - [Commands](#commands) -- [Flags](#command-flags) +- [Global flags](#global-flags) - [Download and install influxctl](#download-and-install-influxctl) - [Configure connection profiles](#configure-connection-profiles) - [Authentication](#authentication) @@ -25,14 +25,14 @@ administrative tasks in an {{< product-name omit=" Clustered" >}} cluster. ## Usage ```sh -influxctl [flags] [command] +influxctl [global-flags] [command] ``` ## Commands | Command | Description | | :-------------------------------------------------------------------- | :------------------------------------- | -| [auth](/influxdb/clustered/reference/cli/influxctl/auth/) | Log in to or log out of InfluxDB v3 | +| [auth](/influxdb/clustered/reference/cli/influxctl/auth/) | Log in to or log out of InfluxDB v3 | | [cluster](/influxdb/clustered/reference/cli/influxctl/cluster/) | List InfluxDB v3 cluster information | | [database](/influxdb/clustered/reference/cli/influxctl/database/) | Manage InfluxDB v3 databases | | [help](/influxdb/clustered/reference/cli/influxctl/help/) | Output `influxctl` help information | @@ -45,15 +45,16 @@ influxctl [flags] [command] ## Global flags -| Flag | | Description | -| :--- | :---------- | :--------------------------------------------------------- | -| | `--debug` | Enable debug logging | -| | `--account` | Override account ID value in configuration file | -| | `--cluster` | Override cluster ID value in configuration file | -| | `--config` | Path to configuration file to use | -| | `--profile` | Specify a connection profile to use (default is `default`) | -| | `--trace` | Enable more verbose debug logging | -| `-h` | `--help` | Show help | +| Flag | | Description | +| :--- | :---------- | :----------------------------------------------------------- | +| | `--debug` | Enable debug logging | +| | `--account` | Override account ID value in configuration file | +| | `--cluster` | Override cluster ID value in configuration file | +| | `--config` | Path to configuration file to use | +| | `--profile` | Specify a connection profile to use (default is `default`) | +| | `--timeout` | Specify a timeout duration for API calls (default is `1m0s`) | +| | `--trace` | Enable more verbose debug logging | +| `-h` | `--help` | Show help | --- @@ -354,7 +355,6 @@ If stored at a non-default location, include the `--config` flag with each ## OAuth2 client authorization settings [profile.auth.oauth2] client_id = "OAUTH_CLIENT_ID" - client_secret = "" scopes = [""] parameters = { audience = "" } token_url = "OAUTH_TOKEN_URL" diff --git a/content/influxdb/clustered/reference/cli/influxctl/database/create.md b/content/influxdb/clustered/reference/cli/influxctl/database/create.md index d18d7cbb0..3655cf412 100644 --- a/content/influxdb/clustered/reference/cli/influxctl/database/create.md +++ b/content/influxdb/clustered/reference/cli/influxctl/database/create.md @@ -155,8 +155,8 @@ influxctl database create \ ### Create a database with a custom partition template The following example creates a new `mydb` database and applies a partition -template that partitions by two tags (`room` and `sensor-type`) and by week using -the time format `%Y wk:%W`: +template that partitions by two tags (`room` and `sensor-type`) and by day using +the time format `%Y-%m-%d`: @@ -166,7 +166,7 @@ influxctl database create \ --template-tag room \ --template-tag sensor-type \ --template-tag-bucket customerID,1000 \ - --template-timeformat '%Y wk:%W' \ + --template-timeformat '%Y-%m-%d' \ mydb ``` diff --git a/content/influxdb/clustered/reference/cli/influxctl/query.md b/content/influxdb/clustered/reference/cli/influxctl/query.md index e21721b69..3e9297d49 100644 --- a/content/influxdb/clustered/reference/cli/influxctl/query.md +++ b/content/influxdb/clustered/reference/cli/influxctl/query.md @@ -418,7 +418,7 @@ Querying system tables can impact the overall performance of your InfluxDB's stable API and are subject to change. {{% /warn %}} -{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} +{{% code-placeholders "DATABASE_(TOKEN|NAME)|TABLE_NAME" %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} @@ -433,7 +433,7 @@ influxctl query \ --enable-system-tables \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ - "SELECT * FROM system.tables" + "SELECT * FROM system.tables WHERE table_name = 'TABLE_NAME'" ``` {{% /influxdb/custom-timestamps %}} {{% /code-tab-content %}} diff --git a/content/influxdb/clustered/reference/cli/influxctl/table/create.md b/content/influxdb/clustered/reference/cli/influxctl/table/create.md index 1d7d7792b..48c1c13b6 100644 --- a/content/influxdb/clustered/reference/cli/influxctl/table/create.md +++ b/content/influxdb/clustered/reference/cli/influxctl/table/create.md @@ -82,8 +82,8 @@ influxctl table create DATABASE_NAME TABLE_NAME ### Create a table with a custom partition template The following example creates a new table and applies a partition -template that partitions by two tags (`room` and `sensor-type`) and by week using -the time format `%Y wk:%W`: +template that partitions by two tags (`room` and `sensor-type`) and by day using +the time format `%Y-%m-%d`: {{% code-placeholders "(DATABASE|TABLE)_NAME" %}} ```sh @@ -91,7 +91,7 @@ influxctl table create \ --template-tag room \ --template-tag sensor-type \ --template-tag-bucket customerID,1000 \ - --template-timeformat '%Y wk:%W' \ + --template-timeformat '%Y-%m-%d' \ DATABASE_NAME \ TABLE_NAME ``` diff --git a/content/influxdb/clustered/reference/client-libraries/flight/python-flight.md b/content/influxdb/clustered/reference/client-libraries/flight/python-flight.md index 3b8de4561..d2f2640ab 100644 --- a/content/influxdb/clustered/reference/client-libraries/flight/python-flight.md +++ b/content/influxdb/clustered/reference/client-libraries/flight/python-flight.md @@ -21,7 +21,7 @@ list_code_example: | sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, - '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', diff --git a/content/influxdb/clustered/reference/client-libraries/v2/_index.md b/content/influxdb/clustered/reference/client-libraries/v2/_index.md index 0be0dff52..3b1ba8b31 100644 --- a/content/influxdb/clustered/reference/client-libraries/v2/_index.md +++ b/content/influxdb/clustered/reference/client-libraries/v2/_index.md @@ -1,7 +1,7 @@ --- title: InfluxDB v2 API client libraries description: > - InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). + InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). View the list of available client libraries. weight: 101 menu: @@ -25,7 +25,7 @@ prepend: ## Client libraries for InfluxDB 2.x and 1.8+ InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs. -InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints). +InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). Functionality varies among client libraries. InfluxDB client libraries are maintained by the InfluxDB community. diff --git a/content/influxdb/clustered/reference/client-libraries/v2/javascript/nodejs/install.md b/content/influxdb/clustered/reference/client-libraries/v2/javascript/nodejs/install.md index a50e10d4e..8e779acf2 100644 --- a/content/influxdb/clustered/reference/client-libraries/v2/javascript/nodejs/install.md +++ b/content/influxdb/clustered/reference/client-libraries/v2/javascript/nodejs/install.md @@ -33,11 +33,13 @@ prepend: 3. In your terminal, create a directory for your Node.js project and change to it. ```sh - mkdir influx-node-app && cd $_ + mkdir influx-node-app && cd influx-node-app ``` 4. Enter the following command to generate an npm package for your project. - The `npm` package manager is included with Node.js. + + - `npm`: the package manager included with Node.js + - `-y`: uses defaults for the package and bypasses prompts ```sh npm init -y @@ -53,15 +55,21 @@ Follow these steps to initialize the TypeScript project: ```sh npm i -g typescript && npm i --save-dev @types/node ``` -2. Create a TypeScript configuration with default values. + +2. Enter the following command to create a TypeScript configuration + (`tsconfig.json`) with default values: ```sh tsc --init ``` -3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. +3. Run the TypeScript compiler. + To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. + + + ```sh - tsc -w -p + tsc --watch ``` ## Install dependencies diff --git a/content/influxdb/clustered/reference/client-libraries/v3/go.md b/content/influxdb/clustered/reference/client-libraries/v3/go.md index 88f37e030..3662e9687 100644 --- a/content/influxdb/clustered/reference/client-libraries/v3/go.md +++ b/content/influxdb/clustered/reference/client-libraries/v3/go.md @@ -20,7 +20,7 @@ to write and query data stored in an {{% product-name %}} database. ## Installation ```sh -go get github.com/InfluxCommunity/influxdb3-go +go get github.com/InfluxCommunity/influxdb3-go/v2 ``` ## Importing the package @@ -31,7 +31,7 @@ Import the package: ```go import ( - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) ``` @@ -75,7 +75,7 @@ Initializes and returns a `influxdb3.Client` instance with the following: package main import ( - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" ) func main() { @@ -175,4 +175,4 @@ query := `SELECT * AND time <= 1641124000s + 8h` queryOptions := influxdb3.QueryOptions{QueryType: influxdb3.InfluxQL} iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query) -``` \ No newline at end of file +``` diff --git a/content/influxdb/clustered/reference/client-libraries/v3/python.md b/content/influxdb/clustered/reference/client-libraries/v3/python.md index dca98614a..7c5b12a58 100644 --- a/content/influxdb/clustered/reference/client-libraries/v3/python.md +++ b/content/influxdb/clustered/reference/client-libraries/v3/python.md @@ -8,48 +8,45 @@ menu: parent: v3 client libraries identifier: influxdb3-python influxdb/clustered/tags: [Flight API, python, gRPC, SQL, client libraries] -metadata: [influxdb3-python v0.5.0] +metadata: [influxdb3-python v0.10.0] weight: 201 aliases: - /influxdb/clustered/reference/client-libraries/v3/pyinflux3/ related: - /influxdb/clustered/query-data/execute-queries/troubleshoot/ -list_code_example: > - + ```python - from influxdb_client_3 import(InfluxDBClient3, - WriteOptions, - write_client_options) + # Example: Write and query data - # Instantiate batch writing options for the client + # Write sensor data in batches from a CSV file to a database + client.write_file(file='./data/home-sensor-data.csv', + timestamp_column='time', + tag_columns=["room"]) - write_options = WriteOptions() - wco = write_client_options(write_options=write_options) - - # Instantiate an InfluxDB v3 client - - with InfluxDBClient3(host=f"{{< influxdb/host >}}", - database=f"DATABASE_NAME", - token=f"DATABASE_TOKEN", - write_client_options=wco) as client: - - # Write data in batches - client.write_file(file='./data/home-sensor-data.csv', timestamp_column='time', - tag_columns=["room"]) - - # Execute a query and retrieve data formatted as a PyArrow Table - - table = client.query( + # Execute a query and retrieve data from the last 90 days + table = client.query( '''SELECT * FROM home WHERE time >= now() - INTERVAL '90 days' ORDER BY time''') - ``` + + # This script assumes the client object is correctly configured + # with your database name, token, and host URL. + # After the script runs, the table variable contains the data + # formatted as a PyArrow table. + ``` --- The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python) @@ -958,7 +955,7 @@ fh.close() client = InfluxDBClient3(host=f"{{< influxdb/host >}}", database=f"DATABASE_NAME", token=f"DATABASE_TOKEN", - fco=flight_client_options(tls_root_certs=cert)) + flight_client_options=flight_client_options(tls_root_certs=cert)) ``` {{% /code-placeholders %}} diff --git a/content/influxdb/clustered/reference/glossary.md b/content/influxdb/clustered/reference/glossary.md index 307e6d483..bb3ab1632 100644 --- a/content/influxdb/clustered/reference/glossary.md +++ b/content/influxdb/clustered/reference/glossary.md @@ -46,7 +46,8 @@ Related entries: ### aggregate A function that returns an aggregated value across a set of points. -For a list of available aggregation functions, see [SQL aggregate functions](/influxdb/clustered/reference/sql/functions/aggregate/). +For a list of available aggregation functions, +see [SQL aggregate functions](/influxdb/clustered/reference/sql/functions/aggregate/). @@ -333,6 +334,7 @@ Related entries: [field](#field), [field key](#field-key), [field set](#field-set), +[tag set](#tag-set), [tag value](#tag-value), [timestamp](#timestamp) @@ -372,7 +374,7 @@ Related entries: A function is an operation that performs a specific task. Functions take input, operate on that input, and then return output. For a complete list of available SQL functions, see -[SQL functions](/inflxudb/clustered/reference/sql/functions/). +[SQL functions](/influxdb/clustered/reference/sql/functions/). @@ -403,10 +405,10 @@ Identifiers are tokens that refer to specific database objects such as database names, field keys, measurement names, tag keys, etc. Related entries: -[database](#database) +[database](#database), [field key](#field-key), [measurement](#measurement), -[tag key](#tag-key), +[tag key](#tag-key) ### influx @@ -425,8 +427,8 @@ and other required processes. ### InfluxDB -An open source time series database (TSDB) developed by InfluxData. -Written in Go and optimized for fast, high-availability storage and retrieval of +An open source time series database (TSDB) developed by InfluxData, optimized +for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet of Things sensor data, and real-time analytics. @@ -438,8 +440,8 @@ The SQL-like query language used to query data in InfluxDB. Telegraf input plugins actively gather metrics and deliver them to the core agent, where aggregator, processor, and output plugins can operate on the metrics. -In order to activate an input plugin, it needs to be enabled and configured in -Telegraf's configuration file. +To activate an input plugin, enable and configure it in the +Telegraf configuration file. Related entries: [aggregator plugin](#aggregator-plugin), @@ -752,7 +754,7 @@ relative to [now](#now). The minimum retention period is **one hour**. Related entries: -[bucket](#bucket), +[bucket](#bucket) ### retention policy (RP) @@ -839,8 +841,8 @@ Related entries: ### series -A collection of data in the InfluxDB data structure that share a common -_measurement_, _tag set_, and _field key_. +In the InfluxDB 3 data structure, a collection of data that share a common +_measurement_ and _tag set_. Related entries: [field set](#field-set), @@ -849,12 +851,13 @@ Related entries: ### series cardinality -The number of unique measurement, tag set, and field key combinations in an InfluxDB database. +The number of unique measurement (table), tag set, and field key combinations in an InfluxDB database. For example, assume that an InfluxDB database has one measurement. The single measurement has two tag keys: `email` and `status`. -If there are three different `email`s, and each email address is associated with two -different `status`es, the series cardinality for the measurement is 6 +If there are three different `email` tag values, +and each email address is associated with two +different `status` tag values, then the series cardinality for the measurement is 6 (3 × 2 = 6): | email | status | @@ -869,7 +872,7 @@ different `status`es, the series cardinality for the measurement is 6 In some cases, performing this multiplication may overestimate series cardinality because of the presence of dependent tags. Dependent tags are scoped by another tag and do not increase series cardinality. -If we add the tag `firstname` to the example above, the series cardinality +If we add the tag `firstname` to the preceding example, the series cardinality would not be 18 (3 × 2 × 3 = 18). The series cardinality would remain unchanged at 6, as `firstname` is already scoped by the `email` tag: @@ -1048,7 +1051,7 @@ Related entries: [aggregate](#aggregate), [function](#function), [selector](#sel The InfluxDB v1 and v2 data storage format that allows greater compaction and higher write and read throughput than B+ or LSM tree implementations. -The TSM storage engine has been replaced by [the InfluxDB v3 storage engine (IOx)](#iox). +The TSM storage engine has been replaced by the [InfluxDB v3 storage engine (IOx)](#iox). Related entries: [IOx](#iox) @@ -1143,9 +1146,6 @@ Points in the WAL are queryable and persist through a system reboot. On process start, all points in the WAL must be flushed before the system accepts new writes. -Related entries: -[tsm](#tsm-time-structured-merge-tree) - ### windowing Grouping data based on specified time intervals. diff --git a/content/influxdb/clustered/reference/influxql/_index.md b/content/influxdb/clustered/reference/influxql/_index.md index d9214a790..e58c86725 100644 --- a/content/influxdb/clustered/reference/influxql/_index.md +++ b/content/influxdb/clustered/reference/influxql/_index.md @@ -1,786 +1,13 @@ --- title: InfluxQL reference documentation -list_title: InfluxQL -description: InfluxQL is an SQL-like query language for interacting with data in InfluxDB. +description: > + InfluxQL is an SQL-like query language for interacting with data in InfluxDB. menu: influxdb_clustered: parent: Reference name: InfluxQL reference identifier: influxql-reference -weight: 143 +weight: 102 + +source: /shared/influxql-v3-reference/_index.md --- - -InfluxQL (Influx Query Language) is an SQL-like query language used to interact -with InfluxDB and work with times series data. - -{{% warn %}} -#### InfluxQL feature support - -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features are still being implemented. -For information about the current implementation status of InfluxQL features, -see [InfluxQL feature support](/influxdb/clustered/reference/influxql/feature-support/). -{{% /warn %}} - -- [Notation](#notation) -- [Query representation](#query-representation) - - [Characters](#characters) - - [Letters and digits](#letters-and-digits) - - [Identifiers](#identifiers) - - [Keywords](#keywords) - - [Literals](#literals) -- [Queries](#queries) -- [Statements](#statements) -- [Clauses](#clauses) -- [Expressions](#expressions) -- [Comments](#comments) -- [Other](#other) -- [Result set](#result-set) - - - -## Notation - -The syntax is specified using Extended Backus-Naur Form ("EBNF"). -EBNF is the same notation used in the [Go programming language specification](https://golang.org/ref/spec). - -```go -Production = production_name "=" [ Expression ] "." . -Expression = Alternative { "|" Alternative } . -Alternative = Term { Term } . -Term = production_name | token [ "…" token ] | Group | Option | Repetition . -Group = "(" Expression ")" . -Option = "[" Expression "]" . -Repetition = "{" Expression "}" . -``` - -Notation operators in order of increasing precedence: - -``` -| alternation -() grouping -[] option (0 or 1 times) -{} repetition (0 to n times) -``` - -## Query representation - -### Characters - -InfluxQL is Unicode text encoded in [UTF-8](http://en.wikipedia.org/wiki/UTF-8). - -``` -newline = /* the Unicode code point U+000A */ . -unicode_char = /* an arbitrary Unicode code point except newline */ . -``` - -### Letters and digits - -Letters are the set of ASCII letters and the underscore (`_`, U+005F). - -Only decimal digits are supported. - -``` -letter = ascii_letter | "_" . -ascii_letter = "A" … "Z" | "a" … "z" . -digit = "0" … "9" . -``` - -### Identifiers - -Identifiers are tokens that refer to -[database](/influxdb/clustered/reference/glossary/#database) names, -[retention policy](/influxdb/clustered/reference/glossary/#retention-policy-rp) names, -[measurement](/influxdb/clustered/reference/glossary/#measurement) names, -[tag keys](/influxdb/clustered/reference/glossary/#tag-key), and -[field keys](/influxdb/clustered/reference/glossary/#field-key). - -The rules are as follows: - -- Double-quoted identifiers can contain any Unicode character except for a new line. -- Double-quoted identifiers can also contain escaped `"` characters (i.e. `\"`). -- Double-quoted identifiers can include InfluxQL [keywords](#keywords). -- Unquoted identifiers must start with an upper or lowercase ASCII character or "_". -- Unquoted identifiers may contain only ASCII letters, decimal digits, and "_". - -``` -identifier = unquoted_identifier | quoted_identifier . -unquoted_identifier = ( letter ) { letter | digit } . -quoted_identifier = `"` unicode_char { unicode_char } `"` . -``` - -#### Examples - -``` -cpu -_cpu_stats -"1h" -"anything really" -"1_Crazy-1337.identifier>NAME👍" -``` - -### Keywords - -``` -ALL ALTER ANY AS ASC BEGIN -BY CREATE CONTINUOUS DATABASE DATABASES DEFAULT -DELETE DESC DESTINATIONS DIAGNOSTICS DISTINCT DROP -DURATION END EVERY EXPLAIN FIELD FOR -FROM GRANT GRANTS GROUP GROUPS IN -INF INSERT INTO KEY KEYS KILL -LIMIT SHOW MEASUREMENT MEASUREMENTS NAME OFFSET -ON ORDER PASSWORD POLICY POLICIES PRIVILEGES -QUERIES QUERY READ REPLICATION RESAMPLE RETENTION -REVOKE SELECT SERIES SET SHARD SHARDS -SLIMIT SOFFSET STATS SUBSCRIPTION SUBSCRIPTIONS TAG -TO USER USERS VALUES WHERE WITH -WRITE -``` - -If you use an InfluxQL keyword as an -[identifier](/influxdb/clustered/reference/glossary/#identifier), -double-quote the identifier in every query. - -The `time` keyword is a special case. -`time` can be a -database name, -[measurement](/influxdb/clustered/reference/glossary/#measurement) name, -[retention policy](/influxdb/clustered/reference/glossary/#retention-policy-rp) name, and -[user](/influxdb/clustered/reference/glossary/#user) name. - -In those cases, you don't need to double-quote `time` in queries. - -`time` can't be a [field key](/influxdb/clustered/reference/glossary/#field-key) or -[tag key](/influxdb/clustered/reference/glossary/#tag-key); -InfluxDB rejects writes with `time` as a field key or tag key and returns an error. - - -### Literals - -#### Integers - -InfluxQL supports decimal integer literals. -Hexadecimal and octal literals aren't currently supported. - -``` -int_lit = ( "1" … "9" ) { digit } . -``` - -#### Floats - -InfluxQL supports floating-point literals. -Exponents aren't currently supported. - -``` -float_lit = int_lit "." int_lit . -``` - -#### Strings - -String literals must be surrounded by single quotes. -Strings may contain `'` characters as long as they are escaped (i.e., `\'`). - -``` -string_lit = `'` { unicode_char } `'` . -``` - -#### Durations - -Duration literals specify a length of time. -An integer literal followed immediately (with no spaces) by one of the duration units listed below is interpreted as a duration literal. -Durations can be specified with mixed units. - -##### Duration units - -| Units | Meaning | -| ------ | --------------------------------------- | -| ns | nanoseconds (1 billionth of a second) | -| u or µ | microseconds (1 millionth of a second) | -| ms | milliseconds (1 thousandth of a second) | -| s | second | -| m | minute | -| h | hour | -| d | day | -| w | week | - -``` -duration_lit = int_lit duration_unit . -duration_unit = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" . -``` - -#### Dates & Times - -Unlike other notations used in InfluxQL, the date and time literal format isn't specified by EBNF. -InfluxQL date and time is specified using Go's time parsing format and -[reference date](https://pkg.go.dev/time#pkg-constants) written in the format required by InfluxQL. -The reference date time is: - -InfluxQL reference date time: January 2nd, 2006 at 3:04:05 PM - -``` -time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02" . -``` - -#### Booleans - -``` -bool_lit = TRUE | FALSE . -``` - -#### Regular Expressions - -``` -regex_lit = "/" { unicode_char } "/" . -``` - -**Comparators:** -`=~` matches against -`!~` doesn't match against - -{{% note %}} -InfluxQL supports using regular expressions when specifying: - -- [field keys](/influxdb/clustered/reference/glossary/#field-key) and [tag keys](/influxdb/clustered/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/clustered/reference/influxql/select/) -- [measurements](/influxdb/clustered/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/clustered/reference/influxql/select/#from-clause) -- [tag values](/influxdb/clustered/reference/glossary/#tag-value) and - string [field values](/influxdb/clustered/reference/glossary/#field-value) - in the [`WHERE` clause](/influxdb/clustered/reference/influxql/where/) -- [tag keys](/influxdb/clustered/reference/glossary/#tag-key) in the - [`GROUP BY` clause](/influxdb/clustered/reference/influxql/group-by/) - -Currently, InfluxQL doesn't support using regular expressions to match non-string -field values in the `WHERE` clause, [databases](/influxdb/clustered/reference/glossary/#database), -and [retention polices](/influxdb/clustered/reference/glossary/#retention-policy-rp). -{{% /note %}} - -## Queries - -A query is composed of one or more statements separated by a semicolon (`;`). - -``` -query = statement { ";" statement } . - -statement = explain_stmt | - explain_analyze_stmt | - select_stmt | - show_field_keys_stmt | - show_measurements_stmt | - show_retention_policies_stmt | - show_tag_keys_stmt | - show_tag_values_with_key = stmt . -``` - - - -## Statements - -### EXPLAIN - -Parses and plans the query, and then prints a summary of estimated costs. - -Many SQL engines use the `EXPLAIN` statement to show join order, join algorithms, and predicate and expression pushdown. -Since InfluxQL doesn't support joins, the cost of an InfluxQL query is typically a function of the total series accessed, the number of iterator accesses to a TSM file, and the number of TSM blocks that need to be scanned. - -A query plan generated by `EXPLAIN` contains the following elements: - -- expression -- auxiliary fields -- number of shards -- number of series -- cached values -- number of files -- number of blocks -- size of blocks - -``` -explain_stmt = "EXPLAIN" select_stmt . -``` - -#### Example - -```sql -> explain select sum(pointReq) from "_internal"."monitor"."write" group by hostname; -> QUERY PLAN ------- -EXPRESSION: sum(pointReq::integer) -NUMBER OF SHARDS: 2 -NUMBER OF SERIES: 2 -CACHED VALUES: 110 -NUMBER OF FILES: 1 -NUMBER OF BLOCKS: 1 -SIZE OF BLOCKS: 931 -``` - -### EXPLAIN ANALYZE - -Executes the specified `SELECT` statement and returns data about the query performance and storage during runtime, visualized as a tree. Use this statement to analyze query performance and storage, including [execution time](#execution-time) and [planning time](#planning-time), and the [iterator type](#iterator-type) and [cursor type](#cursor-type). - -For example, if you execute the following statement: - -```sql -> explain analyze select mean(usage_steal) from cpu where time >= '2018-02-22T00:00:00Z' and time < '2018-02-22T12:00:00Z' -``` - -The output is similar to the following: - -```sql -EXPLAIN ANALYZE ---------------- -. -└── select - ├── execution_time: 2.25823ms - ├── planning_time: 18.381616ms - ├── total_time: 20.639846ms - └── field_iterators - ├── labels - │ └── statement: SELECT mean(usage_steal::float) FROM telegraf."default".cpu - └── expression - ├── labels - │ └── expr: mean(usage_steal::float) - └── create_iterator - ├── labels - │ ├── measurement: cpu - │ └── shard_id: 608 - ├── cursors_ref: 779 - ├── cursors_aux: 0 - ├── cursors_cond: 0 - ├── float_blocks_decoded: 431 - ├── float_blocks_size_bytes: 1003552 - ├── integer_blocks_decoded: 0 - ├── integer_blocks_size_bytes: 0 - ├── unsigned_blocks_decoded: 0 - ├── unsigned_blocks_size_bytes: 0 - ├── string_blocks_decoded: 0 - ├── string_blocks_size_bytes: 0 - ├── boolean_blocks_decoded: 0 - ├── boolean_blocks_size_bytes: 0 - └── planning_time: 14.805277ms``` -``` - -{{% note %}} -`EXPLAIN ANALYZE` ignores query output, so the cost of serialization to JSON or -CSV isn't accounted for. -{{% /note %}} - -##### execution_time - -Shows the amount of time the query took to execute, including reading the time series data, performing operations as data flows through iterators, and draining processed data from iterators. Execution time doesn't include the time taken to serialize the output into JSON or other formats. - -##### planning_time - -Shows the amount of time the query took to plan. -Planning a query in InfluxDB requires a number of steps. Depending on the complexity of the query, planning can require more work and consume more CPU and memory resources than executing the query. For example, the number of series keys required to execute a query affects how quickly the query is planned and how much memory the planning requires. - -First, InfluxDB determines the effective time range of the query and selects the shards to access. -Next, for each shard and each measurement, InfluxDB performs the following steps: - -1. Select matching series keys from the index, filtered by tag predicates in the `WHERE` clause. -2. Group filtered series keys into tag sets based on the `GROUP BY` dimensions. -3. Enumerate each tag set and create a cursor and iterator for each series key. -4. Merge iterators and return the merged result to the query executor. - -##### iterator type - -`EXPLAIN ANALYZE` supports the following iterator types: - -- `create_iterator` node represents work done by the local influxd instance──a complex composition of nested iterators combined and merged to produce the final query output. -- (InfluxDB Enterprise only) `remote_iterator` node represents work done on remote machines. - -For more information about iterators, see [Understanding iterators](#understanding-iterators). - -##### cursor type - -`EXPLAIN ANALYZE` distinguishes 3 cursor types. While the cursor types have the same data structures and equal CPU and I/O costs, each cursor type is constructed for a different reason and separated in the final output. Consider the following cursor types when tuning a statement: - -- cursor_ref: Reference cursor created for `SELECT` projections that include a function, such as `last()` or `mean()`. -- cursor_aux: Auxiliary cursor created for simple expression projections (not selectors or an aggregation). For example, `SELECT foo FROM m` or `SELECT foo+bar FROM m`, where `foo` and `bar` are fields. -- cursor_cond: Condition cursor created for fields referenced in a `WHERE` clause. - -For more information about cursors, see [Understanding cursors](#understanding-cursors). - -##### block types - -`EXPLAIN ANALYZE` separates storage block types, and reports the total number of -blocks decoded and their size (in bytes) on disk. The following block types are supported: - -| Type | Description | -| :--------- | :------------------------------------ | -| `float` | 64-bit IEEE-754 floating-point number | -| `integer` | 64-bit signed integer | -| `unsigned` | 64-bit unsigned integer | -| `boolean` | 1-bit, LSB encoded | -| `string` | UTF-8 string | - -### SELECT - -``` -select_stmt = "SELECT" fields from_clause [ where_clause ] - [ group_by_clause ] [ order_by_clause ] [ limit_clause ] - [ offset_clause ] [ slimit_clause ] [ soffset_clause ] [ timezone_clause ] . -``` - -#### Example - -Select from measurements grouped by the day with a timezone - -```sql -SELECT mean("value") FROM "cpu" GROUP BY region, time(1d) fill(0) tz('America/Chicago') -``` - - - - - - - -### SHOW FIELD KEYS - -``` -show_field_keys_stmt = "SHOW FIELD KEYS" [on_clause] [ from_clause ] . -``` - -#### Examples - -```sql --- show field keys and field value data types from all measurements -SHOW FIELD KEYS - --- show field keys and field value data types from specified measurement -SHOW FIELD KEYS FROM "cpu" -``` - -### SHOW MEASUREMENTS - -``` -show_measurements_stmt = "SHOW MEASUREMENTS" [on_clause] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all measurements -SHOW MEASUREMENTS - --- show measurements where region tag = 'uswest' AND host tag = 'serverA' -SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' - --- show measurements that start with 'h2o' -SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ -``` - - - - - - - -### SHOW TAG KEYS - -``` -show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ] - [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all tag keys -SHOW TAG KEYS - --- show all tag keys from the cpu measurement -SHOW TAG KEYS FROM "cpu" - --- show all tag keys from the cpu measurement where the region key = 'uswest' -SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' - --- show all tag keys where the host key = 'serverA' -SHOW TAG KEYS WHERE "host" = 'serverA' -``` - -### SHOW TAG VALUES - -``` -show_tag_values_stmt = "SHOW TAG VALUES" [on_clause] [ from_clause ] with_tag_clause [ where_clause ] - [ limit_clause ] [ offset_clause ] . -``` - -#### Examples - -```sql --- show all tag values across all measurements for the region tag -SHOW TAG VALUES WITH KEY = "region" - --- show tag values from the cpu measurement for the region tag -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" - --- show tag values across all measurements for all tag keys that do not include the letter c -SHOW TAG VALUES WITH KEY !~ /.*c.*/ - --- show tag values from the cpu measurement for region & host tag keys where service = 'redis' -SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' -``` - - - -## Clauses - -``` -from_clause = "FROM" measurements . - -group_by_clause = "GROUP BY" dimensions fill(fill_option). - -limit_clause = "LIMIT" int_lit . - -offset_clause = "OFFSET" int_lit . - -slimit_clause = "SLIMIT" int_lit . - -soffset_clause = "SOFFSET" int_lit . - -timezone_clause = tz(string_lit) . - -on_clause = "ON" db_name . - -order_by_clause = "ORDER BY" sort_fields . - -where_clause = "WHERE" expr . - -with_measurement_clause = "WITH MEASUREMENT" ( "=" measurement | "=~" regex_lit ) . - -with_tag_clause = "WITH KEY" ( "=" tag_key | "!=" tag_key | "=~" regex_lit | "IN (" tag_keys ")" ) . -``` - -## Expressions - -``` -binary_op = "+" | "-" | "*" | "/" | "%" | "&" | "|" | "^" | "AND" | - "OR" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" . - -expr = unary_expr { binary_op unary_expr } . - -unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit | - float_lit | bool_lit | duration_lit | regex_lit . -``` - -## Default time range - -The default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to _now_. - -## Comments - -Use comments with InfluxQL statements to describe your queries. - -- A single line comment begins with two hyphens (`--`) and ends where InfluxDB detects a line break. - This comment type cannot span several lines. -- A multi-line comment begins with `/*` and ends with `*/`. This comment type can span several lines. - Multi-line comments do not support nested multi-line comments. - -## Other - -``` -alias = "AS" identifier . - -back_ref = ( policy_name ".:MEASUREMENT" ) | - ( db_name "." [ policy_name ] ".:MEASUREMENT" ) . - -db_name = identifier . - -dimension = expr . - -dimensions = dimension { "," dimension } . - -field_key = identifier . - -field = expr [ alias ] . - -fields = field { "," field } . - -fill_option = "null" | "none" | "previous" | int_lit | float_lit | "linear" . - -host = string_lit . - -measurement = measurement_name | - ( policy_name "." measurement_name ) | - ( db_name "." [ policy_name ] "." measurement_name ) . - -measurements = measurement { "," measurement } . - -measurement_name = identifier | regex_lit . - -policy_name = identifier . - -retention_policy = identifier . - -retention_policy_name = "NAME" identifier . - -series_id = int_lit . - -sort_field = field_key [ ASC | DESC ] . - -sort_fields = sort_field { "," sort_field } . - -tag_key = identifier . - -tag_keys = tag_key { "," tag_key } . - -var_ref = measurement . -``` diff --git a/content/influxdb/clustered/reference/influxql/feature-support.md b/content/influxdb/clustered/reference/influxql/feature-support.md index ce3bb42f6..1cfe6c190 100644 --- a/content/influxdb/clustered/reference/influxql/feature-support.md +++ b/content/influxdb/clustered/reference/influxql/feature-support.md @@ -9,173 +9,6 @@ menu: influxdb_clustered: parent: influxql-reference weight: 220 + +source: /shared/influxql-v3-reference/feature-support.md --- - -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features are still being implemented. -This page provides information about the current implementation status of -InfluxQL features. - -- [In-progress features](#in-progress-features) - - [Time zones](#time-zones) - - [SLIMIT clause](#slimit-clause) - - [SOFFSET clause](#soffset-clause) - - [Metaqueries](#metaqueries) -- [Function support](#function-support) - - [Aggregate functions](#aggregate-functions) - - [Selector functions](#selector-functions) - - [Transformations](#transformations) - - [Technical and predictive analysis](#technical-and-predictive-analysis) - -## In-progress features - -### Time zones - -InfluxQL in {{< product-name >}} does not currently support the time zone clause, -which applies a time zone offset to UTC timestamps in query results. - - - -### SLIMIT clause - -InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause, -which limits the number of [series](/influxdb/clustered/reference/glossary/#series) -returned in query results. - - - -### SOFFSET clause - -InfluxQL in {{< product-name >}} does not currently support the `SOFFSET` clause, -which specifies the number of [series](/influxdb/clustered/reference/glossary/#series) -to skip before returning results. - - - -### Metaqueries - -InfluxQL metaqueries return information about the schema of time series data -stored in InfluxDB. -The following table provides information about what metaqueries are available in -{{< product-name >}}: - -| Metaquery | Supported | -| :------------------------------------------------------------ | :----------------------: | -| SHOW DATABASES | | -| **SHOW RETENTION POLICIES** | **{{< icon "check" >}}** | -| **SHOW MEASUREMENTS** | **{{< icon "check" >}}** | -| SHOW SERIES | | -| SHOW SERIES CARDINALITY | | -| **SHOW TAG KEYS** | **{{< icon "check" >}}** | -| SHOW TAG KEY CARDINALITY | | -| **SHOW TAG VALUES** | **{{< icon "check" >}}** | -| SHOW TAG VALUES CARDINALITY | | -| **SHOW FIELD KEYS** | **{{< icon "check" >}}** | -| SHOW FIELD KEYS CARDINALITY | | - -{{% note %}} -#### Cardinality metaqueries - -With the InfluxDB 3.0 storage engine, series cardinality is no longer a limiting -factor for database performance. -Cardinality-related metaqueries will likely not be supported with the InfluxDB 3.0 -storage engine. -{{% /note %}} - -## Function support - -### Aggregate functions - -| Function | Supported | -| :---------------------------------------------------------------------------------- | :----------------------: | -| [COUNT()](/influxdb/clustered/reference/influxql/functions/aggregates/#count) | **{{< icon "check" >}}** | -| [DISTINCT()](/influxdb/clustered/reference/influxql/functions/aggregates/#distinct) | **{{< icon "check" >}}** | -| INTEGRAL() | | -| [MEAN()](/influxdb/clustered/reference/influxql/functions/aggregates/#mean) | **{{< icon "check" >}}** | -| [MEDIAN()](/influxdb/clustered/reference/influxql/functions/aggregates/#median) | **{{< icon "check" >}}** | -| [MODE()](/influxdb/clustered/reference/influxql/functions/aggregates/#mode) | **{{< icon "check" >}}** | -| [SPREAD()](/influxdb/clustered/reference/influxql/functions/aggregates/#spread) | **{{< icon "check" >}}** | -| [STDDEV()](/influxdb/clustered/reference/influxql/functions/aggregates/#stddev) | **{{< icon "check" >}}** | -| [SUM()](/influxdb/clustered/reference/influxql/functions/aggregates/#sum) | **{{< icon "check" >}}** | - - - -### Selector functions - -| Function | Supported | -| :------------------------------------------------------------------------------------- | :----------------------: | -| [BOTTOM()](/influxdb/clustered/reference/influxql/functions/selectors/#bottom) | **{{< icon "check" >}}** | -| [FIRST()](/influxdb/clustered/reference/influxql/functions/selectors/#first) | **{{< icon "check" >}}** | -| [LAST()](/influxdb/clustered/reference/influxql/functions/selectors/#last) | **{{< icon "check" >}}** | -| [MAX()](/influxdb/clustered/reference/influxql/functions/selectors/#max) | **{{< icon "check" >}}** | -| [MIN()](/influxdb/clustered/reference/influxql/functions/selectors/#min) | **{{< icon "check" >}}** | -| [PERCENTILE()](/influxdb/clustered/reference/influxql/functions/selectors/#percentile) | **{{< icon "check" >}}** | -| SAMPLE() | | -| [TOP()](/influxdb/clustered/reference/influxql/functions/selectors/#top) | **{{< icon "check" >}}** | - - - -### Transformations - -| Function | Supported | -| :--------------------------------------------------------------------------------------------------------------------- | :----------------------: | -| [ABS()](/influxdb/clustered/reference/influxql/functions/transformations/#abs) | **{{< icon "check" >}}** | -| [ACOS()](/influxdb/clustered/reference/influxql/functions/transformations/#acos) | **{{< icon "check" >}}** | -| [ASIN()](/influxdb/clustered/reference/influxql/functions/transformations/#asin) | **{{< icon "check" >}}** | -| [ATAN()](/influxdb/clustered/reference/influxql/functions/transformations/#atan) | **{{< icon "check" >}}** | -| [ATAN2()](/influxdb/clustered/reference/influxql/functions/transformations/#atan2) | **{{< icon "check" >}}** | -| [CEIL()](/influxdb/clustered/reference/influxql/functions/transformations/#ceil) | **{{< icon "check" >}}** | -| [COS()](/influxdb/clustered/reference/influxql/functions/transformations/#cos) | **{{< icon "check" >}}** | -| [CUMULATIVE_SUM()](/influxdb/clustered/reference/influxql/functions/transformations/#cumulative_sum) | **{{< icon "check" >}}** | -| [DERIVATIVE()](/influxdb/clustered/reference/influxql/functions/transformations/#derivative) | **{{< icon "check" >}}** | -| [DIFFERENCE()](/influxdb/clustered/reference/influxql/functions/transformations/#difference) | **{{< icon "check" >}}** | -| [ELAPSED()](/influxdb/clustered/reference/influxql/functions/transformations/#elapsed) | **{{< icon "check" >}}** | -| [EXP()](/influxdb/clustered/reference/influxql/functions/transformations/#exp) | **{{< icon "check" >}}** | -| [FLOOR()](/influxdb/clustered/reference/influxql/functions/transformations/#floor) | **{{< icon "check" >}}** | -| [LN()](/influxdb/clustered/reference/influxql/functions/transformations/#ln) | **{{< icon "check" >}}** | -| [LOG()](/influxdb/clustered/reference/influxql/functions/transformations/#log) | **{{< icon "check" >}}** | -| [LOG2()](/influxdb/clustered/reference/influxql/functions/transformations/#log2) | **{{< icon "check" >}}** | -| [LOG10()](/influxdb/clustered/reference/influxql/functions/transformations/#log10) | **{{< icon "check" >}}** | -| [MOVING_AVERAGE()](/influxdb/clustered/reference/influxql/functions/transformations/#moving_average) | **{{< icon "check" >}}** | -| [NON_NEGATIVE_DERIVATIVE()](/influxdb/clustered/reference/influxql/functions/transformations/#non_negative_derivative) | **{{< icon "check" >}}** | -| [NON_NEGATIVE_DIFFERENCE()](/influxdb/clustered/reference/influxql/functions/transformations/#non_negative_difference) | **{{< icon "check" >}}** | -| [POW()](/influxdb/clustered/reference/influxql/functions/transformations/#pow) | **{{< icon "check" >}}** | -| [ROUND()](/influxdb/clustered/reference/influxql/functions/transformations/#round) | **{{< icon "check" >}}** | -| [SIN()](/influxdb/clustered/reference/influxql/functions/transformations/#sin) | **{{< icon "check" >}}** | -| [SQRT()](/influxdb/clustered/reference/influxql/functions/transformations/#sqrt) | **{{< icon "check" >}}** | -| [TAN()](/influxdb/clustered/reference/influxql/functions/transformations/#tan) | **{{< icon "check" >}}** | - -### Technical and predictive analysis - -| Function | Supported | -| :-------------------------------------------------------------------- | :-------: | -| CHANDE_MOMENTUM_OSCILLATOR() | | -| DOUBLE_EXPONENTIAL_MOVING_AVERAGE() | | -| EXPONENTIAL_MOVING_AVERAGE() | | -| HOLT_WINTERS() | | -| HOLT_WINTERS_WITH_FIT() | | -| KAUFMANS_EFFICIENCY_RATIO() | | -| KAUFMANS_ADAPTIVE_MOVING_AVERAGE() | | -| RELATIVE_STRENGTH_INDEX() | | -| TRIPLE_EXPONENTIAL_MOVING_AVERAGE() | | -| TRIPLE_EXPONENTIAL_DERIVATIVE() | | - - - -### Date and time functions - -| Function | Supported | -| :------------------------------------------------------------------------- | :----------------------: | -| [now()](/influxdb/clustered/reference/influxql/functions/date-time/#now) | **{{< icon "check" >}}** | -| [time()](/influxdb/clustered/reference/influxql/functions/date-time/#time) | **{{< icon "check" >}}** | -| tz() | | - - - -### Miscellaneous functions - -| Function | Supported | -| :-------------------------------------------------------------------- | :----------------------: | -| [fill()](/influxdb/clustered/reference/influxql/functions/misc/#fill) | **{{< icon "check" >}}** | diff --git a/content/influxdb/clustered/reference/influxql/functions/_index.md b/content/influxdb/clustered/reference/influxql/functions/_index.md index 37218b988..1a302a6c9 100644 --- a/content/influxdb/clustered/reference/influxql/functions/_index.md +++ b/content/influxdb/clustered/reference/influxql/functions/_index.md @@ -8,79 +8,6 @@ menu: parent: influxql-reference identifier: influxql-functions weight: 208 + +source: /shared/influxql-v3-reference/functions/_index.md --- - -Use InfluxQL functions to aggregate, select, transform, analyze, and predict data. - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB v3 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/clustered/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## InfluxQL functions (by type) - -- [Aggregates](/influxdb/clustered/reference/influxql/functions/aggregates/) - - [COUNT()](/influxdb/clustered/reference/influxql/functions/aggregates/#count) - - [DISTINCT()](/influxdb/clustered/reference/influxql/functions/aggregates/#distinct) - - [MEAN()](/influxdb/clustered/reference/influxql/functions/aggregates/#mean) - - [MEDIAN()](/influxdb/clustered/reference/influxql/functions/aggregates/#median) - - [STDDEV()](/influxdb/clustered/reference/influxql/functions/aggregates/#stddev) - - [SUM()](/influxdb/clustered/reference/influxql/functions/aggregates/#sum) - - - -- [Selectors](/influxdb/clustered/reference/influxql/functions/selectors/) - - [BOTTOM()](/influxdb/clustered/reference/influxql/functions/selectors/#bottom) - - [FIRST()](/influxdb/clustered/reference/influxql/functions/selectors/#first) - - [LAST()](/influxdb/clustered/reference/influxql/functions/selectors/#last) - - [MAX()](/influxdb/clustered/reference/influxql/functions/selectors/#max) - - [MIN()](/influxdb/clustered/reference/influxql/functions/selectors/#min) - - [PERCENTILE()](/influxdb/clustered/reference/influxql/functions/selectors/#percentile) - - [TOP()](/influxdb/clustered/reference/influxql/functions/selectors/#top) - -- [Transformations](/influxdb/clustered/reference/influxql/functions/transformations/) - - [ABS()](/influxdb/clustered/reference/influxql/functions/transformations/#abs) - - [ACOS()](/influxdb/clustered/reference/influxql/functions/transformations/#acos) - - [ASIN()](/influxdb/clustered/reference/influxql/functions/transformations/#asin) - - [ATAN()](/influxdb/clustered/reference/influxql/functions/transformations/#atan) - - [ATAN2()](/influxdb/clustered/reference/influxql/functions/transformations/#atan2) - - [CEIL()](/influxdb/clustered/reference/influxql/functions/transformations/#ceil) - - [COS()](/influxdb/clustered/reference/influxql/functions/transformations/#cos) - - [CUMULATIVE_SUM()](/influxdb/clustered/reference/influxql/functions/transformations/#cumulative_sum) - - [DERIVATIVE()](/influxdb/clustered/reference/influxql/functions/transformations/#derivative) - - [DIFFERENCE()](/influxdb/clustered/reference/influxql/functions/transformations/#difference) - - [EXP()](/influxdb/clustered/reference/influxql/functions/transformations/#exp) - - [FLOOR()](/influxdb/clustered/reference/influxql/functions/transformations/#floor) - - [HISTOGRAM()](/influxdb/clustered/reference/influxql/functions/transformations/#histogram) - - [LN()](/influxdb/clustered/reference/influxql/functions/transformations/#ln) - - [LOG()](/influxdb/clustered/reference/influxql/functions/transformations/#log) - - [LOG2()](/influxdb/clustered/reference/influxql/functions/transformations/#log2) - - [LOG10()](/influxdb/clustered/reference/influxql/functions/transformations/#log10) - - [MOVING_AVERAGE()](/influxdb/clustered/reference/influxql/functions/transformations/#moving_average) - - [NON_NEGATIVE_DERIVATIVE()](/influxdb/clustered/reference/influxql/functions/transformations/#non_negative_derivative) - - [NON_NEGATIVE_DIFFERENCE()](/influxdb/clustered/reference/influxql/functions/transformations/#non_negative_difference) - - [POW()](/influxdb/clustered/reference/influxql/functions/transformations/#pow) - - [ROUND()](/influxdb/clustered/reference/influxql/functions/transformations/#round) - - [SIN()](/influxdb/clustered/reference/influxql/functions/transformations/#sin) - - [SQRT()](/influxdb/clustered/reference/influxql/functions/transformations/#sqrt) - - [TAN()](/influxdb/clustered/reference/influxql/functions/transformations/#tan) - -- [Date and time](/influxdb/clustered/reference/influxql/functions/date-time/) - - [now()](/influxdb/clustered/reference/influxql/functions/date-time/#now) - - [time()](/influxdb/clustered/reference/influxql/functions/date-time/#time) -- [Miscellaneous](/influxdb/clustered/reference/influxql/functions/misc/) - - [fill()](/influxdb/clustered/reference/influxql/functions/misc/#fill) - - - - - - - - - - diff --git a/content/influxdb/clustered/reference/influxql/functions/aggregates.md b/content/influxdb/clustered/reference/influxql/functions/aggregates.md index f7c26aa1b..600d7ca9f 100644 --- a/content/influxdb/clustered/reference/influxql/functions/aggregates.md +++ b/content/influxdb/clustered/reference/influxql/functions/aggregates.md @@ -10,922 +10,6 @@ menu: weight: 205 related: - /influxdb/clustered/query-data/influxql/aggregate-select/ + +source: /shared/influxql-v3-reference/functions/aggregates.md --- - -Use aggregate functions to assess, aggregate, and return values in your data. -Aggregate functions return one row containing the aggregate values from each InfluxQL group. - -_Examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -- [COUNT()](#count) -- [DISTINCT()](#distinct) -- [MEAN()](#mean) -- [MEDIAN()](#median) -- [MODE()](#mode) -- [SPREAD()](#spread) -- [STDDEV()](#stddev) -- [SUM()](#sum) - - - - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/clustered/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## COUNT() - -Returns the number of non-null [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -COUNT(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Count the number of non-null values in a field" %}} - -```sql -SELECT COUNT(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 1970-01-01T00:00:00Z | 26 | - -{{% /expand %}} - -{{% expand "Count the number of non-null values in each field" %}} - -```sql -SELECT COUNT(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count_co | count_hum | count_temp | -| :------------------- | -------: | --------: | ---------: | -| 1970-01-01T00:00:00Z | 26 | 26 | 26 | - -{{% /expand %}} - -{{% expand "Count the number of non-null values in fields where the field key matches a regular expression" %}} - -```sql -SELECT COUNT(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count_hum | count_temp | -| :------------------- | --------: | ---------: | -| 1970-01-01T00:00:00Z | 26 | 26 | - -{{% /expand %}} - -{{% expand "Count distinct values for a field" %}} - -InfluxQL supports nesting [`DISTINCT()`](#distinct) in `COUNT()`. - -```sql -SELECT COUNT(DISTINCT(co)) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 1970-01-01T00:00:00Z | 12 | - -{{% /expand %}} - -{{% expand "Count the number of non-null field values within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - COUNT(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | count | -| :------------------- | ----: | -| 2022-01-01T06:00:00Z | 4 | -| 2022-01-01T12:00:00Z | 6 | -| 2022-01-01T18:00:00Z | 3 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DISTINCT() - -Returns the list of unique [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -DISTINCT(field_key) -``` - -#### Arguments - -- **field_key**: Field key to return distinct values from. - Supports all field types. - -#### Notable behaviors - -- InfluxQL supports nesting `DISTINCT()` with [`COUNT()`](#count-distinct-values-for-a-field). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "List the distinct field values" %}} - -```sql -SELECT DISTINCT(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | distinct | -| :------------------- | -------: | -| 1970-01-01T00:00:00Z | 0 | -| 1970-01-01T00:00:00Z | 1 | -| 1970-01-01T00:00:00Z | 3 | -| 1970-01-01T00:00:00Z | 4 | -| 1970-01-01T00:00:00Z | 7 | -| 1970-01-01T00:00:00Z | 5 | -| 1970-01-01T00:00:00Z | 9 | -| 1970-01-01T00:00:00Z | 18 | -| 1970-01-01T00:00:00Z | 14 | -| 1970-01-01T00:00:00Z | 22 | -| 1970-01-01T00:00:00Z | 17 | -| 1970-01-01T00:00:00Z | 26 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - - -## MEAN() - -Returns the arithmetic mean (average) of [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -MEAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the mean value of a field" %}} - -```sql -SELECT MEAN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of each field" %}} - -```sql -SELECT MEAN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ----------------: | -------: | -----------------: | -| 1970-01-01T00:00:00Z | 5.269230769230769 | 36.15 | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of fields where the field key matches a regular expression" %}} - -```sql -SELECT MEAN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean_hum | mean_temp | -| :------------------- | -------: | -----------------: | -| 1970-01-01T00:00:00Z | 36.15 | 22.396153846153844 | - -{{% /expand %}} - -{{% expand "Calculate the mean value of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MEAN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 22.275 | -| 2022-01-01T12:00:00Z | 22.649999999999995 | -| 2022-01-01T18:00:00Z | 23.033333333333335 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MEDIAN() - -Returns the middle value from a sorted list of [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -MEDIAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MEDIAN()` is nearly equivalent to - [`PERCENTILE(field_key, 50)`](/influxdb/clustered/reference/influxql/functions/selectors/#percentile), - except `MEDIAN()` returns the average of the two middle field values if the - field contains an even number of values. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the median value of a field" %}} - -```sql -SELECT MEDIAN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median | -| :------------------- | -----: | -| 1970-01-01T00:00:00Z | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of each field" %}} - -```sql -SELECT MEDIAN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median_co | median_hum | median_temp | -| :------------------- | --------: | ---------: | ----------: | -| 1970-01-01T00:00:00Z | 1 | 36.05 | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of fields where the field key matches a regular expression" %}} - - -```sql -SELECT MEDIAN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median_hum | median_temp | -| :------------------- | ---------: | ----------: | -| 1970-01-01T00:00:00Z | 36.05 | 22.45 | - -{{% /expand %}} - -{{% expand "Calculate the median value of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MEDIAN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | median | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 22.549999999999997 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MODE() - -Returns the most frequent value in a list of -[field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -MODE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. - -#### Notable behaviors - -- `MODE()` returns the field value with the earliest - [timestamp](/influxdb/clustered/reference/glossary/#timestamp) - if there's a tie between two or more values for the maximum number of occurrences. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Calculate the mode value of a field" %}} - -```sql -SELECT MODE(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode | -| :------------------- | ---: | -| 1970-01-01T00:00:00Z | 0 | - -{{% /expand %}} - -{{% expand "Calculate the mode value of each field" %}} - -```sql -SELECT MODE(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode_co | mode_hum | mode_temp | -| :------------------- | ------: | -------: | --------: | -| 1970-01-01T00:00:00Z | 0 | 36 | 22.7 | - -{{% /expand %}} - -{{% expand "Calculate the mode of field keys that match a regular expression" %}} - -```sql -SELECT MODE(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode_hum | mode_temp | -| :------------------- | -------: | --------: | -| 1970-01-01T00:00:00Z | 36 | 22.7 | - -{{% /expand %}} - -{{% expand "Calculate the mode a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MODE(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | mode | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 1 | -| 2022-01-01T18:00:00Z | 18 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SPREAD() - -Returns the difference between the minimum and maximum -[field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -SPREAD(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Calculate the spread of a field" %}} - -```sql -SELECT SPREAD(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of each field" %}} - -```sql -SELECT SPREAD(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread_co | spread_hum | spread_temp | -| :------------------- | --------: | ---------: | -----------------: | -| 1970-01-01T00:00:00Z | 26 | 1 | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of field keys that match a regular expression" %}} - -```sql -SELECT SPREAD(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread_hum | spread_temp | -| :------------------- | ---------: | -----------------: | -| 1970-01-01T00:00:00Z | 1 | 2.3000000000000007 | - -{{% /expand %}} - -{{% expand "Calculate the spread of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SPREAD(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | spread | -| :------------------- | -----: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 9 | -| 2022-01-01T18:00:00Z | 8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## STDDEV() - -Returns the standard deviation of [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -STDDEV(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the standard deviation of a field" %}} - -```sql -SELECT STDDEV(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of each field" %}} - -```sql -SELECT STDDEV(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev_co | stddev_hum | stddev_temp | -| :------------------- | ----------------: | ------------------: | -----------------: | -| 1970-01-01T00:00:00Z | 7.774613519951676 | 0.25495097567963926 | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of fields where the field key matches a regular expression" %}} - -```sql -SELECT STDDEV(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev_hum | stddev_temp | -| :------------------- | ------------------: | -----------------: | -| 1970-01-01T00:00:00Z | 0.25495097567963926 | 0.5553238833191091 | - -{{% /expand %}} - -{{% expand "Calculate the standard deviation of a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - STDDEV(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | stddev | -| :------------------- | -----------------: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 3.6742346141747673 | -| 2022-01-01T18:00:00Z | 4 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SUM() - -Returns the sum of [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -SUM(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Calculate the sum of values in a field" %}} - -```sql -SELECT SUM(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | --: | -| 1970-01-01T00:00:00Z | 137 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values in each field" %}} - -```sql -SELECT SUM(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum_co | sum_hum | sum_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 137 | 939.9 | 582.3 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values for fields where the field key matches a regular expression" %}} - -```sql -SELECT SUM(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum_hum | sum_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 939.9 | 582.3 | - -{{% /expand %}} - -{{% expand "Calculate the sum of values in a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SUM(co) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | --: | -| 2022-01-01T06:00:00Z | 0 | -| 2022-01-01T12:00:00Z | 21 | -| 2022-01-01T18:00:00Z | 66 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/influxql/functions/date-time.md b/content/influxdb/clustered/reference/influxql/functions/date-time.md index e733faf72..a7a82e9ac 100644 --- a/content/influxdb/clustered/reference/influxql/functions/date-time.md +++ b/content/influxdb/clustered/reference/influxql/functions/date-time.md @@ -8,138 +8,6 @@ menu: name: Date and time parent: influxql-functions weight: 206 + +source: /shared/influxql-v3-reference/functions/date-time.md --- - -Use InfluxQL date and time functions to perform time-related operations. - -- [now()](#now) -- [time()](#time) - - -## now() - -Returns the current system time (UTC). -_Supported only in the [`WHERE` clause](/influxdb/clustered/reference/influxql/where/)._ - -```sql -now() -``` - -## time() - -Used in the [`GROUP BY` clause](/influxdb/clustered/reference/influxql/group-by/) -to group data into time-based intervals, also known as "windows", using the specified interval. -Timestamps in the `time` column are updated to the start boundary of the window -they're in and grouped by `time`. -Windows use preset round-number boundaries based on the specified interval that -are independent of time conditions in the -[`WHERE` clause](/influxdb/clustered/reference/influxql/where/). - -This operation can be used to do the following: - -- Downsample data by aggregating multiple points in each window into a single - point per window. -- Normalize irregular time series data to occur at regular intervals. - -_Supported only in the [`GROUP BY` clause](/influxdb/clustered/reference/influxql/group-by/)._ - -```sql -time(interval[, offset]) -``` - -#### Arguments - -- **interval**: Duration literal that specifies the window interval. -- **offset**: Duration literal that shifts preset time boundaries forward or backward. - Can be positive or negative. _Default is `0s`._ - -##### Examples {#time-examples} - -{{< expand-wrapper >}} - -{{% expand "Downsample data into time-based intervals" %}} - -The following example uses the -[Bitcoin price sample dataset](/influxdb/clustered/reference/sample-data/#bitcoin-price-data). - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'GBP' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(2d) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-05-01T00:00:00Z | 23680.120447159094 | -| 2023-05-03T00:00:00Z | 24048.71484033149 | -| 2023-05-05T00:00:00Z | 24461.9194901099 | -| 2023-05-07T00:00:00Z | 23796.43801933702 | -| 2023-05-09T00:00:00Z | 23118.709889285707 | -| 2023-05-11T00:00:00Z | 22465.008364444446 | -| 2023-05-13T00:00:00Z | 22499.464763186803 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - diff --git a/content/influxdb/clustered/reference/influxql/functions/misc.md b/content/influxdb/clustered/reference/influxql/functions/misc.md index dcd83898e..0161d0bc9 100644 --- a/content/influxdb/clustered/reference/influxql/functions/misc.md +++ b/content/influxdb/clustered/reference/influxql/functions/misc.md @@ -10,237 +10,6 @@ menu: identifier: influxql-misc-functions parent: influxql-functions weight: 206 + +source: /shared/influxql-v3-reference/functions/misc.md --- - -Use InfluxQL miscellaneous functions to perform different operations in -InfluxQL queries. - -- [fill()](#fill) - -## fill() - -Fills _null_ field values returned from empty time windows in `GROUP BY time()` -queries with a specified fill value. - -_Supported only in the [`GROUP BY` clause](/influxdb/clustered/reference/influxql/group-by/)._ - -```sql -fill(behavior) -``` - -#### Arguments - -- **behavior**: Defines the behavior of the fill operation. - If no `FILL` clause is included, the default behavior is `fill(null)`. - - The following options are available: - - - **numeric literal**: Replaces null values with the specified numeric literal. - - **linear**: Uses linear interpolation between existing values to replace null values. - - **none**: Removes rows with null field values. - - **null**: Keeps null values and associated timestamps. - - **previous**: Replaces null values with the most recent non-null value. - -#### Examples {#fill-examples} - -The following example uses the -[Bitcoin price sample dataset](/influxdb/clustered/reference/sample-data/#bitcoin-price-data). - -{{< tabs-wrapper >}} -{{% tabs "small" %}} -[fill(numeric_literal)](#) -[fill(linear)](#) -[fill(none)](#) -[fill(null)](#) -[fill(previous)](#) -{{% /tabs %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(0) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 0 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(linear) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29285.3651 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(none) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(null) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{% tab-content %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(previous) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ---------: | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - - - diff --git a/content/influxdb/clustered/reference/influxql/functions/selectors.md b/content/influxdb/clustered/reference/influxql/functions/selectors.md index e4e89f680..eecdd7d34 100644 --- a/content/influxdb/clustered/reference/influxql/functions/selectors.md +++ b/content/influxdb/clustered/reference/influxql/functions/selectors.md @@ -10,1059 +10,6 @@ menu: weight: 205 related: - /influxdb/clustered/query-data/influxql/aggregate-select/ + +source: /shared/influxql-v3-reference/functions/selectors.md --- - -Use selector functions to assess, select, and return values in your data. -Selector functions return one or more rows with the selected values from each -InfluxQL group. - -_Examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -- [BOTTOM()](#bottom) -- [FIRST()](#first) -- [LAST()](#last) -- [MAX()](#max) -- [MIN()](#min) -- [PERCENTILE()](#percentile) -- [TOP()](#top) -- [Notable behaviors of selector functions](#notable-behaviors-of-selector-functions) - - - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/clustered/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## BOTTOM() - -Returns the smallest `N` [field values](/influxdb/clustered/reference/glossary/#field-value). -`BOTTOM()` supports int64 and float64 field value [data types](/influxdb/clustered/reference/glossary/#field-value). - -```sql -BOTTOM(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) -``` - -{{% note %}} -**Note:** `BOTTOM()` returns the field value with the earliest timestamp if -there's a tie between two or more values for the smallest value. -{{% /note %}} - -#### Arguments - -- **field_expression**: Expression to identify the field to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key) - or constant. -- **tag_expression**: Expression to identify a tag key to segment by. - Can be a [tag key](/influxdb/clustered/reference/glossary/#tag-key) - or constant. Comma-delimit multiple tags. -- **N**: Number of results to return from each InfluxQL group or specified tag segment. - -#### Notable behaviors - -- `BOTTOM()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `BOTTOM()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the bottom three values of a field" %}} - -```sql -SELECT BOTTOM(temp, 3) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | -| :------------------- | -----: | -| 2022-01-01T08:00:00Z | 21 | -| 2022-01-01T08:00:00Z | 21.1 | -| 2022-01-01T09:00:00Z | 21.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom field value for two unique tag values" %}} - -```sql -SELECT BOTTOM(temp, room, 2) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | room | -| :------------------- | -----: | :---------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom three field values and the tag value associated with each" %}} - -```sql -SELECT BOTTOM(temp, 3), room FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | bottom | room | -| :------------------- | -----: | ----------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | -| 2022-01-01T09:00:00Z | 21.4 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the bottom field values for unique tag values and within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} -```sql -SELECT - BOTTOM(temp, room, 2) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -GROUP BY time(2h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | bottom | room | -| :------------------- | -----: | :---------- | -| 2022-01-01T08:00:00Z | 21 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | Living Room | -| 2022-01-01T10:00:00Z | 21.8 | Living Room | -| 2022-01-01T11:00:00Z | 22.4 | Kitchen | -| 2022-01-01T12:00:00Z | 22.2 | Living Room | -| 2022-01-01T12:00:00Z | 22.5 | Kitchen | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `BOTTOM()` -[maintains the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FIRST() - -Returns the [field value](/influxdb/clustered/reference/glossary/#field-value) with the oldest timestamp. - -```sql -FIRST(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). - -#### Notable behaviors - -- `FIRST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the first value for a field" %}} - -```sql -SELECT FIRST(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | first | -| :------------------- | ----: | -| 2022-01-01T08:00:00Z | 21.1 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the first value from each field" %}} - -```sql -SELECT FIRST(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first_co | first_hum | first_temp | -| :------------------- | -------: | --------: | ---------: | -| 1970-01-01T00:00:00Z | 0 | 35.9 | 21.1 | - -{{% /expand %}} - -{{% expand "Select the first value from field keys that match a regular expression" %}} - -```sql -SELECT FIRST(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first_hum | first_temp | -| :------------------- | --------: | ---------: | -| 1970-01-01T00:00:00Z | 35.9 | 21.1 | - -{{% /expand %}} - -{{% expand "Select the first value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - FIRST(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | first | -| :------------------- | ----: | -| 2022-01-01T06:00:00Z | 21 | -| 2022-01-01T12:00:00Z | 22.5 | -| 2022-01-01T18:00:00Z | 23.3 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `FIRST()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LAST() - -Returns the [field value](/influxdb/clustered/reference/glossary/#field-value) with the most recent timestamp. - -```sql -LAST(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). - -#### Notable behaviors - -- `LAST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the last value for a field" %}} - -```sql -SELECT LAST(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | last | -| :------------------- | ---: | -| 2022-01-01T20:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the last value from each field" %}} - -```sql -SELECT LAST(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last_co | last_hum | last_temp | -| :------------------- | ------: | -------: | --------: | -| 1970-01-01T00:00:00Z | 26 | 36.5 | 22.7 | - -{{% /expand %}} - -{{% expand "Select the last value from field keys that match a regular expression" %}} - -```sql -SELECT LAST(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last_hum | last_temp | -| :------------------- | -------: | --------: | -| 1970-01-01T00:00:00Z | 36.5 | 22.7 | - -{{% /expand %}} - -{{% expand "Select the last value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - LAST(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | last | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 22.4 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `LAST()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MAX() - -Returns the greatest [field value](/influxdb/clustered/reference/glossary/#field-value). - -```sql -MAX(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MAX()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the maximum value from a field" %}} - -```sql -SELECT MAX(co) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | max | -| :------------------- | --: | -| 2022-01-01T20:00:00Z | 26 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the maximum value from each field" %}} - -```sql -SELECT MAX(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max_co | max_hum | max_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 26 | 36.9 | 23.3 | - -{{% /expand %}} - -{{% expand "Select the maximum value from field keys that match a regular expression" %}} - -```sql -SELECT MAX(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max_hum | max_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 36.9 | 23.3 | - -{{% /expand %}} - -{{% expand "Select the maximum value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MAX(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 23 | -| 2022-01-01T12:00:00Z | 22.8 | -| 2022-01-01T18:00:00Z | 23.3 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `MAX()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MIN() - -Returns the lowest [field value](/influxdb/clustered/reference/glossary/#field-value). - -```sql -MIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. - -#### Notable behaviors - -- `MIN()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the minimum value from a field" %}} - -```sql -SELECT MIN(temp) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | min | -| :------------------- | --: | -| 2022-01-01T08:00:00Z | 21 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the minimum value from each field" %}} - -```sql -SELECT MIN(*) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min_co | min_hum | min_temp | -| :------------------- | -----: | ------: | -------: | -| 1970-01-01T00:00:00Z | 0 | 35.9 | 21 | - -{{% /expand %}} - -{{% expand "Select the minimum value from field keys that match a regular expression" %}} - -```sql -SELECT MIN(/^[th]/) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min_hum | min_temp | -| :------------------- | ------: | -------: | -| 1970-01-01T00:00:00Z | 35.9 | 21 | - -{{% /expand %}} - -{{% expand "Select the minimum value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - MIN(temp) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | min | -| :------------------- | ---: | -| 2022-01-01T06:00:00Z | 21 | -| 2022-01-01T12:00:00Z | 22.4 | -| 2022-01-01T18:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `MIN()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## PERCENTILE() - -Returns the `N`th percentile [field value](/influxdb/clustered/reference/glossary/#field-value). - -```sql -PERCENTILE(field_expression, N) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. -- **N**: Percentile to return. - Must be an integer or float value **greater than 0 and less than or equal to 100**. - -#### Notable behaviors - -- `PERCENTILE()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `PERCENTILE(example_field, 100)` is equivalent to [`MAX(example_field)`](#max). -- `PERCENTILE(example_field, 50)` is nearly equivalent to - [`MEDIAN(example_field)`](/influxdb/clustered/reference/influxql/functions/aggregates/#median), - except `MEDIAN()` returns the average of the two middle values if the field - contains an even number of values. -- `PERCENTILE(example_field, 0)` returns _null_. - -#### Examples - -{{< expand-wrapper >}} - -{{% expand "Select the 50th percentile value from a field" %}} - -```sql -SELECT PERCENTILE(temp, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | percentile | -| :------------------- | ---------: | -| 2022-01-01T11:00:00Z | 22.4 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from each field" %}} - -```sql -SELECT PERCENTILE(*, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile_co | percentile_hum | percentile_temp | -| :------------------- | ------------: | -------------: | --------------: | -| 1970-01-01T00:00:00Z | 1 | 36 | 22.4 | - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from field keys that match a regular expression" %}} - -```sql -SELECT PERCENTILE(/^[th]/, 50) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile_hum | percentile_temp | -| :------------------- | -------------: | --------------: | -| 1970-01-01T00:00:00Z | 36 | 22.4 | - -{{% /expand %}} - -{{% expand "Select the 50th percentile value from a field within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - PERCENTILE(temp, 50) -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY time(6h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | percentile | -| :------------------- | ---------: | -| 2022-01-01T06:00:00Z | 22.4 | -| 2022-01-01T12:00:00Z | 22.7 | -| 2022-01-01T18:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `PERCENTILE()` -[overrides the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - - - -## TOP() - -Returns the greatest `N` [field values](/influxdb/clustered/reference/glossary/#field-value). -`TOP()` supports int64 and float64 field value [data types](/influxdb/clustered/reference/glossary/#field-value). - -```sql -TOP(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) -``` - -{{% note %}} -**Note:** `TOP()` returns the field value with the earliest timestamp if there's -a tie between two or more values for the greatest value. -{{% /note %}} - -#### Arguments - -- **field_expression**: Expression to identify the field to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key) - or constant. -- **tag_expression**: Expression to identify a tag key to segment by. - Can be a [tag key](/influxdb/clustered/reference/glossary/#tag-key) - or constant. Comma-delimit multiple tags. -- **N**: Number of results to return from each InfluxQL group or specified tag segment. - -#### Notable behaviors - -- `TOP()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). -- `TOP()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Select the top three values of a field" %}} - -```sql -SELECT TOP(temp, 3) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | -| :------------------- | ---: | -| 2022-01-01T09:00:00Z | 23 | -| 2022-01-01T18:00:00Z | 23.3 | -| 2022-01-01T19:00:00Z | 23.1 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top field value for two unique tag values" %}} - -```sql -SELECT TOP(temp, room, 2) FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T18:00:00Z | 22.8 | Living Room | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top three field values and the tag value associated with each" %}} - -```sql -SELECT TOP(temp, 3), room FROM home -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :------ | -| 2022-01-01T09:00:00Z | 23 | Kitchen | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T19:00:00Z | 23.1 | Kitchen | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select the top field values for unique tag values and within time windows (grouped by time)" %}} - -{{% influxdb/custom-timestamps %}} -```sql -SELECT - TOP(temp, room, 2) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -GROUP BY time(2h) -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T09:00:00Z | 23 | Kitchen | -| 2022-01-01T09:00:00Z | 21.4 | Living Room | -| 2022-01-01T10:00:00Z | 22.7 | Kitchen | -| 2022-01-01T11:00:00Z | 22.2 | Living Room | -| 2022-01-01T12:00:00Z | 22.5 | Kitchen | -| 2022-01-01T12:00:00Z | 22.2 | Living Room | - -{{% /influxdb/custom-timestamps %}} - -Notice that when grouping by time, `TOP()` -[maintains the point's original timestamp](#timestamps-when-grouping-by-time). - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable behaviors of selector functions - -- [Timestamps when grouping by time](#timestamps-when-grouping-by-time) -- [Selector functions may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected) - -### Timestamps when grouping by time - -When using selector functions with a `GROUP BY time()` clause, most selector -functions return the timestamp of the starting boundary for each time interval. -However functions with an `N` argument that specifies the number of results to -return per group maintain the original timestamp of each returned point. - -{{< flex >}} -{{% flex-content %}} - -###### Return the start time of each time interval - -- [FIRST()](#first) -- [LAST()](#last) -- [MAX()](#max) -- [MIN()](#min) -- [PERCENTILE()](#percentile) - -{{% /flex-content %}} -{{% flex-content %}} - -###### Maintain the original timestamp - -- [BOTTOM()](#bottom) -- [TOP()](#top) - - -{{% /flex-content %}} -{{< /flex >}} - -### Selector functions may return fewer points than expected - -Queries that use the following selector functions with an `N` argument may -return fewer points than expected. - -- [BOTTOM()](#bottom) -- [TOP()](#top) - - -If the InfluxQL group or specified tag key contains `X` points or unique tag -values and `X` is less than `N`, the function returns `X` results instead of `N` -for each group or tag value. - -{{< expand-wrapper >}} -{{% expand "View example for `FN(field_key, N)`" %}} - -The example below selects the bottom 5 temperatures from the Kitchen between -{{% influxdb/custom-timestamps-span %}}2022-01-01T08:00:00Z{{% /influxdb/custom-timestamps-span %}} -and {{% influxdb/custom-timestamps-span %}}2022-01-01T10:00:00Z{{% /influxdb/custom-timestamps-span %}}. -There are only 3 points recorded for the Kitchen during the queried time range, -so the query returns 3 points instead of 5. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT BOTTOM(temp, 5) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' - AND room = 'Kitchen' -``` - -| time | bottom | -| :------------------- | -----: | -| 2022-01-01T08:00:00Z | 21 | -| 2022-01-01T09:00:00Z | 23 | -| 2022-01-01T10:00:00Z | 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "View example for `FN(field_key, tag_key, N)`" %}} - -The example below selects the top temperature from 3 unique values of the `room` tag. -However, the `room` tag only has 2 unique values, so results only contain 2 values. - -```sql -SELECT TOP(temp, room, 3) FROM home -``` - -{{% influxdb/custom-timestamps %}} - -| time | top | room | -| :------------------- | ---: | :---------- | -| 2022-01-01T18:00:00Z | 23.3 | Kitchen | -| 2022-01-01T18:00:00Z | 22.8 | Living Room | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/influxql/functions/technical-analysis.md b/content/influxdb/clustered/reference/influxql/functions/technical-analysis.md index b08397ccf..d5fb915a9 100644 --- a/content/influxdb/clustered/reference/influxql/functions/technical-analysis.md +++ b/content/influxdb/clustered/reference/influxql/functions/technical-analysis.md @@ -10,1905 +10,6 @@ menu: weight: 205 # None of these functions work yet so listing as draft draft: true + +source: /shared/influxql-v3-reference/functions/technical-analysis.md --- - -Use technical analysis functions to apply algorithms to your time series data. -Many of these algorithms are often used to analyze financial and investment data, -but have application in other use cases as well. - -- [Predictive analysis](#predictive-analysis): - - [HOLT_WINTERS()](#holt_winters) -- [Technical analysis](#technical-analysis-functions): - - [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) - - [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) - - [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) - - [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) - - [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) - - [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) - - [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) - - [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) - -## Predictive analysis - -Predictive analysis functions are a type of technical analysis algorithms that -predict and forecast future values. - -### HOLT_WINTERS() - -Returns N number of predicted [field values](/influxdb/clustered/reference/glossary/#field-value) -using the [Holt-Winters](https://www.otexts.org/fpp/7/5) seasonal method. -`HOLT_WINTERS_WITH_FIT()` returns the fitted values in addition to `N` seasonally -adjusted predicted field values. - -Input data points must occur at regular time intervals. -To ensure regular time intervals, `HOLT_WINTERS` requires an aggregate expression -as input and a a `GROUP BY time()` to apply the aggregate operation at regular intervals. - -Use `HOLT_WINTERS()` to: - -- Predict when data values will cross a given threshold -- Compare predicted values with actual values to detect anomalies in your data - -```sql -HOLT_WINTERS[_WITH_FIT](aggregate_expression, N, S) -``` - -#### Arguments {#arguments-holt-winters} - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/clustered/reference/influxql/functions/aggregate/). - The expression can operate on a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports **numeric fields**. -- **N**: Number of values to predict. - Predicted values occur at the same interval specified in the `GROUP BY time()` clause. -- **S**: Seasonal pattern length (number of values per season) to use when - adjusting for seasonal patterns. - To _not_ seasonally adjust predicted values, set `S` to `0` or `1.` - -#### Notable behaviors - -- In some cases, you may receive fewer than `N` predicted points. - This typically occurs when the seasonal adjustment (`S`) is invalid or when - input data is not suited for the Holt Winters algorithm. - -#### Examples - -The following examples use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -{{< expand-wrapper >}} -{{% expand "Use Holt Winters to predict field values with seasonal adjustment" %}} - -```sql -SELECT - HOLT_WINTERS(MEAN(temp_avg), 12, 12) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters | -| :------------------- | -----------------: | -| 2023-01-23T00:00:00Z | 52.141810685706844 | -| 2023-02-22T00:00:00Z | 55.41941302100692 | -| 2023-03-24T00:00:00Z | 59.74300473524414 | -| 2023-04-23T00:00:00Z | 59.91932719987093 | -| 2023-05-23T00:00:00Z | 56.03083957191051 | -| 2023-06-22T00:00:00Z | 59.98437978757551 | -| 2023-07-22T00:00:00Z | 60.903170945334175 | -| 2023-08-21T00:00:00Z | 60.75738169893358 | -| 2023-09-20T00:00:00Z | 56.619132830933445 | -| 2023-10-20T00:00:00Z | 56.10559366563841 | -| 2023-11-19T00:00:00Z | 56.248977829575935 | -| 2023-12-19T00:00:00Z | 56.075540144158985 | - -{{% /expand %}} -{{% expand "Use Holt Winters to predict field values with no seasonal adjustment" %}} - -```sql -SELECT - HOLT_WINTERS(MEAN(temp_avg), 12, 0) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters | -| :------------------- | ----------------: | -| 2023-01-23T00:00:00Z | 58.55632627159769 | -| 2023-02-22T00:00:00Z | 58.55632627159944 | -| 2023-03-24T00:00:00Z | 58.55632627160024 | -| 2023-04-23T00:00:00Z | 58.55632627160061 | -| 2023-05-23T00:00:00Z | 58.55632627160079 | -| 2023-06-22T00:00:00Z | 58.55632627160087 | -| 2023-07-22T00:00:00Z | 58.5563262716009 | -| 2023-08-21T00:00:00Z | 58.55632627160092 | -| 2023-09-20T00:00:00Z | 58.55632627160093 | -| 2023-10-20T00:00:00Z | 58.55632627160094 | -| 2023-11-19T00:00:00Z | 58.55632627160094 | -| 2023-12-19T00:00:00Z | 58.55632627160094 | - -{{% /expand %}} - -{{% expand "Use Holt Winters to predict field values with fitted values" %}} - -```sql -SELECT - HOLT_WINTERS_WITH_FIT(MEAN(temp_avg), 12, 12) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2021-01-01T00:00:00Z' - AND time <= '2022-12-31T00:00:00Z' -GROUP BY time(30d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | holt_winters_with_fit | -| :------------------- | --------------------: | -| 2020-12-04T00:00:00Z | 50.5 | -| 2021-01-03T00:00:00Z | 53.280924101779426 | -| 2021-02-02T00:00:00Z | 52.099111942046704 | -| 2021-03-04T00:00:00Z | 55.84541855092053 | -| 2021-04-03T00:00:00Z | 60.06803481717513 | -| 2021-05-03T00:00:00Z | 60.414989273392976 | -| 2021-06-02T00:00:00Z | 58.265755948192606 | -| 2021-07-02T00:00:00Z | 63.12426388001118 | -| 2021-08-01T00:00:00Z | 64.34281315294628 | -| 2021-08-31T00:00:00Z | 62.701261106938865 | -| 2021-09-30T00:00:00Z | 58.39095413696881 | -| 2021-10-30T00:00:00Z | 57.571954549171174 | -| 2021-11-29T00:00:00Z | 57.72622091917164 | -| 2021-12-29T00:00:00Z | 56.21981843845102 | -| 2022-01-28T00:00:00Z | 52.592076197024845 | -| 2022-02-27T00:00:00Z | 55.20608671167453 | -| 2022-03-29T00:00:00Z | 59.01290245961656 | -| 2022-04-28T00:00:00Z | 59.10660216049941 | -| 2022-05-28T00:00:00Z | 55.87577637598558 | -| 2022-06-27T00:00:00Z | 59.10005762573857 | -| 2022-07-27T00:00:00Z | 60.04395791516323 | -| 2022-08-26T00:00:00Z | 59.76994469907478 | -| 2022-09-25T00:00:00Z | 56.21467016861341 | -| 2022-10-25T00:00:00Z | 55.76538052914458 | -| 2022-11-24T00:00:00Z | 55.95817013792435 | -| 2022-12-24T00:00:00Z | 55.78474730739332 | -| 2023-01-23T00:00:00Z | 52.33558076070284 | -| 2023-02-22T00:00:00Z | 55.15350456137378 | -| 2023-03-24T00:00:00Z | 58.95292137832944 | -| 2023-04-23T00:00:00Z | 59.15381228655361 | -| 2023-05-23T00:00:00Z | 55.77542228450764 | -| 2023-06-22T00:00:00Z | 59.05797349347727 | -| 2023-07-22T00:00:00Z | 59.87830149275526 | -| 2023-08-21T00:00:00Z | 59.718176562030116 | -| 2023-09-20T00:00:00Z | 56.13817596332756 | -| 2023-10-20T00:00:00Z | 55.626497950276445 | -| 2023-11-19T00:00:00Z | 55.81338302167719 | -| 2023-12-19T00:00:00Z | 55.75008713518608 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Technical analysis functions - -Technical analysis functions apply widely used algorithms to your data. -While they are primarily used in finance and investing, they have -application in other industries. - -- [Notable behaviors of technical analysis functions](#notable-behaviors-of-technical-analysis-functions) -- [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) -- [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) -- [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) -- [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) -- [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) -- [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) -- [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) -- [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) - -### Notable behaviors of technical analysis functions - -#### Must use aggregate or selector functions when grouping by time - -All technical analysis functions support `GROUP BY` clauses that group by tags, -but do not directly support `GROUP BY` clauses that group by time. -To use technical analysis functions with with a `GROUP BY time()` clause, apply -an [aggregate](/influxdb/clustered/reference/influxql/functions/aggregates/) -or [selector](/influxdb/clustered/reference/influxql/functions/selectors/) -function to the **field_expression** argument. -The technical analysis function operates on the result of the aggregate or -selector operation. - ---- - -### CHANDE_MOMENTUM_OSCILLATOR() - -The Chande Momentum Oscillator (CMO) is a technical momentum indicator developed by Tushar Chande. -The CMO indicator is created by calculating the difference between the sum of all -recent higher data points and the sum of all recent lower data points, -then dividing the result by the sum of all data movement over a given time period. -The result is multiplied by 100 to give the -100 to +100 range. -{{% cite %}}[Source](https://www.fidelity.com/learning-center/trading-investing/technical-analysis/technical-indicator-guide/cmo){{% /cite %}} - -```sql -CHANDE_MOMENTUM_OSCILLATOR(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-cmo} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period` | - | simple | `period` | - | none | `period - 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - - **none**: The algorithm does not perform any warmup at all. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 53.84615384615377 | -| 2022-01-01T12:00:00Z | 55.5555555555555 | -| 2022-01-01T13:00:00Z | -19.999999999999858 | -| 2022-01-01T14:00:00Z | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 59.99999999999972 | -| 2022-01-01T16:00:00Z | -14.285714285714432 | -| 2022-01-01T17:00:00Z | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator_co | chande_momentum_oscillator_hum | chande_momentum_oscillator_temp | -| :------------------- | ----------------------------: | -----------------------------: | ------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 20 | 53.84615384615377 | -| 2022-01-01T12:00:00Z | 0 | 20 | 55.5555555555555 | -| 2022-01-01T13:00:00Z | 100 | 42.85714285714228 | -19.999999999999858 | -| 2022-01-01T14:00:00Z | 100 | 24.999999999999332 | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 100 | 25.000000000000444 | 59.99999999999972 | -| 2022-01-01T16:00:00Z | 100 | 0 | -14.285714285714432 | -| 2022-01-01T17:00:00Z | 100 | -100 | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 100 | 50.0000000000003 | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 100 | 28.5714285714285 | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 100 | 38.461538461538545 | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T14:00:00Z | 14.285714285714432 | -| 2022-01-01T15:00:00Z | 59.99999999999972 | -| 2022-01-01T16:00:00Z | -14.285714285714432 | -| 2022-01-01T17:00:00Z | -14.285714285714432 | -| 2022-01-01T18:00:00Z | 38.46153846153834 | -| 2022-01-01T19:00:00Z | 28.57142857142868 | -| 2022-01-01T20:00:00Z | 20 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2022-01-01T12:00:00Z | 94.9367088607595 | -| 2022-01-01T13:00:00Z | 95.04132231404957 | -| 2022-01-01T14:00:00Z | 95.04132231404955 | -| 2022-01-01T15:00:00Z | 92.68218929543389 | -| 2022-01-01T16:00:00Z | 83.79002019036625 | -| 2022-01-01T17:00:00Z | 84.72964405398058 | -| 2022-01-01T18:00:00Z | 86.77405015296912 | -| 2022-01-01T19:00:00Z | 76.28466518769179 | -| 2022-01-01T20:00:00Z | 53.322717259176535 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - CHANDE_MOMENTUM_OSCILLATOR(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | chande_momentum_oscillator | -| :------------------- | -------------------------: | -| 2020-07-07T00:00:00Z | 100 | -| 2020-10-05T00:00:00Z | 21.498959056210964 | -| 2021-01-03T00:00:00Z | 2.0072053525475924 | -| 2021-04-03T00:00:00Z | -6.190741773563866 | -| 2021-07-02T00:00:00Z | -8.924485125858132 | -| 2021-09-30T00:00:00Z | 1.2078830260648301 | -| 2021-12-29T00:00:00Z | -5.181655747468743 | -| 2022-03-29T00:00:00Z | -2.3768115942029 | -| 2022-06-27T00:00:00Z | 6.511381683430422 | -| 2022-09-25T00:00:00Z | -7.7487391104997485 | -| 2022-12-24T00:00:00Z | 2.928763268960232 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### DOUBLE_EXPONENTIAL_MOVING_AVERAGE() - -The Double Exponential Moving Average (DEMA) attempts to remove the inherent lag -associated with moving averages by placing more weight on recent values. -The name suggests this is achieved by applying a double exponential smoothing which is not the case. -The value of an [EMA](#exponential_moving_average) is doubled. -To keep the value in line with the actual data and to remove the lag, the value "EMA of EMA" -is subtracted from the previously doubled EMA. -{{% cite %}}[Source](https://en.wikipedia.org/wiki/Double_exponential_moving_average){{% /cite %}} - -```sql -DOUBLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-dema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `(period - 1) × 2` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T11:00:00Z | 22.630333333333333 | -| 2022-01-01T12:00:00Z | 22.5854 | -| 2022-01-01T13:00:00Z | 22.747560000000004 | -| 2022-01-01T14:00:00Z | 22.814328 | -| 2022-01-01T15:00:00Z | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 22.55332832 | -| 2022-01-01T17:00:00Z | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 23.0672594816 | -| 2022-01-01T19:00:00Z | 23.12957407488 | -| 2022-01-01T20:00:00Z | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average_co | double_exponential_moving_average_hum | double_exponential_moving_average_temp | -| :------------------- | -----------------------------------: | ------------------------------------: | -------------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.056000000000004 | 22.630333333333333 | -| 2022-01-01T12:00:00Z | 0 | 36.019200000000005 | 22.5854 | -| 2022-01-01T13:00:00Z | 0.64 | 36.322880000000005 | 22.747560000000004 | -| 2022-01-01T14:00:00Z | 0.9279999999999999 | 36.332544000000006 | 22.814328 | -| 2022-01-01T15:00:00Z | 2.3232 | 36.266816000000006 | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 5.49376 | 36.104463360000004 | 22.55332832 | -| 2022-01-01T17:00:00Z | 8.15616 | 36.029302272 | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 15.0096384 | 36.573555916800004 | 23.0672594816 | -| 2022-01-01T19:00:00Z | 20.51534848 | 36.62971828224 | 23.12957407488 | -| 2022-01-01T20:00:00Z | 25.294948352 | 36.581181808640004 | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.814328 | -| 2022-01-01T15:00:00Z | 22.772071999999998 | -| 2022-01-01T16:00:00Z | 22.55332832 | -| 2022-01-01T17:00:00Z | 22.642048063999997 | -| 2022-01-01T18:00:00Z | 23.0672594816 | -| 2022-01-01T19:00:00Z | 23.12957407488 | -| 2022-01-01T20:00:00Z | 22.89127547648 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.8312 | -| 2022-01-01T15:00:00Z | 22.792303999999998 | -| 2022-01-01T16:00:00Z | 22.5715328 | -| 2022-01-01T17:00:00Z | 22.65660992 | -| 2022-01-01T18:00:00Z | 23.078180096 | -| 2022-01-01T19:00:00Z | 23.137436544 | -| 2022-01-01T20:00:00Z | 22.89677901824 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - DOUBLE_EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | double_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2020-07-07T00:00:00Z | 63.01034259259259 | -| 2020-10-05T00:00:00Z | 59.68671666666667 | -| 2021-01-03T00:00:00Z | 56.266558888888895 | -| 2021-04-03T00:00:00Z | 58.20687488888889 | -| 2021-07-02T00:00:00Z | 61.229622000000006 | -| 2021-09-30T00:00:00Z | 58.78596032888889 | -| 2021-12-29T00:00:00Z | 55.1067106968889 | -| 2022-03-29T00:00:00Z | 57.311773784533344 | -| 2022-06-27T00:00:00Z | 61.66637935722668 | -| 2022-09-25T00:00:00Z | 57.77452777735112 | -| 2022-12-24T00:00:00Z | 55.044203430886405 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### EXPONENTIAL_MOVING_AVERAGE() - -An exponential moving average (EMA) (or exponentially weighted moving average) -is a type of moving average similar to a -[simple moving average](/influxdb/clustered/reference/influxql/functions/transformations/#moving_average), -except more weight is given to the latest data. - -This type of moving average reacts faster to recent data changes than a simple moving average. -{{% cite %}}[Source](https://www.investopedia.com/terms/e/ema.asp){{% /cite %}} - -```sql -EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-ema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `period - 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 22.47 | -| 2022-01-01T12:00:00Z | 22.482 | -| 2022-01-01T13:00:00Z | 22.6092 | -| 2022-01-01T14:00:00Z | 22.68552 | -| 2022-01-01T15:00:00Z | 22.691312 | -| 2022-01-01T16:00:00Z | 22.5747872 | -| 2022-01-01T17:00:00Z | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 22.894923392 | -| 2022-01-01T19:00:00Z | 22.9769540352 | -| 2022-01-01T20:00:00Z | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average_co | exponential_moving_average_hum | exponential_moving_average_temp | -| :------------------- | ----------------------------: | -----------------------------: | ------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.06 | 22.47 | -| 2022-01-01T12:00:00Z | 0 | 36.036 | 22.482 | -| 2022-01-01T13:00:00Z | 0.4 | 36.2216 | 22.6092 | -| 2022-01-01T14:00:00Z | 0.64 | 36.25296 | 22.68552 | -| 2022-01-01T15:00:00Z | 1.584 | 36.231776 | 22.691312 | -| 2022-01-01T16:00:00Z | 3.7504000000000004 | 36.1390656 | 22.5747872 | -| 2022-01-01T17:00:00Z | 5.85024 | 36.08343936 | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 10.710144 | 36.410063616 | 22.894923392 | -| 2022-01-01T19:00:00Z | 15.2260864 | 36.4860381696 | 22.9769540352 | -| 2022-01-01T20:00:00Z | 19.53565184 | 36.49162290176 | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T14:00:00Z | 22.68552 | -| 2022-01-01T15:00:00Z | 22.691312 | -| 2022-01-01T16:00:00Z | 22.5747872 | -| 2022-01-01T17:00:00Z | 22.624872319999998 | -| 2022-01-01T18:00:00Z | 22.894923392 | -| 2022-01-01T19:00:00Z | 22.9769540352 | -| 2022-01-01T20:00:00Z | 22.866172421119998 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2022-01-01T11:00:00Z | 22.275 | -| 2022-01-01T12:00:00Z | 22.365 | -| 2022-01-01T13:00:00Z | 22.538999999999998 | -| 2022-01-01T14:00:00Z | 22.6434 | -| 2022-01-01T15:00:00Z | 22.66604 | -| 2022-01-01T16:00:00Z | 22.559624 | -| 2022-01-01T17:00:00Z | 22.6157744 | -| 2022-01-01T18:00:00Z | 22.88946464 | -| 2022-01-01T19:00:00Z | 22.973678784 | -| 2022-01-01T20:00:00Z | 22.8642072704 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | exponential_moving_average | -| :------------------- | -------------------------: | -| 2020-07-07T00:00:00Z | 59.971944444444446 | -| 2020-10-05T00:00:00Z | 58.65427777777778 | -| 2021-01-03T00:00:00Z | 56.77478888888889 | -| 2021-04-03T00:00:00Z | 57.86042888888889 | -| 2021-07-02T00:00:00Z | 59.836257333333336 | -| 2021-09-30T00:00:00Z | 58.657309955555554 | -| 2021-12-29T00:00:00Z | 56.38994152888889 | -| 2022-03-29T00:00:00Z | 57.44729825066667 | -| 2022-06-27T00:00:00Z | 60.13504561706667 | -| 2022-09-25T00:00:00Z | 58.085471814684446 | -| 2022-12-24T00:00:00Z | 56.30128308881067 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### KAUFMANS_EFFICIENCY_RATIO() - -Kaufman's Efficiency Ration, or simply "Efficiency Ratio" (ER), is calculated by -dividing the data change over a period by the absolute sum of the data movements -that occurred to achieve that change. -The resulting ratio ranges between 0 and 1 with higher values representing a -more efficient or trending market. - -The ER is very similar to the [Chande Momentum Oscillator](#chande_momentum_oscillator) (CMO). -The difference is that the CMO takes market direction into account, but if you -take the absolute CMO and divide by 100, you you get the Efficiency Ratio. -{{% cite %}}[Source](http://etfhq.com/blog/2011/02/07/kaufmans-efficiency-ratio/){{% /cite %}} - -```sql -KAUFMANS_EFFICIENCY_RATIO(field_expression, period[, hold_period]) -``` - -#### Arguments {#arguments-er} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is the same as `period`. - Must be an integer greater than or equal to `1`. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2022-01-01T12:00:00Z | 0.555555555555555 | -| 2022-01-01T13:00:00Z | 0.19999999999999857 | -| 2022-01-01T14:00:00Z | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio_co | kaufmans_efficiency_ratio_hum | kaufmans_efficiency_ratio_temp | -| :------------------- | ---------------------------: | ----------------------------: | -----------------------------: | -| 2022-01-01T12:00:00Z | 0 | 0.2 | 0.555555555555555 | -| 2022-01-01T13:00:00Z | 1 | 0.4285714285714228 | 0.19999999999999857 | -| 2022-01-01T14:00:00Z | 1 | 0.24999999999999334 | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 1 | 0.25000000000000444 | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 1 | 0 | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 1 | 1 | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 1 | 0.500000000000003 | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 1 | 0.285714285714285 | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 1 | 0.38461538461538547 | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2022-01-01T14:00:00Z | 0.14285714285714432 | -| 2022-01-01T15:00:00Z | 0.5999999999999972 | -| 2022-01-01T16:00:00Z | 0.14285714285714432 | -| 2022-01-01T17:00:00Z | 0.14285714285714432 | -| 2022-01-01T18:00:00Z | 0.38461538461538336 | -| 2022-01-01T19:00:00Z | 0.2857142857142868 | -| 2022-01-01T20:00:00Z | 0.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - KAUFMANS_EFFICIENCY_RATIO(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | kaufmans_efficiency_ratio | -| :------------------- | ------------------------: | -| 2020-10-05T00:00:00Z | 0.21498959056210964 | -| 2021-01-03T00:00:00Z | 0.020072053525475923 | -| 2021-04-03T00:00:00Z | 0.06190741773563866 | -| 2021-07-02T00:00:00Z | 0.08924485125858131 | -| 2021-09-30T00:00:00Z | 0.0120788302606483 | -| 2021-12-29T00:00:00Z | 0.05181655747468743 | -| 2022-03-29T00:00:00Z | 0.023768115942028996 | -| 2022-06-27T00:00:00Z | 0.06511381683430421 | -| 2022-09-25T00:00:00Z | 0.07748739110499749 | -| 2022-12-24T00:00:00Z | 0.029287632689602317 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### KAUFMANS_ADAPTIVE_MOVING_AVERAGE() - -Kaufman's Adaptive Moving Average (KAMA) is a moving average designed to account -for sample noise or volatility. -KAMA will closely follow data points when the data swings are relatively small and noise is low. -KAMA will adjust when the data swings widen and follow data from a greater distance. -This trend-following indicator can be used to identify the overall trend, -time turning points and filter data movements. -{{% cite %}}[Source](http://stockcharts.com/school/doku.php?id=chart_school:technical_indicators:kaufman_s_adaptive_moving_average){{% /cite %}} - -```sql -KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_expression, period[, hold_period]) -``` - -#### Arguments {#arguments-kama} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is the same as `period`. - Must be an integer greater than or equal to `1`. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2022-01-01T12:00:00Z | 22.415923627793976 | -| 2022-01-01T13:00:00Z | 22.429061002513993 | -| 2022-01-01T14:00:00Z | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average_co | kaufmans_adaptive_moving_average_hum | kaufmans_adaptive_moving_average_temp | -| :------------------- | ----------------------------------: | -----------------------------------: | ------------------------------------: | -| 2022-01-01T12:00:00Z | 0 | 36 | 22.415923627793976 | -| 2022-01-01T13:00:00Z | 0.44444444444444453 | 36.052029136316335 | 22.429061002513993 | -| 2022-01-01T14:00:00Z | 0.6913580246913581 | 36.063497322866624 | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 1.7174211248285327 | 36.06981031521873 | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 4.065233958238074 | 36.069519741586184 | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 6.258463310132264 | 36.03862207865899 | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 11.476924061184592 | 36.153751327944484 | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 16.153846700658107 | 36.17872350475971 | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 20.52991483369895 | 36.206893865280215 | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2022-01-01T14:00:00Z | 22.43746706604819 | -| 2022-01-01T15:00:00Z | 22.48506721007708 | -| 2022-01-01T16:00:00Z | 22.48313945274385 | -| 2022-01-01T17:00:00Z | 22.488053855248438 | -| 2022-01-01T18:00:00Z | 22.559247409584806 | -| 2022-01-01T19:00:00Z | 22.589508047087516 | -| 2022-01-01T20:00:00Z | 22.59328743653712 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - KAUFMANS_ADAPTIVE_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | kaufmans_adaptive_moving_average | -| :------------------- | -------------------------------: | -| 2020-10-05T00:00:00Z | 64.23776629054989 | -| 2021-01-03T00:00:00Z | 64.17743082167587 | -| 2021-04-03T00:00:00Z | 64.12884833681618 | -| 2021-07-02T00:00:00Z | 64.11026540732492 | -| 2021-09-30T00:00:00Z | 64.07304846623671 | -| 2021-12-29T00:00:00Z | 63.97149717822299 | -| 2022-03-29T00:00:00Z | 63.94081206327896 | -| 2022-06-27T00:00:00Z | 63.94324197904272 | -| 2022-09-25T00:00:00Z | 63.83284150412919 | -| 2022-12-24T00:00:00Z | 63.76394979616807 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### RELATIVE_STRENGTH_INDEX() - -The relative strength index (RSI) is a momentum indicator that compares the -magnitude of recent increases and decreases over a specified time period to -measure speed and change of data movements. -{{% cite %}}[Source](https://www.investopedia.com/terms/r/rsi.asp){{% /cite %}} - -```sql -RELATIVE_STRENGTH_INDEX(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-rsi} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is the same as the `period`. - Must be an integer greater than or equal to `-1`. -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T12:00:00Z | 92.39130434782608 | -| 2022-01-01T13:00:00Z | 92.78350515463916 | -| 2022-01-01T14:00:00Z | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index_co | relative_strength_index_hum | relative_strength_index_temp | -| :------------------- | -------------------------: | --------------------------: | ---------------------------: | -| 2022-01-01T12:00:00Z | | 98.11827956989245 | 92.39130434782608 | -| 2022-01-01T13:00:00Z | 100 | 98.23677581863977 | 92.78350515463916 | -| 2022-01-01T14:00:00Z | 100 | 95.04467912266443 | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 100 | 93.02941956003185 | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 100 | 88.05084037126848 | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 100 | 88.05084037126848 | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 100 | 91.63299959013992 | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 100 | 80.85951627810859 | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 100 | 76.8440852816889 | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T14:00:00Z | 92.78350515463916 | -| 2022-01-01T15:00:00Z | 90.03334568358646 | -| 2022-01-01T16:00:00Z | 80.49022855250077 | -| 2022-01-01T17:00:00Z | 82.90606558962943 | -| 2022-01-01T18:00:00Z | 87.14940243872873 | -| 2022-01-01T19:00:00Z | 78.48983186121941 | -| 2022-01-01T20:00:00Z | 62.04865064241268 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2022-01-01T12:00:00Z | 97.46835443037975 | -| 2022-01-01T13:00:00Z | 97.52066115702479 | -| 2022-01-01T14:00:00Z | 97.52066115702479 | -| 2022-01-01T15:00:00Z | 96.34109464771694 | -| 2022-01-01T16:00:00Z | 91.89501009518312 | -| 2022-01-01T17:00:00Z | 92.36482202699028 | -| 2022-01-01T18:00:00Z | 93.38702507648456 | -| 2022-01-01T19:00:00Z | 88.1423325938459 | -| 2022-01-01T20:00:00Z | 76.66135862958828 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - RELATIVE_STRENGTH_INDEX(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | relative_strength_index | -| :------------------- | ----------------------: | -| 2020-10-05T00:00:00Z | 69.9692046299246 | -| 2021-01-03T00:00:00Z | 63.37405020679043 | -| 2021-04-03T00:00:00Z | 70.82662989351107 | -| 2021-07-02T00:00:00Z | 74.90131747577793 | -| 2021-09-30T00:00:00Z | 56.212729394565066 | -| 2021-12-29T00:00:00Z | 46.095152535803514 | -| 2022-03-29T00:00:00Z | 60.709021374375894 | -| 2022-06-27T00:00:00Z | 69.93773053391476 | -| 2022-09-25T00:00:00Z | 44.87321655968338 | -| 2022-12-24T00:00:00Z | 41.845933101386215 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### TRIPLE_EXPONENTIAL_MOVING_AVERAGE() - -The triple exponential moving average (TEMA) filters out volatility from -conventional moving averages. -While the name implies that it's a triple exponential smoothing, it's actually a -composite of a [single exponential moving average](#exponential_moving_average), -a [double exponential moving average](#double_exponential_moving_average), -and a triple exponential moving average. -{{% cite %}}[Source](https://www.investopedia.com/terms/t/triple-exponential-moving-average.asp){{% /cite %}} - -```sql -TRIPLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-tema} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :------------------ | - | exponential | `period - 1` | - | simple | `(period - 1) × 3` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T11:00:00Z | 22.54347777777777 | -| 2022-01-01T12:00:00Z | 22.499126666666672 | -| 2022-01-01T13:00:00Z | 22.716772000000002 | -| 2022-01-01T14:00:00Z | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 22.6128236096 | -| 2022-01-01T18:00:00Z | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average_co | triple_exponential_moving_average_hum | triple_exponential_moving_average_temp | -| :------------------- | -----------------------------------: | ------------------------------------: | -------------------------------------: | -| 2022-01-01T11:00:00Z | 0 | 36.03026666666666 | 22.54347777777777 | -| 2022-01-01T12:00:00Z | 0 | 35.99608 | 22.499126666666672 | -| 2022-01-01T13:00:00Z | 0.7840000000000001 | 36.379856000000004 | 22.716772000000002 | -| 2022-01-01T14:00:00Z | 1.0432 | 36.353712 | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 2.663040000000001 | 36.25279040000001 | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 6.300159999999999 | 36.054262656000006 | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 8.977536 | 35.98746094080001 | 22.6128236096 | -| 2022-01-01T18:00:00Z | 16.698608639999996 | 36.67902875136 | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 22.122591232 | 36.68111467007999 | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 26.541314662400005 | 36.579546917888 | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T14:00:00Z | 22.790124000000006 | -| 2022-01-01T15:00:00Z | 22.728720799999994 | -| 2022-01-01T16:00:00Z | 22.465986271999995 | -| 2022-01-01T17:00:00Z | 22.6128236096 | -| 2022-01-01T18:00:00Z | 23.142821016320013 | -| 2022-01-01T19:00:00Z | 23.163081365760007 | -| 2022-01-01T20:00:00Z | 22.834869660416004 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2022-01-01T17:00:00Z | 22.65201408 | -| 2022-01-01T18:00:00Z | 23.164150553600003 | -| 2022-01-01T19:00:00Z | 23.17404420096 | -| 2022-01-01T20:00:00Z | 22.84003200512 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - TRIPLE_EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | triple_exponential_moving_average | -| :------------------- | --------------------------------: | -| 2020-07-07T00:00:00Z | 64.17547253086421 | -| 2020-10-05T00:00:00Z | 59.182219074074055 | -| 2021-01-03T00:00:00Z | 55.03945899999998 | -| 2021-04-03T00:00:00Z | 57.98342055555557 | -| 2021-07-02T00:00:00Z | 61.72370060000002 | -| 2021-09-30T00:00:00Z | 58.3235789128889 | -| 2021-12-29T00:00:00Z | 53.982153124088896 | -| 2022-03-29T00:00:00Z | 57.325663060373344 | -| 2022-06-27T00:00:00Z | 62.67482784650667 | -| 2022-09-25T00:00:00Z | 57.274230204423134 | -| 2022-12-24T00:00:00Z | 54.17634351477504 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### TRIPLE_EXPONENTIAL_DERIVATIVE() - -The triple exponential derivative indicator, commonly referred to as "TRIX," is -an oscillator used to identify oversold and overbought markets, and can also be -used as a momentum indicator. -TRIX calculates a [triple exponential moving average](#triple_exponential_moving_average) -of the [log](/influxdb/v2/query-data/influxql/functions/transformations/#log) -of the data input over the period of time. -The previous value is subtracted from the previous value. -This prevents cycles that are shorter than the defined period from being considered by the indicator. - -Like many oscillators, TRIX oscillates around a zero line. When used as an oscillator, -a positive value indicates an overbought market while a negative value indicates an oversold market. -When used as a momentum indicator, a positive value suggests momentum is increasing -while a negative value suggests momentum is decreasing. -Many analysts believe that when the TRIX crosses above the zero line it gives a -buy signal, and when it closes below the zero line, it gives a sell signal. -{{% cite %}}[Source](https://www.investopedia.com/articles/technical/02/092402.asp){{% /cite %}} - -```sql -TRIPLE_EXPONENTIAL_DERIVATIVE(field_expression, period[, hold_period[, warmup_type]]) -``` - -#### Arguments {#arguments-trix} - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **period**: Number of values to use as the sample size for the algorithm. - Supports integers greater than or equal to 1. - This also controls the exponential decay rate (α) used to determine the weight - of an historical value. - With a period of `3`, the algorithm uses the current value and the previous - two values. -- **hold_period**: Number of values the algorithm needs before emitting results. - Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. - Must be an integer greater than or equal to `-1`. - - | Warmup type | Default hold_period | - | :---------- | :--------------------- | - | exponential | `period` | - | simple | `(period - 1) × 3 + 1` | - -- **warmup_type**: Controls how the algorithm initializes the first `period` values. - Supports the following warmup types: - - - **exponential**: _(Default)_ Exponential moving average of the first `period` - values with scaling alpha (α). - When this method is used and `hold_period` is unspecified or -1, the - algorithm may start emitting points after a much smaller sample size than with _simple_. - - **simple**: Simple moving average of the first `period` values. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -{{< expand-wrapper >}} -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to a field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T12:00:00Z | 0.5731400170122969 | -| 2022-01-01T13:00:00Z | 0.5082054442170802 | -| 2022-01-01T14:00:00Z | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to each field" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(*, 4) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative_co | triple_exponential_derivative_hum | triple_exponential_derivative_temp | -| :------------------- | -------------------------------: | --------------------------------: | ---------------------------------: | -| 2022-01-01T12:00:00Z | | 0.011689978802653656 | 0.5731400170122969 | -| 2022-01-01T13:00:00Z | | 0.08193865253971477 | 0.5082054442170802 | -| 2022-01-01T14:00:00Z | 179.99999999999997 | 0.10794983570248107 | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 148.57142857142853 | 0.0905729924662868 | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 140.22988505747128 | 0.02876803922613469 | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 92.48803827751195 | -0.022670378539191294 | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 84.49217002237135 | 0.10699801078373206 | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 64.59469801081093 | 0.17000537478475408 | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 48.10094220759999 | 0.16771238737589567 | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a custom hold period" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4, 6) -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T14:00:00Z | 0.45740027258918126 | -| 2022-01-01T15:00:00Z | 0.36931756808027405 | -| 2022-01-01T16:00:00Z | 0.1953270968520826 | -| 2022-01-01T17:00:00Z | 0.13729679242548976 | -| 2022-01-01T18:00:00Z | 0.28596038472352703 | -| 2022-01-01T19:00:00Z | 0.3509641845184319 | -| 2022-01-01T20:00:00Z | 0.23932489811719915 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a default non-default warmup type" %}} - -The following example uses the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4, -1, 'simple') -FROM home -WHERE - room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2022-01-01T18:00:00Z | 0.3040309049773704 | -| 2022-01-01T19:00:00Z | 0.37510717611963784 | -| 2022-01-01T20:00:00Z | 0.2625157254706467 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to time windows (grouped by time)" %}} - -The following example use the -[NOAA Bay Area weather sample data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather). - -```sql -SELECT - TRIPLE_EXPONENTIAL_DERIVATIVE(MEAN(temp_avg), 4) -FROM weather -WHERE - location = 'San Francisco' - AND time >= '2020-01-01T00:00:00Z' - AND time <= '2022-12-31T23:59:59Z' -GROUP BY time(90d) -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | triple_exponential_derivative | -| :------------------- | ----------------------------: | -| 2020-10-05T00:00:00Z | 1.8609138140919912 | -| 2021-01-03T00:00:00Z | 0.8545019640246121 | -| 2021-04-03T00:00:00Z | 0.6716861515154271 | -| 2021-07-02T00:00:00Z | 1.0528294030543783 | -| 2021-09-30T00:00:00Z | 0.6847349621789123 | -| 2021-12-29T00:00:00Z | -0.18257939931221046 | -| 2022-03-29T00:00:00Z | -0.1722392917734461 | -| 2022-06-27T00:00:00Z | 0.6038050639217252 | -| 2022-09-25T00:00:00Z | 0.21734485841473639 | -| 2022-12-24T00:00:00Z | -0.44578753427667595 | - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/influxql/functions/transformations.md b/content/influxdb/clustered/reference/influxql/functions/transformations.md index 8070a65e4..24368fb30 100644 --- a/content/influxdb/clustered/reference/influxql/functions/transformations.md +++ b/content/influxdb/clustered/reference/influxql/functions/transformations.md @@ -1,6 +1,6 @@ --- title: InfluxQL transformation functions -list_title: Tranfsormation functions +list_title: Transformation functions description: > Use transformation functions modify and return values in each row of queried data. menu: @@ -8,2743 +8,6 @@ menu: name: Transformations parent: influxql-functions weight: 205 + +source: /shared/influxql-v3-reference/functions/transformations.md --- - -InfluxQL transformation functions modify and return values in each row of queried data. - -- [ABS()](#abs) -- [ACOS()](#acos) -- [ASIN()](#asin) -- [ATAN()](#atan) -- [ATAN2()](#atan2) -- [CEIL()](#ceil) -- [COS()](#cos) -- [CUMULATIVE_SUM()](#cumulative_sum) -- [DERIVATIVE()](#derivative) -- [DIFFERENCE()](#difference) -- [ELAPSED()](#elapsed) -- [EXP()](#exp) -- [FLOOR()](#floor) -- [LN()](#ln) -- [LOG()](#log) -- [LOG2()](#log2) -- [LOG10()](#log10) -- [MOVING_AVERAGE()](#moving_average) -- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) -- [NON_NEGATIVE_DIFFERENCE()](#non_negative_difference) -- [POW()](#pow) -- [ROUND()](#round) -- [SIN()](#sin) -- [SQRT()](#sqrt) -- [TAN()](#tan) - -{{% note %}} -#### Missing InfluxQL functions - -Some InfluxQL functions are in the process of being rearchitected to work with -the InfluxDB 3.0 storage engine. If a function you need is not here, check the -[InfluxQL feature support page](/influxdb/clustered/reference/influxql/feature-support/#function-support) -for more information. -{{% /note %}} - -## Notable behaviors of transformation functions - -#### Must use aggregate or selector functions when grouping by time - -Most transformation functions support `GROUP BY` clauses that group by tags, -but do not directly support `GROUP BY` clauses that group by time. -To use transformation functions with with a `GROUP BY time()` clause, apply -an [aggregate](/influxdb/clustered/reference/influxql/functions/aggregates/) -or [selector](/influxdb/clustered/reference/influxql/functions/selectors/) -function to the **field_expression** argument. -The transformation operates on the result of the aggregate or selector operation. - ---- - -## ABS() - -Returns the absolute value of the field value. - -```sql -ABS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ABS()` to a field" %}} - -```sql -SELECT - a, - ABS(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | abs | -| :------------------- | -----------------: | ----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.33909108671076 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 0.774984088561186 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 0.921037167720451 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 0.73880754843378 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 0.905980032168252 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 0.891164752631417 | - -{{% /expand %}} - -{{% expand "Apply `ABS()` to each field" %}} - -```sql -SELECT ABS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | abs_a | abs_b | -| :------------------- | ----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.163643058925645 | -| 2023-01-01T00:01:00Z | 0.774984088561186 | 0.137034364053949 | -| 2023-01-01T00:02:00Z | 0.921037167720451 | 0.482943221384294 | -| 2023-01-01T00:03:00Z | 0.73880754843378 | 0.0729732928756677 | -| 2023-01-01T00:04:00Z | 0.905980032168252 | 1.77857552719844 | -| 2023-01-01T00:05:00Z | 0.891164752631417 | 0.741147445214238 | - -{{% /expand %}} - -{{% expand "Apply `ABS()` to time windows (grouped by time)" %}} - -```sql -SELECT - ABS(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | abs | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 0.4345725888930678 | -| 2023-01-01T00:10:00Z | 0.12861008519618367 | -| 2023-01-01T00:20:00Z | 0.030168160597251192 | -| 2023-01-01T00:30:00Z | 0.02928699660831855 | -| 2023-01-01T00:40:00Z | 0.02211434600834538 | -| 2023-01-01T00:50:00Z | 0.15530468657783394 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ACOS() - -Returns the arccosine (in radians) of the field value. -Field values must be between -1 and 1. - -```sql -ACOS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ACOS()` to a field" %}} - -```sql -SELECT - a, - ACOS(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | acos | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 1.2248457522250173 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 2.4574862443115 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 2.741531473732281 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 2.4020955294179256 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 2.7044854502651114 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 2.6707024029338 | - -{{% /expand %}} - -{{% expand "Apply `ACOS()` to each field" %}} - -```sql -SELECT ACOS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | acos_a | acos_b | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 1.2248457522250173 | 1.7351786975993897 | -| 2023-01-01T00:01:00Z | 2.4574862443115 | 1.433329416131427 | -| 2023-01-01T00:02:00Z | 2.741531473732281 | 2.074809114132046 | -| 2023-01-01T00:03:00Z | 2.4020955294179256 | 1.6438345403920092 | -| 2023-01-01T00:04:00Z | 2.7044854502651114 | | -| 2023-01-01T00:05:00Z | 2.6707024029338 | 0.7360183965088304 | - -{{% /expand %}} - -{{% expand "Apply `ACOS()` to time windows (grouped by time)" %}} - -```sql -SELECT - ACOS(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | acos | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 2.0203599837582877 | -| 2023-01-01T00:10:00Z | 1.441829029328407 | -| 2023-01-01T00:20:00Z | 1.5406235882252437 | -| 2023-01-01T00:30:00Z | 1.5415051418561052 | -| 2023-01-01T00:40:00Z | 1.5486801779072885 | -| 2023-01-01T00:50:00Z | 1.41486045205998 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ASIN() - -Returns the arcsine (in radians) of the field value. -Field values must be between -1 and 1. - -```sql -ASIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ASIN()` to a field" %}} - -```sql -SELECT - a, - ASIN(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | asin | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.34595057456987915 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | -0.8866899175166036 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | -1.1707351469373848 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | -0.8312992026230288 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | -1.133689123470215 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | -1.0999060761389035 | - -{{% /expand %}} - -{{% expand "Apply `ASIN()` to each field" %}} - -```sql -SELECT ASIN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | asin_a | asin_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.34595057456987915 | -0.1643823708044932 | -| 2023-01-01T00:01:00Z | -0.8866899175166036 | 0.1374669106634696 | -| 2023-01-01T00:02:00Z | -1.1707351469373848 | -0.5040127873371497 | -| 2023-01-01T00:03:00Z | -0.8312992026230288 | -0.07303821359711259 | -| 2023-01-01T00:04:00Z | -1.133689123470215 | | -| 2023-01-01T00:05:00Z | -1.0999060761389035 | 0.8347779302860662 | - -{{% /expand %}} - -{{% expand "Apply `ASIN()` to time windows (grouped by time)" %}} - -```sql -SELECT - ASIN(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | asin | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.44956365696339134 | -| 2023-01-01T00:10:00Z | 0.1289672974664895 | -| 2023-01-01T00:20:00Z | 0.030172738569652847 | -| 2023-01-01T00:30:00Z | 0.029291184938791334 | -| 2023-01-01T00:40:00Z | 0.022116148887608062 | -| 2023-01-01T00:50:00Z | 0.15593587473491674 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ATAN() - -Returns the arctangent (in radians) of the field value. - -```sql -ATAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ATAN()` to a field" %}} - -```sql -SELECT - a, - ATAN(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | atan | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.32692355076199897 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | -0.659300127490126 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | -0.7443170183837121 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | -0.6362993731936669 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | -0.7361091800814261 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | -0.727912249468035 | - -{{% /expand %}} - -{{% expand "Apply `ATAN()` to each field" %}} - -```sql -SELECT ATAN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan_a | atan_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.32692355076199897 | -0.1622053541422186 | -| 2023-01-01T00:01:00Z | -0.659300127490126 | 0.13618613793696105 | -| 2023-01-01T00:02:00Z | -0.7443170183837121 | -0.4499093121666581 | -| 2023-01-01T00:03:00Z | -0.6362993731936669 | -0.07284417510130452 | -| 2023-01-01T00:04:00Z | -0.7361091800814261 | 1.0585985450688151 | -| 2023-01-01T00:05:00Z | -0.727912249468035 | 0.6378113578294793 | - -{{% /expand %}} - -{{% expand "Apply `ATAN()` to time windows (grouped by time)" %}} - -```sql -SELECT - ATAN(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.4099506966510045 | -| 2023-01-01T00:10:00Z | 0.1279079463727065 | -| 2023-01-01T00:20:00Z | 0.030159013397288013 | -| 2023-01-01T00:30:00Z | 0.02927862748761639 | -| 2023-01-01T00:40:00Z | 0.022110742100818606 | -| 2023-01-01T00:50:00Z | 0.15407382461141705 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ATAN2() - -Returns the the arctangent of `y/x` in radians. - -```sql -ATAN2(expression_y, expression_x) -``` - -#### Arguments - -- **expression_y**: Expression to identify the `y` numeric value or one or more - fields to operate on. - Can be a number literal, [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **expression_x**: Expression to identify the `x` numeric value or one or more - fields to operate on. - Can be a number literal, [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ATAN2()` to a field divided by another field" %}} - -```sql -SELECT ATAN2(a, b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2 | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 2.0204217911794937 | -| 2023-01-01T00:01:00Z | -1.395783190047229 | -| 2023-01-01T00:02:00Z | -2.053731408859953 | -| 2023-01-01T00:03:00Z | -1.669248713922653 | -| 2023-01-01T00:04:00Z | -0.47112754043763505 | -| 2023-01-01T00:05:00Z | -0.8770454978291377 | - -{{% /expand %}} - -{{% expand "Apply `ATAN2()` to each field divided by a numeric value" %}} - -```sql -SELECT ATAN2(*, 2) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2_a | atan2_b | -| :------------------- | -------------------: | --------------------: | -| 2023-01-01T00:00:00Z | 0.16794843225523703 | -0.0816396675119722 | -| 2023-01-01T00:01:00Z | -0.36967737169970566 | 0.06841026268126137 | -| 2023-01-01T00:02:00Z | -0.4315666721698651 | -0.2369359777533473 | -| 2023-01-01T00:03:00Z | -0.35385538623378937 | -0.036470468100670846 | -| 2023-01-01T00:04:00Z | -0.4253376417906667 | 0.7268651162204586 | -| 2023-01-01T00:05:00Z | -0.41917415992493756 | 0.35488446257957357 | - -{{% /expand %}} - -{{% expand "Apply `ATAN2()` to time windows (grouped by time)" %}} - -```sql -SELECT - ATAN2(MEAN(a), MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | atan2 | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | -1.278967897411707 | -| 2023-01-01T00:10:00Z | 2.3520553840586773 | -| 2023-01-01T00:20:00Z | 2.226497789888965 | -| 2023-01-01T00:30:00Z | 3.0977773783018656 | -| 2023-01-01T00:40:00Z | 2.9285769547942677 | -| 2023-01-01T00:50:00Z | 0.9505419744107901 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## CEIL() - -Returns the subsequent value rounded up to the nearest integer. - -```sql -CEIL(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `CEIL()` to a field" %}} - -```sql -SELECT - b, - CEIL(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | ceil | -| :------------------- | ------------------: | ---: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 1 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | - -{{% /expand %}} - -{{% expand "Apply `CEIL()` to each field" %}} - -```sql -SELECT CEIL(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ceil_a | ceil_b | -| :------------------- | -----: | -----: | -| 2023-01-01T00:00:00Z | 1 | -0 | -| 2023-01-01T00:01:00Z | -0 | 1 | -| 2023-01-01T00:02:00Z | -0 | -0 | -| 2023-01-01T00:03:00Z | -0 | -0 | -| 2023-01-01T00:04:00Z | -0 | 2 | -| 2023-01-01T00:05:00Z | -0 | 1 | - -{{% /expand %}} - -{{% expand "Apply `CEIL()` to time windows (grouped by time)" %}} - -```sql -SELECT - CEIL(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ceil | -| :------------------- | ---: | -| 2023-01-01T00:00:00Z | 1 | -| 2023-01-01T00:10:00Z | -0 | -| 2023-01-01T00:20:00Z | -0 | -| 2023-01-01T00:30:00Z | -0 | -| 2023-01-01T00:40:00Z | -0 | -| 2023-01-01T00:50:00Z | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## COS() - -Returns the cosine of the field value. - -```sql -COS(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `COS()` to a field" %}} - -```sql -SELECT - b, - COS(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | cos | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | 0.9866403278718959 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.9906254752128878 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | 0.8856319645801471 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | 0.9973386305831397 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | -0.20628737691395405 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.7376943643170851 | - -{{% /expand %}} - -{{% expand "Apply `COS()` to each field" %}} - -```sql -SELECT COS(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cos_a | cos_b | -| :------------------- | -----------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.9430573869206459 | 0.9866403278718959 | -| 2023-01-01T00:01:00Z | 0.7144321674550146 | 0.9906254752128878 | -| 2023-01-01T00:02:00Z | 0.6049946586273094 | 0.8856319645801471 | -| 2023-01-01T00:03:00Z | 0.7392720891861374 | 0.9973386305831397 | -| 2023-01-01T00:04:00Z | 0.616914561474936 | -0.20628737691395405 | -| 2023-01-01T00:05:00Z | 0.6285065034701617 | 0.7376943643170851 | - -{{% /expand %}} - -{{% expand "Apply `COS()` to time windows (grouped by time)" %}} - -```sql -SELECT - COS(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cos | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 0.9914907269510592 | -| 2023-01-01T00:10:00Z | 0.9918765457796455 | -| 2023-01-01T00:20:00Z | 0.9997307399250498 | -| 2023-01-01T00:30:00Z | 0.7850670342365872 | -| 2023-01-01T00:40:00Z | 0.9947779847618986 | -| 2023-01-01T00:50:00Z | 0.9938532355205111 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## CUMULATIVE_SUM() - -Returns the running total of subsequent [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -CUMULATIVE_SUM(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `CUMULATIVE_SUM()` to a field" %}} - -```sql -SELECT CUMULATIVE_SUM(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to each field" %}} - -```sql -SELECT CUMULATIVE_SUM(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum_a | cumulative_sum_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to field keys that match a regular expression" %}} - -```sql -SELECT CUMULATIVE_SUM(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum_a | cumulative_sum_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | -| 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | -| 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | -| 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | -| 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | -| 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | - -{{% /expand %}} - -{{% expand "Apply `CUMULATIVE_SUM()` to time windows (grouped by time)" %}} - -```sql -SELECT - CUMULATIVE_SUM(SUM(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | cumulative_sum | -| :------------------- | -------------------: | -| 2023-01-01T00:00:00Z | 1.3054783385851743 | -| 2023-01-01T00:10:00Z | 0.029980276948385454 | -| 2023-01-01T00:20:00Z | -0.20208529969578404 | -| 2023-01-01T00:30:00Z | -6.882005145666267 | -| 2023-01-01T00:40:00Z | -7.904410787756402 | -| 2023-01-01T00:50:00Z | -6.795080184131271 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DERIVATIVE() - -Returns the rate of change between subsequent [field values](/influxdb/clustered/reference/glossary/#field-value) -per `unit`. - -```sql -SELECT DERIVATIVE(field_expression[, unit]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **unit**: Unit of time to use to calculate the rate of change. - Supports [duration literals](/influxdb/clustered/reference/influxql/#durations). - _Default is `1s` (per second)_. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `DERIVATIVE()` to a field to calculate the per second change" %}} - -```sql -SELECT DERIVATIVE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | --------------------: | -| 2023-01-01T00:01:00Z | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to a field to calculate the per 5 minute change" %}} - -```sql -SELECT DERIVATIVE(b, 5m) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | ------------------: | -| 2023-01-01T00:01:00Z | 1.5033871148979698 | -| 2023-01-01T00:02:00Z | -3.0998879271912148 | -| 2023-01-01T00:03:00Z | 2.0498496425431316 | -| 2023-01-01T00:04:00Z | 9.257744100370537 | -| 2023-01-01T00:05:00Z | -5.187140409921009 | -| 2023-01-01T00:06:00Z | -2.26736721151909 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to each field" %}} - -```sql -SELECT DERIVATIVE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative_a | derivative_b | -| :------------------- | ---------------------: | --------------------: | -| 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to field keys that match a regular expression" %}} - -```sql -SELECT DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative_a | derivative_b | -| :------------------- | ---------------------: | --------------------: | -| 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | -| 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | - -{{% /expand %}} - -{{% expand "Apply `DERIVATIVE()` to time windows (grouped by time)" %}} - -```sql -SELECT - DERIVATIVE(MEAN(b), 1m) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | derivative | -| :------------------- | --------------------: | -| 2023-01-01T00:10:00Z | -0.025809764002219633 | -| 2023-01-01T00:20:00Z | 0.010434324849926194 | -| 2023-01-01T00:30:00Z | -0.06447854269326314 | -| 2023-01-01T00:40:00Z | 0.05657514203880348 | -| 2023-01-01T00:50:00Z | 0.021317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## DIFFERENCE() - -Returns the result of subtraction between subsequent [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -DIFFERENCE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [NON_NEGATIVE_DIFFERENCE()](#non_negative_difference) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `DIFFERENCE()` to a field" %}} - -```sql -SELECT DIFFERENCE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference | -| :------------------- | -------------------: | -| 2023-01-01T00:01:00Z | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to each field" %}} - -```sql -SELECT DIFFERENCE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference_a | difference_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to field keys that match a regular expression" %}} - -```sql -SELECT DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference_a | difference_b | -| :------------------- | -------------------: | -------------------: | -| 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | -| 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | -| 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | - -{{% /expand %}} - -{{% expand "Apply `DIFFERENCE()` to time windows (grouped by time)" %}} - -```sql -SELECT - DIFFERENCE(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | difference | -| :------------------- | ------------------: | -| 2023-01-01T00:10:00Z | -0.2580976400221963 | -| 2023-01-01T00:20:00Z | 0.10434324849926194 | -| 2023-01-01T00:30:00Z | -0.6447854269326314 | -| 2023-01-01T00:40:00Z | 0.5657514203880348 | -| 2023-01-01T00:50:00Z | 0.21317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ELAPSED() - -Returns the difference between subsequent [field value's](/influxdb/clustered/reference/glossary/#field-value) -timestamps in a specified `unit` of time. - -```sql -ELAPSED(field_expression[, unit ]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. -- **unit**: Unit of time to return the elapsed time in. - Supports [duration literals](/influxdb/clustered/reference/influxql/#durations). - _Default is `1ns` (nanoseconds)_. - -#### Notable behaviors - -- If the `unit` is greater than the elapsed time between points, `ELAPSED()` - returns `0`. -- `ELAPSED()` supports the `GROUP BY time()` clause but the query results aren't very useful. - An `ELAPSED()` query with a nested function and a `GROUP BY time()` clause - returns the interval specified in the `GROUP BY time()` clause. - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ELAPSED()` to a field and return elapsed time in nanoseconds" %}} - -```sql -SELECT ELAPSED(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed | -| :------------------- | ----------: | -| 2023-01-01T00:01:00Z | 60000000000 | -| 2023-01-01T00:02:00Z | 60000000000 | -| 2023-01-01T00:03:00Z | 60000000000 | -| 2023-01-01T00:04:00Z | 60000000000 | -| 2023-01-01T00:05:00Z | 60000000000 | -| 2023-01-01T00:06:00Z | 60000000000 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to a field and return elapsed time in seconds" %}} - -```sql -SELECT ELAPSED(b, 1s) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed | -| :------------------- | ------: | -| 2023-01-01T00:01:00Z | 60 | -| 2023-01-01T00:02:00Z | 60 | -| 2023-01-01T00:03:00Z | 60 | -| 2023-01-01T00:04:00Z | 60 | -| 2023-01-01T00:05:00Z | 60 | -| 2023-01-01T00:06:00Z | 60 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to each field" %}} - -```sql -SELECT ELAPSED(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed_a | elapsed_b | -| :------------------- | ----------: | ----------: | -| 2023-01-01T00:01:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:02:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:03:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:04:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:05:00Z | 60000000000 | 60000000000 | -| 2023-01-01T00:06:00Z | 60000000000 | 60000000000 | - -{{% /expand %}} - -{{% expand "Apply `ELAPSED()` to field keys that match a regular expression" %}} - -```sql -SELECT ELAPSED(/[ab]/, 1s) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | elapsed_a | elapsed_b | -| :------------------- | --------: | --------: | -| 2023-01-01T00:01:00Z | 60 | 60 | -| 2023-01-01T00:02:00Z | 60 | 60 | -| 2023-01-01T00:03:00Z | 60 | 60 | -| 2023-01-01T00:04:00Z | 60 | 60 | -| 2023-01-01T00:05:00Z | 60 | 60 | -| 2023-01-01T00:06:00Z | 60 | 60 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## EXP() - -Returns the exponential of the field value. - -```sql -EXP(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `EXP()` to a field" %}} - -```sql -SELECT - a, - EXP(a) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | a | exp | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.33909108671076 | 1.4036711951820788 | -| 2023-01-01T00:01:00Z | -0.774984088561186 | 0.460711111517308 | -| 2023-01-01T00:02:00Z | -0.921037167720451 | 0.39810592427186076 | -| 2023-01-01T00:03:00Z | -0.73880754843378 | 0.4776831901055915 | -| 2023-01-01T00:04:00Z | -0.905980032168252 | 0.40414561525252984 | -| 2023-01-01T00:05:00Z | -0.891164752631417 | 0.4101777188333968 | - -{{% /expand %}} - -{{% expand "Apply `EXP()` to each field" %}} - -```sql -SELECT EXP(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | exp_a | exp_b | -| :------------------- | ------------------: | -----------------: | -| 2023-01-01T00:00:00Z | 1.4036711951820788 | 0.8490450268435884 | -| 2023-01-01T00:01:00Z | 0.460711111517308 | 1.14686755886191 | -| 2023-01-01T00:02:00Z | 0.39810592427186076 | 0.6169648527893578 | -| 2023-01-01T00:03:00Z | 0.4776831901055915 | 0.929625657322271 | -| 2023-01-01T00:04:00Z | 0.40414561525252984 | 5.921415512753404 | -| 2023-01-01T00:05:00Z | 0.4101777188333968 | 2.09834186598405 | - -{{% /expand %}} - -{{% expand "Apply `EXP()` to time windows (grouped by time)" %}} - -```sql -SELECT - EXP(MEAN(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | exp | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | 0.6475413743155294 | -| 2023-01-01T00:10:00Z | 1.137246608416461 | -| 2023-01-01T00:20:00Z | 1.030627830373793 | -| 2023-01-01T00:30:00Z | 1.029720078241656 | -| 2023-01-01T00:40:00Z | 1.0223606806499268 | -| 2023-01-01T00:50:00Z | 1.1680137850180072 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FLOOR() - -Returns the subsequent value rounded down to the nearest integer. - -```sql -FLOOR(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `FLOOR()` to a field" %}} - -```sql -SELECT - b, - FLOOR(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | floor | -| :------------------- | ------------------: | ----: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -1 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -1 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -1 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 1 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0 | - -{{% /expand %}} - -{{% expand "Apply `FLOOR()` to each field" %}} - -```sql -SELECT FLOOR(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | floor_a | floor_b | -| :------------------- | ------: | ------: | -| 2023-01-01T00:00:00Z | 0 | -1 | -| 2023-01-01T00:01:00Z | -1 | 0 | -| 2023-01-01T00:02:00Z | -1 | -1 | -| 2023-01-01T00:03:00Z | -1 | -1 | -| 2023-01-01T00:04:00Z | -1 | 1 | -| 2023-01-01T00:05:00Z | -1 | 0 | - -{{% /expand %}} - -{{% expand "Apply `FLOOR()` to time windows (grouped by time)" %}} - -```sql -SELECT - FLOOR(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | floor | -| :------------------- | ----: | -| 2023-01-01T00:00:00Z | -5 | -| 2023-01-01T00:10:00Z | 1 | -| 2023-01-01T00:20:00Z | 0 | -| 2023-01-01T00:30:00Z | 0 | -| 2023-01-01T00:40:00Z | 0 | -| 2023-01-01T00:50:00Z | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LN() - -Returns the natural logarithm of the field value. -Field values must be greater than or equal to 0. - -```sql -LN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LN()` to a field" %}} - -```sql -SELECT - b, - LN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | ln | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -1.98752355209665 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5758127783016702 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2995556920844895 | - -{{% /expand %}} - -{{% expand "Apply `LN()` to each field" %}} - -```sql -SELECT LN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ln_a | ln_b | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -1.0814865153308908 | | -| 2023-01-01T00:01:00Z | | -1.98752355209665 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.5758127783016702 | -| 2023-01-01T00:05:00Z | | -0.2995556920844895 | - -{{% /expand %}} - -{{% expand "Apply `LN()` to time windows (grouped by time)" %}} - -```sql -SELECT - LN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | ln | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.25161504572793725 | -| 2023-01-01T00:20:00Z | -1.1983831026157092 | -| 2023-01-01T00:30:00Z | -1.2280265702380913 | -| 2023-01-01T00:40:00Z | -1.5089436474159283 | -| 2023-01-01T00:50:00Z | 0.4402187212890264 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG() - -Returns the logarithm of the field value with base `b`. -Field values must be greater than or equal to 0. - -```sql -LOG(field_expression, b) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **b**: Logarithm base to use in the operation. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG()` to a field with a base of 3" %}} - -```sql -SELECT - b, - LOG(b, 3) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -1.8091219009630797 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5241273780031629 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2726673414946528 | - -{{% /expand %}} - -{{% expand "Apply `LOG()` to each field with a base of 5" %}} - -```sql -SELECT LOG(*, 5) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log_a | log_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.6719653532302217 | | -| 2023-01-01T00:01:00Z | | -1.2349178161776593 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.3577725949246566 | -| 2023-01-01T00:05:00Z | | -0.18612441633827553 | - -{{% /expand %}} - -{{% expand "Apply `LOG()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG(SUM(a), 10) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.10927502592347751 | -| 2023-01-01T00:20:00Z | -0.5204511686721008 | -| 2023-01-01T00:30:00Z | -0.5333251630849791 | -| 2023-01-01T00:40:00Z | -0.6553258995757036 | -| 2023-01-01T00:50:00Z | 0.1911845614863297 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG2() - -Returns the logarithm of the field value to the base 2. -Field values must be greater than or equal to 0. - -```sql -LOG2(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG2()` to a field" %}} - -```sql -SELECT - b, - LOG2(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log2 | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -2.8673903722598544 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.8307222397363156 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.4321675114403543 | - -{{% /expand %}} - -{{% expand "Apply `LOG2()` to each field" %}} - -```sql -SELECT LOG2(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log2_a | log2_b | -| :------------------- | -----------------: | ------------------: | -| 2023-01-01T00:00:00Z | -1.560255232456162 | | -| 2023-01-01T00:01:00Z | | -2.8673903722598544 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.8307222397363156 | -| 2023-01-01T00:05:00Z | | -0.4321675114403543 | - -{{% /expand %}} - -{{% expand "Apply `LOG2()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG2(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log2 | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.36300377868474476 | -| 2023-01-01T00:20:00Z | -1.7289013592288134 | -| 2023-01-01T00:30:00Z | -1.7716678429623767 | -| 2023-01-01T00:40:00Z | -2.1769455171078644 | -| 2023-01-01T00:50:00Z | 0.6351013661101591 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## LOG10() - -Returns the logarithm of the field value to the base 10. -Field values must be greater than or equal to 0. - -```sql -LOG10(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `LOG10()` to a field" %}} - -```sql -SELECT - b, - LOG10(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | log10 | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | -0.8631705113283253 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.25007231222579585 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.1300953840950034 | - -{{% /expand %}} - -{{% expand "Apply `LOG10()` to each field" %}} - -```sql -SELECT LOG10(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log10_a | log10_b | -| :------------------- | -------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.46968362586098245 | | -| 2023-01-01T00:01:00Z | | -0.8631705113283253 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 0.25007231222579585 | -| 2023-01-01T00:05:00Z | | -0.1300953840950034 | - -{{% /expand %}} - -{{% expand "Apply `LOG10()` to time windows (grouped by time)" %}} - -```sql -SELECT - LOG10(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | log10 | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 0.10927502592347751 | -| 2023-01-01T00:20:00Z | -0.520451168672101 | -| 2023-01-01T00:30:00Z | -0.5333251630849791 | -| 2023-01-01T00:40:00Z | -0.6553258995757036 | -| 2023-01-01T00:50:00Z | 0.19118456148632973 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## MOVING_AVERAGE() - -Returns the rolling average across a window of subsequent [field values](/influxdb/clustered/reference/glossary/#field-value). - -```sql -MOVING_AVERAGE(field_expression, N) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports all field types. -- **N**: Number of field values to use when calculating the moving average. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `MOVING_AVERAGE()` to a field" %}} - -```sql -SELECT MOVING_AVERAGE(a, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average | -| :------------------- | ------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to each field" %}} - -```sql -SELECT MOVING_AVERAGE(*, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average_a | moving_average_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to field keys that match a regular expression" %}} - -```sql -SELECT MOVING_AVERAGE(/[ab]/, 3) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average_a | moving_average_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | -| 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | -| 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | -| 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | -| 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | -| 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | - -{{% /expand %}} - -{{% expand "Apply `MOVING_AVERAGE()` to time windows (grouped by time)" %}} - -```sql -SELECT - MOVING_AVERAGE(SUM(a), 3) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | moving_average | -| :------------------- | ------------------: | -| 2023-01-01T00:20:00Z | -0.9193144769987766 | -| 2023-01-01T00:30:00Z | 0.626884141339178 | -| 2023-01-01T00:40:00Z | 0.27189834404638374 | -| 2023-01-01T00:50:00Z | 0.6890200973149928 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## NON_NEGATIVE_DERIVATIVE() - -Returns only non-negative rate of change between subsequent -[field values](/influxdb/clustered/reference/glossary/#field-value). -Negative rates of change return _null_. - -```sql -NON_NEGATIVE_DERIVATIVE(field_expression[, unit]) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. -- **unit**: Unit of time to use to calculate the rate of change. - Supports [duration literals](/influxdb/clustered/reference/influxql/#durations). - _Default is `1s` (per second)_. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [DERIVATIVE()](#derivative) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per second change" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | 0.03085914700123513 | -| 2023-01-01T00:08:00Z | 0.0227877053636946 | -| 2023-01-01T00:10:00Z | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | 0.014999637478226817 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per 5 minute change" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(b, 5m) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 1.5033871148979698 | -| 2023-01-01T00:03:00Z | 2.0498496425431316 | -| 2023-01-01T00:04:00Z | 9.257744100370537 | -| 2023-01-01T00:08:00Z | 6.836311609108379 | -| 2023-01-01T00:10:00Z | 0.5028191431616502 | -| 2023-01-01T00:11:00Z | 4.499891243468045 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to each field" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative_a | non_negative_derivative_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | | -| 2023-01-01T00:08:00Z | | 0.0227877053636946 | -| 2023-01-01T00:09:00Z | 0.018437240876186967 | | -| 2023-01-01T00:10:00Z | | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | | 0.014999637478226817 | -| 2023-01-01T00:13:00Z | 0.006694752202850366 | | -| 2023-01-01T00:14:00Z | 0.011836797386191167 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to field keys that match a regular expression" %}} - -```sql -SELECT NON_NEGATIVE_DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative_a | non_negative_derivative_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.005011290382993233 | -| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | -| 2023-01-01T00:04:00Z | | 0.03085914700123513 | -| 2023-01-01T00:05:00Z | 0.00024692132561391543 | | -| 2023-01-01T00:06:00Z | 0.016704951104985283 | | -| 2023-01-01T00:08:00Z | | 0.0227877053636946 | -| 2023-01-01T00:09:00Z | 0.018437240876186967 | | -| 2023-01-01T00:10:00Z | | 0.001676063810538834 | -| 2023-01-01T00:11:00Z | | 0.014999637478226817 | -| 2023-01-01T00:13:00Z | 0.006694752202850366 | | -| 2023-01-01T00:14:00Z | 0.011836797386191167 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to time windows (grouped by time)" %}} - -```sql -SELECT - NON_NEGATIVE_DERIVATIVE(MEAN(b), 1m) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_derivative | -| :------------------- | ----------------------: | -| 2023-01-01T00:20:00Z | 0.010434324849926194 | -| 2023-01-01T00:40:00Z | 0.05657514203880348 | -| 2023-01-01T00:50:00Z | 0.021317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## NON_NEGATIVE_DIFFERENCE() - -Returns only non-negative result of subtraction between subsequent -[field values](/influxdb/clustered/reference/glossary/#field-value). -Negative differences return _null_. - -```sql -NON_NEGATIVE_DIFFERENCE(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, regular expression, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Related functions - -- [DIFFERENCE()](#difference) - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to a field" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(b) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference | -| :------------------- | ----------------------: | -| 2023-01-01T00:01:00Z | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | 1.8515488200741077 | -| 2023-01-01T00:08:00Z | 1.367262321821676 | -| 2023-01-01T00:10:00Z | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | 0.899978248693609 | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to each field" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference_a | non_negative_difference_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | | -| 2023-01-01T00:06:00Z | 1.002297066299117 | | -| 2023-01-01T00:08:00Z | | 1.367262321821676 | -| 2023-01-01T00:09:00Z | 1.106234452571218 | | -| 2023-01-01T00:10:00Z | | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | | 0.899978248693609 | -| 2023-01-01T00:13:00Z | 0.401685132171022 | | -| 2023-01-01T00:14:00Z | 0.71020784317147 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to field keys that match a regular expression" %}} - -```sql -SELECT NON_NEGATIVE_DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference_a | non_negative_difference_b | -| :------------------- | ------------------------: | ------------------------: | -| 2023-01-01T00:01:00Z | | 0.300677422979594 | -| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | -| 2023-01-01T00:04:00Z | | 1.8515488200741077 | -| 2023-01-01T00:05:00Z | 0.014815279536834924 | | -| 2023-01-01T00:06:00Z | 1.002297066299117 | | -| 2023-01-01T00:08:00Z | | 1.367262321821676 | -| 2023-01-01T00:09:00Z | 1.106234452571218 | | -| 2023-01-01T00:10:00Z | | 0.10056382863233004 | -| 2023-01-01T00:11:00Z | | 0.899978248693609 | -| 2023-01-01T00:13:00Z | 0.401685132171022 | | -| 2023-01-01T00:14:00Z | 0.71020784317147 | | - -{{% /expand %}} - -{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to time windows (grouped by time)" %}} - -```sql -SELECT - NON_NEGATIVE_DIFFERENCE(MEAN(b)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | non_negative_difference | -| :------------------- | ----------------------: | -| 2023-01-01T00:20:00Z | 0.10434324849926194 | -| 2023-01-01T00:40:00Z | 0.5657514203880348 | -| 2023-01-01T00:50:00Z | 0.21317362457152655 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## POW() - -Returns the field value to the power of `x`. - -```sql -POW(field_expression, x) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. -- **x**: Power to raise to. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `POW()` to a field with a power of 3" %}} - -```sql -SELECT - b, - POW(b, 3) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | pow | -| :------------------- | ------------------: | ---------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.004382205777325515 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.002573288422171338 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.1126388541916811 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0003885901893904874 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 5.626222933751733 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.4071119474284653 | - -{{% /expand %}} - -{{% expand "Apply `POW()` to each field with a power of 5" %}} - -```sql -SELECT POW(*, 5) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | pow_a | pow_b | -| :------------------- | -------------------: | -----------------------: | -| 2023-01-01T00:00:00Z | 0.004483135555212479 | -0.00011735131084020357 | -| 2023-01-01T00:01:00Z | -0.2795528536239978 | 0.000048322282876973225 | -| 2023-01-01T00:02:00Z | -0.6628050073932118 | -0.026271227986693114 | -| 2023-01-01T00:03:00Z | -0.22011853819169455 | -0.000002069282189962477 | -| 2023-01-01T00:04:00Z | -0.6103699296012646 | 17.797604890097084 | -| 2023-01-01T00:05:00Z | -0.5620694808926487 | 0.22362640363833164 | - -{{% /expand %}} - -{{% expand "Apply `POW()` to time windows (grouped by time)" %}} - -```sql -SELECT - POW(SUM(a), 10) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | pow | -| :------------------- | -----------------------: | -| 2023-01-01T00:00:00Z | 2402278.159218532 | -| 2023-01-01T00:10:00Z | 12.380844221267186 | -| 2023-01-01T00:20:00Z | 0.000006244365466732681 | -| 2023-01-01T00:30:00Z | 0.0000046424621235691315 | -| 2023-01-01T00:40:00Z | 2.7973126174031977e-7 | -| 2023-01-01T00:50:00Z | 81.6292140233699 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ROUND() - -Returns a field value rounded to the nearest integer. - -```sql -ROUND(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `ROUND()` to a field" %}} - -```sql -SELECT - b, - ROUND(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | round | -| :------------------- | ------------------: | ----: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | - -{{% /expand %}} - -{{% expand "Apply `ROUND()` to each field" %}} - -```sql -SELECT ROUND(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | round_a | round_b | -| :------------------- | ------: | ------: | -| 2023-01-01T00:00:00Z | 0 | -0 | -| 2023-01-01T00:01:00Z | -1 | 0 | -| 2023-01-01T00:02:00Z | -1 | -0 | -| 2023-01-01T00:03:00Z | -1 | -0 | -| 2023-01-01T00:04:00Z | -1 | 2 | -| 2023-01-01T00:05:00Z | -1 | 1 | - -{{% /expand %}} - -{{% expand "Apply `ROUND()` to time windows (grouped by time)" %}} - -```sql -SELECT - ROUND(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | round | -| :------------------- | ----: | -| 2023-01-01T00:00:00Z | -4 | -| 2023-01-01T00:10:00Z | 1 | -| 2023-01-01T00:20:00Z | 0 | -| 2023-01-01T00:30:00Z | 0 | -| 2023-01-01T00:40:00Z | 0 | -| 2023-01-01T00:50:00Z | 2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SIN() - -Returns the sine of a field value. - -```sql -SIN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `SIN()` to a field" %}} - -```sql -SELECT - b, - SIN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | sin | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.1629136686003898 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13660588515594851 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.4643877941052164 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0729085450859347 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.9784914502058565 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.6751348197618099 | - -{{% /expand %}} - -{{% expand "Apply `SIN()` to each field" %}} - -```sql -SELECT SIN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sin_a | sin_b | -| :------------------- | ------------------: | ------------------: | -| 2023-01-01T00:00:00Z | 0.3326300722640741 | -0.1629136686003898 | -| 2023-01-01T00:01:00Z | -0.6997047077914582 | 0.13660588515594851 | -| 2023-01-01T00:02:00Z | -0.7962295291135749 | -0.4643877941052164 | -| 2023-01-01T00:03:00Z | -0.673406844448706 | -0.0729085450859347 | -| 2023-01-01T00:04:00Z | -0.7870301289278495 | 0.9784914502058565 | -| 2023-01-01T00:05:00Z | -0.7778043295686337 | 0.6751348197618099 | - -{{% /expand %}} - -{{% expand "Apply `SIN()` to time windows (grouped by time)" %}} - -```sql -SELECT - SIN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sin | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | 0.933528830283535 | -| 2023-01-01T00:10:00Z | 0.9597472276784815 | -| 2023-01-01T00:20:00Z | 0.29712628761434723 | -| 2023-01-01T00:30:00Z | 0.2887011711003489 | -| 2023-01-01T00:40:00Z | 0.21934537994884437 | -| 2023-01-01T00:50:00Z | 0.9998424824522808 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## SQRT() - -Returns the square root of a field value. -Field values must be greater than or equal to 0. -Negative field values return null. - -```sql -SQRT(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `SQRT()` to a field" %}} - -```sql -SELECT - b, - SQRT(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | sqrt | -| :------------------- | ------------------: | -----------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.370181528515334 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | | -| 2023-01-01T00:04:00Z | 1.77857552719844 | 1.3336324558132349 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.860899207349059 | - -{{% /expand %}} - -{{% expand "Apply `SQRT()` to each field" %}} - -```sql -SELECT SQRT(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sqrt_a | sqrt_b | -| :------------------- | -----------------: | -----------------: | -| 2023-01-01T00:00:00Z | 0.5823152811928947 | | -| 2023-01-01T00:01:00Z | | 0.370181528515334 | -| 2023-01-01T00:02:00Z | | | -| 2023-01-01T00:03:00Z | | | -| 2023-01-01T00:04:00Z | | 1.3336324558132349 | -| 2023-01-01T00:05:00Z | | 0.860899207349059 | - -{{% /expand %}} - -{{% expand "Apply `SQRT()` to time windows (grouped by time)" %}} - -```sql -SELECT - SQRT(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | sqrt | -| :------------------- | -----------------: | -| 2023-01-01T00:00:00Z | | -| 2023-01-01T00:10:00Z | 1.134063865909604 | -| 2023-01-01T00:20:00Z | 0.5492555015405052 | -| 2023-01-01T00:30:00Z | 0.5411746169982342 | -| 2023-01-01T00:40:00Z | 0.4702589287652642 | -| 2023-01-01T00:50:00Z | 1.2462130097934059 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## TAN() - -Returns the tangent of the field value. - -```sql -TAN(field_expression) -``` - -#### Arguments - -- **field_expression**: Expression to identify one or more fields to operate on. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, or wildcard (`*`). - Supports numeric field types. - -#### Notable behaviors - -- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). - -#### Examples - -The following examples use the -[Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data). - -{{< expand-wrapper >}} -{{% expand "Apply `TAN()` to a field" %}} - -```sql -SELECT - b, - TAN(b) -FROM numbers -LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | b | tan | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.16511961248511045 | -| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13789861917955581 | -| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.5243575352718546 | -| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.07310309943905952 | -| 2023-01-01T00:04:00Z | 1.77857552719844 | -4.743341375725582 | -| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.9151958486043346 | - -{{% /expand %}} - -{{% expand "Apply `TAN()` to each field" %}} - -```sql -SELECT TAN(*) FROM numbers LIMIT 6 -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | tan_a | tan_b | -| :------------------- | ------------------: | -------------------: | -| 2023-01-01T00:00:00Z | 0.3527145610408791 | -0.16511961248511045 | -| 2023-01-01T00:01:00Z | -0.9793857830953787 | 0.13789861917955581 | -| 2023-01-01T00:02:00Z | -1.3160934857179802 | -0.5243575352718546 | -| 2023-01-01T00:03:00Z | -0.9109052733075013 | -0.07310309943905952 | -| 2023-01-01T00:04:00Z | -1.2757522322802637 | -4.743341375725582 | -| 2023-01-01T00:05:00Z | -1.2375438046768912 | 0.9151958486043346 | - -{{% /expand %}} - -{{% expand "Apply `TAN()` to time windows (grouped by time)" %}} - -```sql -SELECT - TAN(SUM(a)) -FROM numbers -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-01-01T01:00:00Z' -GROUP BY time(10m) -``` - -{{% influxql/table-meta %}} -name: numbers -{{% /influxql/table-meta %}} - -| time | tan | -| :------------------- | ------------------: | -| 2023-01-01T00:00:00Z | -2.603968631156288 | -| 2023-01-01T00:10:00Z | 3.4171098358131733 | -| 2023-01-01T00:20:00Z | 0.31117972731464494 | -| 2023-01-01T00:30:00Z | 0.30154101138968664 | -| 2023-01-01T00:40:00Z | 0.22482036866737865 | -| 2023-01-01T00:50:00Z | 56.3338223288096 | - -{{% /expand %}} -{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/influxql/group-by.md b/content/influxdb/clustered/reference/influxql/group-by.md index 757a9b762..2cb0b0e6a 100644 --- a/content/influxdb/clustered/reference/influxql/group-by.md +++ b/content/influxdb/clustered/reference/influxql/group-by.md @@ -13,632 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_expression_n] ``` + +source: /shared/influxql-v3-reference/group-by.md --- - -Use the `GROUP BY` clause to group data by one or more specified -[tags](/influxdb/clustered/reference/glossary/#tag) or into specified time intervals. -`GROUP BY` requires an [aggregate](/influxdb/clustered/reference/influxql/functions/aggregates/) -or [selector](/influxdb/clustered/reference/influxql/functions/selectors/) -function in the `SELECT` statement. - - - -- [Syntax](#syntax) -- [GROUP BY clause behaviors](#group-by-clause-behaviors) -- [GROUP BY tags](#group-by-tags) - - [GROUP BY tags examples](#group-by-tags-examples) -- [GROUP BY time](#group-by-time) - - [GROUP by time and fill gaps](#group-by-time-and-fill-gaps) - - [GROUP BY time examples](#group-by-time-examples) - - [GROUP BY time with offset](#group-by-time-with-offset) - - [GROUP BY time and fill gaps](#group-by-time-and-fill-gaps) -- [Result set](#result-set) - - [Default time range](#default-time-range) -- [Notable behaviors of the GROUP BY clause](#notable-behaviors-of-the-group-by-clause) - - [Cannot group by fields](#cannot-group-by-fields) - - [Tag order does not matter](#tag-order-does-not-matter) - - [Grouping by tag and no time range returns unexpected timestamps](#grouping-by-tag-and-no-time-range-returns-unexpected-timestamps) - - [Data grouped by time may return unexpected timestamps](#data-grouped-by-time-may-return-unexpected-timestamps) - - [Example data](#example-data) - - [Query results](#query-results) - - [Fill with no data in the queried time range](#fill-with-no-data-in-the-queried-time-range) - - [Fill with previous if no previous value exists](#fill-with-previous-if-no-previous-value-exists) - - [Fill with linear interpolation if there are not two values to interpolate between](#fill-with-linear-interpolation-if-there-are-not-two-values-to-interpolate-between) - - - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_expression_n] -``` - -- **group_expression**: Expression to identify tags or time intervals to group by. - Can be a [tag key](/influxdb/clustered/reference/glossary/#tag-key), - constant, [regular expression](/influxdb/clustered/reference/influxql/regular-expressions/), - wildcard (`*`), or [function expression](/influxdb/clustered/reference/influxql/functions/). - -## GROUP BY clause behaviors - -- `GROUP BY tag_key` - Groups data by a specific tag -- `GROUP BY tag_key1, tag_key2` - Groups data by more than one tag -- `GROUP BY *` - Groups data by all [tags](/influxdb/clustered/reference/glossary/#tag) -- `GROUP BY /regex/` - Groups data by tag keys that match the regular expression -- `GROUP BY time()` - Groups data into time intervals (windows) - -{{% note %}} -If a query includes `WHERE` and `GROUP BY`, the `GROUP BY` clause must appear after -the `WHERE` clause. -{{% /note %}} - -## GROUP BY tags - -Groups data by one or more tag columns. - -### GROUP BY tags examples - -The following examples use the -[Bitcoin price sample data](/influxdb/clustered/reference/sample-data/#bitcoin-price-data). - -{{< expand-wrapper >}} - -{{% expand "Group data by a single tag" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY code -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by more than one tag" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY code, description -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, description=Euro -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, description=British Pound Sterling -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, description=United States Dollar -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by all tags" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY * -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, crypto=bitcoin, description=Euro, symbol=€ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, crypto=bitcoin, description=British Pound Sterling, symbol=£ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, crypto=bitcoin, description=United States Dollar, symbol=$ -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{% expand "Group data by tag keys that match a regular expression" %}} - -```sql -SELECT MEAN(*) FROM bitcoin GROUP BY /^[cd]/ -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR, crypto=bitcoin, description=Euro -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 27328.848667840004 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP, crypto=bitcoin, description=British Pound Sterling -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 23441.832453919982 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD, crypto=bitcoin, description=United States Dollar -{{% /influxql/table-meta %}} - -| time | mean_price | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 28054.160950480004 | - -{{% /expand %}} - -{{< /expand-wrapper >}} - -## GROUP BY time - -`GROUP BY time()` groups data by into specified time intervals, also known as "windows", -and applies the [aggregate](/influxdb/clustered/reference/influxql/functions/aggregates/) -and [selector](/influxdb/clustered/reference/influxql/functions/selectors/) -functions in the `SELECT` clause to each interval. -Use the [`time()` function](/influxdb/clustered/reference/influxql/functions/date-time/#time) -to specify the time interval to group by. - -```sql -SELECT_clause FROM_clause WHERE GROUP BY time(time_interval[, offset])[, group_expression (...)] [fill(behavior)] -``` - -`GROUP BY time()` intervals use preset round-number time boundaries that -are independent of time conditions in the [`WHERE` clause](/influxdb/clustered/reference/influxql/where/). -**Output data uses window start boundaries as the aggregate timestamps.** -Use the `offset` argument of the `time()` function to shift time boundaries forward or -backward in time. - -### GROUP by time and fill gaps - -When grouping by time, if a window in the queried time range does not contain data, -results return a row for the empty window containing the timestamp of the empty -window and _null_ values for each queried field. -Use the [`fill()` function](/influxdb/clustered/reference/influxql/functions/misc/#fill) -_at the end of the `GROUP BY` clause_ to replace _null_ field values. -If no `FILL` clause is included, the default behavior is `fill(null)`. - -`fill()` provides the following behaviors for filling values: - -- **numeric literal**: Replaces null values with the specified numeric literal. -- **linear**: Uses linear interpolation between existing values to replace null values. -- **none**: Removes rows with null field values. -- **null**: Keeps null values and associated timestamps. -- **previous**: Replaces null values with the most recent non-null value. - -_See the [`fill()` documentation](/influxdb/clustered/reference/influxql/functions/misc/#fill) -for detailed examples._ - -### GROUP BY time examples - -The following examples use the -[Bitcoin price sample data](/influxdb/clustered/reference/sample-data/#bitcoin-price-data). - -{{< expand-wrapper >}} - -{{% expand "Group and aggregate query results into 1 hour windows" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(1h) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-05-01T00:00:00Z | 24494.27265 | -| 2023-05-01T01:00:00Z | 24452.1698 | -| 2023-05-01T02:00:00Z | 23902.666124999996 | -| 2023-05-01T03:00:00Z | 23875.211349999998 | -| 2023-05-01T04:00:00Z | 23855.6441 | -| ... | ... | - - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 1 week intervals by tag" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-15T00:00:00Z' -GROUP BY time(1w), code -``` - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=EUR -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 27681.21808576779 | -| 2023-05-04T00:00:00Z | 27829.413580354256 | -| 2023-05-11T00:00:00Z | 26210.24799033149 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=GBP -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 23744.083925842704 | -| 2023-05-04T00:00:00Z | 23871.201395652173 | -| 2023-05-11T00:00:00Z | 22482.33174723755 | - -{{% influxql/table-meta %}} -name: bitcoin -tags: code=USD -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-27T00:00:00Z | 28415.88231123595 | -| 2023-05-04T00:00:00Z | 28568.010941384844 | -| 2023-05-11T00:00:00Z | 26905.87242099449 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -###### GROUP BY time with offset - -{{< expand-wrapper >}} -{{% expand "Group and aggregate query results into 1 hour intervals and offset time boundaries by +15 minutes" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-02T00:00:00Z' -GROUP BY time(1h, 15m) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-30T23:15:00Z | | -| 2023-05-01T00:15:00Z | 29313.6754 | -| 2023-05-01T01:15:00Z | 28932.0882 | -| 2023-05-01T02:15:00Z | 28596.375225000003 | -| 2023-05-01T03:15:00Z | 28578.915075 | -| ... | ... | - -_Note that `offset` forces the first time boundary to be outside -the queried time range so the query returns no results for that first interval._ - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 1 hour intervals and offset time boundaries by -15 minutes" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-02T00:00:00Z' -GROUP BY time(1h, -15m) -``` -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 2023-04-30T23:45:00Z | 29319.9092 | -| 2023-05-01T00:45:00Z | 29285.3651 | -| 2023-05-01T01:45:00Z | 28607.202666666668 | -| 2023-05-01T02:45:00Z | 28576.056175 | -| 2023-05-01T03:45:00Z | 28566.96315 | -| ... | ... | - -{{% /expand %}} -{{< /expand-wrapper >}} - -###### GROUP BY time and fill gaps - -{{< expand-wrapper >}} -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps with `0`" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(0) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 0 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps using linear interpolation" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(linear) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29285.3651 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps with previous values" %}} - -```sql -SELECT - MEAN(price) -FROM bitcoin -WHERE - code = 'USD' - AND time >= '2023-05-01T00:00:00Z' - AND time < '2023-05-01T02:00:00Z' -GROUP BY - time(30m) - fill(previous) -``` - -{{% influxql/table-meta %}} -name: bitcoin -{{% /influxql/table-meta %}} - -| time | mean | -| -------------------- | ---------- | -| 2023-05-01T00:00:00Z | 29319.9092 | -| 2023-05-01T00:30:00Z | 29307.4416 | -| 2023-05-01T01:00:00Z | 29307.4416 | -| 2023-05-01T01:30:00Z | 29263.2886 | - -{{% /expand %}} - -{{< /expand-wrapper >}} - -## Result set - -If at least one row satisfies the query, {{% product-name %}} returns row data in the query result set. -If a query uses a `GROUP BY` clause, the result set includes the following: - -- Columns listed in the query's `SELECT` clause -- A `time` column that contains the timestamp for the record or the group -- An `iox::measurement` column that contains the record's measurement (table) name -- Columns listed in the query's `GROUP BY` clause; each row in the result set contains the values used for grouping - -### Default time range - -If a query doesn't specify a time range in the -[`WHERE` clause](/influxdb/clustered/reference/influxql/where/), InfluxDB uses the -[default time range](/influxdb/clustered/reference/influxql/#default-time-range) for filtering and grouping by time. -If a query includes the `GROUP BY` clause and doesn't specify a time range in the -`WHERE` clause, the default time group is the -[default time range](/influxdb/clustered/reference/influxql/#default-time-range), and the `time` column in the result set contains the start of the range--for example: - -```sql -SELECT mean(temp) FROM home GROUP BY room -``` - -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -----------------: | -| 1970-01-01T00:00:00Z | 22.623076923076926 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | ----------------: | -| 1970-01-01T00:00:00Z | 22.16923076923077 | - -## Notable behaviors of the GROUP BY clause - -### Cannot group by fields - -InfluxQL does not support grouping data by **fields**. - -### Tag order does not matter - -The order that tags are listed in the `GROUP BY` clause does not affect how -data is grouped. - -### Grouping by tag and no time range returns unexpected timestamps - -The `time` column contains the start of the [default time range](#default-time-range). - -### Data grouped by time may return unexpected timestamps - -Because `GROUP BY time()` intervals use preset round-number time boundaries that -are independent of time conditions in the [`WHERE` clause](/influxdb/clustered/reference/influxql/where/), -results may include timestamps outside of the queried time range. -Results represent only data with timestamps in the specified time range, but -output timestamps are determined by by the preset time boundaries. - -The following example groups data by 1-hour intervals, but the time range defined -in the `WHERE` clause covers only part of a window: - -```sql -SELECT MEAN(field) -FROM example -WHERE - time >= '2022-01-01T00:30:00Z' - AND time <= '2022-01-01T01:30:00Z' -GROUP BY time(1h) -``` - -{{% note %}} -**Note**: The timestamp in the first row of query results data occurs before the start of -the queried time range. -[See why](#why-do-these-results-include-timestamps-outside-of-the-queried-time-range). -{{% /note %}} - -{{% influxdb/custom-timestamps %}} -{{< flex >}} -{{% flex-content %}} -#### Example data - -| time | field | -| :------------------- | ----: | -| 2022-01-01T00:00:00Z | 8 | -| 2022-01-01T00:15:00Z | 4 | -| 2022-01-01T00:30:00Z | 0 | -| 2022-01-01T00:45:00Z | 8 | -| 2022-01-01T01:00:00Z | 5 | -| 2022-01-01T01:15:00Z | 0 | -| 2022-01-01T01:30:00Z | 8 | -| 2022-01-01T01:45:00Z | 8 | -| 2022-01-01T02:00:00Z | 9 | -| 2022-01-01T02:15:00Z | 6 | -| 2022-01-01T02:30:00Z | 3 | -| 2022-01-01T02:45:00Z | 0 | - -{{% /flex-content %}} -{{% flex-content %}} - -#### Query results - -| time | field | -| :------------------- | ----: | -| 2022-01-01T00:00:00Z | 4 | -| 2022-01-01T01:00:00Z | 5.25 | -| 2022-01-01T02:00:00Z | 6 | - -{{% /flex-content %}} -{{< /flex >}} -{{% /influxdb/custom-timestamps %}} - -{{< expand-wrapper >}} -{{% expand "Why do these results include timestamps outside of the queried time range?" %}} - -`GROUP BY time()` creates windows with predefined time boundaries based on the -specified interval. These boundaries are not determined by the queried time -range, however, aggregate values in query results are calculated using only -values that are in the queried time range. - -{{< html-diagram/influxql-windows >}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Fill with no data in the queried time range - -Queries ignore `fill()` if no data exists in the queried time range. -This is the expected behavior. - -### Fill with previous if no previous value exists - -`fill(previous)` doesn’t fill null values if there is no previous value in -the queried time range. - -### Fill with linear interpolation if there are not two values to interpolate between - -`fill(linear)` doesn't fill null values if there are no values before or after -the null value in the queried time range. diff --git a/content/influxdb/clustered/reference/influxql/internals.md b/content/influxdb/clustered/reference/influxql/internals.md index 115655c9e..5eb6116de 100644 --- a/content/influxdb/clustered/reference/influxql/internals.md +++ b/content/influxdb/clustered/reference/influxql/internals.md @@ -6,159 +6,6 @@ menu: name: InfluxQL internals parent: influxql-reference weight: 219 + +source: /shared/influxql-v3-reference/internals.md --- - -Learn about the implementation of InfluxQL to understand how -results are processed and how to create efficient queries: - -- [Query life cycle](#query-life-cycle) -- [Understanding iterators](#understanding-iterators) -- [Cursors](#cursors) -- [Auxiliary fields](#auxiliary-fields) -- [Built-in iterators](#built-in-iterators) -- [Call iterators](#call-iterators) - -## Query life cycle - -1. InfluxQL query string is tokenized and then parsed into an abstract syntax - tree (AST). This is the code representation of the query itself. - -2. The AST is passed to the `QueryExecutor` which directs queries to the - appropriate handlers. For example, queries related to meta data are executed - by the **meta service** and `SELECT` statements are executed by the shards - themselves. - -3. The query engine then determines the shards that match the `SELECT` - statement's time range. From these shards, iterators are created for each - field in the statement. - -4. Iterators are passed to the emitter which drains them and joins the resulting - points. The emitter's job is to convert simple time/value points into the - more complex result objects that are returned to the client. - -### Understanding iterators - -Iterators provide a simple interface for looping over a set of points. -For example, this is an iterator over Float points: - -``` -type FloatIterator interface { - Next() *FloatPoint -} -``` - -These iterators are created through the `IteratorCreator` interface: - -``` -type IteratorCreator interface { - CreateIterator(opt *IteratorOptions) (Iterator, error) -} -``` - -The `IteratorOptions` provide arguments about field selection, time ranges, -and dimensions that the iterator creator can use when planning an iterator. -The `IteratorCreator` interface is used at many levels such as the `Shards`, -`Shard`, and `Engine`. This allows optimizations to be performed when applicable -such as returning a precomputed `COUNT()`. - -Iterators aren't just for reading raw data from storage, though. Iterators can be -composed so that they provide additional functionality around an input -iterator. For example, a `DistinctIterator` can compute the distinct values for -each time window for an input iterator. Or a `FillIterator` can generate -additional points that are missing from an input iterator. - -This composition also lends itself well to aggregation. -For example, in the following SQL, `MEAN(value)` is a `MeanIterator` that wraps an iterator from the -underlying shards: - -```sql -SELECT MEAN(value) FROM cpu GROUP BY time(10m) -``` - -The following example wraps `MEAN(value)` with an additional iterator (`DERIVATIVE()`) to determine -the derivative of the mean: - -```sql -SELECT DERIVATIVE(MEAN(value), 20m) FROM cpu GROUP BY time(10m) -``` - -### Cursors - -A **cursor** identifies data by shard in tuples (time, value) for a single series (measurement, tag set and field). The cursor traverses data stored as a log-structured merge-tree and handles deduplication across levels, tombstones for deleted data, and merging the cache (Write Ahead Log). A cursor sorts the `(time, value)` tuples by time in ascending or descending order. - -For example, a query that evaluates one field for 1,000 series over 3 shards constructs a minimum of 3,000 cursors (1,000 per shard). - -### Auxiliary fields - -Because InfluxQL allows users to use selector functions such as `FIRST()`, -`LAST()`, `MIN()`, and `MAX()`, the engine must provide a way to return related -data at the same time with the selected point. - -Let's look at the following query: - -```sql -SELECT FIRST(value), host FROM cpu GROUP BY time(1h) -``` - -We are selecting the first `value` that occurs every hour but we also want to -retrieve the `host` associated with that point. Since the `Point` types only -specify a single typed `Value` for efficiency, we push the `host` into the -auxiliary fields of the point. These auxiliary fields are attached to the point -until it is passed to the emitter where the fields get split off to their own -iterator. - -### Built-in iterators - -There are many helper iterators that let us build queries: - -* Merge Iterator - This iterator combines one or more iterators into a single - new iterator of the same type. This iterator guarantees that all points - within a window will be output before starting the next window, but does not - provide ordering guarantees within the window. This allows for fast access - for aggregate queries that don't need stronger sorting guarantees. - -* Sorted Merge Iterator - Like `MergeIterator`, this iterator combines one or more iterators - into a new iterator of the same type. However, this iterator guarantees - time ordering of every point. This makes it slower than the `MergeIterator` - but this ordering guarantee is required for non-aggregate queries which - return the raw data points. - -* Limit Iterator - This iterator limits the number of points per name or tag - group. This is the implementation of the `LIMIT` & `OFFSET` syntax. - -* Fill Iterator - This iterator injects extra points if they are missing from - the input iterator. It can provide `null` points, points with the previous - value, or points with a specific value. - -* Buffered Iterator - This iterator provides the ability to "unread" a point - back onto a buffer so it can be read again next time. This is used extensively - to provide lookahead for windowing. - -* Reduce Iterator - This iterator calls a reduction function for each point in - a window. When the window is complete, then all points for that window are - output. This is used for simple aggregate functions such as `COUNT()`. - -* Reduce Slice Iterator - This iterator collects all points for a window first, - and then passes them all to a reduction function at once. The results are - returned from the iterator. This is used for aggregate functions such as - `DERIVATIVE()`. - -* Transform Iterator - This iterator calls a transform function for each point - from an input iterator. This is used for executing binary expressions. - -* Dedupe Iterator - This iterator only outputs unique points. Because it is resource-intensive, this iterator is only used for small queries such as meta query statements. - -### Call iterators - -Function calls in InfluxQL are implemented at two levels: - -- Some calls can be -wrapped at multiple layers to improve efficiency. For example, a `COUNT()` can -be performed at the shard level and then multiple `CountIterator`s can be -wrapped with another `CountIterator` to compute the count of all shards. These -iterators can be created using `NewCallIterator()`. - -- Some iterators are more complex or need to be implemented at a higher level. -For example, the `DERIVATIVE()` function needs to retrieve all points for a window -before performing the calculation. This iterator is created by the engine itself -and is never requested to be created by the lower levels. diff --git a/content/influxdb/clustered/reference/influxql/limit-and-slimit.md b/content/influxdb/clustered/reference/influxql/limit-and-slimit.md index 87b6015d4..85217cf08 100644 --- a/content/influxdb/clustered/reference/influxql/limit-and-slimit.md +++ b/content/influxdb/clustered/reference/influxql/limit-and-slimit.md @@ -13,249 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT row_N SLIMIT series_N ``` + +source: /shared/influxql-v3-reference/limit-and-slimit.md --- - -Use `LIMIT` to limit the number of **rows** returned per InfluxQL group. -Use `SLIMIT` to limit the number of [series](/influxdb/clustered/reference/glossary/#series) -returned in query results. - -- [LIMIT clause](#limit-clause) - - [Syntax](#limit-syntax) - - [Examples](#limit-examples) -- [SLIMIT clause](#slimit-clause) - - - - - - -## LIMIT clause - -The `LIMIT` clause limits the number of rows to return from each InfluxQL group. -If the query doesn't include a [`GROUP BY` clause](/influxdb/clustered/reference/influxql/group-by/), -the entire result set is considered a single group. -If a query [groups data by time](/influxdb/clustered/reference/influxql/group-by/#group-by-time), -limits are applied after aggregate and selector operations are applied to each -time window. - -### Syntax {#limit-syntax} - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT N -``` - -#### Arguments - -- **N**: Maximum number of points to return from each InfluxQL group. - If `N` is greater than the number of points in a group, - all points from the group are returned. - -### Examples {#limit-examples} - -The following examples use the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Limit the number of rows returned" %}} - -```sql -SELECT * FROM home LIMIT 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Limit the number of rows returned from each InfluxQL group" %}} - -```sql -SELECT - MEAN(*) -FROM home -GROUP BY - time(2h), - room -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ------: | -------: | -----------------: | -| 2022-01-01T08:00:00Z | 0 | 36.05 | 22 | -| 2022-01-01T10:00:00Z | 0 | 36.05 | 22.549999999999997 | -| 2022-01-01T12:00:00Z | 0.5 | 36.25 | 22.65 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | mean_co | mean_hum | mean_temp | -| :------------------- | ------: | -------: | -----------------: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21.25 | -| 2022-01-01T10:00:00Z | 0 | 36 | 22 | -| 2022-01-01T12:00:00Z | 0 | 35.95 | 22.299999999999997 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## SLIMIT clause - -{{% warn %}} -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features, such as `SLIMIT` are still -being implemented. For more information, see -[InfluxQL feature support](/influxdb/clustered/reference/influxql/feature-support/). -{{% /warn %}} - - diff --git a/content/influxdb/clustered/reference/influxql/math-operators.md b/content/influxdb/clustered/reference/influxql/math-operators.md index bd26127d7..83f39088a 100644 --- a/content/influxdb/clustered/reference/influxql/math-operators.md +++ b/content/influxdb/clustered/reference/influxql/math-operators.md @@ -9,273 +9,6 @@ menu: parent: influxql-reference identifier: influxql-mathematical-operators weight: 215 + +source: /shared/influxql-v3-reference/math-operators.md --- - -Use InfluxQL mathematical operators to perform mathematical operations in InfluxQL queries. -Mathematical operators follow the [standard order of operations](https://golang.org/ref/spec#Operator_precedence). -Parentheses take precedence to division and multiplication, which takes precedence to addition and subtraction. -For example `5 / 2 + 3 * 2 = (5 / 2) + (3 * 2)` and `5 + 2 * 3 - 2 = 5 + (2 * 3) - 2`. - -- [Addition](#addition) -- [Subtraction](#subtraction) -- [Multiplication](#multiplication) -- [Division](#division) -- [Modulo](#modulo) -- [Bitwise AND](#bitwise-and) -- [Bitwise OR](#bitwise-or) -- [Bitwise Exclusive-OR](#bitwise-exclusive-or) -- [Unsupported Operators](#unsupported-operators) -- [Notable behaviors of mathematical operators](#notable-behaviors-of-mathematical-operators) - -## Addition - -Add two numeric operands. Operands may be an identifier, constant, or literal -numeric value. - -```sql -SELECT A + 5 FROM example - -SELECT A + B FROM example - -SELECT * FROM example WHERE A + 5 > 10 - -SELECT * FROM example WHERE A + B > 10 -``` - -## Subtraction - -Subtract one numeric operand from another. Operands may be an identifier, -constant, or literal numeric value. - -```sql -SELECT 1 - A FROM example - -SELECT B - A FROM example - -SELECT * FROM example WHERE 1 - A <= 3 - -SELECT * FROM example WHERE B - A <= 3 -``` - -## Multiplication - -Multiply two numeric operands. Operands may be an identifier, constant, or literal -numeric value. - -```sql -SELECT A * 10 FROM example - -SELECT A * B FROM example - -SELECT * FROM example WHERE A * 10 >= 20 - -SELECT * FROM example WHERE A * B >= 20 -``` - -Multiplication distributes across other operators. - -```sql -SELECT 10 * (A + B + C) FROM example - -SELECT 10 * (A - B - C) FROM example - -SELECT 10 * (A + B - C) FROM example -``` - -## Division - -Divide one numeric operand by another. Operands may be an identifier, constant, -or literal numeric value. - -```sql -SELECT A / 10 FROM example - -SELECT A / B FROM example - -SELECT * FROM example WHERE A / 10 <= 2 - -SELECT * FROM example WHERE A / B <= 2 -``` - -Division distributes across other operators. - -```sql -SELECT 10 / (A + B + C) FROM example - -SELECT 10 / (A - B - C) FROM example - -SELECT 10 / (A + B - C) FROM example -``` - -## Modulo - -Perform a modulo operation with two numeric operands. Operands may be an -identifier, constant, or literal numeric value. - -```sql -SELECT A % 2 FROM example - -SELECT A % B FROM example - -SELECT A FROM example WHERE A % 2 = 0 - -SELECT A, B FROM example WHERE A % B = 0 -``` - -## Bitwise AND - -Perform a bitwise `AND` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A & 255 FROM example - -SELECT A & B FROM example - -SELECT (A ^ true) & B FROM example - -SELECT * FROM example WHERE A & 15 > 0 -``` - -## Bitwise OR - -Perform a bitwise `OR` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A | 5 FROM example - -SELECT A | B FROM example - -SELECT * FROM example WHERE "bitfield" | 12 = 12 -``` - -## Bitwise Exclusive-OR - -Perform a bitwise `Exclusive-OR` operation on two operands _of the same type_. -Supported types are **integers** and **booleans**. -Operands may be an identifier, constant, literal integer value, or literal boolean value. - -```sql -SELECT A ^ 255 FROM example - -SELECT A ^ B FROM example - -SELECT * FROM example WHERE "bitfield" ^ 6 > 0 -``` - -## Unsupported Operators - -### Inequalities - -Using any of `=`,`!=`,`<`,`>`,`<=`,`>=`,`<>` in the `SELECT` statement yields -empty results for all types. -Comparison operators can only be used in the `WHERE` clause. - -### Logical Operators - -Using any of `!|`,`NAND`,`XOR`,`NOR` yield a parser error. - -Additionally using `AND`, `OR` in the `SELECT` clause of a query will not behave -as mathematical operators and simply yield empty results, as they are InfluxQL tokens. -However, you can apply the bitwise operators `&`, `|` and `^` to boolean values. - -### Bitwise Not - -There is no bitwise-not operator, because the results you expect depend on the width of your bitfield. -InfluxQL does not know how wide your bitfield is, so cannot implement a suitable -bitwise-not operator. - -For example, if your bitfield is 8 bits wide, then the integer 1 represents the bits `0000 0001`. -The bitwise-not of this should return the bits `1111 1110`, i.e. the integer 254. -However, if your bitfield is 16 bits wide, then the integer 1 represents the bits `0000 0000 0000 0001`. -The bitwise-not of this should return the bits `1111 1111 1111 1110`, i.e. the integer 65534. - -#### Solution - -You can implement a bitwise-not operation by using the `^` (bitwise xor) operator -together with the number representing all-ones for your word-width: - -For 8-bit data: - -```sql -SELECT A ^ 255 FROM example -``` - -For 16-bit data: - -```sql -SELECT A ^ 65535 FROM example -``` - -For 32-bit data: - -```sql -SELECT A ^ 4294967295 FROM example -``` - -In each case, the constant you need can be calculated as `(2 ** width) - 1`. - -## Notable behaviors of mathematical operators - -- [Mathematical operators with wildcards and regular expressions](#mathematical-operators-with-wildcards-and-regular-expressions) -- [Mathematical operators with functions](#mathematical-operators-with-functions) - -### Mathematical operators with wildcards and regular expressions - -InfluxQL does not support combining mathematical operations with a wildcard (`*`) -or [regular expression](/influxdb/clustered/reference/influxql/regular-expressions/) -in the `SELECT` clause. -The following queries are invalid and the output is an error: - -Perform a mathematical operation on a wildcard. - -```sql -SELECT * + 2 FROM "nope" --- ERR: unsupported expression with wildcard: * + 2 -``` - -Perform a mathematical operation on a wildcard within a function. - -```sql -SELECT COUNT(*) / 2 FROM "nope" --- ERR: unsupported expression with wildcard: count(*) / 2 -``` - -Perform a mathematical operation on a regular expression. - -```sql -SELECT /A/ + 2 FROM "nope" --- ERR: error parsing query: found +, expected FROM at line 1, char 12 -``` - -Perform a mathematical operation on a regular expression within a function. - -```sql -SELECT COUNT(/A/) + 2 FROM "nope" --- ERR: unsupported expression with regex field: count(/A/) + 2 -``` - -### Mathematical operators with functions - -InfluxQL does not support mathematical operators inside of function calls. -Note that InfluxQL only allows functions in the `SELECT` clause. - -For example, the following will work: - -```sql -SELECT 10 * mean("value") FROM "cpu" -``` - -However, the following query will return a parse error: - -```sql -SELECT mean(10 * "value") FROM "cpu" --- Error: expected field argument in mean() -``` - - diff --git a/content/influxdb/clustered/reference/influxql/offset-and-soffset.md b/content/influxdb/clustered/reference/influxql/offset-and-soffset.md index 579f40357..afd1f989f 100644 --- a/content/influxdb/clustered/reference/influxql/offset-and-soffset.md +++ b/content/influxdb/clustered/reference/influxql/offset-and-soffset.md @@ -14,236 +14,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] OFFSET row_N [SLIMIT_clause] SOFFSET series_N ``` + +source: /shared/influxql-v3-reference/offset-and-soffset.md --- - -Use `OFFSET` to specify the number of [rows](/influxdb/clustered/reference/glossary/#series) -to skip in each InfluxQL group before returning results. -Use `SOFFSET` to specify the number of [series](/influxdb/clustered/reference/glossary/#series) -to skip before returning results. - - - [OFFSET clause](#offset-clause) - - [Syntax](#offset-syntax) - - [Notable OFFSET clause behaviors](#notable-offset-clause-behaviors) - - [Examples](#offset-examples) - - [SOFFSET clause](#soffset-clause) - - - - -## `OFFSET` clause - -The `OFFSET` clause skips `N` rows in each InfluxQL group before returning results. -Offsets honor row limits specified in the -[`LIMIT` clause](/influxdb/clustered/reference/influxql/limit-and-slimit/#limit-clause) -and display the limited number of rows after the specified offset. -Use `LIMIT` and `OFFSET` together to paginate query results. - -### Syntax {#offset-syntax} - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] OFFSET N [SLIMIT_clause] [SOFFSET_clause] -``` - -#### Arguments - -- **N**: Number of rows to skip in each InfluxQL group before returning results. - -### Notable OFFSET clause behaviors - -- If there is no `LIMIT` clause in a query with an `OFFSET` clause, the query - returns a single row per InfluxQL group at the specified offset. -- If the query doesn't include a [`GROUP BY` clause](/influxdb/clustered/reference/influxql/group-by/), - the entire result set is considered a single group and is returned in full. -- If a query [groups data by time](/influxdb/clustered/reference/influxql/group-by/#group-by-time), - the offset is applied after aggregate and selector operations are applied to each - time window. -- If the [`WHERE` clause](/influxdb/clustered/reference/influxql/where/) - includes a time range and the `OFFSET` clause causes InfluxQL to return points - with timestamps outside of that time range, InfluxQL returns no results. - -### Examples {#offset-examples} - -The following examples use the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Return the nth row" %}} - -```sql -SELECT * FROM home OFFSET 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Paginate results by 3 and return the 2nd page of results" %}} - -```sql -SELECT * FROM home WHERE room = 'Kitchen' LIMIT 3 OFFSET 3 -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Paginate results from each series by 3 and return the 2nd page of each series" %}} - -```sql -SELECT * FROM home GROUP BY * LIMIT 3 OFFSET 3 -``` - -{{% influxdb/custom-timestamps %}} - -{{% influxql/table-meta %}} -name: home -tags: room=Kitchen -{{% /influxql/table-meta %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | 22.5 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | 22.8 | - -{{% influxql/table-meta %}} -name: home -tags: room=Living Room -{{% /influxql/table-meta %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T11:00:00Z | 0 | 36 | 22.2 | -| 2022-01-01T12:00:00Z | 0 | 35.9 | 22.2 | -| 2022-01-01T13:00:00Z | 0 | 36 | 22.4 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## `SOFFSET` clause - -{{% warn %}} -InfluxQL is being rearchitected to work with the InfluxDB 3.0 storage engine. -This process is ongoing and some InfluxQL features, such as `SOFFSET` are still -being implemented. For more information, see -[InfluxQL feature support](/influxdb/clustered/reference/influxql/feature-support/). -{{% /warn %}} - - diff --git a/content/influxdb/clustered/reference/influxql/order-by.md b/content/influxdb/clustered/reference/influxql/order-by.md index 362e25e4e..6cab40d8f 100644 --- a/content/influxdb/clustered/reference/influxql/order-by.md +++ b/content/influxdb/clustered/reference/influxql/order-by.md @@ -13,97 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [DESC|ASC] ``` + +source: /shared/influxql-v3-reference/order-by.md --- - -Use the `ORDER BY` clause to sort data by time in ascending or descending order. -InfluxQL only supports sorting data by `time`. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [ASC|DESC] -``` - -- If the the `ORDER BY` clause is not included, the default behavior is to sort data by - time in **ascending** order: `ORDER BY time ASC`. -- If the query includes [`WHERE`](/influxdb/clustered/reference/influxql/where/) - and [`GROUP BY`](/influxdb/clustered/reference/influxql/group-by/) clauses, - the `ORDER BY` clause must come **after** these clauses. - -#### Sort orders - -- **ASC (ascending)**: The first row in the results has the oldest timestamp. - The last row in the results has the most recent timestamp. -- **DESC (descending)**: The first row in the results has the most recent timestamp. - The last row in the results has the oldest timestamp. - -## Examples - -The following examples use the -[Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Sort data with the oldest points first" %}} - -{{% note %}} -Ordering data by time in ascending order is the default behavior. -Including `ORDER BY time ASC` in the query isn't necessary, but it is supported. -{{% /note %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -ORDER BY time ASC -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Sort data with the newest points first" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -ORDER BY time DESC -``` - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/influxql/quoting.md b/content/influxdb/clustered/reference/influxql/quoting.md index 826c4ced6..e4faff8d2 100644 --- a/content/influxdb/clustered/reference/influxql/quoting.md +++ b/content/influxdb/clustered/reference/influxql/quoting.md @@ -17,48 +17,6 @@ list_code_example: | -- Quoted identifier "this-is-an-identifier" ``` + +source: /shared/influxql-v3-reference/quoting.md --- - -InfluxQL supports both single and double quotation marks, but they each function -differently and serve different purposes. - -- [Single quotes](#single-quotes) -- [Double quotes](#double-quotes) - -## Single quotes - -Use single quotation marks (`'`) in the -[string literal](/influxdb/clustered/reference/influxql/#strings) and -[timestamp literal](/influxdb/clustered/reference/influxql/#dates--times) syntax. - -In the following example, the `WHERE` clause evaluates the value of the `room` tag. -Tags only contain string values, so the right operand of the predicate expression -should be a string literal. - -```sql -... WHERE room = 'Kitchen' -``` - -## Double quotes - -Use double quotation marks (`"`) to quote [identifiers](/influxdb/clustered/reference/influxql/#identifiers). -Identifiers **must** be double-quoted in the following cases: - -- The identifier contains non-word characters. - Word characters are defined as `[a-z,A-Z,0-9,_]`. -- The identifier is case-sensitive. -- The identifier contains [InfluxQL keywords](/influxdb/clustered/reference/influxql/#keywords). -- The identifier begins with a digit. - -Double-quoted identifiers can also: - -- Contain any Unicode character except for a new line. -- Contain escaped `"` characters (for example: `\"`). -- Include [InfluxQL keywords](/influxdb/clustered/reference/influxql/#keywords). - -**While not always necessary, we recommend that you double quote identifiers.** - -{{% note %}} -InfluxQL quoting guidelines differ from -[line protocol quoting guidelines](/influxdb/clustered/reference/syntax/line-protocol/#quotes). -{{% /note %}} \ No newline at end of file diff --git a/content/influxdb/clustered/reference/influxql/regular-expressions.md b/content/influxdb/clustered/reference/influxql/regular-expressions.md index c0366212b..02ac8f621 100644 --- a/content/influxdb/clustered/reference/influxql/regular-expressions.md +++ b/content/influxdb/clustered/reference/influxql/regular-expressions.md @@ -13,198 +13,6 @@ list_code_example: | ```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` + +source: /shared/influxql-v3-reference/regular-expressions.md --- - -Regular expressions are a sequence of characters used to identify patterns in -identifiers and string values. -InfluxQL supports regular expressions in the following operations: - -- Identifying **fields** and **tags** to query in the - [`SELECT` clause](/influxdb/clustered/reference/influxql/select/). -- Identifying **measurements** to query in the - [`FROM` clause](/influxdb/clustered/reference/influxql/select/#from-clause). -- Testing **tag values** and **string field values** in the - [`WHERE` clause](/influxdb/clustered/reference/influxql/where/). -- Identifying **tag keys** to group by in the - [`GROUP BY` clause](/influxdb/clustered/reference/influxql/group-by/) - -{{% note %}} -#### Query performance - -Regular expression comparisons are more computationally intensive than exact -string comparisons. Queries with regular expressions are not as performant -as those without. -{{% /note %}} - -## Regular expression syntax - -InfluxQL Regular expressions are surrounded by `/` characters and use the -[Go regular expression syntax](http://golang.org/pkg/regexp/syntax/). - -```sql -/regular_expression/ -``` - -### Regular expression flags - -Regular expression flags modify the pattern-matching behavior of the expression. -InfluxQL supports the following regular expression flags: - -| Flag | Description | -| :--- | :------------------------------------------------------------------------------ | -| i | case-insensitive | -| m | multi-line mode: `^` and `$` match begin/end line in addition to begin/end text | -| s | let `.` match `\n` | -| U | ungreedy: swap meaning of `x*` and `x*?`, `x+` and `x+?`, etc. | - -Include regular expression flags at the beginning of your regular expression -pattern enclosed in parentheses (`()`) and preceded by a question mark (`?`). - -```sql -/(?iU)foo*/ -``` - -## Regular expression operators - -InfluxQL provides the following regular expression operators that test if a -string operand matches a regular expression: - -- `=~`: Returns true if the string matches the regular expression -- `!~`: Returns true if the string does not match the regular expression - -InfluxQL regular expression operators are used to test string column values in -the [`WHERE` clause](/influxdb/clustered/reference/influxql/where/). - -## Regular expression examples - -The examples below use the following sample data sets: - -- [NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data) -- [Get started home sensor data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data) - -{{< expand-wrapper >}} - -{{% expand "Use a regular expression to specify field keys and tag keys in the SELECT clause" %}} - -```sql -SELECT /^t/ FROM weather -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | temp_avg | temp_max | temp_min | -| :------------------- | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | 52 | 66 | 44 | -| 2020-01-01T00:00:00Z | 53 | 59 | 47 | -| 2020-01-01T00:00:00Z | 50 | 57 | 44 | -| 2020-01-02T00:00:00Z | 54 | 61 | 49 | -| 2020-01-02T00:00:00Z | 51 | 60 | 44 | -| 2020-01-02T00:00:00Z | 53 | 66 | 42 | -| ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify measurements in the FROM clause" %}} - -```sql -SELECT /^t/ FROM /^[hw]/ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | temp | temp_avg | temp_max | temp_min | -| :------------------- | ---: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | | 52 | 66 | 44 | -| 2020-01-01T00:00:00Z | | 53 | 59 | 47 | -| 2020-01-01T00:00:00Z | | 50 | 57 | 44 | -| 2020-01-02T00:00:00Z | | 54 | 61 | 49 | -| 2020-01-02T00:00:00Z | | 51 | 60 | 44 | -| 2020-01-02T00:00:00Z | | 53 | 66 | 42 | -| ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify tag values in the WHERE clause" %}} - -```sql -SELECT * FROM weather WHERE location !~ /^[S]/ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | location | precip | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | :------- | -----: | -------: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | Concord | 0 | 52 | 66 | 44 | 3.13 | -| 2020-01-01T00:00:00Z | Hayward | 0 | 50 | 57 | 44 | 2.24 | -| 2020-01-02T00:00:00Z | Concord | 0 | 53 | 66 | 42 | 3.13 | -| 2020-01-02T00:00:00Z | Hayward | 0 | 51 | 60 | 44 | 3.8 | -| 2020-01-03T00:00:00Z | Concord | 0 | 49 | 60 | 38 | 2.68 | -| 2020-01-03T00:00:00Z | Hayward | 0 | 50 | 62 | 41 | 3.13 | -| ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify a tag with no value in the WHERE clause" %}} - -```sql -SELECT * FROM home, weather WHERE location !~ /./ -``` - -{{% influxql/table-meta %}} -name: weather -{{% /influxql/table-meta %}} - -| time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | --: | ---: | -------- | ------ | :---------- | ---: | -------- | -------- | -------- | -------- | -| 2022-01-01T08:00:00Z | 0 | 35.9 | | | Kitchen | 21 | | | | | -| 2022-01-01T08:00:00Z | 0 | 35.9 | | | Living Room | 21.1 | | | | | -| 2022-01-01T09:00:00Z | 0 | 36.2 | | | Kitchen | 23 | | | | | -| 2022-01-01T09:00:00Z | 0 | 35.9 | | | Living Room | 21.4 | | | | | -| 2022-01-01T10:00:00Z | 0 | 36.1 | | | Kitchen | 22.7 | | | | | -| 2022-01-01T10:00:00Z | 0 | 36 | | | Living Room | 21.8 | | | | | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Use a regular expression to specify tag keys in the GROUP BY clause" %}} - -```sql -SELECT MAX(precip) FROM weather GROUP BY /^l/ -``` - -{{% influxql/table-meta %}} -name: weather -tags: location=Concord -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2021-10-24T00:00:00Z | 4.53 | - -{{% influxql/table-meta %}} -name: weather -tags: location=Hayward -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2022-12-31T00:00:00Z | 4.34 | - -{{% influxql/table-meta %}} -name: weather -tags: location=San Francisco -{{% /influxql/table-meta %}} - -| time | max | -| :------------------- | ---: | -| 2021-10-24T00:00:00Z | 4.02 | - -{{% /expand %}} - -{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/influxql/select.md b/content/influxdb/clustered/reference/influxql/select.md index ba8ce3807..f772ac801 100644 --- a/content/influxdb/clustered/reference/influxql/select.md +++ b/content/influxdb/clustered/reference/influxql/select.md @@ -14,451 +14,6 @@ list_code_example: | ```sql SELECT [,,] FROM [,] ``` + +source: /shared/influxql-v3-reference/select.md --- - -Use the `SELECT` statement to query data from one or more -[measurements](/influxdb/clustered/reference/glossary/#measurement). -The `SELECT` statement **requires** a [`SELECT` clause](#select-clause) and a -[`FROM` clause](#from-clause). - -- [Syntax](#syntax) - - [SELECT clause](#select-clause) - - [FROM clause](#from-clause) -- [Notable SELECT statement behaviors](#notable-select-statement-behaviors) -- [Data types and casting operations](#data-types-and-casting-operations) -- [SELECT statement examples](#select-statement-examples) - - -## Syntax - -```sql -SELECT field_expression[, ..., field_expression_n[, tag_expression[, ..., tag_expression_n]]] FROM measurement_expression[, ..., measurement_expression_n] -``` - -### SELECT clause - -The `SELECT` clause supports several formats for identifying data to query. -It requires one or more **field expressions** and optional **tag expressions**. - -- **field_expression**: Expression to identify one or more fields to return in query results. - Can be a [field key](/influxdb/clustered/reference/glossary/#field-key), - constant, [regular expression](/influxdb/clustered/reference/influxql/regular-expressions/), - [wildcard (`*`)](#wildcard-expressions-in-select-clauses), or - [function expression](/influxdb/clustered/reference/influxql/functions/) and any - combination of arithmetic operators. -- **tag_expression**: Expression to identify one or more tags to return in query results. - Can be a [tag key](/influxdb/clustered/reference/glossary/#tag-key) or constant. - -#### Select clause behaviors - -- `SELECT field_key` - Returns a specific field. -- `SELECT field_key1, field_key2` - Returns two specific fields. -- `SELECT field_key, tag_key` - Returns a specific field and tag. -- `SELECT *` - Returns all [fields](/influxdb/clustered/reference/glossary/#field) - and [tags](/influxdb/clustered/reference/glossary/#tag). - _See [Wildcard expressions](#wildcard-expressions)._ -- `SELECT /^[t]/` - Returns all [fields](/influxdb/clustered/reference/glossary/#field) - and [tags](/influxdb/clustered/reference/glossary/#tag) with keys that - match the regular expression. At least one field key must match the regular - expression. If no field keys match the regular expression, no results are - returned. - -### FROM clause - -The `FROM` clause specifies the -[measurement](/influxdb/clustered/reference/glossary/#measurement) or -[subquery](/influxdb/clustered/reference/influxql/subqueries/) to query. -It requires one or more comma-delimited -[measurement expressions](#measurement_expression) or [subqueries](#subquery). - -#### measurement_expression - -A measurement expression identifies a measurement to query. -It can be a measurement name, fully-qualified measurement, constant, or -a [regular expression](/influxdb/clustered/reference/influxql/regular-expressions/). - -- **Measurement name**: When using just the measurement name, InfluxQL assumes - the default retention policy of the database specified in the query request. - - ```sql - FROM measurement - ``` - -- **Fully-qualified measurement**: A fully qualified measurement includes a - database name, retention policy name, and measurement name, each separated by - a period (`.`). If the retention policy is not specified, InfluxQL uses the - default retention policy for the specified database. - -```sql -FROM database.retention_policy.measurement - --- Fully-qualified measurement with default retention policy -FROM database..measurement -``` - -{{% note %}} -#### InfluxQL retention policies - -In {{< product-name >}}, **retention policies** are not part of the data model -like they are in InfluxDB 1.x. -Each {{< product-name >}} database has a **retention period** which defines the -maximum age of data to retain in the database. To use fully-qualified -measurements in InfluxQL queries, use the following naming convention when -[creating a database](/influxdb/clustered/admin/databases/create/): - -``` -database_name/retention_policy -``` -{{% /note %}} - -#### Subquery - -An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. -The outer query queries results returned by the inner query (subquery). - -For more information, see [InfluxQL subqueries](/influxdb/clustered/reference/influxql/subqueries/). - -## Notable SELECT statement behaviors - -- [Must query at least one field](#must-query-at-least-one-field) -- [Wildcard expressions](#wildcard-expressions) -- [Cannot include both aggregate and non-aggregate field expressions](#cannot-include-both-aggregate-and-non-aggregate-field-expressions) - -### Must query at least one field - -A query requires at least one [field key](/influxdb/clustered/reference/glossary/#field-key) -in the `SELECT` clause to return data. -If the `SELECT` clause includes only [tag keys](/influxdb/clustered/reference/glossary/#tag-key), -the query returns an empty result. -When using regular expressions in the `SELECT` clause, if regular expression -matches only tag keys and no field keys, the query returns an empty result. - -To return data associated with tag keys, include at least one field key in the -`SELECT` clause. - -### Wildcard expressions - -When using a wildcard expression (`*`) in the `SELECT` clause, the query returns -all tags and fields. -If a [function](/influxdb/clustered/reference/influxql/functions/) is -applied to a wildcard expression, the query returns all _fields_ with -the function applied, but does not return _tags_ unless they are included in -the `SELECT` clause. - -### Cannot include both aggregate and non-aggregate field expressions - -The `SELECT` statement cannot include an aggregate field expression -(one that uses an [aggregate](/influxdb/clustered/reference/influxql/functions/aggregates/) -or [selector](/influxdb/clustered/reference/influxql/functions/aggregates/) -function) **and** a non-aggregate field expression. -For example, in the following query, an aggregate function is applied to one -field, but not the other: - -```sql -SELECT mean(temp), hum FROM home -``` - -This query returns an error. -For more information, see [error about mixing aggregate and non-aggregate queries](/enterprise_influxdb/v1/troubleshooting/errors/#error-parsing-query-mixing-aggregate-and-non-aggregate-queries-is-not-supported). - -## Data types and casting operations - -The [`SELECT` clause](#select-clause) supports specifying a -[field's](/influxdb/clustered/reference/glossary/#field) type and basic -casting operations with the `::` syntax. - -```sql -SELECT field_expression::type FROM measurement_expression -``` - -The `::` syntax allows users to perform basic cast operations in queries. -Currently, InfluxQL supports casting _numeric_ [field values](/influxdb/clustered/reference/glossary/#field-value) -to other numeric types. -Casting to an **identifier type** acts as a filter on results and returns only -columns of that specific identifier type along with the `time` column. - -{{< flex >}} -{{% flex-content "third" %}} - -##### Numeric types - -- `float` -- `integer` -- `unsigned` - -{{% /flex-content %}} -{{% flex-content "third" %}} - -##### Non-numeric types - -- `string` -- `boolean` - -{{% /flex-content %}} -{{% flex-content "third" %}} - -##### Identifier types - -- `field` -- `tag` - -{{% /flex-content %}} -{{< /flex >}} - -{{% note %}} -InfluxQL returns no data if the query attempts to cast a numeric value to a -non-numeric type and vice versa. -{{% /note %}} - -When casting a float value to an integer or unsigned integer, the float value -is truncated at the decimal point. No rounding is performed. - -## SELECT statement examples - -The examples below use the following sample data sets: - -- [Get started home sensor data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data) -- [NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data) - -{{< expand-wrapper >}} -{{% expand "Select all fields and tags from a measurement" %}} - -```sql -SELECT * FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select specific tags and fields from a measurement" %}} - -```sql -SELECT temp, hum, room FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | temp | hum | room | -| :------------------- | ---: | ---: | :---------- | -| 2022-01-01T08:00:00Z | 21 | 35.9 | Kitchen | -| 2022-01-01T08:00:00Z | 21.1 | 35.9 | Living Room | -| 2022-01-01T09:00:00Z | 23 | 36.2 | Kitchen | -| 2022-01-01T09:00:00Z | 21.4 | 35.9 | Living Room | -| 2022-01-01T10:00:00Z | 22.7 | 36.1 | Kitchen | -| 2022-01-01T10:00:00Z | 21.8 | 36 | Living Room | -| ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select all fields from a measurement" %}} - -```sql -SELECT *::field FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | temp | -| :------------------- | --: | ---: | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | 21.8 | -| ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select a field from a measurement and perform basic arithmetic" %}} - -```sql -SELECT (temp * (9 / 5)) + 32 FROM home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | temp | -| :------------------- | ----------------: | -| 2022-01-01T08:00:00Z | 69.80000000000001 | -| 2022-01-01T08:00:00Z | 69.98 | -| 2022-01-01T09:00:00Z | 73.4 | -| 2022-01-01T09:00:00Z | 70.52 | -| 2022-01-01T10:00:00Z | 72.86 | -| 2022-01-01T10:00:00Z | 71.24000000000001 | -| ... | ... | - -{{% /influxdb/custom-timestamps %}} - -{{% note %}} -**Note:** InfluxDB follows the standard order of operations. -See [InfluxQL mathematical operators](/influxdb/clustered/reference/influxql/math-operators/) -for more on supported operators. -{{% /note %}} - -{{% /expand %}} - -{{% expand "Select all data from more than one measurement" %}} - -```sql -SELECT * FROM home, weather -``` - -{{% influxql/table-meta %}} -Name: weather -{{% /influxql/table-meta %}} - -| time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | -| :------------------- | --: | --: | :------------ | -----: | :--- | ---: | -------: | -------: | -------: | -------: | -| 2020-01-01T00:00:00Z | | | Concord | 0 | | | 52 | 66 | 44 | 3.13 | -| 2020-01-01T00:00:00Z | | | San Francisco | 0 | | | 53 | 59 | 47 | 14.32 | -| 2020-01-01T00:00:00Z | | | Hayward | 0 | | | 50 | 57 | 44 | 2.24 | -| 2020-01-02T00:00:00Z | | | San Francisco | 0 | | | 54 | 61 | 49 | 5.82 | -| 2020-01-02T00:00:00Z | | | Hayward | 0 | | | 51 | 60 | 44 | 3.8 | -| 2020-01-02T00:00:00Z | | | Concord | 0 | | | 53 | 66 | 42 | 3.13 | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | - -{{% /expand %}} - -{{% expand "Select all data from a fully-qualified measurement (with default retention policy)" %}} - -```sql -SELECT * FROM "get-started"..home -``` - -{{% influxql/table-meta %}} -Name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -### Type-casting examples - -{{< expand-wrapper >}} - -{{% expand "Cast an integer field to a float" %}} - -```sql -SELECT co::float FROM home -``` - -{{% /expand %}} - -{{% expand "Cast a float field to an integer" %}} - -```sql -SELECT temp::integer FROM home -``` - -{{% /expand %}} - -{{% expand "Cast a float field to an unsigned integer" %}} - -```sql -SELECT temp::unsigned FROM home -``` - -{{% /expand %}} - -{{< /expand-wrapper >}} - - diff --git a/content/influxdb/clustered/reference/influxql/show.md b/content/influxdb/clustered/reference/influxql/show.md index 4abb65865..90bb833f8 100644 --- a/content/influxdb/clustered/reference/influxql/show.md +++ b/content/influxdb/clustered/reference/influxql/show.md @@ -14,153 +14,6 @@ list_code_example: | ``` related: - /influxdb/clustered/query-data/influxql/explore-schema/ + +source: /shared/influxql-v3-reference/show.md --- - -Use InfluxQL `SHOW` statements to query schema information from a database. - -- [SHOW RETENTION POLICIES](#show-retention-policies) -- [SHOW MEASUREMENTS](#show-measurements) -- [SHOW FIELD KEYS](#show-field-keys) -- [SHOW TAG KEYS](#show-tag-keys) -- [SHOW TAG VALUES](#show-tag-values) - -## SHOW RETENTION POLICIES - -Use the `SHOW RETENTION POLICIES` statement to list retention policies associated -with a database. -Each database has a single retention policy--`autogen`. - -{{% note %}} -In {{< product-name >}}, retention policies are not part of the -data structure but are expected by InfluxQL and used in fully-qualified measurements -in the [`FROM` clause](/influxdb/clustered/reference/influxql/select/#from-clause). -The data returned for each retention policy does not represent the actual -retention-related attributes of the database. The values are placeholder values -meant only for InfluxQL feature parity. - -For information about database data retention, see -[List databases](/influxdb/clustered/admin/databases/list/). -{{% /note %}} - -```sql -SHOW RETENTION POLICIES [ON ] -``` - -#### Examples - -```sql --- Show retention policies in the database specified in the query request -SHOW RETENTION POLICIES - --- Show retention policies in a specific database -SHOW RETENTION POLICIES ON "example-database" -``` - -## SHOW MEASUREMENTS - -Use the `SHOW MEASUREMENTS` statement to list measurements in a database. - -```sql -SHOW MEASUREMENTS [with_measurement_clause] [where_clause] [limit_clause] [offset_clause] -``` - -#### Examples - -```sql --- Show all measurements -SHOW MEASUREMENTS - --- Show measurements where region tag = 'uswest' AND host tag = 'serverA' -SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' - --- Show measurements that start with 'h2o' -SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ -``` - -## SHOW FIELD KEYS - -Use the `SHOW FIELD KEYS` statement to list all field keys in a measurement. - -```sql -SHOW FIELD KEYS [from_clause] -``` - -#### Examples - -```sql --- Show field keys and field value data types from all measurements -SHOW FIELD KEYS - --- Show field keys and field value data types from specified measurement -SHOW FIELD KEYS FROM "cpu" -``` - -## SHOW TAG KEYS - -Use the `SHOW TAG KEYS` statement to list tag keys in a measurement. - -```sql -SHOW TAG KEYS [from_clause] [where_clause] [limit_clause] [offset_clause] -``` - -#### Examples - -```sql --- Show all tag keys -SHOW TAG KEYS - --- Show all tag keys from the cpu measurement -SHOW TAG KEYS FROM "cpu" - --- Show all tag keys from the cpu measurement where the region key = 'uswest' -SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' - --- Show all tag keys where the host key = 'serverA' -SHOW TAG KEYS WHERE "host" = 'serverA' -``` - -## SHOW TAG VALUES - -Use the `SHOW TAG VALUES` statement to list values of specified tags in a database. - -```sql -SHOW TAG VALUES [from_clause] WITH KEY = [where_clause] [limit_clause] [offset_clause] -``` - -By default, the `SHOW TAG VALUES` statement only returns unique tag values from -**the last day**. To modify the time range, include -[`WHERE` clause with a time-based predicate](/influxdb/clustered/reference/influxql/where/#time-ranges). - -{{% note %}} - -#### Include a FROM clause - -We strongly recommend including a `FROM` clause with the `SHOW TAG VALUES` -statement that specifies 1-50 tables to query. -Without a `FROM` clause, the InfluxDB query engine must read data from all -tables and return unique tag values from each. - -Depending on the number of tables in your database and the number of unique tag -values in each table, excluding a `FROM` clause can result in poor query performance, -query timeouts, or unnecessary resource allocation that may affect other queries. - -{{% /note %}} - -#### Examples - -```sql --- Show tag values from the cpu measurement for the region tag -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" - --- Show tag values from the cpu measurement for the region tag for a custom time range -SHOW TAG VALUES FROM "cpu" WITH KEY = "region" WHERE time > -7d - --- Show tag values from multiple measurements for the region tag -SHOW TAG VALUES FROM "cpu", "memory", "disk" WITH KEY = "region" - --- Show tag values from the cpu measurement for all tag keys that do not include the letter c -SHOW TAG VALUES FROM "cpu" WITH KEY !~ /.*c.*/ - --- Show tag values from the cpu measurement for region & host tag keys where service = 'redis' -SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' -``` diff --git a/content/influxdb/clustered/reference/influxql/subqueries.md b/content/influxdb/clustered/reference/influxql/subqueries.md index 7984f5e47..c9a9d19ef 100644 --- a/content/influxdb/clustered/reference/influxql/subqueries.md +++ b/content/influxdb/clustered/reference/influxql/subqueries.md @@ -13,234 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` + +source: /shared/influxql-v3-reference/subqueries.md --- - -An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. -The outer query queries results returned by the inner query (subquery). - -- [Syntax](#syntax) -- [Examples](#examples) -- [Notable subquery behaviors](#notable-subquery-behaviors) - -{{% note %}} -InfluxQL does not support a `HAVING` clause, however InfluxQL subqueries offer -functionality similar to the [SQL `HAVING` clause](/influxdb/clustered/reference/sql/having/). -{{% /note %}} - -## Syntax - -```sql -SELECT_clause FROM ( SELECT_statement ) [...] -``` - -When using subqueries, InfluxQL **performs the inner query first**, then performs -the outer query. - -The outer query requires a [`SELECT` clause](/influxdb/clustered/reference/influxql/select/#select-clause) -and a [`FROM` clause](/influxdb/clustered/reference/influxql/select/#from-clause). -The inner query is enclosed in parentheses in the outer query's `FROM` clause. - -InfluxQL supports multiple nested subqueries: - -```sql -SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] -``` - -## Examples - -{{% note %}} -#### Sample data - -The examples below use the following sample data sets: - -- [Get started home sensor data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data) -- [Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data) -{{% /note %}} - -{{< expand-wrapper >}} - -{{% expand "Apply an aggregate function to an aggregated result set" %}} - -```sql -SELECT - SUM(max) -FROM - ( - SELECT - MAX(temp) - FROM - home - GROUP BY - room - ) -``` - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | sum | -| :------------------- | ---: | -| 1970-01-01T00:00:00Z | 46.1 | - -{{% /expand %}} - -{{% expand "Calculate the average difference between two fields" %}} - -```sql -SELECT - MEAN(difference) -FROM - ( - SELECT - a - b AS difference - FROM - numbers - ) -``` - -{{% influxql/table-meta %}} -Table: numbers -{{% /influxql/table-meta %}} - -| time | mean | -| :------------------- | -------------------: | -| 1970-01-01T00:00:00Z | -0.03629771779732732 | - -{{% /expand %}} - -{{% expand "Filter aggregate values based on a threshold" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - co_change -FROM - ( - SELECT - SPREAD(co) AS co_change - FROM - home - GROUP BY - room, - time(2h) - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' - AND co_change >= 4 -``` - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | co_chnage | -| :------------------- | --------: | -| 2022-01-01T18:00:00Z | 4 | -| 2022-01-01T18:00:00Z | 5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Perform additional aggregate operations on aggregate values" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - SUM(co_derivative) AS sum_derivative -FROM - ( - SELECT - DERIVATIVE(MEAN(co)) AS co_derivative - FROM - home - GROUP BY - time(12m), - room - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -GROUP BY - room -``` - -{{% /influxdb/custom-timestamps %}} - -{{% influxql/table-meta %}} -Table: home -{{% /influxql/table-meta %}} - -| time | room | sum_derivative | -| :------------------- | :---------- | -------------: | -| 1970-01-01T00:00:00Z | Kitchen | 5.2 | -| 1970-01-01T00:00:00Z | Living Room | 3.4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable subquery behaviors - -- [Apply time bounds to the outer query to improve performance](#apply-time-bounds-to-the-outer-query-to-improve-performance) -- [Cannot use multiple SELECT statements in a subquery](#cannot-use-multiple-select-statements-in-a-subquery) - -### Apply time bounds to the outer query to improve performance - -To improve the performance of InfluxQL queries that use subqueries and a -specified time range, apply the `WHERE` clause with time-based predicates to the -outer query rather than the inner query. -For example--the following queries return the same results, but **the query with -time-based predicate on the outer query is more performant than the query with -time-based predicate on the inner query**: - -{{% influxdb/custom-timestamps %}} - -#### Time bounds on the outer query {note="(Recommended)"} - -```sql -SELECT - inner_value AS value -FROM - ( - SELECT - raw_value as inner_value - ) -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' -``` - -#### Time bounds on the inner query - -```sql -SELECT - inner_value AS value -FROM - ( - SELECT - raw_value as inner_value - WHERE - time >= '2022-07-19T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z' - ) -``` -{{% /influxdb/custom-timestamps %}} - -### Cannot use multiple SELECT statements in a subquery - -InfluxQL does not support multiple -[`SELECT` statements](/influxdb/clustered/reference/influxql/select/) -per subquery: - -```sql -SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] -``` - -However, InfluxQL does support multiple nested subqueries per outer query: - -```sql -SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] - ------------------ ---------------- - Subquery 1 Subquery 2 -``` diff --git a/content/influxdb/clustered/reference/influxql/time-and-timezone.md b/content/influxdb/clustered/reference/influxql/time-and-timezone.md index 34b34e806..7515a0c9b 100644 --- a/content/influxdb/clustered/reference/influxql/time-and-timezone.md +++ b/content/influxdb/clustered/reference/influxql/time-and-timezone.md @@ -13,367 +13,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` + +source: /shared/influxql-v3-reference/time-and-timezone.md --- - -InfluxQL is designed for working with time series data and includes features specifically for working with time. -You can review the following ways to work with time and timestamps in your InfluxQL queries: - -- [Time syntax](#time-syntax) - - [Add and subtract time values](#add-and-subtract-time-values) -- [Query time range](#query-time-range) - - [Supported operators](#supported-operators) -- [Query examples](#query-examples) -- [Time zone clause](#time-zone-clause) -- [Notable behaviors](#notable-behaviors) - - [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - - [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) - - [Cannot use parameters for durations](#cannot-use-parameters-for-durations) - -## Time syntax - -InfluxQL supports the following timestamp literal syntaxes: - -```sql -'2006-01-02T15:04:05.00Z' -- RFC3339 date-time string -'2006-01-02 15:04:05.00' -- RFC3339-like date-time string -1136189045000000000 -- Unix nanosecond epoch time -1136189045s -- Unix epoch time -``` - -- **RFC3339 date-time string**: - [String literal](/influxdb/clustered/reference/influxql/#strings) using - the RFC3339 timestamp format, `YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`. -- **RFC3339-like date-time string**: - [String literal](/influxdb/clustered/reference/influxql/#strings) using - the RFC3339-like timestamp format, `YYYY-MM-DD HH:MM:SS.nnnnnnnnn`. -- **Unix nanosecond epoch time**: - [Integer](/influxdb/clustered/reference/influxql/#integers) that - represents the number of nanoseconds elapsed since the - [Unix epoch](/influxdb/clustered/reference/glossary/#unix-epoch). -- **Unix epoch time**: - [Duration literal](/influxdb/clustered/reference/influxql/#durations) - that represents the number of specified time units elapsed since the - [Unix epoch](/influxdb/clustered/reference/glossary/#unix-epoch). - _[View supported duration units](/influxdb/clustered/reference/influxql/#durations)_. - -##### Supported timestamp values - -| | RFC3339 | Unix nanosecond time | -| ----------- | :----------------------------: | -------------------: | -| **Maximum** | 2262-04-11T23:47:16.854775807Z | 9223372036854775807 | -| **Minimum** | 1677-09-21T00:12:43.145224193Z | -9223372036854775807 | - -### Add and subtract time values - -Timestamp values support addition and subtraction operations with -[duration literals](/influxdb/clustered/reference/influxql/#durations). -Add (`+`) or subtract (`-`) a duration to or from a timestamp to return an -updated timestamp. - -```sql -'2023-01-01T00:00:00Z' + 2h -- Resolves to 2023-01-01T02:00:00Z -'2023-01-01 00:00:00' - 20h -- Resolves to 2022-12-31T04:00:00Z -1672531200000000000 + 1y -- Resolves to 2024-01-01T00:00:00Z -``` - -{{% note %}} -InfluxQL requires a whitespace between the `+` operators `-` and the duration literal. -{{% /note %}} - -## Query time range - -To specify the time range of a query, use conditional expressions in the -[`WHERE` clause](/inflxudb/clustered/reference/influxql/where/) that -compare the value of the `time` column to an absolute timestamp or a relative -timestamp. - -- **Absolute time range**: Define query time bounds with timestamp literals - - ```sql - WHERE time >= '2023-01-01T00:00:00Z' AND time <= '2023-07-01T00:00:00Z' - WHERE time >= '2023-01-01 00:00:00' AND time <= '2023-07-01 00:00:00' - WHERE time >= 1672531200000000000 AND time <= 1688169600000000000 - WHERE time >= 1672531200s and time <= 1688169600000ms - ``` - -- **Relative time range**: Define query time bounds with a duration literal - added to or subtracted from timestamp literals. - - {{% note %}} - Use `now()` to return the current system time (UTC). - {{% /note %}} - - ```sql - -- Query data from the last day - WHERE time >= now() - 1d - - -- Query data from the previous week - WHERE time >= now() - 1w AND time <= now() - 2w - - -- Query data relative to a specific time - WHERE time >= '2023-01-01' - 1w AND time <= '2023-01-01' + 1w - ``` - -### Supported operators - -Conditional expressions with time operands support the following comparison operators: - -| Operator | Meaning | -|:--------:|:------- | -| `=` | equal to | -| `<>` | not equal to | -| `!=` | not equal to | -| `>` | greater than | -| `>=` | greater than or equal to | -| `<` | less than | -| `<=` | less than or equal to | - -{{% note %}} -Currently, InfluxQL supports the `AND` logical operator to define query time bounds, -but does not support using the `OR` logical operator to query multiple time ranges. -{{% /note %}} - -## Query examples - -The following examples use the -[Get started home sensor sample dataset](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} - -{{% expand "Specify a time range with RFC3339 date-time strings" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range with RFC3339-like date-time strings" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= '2022-01-01 08:00:00' - AND time <= '2022-01-01 12:00:00' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} - -{{% expand "Specify a time range with nanosecond epoch timestamps" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= 1641024000000000000 - AND time <= 1641038400000000000 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range with second-precision epoch timestamps" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - room = 'Kitchen' - AND time >= 1641024000s - AND time <= 1641038400s -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | -| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range relative to a timestamp" %}} -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | -| 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | -| 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | -| 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Specify a time range relative to now" %}} - -```sql -SELECT * FROM home WHERE time >= now() - 2h -``` - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Time zone clause - -{{% warn %}} -InfluxQL in {{< product-name >}} does not currently support the time zone clause, -which applies a time zone offset to UTC timestamps in query results. -{{% /warn %}} - - - -## Notable behaviors - -- [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) -- [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) -- [Cannot use parameters for durations](#cannot-use-parameters-for-durations) - -### Cannot query multiple time ranges - -InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. -For example, the following query returns no results: - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') - OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') -``` - -{{% /influxdb/custom-timestamps %}} - -### Querying future data with a `GROUP BY time()` clause - -Queries that do not specify time bounds in the `WHERE` clause and do not include -a `GROUP BY time()` clause use the [minimum and maximum timestamps](#supported-timestamp-values) -as the default time range. -If the query includes a `GROUP BY time()` clause, the default time range is -between `1677-09-21T00:12:43.145224193Z` and -[`now()`](/influxdb/clustered/reference/influxql/functions/date-time/#now). - -To query data with timestamps that occur in the future (after `now()`), -provide an explicit upper bound in the `WHERE` clause. - -### Cannot use parameters for durations - -Currently, InfluxDB doesn't support using parameters for durations in -[parameterized queries](/influxdb/clustered/query-data/parameterized-queries/). diff --git a/content/influxdb/clustered/reference/influxql/where.md b/content/influxdb/clustered/reference/influxql/where.md index d4da13c1c..84b06f0ef 100644 --- a/content/influxdb/clustered/reference/influxql/where.md +++ b/content/influxdb/clustered/reference/influxql/where.md @@ -12,359 +12,6 @@ list_code_example: | ```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` + +source: /shared/influxql-v3-reference/where.md --- - -Use the `WHERE` clause to filter data based on -[field values](/influxdb/clustered/reference/glossary/#field), -[tag values](/influxdb/clustered/reference/glossary/#tag), and -[timestamps](/influxdb/clustered/reference/glossary/#timestamp). - -- [Syntax](#syntax) -- [Operators](#comparison-operators) - - [Comparison operators](#comparison-operators) - - [Logical operators](#logical-operators) -- [Time ranges](#time-ranges) -- [Regular expressions](#regular-expressions) -- [WHERE clause examples](#where-clause-examples) -- [Notable behaviors](#notable-behaviors) - - [Single and double quotes](#single-and-double-quotes) - - [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - -## Syntax - -```sql -SELECT_clause FROM_clause WHERE [(AND|OR) [...]] -``` - -- **conditional_expression**: Comparison between two operands that evaluates to - `true` or `false`. Comparison logic is determined by - [operators](#operators) used in the expression. - These expressions can operate on InfluxDB fields, tags, and timestamps. - Use logical operators (`AND`, `OR`) to chain multiple conditional expressions - together. - -## Operators - -Operators evaluate the relationship between two operands and return -`true` or `false`. - -### Comparison operators - -| Operator | Meaning | Supported data types | -| :------: | :--------------------------------- | :---------------------- | -| `=` | Equal to | all | -| `<>` | Not equal to | all | -| `!=` | Not equal to | all | -| `>` | Greater than | numeric, timestamp | -| `>=` | Greater than or equal to | numeric, timestamp | -| `<` | Less than | numeric, timestamp | -| `<=` | Less than or equal to | numeric, timestamp | -| `=~` | Matches a regular expression | strings | -| `!~` | Doesn't match a regular expression | strings | - -### Logical operators - -| Operator | Meaning | -| :------- | :---------------------------------------------------------------------- | -| `AND` | Returns `true` if both operands are `true`. Otherwise, returns `false`. | -| `OR` | Returns `true` if any operand is `true`. Otherwise, returns `false`. | - -## Time ranges - -Use the `WHERE` clause to specify a time range to query. -If a time range isn't specified in the `WHERE` clause, the [default time range](/influxdb/clustered/reference/influxql/#default-time-range) is used. - -Timestamps are stored in the `time` column. -Use comparison operators to compare the value of the `time` column to a -timestamp literal, integer (Unix nanosecond timestamp), or [expression](/influxdb/clustered/reference/glossary/#expression). - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Timestamp](#) -[Integer](#) -[Expression](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -WHERE - time >= '2023-01-01T00:00:00Z' - AND time < '2023-07-01T00:00:00Z' -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -WHERE - time >= 1672531200000000000 - AND time < 1688169600000000000 -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -WHERE - time >= now() - 1d - AND time < now() -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -See [Time syntax](/influxdb/clustered/reference/influxql/time-and-timezone/#time-syntax) -for information on how to specify alternative time ranges in the `WHERE` clause. - -{{% note %}} -InfluxQL [does not support querying multiple time ranges](#cannot-query-multiple-time-ranges). -{{% /note %}} - -## Regular expressions - -Regular expressions can be used to evaluate _string_ values in the `WHERE` clause -using regular expression comparison operators: - -- `=~`: Matches a regular expression -- `!~`: Doesn't match a regular expression - -```sql -SELECT * FROM home WHERE room =~ /^K/ -``` - -For more information about InfluxQL regular expression syntax, see -[InfluxQL regular expressions](/influxdb/clustered/reference/influxql/regular-expressions/). - -## WHERE clause examples - -The following examples use the -[Get started home sensor sample dataset](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data). - -{{< expand-wrapper >}} -{{% expand "Select data with a specific tag value" %}} - -```sql -SELECT * FROM home WHERE room = 'Living Room' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | -| 2022-01-01T11:00:00Z | 0 | 36 | Living Room | 22.2 | -| 2022-01-01T12:00:00Z | 0 | 35.9 | Living Room | 22.2 | -| ... | ... | ... | ... | ... | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data from a specific time range" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | -| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | -| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data from a relative time range" %}} - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :---------- | ---: | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | -| 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | -| 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | -| 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select field values above a threshold" %}} - -```sql -SELECT co FROM home WHERE co > 9 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | -| :------------------- | --: | -| 2022-01-01T18:00:00Z | 18 | -| 2022-01-01T19:00:00Z | 14 | -| 2022-01-01T19:00:00Z | 22 | -| 2022-01-01T20:00:00Z | 17 | -| 2022-01-01T20:00:00Z | 26 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select specific field values" %}} - -```sql -SELECT room, co FROM home WHERE co = 9 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | room | co | -| :------------------- | :---------- | --: | -| 2022-01-01T17:00:00Z | Kitchen | 9 | -| 2022-01-01T18:00:00Z | Living Room | 9 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select field values based on arithmetic" %}} - -```sql -SELECT room, co FROM home WHERE co - 10 > 5 -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | room | co | -| :------------------- | :---------- | --: | -| 2022-01-01T18:00:00Z | Kitchen | 18 | -| 2022-01-01T19:00:00Z | Kitchen | 22 | -| 2022-01-01T20:00:00Z | Living Room | 17 | -| 2022-01-01T20:00:00Z | Kitchen | 26 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data with field values above a threshold and a specific tag value" %}} - -```sql -SELECT * FROM home WHERE temp > 22.7 AND room = 'Kitchen' -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | hum | room | temp | -| :------------------- | --: | ---: | :------ | ---: | -| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | -| 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | -| 2022-01-01T14:00:00Z | 1 | 36.3 | Kitchen | 22.8 | -| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | -| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "Select data based on the relationship between columns" %}} - -```sql -SELECT co, temp FROM home WHERE co > temp -``` - -{{% influxql/table-meta %}} -name: home -{{% /influxql/table-meta %}} - -{{% influxdb/custom-timestamps %}} - -| time | co | temp | -| :------------------- | --: | ---: | -| 2022-01-01T20:00:00Z | 26 | 22.7 | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## Notable behaviors - -- [Single and double quotes](#single-and-double-quotes) -- [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) - -### Single and double quotes - -In InfluxQL, single quotation marks (`'`) and double quotation marks (`"`) work -differently and can alter the way a `WHERE` clause functions. -Single quotes are used in [string](/influxdb/clustered/reference/influxql/#strings) -and [timestamp](/influxdb/clustered/reference/influxql/#dates--times) literals. -Double quotes are used to quote [identifiers](/influxdb/clustered/reference/influxql/#identifiers), -(time, field, and tag column names). - -For example, the following conditional expression compares the value of the -`location` _column_ to the _literal string_, `London`: - -```sql -"location" = 'London' -``` - -The following conditional expression compares the value of the `location` _column_ -to the value of the `London` _column_: - -```sql -"location" = "London" -``` - -Misused double and single quotes in the `WHERE` clause often results in unexpected -empty query results. -For more information about quotation marks, see -[InfluxQL quotation](/influxdb/clustered/reference/influxql/quoting/). - -### Cannot query multiple time ranges - -InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. -For example, the following query returns no results: - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT * -FROM home -WHERE - (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') - OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') -``` - -{{% /influxdb/custom-timestamps %}} diff --git a/content/influxdb/clustered/reference/internals/system-tables.md b/content/influxdb/clustered/reference/internals/system-tables.md deleted file mode 100644 index 7241273e8..000000000 --- a/content/influxdb/clustered/reference/internals/system-tables.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: InfluxDB system tables -description: > - InfluxDB system measurements contain time series data used by and generated from the - InfluxDB internal monitoring system. -menu: - influxdb_clustered: - name: System tables - parent: InfluxDB internals -weight: 103 -influxdb/clustered/tags: [tables, information schema] -related: - - /influxdb/clustered/reference/sql/information-schema/ ---- - -{{% warn %}} -Queries of InfluxDB system tables may affect production performance while -system tables are accessed. - -System tables are not currently part of the stable API and the schema may change -in subsequent releases. -{{% /warn %}} - -InfluxDB system measurements contain time series data used by and generated from the -InfluxDB internal monitoring system. - -Each InfluxDB Clustered namespace includes the following system measurements: - -- [queries](#_queries-system-measurement) - -## queries system measurement - -The `system.queries` measurement stores log entries for queries executed for the provided namespace (database) on the node that is currently handling queries. - -The following example shows how to list queries recorded in the `system.queries` measurement: - -```sql -SELECT issue_time, query_type, query_text, success FROM system.queries; -``` - -_When listing measurements (tables) available within a namespace, some clients and query tools may include the `queries` table in the list of namespace tables._ - -`system.queries` reflects a process-local, in-memory, namespace-scoped query log. -While this table may be useful for debugging and monitoring queries, keep the following in mind: - -- Records stored in `system.queries` are volatile. - - Records are lost on pod restarts. - - Queries for one namespace can evict records from another namespace. -- Data reflects the state of a specific pod answering queries for the namespace. - - A query for records in `system.queries` can return different results depending on the pod the request was routed to. - -**Data retention:** System data can be transient and is deleted on pod restarts. - -### queries measurement schema - -- **system.queries** _(measurement)_ - - **fields**: - - **issue_time**: timestamp when the query was issued - - **query_type**: type (syntax: `sql`, `flightsql`, or `influxql`) of the query - - **query_text**: query statement text - - **success**: execution status (boolean) of the query - - **completed_duration**: time (duration) that the query took to complete - - **trace_id**: trace ID for debugging and monitoring events diff --git a/content/influxdb/clustered/reference/release-notes/clustered.md b/content/influxdb/clustered/reference/release-notes/clustered.md new file mode 100644 index 000000000..7474bf116 --- /dev/null +++ b/content/influxdb/clustered/reference/release-notes/clustered.md @@ -0,0 +1,1375 @@ +--- +title: InfluxDB Clustered release notes +description: > + View InfluxDB Clustered release information including new features, bug fixes, and more. +menu: + influxdb_clustered: + parent: Release notes + name: InfluxDB Clustered + identifier: clustered-release-notes +weight: 201 +--- + +{{% note %}} +## Checkpoint releases {.checkpoint} + +Some InfluxDB Clustered releases are checkpoint releases that introduce a +breaking change to an InfluxDB component. +When [upgrading InfluxDB Clustered](/influxdb/clustered/admin/upgrade/), +**always upgrade to each checkpoint release first, before proceeding to newer versions**. + +Checkpoint releases are only made when absolutely necessary and are clearly +identified below with the icon. +{{% /note %}} + +{{< release-toc >}} + +--- + +## 20241024-1354148 {date="2024-10-24" .checkpoint} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20241022-1346953 +``` + +### Known Bugs + +### `core` service DSN parsing errors + +This release has a known bug in the `core` pods with respect to handling of +options in Postgres DSNs. This bug can be seen in the `core-MMMMMMMMMM-NNNNN` +logs that look like the following: + +``` +2024-11-04T01:00:00.000Z | 3: error returned from database: database "influxdb&options=-c%20search_path=" does not exist +2024-11-04T01:00:19.000Z | 4: database "influxdb&options=-c%20search_path=" does not exist +``` + +Due to incorrect parsing of the +`POSTGRES_DSN` environment variable, the `influxdb&options=-c%20search_path=` string is +interpreted as the database name. + +To work around this bug, in your AppInstance, +include a `spec.package.spec.images.overrides` section to override the +`core` pods built-in image with an image that has the bugfix for the DSN +parsing error--for example: + +``` +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: + images: + overrides: + - name: 'influxdb2-artifacts/granite/granite' + newFQIN: 'us-docker.pkg.dev/influxdb2-artifacts/granite/granite:7acf9ca6e1ad15db80b22cd0bc071acdb561eb51' +# ...[remaining configuration] +``` + +### Highlights + +#### AppInstance image override bug fix + +In [20240925-1257864](#20240925-1257864), the AppInstance image override was +broken with the introduction of strict always-on license enforcement. +This release fixes that bug. + +This bug is expected to have an outsized impact on customers running InfluxDB +Clustered in air-gapped environments where the deployment model involves +overriding the default image repository to point to images copied to an +air-gapped registry. + +This release is an alternative to [20240925-1257864](#20240925-1257864) for +customers who depend on this image override feature. + +#### Upgrade bug fix + +[20240925-1257864](#20240925-1257864) introduced a schema migration bug that +caused an `init` container in the `account` Pods to hang indefinitely. +This would only affect InfluxDB Clustered during an upgrade; not a fresh install. + +For customers who experience this bug when attempting to upgrade to +[20240925-1257864](#20240925-1257864), upgrade to this 20241024-1354148 instead. + +### Changes + +#### Deployment + +- Enable overriding the default CPU and memory resource requests and limits for + the Garbage collector and Catalog services. +- Remove the Gateway service and implement the newly introduced Core service. +- Fix logic related to applying default resource limits for IOx components. +- Support [`ResourceQuota`s](https://kubernetes.io/docs/concepts/policy/resource-quotas/) + with the `enableDefaultResourceLimits` feature flag. This causes resource + limits to be applied even to containers that don't normally have limits + applied. + +--- + +## 20240925-1257864 {date="2024-09-25" .checkpoint} + +{{% warn %}} +This release has a number of bugs in it which make it unsuitable for customer use. +If you are currently running this version, please upgrade to +[20241024-1354148](#20241024-1354148). +{{% /warn %}} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:202409XX-XXXXXXX +``` + +### Highlights + +#### Default to partial write semantics + +In InfluxDB Clustered 20240925-1257864+, "partial writes" are enabled by default. +With partial writes enabled, InfluxDB accepts write requests with invalid or +malformed lines of line protocol and successfully write valid lines and rejects +invalid lines. Previously, if any line protocol in a batch was invalid, the +entire batch was rejected and no data was written. + +To disable partial writes and revert back to the previous behavior, set the +`INFLUXDB_IOX_PARTIAL_WRITES_ENABLED` environment variable on your cluster's +Ingester to `false`. Define this environment variable in the +`spec.package.spec.components.ingester.template.containers.iox.env` property in +your `AppInstance` resource. + +{{< expand-wrapper >}} +{{% expand "View example of disabling partial writes in your `AppInstance` resource" %}} + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + spec: + components: + ingester: + template: + containers: + iox: + env: + INFLUXDB_IOX_PARTIAL_WRITES_ENABLED: false +``` + +{{% /expand %}} +{{< /expand-wrapper >}} + +For more information about defining variables in your InfluxDB cluster, see +[Manage environment variables in your InfluxDB Cluster](/influxdb/clustered/admin/env-vars/). + +##### Write API behaviors + +When submitting a write request that includes invalid or malformed line protocol, +The InfluxDB write API returns a 400 response code and does the following: + +- With partial writes _enabled_: + + - Writes all valid points and rejects all invalid points. + - Includes details about the [rejected points](/influxdb/clustered/write-data/troubleshoot/#troubleshoot-rejected-points) + (up to 100 points) in the response body. + +- With partial writes _disabled_: + + - Rejects all points in the batch. + - Includes an error message and the first malformed line of line protocol in + the response body. + +#### Deploy and use the Catalog service by default + +The Catalog service is a new IOx component that centralizes access to the +InfluxDB Catalog among Ingesters, Queriers, Compactors, and Garbage Collectors. +This is expected to improve Catalog query performance overall with an expected +drop in ninety-ninth percentile (p99) latencies. + +### Upgrade notes + +#### License now required + +A valid license token is now required to start up your InfluxDB Cluster. +To avoid possible complications, ensure you have a valid license token. If you +do not, contact your InfluxData sales representative to get a license token +**before upgrading to this release**. + +#### Removed prometheusOperator feature flag + +The `prometheusOperator` feature flag has been removed. +**If you current have this feature flag enabled in your `AppInstance` resource, +remove it before upgrading to this release.** +This flag was deprecated in a previous release, but from this release forward, +enabling this feature flag may cause errors. + +The installation of the Prometheus operator should be handled externally. + +### Changes + +#### Deployment + +- Introduces the `nodeAffinity` and CPU/Memory requests setting for "granite" + components. Previously, these settings were only available for core IOx + components. +- Prior to this release, many of the IOx dashboards deployed with the `grafana` + feature flag were showing "no data." This has been fixed and now all + dashboards should display actual data. + +#### Database Engine + +- Adjusted compactor concurrency scaling heuristic to improve performance as + memory and CPU scale. +- Adjusted default `INFLUXDB_IOX_COMPACTION_PARTITION_MINUTE_THRESHOLD` from + `20m` to `100m` to help compactor more quickly rediscover cool partitions. + +#### Configuration + +- Introduces the `podAntiAffinity` setting for InfluxDB Clustered components. + Previously, the scheduling of pods was influenced by the Kubernetes + scheduler's default behavior. For further details, see the + [Kubernetes pod affinity documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#types-of-inter-pod-affinity-and-anti-affinity). + +--- + +## 20240819-1176644 {date="2024-08-19" .checkpoint} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240819-1176644 +``` + +### Highlights + +#### `admin` section is no longer required + +Previously, an identity provider setup was required through the `admin` section +of the `AppInstance` resource, for example: + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + package: + image: + apiVersion: influxdata.com/v1alpha1 + spec: + ## ...snip + admin: + users: + - ... + dsn: + valueFrom: + ... + identityProvider: + jwksEndpoint: +``` + +This section is no longer required and will no longer result in a schema +validation error when omitted. +When the `admin` section is omitted, the `admin-token` `Secret` can be used +instead to get started quickly. + +{{% note %}} +We still highly recommend OAuth for production; however, this lets you run an +InfluxDB Cluster with out having to integrate with an identity provider.** +{{% /note %}} + +### Upgrade notes + +This release includes some preparatory work for changes being made to database +schemas and tooling for internal services. It does not have an impact to +customer workloads. + +### Changes + +#### Deployment + +- Various Grafana dashboard updates. +- A best-effort, pre-populated `influxctl` config file is provided as a + `ConfigMap` for your convenience. +- Limit garbage collector replicas to 1, see the + [documentation](/influxdb/clustered/reference/internals/storage-engine/#garbage-collector-scaling-strategies) + for further details. + +#### Database engine + +- Improved efficiency of system table queries. +- Fixes for InfluxQL handling of `0` divisor. +- Improve router performance when retrieving statistics. +- Support InfluxQL queries over FlightSQL. +- Various dependency updates. + +#### Configuration + +- Added schema definitions for `admin.users`. + +--- + +## 20240717-1117630 {date="2024-07-17"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240717-1117630 +``` + +### Highlights + +#### Experimental license enforcement + +This release introduces a new feature flag, `useLicensedBinaries`, that causes +InfluxDB to execute IOx components a container image implementing a new license +enforcement mechanism. License enforcement mechanisms include: + +- A proper `License` Custom Resource manifest must be installed in the + namespace to which InfluxDB Clustered is deployed. Only one `License` named + `iox-license` may be deployed per namespace. +- Without a valid `License`, IOx pods crashloop with error logs indicating that + no valid license can be loaded. + - A valid `License` is one that is properly signed by InfluxData and has not + exceeded its hard expiration date. +- One month before the `License` expires, all components begin logging + pending expiry warning messages. These are visible with `kubectl log -n + `. +- If a valid `License` expires while the system is running, it enters a grace + period. +- During the `License`'s grace period, the following happens: + - Throughout the grace period, all components gradually increase the + frequency of license expiry warnings. + - One week into the grace period, the InfluxDB 3.0 Querier begins returning + `FailedPrecondition` gRPC responses for the first 5 minutes of every hour. + - One month into the grace period, the InfluxDB 3.0 Querier begins returning + `FailedPrecondition` gRPC responses 100% of the time until the grace period + ends. +- At the end of the `License` grace period, all IOx components shutdown as + this is the "hard expiration" date when the binaries no longer consider + the `License` valid. + +This feature is being released on an experimental, opt-in basis while we work +with a small group of customers before making requiring licenses to run +InfluxDB Clustered. Before enabling the feature, please be sure you have a +`License` manifest provided to you by your InfluxData sales representative. + +#### Default querier count increased + +Prior to this release, the number of queriers which were spawned from the +default configuration was 1. +This has now been increased to 3. If you have previously overwritten the default +in the `AppInstance` resource, it is no longer required: + +```yaml +apiVersion: kubecfg.dev/v1alpha1 +kind: AppInstance +metadata: + name: influxdb + namespace: influxdb +spec: + ... + resources: + querier: + requests: + #replicas: 3 # No longer required! +``` + +If you wish to keep the number of queriers to 1, you must override the +`replicas` as shown above. +Refer to the schema for further details. + +This new configuration serves as a scalable default installation for +InfluxDB Clustered. + +### Changes + +#### Deployment + +- Ingesters now have a `terminationGracePeriodSeconds` value of `600` to provid + enough time to persist all buffered data. + +#### Database engine + +- Changed default `INFLUXDB_IOX_COMPACTION_*_CONCURRENCY` to be set based on + available memory rather than available cores. +- Improved metadata caching and queries. +- Improved cache read efficiency. +- Improved cache cleaning. +- Fixed some I/O delays on query planning. +- Better handling for resizing worker pools. +- Faster recovery from ingester crashes. +- Faster graceful shutdown of terminating ingester pods. +- Fixed a rare issue where ingesters could become unresponsive after hitting + memory limits. +- Added per-table column limit, to prevent unintended schema expansion. +- Reduced intermediate compactor writes to object storage. +- Increase compactor throughput. +- Numerous telemetry improvements. +- Reduced write thrashing in the catalog. +- Fixed errors with queries that use gap filling. +- Fixed errors with multiple rounds of bulk ingestion. +- Tuned garbage collector. +- Fixed some intermittent failures in bulk ingest. +- Reduced some network gossip between IOx pods. +- Fixed some inconsistent results on leading edge queries. +- Fixed WAL storage leak during ingester crash recovery. +- Improved garbage collection of data beyond the retention limit. + +--- + +## 20240605-1035562 {date="2024-06-05" .checkpoint} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240605-1035562 +``` + +### Highlights + +Multiple improvements to compaction, pruning, and performance of concurrent queries. + +#### Feature flag: `noPrometheus` + +The introduction of the `noPrometheus` feature flag removes the `StatefulSet` +and other resources related to a bare-bones installation of Prometheus that +could be used for basic monitoring of InfluxDB Clustered. + +This feature flag is useful in cases where you already have an installation of +Prometheus and you wish to use it to monitor your InfluxDB cluster. + +Refer to the `AppInstance` schema for further details regarding feature flags. + +### Upgrade notes + +Air-gapped installations need to prefetch the new granite image. + +``` +us-docker.pkg.dev/influxdb2-artifacts/granite/granite@sha256:1683f97386f8af9ce60662ae4ff423770fee166b11378583e211ea30dc849633 +``` + +For more information, see the +[documentation](/influxdb/clustered/install/set-up-cluster/configure-cluster/?t=Private+registry+%28air-gapped%29#public-registry-non-air-gapped). + +### Changes + +#### Deployment + +- Updated Granite components to reference a single image, reducing the overall + image size. +- Added Grafana licensing dashboard. +- Added the `noPrometheus` feature flag. + +#### Database engine + +- Ingesters now provide a soft, best-effort memory limit. + - Provided by `INFLUXDB_IOX_RAM_SOFT_LIMIT_BYTES`, which applies a ceiling + from a percentage of the container memory to avoid `OOMKilled` scenarios. + - Upon reaching this limit, InfluxDB Clustered attempts to persist all + buffered data is and returns a resource exhaustion error for write requests + until memory usage is below 50%. +- Catalog cache write batching. +- Multiple compactor improvements. +- Improved performance of some metadata queries. +- Improved concurrent query performance. + - Adjusted querier partitions assigned to large queries to reduce latency of + sub-second queries and prevent resource bottlenecks cause by long running + queries. + - This can be tuned with the `INFLUXDB_IOX_NUM_QUERY_PARTITIONS` environment + variable. +- Improved reporting for InfluxQL syntax errors. + +--- + +## 20240430-976585 {date="2024-04-30"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240430-976585 +``` + +### Highlights + +- Added configuration settings for an optional Prometheus `ServiceMonitor` + under `observability.serviceMonitor` + - The feature flag is now deprecated, and will be removed in a future release. + + {{% warn %}} + Using this setting will delete and recreate the existing serviceMonitor resource that was provided by the feature flag. + {{% /warn %}} + +#### Deployment + +- Removed Nginx server snippet annotations (`nginx.ingress.kubernetes.io/server-snippet`). +- Added `observability` key in the `AppInstance` resource. + +#### Database engine + +- Improved `NULL` handling for InfluxQL. + +--- + +## 20240418-955990 {date="2024-04-18"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240418-955990 +``` + +### Highlights + +#### Minimum `influxctl` version + +If a user observes an unimplemented gRPC error when running `influxctl database` +commands, then the user should upgrade to `influxctl` v2.8.0 or later and +ensure they are running InfluxDB Clustered [20240326-922145](#20240326-922145) +or newer. + +If upgrading InfluxDB Clustered is not an option, you can continue to use a +version of `influxctl` prior to v2.8.0. + +### Changes + +#### Deployment + +- Routers now calculate the value of write replication based on the number of + running ingesters. + - This can be tuned through the `INFLUXDB_IOX_RPC_WRITE_REPLICAS` environment + variable; however, high values can impact the performance of the system. + +#### Database engine + +- Router cache entries for namespace and retention periods are updated + immediately via gossip. + - Pod restarts are no longer required to immediately see updates. +- Fixes to InfluxQL gap-filling mechanism, `FILL`. + +--- + +## 20240326-922145 {date="2024-03-26"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240325-920726 +``` + +### Highlights + +#### Lower defaults for garbage collection + +Prior to this release, the garbage collector was set at 100 days before objects, +that were no longer returned by queries, were deleted from object store. +This has been reduced to 30 days. +High values lead to a situation where there are many dangling objects and +therefore many unnecessary references in the catalog, which increases +operational burden and cost. + +#### Added support for nodeAffinity at the per-component level + +Introduces the `nodeAffinity` setting for individual components within +InfluxDB Clustered. Previously, the scheduling of pods was influenced by the +Kubernetes scheduler's default behavior. For further details, please consult the +[documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity). + +### Changes + +#### Deployment + +- Support for environment variable modifications to specific components. +- Update optional Grafana component to version 10.3.4. + - This upgrade from 9.x brings with it support for the SQL query type in the + InfluxDB data source. + +#### Database engine + +- Various additional metrics and performance improvements. +- Improve compactor concurrency heuristics. +- Fix gRPC reflection to only include services served by a particular listening + port. + + {{% note %}} + `arrow.flight.protocol.FlightService` is known to be missing in the + `iox-shared-querier`'s reflection service even though `iox-shared-querier` + does run that gRPC service. + {{% /note %}} + +--- + +## 20240227-883344 {date="2024-02-27"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240227-883344 +``` + +### Changes + +#### Deployment + +- Gossip communication between the `global-router`, `iox-shared-compactor`, and + iox-shared-ingester` now works as expected. +- Provide sane defaults to the `global-router` for maximum number of concurrent + requests. +- Lower the number of ndots for `dnsConfig` for IOx components. + +#### Database engine + +- `SHOW TAG VALUES` no longer causes a crash in the querier when the database + has a large number of measurements. +- Number of partitions scanned over in the querier is now limited for safety. + +--- + +## 20240214-863513 {date="2024-02-14" .checkpoint} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240214-863513 +``` + +### Highlights + +#### Grafana dashboards by default + +Previously, the `grafana` feature flag had to be enabled in order to have these +dashboards created. This now occurs by default and the feature flag is reserved +entirely for the creation of a Grafana `Deployment` and remains experimental. + +The contents of these dashboards are placed within various `ConfigMap` resources, +under common format `grafana-dashboard-`. They can either be imported or +mounted into your existing Grafana instance. + +### Upgrade notes + +#### Consolidated authentication + +An authentication component, previously known as `authz`, has been consolidated +into the `token-management` service. + +Now there is a temporary `Job` in place, `delete-authz-schema`, that +automatically removes the `authz` schema from the configured PostgreSQL database. + +### Changes + +#### Documentation + +- Fixed Google example in `example-customer.yml` file. + +#### Deployment + +- Fixed a logical error in the configuration when using Google Workload Identity + caused the `INFLUXDB_IOX_OBJECT_STORE` variable to be set to `memory` instead + of `google`. +- Compactor configuration concurrency is now derived from CPU limit of the pod. +- Compactor now has a lower L1 compaction threshold. + +#### Database engine + +- Correctly validate string length for column sizes. +- FlightSQL support for prepared statements. +- Improve metrics exposed by the compactor. +- Further optimizations to `LIMIT` queries. +- Add `SPREAD`, `MODE`, and `ELAPSED` support for InfluxQL. +- Add `EXPLAIN` to all supported statements in InfluxQL. +- Tracing correctly exposes HTTP path metrics. +- Dependency updates. + +--- + +## 20240111-824437 {date="2024-01-11"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20240111-824437 +``` + +### Highlights + +#### Ingress improvements + +- Ingress no longer requires a host name to be specified. +- When a TLS secret is not specified, the TLS annotations are not generated. + +##### Istio support + +This release includes first class support for Istio via the `Gateway` and +`VirtualService` resources. + +This is enabled through the `ingress` key of the `AppInstance` resource--for example: + +```yaml +package: + spec: + ingress: + template: + kind: 'Gateway' + apiVersion: 'networking.istio.io/v1beta1' + ## At present the 'selector' field is only used for Istio, this maps + ## directly to the Gateway selector to decide which Istio ingress controller + ## pods should serve the configured Gateway. + selector: + istio: 'ingressgateway' +``` + +Note that the use of `Gateway` implies the need for `VirtualService` resources, +these are automatically created for you. + + +### Upgrade notes + +As part of a `partition_id` migration that runs, if you have more than 10 +million rows in the `parquet_file` table, reach out to your Sales representative +before proceeding. You can confirm this with the following query: + +```sql +SELECT count(*) FROM iox_catalog.parquet_file +``` + +### Changes + +#### Database engine + +- `partition_id` is now used to consistently address a partition in the catalog. + This requires a migration which may take some time to complete. +- Bug fixes and dependency updates. + +--- + +## 20231213-791734 {date="2023-12-13"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20231213-791734 +``` + +### Highlights + +#### Labels/annotations + +- You can now add custom annotations and labels in pods by specifying them under + `spec.package.spec.components.*.metadata` +- Common settings for all components can be specified under + `spec.package.spec.components.common`. This is useful when you need to + configure common node selectors, taint tolerations, and annotations to adapt + the workload to requirements of your specific execution environment. + +#### Contour ingress support + +Services are now properly annotated to support the Contour Ingress controller. + +### Changes + +#### Database engine + +- Empty string values for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are ignored. +- Dependency updates. +- Query performance improvements. +- Ingester active persist tasks are tracked as a metric. +- WAL rotation logs moved from debug to info log level. +- Fixed an issue where the compactor could get stuck until reboot. +- Fixed an issue where the compactor might panic. +- Added L2 -> L2 compactions when there are many small L2 files. + +--- + +## 20231117-750011 {date="2023-11-17"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20231117-750011 +``` + +### Highlights + +{{% warn %}} +**This release fixes a regression in the database engine that was introduced in +[20231115-746129](#20231115-746129).** +{{% /warn %}} + +### Changes + +#### Deployment + +- Add support for tuning per-component log filters. +- Add support for `tolerations` at the per-component level. + +--- + +## 20231115-746129 {date="2023-11-15"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20231115-746129 +``` + +### Highlights + +#### Ingress templating + +This update enables custom annotations on the `Ingress` resources. +This is useful when configuration ingress alongside third-party software, such +as `cert-manager`. + +##### OpenShift `Route` + +Along with the ingress templating feature, this version includes OpenShift +`Route` support. +Specify the `apiVersion` and `kind` of the `ingress` configuration to align +with `Route`s and change the typical `Ingress` objects to their `Route` equivalent. + +```yaml +spec: + package: + spec: + ingress: + template: + apiVersion: "route.openshift.io/v1" + kind: "Route" +``` + +#### Support for Google Cloud Storage (GCS) + +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) +authentication methods. + +#### Support for bypassing identity provider configuration for database/token management + +We now generate a valid access token for managing Databases and Tokens and store +it as a secret within the namespace that InfluxDB is deployed. Use this token in +lieu of configuring an identity provider with `influxctl` for interacting with +the cluster. +**This access token is intended only for testing and is not recommended for use in production**. + +This feature requires `influxctl` version 2.2.0 or later. To use the access +token, you first need to copy it to a file by running the following command: + + + +```bash +kubectl get secrets/admin-token --template={{.data.token}} -n | base64 -d > token.json +``` + +After that, you need to tell `influxctl` where to find the access token by +adding the following lines to your `profile.toml` file. + +```toml +[profile.auth.token] +token_file = "/path/to/token.json" +``` + +This is a long-lived access token. Currently, the only way to revoke the token +is to perform the following actions in this order: + +1. Delete the `rsa-keys` secret from your Clustered context and namespace. +2. Rerun the `key-gen` job. +3. Restart the `authz` service. + +If you want to create a new admin token after revoking the existing one, re-run +the `create-admin-token` job. + +### Changes + +#### Deployment + +- Increase HTTP write request limit from 10 MB to 50 MB. +- Added support for [Telegraf Operator](https://github.com/influxdata/telegraf-operator). + We have added the `telegraf.influxdata.com/port` annotation to all the pods. + No configuration is required. We don't yet provide a way to specify the + `telegraf.influxdata.com/class` annotation, which means the pods use the + default Telegraf operator class (called `default`). +- Implement `ingress.template` for `Ingress` and openshift `Route`. +- Add `nodeSelector` support. +- Add Google Cloud support. +- Fix JSONSchema for `value` and `valueFrom` configuration. +- Remove `AWS_ACCESS_KEY_ID` and AWS_SECRET_ACCESS_KEY` environment variabless + when [EKS IRSA](#eks-irsa) is enabled. + +#### Database engine + +- Ingester performance improvements. +- Query pruning improvements where, in many cases, less data is fetched. +- New compactor metrics. +- Compactor tuning: autoscale L1 compaction threshold based on load. +- FlightSQL query gRPC keep-alive fixes. +- Log some querier configs during startup. +- Bulk ingest gRPC API improvements. +- Add `partition_template` column to `system.tables` table. +- Add `last_new_file_created_at`, ` last_deleted_file_at`, `num_files` , + `total_size_mb` columns to `system.partitions` table. +- Enable gossip cache distribution for faster cache coherence between nodes. + +--- + +## 20231024-711448 {date="2023-10-24"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20231024-711448 +``` + +### Highlights + +#### Additional `AppInstance` parameters + +This includes an addition to the `AppInstance` `package` specification with a +new key: `hostingEnvironment`. +Going forward, this object will be updated with various environment-specific +functionality aimed at where you _host_ InfluxDB Clustered, such as `aws` or +`openshift`. + +##### EKS IRSA + +With the addition of the `hostingEnvironment` configuration to the `AppInstance` +resource, InfluxDB now supports passing an `eksRoleArn`. +This role ARN is placed onto the IOx `ServiceAccount`. +Please ensure that the role you provide has AWS S3 permissions. + +##### OpenShift + +InfluxDB Clustered now also support the `openshift` key under the +`hostingEnvironment` object. This specifies OpenShift tailored configuration for +your environment. + +At the moment this simplifies the installation process by removing +`securityContext` from all pods since it is specified by your cluster's +configuration instead. + +#### Ingress configuration + +A backwards-compatible change to the ingress configuration that makes the +ingress use more fine-grained rules to avoid overriding other ingress rules. +You may want to review the details if you have customized the Kubernetes +manifests regarding the ingress resources. + +##### v1 write endpoint + +An endpoint has been exposed for the v1 write path, under `/write`. + +### Changes + +#### Database engine + +- Honor `SSL_CERT_FILE` for PostgreSQL connections. +- Wait for gRPC when shutting down the querier. + +#### Deployment + +- Add defined `resources` to `authzpuller`. + +--- + +## 20231004-666907 {date="2023-10-04" .checkpoint} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20231004-666907 +``` + +### Highlights + +#### Object store custom certificates + +Support for custom certificates has been implemented since version +[20230912-619813](#20230912-619813). +Unfortunately, due to a bug, our Object store client didn't use the custom certificates. +This release fixes that so you can use the existing configuration for custom +certificates to also specify the certificate and certficate authority used by +your object store. + +#### Resource limits + +Until now, the configuration spec only exposed the Kubernetes resource +_requests_ and not the limits. +Setting the limits is important for proper cluster capacity configuration. +This release fixes this deficiency. + +_See [Scale components in your cluster](/influxdb/clustered/admin/scale-cluster/#scale-components-in-your-cluster)._ + +#### Object store configuration + +A backwards-compatible change has been made to object store configuration. +This now enables the use of Azure blob storage. + +#### Installation documentation moved to the documentation site + +The "Install InfluxDB Clustered" instructions (formerly known as "GETTING_STARTED") +are now available on the public +[InfluxDB Clustered documentation](https://docs.influxdata.com/influxdb/clustered/install/). + +The `example-customer.yml` (also known as `myinfluxdb.yml`) example +configuration file still lives in the release bundle alongside the `RELEASE_NOTES`. + +### Upgrade notes + +You **must** update to this release before updating to any subsequent release. +This ensure as schema migration is sequenced properly otherwise a Kubernetes +cluster running pods with different versions will impact write availability. + +### Changes + +#### Deployment + +- Add support for setting resource limits. + +#### Documentation + +- Prior to this release, the example query for the sample data + (`air-sensor-data.lp`) was incorrect. + +#### Database engine + +- Use system certificate store. + +--- + +## 20230922-650371 {date="2023-09-22"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230922-650371 +``` + +### Highlights + +#### Configuration simplification + +This release simplifies the configuration of the admin interface. +The `internalSigningKey` configuration section is now optional and is +autogenerated. + +### Upgrade notes + +We simplified the ingress rules, which may require some changes _if_ you have +custom Ingress resources pointing to the underlying services. +Otherwise, no changes are necessary. + +#### Details + +- Ingress that previously pointed to the `account` service should now point to + the `gateway` service--for example: `/account.v1.AccountService`. +- Ingress that previously pointed to the `authz` service can be removed--for + example: `/authz.public.v1.AuthzPublicService`. +- Ingress that previously pointed to the `database-management` service should + now point to the `gateway` service--for example: + `/database_management.v1.DatabaseService`. +- Ingress that previously pointed to the `token-management` service should now + point to the `gateway` service--for example: + `/token_management.public.v1.TokenManagementPublicService`. + +### Changes + +#### Deployment + +- Update reference version of kubit to 0.0.11. +- Update the default number of routers to match ingesters (3). +- Ensure custom certificates are available to all components. + +#### Database engine + +- Catalog cache convergence improvements. +- Retry after out of memeory (OOM) errors. + +--- + +## 20230915-630658 {date="2023-09-15"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230915-630658 +``` + +### Highlights + +#### Persistent volume fixes + +This release fixes am issue involving volume permissions in some volume +provisioners (for example, EBS). +No action is required for upgrades. + +### Changes + +- Removed the "Generate internal signing key" section from the "Getting started" + documentation. +- Updated `Volume` permissions to fix issues in some environments. + +--- + +## 20230914-628600 {date="2023-09-14"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230914-628600 +``` + +### Highlights + +#### Updated Azure AD documentation + +The `Appendix` / `Configuring Identity Provider` / `Azure` section of the +"Geting started" documentation has been updated: + +```diff +- https://login.microsoftonline.com/{AZURE_TENANT_ID}/.well-known/openid-configuration ++ https://login.microsoftonline.com/{AZURE_TENANT_ID}/v2.0/.well-known/openid-configuration +``` + +### Changes + +#### Deployment + +- Documentation fixes. +- Generate JWT signing keys automatically. + +#### Database engine + +- Various minor fixes. + +--- + +## 20230912-619813 {date="2023-09-12"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230912-619813 +``` + +### Highlights + +#### Custom CA certificates {note="(Optional)"} + +InfluxDB processes inbound API requests (_ingress_) and issues outbound API +request to external services (_egress_). +The _ingress_ transport security parameters (TLS) are configured in the +`ingress` section. InfluxDB can work with any certificate signed with any +Certificate Authority (accepting that CA is then a matter of InfluxDB client's +configuration, outside of the scope of this document). + +_Egress_ connections to TLS secured endpoints (`https` or TLS secured postgres) +are verified by a set of built-in certificate authorities (we use Debian's +[ca-certificates](https://packages.debian.org/stable/ca-certificates)). + +You may need to override the list of accepted CAs if your InfluxDB cluster is +configured to access dependencies that use certificates issued by your private CA. +In some cases your network setup may even involve an auditing MitM proxy that +issues their own certificates. + +This release includes an optional feature that allows you to specify your own CA +list. The custom CA replaces the standard set of CA certificates. The custom +certificate file can contain one or more PEM encoded CA certificates. + + + +```bash +kubectl -n influxdb create configmap custom-ca --from-file=ca.pem +``` + +```yaml +.... +kind: AppInstance +spec: + ... + spec: + ... + egress: + customCertificates: + valueFrom: + configMapKeyRef: + key: ca.pem + name: custom-ca + ... +``` + +### Changes + +#### Deployment + +- Allow users to specify custom certificate authorities for egress calls. + +#### Database engine + +- Fix health probe livelock. +- Handle oversized files in the compactor. +- Various minor optimizations. + +--- + +## 20230911-604209 {date="2023-09-11"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230911-604209 +``` + +### Highlights + +This release contains a breaking change to the monitoring subsystem that +requires manual intervention to unblock. +More details in the Upgrade notes section below. + +### Upgrade notes + +#### Prometheus StatefulSet + +This release contains a change to the prometheus `StatefulSet` resources that +cannot be reconciled automatically by the operator. +You must delete the stateful set manually. +The operator will then automatically re-create the resources. + + + +```bash +kubectl -n influxdb delete sts prometheus +``` + +### Changes + +#### Documentation + +- Update active directory documentation. + +#### Deployment + +- Set `serviceName` in Prometheus deployment. +- Ensure granite ingress has hostname declared. + +#### Database engine + +- Various dependency updates. +- Adjust compactor catalog query rate limiter for small clusters. + +--- + +## 20230908-600131 {date="2023-09-08"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230908-600131 +``` + +### Highlights + +#### Default storage class + +The `storageClassName` parameters are no longer required. +InfluxDB uses the cluster's default storage class unless you override it in your +configuration. + +### Changes + +#### Deployment + +- Remove unnecessary Grafana dashboards. +- Make storage class optional. + +--- + +## 20230907-597343 {date="2023-09-07"} + +### Quickstart + +```yaml +spec: + package: + image: us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:20230907-597343 +``` + +### Upgrade Notes + +This release requires a new configuration block: + +```yaml +monitoringStorage: + storage: 1Gi + storageClassName: +``` + +### Changes + +#### Deployment + +- Make gRPC ingress work with the Traefik ingress controller. +- Add `hosts` field to ingress specification. +- Several fixes in ingress layer for the admin control plane. + +#### Database engine + +- Add support for `FILL(linear)` for selector functions in InfluxQL. +- Prevent sort order mismatches from creating overlapping chains. +- Minor performance optimizations. +- Change `loglevel` to `info` on "No compaction job found" errors. diff --git a/content/influxdb/clustered/reference/release-notes/influxctl.md b/content/influxdb/clustered/reference/release-notes/influxctl.md index ca796a532..4dd477b77 100644 --- a/content/influxdb/clustered/reference/release-notes/influxctl.md +++ b/content/influxdb/clustered/reference/release-notes/influxctl.md @@ -12,11 +12,53 @@ weight: 202 canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ --- +## v2.9.8 {date="2024-10-15"} + +### Bug Fixes + +- Continue revoking tokens on error. +- Reject unsupported input to `--template-timeformat`. +- Remove unused `client_secret` option from + [connection configuration profiles](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles). + +### Dependency Updates + +- Update Go to v1.23.2. +- Update `github.com/jedib0t/go-pretty/v6` from 6.5.9 to 6.6.0. +- Update `github.com/urfave/cli/v2` from 2.27.4 to 2.27.5. +- Update `google.golang.org/grpc` from 1.66.0 to 1.67.1. +- Update `google.golang.org/protobuf` from 1.34.2 to 1.35.1. + +--- + +## v2.9.7 {date="2024-09-11"} + +### Features + +- Add [global `--timeout` flag](/influxdb/clustered/reference/cli/influxctl/#global-flags). +- Improve timezone support. + +### Bug Fixes + +- Use passthrough resolver for gRPC. + +### Dependency Updates + +- Update Go to 1.23.1. +- Update `github.com/pelletier/go-toml/v2` from 2.2.2 to 2.2.3. +- Update `golang.org/x/mod` from 0.20.0 to 0.21.0. +- Update `golang.org/x/oauth2` from 0.22.0 to 0.23.0. +- Update `google.golang.org/grpc` from 1.65.0 to 1.66.0. + +--- + ## v2.9.6 {date="2024-08-15"} ### Bug Fixes -- Update query subcommand to wait for EOF on stdin instead of the first newline. +- Update query to wait for EOF on stdin instead of the first newline. + +--- ## v2.9.5 {date="2024-08-13"} @@ -31,6 +73,8 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update `golang.org/x/mod` from 0.19.0 to 0.20.0 - Update `golang.org/x/oauth2` from 0.21.0 to 0.22.0 +--- + ## v2.9.4 {date="2024-07-25"} ### Bug Fixes @@ -42,12 +86,16 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update `golang.org/x/mod` from 0.18.0 to 0.19.0 - Update `google.golang.org/grpc` from 1.64.0 to 1.65.0 +--- + ## v2.9.3 {date="2024-06-26"} ### Bug Fixes - Update query subcommand to safely handle null timestamp in response. +--- + ## v2.9.2 {date="2024-06-17"} ### Bug Fixes @@ -58,6 +106,8 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update `google.golang.org/protobuf` from 1.34.1 to 1.34.2. +--- + ## v2.9.1 {date="2024-06-06"} ### Dependency Updates @@ -71,6 +121,8 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update `google.golang.org/protobuf` from 1.34.0 to 1.34.1 - Update build dependencies. +--- + ## v2.9.0 {date="2024-05-06"} ### Features @@ -82,7 +134,7 @@ canonical: /influxdb/cloud-dedicated/reference/release-notes/influxctl/ - Update unimplemented error message with additional information. -### Dependecy Updates +### Dependency Updates - Update `github.com/apache/arrow/go/v16` from 16.0.0-20240401180149-68241d8a86e9 to 16.0.0. - Update `github.com/jedib0t/go-pretty/v6` from 6.5.8 to 6.5.9. @@ -197,7 +249,7 @@ associated with another InfluxDB cluster. ### Bug Fixes -- Update arrow to allow non-TLS connections. +- Update Arrow to allow non-TLS connections. - Do not attempt to load cached tokens when an admin token file is provided. - Print retention period up to days rather than very large hours. - Fix indentation of help output. diff --git a/content/influxdb/clustered/reference/sql/_index.md b/content/influxdb/clustered/reference/sql/_index.md index 713a95ac6..fd27fb044 100644 --- a/content/influxdb/clustered/reference/sql/_index.md +++ b/content/influxdb/clustered/reference/sql/_index.md @@ -6,693 +6,13 @@ menu: influxdb_clustered: name: SQL reference parent: Reference -weight: 141 +weight: 101 related: - /influxdb/clustered/reference/internals/arrow-flightsql/ + +source: /content/shared/sql-reference/_index.md --- -{{% product-name %}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. - -- [Identifiers](#identifiers) -- [Quoting and case sensitivity](#quoting-and-case-sensitivity) -- [Literals](#literals) -- [Duration units](#duration-units) -- [Operators](#operators) -- [Keywords](#keywords) -- [Conditional expressions](#conditional-expressions) -- [Statements and clauses](#statements-and-clauses) -- [Comments](#comments) -- [Functions](#functions) - -## Identifiers - -An identifier is a token which refers to the name of an InfluxDB database object, such as a **measurement** or a column name (**time**, **tag keys**, or **field keys**). - -## Quoting - -Use double quotes on [identifiers](#identifiers) to treat them as case-sensitive. -Use single quotes on string literals. - -General quoting guidelines: - -- Single quote RFC3339 and RFC3339-like time values. -- Do _not_ quote Unix epoch time values (integers cast to a timestamp). -- Double-quote mixed case, [camel case](https://en.wikipedia.org/wiki/Camel_case) or case-sensitive identifiers. -- Double-quote identifiers that contain special characters or whitespace characters. - -##### Quoting examples - -```sql --- Double-quote identifiers that contain whitespace -SELECT "water temperature", "buoy location" FROM buoy - --- Double-quote measurement names with special characters -SELECT * FROM "h2o-temperature" - --- Double-quote identifiers that should be treated as case-sensitive -SELECT "pH" FROM "Water" -``` - -{{% note %}} -**Note:** We recommend always double-quoting identifiers, regardless of case-sensitivity. -{{% /note %}} - - -Unquoted identifiers **are not** case-sensitive and match any measurement, tag key, or field key with the same characters, despite case. -For example, if you have two fields in a measurement named `ph` and `pH`, the unquoted identifier, `pH` will match both. -To query in a case-sensitive manner, double-quote identifiers. - -## Literals - -A literal is an explicit value not represented by an identifier. - -### String literals - -String literals are surrounded by single quotes. - -```sql -'santa_monica' -'pH' -'average temperature' -``` - -### Numeric literals - -Number literals are positive or negative numbers that are either exact numbers or floats. - -```sql --- Integers -10 -+10 --10 - --- Unsigned integers -10::BIGINT UNSIGNED -+10::BIGINT UNSIGNED - --- Floats -10.78654 --100.56 -``` - -### Date and time literals - -The following date and time literals are supported: - -```sql -'2022-01-31T06:30:30.123Z' -- (RFC3339) -'2022-01-31T06:30:30.123' -- (RFC3339-like) -'2022-01-31 06:30:30.123' -- (RFC3339-like) -'2022-01-31 06:30:30' -- ((RFC3339-like, no fractional seconds) -1643610630123000000::TIMESTAMP -- (Unix epoch nanosecond cast to a timestamp) -``` - -### Boolean literals - -Boolean literals are either `TRUE` or `FALSE`. - -## Duration units - -Interval literals specify a length or unit of time. - -```sql -INTERVAL '4 minutes' -INTERVAL '12 days 6 hours 30 minutes' -``` - -The following units of time are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks -- months -- years -- century - -## Operators - -Operators are reserved words or characters which perform certain operations, including comparisons and arithmetic. - -### Arithmetic operators - -Arithmetic operators take two numeric values (either literals or variables) and -perform a calculation that returns a single numeric value. - -| Operator | Description | Example | Result | -| :------: | :------------- | ------- | -----: | -| `+` | Addition | `2 + 2` | `4` | -| `-` | Subtraction | `4 - 2` | `2` | -| `*` | Multiplication | `2 * 3` | `6` | -| `/` | Division | `6 / 3` | `2` | -| `%` | Modulo | `7 % 2` | `1` | - -### Comparison operators - -Comparison operators evaluate the relationship between the left and right operands and `TRUE` or `FALSE`. - -| Operator | Meaning | Example | -| :------: | :------------------------------------------------------- | :----------------- | -| `=` | Equal to | `123 = 123` | -| `<>` | Not equal to | `123 <> 456` | -| `!=` | Not equal to | `123 != 456` | -| `>` | Greater than | `3 > 2` | -| `>=` | Greater than or equal to | `3 >= 2` | -| `<` | Less than | `1 < 2` | -| `<=` | Less than or equal to | `1 <= 2` | -| `~` | Matches a regular expression | `'abc' ~ 'a.*'` | -| `~\*` | Matches a regular expression _(case-insensitive)_ | `'Abc' ~\* 'A.*'` | -| `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | -| `!~\*` | Does not match a regular expression _(case-insensitive)_ | `'Abc' !~\* 'a.*'` | - -### Logical operators - -| Operator | Meaning | -| :-------: | :------------------------------------------------------------------------- | -| `AND` | Returns true if both operands are true. Otherwise, returns false. | -| `BETWEEN` | Returns true if the left operand is within the range of the right operand. | -| `EXISTS` | Returns true if the operand is not null. | -| `IN` | Returns true if the left operand is in the right operand list. | -| `LIKE` | Returns true if the left operand matches the right operand pattern string. | -| `NOT` | Negates the subsequent expression. | -| `OR` | Returns true if any operand is true. Otherwise, returns false. | - -### Bitwise operators - -Bitwise operators perform bitwise operations on bit patterns or binary numerals. - -| Operator | Meaning | Example | Result | -| :------: | :------------------ | :------- | -----: | -| `&` | Bitwise and | `5 & 3` | `1` | -| `\|` | Bitwise or | `5 \| 3` | `7` | -| `^` | Bitwise xor | `5 ^ 3` | `6` | -| `>>` | Bitwise shift right | `5 >> 3` | `0` | -| `<<` | Bitwise shift left | `5 << 3` | `40` | - -### Other operators - -| Operator | Meaning | Example | Result | -| :------------: | :----------------------- | :-------------------------------------------------------------------------------- | :------------ | -| `\|\|` | Concatenates strings | `'Hello' \|\| ' world'` | `Hello world` | -| `AT TIME ZONE` | Apply a time zone offset | _[View example](/influxdb/clustered/reference/sql/operators/other/#at-time-zone)_ | | - -## Keywords - -The following reserved keywords cannot be used as identifiers. - -```sql -AND -ALL -ANALYZE -AS -ASC -AT TIME ZONE -BETWEEN -BOTTOM -CASE -DESC -DISTINCT -EXISTS -EXPLAIN -FROM -GROUP BY -HAVING -IN -INNER JOIN -JOIN -LEFT JOIN -LIKE -LIMIT -NOT -EXISTS -NOT IN -OR -ORDER BY -FULL OUTER JOIN -RIGHT JOIN -SELECT -TOP -TYPE -UNION -UNION ALL -WHERE -WITH -``` - -## Conditional expressions - -Conditional expressions evaluate conditions based on input values. -The following conditional expressions are supported: - -| Expression | Description | -| :--------- | :----------------------------------------------------------------- | -| CASE | Allows for use of WHEN-THEN-ELSE statements. | -| COALESCE | Returns the first non-NULL expression in a specified list. | -| NULLIF | Returns a NULL value if value1 = value2. Otherwise returns value1. | - -## Statements and clauses - -InfluxDB SQL supports the following basic syntax for queries: - -```sql -[ WITH with_query [, …] ] -SELECT [ ALL | DISTINCT ] select_expr [, …] -[ FROM from_item [, …] ] -[ JOIN join_item [, …] ] -[ WHERE condition ] -[ GROUP BY grouping_element [, …] ] -[ HAVING condition] -[ UNION [ ALL ] ] -[ ORDER BY expression [ ASC | DESC ][, …] ] -[ LIMIT count ] -``` - -### SELECT statement and FROM clause - -Use the SQL `SELECT` statement to query data from a specific measurement or measurements. The `FROM` clause always accompanies the `SELECT` statement. - -#### Examples - -```sql -SELECT * FROM "h2o_feet" -``` - -### WHERE clause - -Use the `WHERE` clause to filter results based on `fields`, `tags`, and `timestamps`. -Use predicates to evaluate each row. -Rows that evaluate as `TRUE` are returned in the result set. -Rows that evaluate as `FALSE` are omitted from the result set. - -#### Examples - -```sql -SELECT * FROM "h2o_feet" WHERE "water_level" <= 9 -``` - -```sql -SELECT - * -FROM - "h2o_feet" -WHERE - "location" = 'santa_monica' - AND "level description" = 'below 3 feet' -``` - -### JOIN clause - -Use the `JOIN` clause to join data from multiple measurements (tables). -For more information about joins, see -[JOIN clause](/influxdb/clustered/reference/sql/join/). -The following join types are supported: - -{{< flex >}} -{{< flex-content "quarter" >}} - -

INNER JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="inner small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

LEFT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="left small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

RIGHT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="right small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

FULL [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="full small center" >}} -
-{{< /flex-content >}} -{{< /flex >}} - -{{< expand-wrapper >}} -{{% expand "INNER JOIN" %}} - -Inner joins combine rows from tables on the left and right side of the join -based on common column values defined in the `ON` clause. Rows that don't have -matching column values are not included in the output table. - -```sql -SELECT - * -FROM - home -INNER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "LEFT [OUTER] JOIN" %}} - -A left outer join returns all rows from the left side of the join and only -returns data from the right side of the join in rows with matching column values -defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -LEFT OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "RIGHT [OUTER] JOIN" %}} - -A right outer join returns all rows from the right side of the join and only -returns data from the left side of the join in rows with matching column values -defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -RIGHT OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` - -{{% /expand %}} -{{% expand "FULL [OUTER] JOIN" %}} - -A full outer join returns all data from the left and right sides of the join and -combines rows with matching column values defined in the `ON` clause. - -```sql -SELECT - * -FROM - home -FULL OUTER JOIN home_actions ON - home.room = home_actions.room - AND home.time = home_actions.time; -``` -{{% /expand %}} -{{< /expand-wrapper >}} - -### GROUP BY clause - -Use the `GROUP BY` clause to group query results based on specified column values. `GROUP BY` **requires** an aggregate or selector function in the `SELECT` statement. - -#### Examples - -```sql -SELECT - MEAN("water_level"), - "location" -FROM - "h2o_feet" -GROUP BY - "location" -``` - -### HAVING clause - - Use the `HAVING` clause to filter query results based on a specified condition. - The `HAVING` clause must _follow_ the `GROUP BY` clause, but _precede_ the `ORDER BY` clause. - -#### Examples - -```sql -SELECT - MEAN("water_level"), - "location" -FROM - "h2o_feet" -GROUP BY - "location" -HAVING - MEAN("water_level") > 4 -ORDER BY - "location" -``` - -### UNION clause - -The `UNION` clause combines the results of two or more `SELECT` statements without returning any duplicate rows. `UNION ALL` returns all results, including duplicates. - -#### Examples - -```sql -SELECT - 'pH' -FROM - "h2o_pH" -UNION ALL -SELECT - "location" -FROM - "h2o_quality" -``` - -### ORDER BY clause - -The `ORDER BY` clause orders results by specified columns and order. -Sort data based on fields, tags, and timestamps. -The following orders are supported: - -- `ASC`: ascending _(default)_ -- `DESC`: descending - -#### Examples - -```sql -SELECT - "water_level", - "location" -FROM - "h2o_feet" -ORDER BY - "location", - "time" DESC -``` - -### LIMIT clause - -The `LIMIT` clause limits the number of rows to return. -The defined limit should be a non-negative integer. - -#### Examples - -```sql -SELECT - "water_level", - "location" -FROM - "h2o_feet" -LIMIT - 10 -``` - -### WITH clause - -The `WITH` clause provides a way to write auxiliary statements for use in a larger query. -It can help break down large, complicated queries into simpler forms. - -```sql -WITH summary_data as -(SELECT degrees, location, time - FROM average_temperature) -SELECT * FROM summary_data -``` - -### OVER clause - -The `OVER` clause is used with SQL window functions. -A **window function** performs a calculation across a set of table rows that are related in some way to the current row. - While similar to aggregate functions, window functions output results into rows retaining their separate identities. - -```sql -SELECT - time, - water_level -FROM - ( - SELECT - time, - "water_level", - row_number() OVER ( - ORDER BY - water_level desc - ) as rn - FROM - h2o_feet - ) -WHERE - rn <= 3; -``` - -## Comments - -Use comments to describe and add detail or notes to your queries. - -- Single line comments use the double hyphen `--` symbol. Single line comments end with a line break. -- Multi-line comments begin with `/*` and end with ` */`. - -```sql --- Single-line comment - -/* - * Multi-line comment - */ -``` - -## Schema information - -{{% product-name %}} supports the following metadata schema queries: - -```sql -SHOW tables - -SHOW columns FROM -``` - -## Functions - -Following is a list of supported functions by type. - -### Aggregate functions - -An aggregate function performs a calculation or computation on a set of data values in a column and returns a single value. - -| Function | Description | -| :------- | :--------------------------------------------------------- | -| COUNT() | Returns returns the number of rows from a field or tag key | -| AVG() | Returns the average value of a column | -| SUM() | Returns the summed value of a column | -| MEAN() | Returns the mean value of a column | -| MIN() | Returns the smallest value of the selected column | -| MAX() | Returns the largest value of the selected column | - -#### Examples - -```sql - -SELECT COUNT("water_level") -FROM "h2o_feet" - -SELECT AVG("water_level"), "location" -FROM "h2o_feet" -GROUP BY "location" - -SELECT SUM("water_level"), "location" -FROM "h2o_feet" -GROUP BY "location" -``` - -### Selector functions - -Selector functions are unique to InfluxDB. They behave like aggregate functions in that they take a row of data and compute it down to a single value. -However, selectors are unique in that they return a **time value** in addition to the computed value. In short, selectors return an aggregated value along with a timestamp. - -| Function | Description | -| :--------------- | :-------------------------------------------------------------- | -| SELECTOR_FIRST() | Returns the first value of a selected column and timestamp. | -| SELECTOR_LAST() | Returns the last value of a selected column and timestamp. | -| SELECTOR_MIN() | Returns the smallest value of a selected column and timestamp. | -| SELECTOR_MAX() | Returns the largest value of a selected column and timestamp. | - -#### Examples - -```sql -SELECT -SELECTOR_MAX("pH", time)['value'], -SELECTOR_MAX("pH", time)['time'] -FROM "h2o_pH" - -SELECT -SELECTOR_LAST("water_level", time)['value'], -SELECTOR_LAST("water_level", time)['time'] -FROM "h2o_feet" -WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19T00:00:00Z' - -``` - -### Date and time functions - -| Function | Description | -| :----------- | :---------------------------------------------------------------------------------------------- | -| DATE_BIN() | Bins the input timestamp into a specified interval. | -| DATE_TRUNC() | Truncates a timestamp expression based on the date part specified, such as hour, day, or month. | -| DATE_PART() | Returns the specified part of a date. | -| NOW() | Returns the current time (UTC). | - -#### Examples - -```sql -SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z'::timestamp) AS "_time", -SUM(water_level) -FROM "h2o_feet" -GROUP BY "_time" -``` - -```sql -SELECT DATE_TRUNC('month',time) AS "date", -SUM(water_level) -FROM "h2o_feet" -GROUP BY time -``` - -### Approximate functions - -| Function | Description | -| :--------------------------------- | :-------------------------------------------------------------------------------------------- | -| APPROX_MEDIAN | Returns the approximate median of input values. | -| APPROX_DISTINCT | Returns the approximate count of the number of distinct values. Implemented only for strings. | -| APPROX_PERCENTILE_CONT | Returns the approximate percentile of input values. | -| APPROX_PERCENTILE_CONT_WITH_WEIGHT | Returns the approximate percentile of input values with weight. | - -### Math functions - -| Function | Description | -| :------- | :------------------------------------------------------------------------------- | -| ABS() | Absolute value | -| ACOS() | Inverse cosine | -| ASIN() | Inverse sine | -| ATAN() | Inverse tangent | -| ATAN2() | Inverse tangent of y / x | -| CEIL() | Returns the smallest integer value greater than or equal to the specified number | -| COS() | Cosine | -| EXP() | Exponential | -| FLOOR() | Nearest integer less than or equal to the specified number | -| LN() | Natural logarithm | -| LOG10() | Base 10 logarithm | -| LOG2() | Base 2 logarithm | -| POWER() | Returns the value of a number raised to the power of the number | -| ROUND() | Round to the nearest integer | -| SIGNUM() | Sign of the argument (-1, 0, +1) | -| SINE() | Sine | -| SQRT() | Returns the square root of a number | -| TAN() | Tangent | -| TRUNC() | Truncates a number to the specified number of decimal places | - -### Conditional functions - -| Function | Description | -| :------- | :--------------------------------------------------------------------------------------------------------- | -| COALESCE | Returns the first argument that is not null. If all arguments are null, then `COALESCE` will return nulls. | -| NULLIF | Returns a null value if value1 equals value2, otherwise returns value1. | - -### Regular expression functions - -| Function | Description | -| :------------- | :---------------------------------------------------------------------------- | -| REGEXP_MATCH | Matches a regular expression against a string and returns matched substrings. | -| REGEXP_REPLACE | Replaces substrings that match a regular expression by a new substring. | + diff --git a/content/influxdb/clustered/reference/sql/data-types.md b/content/influxdb/clustered/reference/sql/data-types.md index bcd987f17..31ec2c0f3 100644 --- a/content/influxdb/clustered/reference/sql/data-types.md +++ b/content/influxdb/clustered/reference/sql/data-types.md @@ -11,207 +11,10 @@ menu: weight: 200 related: - /influxdb/clustered/query-data/sql/cast-types/ + +source: /content/shared/sql-reference/data-types.md --- -InfluxDB Clustered uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. -Data types define the type of values that can be stored in table columns. -In InfluxDB's SQL implementation, a **measurement** is structured as a table, -and **tags**, **fields** and **timestamps** are exposed as columns. - -DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. -Data types stored in InfluxDB's storage engine are mapped to SQL data types at query time. - -{{% note %}} -When performing casting operations, cast to the **name** of the data type, not the actual data type. -Names and identifiers in SQL are _case-insensitive_ by default. For example: - -```sql -SELECT - '99'::BIGINT, - '2019-09-18T00:00:00Z'::timestamp -``` - -{{% /note %}} - -- [String types](#string-types) -- [Numeric types](#numeric-types) - - [Integers](#integers) - - [Unsigned integers](#unsigned-integers) - - [Floats](#floats) -- [Date and time data types](#date-and-time-data-types) - - [Timestamp](#timestamp) - - [Interval](#interval) -- [Boolean types](#boolean-types) -- [Unsupported SQL types](#unsupported-sql-types) -- [Data types compatible with parameters](#data-types-compatible-with-parameters) - -## String types - -| Name | Data type | Description | -| :------ | :-------- | --------------------------------- | -| STRING | UTF8 | Character string, variable-length | -| CHAR | UTF8 | Character string, fixed-length | -| VARCHAR | UTF8 | Character string, variable-length | -| TEXT | UTF8 | Variable unlimited length | - -##### Example string literals - -```sql -'abcdefghijk' -'time' -'h2o_temperature' -``` - -## Numeric types - -The following numeric types are supported: - -| Name | Data type | Description | -| :-------------- | :-------- | :--------------------------- | -| BIGINT | INT64 | 64-bit signed integer | -| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | -| DOUBLE | FLOAT64 | 64-bit floating-point number | - -### Integers - -InfluxDB SQL supports the 64-bit signed integers: - -**Minimum signed integer**: `-9223372036854775808` -**Maximum signed integer**: `9223372036854775807` - -##### Example integer literals - -```sql -234 --446 -5 -``` - -### Unsigned integers - -InfluxDB SQL supports the 64-bit unsigned integers: - -**Minimum unsigned integer**: `0` -**Maximum unsigned integer**: `18446744073709551615` - -##### Example unsigned integer literals - -Unsigned integer literals are comprised of an integer cast to the `BIGINT UNSIGNED` type: - -```sql -234::BIGINT UNSIGNED -458374893::BIGINT UNSIGNED -5::BIGINT UNSIGNED -``` - -### Floats - -InfluxDB SQL supports the 64-bit double floating point values. -Floats can be a decimal point, decimal integer, or decimal fraction. - -##### Example float literals - -```sql -23.8 --446.89 -5.00 -0.033 -``` - -## Date and time data types - -InfluxDB SQL supports the following DATE/TIME data types: - -| Name | Data type | Description | -| :-------- | :-------- | :------------------------------------------------------------------- | -| TIMESTAMP | TIMESTAMP | TimeUnit::Nanosecond, None | -| INTERVAL | INTERVAL | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) | - -### Timestamp - -A time type is a single point in time using nanosecond precision. - -The following date and time formats are supported: - -```sql -YYYY-MM-DDT00:00:00.000Z -YYYY-MM-DDT00:00:00.000-00:00 -YYYY-MM-DD 00:00:00.000-00:00 -YYYY-MM-DDT00:00:00Z -YYYY-MM-DD 00:00:00.000 -YYYY-MM-DD 00:00:00 -``` - -##### Example timestamp literals - -```sql -'2023-01-02T03:04:06.000Z' -'2023-01-02T03:04:06.000-00:00' -'2023-01-02 03:04:06.000-00:00' -'2023-01-02T03:04:06Z' -'2023-01-02 03:04:06.000' -'2023-01-02 03:04:06' -``` - -### Interval - -The INTERVAL data type can be used with the following precision: - -- nanosecond -- microsecond -- millisecond -- second -- minute -- hour -- day -- week -- month -- year -- century - -##### Example interval literals -```sql -INTERVAL '10 minutes' -INTERVAL '1 year' -INTERVAL '2 days 1 hour 31 minutes' -``` - -## Boolean types - -Booleans store TRUE or FALSE values. - -| Name | Data type | Description | -| :------ | :-------- | :------------------- | -| BOOLEAN | BOOLEAN | True or false values | - -##### Example boolean literals - -```sql -true -TRUE -false -FALSE -``` - -## Unsupported SQL types - -The following SQL types are not currently supported: - -- UUID -- BLOB -- CLOB -- BINARY -- VARBINARY -- REGCLASS -- NVARCHAR -- CUSTOM -- ARRAY -- ENUM -- SET -- DATETIME -- BYTEA - -## Data types compatible with parameters - -For information about data types that can be substituted by parameters, -see how to [use parameterized queries with SQL](/influxdb/clustered/query-data/sql/parameterized-queries/). + diff --git a/content/influxdb/clustered/reference/sql/explain.md b/content/influxdb/clustered/reference/sql/explain.md index c0d602149..3cad7aebb 100644 --- a/content/influxdb/clustered/reference/sql/explain.md +++ b/content/influxdb/clustered/reference/sql/explain.md @@ -11,113 +11,10 @@ related: - /influxdb/clustered/reference/internals/query-plan/ - /influxdb/clustered/query-data/execute-queries/analyze-query-plan/ - /influxdb/clustered/query-data/execute-queries/troubleshoot/ + +source: /content/shared/sql-reference/explain.md --- -The `EXPLAIN` command returns the [logical plan](/influxdb/clustered/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb/clustered/reference/internals/query-plan/#physical-plan) for the -specified SQL statement. - -```sql -EXPLAIN [ANALYZE] [VERBOSE] statement -``` - -- [`EXPLAIN`](#explain) - - [Example `EXPLAIN`](#example-explain) -- [`EXPLAIN ANALYZE`](#explain-analyze) - - [Example `EXPLAIN ANALYZE`](#example-explain-analyze) -- [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose) - - [Example `EXPLAIN ANALYZE VERBOSE`](#example-explain-analyze-verbose) - -## `EXPLAIN` - -Returns the logical plan and physical (execution) plan of a statement. -To output more details, use `EXPLAIN VERBOSE`. - -`EXPLAIN` doesn't execute the statement. -To execute the statement and view runtime metrics, use [`EXPLAIN ANALYZE`](#explain-analyze). - -### Example `EXPLAIN` - -```sql -EXPLAIN -SELECT - room, - avg(temp) AS temp -FROM home -GROUP BY room -``` - -{{< expand-wrapper >}} -{{% expand "View `EXPLAIN` example output" %}} - -| | plan_type | plan | -|---:|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 0 | logical_plan | Projection: home.room, AVG(home.temp) AS temp | -| | | Aggregate: groupBy=[[home.room]], aggr=[[AVG(home.temp)]] | -| | | TableScan: home projection=[room, temp] | -| 1 | physical_plan | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp] | -| | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)] | -| | | CoalesceBatchesExec: target_batch_size=8192 | -| | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8 | -| | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)] | -| | | ParquetExec: file_groups={8 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet, 70434/116281/b7a9e7c57fbfc3bba9427e4b3e35c89e001e2e618b0c7eb9feb4d50a3932f4db/d29370d4-262f-0d32-2459-fe7b099f682f.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], ...]}, projection=[room, temp] | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `EXPLAIN ANALYZE` - -Executes a statement and returns the execution plan and runtime metrics of the statement. -The report includes the [logical plan](/influxdb/clustered/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb/clustered/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution. - -If the plan requires reading lots of data files, `EXPLAIN` and `EXPLAIN ANALYZE` may truncate the list of files in the report. -To output more information, including intermediate plans and paths for all scanned Parquet files, use [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose). - -### Example `EXPLAIN ANALYZE` - -```sql -EXPLAIN ANALYZE -SELECT - room, - avg(temp) AS temp -FROM home -WHERE time >= '2023-01-01' AND time <= '2023-12-31' -GROUP BY room -``` - -{{< expand-wrapper >}} -{{% expand "View `EXPLAIN ANALYZE` example output" %}} - -| | plan_type | plan | -|---:|:------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 0 | Plan with Metrics | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp], metrics=[output_rows=2, elapsed_compute=4.768µs] | -| | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=140.405µs] | -| | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=2, elapsed_compute=6.821µs] | -| | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=2, elapsed_compute=18.408µs, repart_time=59.698µs, fetch_time=1.057882762s, send_time=5.83µs] | -| | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=137.577µs] | -| | | RepartitionExec: partitioning=RoundRobinBatch(8), input_partitions=6, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=46, elapsed_compute=26.637µs, repart_time=6ns, fetch_time=399.971411ms, send_time=6.658µs] | -| | | ProjectionExec: expr=[room@0 as room, temp@2 as temp], metrics=[output_rows=46, elapsed_compute=3.102µs] | -| | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=46, elapsed_compute=25.585µs] | -| | | FilterExec: time@1 >= 1672531200000000000 AND time@1 <= 1703980800000000000, metrics=[output_rows=46, elapsed_compute=26.51µs] | -| | | ParquetExec: file_groups={6 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], ...]}, projection=[room, time, temp], output_ordering=[room@0 ASC, time@1 ASC], predicate=time@6 >= 1672531200000000000 AND time@6 <= 1703980800000000000, pruning_predicate=time_max@0 >= 1672531200000000000 AND time_min@1 <= 1703980800000000000, required_guarantees=[], metrics=[output_rows=46, elapsed_compute=6ns, predicate_evaluation_errors=0, bytes_scanned=3279, row_groups_pruned_statistics=0, file_open_errors=0, file_scan_errors=0, pushdown_rows_filtered=0, num_predicate_creation_errors=0, row_groups_pruned_bloom_filter=0, page_index_rows_filtered=0, time_elapsed_opening=398.462968ms, time_elapsed_processing=1.626106ms, time_elapsed_scanning_total=1.36822ms, page_index_eval_time=33.474µs, pushdown_eval_time=14.267µs, time_elapsed_scanning_until_data=1.27694ms] | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `EXPLAIN ANALYZE VERBOSE` - -Executes a statement and returns the execution plan, runtime metrics, and additional details helpful for debugging the statement. - -The report includes the following: - -- the [logical plan](/influxdb/clustered/reference/internals/query-plan/#logical-plan) -- the [physical plan](/influxdb/clustered/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution -- Information truncated in the `EXPLAIN` report--for example, the paths for all [Parquet files retrieved for the query](/influxdb/clustered/reference/internals/query-plan/#file_groups). -- All intermediate physical plans that DataFusion and the [Querier](/influxdb/clustered/reference/internals/storage-engine/#querier) generate before generating the final physical plan--helpful in debugging to see when an [`ExecutionPlan` node](/influxdb/clustered/reference/internals/query-plan/#executionplan-nodes) is added or removed, and how InfluxDB optimizes the query. - -### Example `EXPLAIN ANALYZE VERBOSE` - -```SQL -EXPLAIN ANALYZE VERBOSE SELECT temp FROM home -WHERE time >= now() - INTERVAL '7 days' AND room = 'Kitchen' -ORDER BY time -``` + diff --git a/content/influxdb/clustered/reference/sql/functions/_index.md b/content/influxdb/clustered/reference/sql/functions/_index.md index a44883c00..80b101381 100644 --- a/content/influxdb/clustered/reference/sql/functions/_index.md +++ b/content/influxdb/clustered/reference/sql/functions/_index.md @@ -9,6 +9,10 @@ menu: parent: SQL reference identifier: sql-functions weight: 220 + +source: /content/shared/sql-reference/functions/_index.md --- -{{< children >}} \ No newline at end of file + \ No newline at end of file diff --git a/content/influxdb/clustered/reference/sql/functions/aggregate.md b/content/influxdb/clustered/reference/sql/functions/aggregate.md index cfb540391..cc5b665c5 100644 --- a/content/influxdb/clustered/reference/sql/functions/aggregate.md +++ b/content/influxdb/clustered/reference/sql/functions/aggregate.md @@ -10,1459 +10,10 @@ menu: weight: 301 related: - /influxdb/clustered/query-data/sql/aggregate-select/ + +source: /content/shared/sql-reference/functions/aggregate.md --- -SQL aggregate functions aggregate values in a specified column for each -group or SQL partition and return a single row per group containing the -aggregate value. - -- [General aggregate functions](#general-aggregate-functions) - - [array_agg](#array_agg) - - [avg](#avg) - - [bit_and](#bit_and) - - [bit_or](#bit_or) - - [bit_xor](#bit_xor) - - [bool_and](#bool_and) - - [bool_or](#bool_or) - - [count](#count) - - [first_value](#first_value) - - [last_value](#last_value) - - [max](#max) - - [mean](#mean) - - [median](#median) - - [min](#min) - - [sum](#sum) -- [Statistical aggregate functions](#statistical-aggregate-functions) - - [corr](#corr) - - [covar](#covar) - - [covar_pop](#covar_pop) - - [covar_samp](#covar_samp) - - [regr_avgx](#regr_avgx) - - [regr_avgy](#regr_avgy) - - [regr_count](#regr_count) - - [regr_intercept](#regr_intercept) - - [regr_r2](#regr_r2) - - [regr_slope](#regr_slope) - - [regr_sxx](#regr_sxx) - - [regr_syy](#regr_syy) - - [regr_sxy](#regr_sxy) - - [stddev](#stddev) - - [stddev_pop](#stddev_pop) - - [stddev_samp](#stddev_samp) - - [var](#var) - - [var_pop](#var_pop) - - [var_samp](#var_samp) -- [Approximate aggregate functions](#approximate-aggregate-functions) - - [approx_distinct](#approx_distinct) - - [approx_median](#approx_median) - - [approx_percentile_cont](#approx_percentile_cont) - - [approx_percentile_cont_with_weight](#approx_percentile_cont_with_weight) - ---- - -## General aggregate functions - -- [array_agg](#array_agg) -- [avg](#avg) -- [bit_and](#bit_and) -- [bit_or](#bit_or) -- [bit_xor](#bit_xor) -- [bool_and](#bool_and) -- [bool_or](#bool_or) -- [count](#count) -- [first_value](#first_value) -- [last_value](#last_value) -- [max](#max) -- [mean](#mean) -- [median](#median) -- [min](#min) -- [sum](#sum) - -### array_agg - -Returns an array created from the expression elements. - -{{% note %}} -`array_agg` returns a `LIST` arrow type which is not supported by InfluxDB. -To use with InfluxDB, use bracket notation to reference the index of an element -in the returned array. Arrays are 1-indexed. -{{% /note %}} - -```sql -array_agg(expression) -``` - -#### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `array_agg` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - array_agg(temp)[3] AS '3rd_temp' -FROM home -GROUP BY room -``` - -| room | 3rd_temp | -| :---------- | -------: | -| Kitchen | 22.7 | -| Living Room | 21.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### avg - -Returns the average of numeric values in the specified column. - -```sql -avg(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -##### Aliases - -- `mean` - -{{< expand-wrapper >}} -{{% expand "View `avg` query example" %}} - -```sql -SELECT - location, - avg(water_level) AS water_level_avg -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_avg | -| :----------- | -----------------: | -| coyote_creek | 5.359142420303919 | -| santa_monica | 3.5307120942458843 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_and - -Computes the bitwise `AND` of all non-null input values. - -```sql -bit_and(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_and` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_and(precip::BIGINT) AS precip_bit_and -FROM weather -GROUP BY location -``` - -| location | precip_bit_and | -| :------------ | -------------: | -| Concord | 0 | -| Hayward | 0 | -| San Francisco | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_or - -Computes the bitwise OR of all non-null input values. - -```sql -bit_or(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_or` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_or(precip::BIGINT) AS precip_bit_or -FROM weather -GROUP BY location -``` - -| location | precip_bit_or | -| :------------ | ------------: | -| Concord | 7 | -| Hayward | 7 | -| San Francisco | 7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bit_xor - -Computes the bitwise exclusive OR of all non-null input values. - -```sql -bit_xor(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bit_xor` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bit_xor(precip::BIGINT) AS precip_bit_xor -FROM weather -GROUP BY location -``` - -| location | precip_bit_xor | -| :------------ | -------------: | -| Concord | 4 | -| Hayward | 6 | -| San Francisco | 4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bool_and - -Returns `true` if _all_ non-null input values are `true`, otherwise returns `false`. - -```sql -bool_and(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bool_and` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bool_and(precip > 0) AS precip_bool_and -FROM weather -GROUP BY location -``` - -| location | precip_bool_and | -| :------------ | --------------: | -| Concord | false | -| Hayward | false | -| San Francisco | false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### bool_or - -Returns `true` if _any_ non-null input value is `true`, otherwise returns `false`. - -```sql -bool_or(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `bool_or` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - bool_or(precip > 0) AS precip_bool_or -FROM weather -GROUP BY location -``` - -| location | precip_bool_or | -| :------------ | -------------: | -| Concord | true | -| Hayward | true | -| San Francisco | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### count - -Returns the number of rows in the specified column. - -Count includes _null_ values in the total count. -To exclude _null_ values from the total count, include ` IS NOT NULL` -in the `WHERE` clause. - -```sql -count(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `count` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - count(precip) AS precip_count -FROM weather -GROUP BY location -``` - -| location | precip_count | -| :------------ | -----------: | -| Concord | 1094 | -| Hayward | 1096 | -| San Francisco | 1096 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### first_value - -Returns the first element in an aggregation group according to the specified ordering. -If no ordering is specified, returns an arbitrary element from the group. - -```sql -first_value(expression [ORDER BY expression]) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `first_value` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - first_value(temp_max ORDER BY time) AS temp_max_first_value -FROM weather -GROUP BY location -``` - -| location | temp_max_first_value | -| :------------ | -------------------: | -| Concord | 59 | -| Hayward | 57 | -| San Francisco | 66 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### last_value - -Returns the last element in an aggregation group according to the specified ordering. -If no ordering is specified, returns an arbitrary element from the group. - -```sql -last_value(expression [ORDER BY expression]) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `last_value` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - last_value(temp_max ORDER BY time) AS temp_max_last_value -FROM weather -GROUP BY location -``` - -| location | temp_max_last_value | -| :------------ | ------------------: | -| Concord | 59 | -| Hayward | 58 | -| San Francisco | 62 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### max - -Returns the maximum value in the specified column. - -```sql -max(expression) -``` - -_To return both the maximum value and its associated timestamp, use -[`selector_max`](/influxdb/clustered/reference/sql/functions/selector/#selector_max)._ - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `max` query example" %}} - -```sql -SELECT - location, - max(water_level) AS water_level_max -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_max | -| :----------- | --------------: | -| santa_monica | 7.205 | -| coyote_creek | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### mean - -_Alias of [avg](#avg)._ - -### median - -Returns the median value in the specified column. - -``` -median(expression) -``` - -#### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `median` query example" %}} - -```sql -SELECT - location, - median(water_level) AS water_level_max -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_median | -| :----------- | -----------------: | -| coyote_creek | 5.4645 | -| santa_monica | 3.471 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### min - -Returns the minimum value in the specified column. - -```sql -min(expression) -``` - -_To return both the minimum value and its associated timestamp, use -[`selector_max`](/influxdb/clustered/reference/sql/functions/selector/#selector_min)._ - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `min` query example" %}} - -```sql -SELECT - location, - min(water_level) AS water_level_min -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_min | -| :----------- | --------------: | -| coyote_creek | -0.61 | -| santa_monica | -0.243 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### sum - -Returns the sum of all values in the specified column. - -```sql -sum(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sum` query example" %}} - -```sql -SELECT - location, - sum(water_level) AS water_level_sum -FROM h2o_feet -GROUP BY location -``` - -| location | water_level_sum | -| :----------- | -----------------: | -| santa_monica | 27024.070369358 | -| coyote_creek | 40750.918963991004 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - -## Statistical aggregate functions - -- [corr](#corr) -- [covar](#covar) -- [covar_pop](#covar_pop) -- [covar_samp](#covar_samp) -- [regr_avgx](#regr_avgx) -- [regr_avgy](#regr_avgy) -- [regr_count](#regr_count) -- [regr_intercept](#regr_intercept) -- [regr_r2](#regr_r2) -- [regr_slope](#regr_slope) -- [regr_sxx](#regr_sxx) -- [regr_syy](#regr_syy) -- [regr_sxy](#regr_sxy) -- [stddev](#stddev) -- [stddev_pop](#stddev_pop) -- [stddev_samp](#stddev_samp) -- [var](#var) -- [var_pop](#var_pop) -- [var_samp](#var_samp) - -### corr - -Returns the coefficient of correlation between two numeric values. - -```sql -corr(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `corr` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - corr(hum, temp) AS correlation -FROM home -GROUP BY room -``` - -| room | correlation | -| :---------- | ------------------: | -| Living Room | 0.43665270457835725 | -| Kitchen | 0.6741766954929539 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar - -Returns the covariance of a set of number pairs. - -```sql -covar(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar(hum, temp) AS covar -FROM home -GROUP BY room -``` - -| room | covar | -| :---------- | ------------------: | -| Living Room | 0.03346153846153959 | -| Kitchen | 0.11134615384615432 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar_pop - -Returns the population covariance of a set of number pairs. - -```sql -covar_pop(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar_pop(hum, temp) AS covar_pop -FROM home -GROUP BY room -``` - -| room | covar_pop | -| :---------- | -------------------: | -| Kitchen | 0.10278106508875783 | -| Living Room | 0.030887573964498087 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### covar_samp - -Returns the sample covariance of a set of number pairs. - -```sql -covar_samp(expression1, expression2) -``` - -##### Arguments - -- **expression1**: First column or literal value to operate on. -- **expression2**: Second column or literal value to operate on. - -{{< expand-wrapper >}} -{{% expand "View `covar_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - covar_samp(hum, temp) AS covar_samp -FROM home -GROUP BY room -``` - -| room | covar_samp | -| :---------- | ------------------: | -| Kitchen | 0.11134615384615432 | -| Living Room | 0.03346153846153959 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_avgx - -Computes the average of the independent variable (input), `expression_x`, for the -non-null dependent variable, `expression_y`. - -```sql -regr_avgx(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_avgx` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_avgx(temp_min, temp_max) AS temp_regr_avgx -FROM weather -GROUP BY location -``` - -| location | temp_regr_avgx | -| :------------ | ----------------: | -| Concord | 75.54379562043796 | -| Hayward | 69.14808043875686 | -| San Francisco | 67.59945255474454 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_avgy - -Computes the average of the dependent variable (output), `expression_y`, for the -non-null dependent variable, `expression_y`. - -```sql -regr_avgy(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_avgy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_avgy(temp_min, temp_max) AS temp_regr_avgy -FROM weather -GROUP BY location -``` - -| location | temp_regr_avgy | -| :------------ | -----------------: | -| Concord | 50.153284671532845 | -| Hayward | 50.913162705667276 | -| San Francisco | 51.52372262773722 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_count - -Counts the number of non-null paired data points. - -```sql -regr_count(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_count` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_count(temp_min, temp_max) AS temp_regr_count -FROM weather -GROUP BY location -``` - -| location | temp_regr_count | -| :------------ | --------------: | -| Concord | 1096 | -| Hayward | 1094 | -| San Francisco | 1096 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_intercept - -Computes the y-intercept of the linear regression line. -For the equation `(y = kx + b)`, this function returns `b`. - -```sql -regr_intercept(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_intercept` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_intercept(temp_min, temp_max) AS temp_regr_intercept -FROM weather -GROUP BY location -``` - -| location | temp_regr_intercept | -| :------------ | ------------------: | -| Concord | 11.636281392206769 | -| Hayward | 12.876956842745152 | -| San Francisco | 19.125237647086607 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_r2 - -Computes the square of the correlation coefficient between the independent and -dependent variables. - -```sql -regr_r2(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_r2` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_r2(temp_min, temp_max) AS temp_regr_r2 -FROM weather -GROUP BY location -``` - -| location | temp_regr_r2 | -| :------------ | -----------------: | -| Concord | 0.6474628308450441 | -| Hayward | 0.5166296626320914 | -| San Francisco | 0.5032317511200297 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_slope - -Returns the slope of the linear regression line for non-null pairs in aggregate columns. -Given input column `Y` and `X`: `regr_slope(Y, X)` returns the slope -(`k` in `Y = k*X + b`) using minimal RSS fitting. - -``` sql -regr_slope(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Y expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: X expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_slope` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_slope(temp_min, temp_max) AS temp_regr_slope -FROM weather -GROUP BY location -``` - -| location | temp_regr_slope | -| :------------ | -----------------: | -| Concord | 0.5098632252058237 | -| Hayward | 0.5500688612261629 | -| San Francisco | 0.4792714105844738 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_sxx - -Computes the sum of squares of the independent variable. - -```sql -regr_sxx(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_sxx` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_sxx(temp_min, temp_max) AS temp_regr_sxx -FROM weather -GROUP BY location -``` - -| location | temp_regr_sxx | -| :------------ | -----------------: | -| Concord | 210751.89781021897 | -| Hayward | 99644.01096892142 | -| San Francisco | 77413.15967153282 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_syy - -Computes the sum of squares of the dependent variable. - -```sql -regr_syy(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_syy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_syy(temp_min, temp_max) AS temp_regr_syy -FROM weather -GROUP BY location -``` - -| location | temp_regr_syy | -| :------------ | -----------------: | -| Concord | 84618.24817518248 | -| Hayward | 58358.750457038404 | -| San Francisco | 35335.38321167884 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### regr_sxy - -Computes the sum of products of paired data points. - -```sql -regr_sxy(expression_y, expression_x) -``` - -#### Arguments - -- **expression_y**: Dependent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Independent variable. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `regr_sxy` query example" %}} - -_The following example uses the -[NOAA Bay Area weather data](/influxdb/clustered/reference/sample-data/#noaa-bay-area-weather-data)._ - -```sql -SELECT - location, - regr_sxy(temp_min, temp_max) AS temp_regr_sxy -FROM weather -GROUP BY location -``` - -| location | temp_regr_sxy | -| :------------ | -----------------: | -| Concord | 107454.64233576645 | -| Hayward | 54811.06764168191 | -| San Francisco | 37101.914233576645 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev - -Returns the standard deviation of a set of numbers. - -```sql -stddev(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev(co) AS stddev -FROM home -GROUP BY room -``` - -| room | stddev | -| :---------- | ----------------: | -| Living Room | 5.885662718931967 | -| Kitchen | 9.321879418735037 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev_pop - -Returns the population standard deviation of a set of numbers. - -```sql -stddev_pop(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev_pop(co) AS stddev_pop -FROM home -GROUP BY room -``` - -| room | stddev_pop | -| :---------- | ----------------: | -| Kitchen | 8.956172047894082 | -| Living Room | 5.654761830612032 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### stddev_samp - -Returns the sample standard deviation of a set of numbers. - -```sql -stddev_samp(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `stddev_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - stddev_samp(co) AS stddev_samp -FROM home -GROUP BY room -``` - -| room | stddev_samp | -| :---------- | ----------------: | -| Living Room | 5.885662718931967 | -| Kitchen | 9.321879418735037 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var - -Returns the statistical variance of a set of numbers. - -```sql -var(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var(co) AS var -FROM home -GROUP BY room -``` - -| room | var | -| :---------- | ----------------: | -| Living Room | 34.64102564102564 | -| Kitchen | 86.89743589743587 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var_pop - -Returns the statistical population variance of a set of numbers. - -```sql -var_pop(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var_pop` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var_pop(co) AS var_pop -FROM home -GROUP BY room -``` - -| room | var_pop | -| :---------- | -----------------: | -| Living Room | 31.976331360946745 | -| Kitchen | 80.21301775147927 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### var_samp - -Returns the statistical sample variance of a set of numbers. - -```sql -var_samp(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `var_samp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - var_samp(co) AS var_samp -FROM home -GROUP BY room -``` - -| room | var_samp | -| :---------- | ----------------: | -| Kitchen | 86.89743589743587 | -| Living Room | 34.64102564102564 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Approximate aggregate functions - -- [approx_distinct](#approx_distinct) -- [approx_median](#approx_median) -- [approx_percentile_cont](#approx_percentile_cont) -- [approx_percentile_cont_with_weight](#approx_percentile_cont_with_weight) - -### approx_distinct - -Returns the approximate number of distinct input values calculated using the -HyperLogLog algorithm. - -```sql -approx_distinct(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `approx_distinct` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_distinct(co::string) AS approx_distinct -FROM home -GROUP BY room -``` - -| room | approx_distinct | -| :---------- | --------------: | -| Living Room | 7 | -| Kitchen | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_median - -Returns the approximate median (50th percentile) of input values. -It is an alias of `approx_percentile_cont(x, 0.5)`. - -```sql -approx_median(expression) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `approx_median` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_median(temp) AS approx_median -FROM home -GROUP BY room -``` - -| room | approx_median | -| :---------- | ------------: | -| Kitchen | 22.7 | -| Living Room | 22.3 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_percentile_cont - -Returns the approximate percentile of input values using the t-digest algorithm. - -```sql -approx_percentile_cont(expression, percentile, centroids) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). -- **centroids**: Number of centroids to use in the t-digest algorithm. _Default is 100_. - - If there are this number or fewer unique values, you can expect an exact result. - A higher number of centroids results in a more accurate approximation, but - requires more memory to compute. - -{{< expand-wrapper >}} -{{% expand "View `approx_percentile_cont` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_percentile_cont(temp, 0.99) AS "99th_percentile" -FROM home -GROUP BY room -``` - -| room | 99th_percentile | -| :---------- | --------------: | -| Kitchen | 23.3 | -| Living Room | 22.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### approx_percentile_cont_with_weight - -Returns the weighted approximate percentile of input values using the -t-digest algorithm. - -```sql -approx_percentile_cont_with_weight(expression, weight, percentile) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **weight**: Expression to use as weight. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). - -{{< expand-wrapper >}} -{{% expand "View `approx_percentile_cont_with_weight` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - approx_percentile_cont_with_weight(temp, co, 0.99) AS "co_weighted_99th_percentile" -FROM home -GROUP BY room -``` - -| room | co_weighted_99th_percentile | -| :---------- | --------------------------: | -| Kitchen | 23.3 | -| Living Room | 22.8 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/functions/conditional.md b/content/influxdb/clustered/reference/sql/functions/conditional.md index 14a0da7b7..d24f94cb5 100644 --- a/content/influxdb/clustered/reference/sql/functions/conditional.md +++ b/content/influxdb/clustered/reference/sql/functions/conditional.md @@ -8,137 +8,10 @@ menu: name: Conditional parent: sql-functions weight: 306 + +source: /content/shared/sql-reference/functions/conditional.md --- -The InfluxDB SQL implementation supports the following conditional functions for -conditionally handling _null_ values: - -- [coalesce](#coalesce) -- [ifnull](#ifnull) -- [nullif](#nullif) -- [nvl](#nvl) - -## coalesce - -Returns the first of its arguments that is not _null_. -Returns _null_ if all arguments are _null_. -This function is often used to substitute a default value for _null_ values. - -```sql -coalesce(expression1[, ..., expression_n]) -``` - -##### Arguments - -- **expression1, expression_n**: - Expression to use if previous expressions are _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. - Pass as many expression arguments as necessary. - -{{< expand-wrapper >}} -{{% expand "View `coalesce` query example" %}} - -```sql -SELECT - val1, - val2, - val3, - coalesce(val1, val2, val3, 'quz') AS coalesce -FROM - (values ('foo', 'bar', 'baz'), - (NULL, 'bar', 'baz'), - (NULL, NULL, 'baz'), - (NULL, NULL, NULL) - ) data(val1, val2, val3) -``` - -| val1 | val2 | val3 | coalesce | -| :--: | :--: | :--: | :------: | -| foo | bar | baz | foo | -| | bar | baz | bar | -| | | baz | baz | -| | | | quz | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ifnull - -_Alias of [nvl](#nvl)._ - -## nullif - -Returns _null_ if _expression1_ equals _expression2_; otherwise it returns _expression1_. -This can be used to perform the inverse operation of [`coalesce`](#coalesce). - -```sql -nullif(expression1, expression2) -``` - -##### Arguments - -- **expression1**: Expression to compare and return if equal to expression2. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression2**: Expression to compare to expression1. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nullif` query example" %}} - -```sql -SELECT - value, - nullif(value, 'baz') AS nullif -FROM - (values ('foo'), - ('bar'), - ('baz') - ) data(value) -``` - -| value | nullif | -| :---- | :----- | -| foo | foo | -| bar | bar | -| baz | | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## nvl - -Returns _expression2_ if _expression1_ is _null_; otherwise it returns _expression1_. - -```sql -nvl(expression1, expression2) -``` - -##### Arguments - -- **expression1**: Return this expression if not _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression2**: Return this expression if _expression1_ is _null_. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nvl` query example" %}} - -```sql -SELECT - value, - nvl(value, 'baz') AS nvl -FROM - (values ('foo'), - ('bar'), - (NULL) - ) data(value) -``` - -| value | nvl | -| :---- | :-- | -| foo | foo | -| bar | bar | -| | baz | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/functions/math.md b/content/influxdb/clustered/reference/sql/functions/math.md index 26f9a38fb..7fa485117 100644 --- a/content/influxdb/clustered/reference/sql/functions/math.md +++ b/content/influxdb/clustered/reference/sql/functions/math.md @@ -8,1276 +8,10 @@ menu: name: Math parent: sql-functions weight: 306 + +source: /content/shared/sql-reference/functions/math.md --- -The InfluxDB SQL implementation supports the following math functions for -performing mathematic operations: - -- [abs](#abs) -- [acos](#acos) -- [acosh](#acosh) -- [asin](#asin) -- [asinh](#asinh) -- [atan](#atan) -- [atanh](#atanh) -- [atan2](#atan2) -- [cbrt](#cbrt) -- [ceil](#ceil) -- [cos](#cos) -- [cosh](#cosh) -- [degrees](#degrees) -- [exp](#exp) -- [factorial](#factorial) -- [floor](#floor) -- [gcd](#gcd) -- [isnan](#isnan) -- [iszero](#iszero) -- [lcm](#lcm) -- [ln](#ln) -- [log](#log) -- [log10](#log10) -- [log2](#log2) -- [nanvl](#nanvl) -- [pi](#pi) -- [power](#power) -- [pow](#pow) -- [radians](#radians) -- [random](#random) -- [round](#round) -- [signum](#signum) -- [sin](#sin) -- [sinh](#sinh) -- [sqrt](#sqrt) -- [tan](#tan) -- [tanh](#tanh) -- [trunc](#trunc) - -## abs - -Returns the absolute value of a number. - -```sql -abs(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `abs` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT abs(temp) AS abs FROM home LIMIT 3 -``` - -| abs | -| ---: | -| 21 | -| 23 | -| 22.7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## acos - -Returns the arc cosine or inverse cosine of a number. - -```sql -acos(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `acos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT acos(temp * .01) AS acos FROM home LIMIT 3 -``` - -| acos | -| -----------------: | -| 1.359221367036801 | -| 1.3387186439321834 | -| 1.3418001704498232 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## acosh - -Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. - -```sql -acosh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `acosh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT acosh(temp) AS acosh FROM home LIMIT 3 -``` - -| acosh | -| -----------------: | -| 3.737102242198924 | -| 3.8281684713331012 | -| 3.8150265878962055 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## asin - -Returns the arc sine or inverse sine of a number. - -```sql -asin(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `asin` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT asin(temp * .01) AS asin FROM home LIMIT 3 -``` - -| asin | -| ------------------: | -| 0.2115749597580956 | -| 0.23207768286271319 | -| 0.22899615634507337 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## asinh - -Returns the area hyperbolic sine or inverse hyperbolic sine of a number. - -```sql -asinh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `asinh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT asinh(temp) AS asinh FROM home LIMIT 3 -``` - -| asinh | -| -----------------: | -| 3.7382360302615427 | -| 3.8291136516208812 | -| 3.8159969160459988 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atan - -Returns the arc tangent or inverse tangent of a number. - -```sql -atan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atan` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atan(temp * .01) AS atan FROM home LIMIT 3 -``` - -| atan | -| ------------------: | -| 0.206992194219821 | -| 0.22606838799388393 | -| 0.22321725383717603 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atanh - -Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. - -```sql -atanh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atanh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atanh(temp * .01) AS atanh FROM home LIMIT 3 -``` - -| atanh | -| ------------------: | -| 0.21317134656485978 | -| 0.2341894667593668 | -| 0.23102419806174476 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## atan2 - -Returns the arc tangent or inverse tangent of `expression_y / expression_x`. - -```sql -atan2(expression_y, expression_x) -``` - -##### Arguments - -- **expression_y**: First numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Second numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `atan2` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT atan2(temp, hum) AS atan2 FROM home LIMIT 3 -``` - -| atan2 | -| -----------------: | -| 0.5292859396993504 | -| 0.5660139100632452 | -| 0.5613335864315844 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cbrt - -Returns the cube root of a number. - -```sql -cbrt(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cbrt` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cbrt(temp) AS cbrt FROM home LIMIT 3 -``` - -| cbrt | -| -----------------: | -| 2.7589241763811208 | -| 2.843866979851566 | -| 2.831448188528187 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ceil - -Returns the nearest integer greater than or equal to a number. - -```sql -ceil(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `ceil` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT ceil(temp) AS ceil FROM home LIMIT 3 -``` - -| ceil | -| ---: | -| 21 | -| 23 | -| 23 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cos - -Returns the cosine of a number. - -```sql -cos(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cos(temp) AS cos FROM home LIMIT 3 -``` - -| cos | -| ------------------: | -| -0.5477292602242684 | -| -0.5328330203333975 | -| -0.7591100556583898 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## cosh - -Returns the hyperbolic cosine of a number. - -```sql -cosh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `cosh` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT cosh(temp) AS cosh FROM home LIMIT 3 -``` - -| cosh | -| -----------------: | -| 659407867.2416073 | -| 4872401723.124452 | -| 3609563974.9715896 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## degrees - -Converts radians to degrees. - -```sql -degrees(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `degrees` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT degrees(a) AS degrees FROM numbers LIMIT 3 -``` - -| degrees | -| ------------------: | -| 19.428488139031185 | -| -44.403317464348774 | -| -52.771542485064785 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## exp - -Returns the base-e exponential of a number. - -```sql -exp(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to use as the exponent. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `exp` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT exp(temp) AS exp FROM home LIMIT 3 -``` - -| exp | -| -----------------: | -| 1318815734.4832146 | -| 9744803446.248903 | -| 7219127949.943179 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## factorial - -Returns 1 if value is less than 2. - -```sql -factorial(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `factorial` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT factorial((b + 2)::BIGINT) AS factorial FROM numbers LIMIT 3 -``` - -| factorial | -| --------: | -| 1 | -| 2 | -| 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## floor - -Returns the nearest integer less than or equal to a number. - -```sql -floor(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `floor` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT floor(temp) AS floor FROM home LIMIT 3 -``` - -| floor | -| ----: | -| 21 | -| 23 | -| 22 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## gcd - -Returns the greatest common divisor of `expression_x` and `expression_y`. -Returns `0` if both inputs are zero. - -```sql -gcd(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: First numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Second numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `gcd` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT gcd((a * 5)::BIGINT, (b * 5)::BIGINT) AS gcd FROM numbers LIMIT 3 -``` - -| gcd | -| --------: | -| 1 | -| 3 | -| 2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## isnan - -Returns `true` if a given number is ±NaN, otherwise returns `false`. - -```sql -isnan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Must be a float (`DOUBLE`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `isnan` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/clustered/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT isnan(a) -FROM - (VALUES (4.56), - ('NaN'::DOUBLE), - (16.2) - ) AS data(a) -``` - -| isnan | -| ----: | -| false | -| true | -| false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## iszero - -Returns `true` if the given number is ±0.0, otherwise returns `false`. - -```sql -iszero(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `iszero` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/clustered/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT iszero(a) -FROM - (VALUES (0), - (1), - (2) - ) AS data(a) -``` - -| iszero | -| -----: | -| true | -| false | -| false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lcm - -Returns the least common multiple of `expression_x` and `expression_y`. -Returns `0` if either input is zero. - -```sql -lcm(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: First numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Second numeric expression to operate on. - Must be an integer (`BIGINT`). - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `lcm` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT lcm((a * 10)::BIGINT, (b * 10)::BIGINT) AS lcm FROM numbers LIMIT 3 -``` - -| lcm | -| --: | -| 3 | -| 7 | -| 36 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ln - -Returns the natural logarithm of a number. - -```sql -ln(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `ln` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT ln(temp) AS ln FROM home LIMIT 3 -``` - -| ln | -| -----------------: | -| 3.044522437723423 | -| 3.1354942159291497 | -| 3.122364924487357 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log - -Returns the base-x logarithm of a number. - -``` -log([base, ]numeric_expression) -``` - -#### Arguments - -- **base**: Base numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - Default is `10`. -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - temp, - log(2, temp) AS temp_log2, - log(4, temp) AS temp_log4, - log(temp) AS temp_log10 -FROM home -LIMIT 3 -``` - -| temp | temp_log2 | temp_log4 | temp_log10 | -| :--- | ----------------: | -----------------: | -----------------: | -| 21 | 4.392317422778761 | 2.1961587113893803 | 1.322219294733919 | -| 23 | 4.523561956057013 | 2.2617809780285065 | 1.3617278360175928 | -| 22.7 | 4.504620392403553 | 2.2523101962017766 | 1.3560258571931225 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log10 - -Returns the base-10 logarithm of a number. - -```sql -log10(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log10` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT log10(temp) AS log10 FROM home LIMIT 3 -``` - -| log10 | -| -----------------: | -| 1.3222192947339193 | -| 1.3617278360175928 | -| 1.3560258571931227 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## log2 - -Returns the base-2 logarithm of a number. - -```sql -log2(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `log2` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT log2(temp) AS log2 FROM home LIMIT 3 -``` - -| log2 | -| ----------------: | -| 4.392317422778761 | -| 4.523561956057013 | -| 4.504620392403552 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## nanvl - -Returns the first argument if it’s not `±NaN`. -Otherwise returns the second argument. - -```sql -nanvl(expression_x, expression_y) -``` - -##### Arguments - -- **expression_x**: Numeric expression to return if it’s not `NaN`. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Numeric expression to return if the first expression is `NaN`. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `nanvl` query example" %}} - -_The following example uses the -[Table value constructor](/influxdb/clustered/reference/sql/table-value-constructor/) -to simulate sample data._ - -```sql -SELECT nanvl(a, 0.0) AS nanvl -FROM - (VALUES (4.56), - ('NaN'::DOUBLE), - (16.2) - ) AS data(a) -``` - -| nanvl | -| ----: | -| 4.56 | -| 0 | -| 16.2 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## pi - -Returns an approximate value of π. - -```sql -pi() -``` - -{{< expand-wrapper >}} -{{% expand "View `pi` query example" %}} - -```sql -SELECT pi() AS pi -``` - -| pi | -| :---------------- | -| 3.141592653589793 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## power - -Returns a base expression raised to the power of an exponent. - -```sql -power(base, exponent) -``` - -##### Aliases - -- `pow` - -##### Arguments - -- **base**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **exponent**: Exponent numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `power` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT power(temp, hum * .1) AS power FROM home LIMIT 3 -``` - -| power | -| -----------------: | -| 55817.099910217476 | -| 85007.01501569824 | -| 78569.38332452129 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## `pow` - -_Alias of [power](#power)._ - -## radians - -Converts degrees to radians. - -```sql -radians(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `radians` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT radians(b) AS radians FROM numbers LIMIT 3 -``` - -| radians | -| --------------------: | -| -0.0028561101762876 | -| 0.0023917008411179744 | -| -0.008428949313343818 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## random - -Returns a random float value between 0 and 1. -The random seed is unique to each row. - -```sql -random() -``` - -{{< expand-wrapper >}} -{{% expand "View `random` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT temp * random() AS random FROM home LIMIT 3 -``` - -{{% note %}} -Due to the nature of the function, your results will not match the results below. -{{% /note %}} - -| random | -| -----------------: | -| 0.5030770374815072 | -| 12.938847036567514 | -| 2.8204596545385385 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## round - -Rounds a number to the nearest integer. - -```sql -round(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `round` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT round(temp) AS round FROM home LIMIT 3 -``` - -| round | -| ----: | -| 21 | -| 23 | -| 23 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## signum - -Returns the sign of a number. -Negative numbers return `-1`. -Zero and positive numbers return `1`. - -```sql -signum(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `signum` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT signum(temp - 23) AS signum FROM home LIMIT 3 -``` - -| signum | -| -----: | -| -1 | -| 1 | -| -1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sin - -Returns the sine of a number. - -```sql -sin(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sin` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sin(temp) AS sin FROM home LIMIT 3 -``` - -| sin | -| ------------------: | -| 0.8366556385360561 | -| -0.8462204041751706 | -| -0.6509623056662469 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sinh - -Returns the hyperbolic sine of a number. - -```sql -sinh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sinh ` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sinh(temp) AS sinh FROM home LIMIT 3 -``` - -| sinh | -| -----------------: | -| 659407867.2416073 | -| 4872401723.124452 | -| 3609563974.9715896 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## sqrt - -Returns the square root of a number. - -```sql -sqrt(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `sqrt` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT sqrt(temp) AS sqrt FROM home LIMIT 3 -``` - -| sqrt | -| ----------------: | -| 4.58257569495584 | -| 4.795831523312719 | -| 4.764451699828638 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## tan - -Returns the tangent of a number. - -```sql -tan(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `tan` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT tan(temp) AS tan FROM home LIMIT 3 -``` - -| tan | -| ------------------: | -| -1.5274985276366035 | -| 1.5881530833912738 | -| 0.8575335036257101 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## tanh - -Returns the hyperbolic tangent of a number. - -```sql -tanh(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `tanh` query example" %}} - -_The following example uses the -[Random numbers sample dataset](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data)._ - -```sql -SELECT tanh(a) AS tanh FROM numbers LIMIT 3 -``` - -| tanh | -| ------------------: | -| 0.32666571332086836 | -| -0.6498182711525403 | -| -0.7263877015335474 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## trunc - -Truncates a number toward zero (at the decimal point). - -```sql -trunc(numeric_expression) -``` - -##### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `trunc` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT trunc(temp) AS trunc FROM home LIMIT 3 -``` - -| trunc | -| ----: | -| 21 | -| 23 | -| 22 | - -{{% /expand %}} -{{< /expand-wrapper >}} + \ No newline at end of file diff --git a/content/influxdb/clustered/reference/sql/functions/misc.md b/content/influxdb/clustered/reference/sql/functions/misc.md index 585e1ce7e..db59f5046 100644 --- a/content/influxdb/clustered/reference/sql/functions/misc.md +++ b/content/influxdb/clustered/reference/sql/functions/misc.md @@ -8,239 +8,10 @@ menu: name: Miscellaneous parent: sql-functions weight: 310 + +source: /content/shared/sql-reference/functions/misc.md --- -The InfluxDB SQL implementation supports the following miscellaneous functions -for performing a variety of operations: - -- [arrow_cast](#arrow_cast) -- [arrow_typeof](#arrow_typeof) -- [interpolate](#interpolate) -- [locf](#locf) - - -## arrow_cast - -Casts a value to a specific Arrow data type. - -```sql -arrow_cast(expression, datatype) -``` - -#### Arguments - -- **expression**: Expression to cast. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. -- **datatype**: [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) - to cast to. - -{{< expand-wrapper >}} -{{% expand "View `arrow_cast` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - arrow_cast(time, 'Int64') AS time, - arrow_cast(temp, 'Utf8') AS temp, - arrow_cast(co, 'Float64')AS co -FROM home -LIMIT 1 -``` - -| time | temp | co | -| :------------------ | ---: | --: | -| 1641024000000000000 | 21.0 | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## arrow_typeof - -Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) -of the the expression: - -```sql -arrow_typeof(expression) -``` - -##### Arguments - -- **expression**: Expression to evaluate. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. - -{{< expand-wrapper >}} -{{% expand "View `arrow_typeof` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - arrow_typeof(time) AS time, - arrow_typeof(room) AS room, - arrow_typeof(temp) AS temp, - arrow_typeof(co) AS co -FROM home -LIMIT 1 -``` - -| time | room | temp | co | -| :-------------------------- | :---------------------- | :------ | :---- | -| Timestamp(Nanosecond, None) | Dictionary(Int32, Utf8) | Float64 | Int64 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## interpolate - -Fills null values in a specified aggregated column by interpolating values -from existing values. -Must be used with [`date_bin_gapfill`](/influxdb/clustered/reference/sql/functions/time-and-date/#date_bin_gapfill). - -```sql -interpolate(aggregate_expression) -``` - -##### Arguments - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/clustered/reference/sql/functions/aggregate/). - The expression can be a constant, column, or function, and any combination of - arithmetic operators supported by the aggregate function. - -##### Related functions - -[date_bin_gapfill](/influxdb/clustered/reference/sql/functions/time-and-date/#date_bin_gapfill), -[locf](#locf) - -{{< expand-wrapper >}} -{{% expand "View `interpolate` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - interpolate(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 22 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 22.85 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.25 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.6 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## locf - -Fills null values in a specified aggregated column by carrying the last observed -value forward. -Must be used with [`date_bin_gapfill`](/influxdb/clustered/reference/sql/functions/time-and-date/#date_bin_gapfill). - -_LOCF is an initialism of "last observation carried forward."_ - -```sql -locf(aggregate_expression) -``` - -##### Arguments - -- **aggregate_expression**: Aggregate operation on a specified expression. - The operation can use any [aggregate function](/influxdb/clustered/reference/sql/functions/aggregate/). - The expression can be a constant, column, or function, and any combination of - arithmetic operators supported by the aggregate function. - -##### Related functions - -[date_bin_gapfill](/influxdb/clustered/reference/sql/functions/time-and-date/#date_bin_gapfill), -[interpolate](#interpolate) - -{{< expand-wrapper >}} -{{% expand "View `locf` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - locf(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 21 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 23 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - - + \ No newline at end of file diff --git a/content/influxdb/clustered/reference/sql/functions/regular-expression.md b/content/influxdb/clustered/reference/sql/functions/regular-expression.md index cabea0118..a7fa8971d 100644 --- a/content/influxdb/clustered/reference/sql/functions/regular-expression.md +++ b/content/influxdb/clustered/reference/sql/functions/regular-expression.md @@ -9,145 +9,10 @@ menu: parent: sql-functions weight: 308 influxdb/clustered/tags: [regular expressions, sql] + +source: /content/shared/sql-reference/functions/regular-expression.md --- -The InfluxDB SQL implementation uses the -[PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions) -regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax) -(excluding some features such as look-around and back-references) and supports -the following regular expression functions: - -- [regexp_like](#regexp_like) -- [regexp_match](#regexp_match) -- [regexp_replace](#regexp_replace) - -## regexp_like - -True if a regular expression has at least one match in a string; -false otherwise. - -```sql -regexp_like(str, regexp[, flags]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to test against the string expression. - Can be a constant, column, or function. -- **flags**: Optional regular expression flags that control the behavior of the - regular expression. The following flags are supported: - - **i**: (insensitive) Ignore case when matching. - - **m**: (multi-line) `^` and `$` match the beginning and end of a line, respectively. - - **s**: (single-line) `.` matches newline (`\n`). - - **R**: (CRLF) When multi-line mode is enabled, `\r\n` is used to delimit lines. - - **U**: (ungreedy) Swap the meaning of `x*` and `x*?`. - -{{< expand-wrapper >}} -{{% expand "View `regexp_replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - regexp_like(room::STRING, 'R', 'i') AS regexp_like -FROM home -``` - -| room | regexp_like | -| :---------- | :---------- | -| Kitchen | false | -| Living Room | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## regexp_match - -Returns a list of regular expression matches in a string. - -```sql -regexp_match(str, regexp, flags) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to match against. - Can be a constant, column, or function. -- **flags**: Regular expression flags that control the behavior of the - regular expression. The following flags are supported. - - **i**: (insensitive) Ignore case when matching. - -{{< expand-wrapper >}} -{{% expand "View `regexp_replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -{{% note %}} -`regexp_match` returns a _list_ Arrow type, which is not supported by InfluxDB. -Use _bracket notation_ to reference a value in the list. -Lists use 1-based indexing. -{{% /note %}} - -```sql -SELECT DISTINCT - room, - regexp_match(room::STRING, '.{3}')[1] AS regexp_match -FROM home -``` - -| room | regexp_match | -| :---------- | :----------- | -| Kitchen | Kit | -| Living Room | Liv | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## regexp_replace - -Replaces substrings in a string that match a regular expression. - -```sql -regexp_replace(str, regexp, replacement, flags) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to match against. - Can be a constant, column, or function. -- **replacement**: Replacement string expression. - Can be a constant, column, or function, and any combination of string operators. -- **flags**: Regular expression flags that control the behavior of the - regular expression. The following flags are supported. - - **g**: (global) Search globally and don't return after the first match. - - **i**: (insensitive) Ignore case when matching. - -{{< expand-wrapper >}} -{{% expand "View `regexp_replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - regexp_replace(room::STRING, '\sRoom', '', 'gi') AS regexp_replace -FROM home -``` - -| room | regexp_replace | -| :---------- | :------------- | -| Kitchen | Kitchen | -| Living Room | Living | - -{{% /expand %}} -{{< /expand-wrapper >}} + \ No newline at end of file diff --git a/content/influxdb/clustered/reference/sql/functions/selector.md b/content/influxdb/clustered/reference/sql/functions/selector.md index 9d43cc983..922615f2f 100644 --- a/content/influxdb/clustered/reference/sql/functions/selector.md +++ b/content/influxdb/clustered/reference/sql/functions/selector.md @@ -10,191 +10,10 @@ menu: weight: 302 related: - /influxdb/clustered/query-data/sql/aggregate-select/ + +source: /content/shared/sql-reference/functions/selector.md --- -SQL selector functions are designed to work with time series data. -They behave similarly to aggregate functions in that they take a collection of -data and return a single value. -However, selectors are unique in that they return a _struct_ that contains -a **time value** in addition to the computed value. - -- [How do selector functions work?](#how-do-selector-functions-work) -- [Selector functions](#selector-functions) - - [selector_min](#selector_min) - - [selector_max](#selector_max) - - [selector_first](#selector_first) - - [selector_last](#selector_last) - -## How do selector functions work? - -Each selector function returns an [Arrow _struct_](https://arrow.apache.org/docs/format/Columnar.html#struct-layout) -(similar to a JSON object) representing a single time and value from the -specified column in the each group. -What time and value get returned depend on the logic in the selector function. -For example, `selector_first` returns the value of specified column in the first row of the group. -`selector_max` returns the maximum value of the specified column in the group. - -### Selector struct schema - -The struct returned from a selector function has two properties: - -- **time**: `time` value in the selected row -- **value**: value of the specified column in the selected row - -```js -{time: 2023-01-01T00:00:00Z, value: 72.1} -``` - -### Selector functions in use - -In your `SELECT` statement, execute a selector function and use bracket notation -to reference properties of the [returned struct](#selector-struct-schema) to -populate the column value: - -```sql -SELECT - selector_first(temp, time)['time'] AS time, - selector_first(temp, time)['value'] AS temp, - room -FROM home -GROUP BY room -``` - -## Selector functions - -- [selector_min](#selector_min) -- [selector_max](#selector_max) -- [selector_first](#selector_first) -- [selector_last](#selector_last) - -### selector_min - -Returns the smallest value of a selected column and a timestamp. - -```sql -selector_min(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_min` query example" %}} - -```sql -SELECT - selector_min(water_level, time)['time'] AS time, - selector_min(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T14:30:00Z | -0.61 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_max - -Returns the largest value of a selected column and a timestamp. - -```sql -selector_max(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_max` query example" %}} - -```sql -SELECT - selector_max(water_level, time)['time'] AS time, - selector_max(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T07:24:00Z | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_first - -Returns the first value ordered by time ascending. - -```sql -selector_first(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_first` query example" %}} - -```sql -SELECT - selector_first(water_level, time)['time'] AS time, - selector_first(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-08-28T07:24:00Z | 9.964 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### selector_last - -Returns the last value ordered by time ascending. - -```sql -selector_last(expression, timestamp) -``` - -##### Arguments - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of string or - arithmetic operators. -- **timestamp**: Time expression. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `selector_last` query example" %}} - -```sql -SELECT - selector_last(water_level, time)['time'] AS time, - selector_last(water_level, time)['value'] AS water_level -FROM h2o_feet -``` - -| time | water_level | -| :------------------- | ----------: | -| 2019-09-17T21:42:00Z | 4.938 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/functions/string.md b/content/influxdb/clustered/reference/sql/functions/string.md index bb5639366..ae7915a4f 100644 --- a/content/influxdb/clustered/reference/sql/functions/string.md +++ b/content/influxdb/clustered/reference/sql/functions/string.md @@ -8,1498 +8,10 @@ menu: name: String parent: sql-functions weight: 307 + +source: /content/shared/sql-reference/functions/string.md --- -The InfluxDB SQL implementation supports the following string functions for -operating on string values: - -- [ascii](#ascii) -- [bit_length](#bit_length) -- [btrim](#btrim) -- [char_length](#char_length) -- [character_length](#character_length) -- [concat](#concat) -- [concat_ws](#concat_ws) -- [chr](#chr) -- [ends_with](#ends_with) -- [find_in_set](#find_in_set) -- [initcap](#initcap) -- [instr](#instr) -- [left](#left) -- [length](#length) -- [levenshtein](#levenshtein) -- [lower](#lower) -- [lpad](#lpad) -- [ltrim](#ltrim) -- [md5](#md5) -- [octet_length](#octet_length) -- [overlay](#overlay) -- [position](#position) -- [repeat](#repeat) -- [replace](#replace) -- [reverse](#reverse) -- [right](#right) -- [rpad](#rpad) -- [rtrim](#rtrim) -- [split_part](#split_part) -- [starts_with](#starts_with) -- [strpos](#strpos) -- [substr](#substr) -- [substr_index](#substr_index) -- [to_hex](#to_hex) -- [translate](#translate) -- [trim](#trim) -- [upper](#upper) -- [uuid](#uuid) - -## ascii - -Returns the ASCII value of the first character in a string. - -{{% note %}} -`ascii` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/clustered/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -ascii(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[chr](#chr) - -{{< expand-wrapper >}} -{{% expand "View `ascii` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - ascii(room)::BIGINT AS ascii -FROM home -``` - -| room | ascii | -| :---------- | ----: | -| Kitchen | 75 | -| Living Room | 76 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## bit_length - -Returns the bit length of a string. - -{{% note %}} -`bit_length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/clustered/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -bit_length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[length](#length), [octet_length](#octet_length) - -{{< expand-wrapper >}} -{{% expand "View `bit_length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - bit_length(room)::BIGINT AS bit_length -FROM home -``` - -| room | bit_length | -| :---------- | ---------: | -| Living Room | 88 | -| Kitchen | 56 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## btrim - -Trims the specified trim string from the start and end of a string. -If no trim string is provided, all whitespace is removed from the start and end -of the input string. - -```sql -btrim(str[, trim_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **trim_str**: String expression to trim from the beginning and end of the input string. - Can be a constant, column, or function, and any combination of arithmetic operators. - _Default is whitespace characters_. - -##### Related functions - -[ltrim](#ltrim), -[rtrim](#rtrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `btrim` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - btrim(room::STRING, ' Room') AS btrim -FROM home -``` - -| room | btrim | -| :---------- | :------ | -| Living Room | Living | -| Kitchen | Kitchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## char_length - -_Alias of [length](#length)._ - -## character_length - -_Alias of [length](#length)._ - -## concat - -Concatenates multiple strings together. - -```sql -concat(str[, ..., str_n]) -``` - -##### Arguments - -- **str**: String expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. -- **str_n**: Subsequent string expression to concatenate. - -##### Related functions - -[contcat_ws](#contcat_ws) - -{{< expand-wrapper >}} -{{% expand "View `concat` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - concat('At ', time::STRING, ', the ', room, ' was ', temp::STRING, '°C.') AS concat -FROM home -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| concat | -| :---------------------------------------------- | -| At 2022-01-01T08:00:00, the Kitchen was 21.0°C. | -| At 2022-01-01T09:00:00, the Kitchen was 23.0°C. | -| At 2022-01-01T10:00:00, the Kitchen was 22.7°C. | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## concat_ws - -Concatenates multiple strings together with a specified separator. - -```sql -concat_ws(separator, str[, ..., str_n]) -``` - -##### Arguments - -- **separator**: Separator to insert between concatenated strings. -- **str**: String expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. -- **str_n**: Subsequent string expression to concatenate. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[concat](#concat) - -{{< expand-wrapper >}} -{{% expand "View `concat_ws` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - concat_ws(' -- ', time::STRING, room, temp::STRING) AS concat_ws -FROM home -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| concat_ws | -| :----------------------------------------- | -| 2022-01-01T08:00:00 \-\- Kitchen \-\- 21.0 | -| 2022-01-01T09:00:00 \-\- Kitchen \-\- 23.0 | -| 2022-01-01T10:00:00 \-\- Kitchen \-\- 22.7 | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## chr - -Returns the character with the specified ASCII or Unicode code value. - -``` -chr(expression) -``` - -#### Arguments - -- **expression**: Expression containing the ASCII or Unicode code value to operate on. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. - -##### Related functions - -[ascii](#ascii) - -{{< expand-wrapper >}} -{{% expand "View `chr` query example" %}} - -```sql -SELECT - ascii, - chr(ascii) AS chr -FROM - (values (112), - (75), - (214) - ) data(ascii) -``` - -| ascii | chr | -| :---- | :-: | -| 112 | p | -| 75 | K | -| 214 | Ö | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ends_with - -Tests if a string ends with a substring. - -```sql -ends_with(str, substr) -``` - -##### Arguments - -- **str**: String expression to test. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to test for. - -{{< expand-wrapper >}} -{{% expand "View `ends_with` query example" %}} - -```sql -SELECT - string, - ends_with(string, 'USA') AS ends_with -FROM - (values ('New York, USA'), - ('London, UK'), - ('San Francisco, USA') - ) data(string) -``` - -| string | ends_with | -| :----------------- | :-------- | -| New York, USA | true | -| London, UK | false | -| San Francisco, USA | true | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## find_in_set - -Returns the position of a string in a comma-delimited list of substrings. -Returns 0 if the string is not in the list of substrings. - -```sql -find_in_set(str, strlist) -``` - -##### Arguments - -- **str**: String expression to find in `strlist`. -- **strlist**: A string containing a comma-delimited list of substrings. - -{{< expand-wrapper >}} -{{% expand "View `find_in_set` query example" %}} - -```sql -SELECT - string, - find_in_set(string, 'Isaac,John,Sara') AS find_in_set -FROM - (values ('John'), - ('Sarah'), - ('Isaac') - ) data(string) -``` - -| string | find_in_set | -| :----- | ----------: | -| John | 2 | -| Sarah | 0 | -| Isaac | 1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## initcap - -Capitalizes the first character in each word in the input string. -Words are delimited by non-alphanumeric characters. - -```sql -initcap(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[lower](#lower), -[upper](#upper) - -{{< expand-wrapper >}} -{{% expand "View `initcap` query example" %}} - -```sql -SELECT - string, - initcap(string) AS initcap -FROM - (values ('hello world'), - ('hello-world'), - ('hello_world') - ) data(string) -``` - -| string | initcap | -| :---------- | :---------- | -| hello world | Hello World | -| hello-world | Hello-World | -| hello_world | Hello_World | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## instr - -Returns the location where a substring first appears in a string (starting at 1). -If the substring is not in the string, the function returns 0. - -```sql -instr(str, substr) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `instr` query example" %}} - -```sql -SELECT - string, - instr(string, 'neighbor') AS instr -FROM - (values ('good neighbor'), - ('bad neighbor'), - ('next-door neighbor'), - ('friend') - ) data(string) -``` - -| string | instr | -| :----------------- | ----: | -| good neighbor | 6 | -| bad neighbor | 5 | -| next-door neighbor | 11 | -| friend | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## left - -Returns a specified number of characters from the left side of a string. - -```sql -left(str, n) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of characters to return. - -##### Related functions - -[right](#right) - -{{< expand-wrapper >}} -{{% expand "View `left` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - left(room::STRING, 3) AS left -FROM home -``` - -| room | left | -| :---------- | :--- | -| Kitchen | Kit | -| Living Room | Liv | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## length - -Returns the number of characters in a string. - -{{% note %}} -`char_length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/clustered/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Aliases - -- char\_length -- character\_length - -##### Related functions - -[bit_length](#bit_length), -[octet_length](#octet_length) - -{{< expand-wrapper >}} -{{% expand "View `length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - length(room)::BIGINT AS length -FROM home -``` - -| room | length | -| :---------- | -----: | -| Kitchen | 7 | -| Living Room | 11 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## levenshtein - -Returns the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) -between two strings. - -```sql -levenshtein(str1, str2) -``` - -##### Arguments -- **str1**: First string expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **str2**: Second string expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `levenshtein` query example" %}} - -```sql -SELECT - string1, - string2, - levenshtein(string1, string2) AS levenshtein -FROM - (values ('kitten', 'sitting'), - ('puppy', 'jumping'), - ('cow', 'lowing') - ) data(string1, string2) -``` - -| string1 | string2 | levenshtein | -| :------ | :------ | ----------: | -| kitten | sitting | 3 | -| puppy | jumping | 5 | -| cow | lowing | 4 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lower - -Converts a string to lower-case. - -```sql -lower(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[initcap](#initcap), -[upper](#upper) - -{{< expand-wrapper >}} -{{% expand "View `lower` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - lower(room::STRING) AS lower -FROM home -``` - -| room | lower | -| :---------- | :---------- | -| Kitchen | kitchen | -| Living Room | living room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## lpad - -Pads the left side of a string with another string to a specified string length. - -```sql -lpad(str, n[, padding_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: String length to pad to. -- **padding_str**: String expression to pad with. - Can be a constant, column, or function, and any combination of string operators. - _Default is a space._ - -##### Related functions - -[rpad](#rpad) - -{{< expand-wrapper >}} -{{% expand "View `lpad` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - lpad(room::STRING, 14, '-') AS lpad -FROM home -``` - -| room | lpad | -| :---------- | :-------------------- | -| Kitchen | \-\-\-\-\-\-\-Kitchen | -| Living Room | \-\-\-Living Room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## ltrim - -Removes leading spaces from a string. - -```sql -ltrim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[rtrim](#rtrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `ltrim` query example" %}} - -```sql -SELECT - string, - ltrim(string) AS ltrim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | ltrim | -| :-------------------------------------- | :-------------------------------------- | -|   Leading spaces | Leading spaces | -| Trailing spaces   | Trailing spaces   | -| Leading and trailing spaces   | Leading and trailing spaces   | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## md5 - -Computes an MD5 128-bit checksum for a string expression. - -```sql -md5(str) -``` - -##### Arguments - -- **expression**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `md5` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - md5(room) AS md5 -FROM home -``` - -| room | md5 | -| :---------- | :------------------------------- | -| Kitchen | 33fa00a66f2edf0d1c5697a9f8693ba8 | -| Living Room | f45b0e6aec165544faccaf2cad820542 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## octet_length - -Returns the length of a string in bytes. - -{{% note %}} -`length` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/clustered/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -octet_length(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[bit_length](#bit_length), -[length](#length) - -{{< expand-wrapper >}} -{{% expand "View `octet_length` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - octet_length(room)::BIGINT AS octet_length -FROM home -``` - -| room | octet_length | -| :---------- | -----------: | -| Living Room | 11 | -| Kitchen | 7 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## overlay - -Replaces part of a string with another substring using a specified starting -position and number of characters to replace. - -```sql -overlay(str PLACING substr FROM pos [FOR count]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to use to replace part of the specified string (`str`). - Can be a constant, column, or function, and any combination of string operators. -- **pos**: Start position of the substring replacement (`substr`). -- **count**: Number of characters in the string (`str`) to replace with the - substring (`substr`) beginning from the start position (`pos`). - If not specified, the function uses the length of the substring. - -{{< expand-wrapper >}} -{{% expand "View `overlay` query example" %}} - -```sql -SELECT - string, - overlay(string PLACING '****' FROM 1 FOR 12) AS overlay -FROM - (values ('2223000048410010'), - ('2222420000001113'), - ('4917484589897107') - ) data(string) -``` - -| string | overlay | -| :--------------- | :------- | -| 2223000048410010 | ****0010 | -| 2222420000001113 | ****1113 | -| 4917484589897107 | ****7107 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## position - -Returns the position of a substring in a string. - -```sql -position(substr IN str) -``` - -##### Arguments - -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. -- **str**: String expression to search. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `position` query example" %}} - -```sql -SELECT - string, - position('oo' IN string) AS position -FROM - (values ('cool'), - ('scoop'), - ('ice cream') - ) data(string) -``` - -| string | position | -| :-------- | -------: | -| cool | 2 | -| scoop | 3 | -| ice cream | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## repeat - -Returns a string with an input string repeated a specified number of times. - -```sql -repeat(str, n) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of times to repeat the input string. - -{{< expand-wrapper >}} -{{% expand "View `repeat` query example" %}} - -```sql -SELECT - string, - repeat(string, 3) AS repeat -FROM - (values ('foo '), - ('bar '), - ('baz ') - ) data(string) -``` - -| string | repeat | -| :-------- | :---------- | -| foo  | foo foo foo | -| bar  | bar bar bar | -| baz  | baz baz baz | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## replace - -Replaces all occurrences of a specified substring in a string with a new substring. - -```sql -replace(str, substr, replacement) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to replace in the input string. - Can be a constant, column, or function, and any combination of string operators. -- **replacement**: Replacement substring expression. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `replace` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - replace(room::STRING, ' ', '_') AS replace -FROM home -``` - -| room | replace | -| :---------- | :---------- | -| Kitchen | Kitchen | -| Living Room | Living_Room | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## reverse - -Reverses the character order of a string. - -```sql -reverse(str) -``` - -##### Arguments - -- **str**: String expression to repeat. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `reverse` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - reverse(room::STRING) AS reverse -FROM home -``` - -| room | reverse | -| :---------- | :---------- | -| Kitchen | nehctiK | -| Living Room | mooR gniviL | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## right - -Returns a specified number of characters from the right side of a string. - -```sql -right(str, n) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: Number of characters to return. - -##### Related functions - -[left](#left) - -{{< expand-wrapper >}} -{{% expand "View `right` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - right(room::STRING, 3) AS right -FROM home -``` - -| room | right | -| :---------- | :---- | -| Living Room | oom | -| Kitchen | hen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## rpad - -Pads the right side of a string with another string to a specified string length. - -```sql -rpad(str, n[, padding_str]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **n**: String length to pad to. -- **padding_str**: String expression to pad with. - Can be a constant, column, or function, and any combination of string operators. - _Default is a space._ - -##### Related functions - -[lpad](#lpad) - -{{< expand-wrapper >}} -{{% expand "View `rpad` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - rpad(room::STRING, 14, '-') AS rpad -FROM home -``` - -| room | rpad | -| :---------- | :-------------------- | -| Kitchen | Kitchen\-\-\-\-\-\-\- | -| Living Room | Living Room\-\-\- | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## rtrim - -Removes trailing spaces from a string. - -```sql -rtrim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[ltrim](#ltrim), -[trim](#trim) - -{{< expand-wrapper >}} -{{% expand "View `rtrim` query example" %}} - -```sql -SELECT - string, - rtrim(string) AS rtrim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | rtrim | -| :-------------------------------------- | :-------------------------------------- | -|   Leading spaces |   Leading spaces | -| Trailing spaces   | Trailing spaces | -| Leading and trailing spaces   |   Leading and trailing spaces | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## split_part - -Splits a string based on a specified delimiter and returns the substring in the -specified position. - -```sql -split_part(str, delimiter, pos) -``` - -##### Arguments - -- **str**: String expression to spit. - Can be a constant, column, or function, and any combination of string operators. -- **delimiter**: String or character to split on. -- **pos**: Position of the part to return. - -{{< expand-wrapper >}} -{{% expand "View `split_part` query example" %}} - -```sql -SELECT - url, - split_part(url, '.', 1) AS split_part -FROM - (values ('www.influxdata.com'), - ('docs.influxdata.com'), - ('community.influxdata.com') - ) data(url) -``` - -| url | split_part | -| :----------------------- | :--------- | -| www.influxdata.com | www | -| docs.influxdata.com | docs | -| community.influxdata.com | community | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## starts_with - -Tests if a string starts with a substring. - -```sql -starts_with(str, substr) -``` - -##### Arguments - -- **str**: String expression to test. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring to test for. - -{{< expand-wrapper >}} -{{% expand "View `starts_with` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - starts_with(room::STRING, 'Kit') AS starts_with -FROM home -``` - -| room | starts_with | -| :---------- | :---------- | -| Kitchen | true | -| Living Room | false | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## strpos - -Returns the starting position of a specified substring in a string. -Positions begin at 1. -If the substring does not exist in the string, the function returns 0. - -{{% note %}} -`strpos` returns a 32-bit integer. -To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/clustered/query-data/sql/cast-types/#cast-to-an-integer). -{{% /note %}} - -```sql -strpos(str, substr) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **substr**: Substring expression to search for. - Can be a constant, column, or function, and any combination of string operators. - -{{< expand-wrapper >}} -{{% expand "View `strpos` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - strpos(room::STRING, 'Room')::BIGINT AS strpos -FROM home -``` - -| room | strpos | -| :---------- | -----: | -| Kitchen | 0 | -| Living Room | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## substr - -Extracts a substring of a specified number of characters from a specific -starting position in a string. - -```sql -substr(str, start_pos[, length]) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **start_pos**: Character position to start the substring at. - The first character in the string has a position of 1. -- **length**: Number of characters to extract. - If not specified, returns the rest of the string after the start position. - -{{< expand-wrapper >}} -{{% expand "View `substr` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - substr(room::STRING, 3, 5) AS substr -FROM home -``` - -| room | substr | -| :---------- | :--------- | -| Living Room | ving  | -| Kitchen | tchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## substr_index - -Returns the substring that occurs before or after the specified number (`count`) -of delimiter (`delimiter`) occurrences in a string (`str`). -If the count is positive, the function returns everything to the left of the -final delimiter (counting from the left). -If the count is negative, the function returns everything to the right of the -final delimiter (counting from the right). - -```sql -substr_index(str, delimiter, count) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **delimiter**: String expression to use to delimit substrings in the string (`str`). - Can be a constant, column, or function, and any combination of string operators. -- **count**: The Nth occurrence of the delimiter (`delimiter`) to split on. - Can be a constant, column, or function, and any combination of arithmetic operators. - Supports positive and negative numbers. - -{{< expand-wrapper >}} -{{% expand "View `substr_index` query example" %}} - -```sql -SELECT - url, - substr_index(url, '.', 1) AS subdomain, - substr_index(url, '.', -1) AS tld -FROM - (values ('docs.influxdata.com'), - ('community.influxdata.com'), - ('cloud2.influxdata.com') - ) data(url) -``` - -| url | subdomain | tld | -| :----------------------- | :-------- | :-- | -| docs.influxdata.com | docs | com | -| community.influxdata.com | community | com | -| arrow.apache.org | arrow | org | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## translate - -Translates characters in a string to specified translation characters. - -```sql -translate(str, chars, translation) -``` - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. -- **chars**: Characters to translate. -- **translation**: Translation characters. Translation characters replace only - characters at the same position in the **chars** string. - -{{< expand-wrapper >}} -{{% expand "View `translate` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - translate(room::STRING, 'Rom', 'sOn') AS translate -FROM home -``` - -| room | translate | -| :---------- | :---------- | -| Living Room | Living sOOn | -| Kitchen | Kitchen | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_hex - -Converts an integer to a hexadecimal string. - -```sql -to_hex(int) -``` - -##### Arguments - -- **int**: Integer expression to convert. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `to_hex` query example" %}} - -```sql -SELECT - int, - to_hex(int) AS to_hex -FROM - (values (123), - (345), - (678) - ) data(int) -``` - -| int | to_hex | -| :-- | -----: | -| 123 | 7b | -| 345 | 159 | -| 678 | 2a6 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## trim - -Removes leading and trailing spaces from a string. - -```sql -trim(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[btrim](#btrim), -[ltrim](#ltrim), -[rtrim](#rtrim) - -{{< expand-wrapper >}} -{{% expand "View `trim` query example" %}} - -```sql -SELECT - string, - trim(string) AS trim -FROM - (values (' Leading spaces'), - ('Trailing spaces '), - (' Leading and trailing spaces ') - ) data(string) -``` - -| string | trim | -| :-------------------------------------- | :-------------------------- | -|   Leading spaces | Leading spaces | -| Trailing spaces   | Trailing spaces | -| Leading and trailing spaces   | Leading and trailing spaces | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## upper - -Converts a string to upper-case. - -```sql -upper(str) -``` - -##### Arguments - -- **str**: String expression to operate on. - Can be a constant, column, or function, and any combination of string operators. - -##### Related functions - -[initcap](#initcap), -[lower](#lower) - -{{< expand-wrapper >}} -{{% expand "View `upper` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT DISTINCT - room, - upper(room::STRING) AS upper -FROM home -``` - -| room | upper | -| :---------- | :---------- | -| Living Room | LIVING ROOM | -| Kitchen | KITCHEN | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## uuid - -Returns a UUID v4 string value that is unique per row. - -```sql -uuid() -``` - -{{< expand-wrapper >}} -{{% expand "View `uuid` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - room, - uuid() AS uuid -FROM (SELECT DISTINCT room FROM home) -``` - -| room | uuid | -| :---------- | :----------------------------------: | -| Kitchen | f0b41da9-e334-4b7d-b925-a54ca6b082f3 | -| Living Room | c31be90e-c4ed-4304-b633-47b969ef3ab6 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/functions/time-and-date.md b/content/influxdb/clustered/reference/sql/functions/time-and-date.md index 7257afa32..e6cbcb3a6 100644 --- a/content/influxdb/clustered/reference/sql/functions/time-and-date.md +++ b/content/influxdb/clustered/reference/sql/functions/time-and-date.md @@ -8,818 +8,10 @@ menu: name: Time and date parent: sql-functions weight: 305 + +source: /content/shared/sql-reference/functions/time-and-date.md --- -InfluxDB's SQL implementation supports time and date functions that are useful when working with time series data. - -- [current_date](#current_date) -- [current_time](#current_time) -- [date_bin](#date_bin) -- [date_bin_gapfill](#date_bin_gapfill) -- [date_trunc](#date_trunc) -- [datetrunc](#datetrunc) -- [date_part](#date_part) -- [datepart](#datepart) -- [extract](#extract) -- [from_unixtime](#from_unixtime) -- [now](#now) -- [to_timestamp](#to_timestamp) -- [to_timestamp_millis](#to_timestamp_millis) -- [to_timestamp_micros](#to_timestamp_micros) -- [to_timestamp_seconds](#to_timestamp_seconds) - -## current_date - -Returns the current UTC date. - -{{% note %}} -`current_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a timestamp](/influxdb/clustered/query-data/sql/cast-types/#cast-to-a-timestamp-type). -{{% /note %}} - -The `current_date()` return value is determined at query time and will return -the same date, no matter when in the query plan the function executes. - -``` -current_date() -``` - -{{< expand-wrapper >}} -{{% expand "View `current_date` query example" %}} - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - time, - temp, - current_date()::TIMESTAMP AS current_date -FROM home -WHERE - time > current_date()::TIMESTAMP - INTERVAL '5 years' -LIMIT 3 -``` - -{{% influxdb/custom-timestamps %}} - -| time | temp | current_date | -| :------------------- | ---: | :---------------------------- | -| 2022-01-01T08:00:00Z | 21 | {{< datetime/current-date >}} | -| 2022-01-01T09:00:00Z | 23 | {{< datetime/current-date >}} | -| 2022-01-01T10:00:00Z | 22.7 | {{< datetime/current-date >}} | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## current_time - -Returns the current UTC time. - -{{% note %}} -`current_date` returns a `TIME64` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a string](/influxdb/clustered/query-data/sql/cast-types/#cast-to-a-string-type). -{{% /note %}} - -The `current_time()` return value is determined at query time and will return the same time, -no matter when in the query plan the function executes. - -``` -current_time() -``` - -{{< expand-wrapper >}} -{{% expand "View `current_time` query example" %}} - -_The following example uses the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -SELECT - time, - temp, - current_time()::STRING AS current_time -FROM home -LIMIT 3 -``` - -| time | temp | current_time | -| :------------------- | ---: | :---------------------------- | -| 2022-01-01T08:00:00Z | 21 | {{< datetime/current-time >}} | -| 2022-01-01T09:00:00Z | 23 | {{< datetime/current-time >}} | -| 2022-01-01T10:00:00Z | 22.7 | {{< datetime/current-time >}} | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## date_bin - -Calculates time intervals and returns the start of the interval nearest to the specified timestamp. -Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" -and applying an aggregate or selector function to each window. - -For example, if you "bin" or "window" data into 15 minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 minute bin it is in: `2023-01-01T18:15:00Z`. - -```sql -date_bin(interval, expression[, origin_timestamp]) -``` - -##### Arguments: - -- **interval**: Bin interval. -- **expression**: Time expression to operate on. - Can be a constant, column, or function. -- **origin_timestamp**: Starting point used to determine bin boundaries. - _Default is the Unix epoch._ - -The following intervals are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks -- months -- years -- century - -{{< expand-wrapper >}} -{{% expand "View `date_bin` query example" %}} - -The following query returns the daily average of water levels in the queried time range. - -```sql -SELECT - date_bin(INTERVAL '1 day', time, TIMESTAMP '1970-01-01 00:00:00Z') AS time, - avg("water_level") AS water_level_avg -FROM "h2o_feet" -WHERE - time >= timestamp '2019-09-10T00:00:00Z' - AND time <= timestamp '2019-09-20T00:00:00Z' -GROUP BY 1 -ORDER BY time DESC -``` - -| time | water_level_avg | -| :----------------------- | :----------------- | -| 2019-09-17T00:00:00.000Z | 4.370175687443861 | -| 2019-09-16T00:00:00.000Z | 4.6034785848437485 | -| 2019-09-15T00:00:00.000Z | 4.680651501506248 | -| 2019-09-14T00:00:00.000Z | 4.857683652395836 | -| 2019-09-13T00:00:00.000Z | 4.911051520291668 | -| 2019-09-12T00:00:00.000Z | 4.763990784533338 | -| 2019-09-11T00:00:00.000Z | 4.6582452515041695 | -| 2019-09-10T00:00:00.000Z | 4.608425018785421 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## date_bin_gapfill - -Calculates time intervals and returns the start of the interval nearest to the specified timestamp. -If no rows exist in a time interval, a new row is inserted with a `time` value -set to the interval start time, all columns in the `GROUP BY` clause populated, -and null values in aggregate columns. - -Use `date_bin_gapfill` with [`interpolate`](/influxdb/clustered/reference/sql/functions/misc/#interpolate) -or [`locf`](/influxdb/clustered/reference/sql/functions/misc/#locf) to -[fill gaps in data]() -at specified time intervals. - -```sql -date_bin_gapfill(interval, expression[, origin_timestamp]) -``` - -{{% note %}} -`date_bin_gapfill` requires [time bounds](/influxdb/clustered/query-data/sql/basic-query/#query-data-within-time-boundaries) -in the `WHERE` clause. -{{% /note %}} - -##### Arguments: - -- **interval**: Bin interval. -- **expression**: Time expression to operate on. - Can be a constant, column, or function. -- **origin_timestamp**: Starting point used to determine bin boundaries. - _Default is the Unix epoch._ - -The following intervals are supported: - -- nanoseconds -- microseconds -- milliseconds -- seconds -- minutes -- hours -- days -- weeks -- months -- years -- century - -##### Related functions - -[interpolate](/influxdb/clustered/reference/sql/functions/misc/#interpolate), -[locf](/influxdb/clustered/reference/sql/functions/misc/#locf) - -{{< expand-wrapper >}} -{{% expand "View `date_bin_gapfill` query examples" %}} - -_The following examples use the sample data set provided in the -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -- [Use date_bin_gapfill to insert rows when no rows exists](#use-date_bin_gapfill-to-insert-rows-when-no-rows-exists) -- [Use date_bin_gapfill to fill gaps in data](#use-date_bin_gapfill-to-fill-gaps-in-data) - -#### Use date_bin_gapfill to insert rows when no rows exists - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - avg(temp) as temp -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | temp | -| :------------------- | :---------- | ---: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -#### Use date_bin_gapfill to fill gaps in data - -Use `interpolate` and `locf` to fill the null values in rows inserted by -`date_bin_gapfill`. - -{{< tabs-wrapper >}} -{{% tabs "small" %}} -[interpolate](#) -[locf](#) -{{% /tabs %}} -{{% tab-content %}} - -The example below uses [`interpolate`](/influxdb/clustered/reference/sql/functions/misc/#interpolate) -to fill null values by interpolating values between non-null values. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - interpolate(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 22 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 22.85 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.25 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.6 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /tab-content %}} -{{% tab-content %}} - -The example below uses [`locf`](/influxdb/clustered/reference/sql/functions/misc/#locf) -to fill null values by carrying the last observed value forward. - -{{% influxdb/custom-timestamps %}} - -```sql -SELECT - date_bin_gapfill(INTERVAL '30 minutes', time) as _time, - room, - locf(avg(temp)) -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T10:00:00Z' -GROUP BY _time, room -``` - -| _time | room | AVG(home.temp) | -| :------------------- | :---------- | -------------: | -| 2022-01-01T08:00:00Z | Kitchen | 21 | -| 2022-01-01T08:30:00Z | Kitchen | 21 | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T09:30:00Z | Kitchen | 23 | -| 2022-01-01T10:00:00Z | Kitchen | 22.7 | -| 2022-01-01T08:00:00Z | Living Room | 21.1 | -| 2022-01-01T08:30:00Z | Living Room | 21.1 | -| 2022-01-01T09:00:00Z | Living Room | 21.4 | -| 2022-01-01T09:30:00Z | Living Room | 21.4 | -| 2022-01-01T10:00:00Z | Living Room | 21.8 | - -{{% /influxdb/custom-timestamps %}} - -{{% /tab-content %}} -{{< /tabs-wrapper >}} - -{{% /expand %}} -{{< /expand-wrapper >}} - - -## date_trunc - -Truncates a timestamp value to a specified precision. - -```sql -date_trunc(precision, expression) -``` - -##### Arguments: - -- **precision**: Time precision to truncate to. - The following precisions are supported: - - - year - - month - - week - - day - - hour - - minute - - second - -- **expression**: Time expression to operate on. - Can be a constant, column, or function. - -##### Aliases - -- `datetrunc` - -{{< expand-wrapper >}} -{{% expand "View `date_trunc` query examples" %}} - -#### Use date_trunc to return hourly averages - -```sql -SELECT - avg(water_level) AS level, - date_trunc('hour', time) AS hour -FROM h2o_feet -WHERE - time >= timestamp '2019-09-10T00:00:00Z' - AND time <= timestamp '2019-09-12T00:00:00Z' -GROUP BY hour -ORDER BY hour -``` - -| hour | level | -| :----------------------- | :----------------- | -| 2019-09-10T00:00:00.000Z | 3.7248000000000006 | -| 2019-09-10T01:00:00.000Z | 3.8561499999999995 | -| 2019-09-10T02:00:00.000Z | 4.5405999999999995 | -| 2019-09-10T03:00:00.000Z | 5.5548072072500005 | -| 2019-09-10T04:00:00.000Z | 6.433900000000001 | -| 2019-09-10T05:00:00.000Z | 6.810949999999998 | - -#### Use date_trunc to return weekly averages - -```sql -SELECT - mean(water_level) as level, - date_trunc('week',time) AS week -FROM h2o_feet -WHERE - time >= timestamp '2019-08-01T00:00:00Z' - AND time <= timestamp '2019-10-31T00:00:00Z' -GROUP BY week -ORDER BY week -``` - -| level | week | -| :----------------- | :----------------------- | -| 4.3314415259020835 | 2019-08-12T00:00:00.000Z | -| 4.234838403584523 | 2019-08-19T00:00:00.000Z | -| 4.4184818559633925 | 2019-08-26T00:00:00.000Z | -| 4.405153386766021 | 2019-09-02T00:00:00.000Z | -| 4.725866897257734 | 2019-09-09T00:00:00.000Z | -| 4.499938596774042 | 2019-09-16T00:00:00.000Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## datetrunc - -_Alias of [date_trunc](#date_trunc)._ - -## date_part - -Returns the specified part of the date as an integer. - -```sql -date_part(part, expression) -``` - -##### Arguments: - -- **part**: Part of the date to return. - The following date parts are supported: - - - year - - month - - week _(week of the year)_ - - day _(day of the month)_ - - hour - - minute - - second - - millisecond - - microsecond - - nanosecond - - dow _(day of the week)_ - - doy _(day of the year)_ - -- **expression**: Time expression to operate on. - Can be a constant, column, or function. - -##### Aliases - -- `datepart` - -{{< expand-wrapper >}} -{{% expand "View `date_part` query examples" %}} - -```sql -SELECT - date_part('hour', time) AS hour, - time, - "level description", - location -FROM h2o_feet -WHERE - time >= timestamp '2019-08-17T02:54:00Z' - AND time <= timestamp '2019-08-17T03:06:00Z' -ORDER BY time -``` - -| hour | time | level description | location | -| :--: | :------------------- | :------------------- | :----------- | -| 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | coyote_creek | -| 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | santa_monica | -| 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | coyote_creek | -| 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | santa_monica | -| 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | coyote_creek | -| 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | santa_monica | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## datepart - -_Alias of [date_part](#date_part)._ - -## extract - -Returns a sub-field from a time value as an integer. -Similar to `date_part`, but with different arguments. - -```sql -extract(field FROM source) -``` - -##### Arguments - -- **field**: Part or field of the date to return. - The following date fields are supported: - - - year - - month - - week _(week of the year)_ - - day _(day of the month)_ - - hour - - minute - - second - - millisecond - - microsecond - - nanosecond - - dow _(day of the week)_ - - doy _(day of the year)_ - -- **source**: Source time expression to operate on. - Can be a constant, column, or function. - -{{< expand-wrapper >}} -{{% expand "View `extract` query example" %}} - -```sql -SELECT - extract(day from time) AS day -FROM - h2o_feet -LIMIT 1 -``` - -| day | -| :-- | -| 25 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## from_unixtime - -Converts an integer to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). -Input is parsed as a [Unix nanosecond timestamp](/influxdb/clustered/reference/glossary/#unix-timestamp) -and returns the corresponding RFC3339 timestamp. - -```sql -from_unixtime(expression) -``` - -##### Arguments: - -- **expression**: Integer expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `from_unixtime` query example" %}} - -```sql -SELECT - from_unixtime(1672531200000000000) AS RFC3339 -``` - -| RFC3339 | -| :------------------- | -| 2023-01-01T00:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## now - -Returns the current UTC timestamp. - -The `now()` return value is determined at query time and will return the same timestamp, -no matter when in the query plan the function executes. - -```sql -now() -``` - -{{< expand-wrapper >}} -{{% expand "View `now` query example" %}} - -```sql -SELECT - "water_level", - "time" -FROM h2o_feet -WHERE - time <= now() - interval '12 minutes' -``` - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp - -Converts a value to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix nanosecond timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp(expression) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp` query example" %}} - -```sql -SELECT to_timestamp(1704067200000000000) -``` - -| to_timestamp(Int64(1704067200000000000)) | -| :--------------------------------------- | -| 2024-01-01T00:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_millis - -Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix millisecond timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_millis(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_millis` query example" %}} - -```sql -SELECT to_timestamp_millis(1704067200001) AS time -``` - -Results -| to_timestamp_millis(Int64(1704067200001)) | -| :---------------------------------------- | -| 2024-01-01T00:00:00.001Z | - -{{% /expand %}} -{{% expand "View `to_timestamp_millis` example with string format parsing" %}} - -```sql -SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond -``` - -| millisecond | -| :----------------------- | -| 2024-01-01T01:01:59.123Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_micros - -Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix microsecond timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_micros(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_micros` query example" %}} - -```sql -SELECT to_timestamp_micros(1704067200000001) -``` - -| to_timestamp_micros(Int64(1704067200000001)) | -| :------------------------------------------- | -| 2024-01-01T00:00:00.000001Z | -{{% /expand %}} -{{% expand "View `to_timestamp_micros` example with string format parsing" %}} - -```sql -SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond -``` - -| microsecond | -| :-------------------------- | -| 2024-01-01T01:01:59.123456Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_nanos - -Converts a value to RFC3339 nanosecond timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix nanosecond timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_nanos(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_nanos` query example" %}} - -```sql -SELECT to_timestamp_nanos(1704067200000000001) -``` - -| to_timestamp_nanos(Int64(1704067200000000001)) | -| :--------------------------------------------- | -| 2024-01-01T00:00:00.000000001Z | -{{% /expand %}} -{{% expand "View `to_timestamp_nanos` example with string format parsing" %}} - -```sql -SELECT to_timestamp_nanos('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS nanosecond -``` - -| nanosecond | -| :----------------------------- | -| 2024-01-01T01:01:59.123456789Z | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## to_timestamp_seconds - -Converts a value to RFC3339 second timestamp format (`YYYY-MM-DDT00:00:00Z`). -Supports timestamp, integer, and unsigned integer types as input. -Integers and unsigned integers are parsed as -[Unix second timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) -and return the corresponding RFC3339 timestamp. - -```sql -to_timestamp_seconds(expression[, ..., format_n]) -``` - -##### Arguments: - -- **expression**: Expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) - pattern to use to parse the _string_ expression. - Formats are attempted in the order that they appear. - The function returns the timestamp from the first format to parse successfully. - If no formats parse successfully, the function returns an error. - -{{< expand-wrapper >}} -{{% expand "View `to_timestamp_seconds` query example" %}} - -```sql -SELECT to_timestamp_seconds(1704067201) -``` - -| to_timestamp_seconds(Int64(1704067201)) | -| :-------------------------------------- | -| 2024-01-01T00:00:01Z | - -{{% /expand %}} -{{% expand "View `to_timestamp_seconds` example with string format parsing" %}} - -```sql -SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS second -``` - -| second | -| :------------------- | -| 2024-01-01T01:01:59Z | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/group-by.md b/content/influxdb/clustered/reference/sql/group-by.md index 905e4ed78..92d46ce7b 100644 --- a/content/influxdb/clustered/reference/sql/group-by.md +++ b/content/influxdb/clustered/reference/sql/group-by.md @@ -7,92 +7,10 @@ menu: name: GROUP BY clause parent: SQL reference weight: 203 + +source: /content/shared/sql-reference/group-by.md --- -Use the `GROUP BY` clause to group data by values. - -`GROUP BY` is an optional clause used to group rows that have the same values for all columns and expressions in the list. -To output an aggregation for each group, include an aggregate or selector function in the `SELECT` statement. -When `GROUP BY` appears in a query, the `SELECT` list can only use columns that appear in the `GROUP BY` list -or in aggregate expressions. - -`GROUP BY` can use column aliases that are defined in the `SELECT` clause. -`GROUP BY` can't use an alias named `time`. -In a `GROUP BY` list, `time` always refers to the measurement `time` column. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT - AGGREGATE_FN(field1), - tag1 -FROM measurement -GROUP BY tag1 -``` - -## Examples - -### Group data by tag values - -```sql -SELECT - AVG("water_level") AS "avg_water_level", - "location" -FROM "h2o_feet" -GROUP BY "location" -``` - -{{< expand-wrapper >}}} -{{% expand "View example results" %}} - -| avg_water_level | location | -| ----------------: | ------------ | -| 5.359142420303919 | coyote_creek | -| 3.530712094245885 | santa_monica | - -{{% /expand %}} -{{< /expand-wrapper >}} - -Group results in 15 minute time intervals by tag: - -```sql -SELECT - "location", - DATE_BIN(INTERVAL '15 minutes', time, TIMESTAMP '2022-01-01 00:00:00Z') AS _time, - COUNT("water_level") AS count -FROM "h2o_feet" -WHERE - time >= timestamp '2019-09-17T00:00:00Z' - AND time <= timestamp '2019-09-17T01:00:00Z' -GROUP BY - _time, - location -ORDER BY - location, - _time -``` - -{{< expand-wrapper >}}} -{{% expand "View example results" %}} - -The query uses the `COUNT()` function to count the number of `water_level` points per 15 minute interval. -Results are then ordered by location and time. - -| location | _time | count | -| :----------- | :-------------------- | ----: | -| coyote_creek | 2019-09-16T23:45:00Z | 1 | -| coyote_creek | 2019-09-17T00:00:00Z | 2 | -| coyote_creek | 2019-09-17T00:15:00Z | 3 | -| coyote_creek | 2019-09-17T00:30:00Z | 2 | -| coyote_creek | 2019-09-17T00:45:00Z | 3 | -| santa_monica | 2019-09-16T23:45:00Z | 1 | -| santa_monica | 2019-09-17T00:00:00Z | 2 | -| santa_monica | 2019-09-17T00:15:00Z | 3 | -| santa_monica | 2019-09-17T00:30:00Z | 2 | -| santa_monica | 2019-09-17T00:45:00Z | 3 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/having.md b/content/influxdb/clustered/reference/sql/having.md index 6c8846fc2..39307c66c 100644 --- a/content/influxdb/clustered/reference/sql/having.md +++ b/content/influxdb/clustered/reference/sql/having.md @@ -10,78 +10,10 @@ menu: weight: 205 related: - /influxdb/clustered/reference/sql/subqueries/ + +source: /content/shared/sql-reference/having.md --- -The `HAVING` clause places conditions on results created by an aggregate operation on groups. -The `HAVING` clause must follow the `GROUP BY` clause and precede the `ORDER BY` clause. - -{{% note %}} -The `WHERE` clause filters rows based on specified conditions _before_ the aggregate operation. -The `HAVING` clause filters rows based on specified conditions _after_ the aggregate operation has taken place. -{{% /note %}} - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [HAVING_clause] [ORDER_BY_clause] -``` - -## Examples - -### Return rows with an aggregate value greater than a specified number - -```sql -SELECT - MEAN("water_level") AS "mean_water_level", "location" -FROM - "h2o_feet" -GROUP BY - "location" -HAVING - "mean_water_level" > 5 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns on rows with values in the `mean_water_level` greater than 5 _after_ the aggregate operation. - -| location | mean_water_level | -| :----------- | :---------------- | -| coyote_creek | 5.359142420303919 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Return the average result greater than a specified number from a specific time range - -```sql -SELECT - AVG("water_level") AS "avg_water_level", - "time" -FROM - "h2o_feet" -WHERE - time >= '2019-09-01T00:00:00Z' AND time <= '2019-09-02T00:00:00Z' -GROUP BY - "time" -HAVING - "avg_water_level" > 6.82 -ORDER BY - "time" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query calculates the average water level per time and only returns rows with an average greater than 6.82 during the specified time range. - -| time | avg_water_level | -| :------------------- | -----------------: | -| 2019-09-01T22:06:00Z | 6.8225 | -| 2019-09-01T22:12:00Z | 6.8405000000000005 | -| 2019-09-01T22:30:00Z | 6.8505 | -| 2019-09-01T22:36:00Z | 6.8325 | -{{% /expand %}} -{{< /expand-wrapper >}} \ No newline at end of file + diff --git a/content/influxdb/clustered/reference/sql/information-schema.md b/content/influxdb/clustered/reference/sql/information-schema.md index a7cc55e6d..8c2d51c1c 100644 --- a/content/influxdb/clustered/reference/sql/information-schema.md +++ b/content/influxdb/clustered/reference/sql/information-schema.md @@ -7,140 +7,10 @@ menu: influxdb_clustered: parent: SQL reference weight: 210 + +source: /content/shared/sql-reference/information-schema.md --- -The underlying query engine for the InfluxDB SQL implementation, -[DataFusion](https://arrow.apache.org/datafusion/index.html), provides commands -that return metadata related to your data schema. -To access this information, use the `SHOW TABLES`, `SHOW COLUMNS`, and -`SHOW ALL` commands or query views in the [ISO](https://www.iso.org/) SQL -`information_schema` schema. - -In the context of InfluxDB, a [measurement](/influxdb/clustered/reference/glossary/#measurement) -is represented as a table. Time, [tags](/influxdb/clustered/reference/glossary/#tag), -and [fields](/influxdb/clustered/reference/glossary/#field) are each represented -by columns in a table. - -- [SHOW TABLES](#show-tables) - - [Example SHOW TABLES output](#example-show-tables-output) -- [SHOW COLUMNS](#show-columns) - - [Example SHOW COLUMNS output](#example-show-columns-output) -- [SHOW ALL](#show-all) - - [Example SHOW ALL output](#view-show-all-example-output) - -## SHOW TABLES - -Returns information about tables (measurements) in an InfluxDB database. - -```sql -SHOW TABLES -``` - -You can also query the `information_schema.tables` view: - -```sql -SELECT * FROM information_schema.tables -``` - -#### Example SHOW TABLES output - -_Measurements are those that use the **`iox` table schema**._ - -| table_catalog | table_schema | table_name | table_type | -| :------------ | :----------------- | :---------- | :--------- | -| public | iox | home | BASE TABLE | -| public | system | queries | BASE TABLE | -| public | information_schema | tables | VIEW | -| public | information_schema | views | VIEW | -| public | information_schema | columns | VIEW | -| public | information_schema | df_settings | VIEW | - -## SHOW COLUMNS - -Returns information about the schema of a table (measurement) in an InfluxDB database. - -```sql -SHOW COLUMNS FROM example_table -``` - -You can also query the `information_schema.columns` view: - -```sql -SELECT - table_catalog, - table_schema, - table_name, - column_name, - data_type, - is_nullable -FROM information_schema.columns -WHERE table_name = 'example_table' -``` - -#### Example SHOW COLUMNS output - -| table_catalog | table_schema | table_name | column_name | data_type | is_nullable | -| :------------ | :----------- | :--------- | :---------- | :-------------------------- | :---------- | -| public | iox | home | co | Int64 | YES | -| public | iox | home | hum | Float64 | YES | -| public | iox | home | room | Dictionary(Int32, Utf8) | YES | -| public | iox | home | temp | Float64 | YES | -| public | iox | home | time | Timestamp(Nanosecond, None) | NO | - -## SHOW ALL - -Returns the configuration options of the current session. - -```sql -SHOW ALL -``` - -You can also query the `information_schema.df_settings` view: - -```sql -SELECT * FROM information_schema.df_settings -``` - -{{< expand-wrapper >}} -{{% expand "View `SHOW ALL` example output" %}} - -| name | setting | -| :-------------------------------------------------------- | :------- | -| datafusion.catalog.create_default_catalog_and_schema | true | -| datafusion.catalog.default_catalog | public | -| datafusion.catalog.default_schema | iox | -| datafusion.catalog.format | | -| datafusion.catalog.has_header | false | -| datafusion.catalog.information_schema | true | -| datafusion.catalog.location | | -| datafusion.execution.batch_size | 8192 | -| datafusion.execution.coalesce_batches | true | -| datafusion.execution.collect_statistics | false | -| datafusion.execution.parquet.enable_page_index | false | -| datafusion.execution.parquet.metadata_size_hint | | -| datafusion.execution.parquet.pruning | true | -| datafusion.execution.parquet.pushdown_filters | true | -| datafusion.execution.parquet.reorder_filters | true | -| datafusion.execution.parquet.skip_metadata | true | -| datafusion.execution.target_partitions | 4 | -| datafusion.execution.time_zone | +00:00 | -| datafusion.explain.logical_plan_only | false | -| datafusion.explain.physical_plan_only | false | -| datafusion.optimizer.enable_round_robin_repartition | true | -| datafusion.optimizer.filter_null_join_keys | false | -| datafusion.optimizer.hash_join_single_partition_threshold | 1048576 | -| datafusion.optimizer.max_passes | 3 | -| datafusion.optimizer.prefer_hash_join | true | -| datafusion.optimizer.repartition_aggregations | true | -| datafusion.optimizer.repartition_file_min_size | 10485760 | -| datafusion.optimizer.repartition_file_scans | true | -| datafusion.optimizer.repartition_joins | true | -| datafusion.optimizer.repartition_sorts | false | -| datafusion.optimizer.repartition_windows | true | -| datafusion.optimizer.skip_failed_rules | true | -| datafusion.optimizer.top_down_join_key_reordering | true | -| datafusion.sql_parser.enable_ident_normalization | true | -| datafusion.sql_parser.parse_float_as_decimal | false | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/join.md b/content/influxdb/clustered/reference/sql/join.md index f4e3b7d25..482daecb9 100644 --- a/content/influxdb/clustered/reference/sql/join.md +++ b/content/influxdb/clustered/reference/sql/join.md @@ -7,267 +7,10 @@ menu: name: JOIN clause parent: SQL reference weight: 202 + +source: /content/shared/sql-reference/join.md --- -Use the `JOIN` clause to join data from different tables together based on -logical relationships. - -- [Syntax](#syntax) -- [Join types](#join-types) - - [INNER JOIN](#inner-join) - - [LEFT [OUTER] JOIN](#left-outer-join) - - [RIGHT [OUTER] JOIN](#right-outer-join) - - [FULL [OUTER] JOIN](#full-outer-join) -- [Troubleshoot joins](#troubleshoot-joins) - -## Syntax - -```sql -SELECT_clause -FROM -[INNER | LEFT [OUTER] | RIGHT [OUTER] | FULL [OUTER]] JOIN -ON -[WHERE_clause] -[GROUP_BY_clause] -[HAVING_clause] -[ORDER_BY_clause] -``` - -### Arguments - -- **left_join_items**: One or more tables specified in the `FROM` clause that - represent the left side of the join. -- **right_join_items**: One or more tables specified in the `JOIN` clause that - represent the right side of the join. -- **join_condition**: A predicate expression in the `ON` clause that uses the - `=` (equal to) comparison operator to compare column values from the left side - of the join to column values on the right side of the join. Rows with values - that match the defined predicate are joined using the specified - [join type](#join-types). - - -
- -{{% note %}} -If both sides of the join include columns with the same name, you need to -use the fully-qualified reference to prevent ambiguity. -A _fully-qualified reference_ uses dot notation to reference both the table name -and the column name--for example: `table_name.column_name` -{{% /note %}} - -## Join types - -The following joins types are supported: - -{{< flex >}} -{{< flex-content "quarter" >}} - -

INNER JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="inner small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

LEFT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="left small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

RIGHT [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="right small center" >}} -
-{{< /flex-content >}} -{{< flex-content "quarter" >}} - -

FULL [OUTER] JOIN

- {{< svg svg="static/svgs/join-diagram.svg" class="full small center" >}} -
-{{< /flex-content >}} -{{< /flex >}} - -#### Join sample tables - -The examples below illustrate join methods using the following tables: - -{{% influxdb/custom-timestamps %}} - -##### prod_line - -| time | station | produced | -| :------------------- | :-----: | -------: | -| 2022-01-01T08:00:00Z | B1 | 26 | -| 2022-01-01T09:00:00Z | B1 | 54 | -| 2022-01-01T10:00:00Z | B1 | 56 | -| 2022-01-01T11:00:00Z | B1 | | -| 2022-01-01T12:00:00Z | B1 | 82 | - -##### errors - -| time | station | level | message | -| :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### INNER JOIN - -Inner joins combine rows from tables on the left and right side of the join -based on common column values defined in the `ON` clause. Rows that don't have -matching column values are not included in the output table. - -{{% influxdb/custom-timestamps %}} - -#### Inner join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -RIGHT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` -##### Inner join results - -| time | station | produced | time | station | level | message | -| :------------------- | :-----: | -------: | :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### LEFT [OUTER] JOIN - -A left outer join returns all rows from the left side of the join and only -returns data from the right side of the join in rows with matching column values -defined in the `ON` clause. - -{{% influxdb/custom-timestamps %}} - -#### Left outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -LEFT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` - -##### Left outer join results - -| time | station | produced | time | station | level | message | -| -------------------- | ------- | -------- | -------------------- | ------- | ----- | -------------------- | -| 2022-01-01T08:00:00Z | B1 | 26 | | | | | -| 2022-01-01T09:00:00Z | B1 | 54 | | | | | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | -| 2022-01-01T12:00:00Z | B1 | 82 | | | | | - -{{% /influxdb/custom-timestamps %}} - - -### RIGHT [OUTER] JOIN - -A right outer join returns all rows from the right side of the join and only -returns data from the left side of the join in rows with matching column values -defined in the `ON` clause. - -{{% influxdb/custom-timestamps %}} - -#### Right outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -RIGHT JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - prod_line.time -``` - -##### Right outer join results - -| time | station | produced | time | station | level | message | -| :------------------- | :-----: | -------: | :------------------- | :-----: | :---: | :------------------- | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | - -{{% /influxdb/custom-timestamps %}} - -### FULL [OUTER] JOIN - -A full outer join returns all data from the left and right sides of the join and -combines rows with matching column values defined in the `ON` clause. -Data that is not available on each respective side of the join is NULL. - -{{% influxdb/custom-timestamps %}} - -#### Full outer join example - -{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} - -```sql -SELECT - * -FROM - prod_line -FULL JOIN errors ON - prod_line.time = errors.time - AND prod_line.station = errors.station -ORDER BY - time -``` - -##### Full outer join results - -| time | station | produced | time | station | level | message | -| -------------------- | ------- | -------- | -------------------- | ------- | ----- | -------------------- | -| 2022-01-01T08:00:00Z | B1 | 26 | | | | | -| 2022-01-01T09:00:00Z | B1 | 54 | | | | | -| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | -| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | -| 2022-01-01T12:00:00Z | B1 | 82 | | | | | - -{{% /influxdb/custom-timestamps %}} - -## Troubleshoot joins - -### Ambiguous reference to unqualified field - -If a column exists on both sides of the join and is used in in the `SELECT`, -`ON`, `WHERE`, `HAVING`, `GROUP BY`, or `ORDER BY` clause, you must use a -[fully-qualified reference](#fully-qualified-reference). For example, if both -sides of the join have a `time` column and you want to explicitly select a -time column, you must specifiy which side of the join to use the time column from: - -{{% code-callout "prod_line.time" "green" %}} -``` -SELECT - prod_line.time, - produced, - message, -FROM - prod_line -INNER JOIN errors ON - -- ... -``` -{{% /code-callout %}} \ No newline at end of file + diff --git a/content/influxdb/clustered/reference/sql/limit.md b/content/influxdb/clustered/reference/sql/limit.md index 4063a214f..4aaaef74f 100644 --- a/content/influxdb/clustered/reference/sql/limit.md +++ b/content/influxdb/clustered/reference/sql/limit.md @@ -7,70 +7,10 @@ menu: name: LIMIT clause parent: SQL reference weight: 206 + +source: /content/shared/sql-reference/limit.md --- -The `LIMIT` clause limits the number of rows returned by a query to a specified non-negative integer. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT -``` - -## Examples - -### Limit results to a maximum of five rows - -```sql -SELECT - "water_level","location", "time" -FROM - "h2o_feet" -LIMIT - 5 -``` -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns a maximum of 5 results. - -| location | time | water_level | -| :----------- | :----------------------- | ----------- | -| coyote_creek | 2019-08-28T00:00:00.000Z | 4.206 | -| coyote_creek | 2019-08-28T00:06:00.000Z | 4.052 | -| coyote_creek | 2019-08-28T00:12:00.000Z | 3.901 | -| coyote_creek | 2019-08-28T00:18:00.000Z | 3.773 | -| coyote_creek | 2019-08-28T00:24:00.000Z | 3.632 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Sort and limit results - -Use the `ORDER BY` and `LIMIT` clauses to first sort results by specified columns, -then limit the sorted results by a specified number. - -```sql -SELECT - "water_level", "location", "time" -FROM - "h2o_feet" -ORDER BY - "water_level" DESC -LIMIT - 3 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query returns the highest 3 `water_level` readings in the `h2o_feet` measurement. - -| location | time | water_level | -| :----------- | :----------------------- | ----------- | -| coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | -| coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | -| coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | -{{% /expand %}} -{{< /expand-wrapper >}} - + diff --git a/content/influxdb/clustered/reference/sql/operators/_index.md b/content/influxdb/clustered/reference/sql/operators/_index.md index e383f2ecc..26419deaf 100644 --- a/content/influxdb/clustered/reference/sql/operators/_index.md +++ b/content/influxdb/clustered/reference/sql/operators/_index.md @@ -8,11 +8,10 @@ menu: name: Operators parent: SQL reference weight: 211 + +source: /content/shared/sql-reference/operators/_index.md --- -SQL operators are reserved words or characters which perform certain operations, -including comparisons and arithmetic. - -{{< children type="anchored-list" >}} - -{{< children hlevel="h2" >}} + diff --git a/content/influxdb/clustered/reference/sql/operators/arithmetic.md b/content/influxdb/clustered/reference/sql/operators/arithmetic.md index 976da50c0..e3fe163f4 100644 --- a/content/influxdb/clustered/reference/sql/operators/arithmetic.md +++ b/content/influxdb/clustered/reference/sql/operators/arithmetic.md @@ -17,140 +17,10 @@ list_code_example: | | `*` | Multiplication | `2 * 3` | `6` | | `/` | Division | `6 / 3` | `2` | | `%` | Modulo | `7 % 2` | `1` | + +source: /content/shared/sql-reference/operators/arithmetic.md --- -Arithmetic operators take two numeric values (either literals or variables) -and perform a calculation that returns a single numeric value. - -| Operator | Description | | -| :------: | :------------- | :------------------------------------- | -| `+` | Addition | [{{< icon "link" >}}](#addition) | -| `-` | Subtraction | [{{< icon "link" >}}](#subtraction) | -| `*` | Multiplication | [{{< icon "link" >}}](#multiplication) | -| `/` | Division | [{{< icon "link" >}}](#division) | -| `%` | Modulo | [{{< icon "link" >}}](#modulo) | - -## + {#addition .monospace} - -The `+` operator adds two operands together and returns the sum. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 + 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(1) + int64(2) | -| ------------------: | -| 3 | - -{{% /flex-content %}} -{{< /flex >}} - -## - {#subtraction .monospace} - -The `-` operator subtracts the right operand from the left operand and returns -the difference. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 4 - 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(4) - int64(2) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -## * {#multiplication .monospace} - -The `*` operator multiplies two operands together and returns the product. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 2 * 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(2) * int64(3) | -| ------------------: | -| 6 | - -{{% /flex-content %}} -{{< /flex >}} - -## / {#division .monospace} - -The `/` operator divides the left operand by the right operand and returns the quotient. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 6 / 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| int64(6) / int64(3) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -## % {#modulo .monospace} - -The `%` (modulo) operator divides the left operand by the right operand and returns the -remainder. If the left operand is not divisible by the right operand, it returns -the left operand. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 8 % 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(8) % Int64(3) | -| ------------------: | -| 2 | - -{{% /flex-content %}} -{{< /flex >}} - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 % 8 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) % Int64(8) | -| ------------------: | -| 3 | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/clustered/reference/sql/operators/bitwise.md b/content/influxdb/clustered/reference/sql/operators/bitwise.md index bf63972c9..cc738db92 100644 --- a/content/influxdb/clustered/reference/sql/operators/bitwise.md +++ b/content/influxdb/clustered/reference/sql/operators/bitwise.md @@ -16,137 +16,10 @@ list_code_example: | | `^` | Bitwise xor | `5 ^ 3` | `6` | | `>>` | Bitwise shift right | `5 >> 3` | `0` | | `<<` | Bitwise shift left | `5 << 3` | `40` | + +source: /content/shared/sql-reference/operators/bitwise.md --- -Bitwise operators perform bitwise operations on bit patterns or binary numerals. - -| Operator | Meaning | | -| :------: | :------------------ | :------------------------------------------ | -| `&` | Bitwise and | [{{< icon "link" >}}](#bitwise-and) | -| `\|` | Bitwise or | [{{< icon "link" >}}](#bitwise-or) | -| `^` | Bitwise xor | [{{< icon "link" >}}](#bitwise-xor) | -| `>>` | Bitwise shift right | [{{< icon "link" >}}](#bitwise-shift-right) | -| `<<` | Bitwise shift left | [{{< icon "link" >}}](#bitwise-shift-left) | - -## & {#bitwise-and .monospace} - -The `&` (bitwise AND) operator compares each bit of the left operand to the -corresponding bit of the right operand. -If both bits are 1, the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 & 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) & Int64(3) | -| ------------------: | -| 1 | - -{{% /flex-content %}} -{{< /flex >}} - -## \| {#bitwise-or .monospace} - -The `|` (bitwise OR or inclusive OR) operator compares each bit of the left -operand to the corresponding bit of the right operand. -If either bit is 1, the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 | 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \| Int64(3) | -| -------------------: | -| 7 | - -{{% /flex-content %}} -{{< /flex >}} - -## ^ {#bitwise-xor .monospace} - -The `^` (bitwise XOR or exclusive OR) operator compares each bit of the left -operand to the corresponding bit of the right operand. -If the bit in one of the operands is 0 and the bit in the other operand is 1, -the corresponding result bit is set to 1. -Otherwise, the corresponding result bit is set to 0. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 ^ 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) BIT_XOR Int64(3) | -| ------------------------: | -| 6 | - -{{% /flex-content %}} -{{< /flex >}} - -## \>\> {#bitwise-shift-right .monospace} - -The `>>` (bitwise shift right) operator shifts the bits in the left operand to -the right by the number of positions specified in the right operand. -For unsigned numbers, bit positions vacated by the shift operation are filled with 0. -For signed numbers, the sign bit is used to fill the vacated bit positions. -If the number is positive, the bit position is filled with 0. -If the number is negative, the bit position is filled with 1. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 >> 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \>\> Int64(3) | -| ---------------------: | -| 0 | - -{{% /flex-content %}} -{{< /flex >}} - -## \<\< {#bitwise-shift-left .monospace} - -The `<<` (bitwise shift left) operator shifts the bits in the left operand to -the left by the number of positions specified in the right operand. -Bit positions vacated by the shift operation are filled with 0. -Bits that shift off the end are discarded, including the sign bit. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 5 << 3 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(5) \<\< Int64(3) | -| ---------------------: | -| 40 | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/clustered/reference/sql/operators/comparison.md b/content/influxdb/clustered/reference/sql/operators/comparison.md index 540ab6bfc..1b8025755 100644 --- a/content/influxdb/clustered/reference/sql/operators/comparison.md +++ b/content/influxdb/clustered/reference/sql/operators/comparison.md @@ -23,267 +23,10 @@ list_code_example: | | `~*` | Matches a regular expression _(case-insensitive)_ | `'Abc' ~* 'A.*'` | | `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | | `!~*` | Does not match a regular expression _(case-insensitive)_ | `'Abc' !~* 'a.*'` | + +source: /content/shared/sql-reference/operators/comparison.md --- -Comparison operators evaluate the relationship between the left and right -operands and returns `true` or `false`. - - -| Operator | Meaning | | -| :------: | :------------------------------------------------------- | :------------------------------------------------------ | -| `=` | Equal to | [{{< icon "link" >}}](#equal-to) | -| `<>` | Not equal to | [{{< icon "link" >}}](#not-equal-to) | -| `!=` | Not equal to | [{{< icon "link" >}}](#not-equal-to) | -| `>` | Greater than | [{{< icon "link" >}}](#greater-than) | -| `>=` | Greater than or equal to | [{{< icon "link" >}}](#greater-than-or-equal) | -| `<` | Less than | [{{< icon "link" >}}](#less-than) | -| `<=` | Less than or equal to | [{{< icon "link" >}}](#less-than-or-equal) | -| `~` | Matches a regular expression | [{{< icon "link" >}}](#regexp-match) | -| `~*` | Matches a regular expression _(case-insensitive)_ | [{{< icon "link" >}}](#regexp-match-case-insensitive) | -| `!~` | Does not match a regular expression | [{{< icon "link" >}}](#regexp-nomatch) | -| `!~*` | Does not match a regular expression _(case-insensitive)_ | [{{< icon "link" >}}](#regexp-nomatch-case-insensitive) | - -## = {#equal-to .monospace} - -The `=` operator compares the left and right operands and, if equal, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 = 123 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) = Int64(123) | -| :---------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !=, <> {#not-equal-to .monospace} - -The `!=` and `<>` operators compare the left and right operands and, if not equal, -returns `true`. Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 != 456 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) != Int64(456) | -| :----------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 123 <> 456 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(123) != Int64(456) | -| :----------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## > {#greater-than .monospace} - -The `>` operator compares the left and right operands and, if the left operand -is greater than the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 > 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) > Int64(2) | -| :------------------ | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## >= {#greater-than-or-equal .monospace} - -The `>=` operator compares the left and right operands and, if the left operand -is greater than or equal to the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 3 >= 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int64(3) >= Int64(2) | -| :------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## < {#less-than .monospace} - -The `<` operator compares the left and right operands and, if the left operand -is less than the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 < 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int641(1) < Int64(2) | -| :------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## <= {#less-than-or-equal .monospace} - -The `<=` operator compares the left and right operands and, if the left operand -is less than or equal to the right operand, returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 1 <= 2 -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Int641(1) <= Int64(2) | -| :-------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## ~ {#regexp-match .monospace} - -The `~` operator compares the left string operand to the right regular expression -operand and, if it matches (case-sensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'abc' ~ 'a.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("abc") ~ Utf8("a.*") | -| :------------------------ | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## ~* {#regexp-match-case-insensitive .monospace} - -The `~*` operator compares the left string operand to the right regular expression -operand and, if it matches (case-insensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Abc' ~* 'A.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("Abc") ~* Utf8("A.*") | -| :------------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !~ {#regexp-nomatch .monospace} - -The `!~` operator compares the left string operand to the right regular expression -operand and, if it does not match (case-sensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'abc' !~ 'd.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("abc") !~ Utf8("d.*") | -| :------------------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -## !~* {#regexp-nomatch-case-insensitive .monospace} - -The `!~*` operator compares the left string operand to the right regular expression -operand and, if it does not match (case-insensitive), returns `true`. -Otherwise returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Abc' !~* 'a.*' -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Utf8("Abc") !~* Utf8("a.*") | -| :-------------------------- | -| false | - -{{% /flex-content %}} -{{< /flex >}} + diff --git a/content/influxdb/clustered/reference/sql/operators/logical.md b/content/influxdb/clustered/reference/sql/operators/logical.md index 3ffeb1584..d5adf9106 100644 --- a/content/influxdb/clustered/reference/sql/operators/logical.md +++ b/content/influxdb/clustered/reference/sql/operators/logical.md @@ -21,443 +21,10 @@ list_code_example: | | `LIKE` | Returns true if the left operand matches the right operand pattern string. | | `NOT` | Negates the subsequent expression. | | `OR` | Returns true if any operand is true. Otherwise, returns false. | + +source: /content/shared/sql-reference/operators/logical.md --- -Logical operators combine or manipulate conditions in a SQL query. - -| Operator | Meaning | | -| :-------: | :------------------------------------------------------------------------- | :------------------------------ | -| `AND` | Returns true if both operands are true. Otherwise, returns false. | [{{< icon "link" >}}](#and) | -| `BETWEEN` | Returns true if the left operand is within the range of the right operand. | [{{< icon "link" >}}](#between) | -| `EXISTS` | Returns true if the results of a subquery are not empty. | [{{< icon "link" >}}](#exists) | -| `IN` | Returns true if the left operand is in the right operand list. | [{{< icon "link" >}}](#in) | -| `LIKE` | Returns true if the left operand matches the right operand pattern string. | [{{< icon "link" >}}](#like) | -| `NOT` | Negates the subsequent expression. | [{{< icon "link" >}}](#not) | -| `OR` | Returns true if any operand is true. Otherwise, returns false. | [{{< icon "link" >}}](#or) | - -{{% note %}} -#### Sample data - -Query examples on this page use the following sample data sets: - -- [Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data) -- [Home sensor actions sample data](/influxdb/clustered/reference/sample-data/#home-sensor-actions-data) -{{% /note %}} - -## AND {.monospace} - -The `AND` operand returns `true` if both operands are `true`. Otherwise, it returns false. -This operator is typically used in the [`WHERE` clause](/influxdb/clustered/reference/sql/where/) -to combine multiple conditions. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT true AND false AS "AND condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| AND condition | -| :------------ | -| false | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`AND` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co > 10 - AND room = 'Kitchen' -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## BETWEEN {.monospace} - -The `BETWEEN` operator returns `true` if the left numeric operand is within the -range specified in the right operand. Otherwise, it returns `false` - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 6 BETWEEN 5 AND 8 AS "BETWEEN condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| BETWEEN condition | -| :---------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`BETWEEN` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co BETWEEN 5 AND 10 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## EXISTS {.monospace} - -The `EXISTS` operator returns `true` if result of a -[correlated subquery](/influxdb/clustered/reference/sql/subqueries/#correlated-subqueries) -is not empty. Otherwise it returns `false`. - -_See [SQL subquery operators](/influxdb/clustered/reference/sql/subqueries/#subquery-operators)._ - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`EXISTS` operator with a subquery in the `WHERE` clause" %}} - -```sql -SELECT * -FROM - home home_actions -WHERE EXISTS ( - SELECT * - FROM home - WHERE - home.co = home_actions.co - 1 -) -ORDER BY time -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | -| 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | -| 1 | 36.1 | Living Room | 22.3 | 2022-01-01T15:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## IN {.monospace} - -The `IN` operator returns `true` if the left operand is in the right operand -list or subquery result. Otherwise, it returns `false`. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'John' IN ('Jane', 'John') AS "IN condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| IN condition | -| :----------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -_See [SQL subquery operators](/influxdb/clustered/reference/sql/subqueries/#subquery-operators)._ - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`IN` operator with a list in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room IN ('Bathroom', 'Bedroom', 'Kitchen') -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`IN` operator with a subquery in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room IN ( - SELECT DISTINCT room - FROM home_actions - ) -ORDER BY time -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## LIKE {.monospace} - -The `LIKE` operator returns `true` if the left operand matches the string pattern -specified in the right operand. -`LIKE` expressions support [SQL wildcard characters](#sql-wildcard-characters). - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'John' LIKE 'J_%n' AS "LIKE condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| LIKE condition | -| :------------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -{{< expand-wrapper >}} -{{% expand "`LIKE` operator in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - room LIKE '%Room' -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -### SQL wildcard characters - -The InfluxDB SQL implementation supports the following wildcard characters when -using the `LIKE` operator to match strings to a pattern. - -| Character | Description | -| :-------: | :--------------------------------- | -| `%` | Represents zero or more characters | -| `_` | Represents any single character | - -## NOT {.monospace} - -The `NOT` operator negates the subsequent expression. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT NOT true AS "NOT condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| NOT condition | -| :------------ | -| false | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`NOT IN`" %}} - -```sql -SELECT * -FROM home -WHERE - room NOT IN ('Kitchen', 'Bathroom') -LIMIT 4 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "`NOT EXISTS`" %}} - -```sql -SELECT * -FROM - home home_actions -WHERE NOT EXISTS ( - SELECT * - FROM home - WHERE - home.co = home_actions.co + 4 -) -ORDER BY time -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} - -{{% expand "`NOT BETWEEN`" %}} - -```sql -SELECT * -FROM home -WHERE - co NOT BETWEEN 1 AND 22 - AND room = 'Kitchen' -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} - -## OR {.monospace} - -The `OR` operator returns `true` if any operand is `true`. -Otherwise, it returns `false`. -This operator is typically used in the [`WHERE` clause](/influxdb/clustered/reference/sql/where/) -to combine multiple conditions. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT true OR false AS "OR condition" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| OR condition | -| :----------- | -| true | - -{{% /flex-content %}} -{{< /flex >}} - -##### Examples - -{{< expand-wrapper >}} -{{% expand "`OR` in the `WHERE` clause" %}} - -```sql -SELECT * -FROM home -WHERE - co > 20 - OR temp > 23 -``` - -{{% influxdb/custom-timestamps %}} - -| co | hum | room | temp | time | -| --: | ---: | :------ | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | - -{{% /influxdb/custom-timestamps %}} -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/operators/other.md b/content/influxdb/clustered/reference/sql/operators/other.md index 837f67cf1..236738372 100644 --- a/content/influxdb/clustered/reference/sql/operators/other.md +++ b/content/influxdb/clustered/reference/sql/operators/other.md @@ -13,51 +13,10 @@ list_code_example: | | :------------: | :----------------------- | :-------------------------------------- | :------------ | | `\|\|` | Concatenate strings | `'Hello' \|\| ' world'` | `Hello world` | | `AT TIME ZONE` | Apply a time zone offset | _[View example](/influxdb/clustered/reference/sql/operators/other/#at-time-zone)_ | | + +source: /content/shared/sql-reference/operators/other.md --- -SQL supports miscellaneous operators that perform various operations. - -| Operator | Meaning | | -| :------: | :------------------ | :------------------------------------------ | -| `\|\|` | Concatenate strings | [{{< icon "link" >}}](#concatenate-strings) | - -## || {#concatenate-strings} - -The `||` operator concatenates two string operands into a single string. - -{{< flex >}} -{{% flex-content "two-thirds operator-example" %}} - -```sql -SELECT 'Hello' || ' world' AS "Concatenated" -``` - -{{% /flex-content %}} -{{% flex-content "third operator-example" %}} - -| Concatenated | -| :----------- | -| Hello world | - -{{% /flex-content %}} -{{< /flex >}} - -## AT TIME ZONE - -The `AT TIME ZONE` operator applies the offset of the specified time zone to a -timestamp type and returns an updated UTC timestamp. Time zone offsets are -provided by the the operating system time zone database. - -{{% note %}} -Timestamp types in InfluxDB always represent a UTC time. The returned timestamp -is a UTC timestamp adjusted for the offset of the specified time zone. -{{% /note %}} - -```sql -SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'UTC with TZ offset' -``` - -| UTC with TZ offset | -| :----------------------- | -| 2024-01-01T08:00:00.000Z | + diff --git a/content/influxdb/clustered/reference/sql/order-by.md b/content/influxdb/clustered/reference/sql/order-by.md index 4e3eb2939..4851edd37 100644 --- a/content/influxdb/clustered/reference/sql/order-by.md +++ b/content/influxdb/clustered/reference/sql/order-by.md @@ -8,91 +8,10 @@ menu: name: ORDER BY clause parent: SQL reference weight: 204 + +source: /content/shared/sql-reference/order-by.md --- -The `ORDER BY` clause sort results by specified columns and order. -Sort data based on fields, tags, and timestamps. -The following orders are supported: - -- `ASC`: ascending _(default)_ -- `DESC`: descending - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -[SELECT CLAUSE] [FROM CLAUSE] [ ORDER BY expression [ ASC | DESC ][, …] ] -``` - -{{% note %}} -**Note:** If your query includes a `GROUP BY` clause, the `ORDER BY` clause must appear **after** the `GROUP BY` clause. -{{% /note %}} - -## Examples - -### Sort data by time with the most recent first - -```sql -SELECT - "water_level", "time" -FROM - "h2o_feet" -WHERE - "location" = 'coyote_creek' -ORDER BY - time DESC -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -| time | water_level | -| :----------------------- | :----------- | -| 2019-09-17T16:24:00.000Z | 3.235 | -| 2019-09-17T16:18:00.000Z | 3.314 | -| 2019-09-17T16:12:00.000Z | 3.402 | -| 2019-09-17T16:06:00.000Z | 3.497 | -| 2019-09-17T16:00:00.000Z | 3.599 | -| 2019-09-17T15:54:00.000Z | 3.704 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Sort data by tag or field values - -```sql -SELECT - "water_level", "time", "location" -FROM - "h2o_feet" -ORDER BY - "location", "water_level" DESC -``` - -### Sort data by selection order - -```sql -SELECT - "location","water_level", "time" -FROM - "h2o_feet" -ORDER BY - 1, 2 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -The query sorts results the location of a column in the `SELECT` statement: -first by `location` (1), and second by `water_level` (2). - -| location | time | water_level | -| :----------- | :----------------------- | :---------- | -| coyote_creek | 2019-08-28T14:30:00.000Z | -0.61 | -| coyote_creek | 2019-08-29T15:18:00.000Z | -0.594 | -| coyote_creek | 2019-08-28T14:36:00.000Z | -0.591 | -| coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | -| coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | -| coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/select.md b/content/influxdb/clustered/reference/sql/select.md index 446a1cb66..705308bfe 100644 --- a/content/influxdb/clustered/reference/sql/select.md +++ b/content/influxdb/clustered/reference/sql/select.md @@ -9,106 +9,10 @@ menu: weight: 201 related: - /influxdb/clustered/reference/sql/subqueries/ + +source: /content/shared/sql-reference/select.md --- -Use the `SELECT` statement to query data from an InfluxDB measurement. -The `SELECT` clause is required when querying data in SQL. - -- [Syntax](#syntax) -- [Examples](#examples) - -### Syntax - -```sql -SELECT a, b, "time" FROM -``` - -{{% note %}} -**Note:** When querying InfluxDB, the `SELECT` statement **always requires** a `FROM` clause. -{{% /note %}} - -The SELECT clause supports the following: - - - `SELECT *` - return all tags, fields and timestamps. - - `SELECT DISTINCT` to return all distinct (different) values. - - `SELECT <"field" or "tag">` - returns a specified field or tag. - - `SELECT <"field" or "tag">, <"field" or "tag">` - returns more than one tag or field. - - `SELECT <"field"> AS a `- return the field as the alias. - -## Examples - -The following examples use data from the NOAA database. -To download the NOAA test data see [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). - -### Select all fields and tags from a measurement - -```sql -SELECT * FROM h2o_feet LIMIT 10 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} -| level description | location | time | water_level | -| :------------------------ | :----------- | :----------------------- | :---------- | -| at or greater than 9 feet | coyote_creek | 2019-09-01T00:00:00.000Z | 9.126144144 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T00:06:00.000Z | 9.009 | -| between 6 and 9 feet | coyote_creek | 2019-09-01T00:12:00.000Z | 8.862 | -| between 6 and 9 feet | coyote_creek | 2019-09-01T00:18:00.000Z | 8.714 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select specific tags and fields from a measurement - -```sql -SELECT "location", "water_level" FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "1" %}} -| location | water_level | -| :----------- | :---------- | -| coyote_creek | 9.126144144 | -| coyote_creek | 9.009 | -| coyote_creek | 8.862 | -| coyote_creek | 8.714 | -| coyote_creek | 8.547 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select a field, tag and timestamp from a measurement - -```sql -SELECT "water_level", "location", "time" FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "2" %}} -| location | time | water_level | -| :----------- | :----------------------- | :---------- | -| coyote_creek | 2019-08-20T00:00:00.000Z | 8.638 | -| coyote_creek | 2019-08-20T00:06:00.000Z | 8.658 | -| coyote_creek | 2019-08-20T00:12:00.000Z | 8.678 | -{{% /expand %}} -{{< /expand-wrapper >}} - -### Select a field and perform basic arithmetic - -The following query takes the value of water_level, multiplies it by 3 and adds 5 to the result. - -```sql -SELECT ("water_level" * 3) + 5 FROM "h2o_feet" -``` - -{{< expand-wrapper >}} -{{% expand "View example results" "3" %}} -| water_level | -| :----------------- | -| 30.128 | -| 30.641000000000002 | -| 31.142000000000003 | -| 31.586 | -| 32.027 | -| 32.378432432 | -{{% /expand %}} -{{< /expand-wrapper >}} - + diff --git a/content/influxdb/clustered/reference/sql/subqueries.md b/content/influxdb/clustered/reference/sql/subqueries.md index ab6ff4d2b..f6ca315f7 100644 --- a/content/influxdb/clustered/reference/sql/subqueries.md +++ b/content/influxdb/clustered/reference/sql/subqueries.md @@ -13,747 +13,10 @@ related: - /influxdb/clustered/reference/sql/select/ - /influxdb/clustered/reference/sql/where/ - /influxdb/clustered/reference/sql/having/ + +source: /content/shared/sql-reference/subqueries.md --- -Subqueries (also known as inner queries or nested queries) are queries within -a query. -Subqueries can be used in `SELECT`, `FROM`, `WHERE`, and `HAVING` clauses. - -- [Subquery operators](#subquery-operators) - - [[ NOT ] EXISTS](#-not--exists) - - [[ NOT ] IN](#-not--in) -- [SELECT clause subqueries](#select-clause-subqueries) -- [FROM clause subqueries](#from-clause-subqueries) -- [WHERE clause subqueries](#where-clause-subqueries) -- [HAVING clause subqueries](#having-clause-subqueries) -- [Subquery categories](#subquery-categories) - - [Correlated subqueries](#correlated-subqueries) - - [Non-correlated subqueries](#non-correlated-subqueries) - - [Scalar subqueries](#scalar-subqueries) - - [Non-scalar subqueries](#non-scalar-subqueries) - -{{% note %}} -#### Sample data - -Query examples on this page use the following sample data sets: - -- [Get started home sensor sample data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data) -- [Home sensor actions sample data](/influxdb/clustered/reference/sample-data/#home-sensor-actions-data) -- [NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data) - -{{% /note %}} - -## Subquery operators - -- [[ NOT ] EXISTS](#-not--exists) -- [[ NOT ] IN](#-not--in) - -### [ NOT ] EXISTS - -The `EXISTS` operator returns all rows where a -_[correlated subquery](#correlated-subquery)_ produces one or more matches for -that row. `NOT EXISTS` returns all rows where a _correlated subquery_ produces -zero matches for that row. Only _correlated subqueries_ are supported. - -#### Syntax {#-not-exists-syntax} - -```sql -[NOT] EXISTS (subquery) -``` - -### [ NOT ] IN - -The `IN` operator returns all rows where a given expression’s value can be found -in the results of a _[correlated subquery](#correlated-subqueries)_. -`NOT IN` returns all rows where a given expression’s value cannot be found in -the results of a subquery or list of values. - -#### Syntax {#-not-in-syntax} - -```sql -expression [NOT] IN (subquery|list-literal) -``` - -#### Examples {#-not-in-examples} - -{{< expand-wrapper >}} -{{% expand "View `IN` examples using a query" %}} -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[IN](#) -[NOT IN](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - room IN ( - SELECT - DISTINCT room - FROM - home_actions - ) -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - room NOT IN ( - SELECT - DISTINCT room - FROM - home_actions - ) -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} -{{% /expand %}} - -{{% expand "View `IN` examples using a list literal" %}} -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[IN](#) -[NOT IN](#) -{{% /code-tabs %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM home -WHERE room IN ('Bathroom', 'Bedroom', 'Kitchen') -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```sql -SELECT - time, - room, - temp -FROM home -WHERE room NOT IN ('Bathroom', 'Bedroom', 'Kitchen') -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} -{{% /expand %}} - -{{< /expand-wrapper >}} - -## SELECT clause subqueries - -`SELECT` clause subqueries use values returned from the inner query as part -of the outer query's `SELECT` list. -The `SELECT` clause only supports [scalar subqueries](#scalar-subqueries) that -return a single value per execution of the inner query. -The returned value can be unique per row. - -### Syntax {#select-subquery-syntax} - -```sql -SELECT [expression1[, expression2, ..., expressionN],] () -``` - -{{% note %}} -`SELECT` clause subqueries can be used as an alternative to `JOIN` operations. -{{% /note %}} - -### Examples {#select-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "`SELECT` clause with correlated subquery" %}} - -```sql -SELECT - time, - room, - co, - ( - SELECT - MAX(description) - FROM - home_actions - WHERE - time = home.time - AND room = home.room - AND level != 'ok' - ) AS "Alert Description" -FROM - home -ORDER BY - room, - time -``` - -#### Inner query results - -Because the inner query is a [correlated subquery](#correlated-subqueries), -the result depends on the values of `room` and `time` columns in the outer query. -The results below represent the action description for each `room` and `time` -combination with a `level` value that does not equal `ok`. - -{{% influxdb/custom-timestamps %}} -| time | room | MAX(home_actions.description) | -| :------------------- | :---------- | :------------------------------------------ | -| 2022-01-01T18:00:00Z | Kitchen | Carbon monoxide level above normal: 18 ppm. | -| 2022-01-01T19:00:00Z | Kitchen | Carbon monoxide level above normal: 22 ppm. | -| 2022-01-01T20:00:00Z | Kitchen | Carbon monoxide level above normal: 26 ppm. | -| 2022-01-01T19:00:00Z | Living Room | Carbon monoxide level above normal: 14 ppm. | -| 2022-01-01T20:00:00Z | Living Room | Carbon monoxide level above normal: 17 ppm. | -{{% /influxdb/custom-timestamps %}} - -#### Outer query results - -{{% influxdb/custom-timestamps %}} -| time | room | co | Alert Description | -| :------------------- | :---------- | --: | :------------------------------------------ | -| 2022-01-01T08:00:00Z | Kitchen | 0 | | -| 2022-01-01T09:00:00Z | Kitchen | 0 | | -| 2022-01-01T10:00:00Z | Kitchen | 0 | | -| 2022-01-01T11:00:00Z | Kitchen | 0 | | -| 2022-01-01T12:00:00Z | Kitchen | 0 | | -| 2022-01-01T13:00:00Z | Kitchen | 1 | | -| 2022-01-01T14:00:00Z | Kitchen | 1 | | -| 2022-01-01T15:00:00Z | Kitchen | 3 | | -| 2022-01-01T16:00:00Z | Kitchen | 7 | | -| 2022-01-01T17:00:00Z | Kitchen | 9 | | -| 2022-01-01T18:00:00Z | Kitchen | 18 | Carbon monoxide level above normal: 18 ppm. | -| 2022-01-01T19:00:00Z | Kitchen | 22 | Carbon monoxide level above normal: 22 ppm. | -| 2022-01-01T20:00:00Z | Kitchen | 26 | Carbon monoxide level above normal: 26 ppm. | -| 2022-01-01T08:00:00Z | Living Room | 0 | | -| 2022-01-01T09:00:00Z | Living Room | 0 | | -| 2022-01-01T10:00:00Z | Living Room | 0 | | -| 2022-01-01T11:00:00Z | Living Room | 0 | | -| 2022-01-01T12:00:00Z | Living Room | 0 | | -| 2022-01-01T13:00:00Z | Living Room | 0 | | -| 2022-01-01T14:00:00Z | Living Room | 0 | | -| 2022-01-01T15:00:00Z | Living Room | 1 | | -| 2022-01-01T16:00:00Z | Living Room | 4 | | -| 2022-01-01T17:00:00Z | Living Room | 5 | | -| 2022-01-01T18:00:00Z | Living Room | 9 | | -| 2022-01-01T19:00:00Z | Living Room | 14 | Carbon monoxide level above normal: 14 ppm. | -| 2022-01-01T20:00:00Z | Living Room | 17 | Carbon monoxide level above normal: 17 ppm. | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## FROM clause subqueries - -`FROM` clause subqueries return a set of results that is then queried and -operated on by the outer query. - -### Syntax {#from-subquery-syntax} - -```sql -SELECT expression1[, expression2, ..., expressionN] FROM () -``` - -### Examples {#from-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "View `FROM` clause subquery example" %}} - -The following query returns the average of maximum values per room. -The inner query returns the maximum value for each field from each room. -The outer query uses the results of the inner query and returns the average -maximum value for each field. - -```sql -SELECT - AVG(max_co) AS avg_max_co, - AVG(max_hum) AS avg_max_hum, - AVG(max_temp) AS avg_max_temp -FROM - ( - SELECT - room, - MAX(co) AS max_co, - MAX(hum) AS max_hum, - MAX(temp) AS max_temp - FROM - home - GROUP BY - room - ) -``` - -#### Inner query results - -| room | max_co | max_hum | max_temp | -| :---------- | -----: | ------: | -------: | -| Living Room | 17 | 36.4 | 22.8 | -| Kitchen | 26 | 36.9 | 23.3 | - -#### Outer query results - -| avg_max_co | avg_max_hum | avg_max_temp | -| ---------: | ----------: | -----------: | -| 21.5 | 36.7 | 23.1 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -## WHERE clause subqueries - -[`WHERE` clause](/influxdb/clustered/reference/sql/where/) subqueries -compare an expression to the result of the subquery and return _true_ or _false_. -Rows that evaluate to _false_ or NULL are filtered from results. -The `WHERE` clause supports correlated and non-correlated subqueries -as well as scalar and non-scalar subqueries (depending on the the operator used -in the predicate expression). - -### Syntax {#where-subquery-syntax} - -```sql -SELECT - expression1[, expression2, ..., expressionN] -FROM - -WHERE - expression operator () -``` - -{{% note %}} -`WHERE` clause subqueries can be used as an alternative to `JOIN` operations. -{{% /note %}} - -### Examples {#where-subquery-examples} -{{< expand-wrapper >}} -{{% expand "`WHERE` clause with scalar subquery" %}} - -The following query returns all points with `temp` values above the average -of all `temp` values. The subquery returns the average `temp` value. - -```sql -SELECT - * -FROM - home -WHERE - temp > ( - SELECT - AVG(temp) - FROM - home - ) -``` - -#### Inner query result - -| AVG(home.temp) | -| :----------------- | -| 22.396153846153844 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | -| 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | -| 3 | 36.2 | Kitchen | 22.7 | 2022-01-01T15:00:00Z | -| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | -| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | -| 0 | 36 | Living Room | 22.4 | 2022-01-01T13:00:00Z | -| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | -| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`WHERE` clause with non-scalar subquery" %}} - -Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and -can only return a single column. -The values in the returned column are evaluated as a list. - -The following query returns all points in the `home` measurement associated with -the same timestamps as `warn` level alerts in the `home_actions` measurement. - -```sql -SELECT - * -FROM - home -WHERE - time IN ( - SELECT - DISTINCT time - FROM - home_actions - WHERE - level = 'warn' - ) -``` - -#### Inner query result - -{{% influxdb/custom-timestamps %}} -| time | -| :------------------- | -| 2022-01-01T18:00:00Z | -| 2022-01-01T19:00:00Z | -| 2022-01-01T20:00:00Z | -{{% /influxdb/custom-timestamps %}} - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | -| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | -| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | -| 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | -| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | -| 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`WHERE` clause with correlated subquery" %}} - -The following query returns rows with temperature values greater than the median -temperature value for each room. The subquery in the `WHERE` clause uses the -`room` value from the outer query to return the median `temp` value for that -specific room. - -```sql -SELECT - time, - room, - temp -FROM - home outer_query -WHERE - temp > ( - SELECT - median(temp) AS temp - FROM - home - WHERE - room = outer_query.room - GROUP BY - room - ) -ORDER BY room, time -``` - -#### Inner query result - -The result of the inner query depends on the value of `room` in the outer query, -but the following table contains the median `temp` value for each room. - -| room | temp | -| :---------- | ---: | -| Living Room | 22.3 | -| Kitchen | 22.7 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| time | room | temp | -| :------------------- | :---------- | ---: | -| 2022-01-01T09:00:00Z | Kitchen | 23 | -| 2022-01-01T13:00:00Z | Kitchen | 22.8 | -| 2022-01-01T14:00:00Z | Kitchen | 22.8 | -| 2022-01-01T18:00:00Z | Kitchen | 23.3 | -| 2022-01-01T19:00:00Z | Kitchen | 23.1 | -| 2022-01-01T13:00:00Z | Living Room | 22.4 | -| 2022-01-01T16:00:00Z | Living Room | 22.4 | -| 2022-01-01T17:00:00Z | Living Room | 22.6 | -| 2022-01-01T18:00:00Z | Living Room | 22.8 | -| 2022-01-01T19:00:00Z | Living Room | 22.5 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## HAVING clause subqueries - -[`HAVING` clause](/influxdb/clustered/reference/sql/having/) subqueries -compare an expression that uses aggregate values returned by aggregate functions -in the `SELECT` clause to the result of the subquery and return _true_ or _false_. -Rows that evaluate to _false_ or NULL are filtered from results. -The `HAVING` clause supports correlated and non-correlated subqueries -as well as scalar and non-scalar subqueries (depending on the the operator used -in the predicate expression). - -### Syntax {#having-subquery-syntax} - -```sql -SELECT - aggregate_expression1[, aggregate_expression2, ..., aggregate_expressionN] -FROM - -WHERE - -GROUP BY - column_expression1[, column_expression2, ..., column_expressionN] -HAVING - expression operator () -``` - -### Examples {#having-subquery-examples} - -{{< expand-wrapper >}} -{{% expand "`HAVING` clause with scalar subquery" %}} - -The following query returns all two hour blocks of time with average `temp` values -greater then the median `temp` value. - -```sql -SELECT - DATE_BIN(INTERVAL '2 hours', time) AS "2-hour block", - AVG(temp) AS avg_temp -FROM - home -GROUP BY - 1 -HAVING - avg_temp > ( - SELECT - MEDIAN(temp) - FROM - home - ) -``` - -#### Inner query result - -| MEDIAN(home.temp) | -| :---------------- | -| 22.45 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | avg_temp | -| :------------------- | -------: | -| 2022-01-01T12:00:00Z | 22.475 | -| 2022-01-01T16:00:00Z | 22.525 | -| 2022-01-01T18:00:00Z | 22.925 | -| 2022-01-01T14:00:00Z | 22.525 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`HAVING` clause with non-scalar subquery" %}} - -Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and -can only return a single column. -The values in the returned column are evaluated as a list. - -The following query returns the maximum `co` and `temp` values within 2-hour -windows of time where the `time` value associated with time window is also -associated with a warning in the `home_actions` measurement. - -```sql -SELECT - date_bin(INTERVAL '2 hours', time) AS "2-hour block", - max(co) AS max_co, - max(temp) as max_temp -FROM - home -GROUP BY - 1, - room -HAVING - "2-hour block" IN ( - SELECT - DISTINCT time - FROM - home_actions - WHERE - level = 'warn' - ) -``` - -#### Inner query result - -{{% influxdb/custom-timestamps %}} -| time | -| :------------------- | -| 2022-01-01T18:00:00Z | -| 2022-01-01T19:00:00Z | -| 2022-01-01T20:00:00Z | -{{% /influxdb/custom-timestamps %}} - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | max_co | max_temp | -| :------------------- | -----: | -------: | -| 2022-01-01T18:00:00Z | 14 | 22.8 | -| 2022-01-01T18:00:00Z | 22 | 23.3 | -| 2022-01-01T20:00:00Z | 17 | 22.2 | -| 2022-01-01T20:00:00Z | 26 | 22.7 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{% expand "`HAVING` clause with correlated subquery" %}} - -The following query returns 2-hour windows of time with average `temp` values -greater than the median `temp` value for each room. The subquery in the `HAVING` -clause uses the `room` value from the outer query to return the median `temp` value -for that specific room. - -```sql -SELECT - time, - room, - temp -FROM - home outer_query -WHERE - temp > ( - SELECT - median(temp) AS temp - FROM - home - WHERE - room = outer_query.room - GROUP BY - room - ) -ORDER BY room, time -``` - -#### Inner query result - -The result of the inner query depends on the value of `room` in the outer query, -but the following table contains the median `temp` value for each room. - -| room | temp | -| :---------- | ---: | -| Living Room | 22.3 | -| Kitchen | 22.7 | - -#### Outer query result - -{{% influxdb/custom-timestamps %}} -| 2-hour block | room | avg_temp | -| :------------------- | :---------- | -----------------: | -| 2022-01-01T14:00:00Z | Kitchen | 22.75 | -| 2022-01-01T18:00:00Z | Kitchen | 23.200000000000003 | -| 2022-01-01T16:00:00Z | Living Room | 22.5 | -| 2022-01-01T18:00:00Z | Living Room | 22.65 | -{{% /influxdb/custom-timestamps %}} - -{{% /expand %}} -{{< /expand-wrapper >}} - -## Subquery categories - -SQL subqueries can be categorized as one or more of the following based on the -behavior of the subquery: - -- [correlated](#correlated-subqueries) or [non-correlated](#non-correlated-subqueries) -- [scalar](#scalar-subqueries) or [non-scalar](#non-scalar-subqueries) - -### Correlated subqueries - -In a **correlated** subquery, the inner query depends on the outer query, using -values from the outer query for its results. -Correlated subqueries can return a maximum of one row, so -[aggregations](/influxdb/clustered/reference/sql/functions/aggregate/) may -be required in the inner query. - -In the query below, the inner query (`SELECT temp_avg FROM weather WHERE location = home.room`) -depends on data (`home.room`) from the outer query -(`SELECT time, room, temp FROM home`) and is therefore a _correlated_ subquery. - -```sql -SELECT - time, - room, - temp -FROM - home -WHERE - temp = ( - SELECT - temp_avg - FROM - weather - WHERE - location = home.room - ) -``` - -{{% note %}} -#### Correlated subquery performance - -Because correlated subqueries depend on the outer query and typically must -execute for each row returned by the outer query, correlated subqueries are -**less performant** than non-correlated subqueries. -{{% /note %}} - -### Non-correlated subqueries - -In a **non-correlated** subquery, the inner query _doesn't_ depend on the outer -query and executes independently. -The inner query executes first, and then passes the results to the outer query. - -In the query below, the inner query (`SELECT MIN(temp_avg) FROM weather`) can -run independently from the outer query (`SELECT time, temp FROM home`) and is -therefore a _non-correlated_ subquery. - -```sql -SELECT - time, - temp -FROM - home -WHERE - temp < ( - SELECT - MIN(temp_avg) - FROM - weather - ) -``` - -### Scalar subqueries - -A **scalar** subquery returns a single value (one column of one row). -If no rows are returned, the subquery returns NULL. - -The example subquery below returns the average value of a specified column. -This value is a single scalar value. - -```sql -SELECT * FROM home WHERE co > (SELECT avg(co) FROM home) -``` - -### Non-scalar subqueries - -A **non-scalar** subquery returns 0, 1, or multiple rows, each of which may -contain 1 or multiple columns. For each column, if there is no value to return, -the subquery returns NULL. If no rows qualify to be returned, the subquery -returns 0 rows. - -The example subquery below returns all distinct values in a column. -Multiple values are returned. - -```sql -SELECT * FROM home WHERE room IN (SELECT DISTINCT room FROM home_actions) -``` \ No newline at end of file + diff --git a/content/influxdb/clustered/reference/sql/table-value-constructor.md b/content/influxdb/clustered/reference/sql/table-value-constructor.md index f668b64c4..009a8e0b6 100644 --- a/content/influxdb/clustered/reference/sql/table-value-constructor.md +++ b/content/influxdb/clustered/reference/sql/table-value-constructor.md @@ -7,115 +7,10 @@ menu: influxdb_clustered: parent: SQL reference weight: 220 + +source: /content/shared/sql-reference/table-value-constructor.md --- -The table value constructor (TVC) uses the `VALUES` keyword to specify a set of -row value expressions to construct into a table. -The TVC can be used in the `FROM` clause -to build an ad hoc table at query time. - -```sql -VALUES (row_value_list)[,...n] -``` - -##### Arguments - -- **row_value_list**: - Comma-delimited list of column values. - Enclose each list in parentheses and separate multiple lists with commas. - Each list must have the same number of values and values must be in the same - order as columns in the table. - Each list must contain a value for each column. - -## Usage - -```sql -SELECT - expression[,...n] -FROM - (VALUES (row_value_list)[,...n]) [AS] table_name(column_name[,...n]) -``` - -{{% note %}} -When using the TVC, the `AS` keyword is optional and implied when naming the -table and providing column names. -{{% /note %}} - -## Examples - -- [Select data from an ad hoc table](#select-data-from-an-ad-hoc-table) - - -### Select data from an ad hoc table - -```sql -SELECT * -FROM - (VALUES ('2023-01-01 12:00:00'::TIMESTAMP, 1.23, 4.56), - ('2023-01-01 13:00:00'::TIMESTAMP, 2.46, 8.1), - ('2023-01-01 13:00:00'::TIMESTAMP, 4.81, 16.2) - ) AS data(time, f1, f2) -``` - -| time | f1 | f2 | -| :------------------- | ---: | ---: | -| 2023-01-01T12:00:00Z | 1.23 | 4.56 | -| 2023-01-01T13:00:00Z | 2.46 | 8.1 | -| 2023-01-01T13:00:00Z | 4.81 | 16.2 | - - + diff --git a/content/influxdb/clustered/reference/sql/union.md b/content/influxdb/clustered/reference/sql/union.md index 0b71e5b37..03ed3cb0a 100644 --- a/content/influxdb/clustered/reference/sql/union.md +++ b/content/influxdb/clustered/reference/sql/union.md @@ -8,161 +8,10 @@ menu: name: UNION clause parent: SQL reference weight: 206 + +source: /content/shared/sql-reference/union.md --- -The `UNION` clause combines the results of two or more `SELECT` statements into -a single result set. -By default, `UNION` only keeps unique rows. -To keep all rows, including duplicates, use `UNION ALL`. - -- [Syntax](#syntax) -- [Examples](#examples) - -**When using the `UNION` clause**: - -- The number of columns in each result set must be the same. -- Columns must be in the same order and of the same or compatible data types. - -## Syntax - -```sql -SELECT expression[,...n] -FROM measurement_1 -UNION [ALL] -SELECT expression[,...n] -FROM measurement_2 -``` - -## Examples - -- [Union results from different measurements](#union-results-from-different-measurements) -- [Return the highest and lowest three results in a single result set](#return-the-highest-and-lowest-three-results-in-a-single-result-set) -- [Union query results with custom data](#union-query-results-with-custom-data) - -### Union results from different measurements - -```sql -( - SELECT - 'h2o_pH' AS measurement, - time, - "pH" AS "water_pH" - FROM "h2o_pH" - LIMIT 4 -) -UNION -( - SELECT - 'h2o_quality' AS measurement, - time, - index - FROM h2o_quality - LIMIT 4 -) -``` -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| measurement | time | water_pH | -| :---------- | :------------------- | -------: | -| h2o_pH | 2019-08-27T00:12:00Z | 7 | -| h2o_pH | 2019-08-27T00:18:00Z | 8 | -| h2o_quality | 2019-09-11T01:06:00Z | 89 | -| h2o_pH | 2019-08-27T00:06:00Z | 7 | -| h2o_quality | 2019-09-11T00:00:00Z | 26 | -| h2o_quality | 2019-09-11T01:00:00Z | 19 | -| h2o_quality | 2019-09-11T00:48:00Z | 65 | -| h2o_pH | 2019-08-27T00:00:00Z | 8 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Return the highest and lowest three results in a single result set - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol)._ - -```sql -( - SELECT - 'low' as type, - time, - co - FROM home - ORDER BY co ASC - LIMIT 3 -) -UNION -( - SELECT - 'high' as type, - time, - co - FROM home - ORDER BY co DESC - LIMIT 3 -) -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| type | time | co | -| :--- | :------------------- | --: | -| high | 2022-01-01T20:00:00Z | 26 | -| high | 2022-01-01T19:00:00Z | 22 | -| high | 2022-01-01T18:00:00Z | 18 | -| low | 2022-01-01T14:00:00Z | 0 | -| low | 2022-01-01T10:00:00Z | 0 | -| low | 2022-01-01T08:00:00Z | 0 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Union query results with custom data - -_The following example uses the sample data set provided in -[Get started with InfluxDB tutorial](/influxdb/clustered/get-started/write/#construct-line-protocol). -It also uses the [table value constructor](/influxdb/clustered/reference/sql/table-value-constructor/) -to build a table with custom data._ - -```sql -SELECT * -FROM home -WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T12:00:00Z' -UNION -SELECT * FROM - (VALUES (0, 34.2, 'Bedroom', 21.1, '2022-01-01T08:00:00Z'::TIMESTAMP), - (0, 34.5, 'Bedroom', 21.2, '2022-01-01T09:00:00Z'::TIMESTAMP), - (0, 34.6, 'Bedroom', 21.5, '2022-01-01T10:00:00Z'::TIMESTAMP), - (0, 34.5, 'Bedroom', 21.8, '2022-01-01T11:00:00Z'::TIMESTAMP), - (0, 33.9, 'Bedroom', 22.0, '2022-01-01T12:00:00Z'::TIMESTAMP) - ) newRoom(co, hum, room, temp, time) -ORDER BY room, time -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -| co | hum | room | temp | time | -| --: | ---: | :---------- | ---: | :------------------- | -| 0 | 34.2 | Bedroom | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 34.5 | Bedroom | 21.2 | 2022-01-01T09:00:00Z | -| 0 | 34.6 | Bedroom | 21.5 | 2022-01-01T10:00:00Z | -| 0 | 34.5 | Bedroom | 21.8 | 2022-01-01T11:00:00Z | -| 0 | 33.9 | Bedroom | 22 | 2022-01-01T12:00:00Z | -| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | -| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | -| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | -| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | -| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | -| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | -| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | -| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | -| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | -| 0 | 35.9 | Living Room | 22.2 | 2022-01-01T12:00:00Z | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/reference/sql/where.md b/content/influxdb/clustered/reference/sql/where.md index 403e27c48..a11326f58 100644 --- a/content/influxdb/clustered/reference/sql/where.md +++ b/content/influxdb/clustered/reference/sql/where.md @@ -10,125 +10,10 @@ menu: weight: 202 related: - /influxdb/clustered/reference/sql/subqueries/ + +source: /content/shared/sql-reference/where.md --- -Use the `WHERE` clause to filter results based on fields, tags, or timestamps. - -- [Syntax](#syntax) -- [Examples](#examples) - -## Syntax - -```sql -SELECT_clause FROM_clause WHERE [(AND|OR) [...]] -``` - -{{% note %}} -**Note:** Unlike InfluxQL, SQL **supports** `OR` in the `WHERE` clause to specify multiple conditions, including time ranges. -{{% /note %}} - -## Examples - -Note that single quotes are required for string literals in the `WHERE` clause. - -### Filter data based on field values - -```sql -SELECT * -FROM "h2o_feet" -WHERE "water_level" >= 9.78 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns data from the `h2o_feet` measurement with `water_level` field values -that are greater than or equal to 9.78. - -| level description | location | time | water_level | -| :------------------------ | :----------- | :----------------------- | :---------- | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:06:00.000Z | 9.8 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:12:00.000Z | 9.829 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:18:00.000Z | 9.862 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:24:00.000Z | 9.892 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:30:00.000Z | 9.902 | -| at or greater than 9 feet | coyote_creek | 2019-09-01T23:36:00.000Z | 9.898 | - -{{% /expand %}} -{{< /expand-wrapper >}} - - -### Filter data based on specific tag and field values - -```sql -SELECT * -FROM "h2o_feet" -WHERE "location" = 'santa_monica' and "level description" = 'below 3 feet' -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns all data from the `h2o_feet` measurement with the `location` tag key, `santa_monica`, -and a `level description` field value that equals `below 3 feet`. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | santa_monica | 2019-09-01T00:00:00.000Z | 1.529 | -| below 3 feet | santa_monica | 2019-09-01T00:06:00.000Z | 1.444 | -| below 3 feet | santa_monica | 2019-09-01T00:12:00.000Z | 1.335 | -| below 3 feet | santa_monica | 2019-09-01T00:18:00.000Z | 1.345 | -| below 3 feet | santa_monica | 2019-09-01T00:24:00.000Z | 1.27 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Filter data within a specific time period - -```sql -SELECT * -FROM h2o_feet -WHERE "location" = 'santa_monica' -AND "time" >= '2019-08-19T12:00:00Z'::timestamp AND "time" <= '2019-08-19T13:00:00Z'::timestamp -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns results with timestamps greater than or equal to `08-19-2019T12:00:00Z` and -less than or equal to `08-19-2019T13:00:00Z`. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | santa_monica | 2019-08-19T12:00:00.000Z | 2.533 | -| below 3 feet | santa_monica | 2019-08-19T12:06:00.000Z | 2.543 | -| below 3 feet | santa_monica | 2019-08-19T12:12:00.000Z | 2.385 | -| below 3 feet | santa_monica | 2019-08-19T12:18:00.000Z | 2.362 | -| below 3 feet | santa_monica | 2019-08-19T12:24:00.000Z | 2.405 | -| below 3 feet | santa_monica | 2019-08-19T12:30:00.000Z | 2.398 | - -{{% /expand %}} -{{< /expand-wrapper >}} - -### Filter data using the OR operator - -```sql -SELECT * -FROM "h2o_feet" -WHERE "level description" = 'less than 3 feet' OR "water_level" < 2.5 -``` - -{{< expand-wrapper >}} -{{% expand "View example results" %}} - -The query returns results with a `level description` field value equal to `less than 3 feet` or a `water_level` field value less than 2.5. - -| level description | location | time | water_level | -| :---------------- | :----------- | :----------------------- | :---------- | -| below 3 feet | coyote_creek | 2019-08-25T10:06:00.000Z | 2.398 | -| below 3 feet | coyote_creek | 2019-08-25T10:12:00.000Z | 2.234 | -| below 3 feet | coyote_creek | 2019-08-25T10:18:00.000Z | 2.064 | -| below 3 feet | coyote_creek | 2019-08-25T10:24:00.000Z | 1.893 | - -{{% /expand %}} -{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/write-data/line-protocol/client-libraries.md b/content/influxdb/clustered/write-data/line-protocol/client-libraries.md index 582947d5b..9d421bb69 100644 --- a/content/influxdb/clustered/write-data/line-protocol/client-libraries.md +++ b/content/influxdb/clustered/write-data/line-protocol/client-libraries.md @@ -120,7 +120,7 @@ The following steps set up a Go project using the which provides the InfluxDB `influxdb3` Go client library module. ```sh - go get github.com/InfluxCommunity/influxdb3-go + go get github.com/InfluxCommunity/influxdb3-go/v2 ``` @@ -229,7 +229,7 @@ points. "os" "fmt" "time" - "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" "github.com/influxdata/line-protocol/v2/lineprotocol" ) diff --git a/content/influxdb/clustered/write-data/troubleshoot.md b/content/influxdb/clustered/write-data/troubleshoot.md index 1c7c9b5f5..5e397c5e4 100644 --- a/content/influxdb/clustered/write-data/troubleshoot.md +++ b/content/influxdb/clustered/write-data/troubleshoot.md @@ -5,7 +5,8 @@ weight: 106 description: > Troubleshoot issues writing data. Find response codes for failed writes. - Discover how writes fail, from exceeding rate or payload limits, to syntax errors and schema conflicts. + Discover how writes fail, from exceeding rate or payload limits, to syntax + errors and schema conflicts. menu: influxdb_clustered: name: Troubleshoot issues @@ -17,7 +18,8 @@ related: - /influxdb/clustered/reference/internals/durability/ --- -Learn how to avoid unexpected results and recover from errors when writing to {{% product-name %}}. +Learn how to avoid unexpected results and recover from errors when writing to +{{% product-name %}}. - [Handle write responses](#handle-write-responses) - [Review HTTP status codes](#review-http-status-codes) @@ -26,12 +28,26 @@ Learn how to avoid unexpected results and recover from errors when writing to {{ ## Handle write responses -In {{% product-name %}}, writes are synchronous. -After InfluxDB validates the request and ingests the data, it sends a _success_ response (HTTP `204` status code) as an acknowledgement that the data is written and queryable. -To ensure that InfluxDB handles writes in the order you request them, wait for the acknowledgement before you send the next request. +{{% product-name %}} does the following when you send a write request: -If InfluxDB successfully writes all the request data to the database, it returns _success_ (HTTP `204` status code). -The first rejected point in a batch causes InfluxDB to reject the entire batch and respond with an [HTTP error status](#review-http-status-codes). +1. Validates the request. +2. If successful, attempts to ingest data from the request body; otherwise, + responds with an [error status](#review-http-status-codes). +3. Ingests or rejects data in the batch and returns one of the following HTTP + status codes: + + - `204 No Content`: All data in the batch is ingested. + - `400 Bad Request`: Some or all of the data has been rejected. + Data that has not been rejected is ingested and queryable. + +The response body contains error details about +[rejected points](#troubleshoot-rejected-points), up to 100 points. + +Writes are synchronous--the response status indicates the final status of the +write and all ingested data is queryable. + +To ensure that InfluxDB handles writes in the order you request them, +wait for the response before you send the next request. ### Review HTTP status codes @@ -42,7 +58,7 @@ Write requests return the following status codes: | HTTP response code | Message | Description | | :-------------------------------| :--------------------------------------------------------------- | :------------- | | `204 "Success"` | | If InfluxDB ingested the data | -| `400 "Bad request"` | `message` contains the first malformed line | If data is malformed | +| `400 "Bad request"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections | If some or all request data isn't allowed (for example, if it is malformed or falls outside of the bucket's retention period)--the response body indicates whether a partial write has occurred or if all data has been rejected | | `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/clustered/admin/tokens/) doesn't have [permission](/influxdb/clustered/reference/cli/influxctl/token/create/#examples) to write to the database. See [examples using credentials](/influxdb/clustered/get-started/write/#write-line-protocol-to-influxdb) in write requests. | | `404 "Not found"` | requested **resource type** (for example, "organization" or "database"), and **resource name** | If a requested resource (for example, organization or database) wasn't found | | `500 "Internal server error"` | | Default status for an error | @@ -62,6 +78,10 @@ If you notice data is missing in your database, do the following: ## Troubleshoot rejected points -InfluxDB rejects points that fall within the same partition (default partitioning is measurement and day) as existing bucket data and have a different data type for an existing field. +InfluxDB rejects points that fall within the same partition (default partitioning +is by measurement and day) as existing bucket data and have a different data type +for an existing field. -Check for [field data type](/influxdb/clustered/reference/syntax/line-protocol/#data-types-and-format) differences between the rejected data point and points within the same database and partition--for example, did you attempt to write `string` data to an `int` field? +Check for [field data type](/influxdb/clustered/reference/syntax/line-protocol/#data-types-and-format) +differences between the rejected data point and points within the same database +and partition--for example, did you attempt to write `string` data to an `int` field? diff --git a/content/influxdb/v1/about_the_project/_index.md b/content/influxdb/v1/about_the_project/_index.md index b23723113..87d4629d4 100644 --- a/content/influxdb/v1/about_the_project/_index.md +++ b/content/influxdb/v1/about_the_project/_index.md @@ -2,8 +2,8 @@ title: About InfluxDB OSS description: > Release notes, licenses, contribution guidelines, and third-party software details for InfluxDB. -alias: - -/docs/v1.8/about/ +aliases: + - /docs/v1.8/about/ menu: influxdb_v1: name: About the project diff --git a/content/influxdb/v1/about_the_project/release-notes.md b/content/influxdb/v1/about_the_project/release-notes.md index a7f8c6f8c..4fde87a27 100644 --- a/content/influxdb/v1/about_the_project/release-notes.md +++ b/content/influxdb/v1/about_the_project/release-notes.md @@ -1,5 +1,5 @@ --- -title: InfluxDB 1.8 release notes +title: InfluxDB v1 release notes description: Important changes and and what's new in each version of InfluxDB OSS. menu: influxdb_v1: @@ -11,6 +11,187 @@ aliases: v2: /influxdb/v2/reference/release-notes/influxdb/ --- +## v1.11.8 {date="2024-11-15"} + +### Bug Fixes + +- Strip double quotes from measurement names in the [`/api/v2/delete` + compatibility API](/influxdb/v1/tools/api/#apiv2delete-http-endpoint) before + string comparisons (e.g. to allow special characters in measurement names). + +## v1.11.7 {date="2024-10-10"} + +This release represents the first public release of InfluxDB OSS v1 since 2021 +and includes many enhancements and bug fixes added to InfluxDB Enterprise and +then back-ported to InfluxDB OSS v1. Many of these enhancements improve +compatibility between InfluxDB v1 and InfluxDB v3 and help to ease the migration +of InfluxDB v1 workloads to InfluxDB v3. + +{{% warn %}} +#### Before upgrading to InfluxDB 1.11 + +The last public release of InfluxDB v1 was v1.8.10. Upgrading from v1.8.10 to +v1.11.7 is a large jump and should be done with care. Consider doing +one or more of the the following before upgrading: + +- [Back up your data](/influxdb/v1/administration/backup_and_restore/) +- Create a clone of your current InfluxDB using InfluxDB 1.11 with identical + configuration options. Dual-write to your current InfluxDB + instance and your new 1.11 instance. Test writing and querying data with + InfluxDB 1.11. + +#### No 32-bit builds + +InfluxData no longer provides builds of InfluxDB v1 for 32-bit architectures. +All official build packages are for 64-bit architectures. +{{% /warn %}} + +### Features + +- **InfluxQL improvements:** + - Upgrade to InfluxQL 1.2.0. + - Support database and retention policy wildcards in `SHOW MEASUREMENTS`--for example: + `SHOW MEASUREMENTS ON *.*` + - Optimize `SHOW FIELD KEY CARDINALITY`. + - `SHOW TAG VALUES` returns results from one specific retention policy. + - Support `WITH KEY` clause in with `SHOW TAG KEYS`. + - Support Hyper Log Log operators: `count_hll`, `sum_hll`, `merge_hll`. + - Use `count_hll` for `SHOW SERIES CARDINALITY` queries. +- **Logging improvements:** + - Log slow queries even without query logging enabled. + - Always log the log level. + - Add version number to `/debug/vars` output. + - Include `crypto` diagnostics in `/debug/vars` output. + - Add the ability to log queries killed by `query-timeout`. + - Add logging to compaction. +- **New InfluxDB inspection tools:** + - Add [`influx_inspect report-db` command](/influxdb/v1/tools/influx_inspect/#report-db) + to estimate the cardinality of a 1.x database when migrated to InfluxDB Cloud (TSM). + - Add the [`influx_inspect check-schema`](/influxdb/v1/tools/influx_inspect/#check-schema) + and [`influx_inspect merge-schema`](/influxdb/v1/tools/influx_inspect/#merge-schema) + commands to check for type conflicts between shards. +- **New configuration options:** + - Add [`total-buffer-bytes`](/influxdb/v1/administration/config/#total-buffer-bytes--0) + configuration option to set the total number of bytes to allocate to + subscription buffers. + - Add [`termination-query-log`](/influxdb/v1/administration/config/#termination-query-log--false) + configuration option to enable dumping running queries to log on `SIGTERM`. + - Add [`max-concurrent-deletes`](/influxdb/v1/administration/config/#max-concurrent-deletes--1) + configuration option to set delete concurrency. + - Add [Flux query configuration settings](/influxdb/v1/administration/config/#flux-query-management-settings). + - Add [`compact-series-file`](/influxdb/v1/administration/config/#compact-series-file--false) + configuration option to enable or disable series file compaction on startup. + - Add [`prom-read-auth-enabled` configuration option](/influxdb/v1/administration/config/#prom-read-auth-enabled--false) + to authenticate Prometheus remote read. +- **Flux improvements:** + - Upgrade Flux to v0.194.5. + - Update Flux components to use `flux/array` instead of `arrow/array`. + - Add Flux query support to the `influx` REPL. + - Add [new pushdown capabilities](/influxdb/v1/flux/guides/optimize-queries/#start-queries-with-pushdowns) + to improve Flux query performance. +- **InfluxDB v2 compatibility API updates:** + - Partially support create, retrieve, update, delete, and list operations in the + [`/v2/api/buckets` compatibility API](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints) + and correctly handle requests to unsupported `/v2/api/buckets` endpoints. + - Implement the [`v2/api/delete` compatibility API](/influxdb/v1/tools/api/#apiv2delete-http-endpoint). +- **Additional internal metrics:** + - Ingress metrics by measurement. + - Measurement metrics by login. + - Series creation ingress metrics. + - Add subscription buffer size usage metric. +- **Build improvements:** + - Enable static-pie builds for InfluxDB 1.x. + - Make Windows and ARM64 builds possible. +- **Miscellaneous additions and optimizations:** + - Add multiple UDP writers. + - Optimize series iteration. + - Optimize saving changes to `fields.idx`. + +### Bug Fixes + +- Prevent `GROUP BY` from returning multiple results per group in some circumstances. +- Add `curl` dependency to InfluxDB packages for use in systemd scripts. +- Use `defer` to unlock mutexes. +- Ensure `influxd-ctl backup` creates a usable backup when only the `-shard` + option is provided. +- `influx_inspect verify -dir` no longer appends `/data` to the directory path. + Files are checked recursively, which include files in the `/data` directory + and other subdirectories. +- Don't rename files on mmap failure. +- Fully clean up partially opened TSI. +- Remember shards that fail `Open()` and avoid repeated attempts. +- Improve error messages when opening index partitions. +- Create `TSI MANIFEST` files atomically +- Add paths to TSI log and index file errors. +- Restore in-memory Manifest on write error. +- Generalize test for Windows. +- Use `copy` when a rename spans volumes. +- Add tests for file rename across volumes. +- Log errors in continuous query statistics storage. +- Remove breaking argument validation for `_fieldKeys` iterator. +- `ListBuckets` properly returns a wrapped response. +- Don't write skipped shard messages to the line protocol output destination. +- Add warning if `fields.idxl` is encountered. +- Prevent world-writable `MANIFEST` files. +- Do not escape CSV output. +- Avoid SIGBUS when reading non-standard series segment files. +- Prevent retention service from creating orphaned shard files. +- Sync index file before closing. +- Abort processing a write request when encountering a precision error. +- `MeasurementsCardinality` should not be less than 0. +- Replace unprintable and invalid characters in errors. +- Keep TSI reference or don't close `TagValueSeriesIDIterator` on error. +- Eliminate race condition on `Monitor.globalTags`. +- Correctly handle `MaxSeriesPerDatabaseExceeded`. +- Return underlying errors when creating a subscription. +- Fix a race condition that caused restore commands to fail. +- Create shards without overlapping time ranges. +- Improve error messages for snapshots with no data. +- Detect misquoted tag values and return an error. +- Use `debug` log level in `influx_tools compact-shard`. +- Allow limiting shards during Flux iterator reads. +- When restoring data, force the `-db` parameter when `-newdb` is used. +- Sync series segments to disk after writing. +- Fix deadlock in `influx_inspect dumptsi`. +- Prevent errors when restoring from a portable backup. +- Copy names from mmapped memory before closing the iterator. +- TSI should compact log files that are old or too large. +- Compact old `tsl` files without new writes. +- Enforce a hard limit on field size while parsing line protocol. +- Ensure log formatting (JSON) is respected. +- Ensure systemd handles HTTPS and 40x response codes and blocks indefinitely + while waiting for API repsonses. +- Avoid compaction queue stats flutter. +- Require database authorization to see continuous queries. +- Return correct count of `ErrNotExecuted`. +- Address various `staticcheck` warnings. +- Properly shutdown multiple HTTP servers. +- Make error messaging for missing shards consistent. +- Fix redundant registrations for prometheus collector metrics. +- Improved performance for sorted merge iterator. +- Grow tag index buffer when needed. +- Fixes key collisions when serializing `/debug/vars`. +- Return an error when trying to delete a nonexistent shard ID. +- Improved CORS support: + - Add User-Agent to allowed CORS headers. + - Allow CORS in v2 compatibility endpoints. + - Allow the `PATCH` request method. + +### Other + +- Upgrade to Go 1.22.7. +- Detect and use the Rust version defined in Flux (1.73). +- Upgrade Flux to v0.194.5. +- Upgrade multiple dependencies for maintenance and security. +- Upgrade `xbuilder` for parity with InfluxDB Enterprise. +- Upgrade to latest crossbuilder. +- Use community maintained `golang-jwt` +- Generate `influxdb.${CIRCLE_TAG}.digests` for each release. +- Update contribution guidelines. +- Remove deprecated `influx_stress` tool. + +--- + ## v1.8.10 {date="2021-10-11"} ### Bug fixes @@ -163,7 +344,7 @@ This release updates support for the Flux language and queries. To learn about F #### Forward compatibility -- [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-20-api-compatibility-endpoints) are now part of the InfluxDB 1.x line. +- [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints) are now part of the InfluxDB 1.x line. This allows you to leverage the new InfluxDB 2.0 [client libraries](/influxdb/v1/tools/api_client_libraries/) for both writing and querying data with Flux. Take advantage of the latest client libraries while readying your implementation for a move to InfluxDB 2.0 Cloud when you're ready to scale. diff --git a/content/influxdb/v1/administration/_index.md b/content/influxdb/v1/administration/_index.md index f965a470e..116ab4ae2 100644 --- a/content/influxdb/v1/administration/_index.md +++ b/content/influxdb/v1/administration/_index.md @@ -13,6 +13,6 @@ The administration documentation contains all the information needed to administ ## Downgrade -To revert to a prior version, complete the same steps as when [Upgrading to InfluxDB 1.8.x](/influxdb/v1/administration/upgrading/), replacing 1.8.x with the version 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). +To revert to a prior version, complete the same steps as when [Upgrading to InfluxDB 1.11.x](/influxdb/v1/administration/upgrading/), replacing 1.11.x with the version 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. diff --git a/content/influxdb/v1/administration/backup_and_restore.md b/content/influxdb/v1/administration/backup_and_restore.md index 736a9f709..3ff557114 100644 --- a/content/influxdb/v1/administration/backup_and_restore.md +++ b/content/influxdb/v1/administration/backup_and_restore.md @@ -1,6 +1,6 @@ --- title: Back up and restore data -seotitle: Back up and restore data in InfluxDB v1.8 +seotitle: Back up and restore data in InfluxDB v1.11 description: > To prevent unexpected data loss, back up and restore InfluxDB OSS instances. aliases: @@ -13,20 +13,43 @@ menu: v2: /influxdb/v2/backup-restore/ --- -Use the InfluxDB {{< current-version >}} `backup` and `restore` utilities +Use the InfluxDB OSS {{< current-version >}} `backup`, `restore`, `export`, and `import` utilities to prevent unexpected data loss and preserve the ability to restore data if it ever is lost. -These utilities let you: + +You can use these tools in your back up and restore procedures to: + +- Provide disaster recovery due to unexpected events +- Migrate data to new environments or servers +- Restore instances to a consistent state +- Export and import data for debugging + +Depending on the volume of data to be protected and your application requirements, InfluxDB OSS {{< current-version >}} offers two methods, described below, for managing backups and restoring data: + +- [Backup and restore utilities](#backup-and-restore-utilities): Use for most applications +- [Exporting and importing data](#exporting-and-importing-data): Use for very large datasets and to debug data + +> [!Note] +> #### Back up and restore between InfluxDB Enterprise and OSS +> +> Use the `backup` and `restore` utilities in +> [InfluxDB Enterprise](/enterprise_influxdb/v1/administration/backup-and-restore/) and +> [InfluxDB OSS (version 1.5 and later)](#backup-and-restore-utilities/) to: +> +> - Restore InfluxDB Enterprise backup files to InfluxDB OSS instances. +> - Back up InfluxDB OSS data that can be restored in InfluxDB Enterprise clusters. + +## Backup and restore utilities + +Use InfluxDB OSS {{< current-version >}} `backup` and `restore` utilities to: - Back up and restore multiple databases at a time. - Back up specific time ranges. -- Import data from [InfluxDB Enterprise](/enterprise_influxdb/v1/) clusters. - Create backup files compatible with InfluxDB Enterprise. + +Use the `backup` and `restore` utilities to back up and restore data for `influxd` +instances of InfluxDB OSS version 1.4 and earlier, version 1.5 and later, and [InfluxDB Enterprise](/enterprise_influxdb/v1/). -{{% note %}} -#### InfluxDB Enterprise users -See [Back up and restore in InfluxDB Enterprise](/enterprise_influxdb/v1/administration/backup-and-restore/). -{{% /note %}} - [Backup formats](#backup-formats) - [Specify your backup format](#specify-your-backup-format) @@ -49,7 +72,14 @@ The InfluxDB `backup` utility outputs data backups in one of two formats: **lega Each format provides different functionality and support for other versions of InfluxDB. The major difference between the formats is that the legacy format can only be used with InfluxDB OSS 1.x. The portable format is "portable" between -InfluxDB 1.5–{{< current-version >}} and InfluxDB Enterprise. +InfluxDB 1.5–{{< current-version >}} and [InfluxDB Enterprise](/enterprise_influxdb/v1/). + +{{% note %}} +#### Use the portable format for InfluxDB 1.5 and later + +Use the portable format unless you need to be able to restore +the backup to InfluxDB 1.4 or earlier. +{{% /note %}} | Backup functionality | Legacy format | Portable format | | :------------------------------------------------------ | :------------------: | :------------------: | @@ -79,13 +109,6 @@ influxd restore -portable /path/to/backup-destination ``` {{< /code-callout >}} -{{% note %}} -#### We recommend the portable format - -We recommend using the portable format unless you need to be able to restore -the backup to InfluxDB 1.4 or earlier. -{{% /note %}} - ### Determine your backup's format Use the directory structure of the backup directory to determine the format of the backup. @@ -121,8 +144,8 @@ Use the directory structure of the backup directory to determine the format of t [offline legacy restore](?t=Legacy+format#offline-legacy-restore)_. - Both the source and target InfluxDB instances must be the same InfluxDB version or differ by only a minor version. - For example, you can back up data from InfluxDB {{< latest-patch minorVersionOffset=-1 >}} - and restore it to an InfluxDB {{< latest-patch >}} instance. + For example, you can back up data from InfluxDB 1.7 and restore it to an InfluxDB 1.8 instance. + The only exception is restoring data from InfluxDB 1.8 into 1.11. ## Important notes @@ -665,4 +688,85 @@ at the root level of your InfluxDB configuration file (`influxdb.conf`). ```toml # Bind address to use for the RPC service for backup and restore. bind-address = "127.0.0.1:8088" -``` \ No newline at end of file +``` + +## Exporting and importing data + +For most applications, the [backup and restore utilities](#backup-and-restore-utilities) provide the tools you need for your backup and restore strategy. +However, in some cases, the standard backup and restore utilities might not adequately handle the volumes of data in your application. + +As an alternative to the standard backup and restore utilities, use the InfluxDB `influx_inspect export` and `influx -import` commands to create backup and restore procedures for your disaster recovery and backup strategy. These commands can be executed manually or included in shell scripts that run the export and import operations at scheduled intervals. +You can use the commands to export and import data between an +InfluxDB OSS {{< current-version >}} instance and an [InfluxDB Enterprise](/enterprise_influxdb/v1/) cluster. + +- [Exporting data](#exporting-data) +- [Importing data](#importing-data) +- [Example: export and import for disaster recovery](#example-export-and-import-for-disaster-recovery) + +### Exporting data + +Use the [`influx_inspect export` command](/influxdb/v1/tools/influx_inspect#export) to export data in line protocol format from your InfluxDB OSS {{< current-version >}} instance. +Options include the following: + +- `-database`: Export all or specific databases +- `-start` and `-end`: Filter with starting and ending timestamps +- `-compress`: Use GNU zip (gzip) compression for smaller files and faster exports + +The following example shows how to export data filtered to one day and compressed +for optimal speed and file size: + +```bash +influx_inspect export \ + -database DATABASE_NAME \ + -compress \ + -start 2019-05-19T00:00:00.000Z \ + -end 2019-05-19T23:59:59.999Z +``` + +The exported file contains the following: + +```sh +# DDL +CREATE DATABASE WITH NAME +# DML +# CONTEXT-DATABASE: +# CONTEXT-RETENTION-POLICY: + + +``` + +- `DDL`: an InfluxQL `CREATE` statement to create the target database when [importing the data](#importing-data) +- `DML`: Context metadata that specifies the target database and retention policy + for [importing the data](#importing-data) +- the line protocol data + +For details on optional settings and usage, see [`influx_inspect export` command](/influxdb/v1/tools/influx_inspect#export). + +### Importing data + +To import line protocol data from a file, use the [`influx -import` CLI command](/influxdb/v1/tools/influx-cli/use-influx-cli/#influx-arguments). + +In your import file, include the following sections: + +- _Optional_: **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/influxdb/v1/query_language/manage-database/) for creating the relevant [database](/influxdb/v1/concepts/glossary/#database) and managing the [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp). +If your database and retention policy already exist, your file can skip this section. +- **DML (Data Manipulation Language)**: Context metadata that specifies the database and (if desired) retention policy for the import and contains the data in [line protocol](/influxdb/v1/concepts/glossary/#influxdb-line-protocol). + +In the following example, the compressed data file (in GNU zip format) is imported into the database +specified in the file's `DML` metadata. + +```bash +influx -import -path -compressed +``` + +For details on using the `influx -import` command, see [Import data from a file](/influxdb/v1/tools/influx-cli/use-influx-cli/#import-data-from-a-file). + +### Example: export and import for disaster recovery + +For an example of using the exporting and importing data approach for disaster recovery, see the presentation from Influxdays 2019 on ["Architecting for Disaster Recovery."](https://www.youtube.com/watch?v=LyQDhSdnm4A). In this presentation, Capital One discusses the following: + +- Exporting data every 15 minutes from an active InfluxDB Enterprise cluster to an AWS S3 bucket. +- Replicating the export file in the S3 bucket using the AWS S3 copy command. +- Importing data every 15 minutes from the AWS S3 bucket to an InfluxDB Enterprise cluster available for disaster recovery. +- Advantages of the export-import approach over the standard backup and restore utilities for large volumes of data. +- Managing users and scheduled exports and imports with a custom administration tool. diff --git a/content/influxdb/v1/administration/config.md b/content/influxdb/v1/administration/config.md index e8e11d459..4bcd5ee17 100644 --- a/content/influxdb/v1/administration/config.md +++ b/content/influxdb/v1/administration/config.md @@ -24,6 +24,7 @@ The InfluxDB open source (OSS) configuration file contains configuration setting * [Metastore `[meta]`](#metastore-settings) * [Data `[data]`](#data-settings) * [Query management `[coordinator]`](#query-management-settings) + * [Flux query management `[flux-controller]`](#flux-query-management-settings) * [Retention policies `[retention]`](#retention-policy-settings) * [Shard precreation `[shard-precreation]`](#shard-precreation-settings) * [Monitoring `[monitor]`](#monitoring-settings) @@ -178,6 +179,12 @@ The bind address to use for the RPC service for [backup and restore](/influxdb/v Environment variable: `INFLUXDB_BIND_ADDRESS` +### `compact-series-file = false` {metadata="v1.11.4+"} + +Determines if series files should be compacted on startup. If `true`, InfluxDB +runs [`influxd_inspect -compact-series-file`](/influxdb/v1/tools/influx_inspect/#--compact-series-file-) +before starting the `influxd` server. Default is `false`. + ## Metastore settings ### `[meta]` @@ -327,9 +334,16 @@ For more information on `GOMAXPROCS` environment variable, see [`GOMAXPROCS` env Environment variable: `INFLUXDB_DATA_MAX_CONCURRENT_COMPACTIONS` +#### `max-concurrent-deletes = 1` {metadata="v1.11.7+"} + +The maximum number of simultaneous `DELETE` calls on a shard. Default is `1` +and should be left unchanged for most use cases. + +Environment variable: `INFLUXDB_DATA_MAX_CONCURRENT_DELETES` + #### `compact-throughput = "48m"` -The maximum number of bytes per seconds TSM compactions write to disk. Default is `"48m"` (48 million). +The maximum number of bytes per second TSM compactions write to disk. Default is `"48m"` (48 million). Note that short bursts are allowed to happen at a possibly larger value, set by `compact-throughput-burst`. Environment variable: `INFLUXDB_DATA_COMPACT_THROUGHPUT` @@ -477,6 +491,66 @@ buckets. Environment variable: `INFLUXDB_COORDINATOR_MAX_SELECT_BUCKETS` +#### `termination-query-log = false` + +Print a list of running queries when InfluxDB receives a `SIGTERM` +(sent when a process exceeds a container memory limit or by the `kill` command). + +Environment variable: `INFLUXDB_COORDINATOR_TERMINATE_QUERY_LOG` + +----- + +## Flux query management settings + +### `[flux-controller]` {metadata="v1.11.7+"} + +The `flux-controller` settings control the behavior of Flux queries. + +#### `query-concurrency = 0` {metadata="v1.11.7+"} + +The number of Flux queries that are allowed to execute concurrently. +`0` means unlimited. Default is `0`. + +Environment variable: `INFLUXDB_FLUX_CONTROLLER_QUERY_CONCURRENCY` + +#### `query-initial-memory-bytes = 0` {metadata="v1.11.7+"} + +The initial number of bytes allocated for a Flux query when it is started. +If this is unset, then the `query-max-memory-bytes` is used. +`0` means unlimited. Default is `0`. + +Environment variable: `INFLUXDB_FLUX_CONTROLLER_QUERY_INITIAL_MEMORY_BYTES` + +#### `query-max-memory-bytes = 0` {metadata="v1.11.7+"} + +The maximum number of bytes (in table memory) a Flux query is allowed to use at +any given time. `0` means unlimited. Default is `0`. + +A query may not be able to use its entire quota of memory if requesting more +memory would conflict with the maximum amount of memory that the controller can +request. + +Environment variable: `INFLUXDB_FLUX_CONTROLLER_QUERY_MAX_MEMORY_BYTES` + +#### `total-max-memory-bytes = 0` {metadata="v1.11.7+"} + +The maximum amount of memory the Flux query controller is allowed to allocate to +Flux queries. `0` means unlimited. Default is `0`. + +If this is unset, then this number is `query-concurrency * query-max-memory-bytes`. +This number must be greater than or equal to +`query-concurrency * query-initial-memory-bytes` and may be less than +`query-concurrency * query-max-memory-bytes`. + +Environment variable: `INFLUXDB_FLUX_CONTROLLER_TOTAL_MAX_MEMORY_BYTES` + +#### `query-queue-size = 0` {metadata="v1.11.7+"} + +The number of Flux queries that are allowed to be queued for execution before +new queries are rejected. `0` means unlimited. Default is `0`. + +Environment variable: `INFLUXDB_FLUX_CONTROLLER_QUERY_QUEUE_SIZE` + ----- ## Retention policy settings @@ -698,6 +772,13 @@ This setting has no effect if [`auth-enabled`](#auth-enabled-false) is set to `f Environment variable: `INFLUXDB_HTTP_PING_AUTH_ENABLED` +#### `prom-read-auth-enabled = false` + +Enables authentication on the Prometheus remote read API. Default is `false`. +This setting has no effect if [`auth-enabled`](#auth-enabled-false) is set to `false`. + +Environment variable: `INFLUXDB_HTTP_PROM_READ_AUTH_ENABLED` + #### `http-headers` User-supplied [HTTP response headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). @@ -885,6 +966,14 @@ The number of in-flight writes buffered in the write channel. Environment variable: `INFLUXDB_SUBSCRIBER_WRITE_BUFFER_SIZE` +#### `total-buffer-bytes = 0` {metadata="v1.11.7"} + +The total size in bytes allocated to buffering across all subscriptions. +Each named subscription receives an even division of the total. +Default is `0`. + +Environment variable: `INFLUXDB_SUBSCRIBER_TOTAL_BUFFER_BYTES` + ----- ## Graphite settings diff --git a/content/influxdb/v1/administration/upgrading.md b/content/influxdb/v1/administration/upgrading.md index adc7b735e..5ea792595 100644 --- a/content/influxdb/v1/administration/upgrading.md +++ b/content/influxdb/v1/administration/upgrading.md @@ -1,5 +1,5 @@ --- -title: Upgrade to InfluxDB 1.8.x +title: Upgrade to InfluxDB 1.11.x description: Upgrade to the latest version of InfluxDB. menu: influxdb_v1: @@ -9,7 +9,7 @@ menu: --- -We recommend enabling Time Series Index (TSI) (step 3 of Upgrade to InfluxDB 1.8.x). [Switch between TSM and TSI](#switch-index-types) as needed. To learn more about TSI, see: +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/) @@ -23,13 +23,13 @@ To upgrade from InfluxDB OSS to InfluxDB Enterprise, [contact InfluxData Sales]( and see [Migrate to InfluxDB Enterprise](/enterprise_influxdb/v1/guides/migration/). {{% /note %}} -## Upgrade to InfluxDB 1.8.x +## Upgrade to InfluxDB 1.11.x -1. [Download](https://www.influxdata.com/downloads/) InfluxDB version 1.8.x and [install the upgrade](/influxdb/v1/introduction/installation/). +1. [Download](https://www.influxdata.com/downloads/) InfluxDB version 1.11.x and [install the upgrade](/influxdb/v1/introduction/installation/). -2. Migrate configuration file customizations from your existing configuration file to the InfluxDB 1.8.x [configuration file](/influxdb/v1/administration/config/). Add or modify your environment variables as needed. +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.8.x, complete the following steps: +3. 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`. @@ -53,12 +53,12 @@ Run the `buildtsi` command using the user account that you are going to run the Switch index types at any time by doing one of the following: -- To switch from to `inmem` to `tsi1`, complete steps 3 and 4 above in [Upgrade to InfluxDB 1.8.x](#upgrade-to-influxdb-1-8-x). -- To switch from to `tsi1` to `inmem`, change `tsi1` to `inmem` by completing steps 3a-3c and 4 above in [Upgrade to InfluxDB 1.8.x](#upgrade-to-influxdb-1-8-x). +- To switch from to `inmem` to `tsi1`, complete steps 3 and 4 above in [Upgrade to InfluxDB 1.11.x](#upgrade-to-influxdb-1-8-x). +- 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-1-8-x). ## Downgrade InfluxDB -To downgrade to an earlier version, complete the procedures above in [Upgrade to InfluxDB 1.8.x](#upgrade-to-influxdb-1-8-x), replacing the version numbers with the version that you want to downgrade to. +To downgrade to an earlier version, complete the procedures above in [Upgrade to InfluxDB 1.11.x](#upgrade-to-influxdb-1-8-x), 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. diff --git a/content/influxdb/v1/concepts/file-system-layout.md b/content/influxdb/v1/concepts/file-system-layout.md index b3c6dc016..cacad80be 100644 --- a/content/influxdb/v1/concepts/file-system-layout.md +++ b/content/influxdb/v1/concepts/file-system-layout.md @@ -59,6 +59,13 @@ For more information about using InfluxDB configuration files, see | [WAL directory](#wal-directory) | `~/.influxdb/wal/` | | [Metastore directory](#metastore-directory) | `~/.influxdb/meta/` | +#### Homebrew default directories +| Path | Default | +| :------------------------------------------ | :------------------ | +| [Data directory](#data-directory) | `/opt/homebrew/var/influxdb/data/` | +| [WAL directory](#wal-directory) | `/opt/homebrew/var/influxdb/wal/` | +| [Metastore directory](#metastore-directory) | `/opt/homebrew/var/meta/` | + #### macOS file system overview {{% filesystem-diagram %}} - ~/.influxdb/ diff --git a/content/influxdb/v1/concepts/glossary.md b/content/influxdb/v1/concepts/glossary.md index da30c706b..22668d937 100644 --- a/content/influxdb/v1/concepts/glossary.md +++ b/content/influxdb/v1/concepts/glossary.md @@ -27,7 +27,7 @@ Related entries: [InfluxDB line protocol](/influxdb/v1/concepts/glossary/#influx ## bucket -A bucket is a named location where time series data is stored in **InfluxDB 2.0**. In InfluxDB 1.8+, each combination of a database and a retention policy (database/retention-policy) represents a bucket. Use the [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api#influxdb-2-0-api-compatibility-endpoints) included with InfluxDB 1.8+ to interact with buckets. +A bucket is a named location where time series data is stored in **InfluxDB 2.0**. In InfluxDB 1.8+, each combination of a database and a retention policy (database/retention-policy) represents a bucket. Use the [InfluxDB 2.x API compatibility endpoints](/influxdb/v1/tools/api#influxdb-2-0-api-compatibility-endpoints) included with InfluxDB 1.8+ to interact with buckets. ## continuous query (CQ) diff --git a/content/influxdb/v1/flux/_index.md b/content/influxdb/v1/flux/_index.md index bcdfb387a..fad20d9cf 100644 --- a/content/influxdb/v1/flux/_index.md +++ b/content/influxdb/v1/flux/_index.md @@ -10,11 +10,9 @@ v2: /influxdb/v2/query-data/get-started/ --- Flux is a functional data scripting language designed for querying, analyzing, and acting on time series data. -Its takes the power of [InfluxQL](/influxdb/v1/query_language/spec/) and the functionality of [TICKscript](/kapacitor/v1/reference/tick/introduction/) and combines them into a single, unified syntax. +It takes the power of [InfluxQL](/influxdb/v1/query_language/spec/) and the functionality of [TICKscript](/kapacitor/v1/reference/tick/introduction/) and combines them into a single, unified syntax. -> Flux v0.65 is production-ready and included with [InfluxDB v1.8](/influxdb/v1/). -> The InfluxDB v1.8 implementation of Flux is read-only and does not support -> writing data back to InfluxDB. +> Flux is production-ready and included with [InfluxDB v1.8+](/influxdb/v1/). ## Flux design principles Flux is designed to be usable, readable, flexible, composable, testable, contributable, and shareable. diff --git a/content/influxdb/v1/flux/get-started/_index.md b/content/influxdb/v1/flux/get-started/_index.md index 05be60e4a..407e7075d 100644 --- a/content/influxdb/v1/flux/get-started/_index.md +++ b/content/influxdb/v1/flux/get-started/_index.md @@ -25,9 +25,10 @@ It covers querying time series data from InfluxDB using Flux, and introduces Flu ## What you will need ##### InfluxDB v1.8+ -Flux v0.65 is built into InfluxDB v1.8 and can be used to query data stored in InfluxDB. -InfluxDB v1.8's `influx` CLI also includes a `-type=` option that, when set to `flux`, will start an -interactive Flux Read-Eval-Print-Loop (REPL) allowing you to write and run Flux queries from the command line. +Flux is built into InfluxDB v1.8+ and can be used to query data stored in InfluxDB. +InfluxDB `influx` CLI also includes a `-type=` option that, when set to `flux`, +will start an interactive Flux Read-Eval-Print-Loop (REPL) allowing you to write +and run Flux queries from the command line. --- diff --git a/content/influxdb/v1/flux/guides/flux-in-dashboards.md b/content/influxdb/v1/flux/guides/flux-in-dashboards.md index 89502786e..1bf864aef 100644 --- a/content/influxdb/v1/flux/guides/flux-in-dashboards.md +++ b/content/influxdb/v1/flux/guides/flux-in-dashboards.md @@ -20,8 +20,8 @@ This guide walks through using Flux queries in Chronograf dashboard cells. --- -_**Chronograf v1.8+** and **InfluxDB v1.8 with [Flux enabled](/influxdb/v1/flux/installation)** -are required to use Flux in dashboards._ +_**Chronograf v1.8+** and **InfluxDB v1.8+ with [Flux enabled](/influxdb/v1/flux/installation)** +are required for Flux in dashboards._ --- diff --git a/content/influxdb/v1/flux/guides/optimize-queries.md b/content/influxdb/v1/flux/guides/optimize-queries.md index 46b3b5165..3d427d082 100644 --- a/content/influxdb/v1/flux/guides/optimize-queries.md +++ b/content/influxdb/v1/flux/guides/optimize-queries.md @@ -12,64 +12,184 @@ canonical: /influxdb/v2/query-data/optimize-queries/ Optimize your Flux queries to reduce their memory and compute (CPU) requirements. -- [Start queries with pushdown functions](#start-queries-with-pushdowns) +- [Start queries with pushdowns](#start-queries-with-pushdowns) +- [Avoid processing filters inline](#avoid-processing-filters-inline) - [Avoid short window durations](#avoid-short-window-durations) - [Use "heavy" functions sparingly](#use-heavy-functions-sparingly) +- [Use set() instead of map() when possible](#use-set-instead-of-map-when-possible) - [Balance time range and data precision](#balance-time-range-and-data-precision) +- [Measure query performance with Flux profilers](#measure-query-performance-with-flux-profilers) -## Start queries with pushdown functions -Some Flux functions can push their data manipulation down to the underlying -data source rather than storing and manipulating data in memory. -These are known as "pushdown" functions and using them correctly can greatly -reduce the amount of memory necessary to run a query. +## Start queries with pushdowns -#### Pushdown functions -- [range()](/flux/v0/stdlib/universe/range/) -- [filter()](/flux/v0/stdlib/universe/filter/) -- [group()](/flux/v0/stdlib/universe/group/) +**Pushdowns** are functions or function combinations that push data operations +to the underlying data source rather than operating on data in memory. +Start queries with pushdowns to improve query performance. Once a non-pushdown +function runs, Flux pulls data into memory and runs all subsequent operations there. -Use pushdown functions at the beginning of your query. +#### Pushdown functions and function combinations + +The following pushdowns are supported in InfluxDB OSS 1.11+. + +| Functions | Supported | +| :----------------------------- | :-----------------------: | +| **count()** | {{< icon "check" "v2" >}} | +| **drop()** | {{< icon "check" "v2" >}} | +| **duplicate()** | {{< icon "check" "v2" >}} | +| **filter()** {{% req " \*" %}} | {{< icon "check" "v2" >}} | +| **fill()** | {{< icon "check" "v2" >}} | +| **first()** | {{< icon "check" "v2" >}} | +| **group()** | {{< icon "check" "v2" >}} | +| **keep()** | {{< icon "check" "v2" >}} | +| **last()** | {{< icon "check" "v2" >}} | +| **max()** | {{< icon "check" "v2" >}} | +| **mean()** | {{< icon "check" "v2" >}} | +| **min()** | {{< icon "check" "v2" >}} | +| **range()** | {{< icon "check" "v2" >}} | +| **rename()** | {{< icon "check" "v2" >}} | +| **sum()** | {{< icon "check" "v2" >}} | +| **window()** | {{< icon "check" "v2" >}} | +| _Function combinations_ | | +| **group()** \|> **max()** | {{< icon "check" "v2" >}} | +| **group()** \|> **min()** | {{< icon "check" "v2" >}} | +| **window()** \|> **count()** | {{< icon "check" "v2" >}} | +| **window()** \|> **first()** | {{< icon "check" "v2" >}} | +| **window()** \|> **last()** | {{< icon "check" "v2" >}} | +| **window()** \|> **max()** | {{< icon "check" "v2" >}} | +| **window()** \|> **min()** | {{< icon "check" "v2" >}} | +| **window()** \|> **sum()** | {{< icon "check" "v2" >}} | + +{{% caption %}} +{{< req "\*" >}} **filter()** only pushes down when all parameter values are static. +See [Avoid processing filters inline](#avoid-processing-filters-inline). +{{% /caption %}} + +Use pushdown functions and function combinations at the beginning of your query. Once a non-pushdown function runs, Flux pulls data into memory and runs all subsequent operations there. ##### Pushdown functions in use + ```js from(bucket: "db/rp") - |> range(start: -1h) // - |> filter(fn: (r) => r.sensor == "abc123") // Pushed to the data source - |> group(columns: ["_field", "host"]) // + |> range(start: -1h) // + |> filter(fn: (r) => r.sensor == "abc123") // + |> group(columns: ["_field", "host"]) // Pushed to the data source + |> aggregateWindow(every: 5m, fn: max) // + |> filter(fn: (r) => r._value >= 90.0) // - |> aggregateWindow(every: 5m, fn: max) // - |> filter(fn: (r) => r._value >= 90.0) // Run in memory - |> top(n: 10) // + |> top(n: 10) // Run in memory +``` + +### Avoid processing filters inline + +Avoid using mathematic operations or string manipulation inline to define data filters. +Processing filter values inline prevents `filter()` from pushing its operation down +to the underlying data source, so data returned by the +previous function loads into memory. +This often results in a significant performance hit. + +For example, the following query uses [Chronograf dashboard template variables](/chronograf/v1/guides/dashboard-template-variables/) +and string concatenation to define a region to filter by. +Because `filter()` uses string concatenation inline, it can't push its operation +to the underlying data source and loads all data returned from `range()` into memory. + +```js +from(bucket: "db/rp") + |> range(start: -1h) + |> filter(fn: (r) => r.region == v.provider + v.region) +``` + +To dynamically set filters and maintain the pushdown ability of the `filter()` function, +use variables to define filter values outside of `filter()`: + +```js +region = v.provider + v.region + +from(bucket: "db/rp") + |> range(start: -1h) + |> filter(fn: (r) => r.region == region) ``` ## Avoid short window durations + Windowing (grouping data based on time intervals) is commonly used to aggregate and downsample data. Increase performance by avoiding short window durations. More windows require more compute power to evaluate which window each row should be assigned to. Reasonable window durations depend on the total time range queried. ## Use "heavy" functions sparingly + The following functions use more memory or CPU than others. Consider their necessity in your data processing before using them: - [map()](/flux/v0/stdlib/universe/map/) - [reduce()](/flux/v0/stdlib/universe/reduce/) -- [window()](/flux/v0/stdlib/universe/window/) - [join()](/flux/v0/stdlib/universe/join/) - [union()](/flux/v0/stdlib/universe/union/) - [pivot()](/flux/v0/stdlib/universe/pivot/) -{{% note %}} -We're continually optimizing Flux and this list may not represent its current state. -{{% /note %}} +## Use set() instead of map() when possible + +[`set()`](/flux/v0/stdlib/universe/set/), +[`experimental.set()`](/flux/v0/stdlib/experimental/set/), +and [`map`](/flux/v0/stdlib/universe/map/) +can each set column values in data, however **set** functions have performance +advantages over `map()`. + +Use the following guidelines to determine which to use: + +- If setting a column value to a predefined, static value, use `set()` or `experimental.set()`. +- If dynamically setting a column value using **existing row data**, use `map()`. + +#### Set a column value to a static value + +The following queries are functionally the same, but using `set()` is more performant than using `map()`. + +```js +data + |> map(fn: (r) => ({ r with foo: "bar" })) + +// Recommended +data + |> set(key: "foo", value: "bar") +``` + +#### Dynamically set a column value using existing row data + +```js +data + |> map(fn: (r) => ({ r with foo: r.bar })) +``` ## Balance time range and data precision + To ensure queries are performant, balance the time range and the precision of your data. For example, if you query data stored every second and request six months worth of data, -results will include a minimum of ≈15.5 million points. +results would include ≈15.5 million points per series. +Depending on the number of series returned after `filter()`([cardinality](/influxdb/v1/concepts/glossary/#series-cardinality)), +this can quickly become many billions of points. Flux must store these points in memory to generate a response. +Use [pushdowns](#pushdown-functions-and-function-combinations) to optimize how +many points are stored in memory. -To query data over large periods of time, create a [continuous query](/influxdb/v1/query_language/continuous_queries/) -to downsample data, and then query the downsampled data instead. +## Measure query performance with Flux profilers + +Use the [Flux Profiler package](/flux/v0/stdlib/profiler/) +to measure query performance and append performance metrics to your query output. +The following Flux profilers are available: + +- **query**: provides statistics about the execution of an entire Flux script. +- **operator**: provides statistics about each operation in a query. + +Import the `profiler` package and enable profilers with the `profile.enabledProfilers` option. + +```js +import "profiler" + +option profiler.enabledProfilers = ["query", "operator"] + +// Query to profile +``` + +For more information about Flux profilers, see the [Flux Profiler package](/flux/v0/stdlib/profiler/). diff --git a/content/influxdb/v1/guides/migrate-to-enterprise.md b/content/influxdb/v1/guides/migrate-to-enterprise.md index b87ecdb47..aeadacd05 100644 --- a/content/influxdb/v1/guides/migrate-to-enterprise.md +++ b/content/influxdb/v1/guides/migrate-to-enterprise.md @@ -14,4 +14,4 @@ menu: To migrate InfluxDB {{< current-version >}} to InfluxDB Enterprise, follow the instructions provided in [Migrate InfluxDB OSS instances to InfluxDB Enterprise clusters](/enterprise_influxdb/v1/guides/migration/) -In the InfluxDB Enterprise documentation. +in the InfluxDB Enterprise documentation. diff --git a/content/influxdb/v1/guides/query_data.md b/content/influxdb/v1/guides/query_data.md index 8194804ef..3046d0c93 100644 --- a/content/influxdb/v1/guides/query_data.md +++ b/content/influxdb/v1/guides/query_data.md @@ -1,7 +1,7 @@ --- title: Query data with the InfluxDB API description: Query data with Flux and InfluxQL in the InfluxDB API. -alias: +aliases: -/docs/v1.8/query_language/querying_data/ menu: influxdb_v1: @@ -54,7 +54,7 @@ The header row defines column labels for the table. The `cpu` [measurement](/inf ### Flux Check out the [Get started with Flux](/influxdb/v2/query-data/get-started/) to learn more about building queries with Flux. -For more information about querying data with the InfluxDB API using Flux, see the [API reference documentation](/influxdb/v1/tools/api/#influxdb-2-0-api-compatibility-endpoints). +For more information about querying data with the InfluxDB API using Flux, see the [API reference documentation](/influxdb/v1/tools/api/#influxdb-2x-api-compatibility-endpoints). ## Query data with InfluxQL diff --git a/content/influxdb/v1/guides/write_data.md b/content/influxdb/v1/guides/write_data.md index de7c401c7..5b7f86d50 100644 --- a/content/influxdb/v1/guides/write_data.md +++ b/content/influxdb/v1/guides/write_data.md @@ -28,8 +28,9 @@ curl -i -XPOST http://localhost:8086/query --data-urlencode "q=CREATE DATABASE m The InfluxDB API is the primary means of writing data into InfluxDB. -- To **write to a database using the InfluxDB 1.8 API**, send `POST` requests to the `/write` endpoint. For example, to write a single point to the `mydb` database. -The data consists of the [measurement](/influxdb/v1/concepts/glossary/#measurement) `cpu_load_short`, the [tag keys](/influxdb/v1/concepts/glossary/#tag-key) `host` and `region` with the [tag values](/influxdb/v1/concepts/glossary/#tag-value) `server01` and `us-west`, the [field key](/influxdb/v1/concepts/glossary/#field-key) `value` with a [field value](/influxdb/v1/concepts/glossary/#field-value) of `0.64`, and the [timestamp](/influxdb/v1/concepts/glossary/#timestamp) `1434055562000000000`. +- To **write to a database using the InfluxDB v1 API**, send `POST` requests to the `/write` endpoint. + + The following example shows how to write a point to the `mydb` database. The point data consists of the [measurement](/influxdb/v1/concepts/glossary/#measurement) `cpu_load_short`, the [tag keys](/influxdb/v1/concepts/glossary/#tag-key) `host` and `region` with the [tag values](/influxdb/v1/concepts/glossary/#tag-value) `server01` and `us-west`, the [field key](/influxdb/v1/concepts/glossary/#field-key) `value` with a [field value](/influxdb/v1/concepts/glossary/#field-value) of `0.64`, and the [timestamp](/influxdb/v1/concepts/glossary/#timestamp) `1434055562000000000`. ```bash curl -i -XPOST 'http://localhost:8086/write?db=mydb' diff --git a/content/influxdb/v1/introduction/install.md b/content/influxdb/v1/introduction/install.md index ad981026e..67501783a 100644 --- a/content/influxdb/v1/introduction/install.md +++ b/content/influxdb/v1/introduction/install.md @@ -213,13 +213,13 @@ If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/) For example: ``` - wget https://dl.influxdata.com/influxdb/releases/influxdb-{{< latest-patch >}}_linux_amd64.tar.gz.asc + wget https://download.influxdata.com/influxdb/releases/influxdb-{{< latest-patch >}}-linux-amd64.tar.gz.asc ``` 3. Verify the signature with `gpg --verify`: ``` - gpg --verify influxdb-{{< latest-patch >}}_linux_amd64.tar.gz.asc influxdb-{{< latest-patch >}}_linux_amd64.tar.gz + gpg --verify influxdb-{{< latest-patch >}}_linux_amd64.tar.gz.asc influxdb-{{< latest-patch >}}-linux-amd64.tar.gz ``` The output from this command should include the following: diff --git a/content/influxdb/v1/query_language/manage-database.md b/content/influxdb/v1/query_language/manage-database.md index 8922fed68..719075247 100644 --- a/content/influxdb/v1/query_language/manage-database.md +++ b/content/influxdb/v1/query_language/manage-database.md @@ -171,6 +171,11 @@ Delete all data in the database that occur before January 01, 2020: > DELETE WHERE time < '2020-01-01' ``` +Delete all data associated with the measurement `h2o_feet` in retention policy `one_day`: +``` +> DELETE FROM "one_day"."h2o_feet" +``` + A successful `DELETE` query returns an empty result. Things to note about `DELETE`: @@ -178,7 +183,8 @@ Things to note about `DELETE`: * `DELETE` supports [regular expressions](/influxdb/v1/query_language/explore-data/#regular-expressions) in the `FROM` clause when specifying measurement names and in the `WHERE` clause -when specifying tag values. +when specifying tag values. It *does not* support regular expressions for the retention policy in the `FROM` clause. +`DELETE` requires that you define *one* retention policy in the `FROM` clause. * `DELETE` does not support [fields](/influxdb/v1/concepts/glossary/#field) in the `WHERE` clause. * If you need to delete points in the future, you must specify that time period as `DELETE SERIES` runs for `time < now()` by default. [Syntax](https://github.com/influxdata/influxdb/issues/8007) diff --git a/content/influxdb/v1/query_language/spec.md b/content/influxdb/v1/query_language/spec.md index 23ebe27b0..3ffab21ed 100644 --- a/content/influxdb/v1/query_language/spec.md +++ b/content/influxdb/v1/query_language/spec.md @@ -1135,7 +1135,7 @@ SHOW TAG KEY EXACT CARDINALITY ### SHOW TAG KEYS ``` -show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ] +show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [with_key_clause] [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . ``` @@ -1153,6 +1153,9 @@ SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' -- show all tag keys where the host key = 'serverA' SHOW TAG KEYS WHERE "host" = 'serverA' + +-- show specific tag keys +SHOW TAG KEYS WITH KEY IN ("region", "host") ``` ### SHOW TAG VALUES diff --git a/content/influxdb/v1/tools/api.md b/content/influxdb/v1/tools/api.md index 0f743c231..7787bb76c 100644 --- a/content/influxdb/v1/tools/api.md +++ b/content/influxdb/v1/tools/api.md @@ -13,43 +13,67 @@ v2: /influxdb/v2/reference/api/ --- The InfluxDB API provides a simple way to interact with the database. -It uses HTTP response codes, HTTP authentication, JWT Tokens, and basic authentication, and responses are returned in JSON. +It uses HTTP authentication and JWT Tokens. +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/), +or the client of your choice. + +{{% note %}} +If you're getting started with InfluxDB v1, we recommend using the +InfluxDB v1 client libraries and InfluxQL for +[InfluxDB v3 compatibility](/influxdb/v1/tools/api/#influxdb-v3-compatibility). +{{% /note %}} The following sections assume your InfluxDB instance is running on `localhost` port `8086` and HTTPS is not enabled. Those settings [are configurable](/influxdb/v1/administration/config/#http-endpoints-settings). -- [InfluxDB 2.0 API compatibility endpoints](#influxdb-2-0-api-compatibility-endpoints) -- [InfluxDB 1.x HTTP endpoints](#influxdb-1-x-http-endpoints) +- [InfluxDB v3 compatibility](#influxdb-v3-compatibility) +- [InfluxDB 2.x API compatibility endpoints](#influxdb-2x-api-compatibility-endpoints) +- [InfluxDB 1.x HTTP endpoints](#influxdb-1x-http-endpoints) -## InfluxDB 2.0 API compatibility endpoints +## InfluxDB v3 compatibility -InfluxDB 1.8.0 introduced forward compatibility APIs for InfluxDB 2.0. -There are multiple reasons for introducing these: +InfluxDB v3 is InfluxDB’s next generation that allows +infinite series cardinality without impact on overall database performance, and +brings native SQL support and improved InfluxQL performance. -- The latest [InfluxDB client libraries](/influxdb/v1/tools/api_client_libraries/) - are built for the InfluxDB 2.0 API, but now also work with **InfluxDB 1.8.0+**. -- InfluxDB Cloud is a generally available service across multiple cloud service providers and regions - that is fully compatible with the **latest** client libraries. +InfluxDB v3 supports the v1 `/write` and `/query` HTTP API endpoints. +InfluxDB v3 isn't optimized for Flux. -If you are just getting started with InfluxDB 1.x today, we recommend adopting -the [latest client libraries](/influxdb/v1/tools/api_client_libraries/). -They allow you to easily move from InfluxDB 1.x to InfluxDB 2.0 Cloud or open source, -(when you are ready). +If you're getting started with InfluxDB v1, we recommend using the +InfluxDB v1 client libraries and InfluxQL. +When you're ready, you can migrate to InfluxDB v3 and continue using the v1 client +libraries as you gradually move your query workloads to use the v3 client libraries +(and the v3 Flight API). -The following forward compatible APIs are available: +For more information, see [API compatibility and migration guides for InfluxDB v3](/influxdb/cloud-dedicated/guides). -| Endpoint | Description | -|:---------- |:---------- | -| [/api/v2/query](#api-v2-query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB 2.0 API and [Flux](/flux/latest/) | -| [/api/v2/write](#api-v2-write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB 2.0 API _(compatible with InfluxDB 2.0 client libraries)_ | -| [/health](#health-http-endpoint) | Check the health of your InfluxDB instance | +## InfluxDB 2.x API compatibility endpoints + +InfluxDB 1.8.0 introduced forward compatibility APIs for InfluxDB v2. +[InfluxDB v2 client libraries](/influxdb/v1/tools/api_client_libraries/) +are built for the InfluxDB v2 API, but also work with **InfluxDB 1.8+**. + +InfluxDB v1 supports the following v2-compatible APIs: + +| Endpoint | Description | +| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | +| [/api/v2/query](#api-v2-query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB v2 API and [Flux](/flux/latest/) | +| [/api/v2/write](#api-v2-write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB v2 API _(compatible with InfluxDB v2 client libraries)_ | +| [/api/v2/buckets](#apiv2buckets-http-endpoint) | Allows some client code using buckets to run against 1.x and 2.x without modification | +| [/api/v2/delete](#apiv2delete-http-endpoint) | Supports deletion by tag value, timestamp, and measurement using the InfluxDB v2 API _(compatible with InfluxDB v2 client libraries)_ | +| [/health](#health-http-endpoint) | Check the health of your InfluxDB instance | ### `/api/v2/query/` HTTP endpoint The `/api/v2/query` endpoint accepts `POST` HTTP requests. -Use this endpoint to query data using [Flux](/influxdb/v1/flux/) and [InfluxDB 2.0 client libraries](/influxdb/v2/api-guide/client-libraries/). - Flux is the primary language for working with data in InfluxDB 2.0. +Use this endpoint to query data using [Flux](/influxdb/v1/flux/) and [InfluxDB v2 client libraries](/influxdb/v2/api-guide/client-libraries/). + Flux is the primary language for working with data in InfluxDB v2. **Include the following HTTP headers:** @@ -90,14 +114,14 @@ curl -XPOST localhost:8086/api/v2/query -sS \ ### `/api/v2/write/` HTTP endpoint The `/api/v2/write` endpoint accepts `POST` HTTP requests. -Use this endpoint to write to an InfluxDB 1.8.0+ database using [InfluxDB 2.0 client libraries](/influxdb/v2/api-guide/client-libraries/). +Use this endpoint to write to an InfluxDB 1.8.0+ database using [InfluxDB v2 client libraries](/influxdb/v2/api-guide/client-libraries/). Both InfluxDB 1.x and 2.0 APIs support the same line protocol format for raw time series data. For the purposes of writing data, the APIs differ only in the URL parameters and request headers. -InfluxDB 2.0 uses [organizations](/influxdb/v2/reference/glossary/#organization) +InfluxDB v2 uses [organizations](/influxdb/v2/reference/glossary/#organization) and [buckets](/influxdb/v2/reference/glossary/#bucket) instead of databases and retention policies. -The `/api/v2/write` endpoint maps the supplied version 1.8 database and retention policy to a bucket. +The `/api/v2/write` endpoint maps the supplied version 1.x database and retention policy to a bucket. **Include the following URL parameters:** @@ -112,7 +136,7 @@ The `/api/v2/write` endpoint maps the supplied version 1.8 database and retentio **Include the following HTTP header:** -- `Authorization`: In InfluxDB 2.0 uses [API Tokens](/influxdb/v2/admin/tokens/) +- `Authorization`: In InfluxDB v2 uses [API Tokens](/influxdb/v2/admin/tokens/) to access the platform and all its capabilities. InfluxDB v1.x uses a username and password combination when accessing the HTTP APIs. Use the Token schema to provide your InfluxDB 1.x username and password separated by a colon (`:`). @@ -138,6 +162,105 @@ curl -XPOST "localhost:8086/api/v2/write?bucket=db/rp&precision=s" \ {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +### `/api/v2/buckets/` HTTP endpoint + +The [/api/v2/buckets](/influxdb/v2/api/#tag/Buckets) endpoint accepts `GET`, +`POST` and `DELETE` HTTP requests. Use this endpoint to +[create](/influxdb/v2/api/#operation/PostBuckets), +[delete](/influxdb/v2/api/#operation/DeleteBucketsID), +[list](/influxdb/v2/api/#operation/GetBuckets), +[update](/influxdb/v2/api/#operation/PatchBucketsID) and +[retrieve](/influxdb/v2/api/#operation/GetBucketsID) +buckets in your InfluxDB instance. Note that InfluxDB 2.x uses organizations and +buckets instead of databases and retention policies. + +**Include the following URL parameters:** + +- `bucket`: Provide the database name and retention policy separated by a forward slash (`/`). + For example: `database/retention-policy`. + Empty retention policies map to the default retention policy. +- `org`: In InfluxDB 1.x, there is no concept of organization. The `org` parameter is ignored and can be left empty. + +**Include the following HTTP header:** + +- `Authorization`: InfluxDB 2.x uses this header with the `Token` scheme and + [API Tokens](/influxdb/v2/admin/tokens/) to authenticate each API request. + InfluxDB v1.x uses username and password credentials for authenticating API requests. + To provide InfluxDB 1.x credentials, use the `Token` scheme and include your + username and password separated by a colon (`:`). + + - `Token` scheme with v1.x credentials: + + ``` + Authorization: Token USERNAME:PASSWORD + ``` + +The following example shows how to list all databases: + +```bash +curl --request GET "http://localhost:8086/api/v2/buckets" + -H 'Authorization: Token :' +``` + +The following example shows how to delete a database named `test`: + +```bash +curl --request DELETE "http://localhost:8086/api/v2/buckets/test/autogen" + --header "Content-type: application/json" + -H 'Authorization: Token :' +``` + +### `/api/v2/delete/` HTTP endpoint + +The [`/api/v2/delete`](/influxdb/v2/api/#tag/Delete) endpoint accepts `POST` HTTP requests. Use this endpoint to delete points from InfluxDB, including points with specific tag values, timestamps and measurements. + +**Include the following URL parameters:** + +- `bucket`: Provide the database name and retention policy separated by a forward slash (`/`). + For example: `database/retention-policy`. +- `precision`: Precision of timestamps in the line protocol. + Accepts `ns` (nanoseconds), `us`(microseconds), `ms` (milliseconds) and `s` (seconds). + +**Include the following HTTP header:** + +- `Authorization`: InfluxDB 2.x uses this header with the `Token` scheme and [API Tokens](/influxdb/v2/admin/tokens/) + to authenticate each API request. + InfluxDB v1.x uses username and password credentials for authenticating API requests. + To provide InfluxDB 1.x credentials, use the `Token` scheme and include your username and password separated by a colon (`:`). + + - `Token` scheme with v1.x credentials: + + ```http + Authorization: Token USERNAME:PASSWORD + ``` + +Delete all points in a specified time range: + +```bash +curl --request POST "http://localhost:8086/api/v2/delete?bucket=exampleDB/autogen \ + --header 'Authorization: Token :' \ + --header 'Content-Type: application/json' \ + --data '{ + "start": "2020-03-01T00:00:00Z", + "stop": "2020-11-14T00:00:00Z" + }' +``` + +Delete points in a specific measurement with a specific tag value: + +```bash +curl --request POST "http://localhost:8086/api/v2/delete?bucket=exampleDB/autogen \ + --header 'Authorization: Token :' \ + --header 'Content-Type: application/json' \ + --data '{ + "start": "2020-03-01T00:00:00Z", + "stop": "2020-11-14T00:00:00Z", + "predicate": "_measurement=\"example-measurement\" AND exampleTag=\"exampleTagValue\"" + }' +``` + +If you use the `predicate` option in your request, review [delete predicate syntax](/influxdb/v2/reference/syntax/delete-predicate/) and note its [limitations](/influxdb/v2/reference/syntax/delete-predicate/#limitations). + ### `/health` HTTP endpoint The `/health` endpoint accepts `Get` HTTP requests. Use this endpoint to check the health of your InfluxDB instance. diff --git a/content/influxdb/v1/tools/api_client_libraries.md b/content/influxdb/v1/tools/api_client_libraries.md index 36483663a..e030250c8 100644 --- a/content/influxdb/v1/tools/api_client_libraries.md +++ b/content/influxdb/v1/tools/api_client_libraries.md @@ -13,15 +13,16 @@ menu: v2: /influxdb/v2/api-guide/client-libraries/ --- -InfluxDB client libraries are language-specific packages that integrate with the InfluxDB 2.0 API and support both **InfluxDB 1.8+** and **InfluxDB 2.0**. +InfluxDB v2 client libraries are language-specific packages that integrate +with the InfluxDB v2 API and support both **InfluxDB 1.8+** and **InfluxDB 2.x**. {{% note %}} -We recommend using the new client libraries on this page to leverage the new -read (via Flux) and write APIs and prepare for conversion to InfluxDB v2 and -InfluxDB Cloud. -For more information, see [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1/tools/api/#influxdb-2-0-api-compatibility-endpoints). -Client libraries for [InfluxDB 1.7 and earlier](/influxdb/v1/tools/api_client_libraries/) -may continue to work, but are not maintained by InfluxData. +If you're getting started with InfluxDB v1, we recommend using the +InfluxDB v1 client libraries and InfluxQL for +[InfluxDB v3 compatibility](/influxdb/v1/tools/api/#influxdb-v3-compatibility). + +For more information about API and client library compatibility, see the +[InfluxDB v1 API reference](/influxdb/v1/tools/api/). {{% /note %}} ## Client libraries diff --git a/content/influxdb/v1/tools/flux-vscode.md b/content/influxdb/v1/tools/flux-vscode.md index e5a9dfa79..0461f7813 100644 --- a/content/influxdb/v1/tools/flux-vscode.md +++ b/content/influxdb/v1/tools/flux-vscode.md @@ -18,15 +18,15 @@ provides Flux syntax highlighting, autocompletion, and a direct InfluxDB server integration that lets you run Flux scripts natively and show results in VS Code. {{% note %}} -#### Enable Flux in InfluxDB 1.8 -To use the Flux VS Code extension with InfluxDB 1.8, ensure Flux is enabled in +#### Enable Flux in InfluxDB 1.11 +To use the Flux VS Code extension with InfluxDB 1.11, ensure Flux is enabled in your InfluxDB configuration file. For more information, see [Enable Flux](/influxdb/v1/flux/installation/). {{% /note %}} ##### On this page - [Install the Flux VS Code extension](#install-the-flux-vs-code-extension) -- [Connect to InfluxDB 1.8](#connect-to-influxdb-18) +- [Connect to InfluxDB 1.11](#connect-to-influxdb-111) - [Query InfluxDB from VS Code](#query-influxdb-from-vs-code) - [Explore your schema](#explore-your-schema) - [Debug Flux queries](#debug-flux-queries) @@ -38,7 +38,7 @@ The Flux VS Code extension is available in the **Visual Studio Marketplace**. For information about installing extensions from the Visual Studio marketplace, see the [Extension Marketplace documentation](https://code.visualstudio.com/docs/editor/extension-gallery). -## Connect to InfluxDB 1.8 +## Connect to InfluxDB 1.11 To create an InfluxDB connection in VS Code: 1. Open the **VS Code Command Pallet** ({{< keybind mac="⇧⌘P" other="Ctrl+Shift+P" >}}). diff --git a/content/influxdb/v1/tools/grafana.md b/content/influxdb/v1/tools/grafana.md index 6b3bf8f34..5538c4983 100644 --- a/content/influxdb/v1/tools/grafana.md +++ b/content/influxdb/v1/tools/grafana.md @@ -1,8 +1,8 @@ --- title: Use Grafana with InfluxDB -seotitle: Use Grafana with InfluxDB v1.8 +seotitle: Use Grafana with InfluxDB v1.11 description: > - Configure Grafana to query and visualize data from InfluxDB v1.8. + Configure Grafana to query and visualize data from InfluxDB v1.11. menu: influxdb_v1: name: Grafana @@ -13,7 +13,7 @@ canonical: /influxdb/v2/tools/grafana/ --- Use [Grafana](https://grafana.com/) or [Grafana Cloud](https://grafana.com/products/cloud/) -to visualize data from your **InfluxDB v1.8** instance. +to visualize data from your **InfluxDB v1.11** instance. {{% note %}} #### Required diff --git a/content/influxdb/v1/tools/influx-cli/_index.md b/content/influxdb/v1/tools/influx-cli/_index.md index f3c7efa3c..b6523f062 100644 --- a/content/influxdb/v1/tools/influx-cli/_index.md +++ b/content/influxdb/v1/tools/influx-cli/_index.md @@ -8,9 +8,8 @@ menu: v2: /influxdb/v2/reference/cli/influx/ --- -The `influx` command line interface (CLI) provides an interactive shell for the HTTP API associated with `influxd`. -Use `influx` to write data (manually or from a file), query data interactively, and view query output in different formats. - +The `influx` command line interface (CLI) provides an interactive shell for the HTTP API associated with `influxd`. +It includes commands for writing and querying data, and managing many aspects of InfluxDB, including databases, organizations, users, and tasks. ## Usage @@ -18,28 +17,29 @@ Use `influx` to write data (manually or from a file), query data interactively, influx [flags] ``` - ## Flags {.no-shorthand} -| Flag | Description | -|-------------------|-------------------------------------------------------------------------------------------------------| -| `-version` | Display the version and exit | -| `-url-prefix` | Path to add to the URL after the host and port. Specifies a custom endpoint to connect to. | -| `-host` | HTTP address of InfluxDB (default: `http://localhost:8086`) | -| `-port` | Port to connect to | -| `-socket` | Unix socket to connect to | -| `-database` | Database to connect to the server | -| `-password` | Password to connect to the server. Leaving blank will prompt for password (`--password ''`). | -| `-username` | Username to connect to the server | -| `-ssl` | Use https for requests | -| `-unsafessl` | Set this when connecting to the cluster using https | -| `-execute` | Execute command and quit | -| `-type` | Specify the query language for executing commands or when invoking the REPL. | -| `-format` | Specify the format of the server responses: json, csv, or column | -| `-precision` | Specify the format of the timestamp: rfc3339, h, m, s, ms, u or ns | -| `-consistency` | Set write consistency level: any, one, quorum, or all | -| `-pretty` | Turns on pretty print for JSON format | -| `-import` | Import a previous database export from file | -| `-pps` | Points per second the import will allow. The default is `0` and will not throttle importing. | -| `-path` | Path to file to import | -| `-compressed` | Set to true if the import file is compressed | +| Flag | Description | +| -------------- | --------------------------------------------------------------------------------------------- | +| `-version` | Display the version and exit | +| `-url-prefix` | Path to add to the URL after the host and port. Specifies a custom endpoint to connect to. | +| `-host` | HTTP address of InfluxDB (default: `http://localhost:8086`) | +| `-port` | Port to connect to | +| `-socket` | Unix socket to connect to | +| `-database` | Database to connect to the server | +| `-password` | Password to connect to the server. Leaving blank will prompt for password (`--password ''`). | +| `-username` | Username to connect to the server | +| `-ssl` | Use https for requests | +| `-unsafessl` | Set this when connecting to the cluster using https | +| `-execute` | Execute command and quit | +| `-type` | Specify the query language for executing commands or when invoking the REPL: influxql or flux | +| `-format` | Specify the format of the server responses: json, csv, or column | +| `-precision` | Specify the format of the timestamp: rfc3339, h, m, s, ms, u or ns | +| `-consistency` | Set write consistency level: any, one, quorum, or all | +| `-pretty` | Turns on pretty print for JSON format | +| `-import` | Import a previous database export from file | +| `-pps` | Points per second the import will allow. The default is `0` and will not throttle importing. | +| `-path` | Path to file to import | +| `-compressed` | Set to true if the import file is compressed | + +{{< children >}} \ No newline at end of file diff --git a/content/influxdb/v1/tools/shell.md b/content/influxdb/v1/tools/influx-cli/use-influx-cli.md similarity index 70% rename from content/influxdb/v1/tools/shell.md rename to content/influxdb/v1/tools/influx-cli/use-influx-cli.md index 7309553f7..41818193d 100644 --- a/content/influxdb/v1/tools/shell.md +++ b/content/influxdb/v1/tools/influx-cli/use-influx-cli.md @@ -3,35 +3,71 @@ title: Using influx - InfluxDB command line interface description: InfluxDB's command line interface (`influx`) is an interactive shell for the HTTP API. menu: influxdb_v1: - name: Using influx + name: Use influx CLI weight: 10 - parent: Guides + parent: influx +aliases: + - /influxdb/v1/tools/shell/ +related: + - /influxdb/v1/administration/backup_and_restore/ --- -InfluxDB's command line interface (`influx`) is an interactive shell for the HTTP API. -Use `influx` to write data (manually or from a file), query data interactively, and view query output in different formats. +The `influx` command line interface (CLI) provides an interactive shell for the HTTP API associated with `influxd`. +Use `influx` to write data (manually or from a file), query data interactively, view query output in different formats, and manage resources in InfluxDB. -* [Launch `influx`](/influxdb/v1/tools/shell/#launch-influx) -* [`influx` Arguments](/influxdb/v1/tools/shell/#influx-arguments) -* [`influx` Commands](/influxdb/v1/tools/shell/#influx-commands) +* [Launch `influx`](#launch-influx) +* [`influx` Arguments](#influx-arguments) +* [`influx` Commands](#influx-commands) ## Launch `influx` -If you [install](https://influxdata.com/downloads/) InfluxDB via a package manager, the CLI is installed at `/usr/bin/influx` (`/usr/local/bin/influx` on macOS). + +The `influx` CLI is included when you [install InfluxDB OSS {{< current-version >}}](/influxdb/v1/introduction/install/). + +The `influx` CLI is installed at the following path, depending on your +system and package manager: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Linux](#linux) +[macOS](#macos) +[Homebrew](#homebrew) +{{% /code-tabs %}} +{{% code-tab-content %}} +```bash +/usr/bin/influx +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```bash +/usr/local/bin/influx +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```bash +/opt/homebrew/opt/influxdb@1/bin/influx +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} To access the CLI, first launch the `influxd` database process and then launch `influx` in your terminal. -Once you've entered the shell and successfully connected to an InfluxDB node, you'll see the following output: -
-
+ ```bash -$ influx -Connected to http://localhost:8086 version {{< latest-patch >}} -InfluxDB shell version: {{< latest-patch >}} +influx ``` -> **Note:** The versions of InfluxDB and the CLI should be identical. If not, parsing issues can occur with queries. +If successfully connected to an InfluxDB node, the output is the following: -You can now enter InfluxQL queries as well as some CLI-specific commands directly in your terminal. -You can use `help` at any time to get a list of available commands. Use `Ctrl+C` to cancel if you want to cancel a long-running InfluxQL query. +```bash +Connected to http://localhost:8086 version {{< latest-patch >}} +InfluxDB shell version: {{< latest-patch >}} +> +``` + +_The versions of InfluxDB and the CLI should be identical. If not, parsing issues can occur with queries._ + +In the prompt, you can enter InfluxQL queries as well as CLI-specific commands. +Enter `help` to get a list of available commands. +Use `Ctrl+C` to cancel if you want to cancel a long-running InfluxQL query. ## Environment Variables @@ -64,12 +100,14 @@ List of host names that should **not** go through any proxy. If set to an asteri NO_PROXY=123.45.67.89,123.45.67.90 ``` - ## `influx` Arguments -There are several arguments you can pass into `influx` when starting. -List them with `$ influx --help`. -The list below offers a brief discussion of each option. -We provide detailed information on `-execute`, `-format`, and `-import` at the end of this section. + +Arguments specify connection, write, import, and output options for the CLI session. + +`influx` provides the following arguments: + +`-h`, `-help` +List `influx` arguments `-compressed` Set to true if the import file is compressed. @@ -94,8 +132,8 @@ The host to which `influx` connects. By default, InfluxDB runs on localhost. `-import` -Import new data from a file or import a previously [exported](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md) database from a file. -See [-import](/influxdb/v1/tools/shell/#import-data-from-a-file-with-import). +Import new data or [exported data](/enterprise_influxdb/v1/administration/backup-and-restore/#exporting-data) from a file. +See [-import](#import-data-from-a-file). `-password 'password'` The password `influx` uses to connect to the server. @@ -105,7 +143,7 @@ variable. `-path` The path to the file to import. -Use with `-import`. +Use with[-import](#import-data-from-a-file). `-port 'port #'` The port to which `influx` connects. @@ -139,6 +177,12 @@ Alternatively, set the username for the CLI with the `INFLUX_USERNAME` environme `-version` Display the InfluxDB version and exit. +The following sections provide detailed examples for some arguments, including `-execute`, `-format`, and `-import`. + +- [Execute an InfluxQL command and quit with `-execute`](#execute-an-influxql-command-and-quit-with--execute) +- [Specify the format of the server responses with `-format`](#specify-the-format-of-the-server-responses-with--format) +- [Import data from a file](#import-data-from-a-file) + ### Execute an InfluxQL command and quit with `-execute` Execute queries that don't require a database specification: @@ -241,13 +285,13 @@ $ influx -format=json -pretty } ``` -### Import data from a file with `-import` +### Import data from a file -The import file has two sections: +An import file has two sections: -* **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/influxdb/v1/query_language/manage-database/) for creating the relevant [database](/influxdb/v1/concepts/glossary/) and managing the [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp). +- _Optional_: **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/influxdb/v1/query_language/manage-database/) for creating the relevant [database](/influxdb/v1/concepts/glossary/) and managing the [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp). If your database and retention policy already exist, your file can skip this section. -* **DML (Data Manipulation Language)**: Lists the relevant database and (if desired) retention policy and contains the data in [line protocol](/influxdb/v1/concepts/glossary/#influxdb-line-protocol). +- **DML (Data Manipulation Language)**: Context metadata that specifies the database and (if desired) retention policy for the import and contains the data in [line protocol](/influxdb/v1/concepts/glossary/#influxdb-line-protocol). Example: @@ -279,27 +323,31 @@ Results: 2015/12/22 12:25:06 Processed 5 inserts 2015/12/22 12:25:06 Failed 0 inserts ``` - -> **Note:** For large datasets, `influx` writes out a status message every 100,000 points. - -For example: +> [!Note] +> For large datasets, `influx` writes out a status message every 100,000 points. +> +> For example: > - 2015/08/21 14:48:01 Processed 3100000 lines. - Time elapsed: 56.740578415s. - Points per second (PPS): 54634 +> ```sh +> 2015/08/21 14:48:01 Processed 3100000 lines. +> Time elapsed: 56.740578415s. +> Points per second (PPS): 54634 +> ``` Things to note about `-import`: -* Allow the database to ingest points by using `-pps` to set the number of points per second allowed by the import. By default, pps is zero and `influx` does not throttle importing. -* Imports work with `.gz` files, just include `-compressed` in the command. -* Include timestamps in the data file. InfluxDB will assign the same timestamp to points without a timestamp. This can lead to unintended [overwrite behavior](/influxdb/v1/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points). -* If your data file has more than 5,000 points, it may be necessary to split that file into several files in order to write your data in batches to InfluxDB. -We recommend writing points in batches of 5,000 to 10,000 points. -Smaller batches, and more HTTP requests, will result in sub-optimal performance. -By default, the HTTP request times out after five seconds. -InfluxDB will still attempt to write the points after that time out but there will be no confirmation that they were successfully written. +- To throttle the import, use `-pps` to set the number of points per second to ingest. By default, pps is zero and `influx` does not throttle importing. +- To import a file compressed with `gzip` (GNU zip), include the -compressed flag. +- Include timestamps in the data file. + If points don’t include a timestamp, InfluxDB assigns the same timestamp to those points, which can result in unintended [duplicate points or overwrites](/influxdb/v1/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points). +- If your data file contains more than 5,000 points, consider splitting it into smaller files to write data to InfluxDB in batches. + We recommend writing points in batches of 5,000 to 10,000 for optimal performance. + Writing smaller batches increases the number of HTTP requests, which can negatively impact performance. + By default, the HTTP request times out after five seconds. Although InfluxDB continues attempting to write the points after a timeout, you won’t receive confirmation of a successful write. -> **Note:** For how to export data from InfluxDB version 0.8.9, see [Exporting from 0.8.9](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md). +> **Note:** To export data from InfluxDB version 0.8.9, see [Exporting from 0.8.9](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md). + +For more information, see [exporting and importing data](/influxdb/v1/administration/backup_and_restore/#exporting-and-importing-data). ## `influx` commands diff --git a/content/influxdb/v1/tools/influx_inspect.md b/content/influxdb/v1/tools/influx_inspect.md index e8d3f23a7..b53b887e7 100644 --- a/content/influxdb/v1/tools/influx_inspect.md +++ b/content/influxdb/v1/tools/influx_inspect.md @@ -29,18 +29,21 @@ influx_inspect [ [ command ] [ options ] ] The `influx_inspect` commands are summarized here, with links to detailed information on each of the commands. -* [`buildtsi`](#buildtsi): Converts in-memory (TSM-based) shards to TSI. -* [`deletetsm`](#deletetsm): Bulk deletes a measurement from a raw TSM file. -* [`dumptsi`](#dumptsi): Dumps low-level details about TSI files. -* [`dumptsm`](#dumptsm): Dumps low-level details about TSM files. -* [`dumptsmwal`](#dumptsmwal): Dump all data from a WAL file. -* [`export`](#export): Exports raw data from a shard in InfluxDB line protocol format. -* [`report`](#report): Displays a shard level report. -* [`report-disk`](#report-disk): Reports disk usage by shards and measurements. -* [`reporttsi`](#reporttsi): Reports on cardinality for shards and measurements. -* [`verify`](#verify): Verifies the integrity of TSM files. -* [`verify-seriesfile`](#verify-seriesfile): Verifies the integrity of series files. -* [`verify-tombstone`](#verify-tombstone): Verifies the integrity of tombstones. +- [`buildtsi`](#buildtsi): Converts in-memory (TSM-based) shards to TSI. +- [`check-schema`](#check-schema): Checks for type conflicts between shards. +- [`deletetsm`](#deletetsm): Bulk deletes a measurement from a raw TSM file. +- [`dumptsi`](#dumptsi): Dumps low-level details about TSI files. +- [`dumptsm`](#dumptsm): Dumps low-level details about TSM files. +- [`dumptsmwal`](#dumptsmwal): Dump all data from a WAL file. +- [`export`](#export): Exports raw data from a shard in InfluxDB line protocol format. +- [`merge-schema`](#merge-schema): Merges a set of schema files from the `check-schema` command. +- [`report`](#report): Displays a shard level report. +- [`report-db`](#report-db): Estimates InfluxDB Cloud (TSM) cardinality for a database. +- [`report-disk`](#report-disk): Reports disk usage by shards and measurements. +- [`reporttsi`](#reporttsi): Reports on cardinality for shards and measurements. +- [`verify`](#verify): Verifies the integrity of TSM files. +- [`verify-seriesfile`](#verify-seriesfile): Verifies the integrity of series files. +- [`verify-tombstone`](#verify-tombstone): Verifies the integrity of tombstones. ### `buildtsi` @@ -88,7 +91,11 @@ The name of the database. ##### `-datadir ` -The path to the `data` directory. +The path to the [`data` directory](/influxdb/v1/concepts/file-system-layout/#data-directory). + +Default value is `$HOME/.influxdb/data`. +See the [file system layout](/influxdb/v1/concepts/file-system-layout/#file-system-layout) +for InfluxDB on your system. ##### `[ -max-cache-size ]` @@ -115,7 +122,11 @@ Flag to enable output in verbose mode. ##### `-waldir ` -The directory for the WAL (Write Ahead Log) files. +The directory for the (WAL (Write Ahead Log)](/influxdb/v1/concepts/file-system-layout/#wal-directory) files. + +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. #### Examples @@ -139,6 +150,31 @@ $ influx_inspect buildtsi -database mydb -datadir ~/.influxdb/data -waldir ~/.in $ influx_inspect buildtsi -database stress -shard 1 -datadir ~/.influxdb/data -waldir ~/.influxdb/wal ``` +### `check-schema` + +Check for type conflicts between shards. + +#### Syntax + +``` +influx_inspect check-schema [ options ] +``` + +#### Options + +##### [ `-conflicts-file ` ] + +The filename where conflicts data should be written. Default is `conflicts.json`. + +##### [ `-path ` ] + +Directory path where `fields.idx` files are located. Default is the current +working directory `.`. + +##### [ `-schema-file ` ] + +The filename where schema data should be written. Default is `schema.json`. + ### `deletetsm` Use `deletetsm -measurement` to delete a measurement in a raw TSM file (from specified shards). @@ -211,7 +247,7 @@ Optional arguments are in brackets. ##### `-series-file ` -Path to the `_series` directory under the database `data` directory. Required. +The path to the `_series` directory under the database `data` directory. Required. ##### [ `-series` ] @@ -276,7 +312,7 @@ influx_inspect dumptsm [ options ] ##### `` -Path to the `.tsm` file, located by default in the `data` directory. +The path to the `.tsm` file, located by default in the `data` directory. #### Options @@ -284,17 +320,17 @@ Optional arguments are in brackets. ##### [ `-index` ] -Flag to dump raw index data. +The flag to dump raw index data. Default value is `false`. ##### [ `-blocks` ] -Flag to dump raw block data. +The flag to dump raw block data. Default value is `false`. ##### [ `-all` ] -Flag to dump all data. Caution: This may print a lot of information. +The flag to dump all data. Caution: This may print a lot of information. Default value is `false`. ##### [ `-filter-key ` ] @@ -318,7 +354,7 @@ Optional arguments are in brackets. ##### [ `-show-duplicates` ] -Flag to show keys which have duplicate or out-of-order timestamps. +The flag to show keys which have duplicate or out-of-order timestamps. If a user writes points with timestamps set by the client, then multiple points with the same timestamp (or with time-descending timestamps) can be written. ### `export` @@ -349,8 +385,11 @@ Default value is `""`. ##### `-datadir ` -The path to the `data` directory. -Default value is `"$HOME/.influxdb/data"`. +The path to the [`data` directory](/influxdb/v1/concepts/file-system-layout/#data-directory). + +Default value is `$HOME/.influxdb/data`. +See the [file system layout](/influxdb/v1/concepts/file-system-layout/#file-system-layout) +for InfluxDB on your system. ##### [ `-end ` ] @@ -377,13 +416,14 @@ YYYY-MM-DDTHH:MM:SS+07:00 ##### [ `-lponly` ] Output data in line protocol format only. -Does not include comments or data definition language (DDL), like `CREATE DATABASE`. +Does not output data definition language (DDL) statements (such as `CREATE DATABASE`) +or DML context metadata (such as `# CONTEXT-DATABASE`). ##### [ `-out ` or `-out -`] Location to export shard data. Specify an export directory to export a file, or add a hyphen after out (`-out -`) to export shard data to standard out (`stdout`) and send status messages to standard error (`stderr`). -Default value is `"$HOME/.influxdb/export"`. +Default value is `$HOME/.influxdb/export`. ##### [ `-retention ` ] @@ -397,7 +437,10 @@ The timestamp string must be in [RFC3339 format](https://tools.ietf.org/html/rfc ##### [ `-waldir ` ] Path to the [WAL](/influxdb/v1/concepts/glossary/#wal-write-ahead-log) directory. -Default value is `"$HOME/.influxdb/wal"`. + +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. #### Examples @@ -410,23 +453,43 @@ influx_inspect export -compress ##### Export data from a specific database and retention policy ```bash -influx_inspect export -database mydb -retention autogen +influx_inspect export -database DATABASE_NAME -retention RETENTION_POLICY ``` ##### Output file ```bash # DDL -CREATE DATABASE MY_DB_NAME -CREATE RETENTION POLICY autogen ON MY_DB_NAME DURATION inf REPLICATION 1 +CREATE DATABASE DATABASE_NAME +CREATE RETENTION POLICY ON DURATION inf REPLICATION 1 # DML -# CONTEXT-DATABASE:MY_DB_NAME -# CONTEXT-RETENTION-POLICY:autogen +# CONTEXT-DATABASE:DATABASE_NAME +# CONTEXT-RETENTION-POLICY:RETENTION_POLICY randset value=97.9296104805 1439856000000000000 randset value=25.3849066842 1439856100000000000 ``` +### `merge-schema` + +Merge a set of schema files from the [`check-schema` command](#check-schema). + +#### Syntax + +``` +influx_inspect merge-schema [ options ] +``` + +#### Options + +##### [ `-conflicts-file ` ] + +Filename conflicts data should be written to. Default is `conflicts.json`. + +##### [ `-schema-file ` ] + +Filename for the output file. Default is `schema.json`. + ### `report` Displays series metadata for all shards. @@ -462,6 +525,48 @@ The flag to report exact cardinality counts instead of estimates. Default value is `false`. Note: This can use a lot of memory. +### `report-db` + +Use the `report-db` command to estimate the series cardinality of data in a +database when migrated to InfluxDB Cloud (TSM). InfluxDB Cloud (TSM) includes +fields keys in the series key so unique field keys affect the total cardinality. +The total series cardinality of data in a InfluxDB 1.x database may differ from +from the series cardinality of that same data when migrated to InfluxDB Cloud (TSM). + +#### Syntax + +``` +influx_inspect report-db [ options ] +``` + +#### Options + +##### [ `-c ` ] + +Set worker concurrency. Default is `1`. + +##### `-db-path ` + +{{< req >}}: The path to the database. + +##### [ `-detailed` ] + +Include counts for fields, tags in the command output. + +##### [ `-exact` ] + +Report exact cardinality counts instead of estimates. +This method of calculation can use a lot of memory. + +##### [ `-rollup ` ] + +Specify the cardinality "rollup" level--the granularity of the cardinality report: + +- `t`: total +- `d`: database +- `r`: retention policy +- `m`: measurement (Default) + ### `report-disk` Use the `report-disk` command to review disk usage by shards and measurements for TSM files in a specified directory. Useful for determining disk usage for capacity planning and identifying which measurements or shards are using the most space. @@ -480,7 +585,7 @@ influx_inspect report-disk [ options ] ##### `` -Path to the directory with `.tsm` file(s) to report disk usage for. Default location is `"$HOME/.influxdb/data"`. +Path to the directory with `.tsm` file(s) to report disk usage for. Default location is `$HOME/.influxdb/data`. When specifying the path, wildcards (`*`) can replace one or more characters. diff --git a/content/influxdb/v2/admin/backup-restore/backup.md b/content/influxdb/v2/admin/backup-restore/backup.md index e1ee64638..a38ae9a89 100644 --- a/content/influxdb/v2/admin/backup-restore/backup.md +++ b/content/influxdb/v2/admin/backup-restore/backup.md @@ -28,9 +28,8 @@ The InfluxDB {{< current-version >}} `influx backup` command is not compatible w - [Manually upgrade from InfluxDB 1.x to {{< current-version >}}](/influxdb/v2/upgrade/v1-to-v2/manual-upgrade/) {{% /note %}} -{{% cloud %}} -The `influx backup` command **cannot** back up data stored in **InfluxDB Cloud**. -{{% /cloud %}} +> [!Important] +> The `influx backup` command **cannot** back up data stored in **InfluxDB Cloud**. The `influx backup` command requires: diff --git a/content/influxdb/v2/admin/backup-restore/restore.md b/content/influxdb/v2/admin/backup-restore/restore.md index 771aae769..9a1b0fb1d 100644 --- a/content/influxdb/v2/admin/backup-restore/restore.md +++ b/content/influxdb/v2/admin/backup-restore/restore.md @@ -15,9 +15,8 @@ related: - /influxdb/v2/reference/cli/influxd/restore/ --- -{{% cloud %}} -Restores **not supported in InfluxDB Cloud**. -{{% /cloud %}} +> [!Important] +> Restores **not supported in InfluxDB Cloud**. Use the `influx restore` command to restore backup data and metadata from InfluxDB OSS. diff --git a/content/influxdb/v2/admin/buckets/create-bucket.md b/content/influxdb/v2/admin/buckets/create-bucket.md index 3bceab5d8..077a587c8 100644 --- a/content/influxdb/v2/admin/buckets/create-bucket.md +++ b/content/influxdb/v2/admin/buckets/create-bucket.md @@ -11,9 +11,12 @@ menu: weight: 201 aliases: - /influxdb/v2/organizations/buckets/create-bucket/ +related: + - /influxdb/v2/reference/internals/data-retention/ + --- -Use the InfluxDB user interface (UI) the `influx` command line interface (CLI), +Use the InfluxDB user interface (UI), the `influx` command line interface (CLI), or the InfluxDB API to create a bucket. {{% note %}} @@ -42,10 +45,10 @@ There are two places you can create a bucket in the UI. 1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. -{{< nav-icon "data" >}} + {{< nav-icon "data" >}} 2. Click **{{< icon "plus" >}} Create Bucket** in the upper right. -3. Enter a **Name** for the bucket +3. Enter a **Name** for the bucket _(see [Bucket naming restrictions](#bucket-naming-restrictions))_. 4. Select when to **Delete Data**: - **Never** to retain data forever. @@ -54,12 +57,12 @@ There are two places you can create a bucket in the UI. ### Create a bucket in the Data Explorer -1. In the navigation menu on the left, select **Explore* (**Data Explorer**). +1. In the navigation menu on the left, select **Explore (Data Explorer)**. -{{< nav-icon "data-explorer" >}} + {{< nav-icon "data-explorer" >}} 2. In the **From** panel in the Flux Builder, select `+ Create Bucket`. -3. Enter a **Name** for the bucket +3. Enter a **Name** for the bucket _(see [Bucket naming restrictions](#bucket-naming-restrictions))_. 4. Select when to **Delete Data**: - **Never** to retain data forever. diff --git a/content/influxdb/v2/admin/security/enable-tls.md b/content/influxdb/v2/admin/security/enable-tls.md index a7a854166..4e7648870 100644 --- a/content/influxdb/v2/admin/security/enable-tls.md +++ b/content/influxdb/v2/admin/security/enable-tls.md @@ -15,15 +15,12 @@ aliases: Enabling TLS encrypts the communication between clients and the InfluxDB server. When configured with a signed certificate, TLS also allows clients to verify the authenticity of the InfluxDB server. -To set up TLS over HTTPS, do the following: +Follow steps to set up TLS over HTTPS, connect to your server, and troubleshoot problems: - [Obtain requirements](#obtain-requirements) - - [Single domain certificates signed by a Certificate Authority (CA)](#single-domain-certificates-signed-by-a-certificate-authority-ca) - - [Wildcard certificates signed by a Certificate Authority](#wildcard-certificates-signed-by-a-certificate-authority) - - [Self-signed certificates](#self-signed-certificates) - [Configure InfluxDB to use TLS](#configure-influxdb-to-use-tls) - [Connect Telegraf to a secured InfluxDB instance](#connect-telegraf-to-a-secured-influxdb-instance) - - [Example configuration](#example-configuration) +- [Troubleshoot TLS](#troubleshoot-tls) {{% warn %}} InfluxData **strongly recommends** enabling HTTPS, especially if you plan on sending requests to InfluxDB over a network. @@ -58,86 +55,191 @@ You can generate a self-signed certificate on your own machine. ## Configure InfluxDB to use TLS -1. **Download or generate certificate files** +1. [Download or generate certificate files](#download-or-generate-certificate-files) +2. [Set certificate file permissions](#set-certificate-file-permissions) +3. [Run `influxd` with TLS flags](#run-influxd-with-tls-flags) +4. [Verify TLS connection](#verify-tls-connection) - If using a [certificate signed by a CA](#single-domain-certificates-signed-by-a-certificate-authority-ca), follow their instructions to download and install the certificate files. - Note the location where certificate files are installed, and then continue to [set certificate file permissions](#set-certificate-file-permissions). +### Download or generate certificate files - {{% note %}} - #### Where are my certificates? +Choose one of the following: - The location of your certificate files depends on your system, domain, and certificate authority. +- [Download and install CA certificate files](#download-and-install-ca-certificate-files) +- [Generate self-signed certificates](#generate-self-signed-certificates) - For example, if [Let's Encrypt](https://letsencrypt.org/) is your CA and you use [certbot](https://certbot.eff.org/) to install certificates, the default location is - `/etc/letsencrypt/live/$domain`. For more information about Let's Encrypt certificate paths, see [Where are my certificates?](https://eff-certbot.readthedocs.io/en/latest/using.html#where-are-my-certificates) - {{% /note %}} +#### Download and install CA certificate files - To generate [self-signed certificates](#self-signed-certificates), use the `openssl` command on your system. +If using a [certificate signed by a CA](#single-domain-certificates-signed-by-a-certificate-authority-ca), follow their instructions to download and install the certificate files. +Note the location where certificate files are installed, and then continue to [set certificate file permissions](#set-certificate-file-permissions). - The following example shows how to generate certificates located in `/etc/ssl`. - Files remain valid for the specified `NUMBER_OF_DAYS`. - The `openssl` command prompts you for optional fields that you can fill out or leave blank; both actions generate valid certificate files. +{{% note %}} +#### Where are my certificates? - ```bash - sudo openssl req -x509 -nodes -newkey rsa:2048 \ - -keyout /etc/ssl/influxdb-selfsigned.key \ - -out /etc/ssl/influxdb-selfsigned.crt \ - -days - ``` +The location of your certificate files depends on your system, domain, and certificate authority. -1. **Set certificate file permissions** - +For example, if [Let's Encrypt](https://letsencrypt.org/) is your CA and you use [certbot](https://certbot.eff.org/) to install certificates, the default location is +`/etc/letsencrypt/live/$domain`. For more information about Let's Encrypt certificate paths, see [Where are my certificates?](https://eff-certbot.readthedocs.io/en/latest/using.html#where-are-my-certificates) +{{% /note %}} - The user running InfluxDB must have read permissions on the TLS certificate files. +#### Generate self-signed certificates - {{% note %}}You may opt to set up multiple users, groups, and permissions. - Ultimately, make sure all users running InfluxDB have read permissions for the TLS certificate. - {{% /note %}} +To generate [self-signed certificates](#self-signed-certificates), use the `openssl` command on your system. - In your terminal, run `chmod` to set permissions on your installed certificate files--for example: +The following example: - ```bash - sudo chmod 644 - sudo chmod 600 - ``` +1. Configures [Subject Alternative Name](https://docs.openssl.org/master/man5/x509v3_config/#subject-alternative-name) (`subjectAltName`, SAN) + for your TLS certificate. +2. Generates certificates located in `/etc/ssl` for Unix-like and Windows systems. - The following example shows how to set read permissions on the self-signed certificate files saved in `/etc/ssl`: +_For example purposes only, the code creates an unencrypted private key._ - ```bash - sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt - sudo chmod 600 /etc/ssl/influxdb-selfsigned.key - ``` +{{% warn %}} +#### Encrypt private keys -2. **Run `influxd` with TLS flags** +Use encrypted keys to enhance security. +If you must use an unencrypted key, ensure it's stored securely and has appropriate file permissions. +{{% /warn %}} - Start InfluxDB with TLS command line flags: +```bash +# Create a temporary configuration file that defines properties for +# the Subject Alternative Name (SAN) extension +cat > san.cnf < /var/log/influxdb.log 2>&1 & +``` + +If successful, InfluxDB runs in the background and logs to `influxdb.log`. + +### Verify TLS connection + +To test your certificates, access InfluxDB using the `https://` protocol--for example, using cURL: + + + + + + + +```bash +curl --verbose https://localhost:8086/api/v2/ping +``` + +If using a self-signed certificate, skip certificate verification--for example, in a cURL command, +pass the `-k, --insecure` flag: + + + +```bash +curl --verbose --insecure https://localhost:8086/api/v2/ping +``` + +If successful, the `curl --verbose` output shows a TLS handshake--for example: + + + +```bash +* [CONN-0-0][CF-SSL] TLSv1.3 (IN), TLS handshake +``` You can further configure TLS settings using [`tls-min-version`](/influxdb/v2/reference/config-options/#tls-min-version) @@ -152,7 +254,7 @@ update the following `influxdb_v2` output settings in your Telegraf configuratio - Update URLs to use HTTPS instead of HTTP. - If using a self-signed certificate, uncomment and set `insecure_skip_verify` to `true`. -### Example configuration +### Example Telegraf configuration ```toml ############################################################################### @@ -176,3 +278,75 @@ update the following `influxdb_v2` output settings in your Telegraf configuratio ``` Restart Telegraf using the updated configuration file. + +## Troubleshoot TLS + +Identify and resolve issues after activating TLS. + +- [Check InfluxDB logs](#check-influxdb-logs) +- [Verify certificate and key files](#verify-certificate-and-key-files) +- [Test with OpenSSL](#test-with-openssl) +- [Check file permissions](#check-file-permissions) +- [Verify TLS configuration](#verify-tls-configuration) +- [Update OpenSSL and InfluxDB](#update-openssl-and-influxdb) + +### Check InfluxDB logs + +Review the InfluxDB logs for any error messages or warnings about the issue. + +#### Example TLS error + +```text +msg="http: TLS handshake error from [::1]:50476: +remote error: tls: illegal parameter" log_id=0rqN8H_0000 service=http +``` + +### Verify certificate and key Files + +To ensure that the certificate and key files are correct and match each other, +enter the following command in your terminal: + +```bash +openssl x509 -noout -modulus -in /etc/ssl/influxdb-selfsigned.crt | openssl md5 +openssl rsa -noout -modulus -in /etc/ssl/influxdb-selfsigned.key | openssl md5 +``` + +### Test with OpenSSL + +Use OpenSSL to test the server's certificate and key--for example, enter the +following command in your terminal: + +```bash +openssl s_client -connect localhost:8086 -CAfile /etc/ssl/influxdb-selfsigned.crt +``` + +### Check file permissions + +Ensure that the InfluxDB process has read access to the certificate and key +files--for example, enter the following command to set file permissions: + +```bash +sudo chmod 644 /etc/ssl/influxdb-selfsigned.crt +sudo chmod 600 /etc/ssl/influxdb-selfsigned.key +``` + +### Verify TLS configuration + +Ensure that the TLS configuration in InfluxDB is correct. +Check the paths to the certificate and key files in the InfluxDB configuration +or command line flags. + +#### Example error: cannot validate certificate for + +```log +Sep 25 14:00:02 host influxd-systemd-start.sh[11782]: ts=2024-09-25T12:00:02.055617Z lvl=error msg="Unable to gather" log_id=0rr6jG30000 service=scraper scraper-name="new target" error="Get \"https://10.1.2.3:8086/metrics\": tls: failed to verify certificate: x509: cannot validate certificate for 10.1.2.3 because it doesn't contain any IP SANs" +Sep 25 14:00:02 host influxd-systemd-start.sh[11782]: ts=2024-09-25T12:00:02.055397Z lvl=info msg="http: TLS handshake error from 10.1.2.3:46380: remote error: tls: bad certificate" log_id=0rr6jG30000 service=http +``` + +If you access your InfluxDB server via IP address, then include the address in +your subjectAltName configuration. + +### Update OpenSSL and InfluxDB + +Ensure that you are using the latest versions of OpenSSL and InfluxDB, as +updates may include fixes for TLS-related issues. diff --git a/content/influxdb/v2/api-guide/client-libraries/_index.md b/content/influxdb/v2/api-guide/client-libraries/_index.md index 697dcdbc5..fed8999ef 100644 --- a/content/influxdb/v2/api-guide/client-libraries/_index.md +++ b/content/influxdb/v2/api-guide/client-libraries/_index.md @@ -19,9 +19,4 @@ influxdb/v2/tags: [client libraries] InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. The following **InfluxDB v2** client libraries are available: -{{% note %}} -These client libraries are in active development and may not be feature-complete. -This list will continue to grow as more client libraries are released. -{{% /note %}} - {{< children type="list" >}} diff --git a/content/influxdb/v2/api-guide/client-libraries/nodejs/install.md b/content/influxdb/v2/api-guide/client-libraries/nodejs/install.md index cebfe2a98..4d7fd0e7f 100644 --- a/content/influxdb/v2/api-guide/client-libraries/nodejs/install.md +++ b/content/influxdb/v2/api-guide/client-libraries/nodejs/install.md @@ -21,31 +21,47 @@ aliases: 2. Ensure that InfluxDB is running and you can connect to it. For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2/reference/urls/). -3. Start a new Node.js project. - The `npm` package manager is included with Node.js. +3. Create a directory for your new Node.js project, and then change to the + directory--for example, enter the following command into your terminal: - ```sh - npm init -y influx-node-app - ``` + ```sh + mkdir influx-node-app && cd influx-node-app + ``` + +4. Enter the following command to generate an npm package for your project. + + - `npm`: the package manager included with Node.js + - `-y`: uses defaults for the package and bypasses prompts + + ```sh + npm init -y + ``` ## Install TypeScript -Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). Follow these steps to initialize the TypeScript project. +Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). +Follow these steps to initialize the TypeScript project: 1. Install TypeScript and type definitions for Node.js. ```sh npm i -g typescript && npm i --save-dev @types/node ``` -2. Create a TypeScript configuration with default values. + +2. Enter the following command to create a TypeScript configuration + (`tsconfig.json`) with default values: ```sh tsc --init ``` -3. Run the TypeScript compiler. To recompile your code automatically as you make changes, pass the `watch` flag to the compiler. +3. Run the TypeScript compiler. + To recompile your code automatically as you make changes, pass the `--watch, -w` flag to the compiler. + + + ```sh - tsc -w -p + tsc --watch ``` ## Install dependencies @@ -76,7 +92,7 @@ The client examples include an [`env`](https://github.com/influxdata/influxdb-cl The examples use these properties to interact with the InfluxDB API. {{% /note %}} -1. Set environment variables or update `env.mjs` with your InfluxDB [bucket](/influxdb/v2/admin/buckets/), [organization](/influxdb/v2/admin/organizations/), [token](/influxdb/v2/admin/tokens/), and [url](/influxdb/v2/reference/urls/). +1. Set environment variables or update `env.mjs` with your InfluxDB [bucket](/influxdb/v2/admin/buckets/), [organization](/influxdb/v2/admin/organizations/), [token](/influxdb/v2/admin/tokens/), and [URL](/influxdb/v2/reference/urls/). ```sh export INFLUX_URL=http://localhost:8086 @@ -89,7 +105,9 @@ The examples use these properties to interact with the InfluxDB API. - *`YOUR_ORG`*: InfluxDB organization ID - *`YOUR_BUCKET`*: InfluxDB bucket name -2. Run an example script. +2. Run one of the [`influxdb-client-js` example scripts](https://github.com/influxdata/influxdb-client-js/tree/master/examples/). + + ```sh query.ts diff --git a/content/influxdb/v2/reference/api/influxdb-1x/_index.md b/content/influxdb/v2/api-guide/influxdb-1x/_index.md similarity index 77% rename from content/influxdb/v2/reference/api/influxdb-1x/_index.md rename to content/influxdb/v2/api-guide/influxdb-1x/_index.md index ac16c7fe4..9aa3df46a 100644 --- a/content/influxdb/v2/reference/api/influxdb-1x/_index.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/_index.md @@ -6,12 +6,14 @@ description: > menu: influxdb_v2: name: v1 compatibility - parent: InfluxDB v2 API + parent: Develop with the API weight: 104 influxdb/v2/tags: [influxql, query, write] related: - /influxdb/v2/query-data/influxql - /influxdb/v2/install/upgrade/v1-to-v2/ +aliases: + - /influxdb/v2/reference/api/influxdb-1x/ --- The InfluxDB v2 API includes InfluxDB 1.x compatibility endpoints that work with @@ -37,7 +39,7 @@ Use the `Authorization` header with the `Token` scheme to provide your token to #### Syntax -```sh +```http Authorization: Token INFLUX_API_TOKEN ``` @@ -49,6 +51,9 @@ Authorization: Token INFLUX_API_TOKEN [Node.js](#nodejs) {{% /code-tabs %}} {{% code-tab-content %}} + + + ```sh {{% get-shared-text "api/v1-compat/auth/oss/token-auth.sh" %}} ``` @@ -77,21 +82,21 @@ Username and password schemes require the following credentials: {{% note %}} #### Password or Token -If you have [set a password](/influxdb/v2/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations) for the 1.x-compatible username, provide the 1.x-compatible password. + +If you have [set a password](/influxdb/v2/install/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations) for the 1.x-compatible username, provide the 1.x-compatible password. If you haven't set a password for the 1.x-compatible username, provide the InfluxDB [authentication token](/influxdb/v2/admin/tokens/) as the password. {{% /note %}} -For information about creating and managing 1.x-compatible authorizations, see: - -- [`influx v1 auth` command](/influxdb/v2/reference/cli/influx/v1/auth/) -- [Manually upgrade – 1.x-compatible authorizations](/influxdb/v2/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations) +For more information, see how to create and manage +[1.x-compatible authorizations](/influxdb/v2/install/upgrade/v1-to-v2/manual-upgrade/#1x-compatible-authorizations) +when manually upgrading from InfluxDB v1 to v2. {{% /oss-only %}} {{% cloud-only %}} - **username**: InfluxDB Cloud username - (Use the email address you signed up with as your username, _e.g._ `exampleuser@influxdata.com`.) + (Use the email address you signed up with as your username--for example, `exampleuser@influxdata.com`.) - **password**: InfluxDB Cloud [API token](/influxdb/cloud/admin/tokens/) {{% /cloud-only %}} @@ -107,7 +112,7 @@ password credentials to InfluxDB. {{% oss-only %}} -```sh +```http Authorization: Basic INFLUX_USERNAME:INFLUX_PASSWORD_OR_TOKEN ``` @@ -116,7 +121,7 @@ Authorization: Basic INFLUX_USERNAME:INFLUX_PASSWORD_OR_TOKEN {{% cloud-only %}} -```sh +```http Authorization: Basic exampleuser@influxdata.com:INFLUX_API_TOKEN ``` @@ -124,6 +129,8 @@ Authorization: Basic exampleuser@influxdata.com:INFLUX_API_TOKEN ##### Example +{{% code-placeholders "INFLUX_(USERNAME|PASSWORD_OR_TOKEN|API_TOKEN)|exampleuser@influxdata.com" %}} + {{% oss-only %}} {{< code-tabs-wrapper >}} @@ -132,6 +139,9 @@ Authorization: Basic exampleuser@influxdata.com:INFLUX_API_TOKEN [Node.js](#nodejs) {{% /code-tabs %}} {{% code-tab-content %}} + + + ```sh {{% get-shared-text "api/v1-compat/auth/oss/basic-auth.sh" %}} ``` @@ -154,6 +164,9 @@ Authorization: Basic exampleuser@influxdata.com:INFLUX_API_TOKEN [Node.js](#nodejs) {{% /code-tabs %}} {{% code-tab-content %}} + + + ```sh {{% get-shared-text "api/v1-compat/auth/cloud/basic-auth.sh" %}} ``` @@ -167,8 +180,8 @@ Authorization: Basic exampleuser@influxdata.com:INFLUX_API_TOKEN {{< /code-tabs-wrapper >}} Replace the following: -- *`exampleuser@influxdata.com`*: the email address that you signed up with -- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) +- {{% code-placeholder-key %}}`exampleuser@influxdata.com`{{% /code-placeholder-key %}}: the email address that you signed up with +- {{% code-placeholder-key %}}`INFLUX_API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) {{% /cloud-only %}} @@ -186,7 +199,7 @@ Use InfluxDB 1.x API parameters to provide credentials through the query string. {{% oss-only %}} -```sh +```http /query/?u=INFLUX_USERNAME&p=INFLUX_PASSWORD_OR_TOKEN /write/?u=INFLUX_USERNAME&p=INFLUX_PASSWORD_OR_TOKEN ``` @@ -195,7 +208,7 @@ Use InfluxDB 1.x API parameters to provide credentials through the query string. {{% cloud-only %}} -```sh +```http /query/?u=INFLUX_USERNAME&p=INFLUX_API_TOKEN /write/?u=INFLUX_USERNAME&p=INFLUX_API_TOKEN ``` @@ -211,6 +224,9 @@ Use InfluxDB 1.x API parameters to provide credentials through the query string. [Node.js](#nodejs) {{% /code-tabs %}} {{% code-tab-content %}} + + + ```sh {{< get-shared-text "api/v1-compat/auth/oss/querystring-auth.sh" >}} ``` @@ -223,8 +239,8 @@ Use InfluxDB 1.x API parameters to provide credentials through the query string. {{< /code-tabs-wrapper >}} Replace the following: -- *`INFLUX_USERNAME`*: [InfluxDB 1.x username](#manage-credentials) -- *`INFLUX_PASSWORD_OR_TOKEN`*: [InfluxDB 1.x password or InfluxDB API token](#manage-credentials) +- {{% code-placeholder-key %}}`INFLUX_USERNAME`{{% /code-placeholder-key %}}: [InfluxDB 1.x username](#manage-credentials) +- {{% code-placeholder-key %}}`INFLUX_PASSWORD_OR_TOKEN`{{% /code-placeholder-key %}}: [InfluxDB 1.x password or InfluxDB API token](#manage-credentials) {{% /oss-only %}} @@ -236,6 +252,9 @@ Replace the following: [Node.js](#nodejs) {{% /code-tabs %}} {{% code-tab-content %}} + + + ```sh {{% get-shared-text "api/v1-compat/auth/cloud/basic-auth.sh" %}} ``` @@ -248,9 +267,11 @@ Replace the following: {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +{{% /code-placeholders %}} + Replace the following: -- *`exampleuser@influxdata.com`*: the email address that you signed up with -- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) +- {{% code-placeholder-key %}}`exampleuser@influxdata.com`{{% /code-placeholder-key %}}: the email address that you signed up with +- {{% code-placeholder-key %}}`INFLUX_API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) {{% /cloud-only %}} @@ -258,7 +279,7 @@ Replace the following: The compatibility API supports InfluxQL, with the following caveats: -- The `INTO` clause (e.g. `SELECT ... INTO ...`) is not supported. +- The `INTO` clause (for example, `SELECT ... INTO ...`) is not supported. - With the exception of [`DELETE`](/influxdb/v1/query_language/manage-database/#delete-series-with-delete) and [`DROP MEASUREMENT`](/influxdb/v1/query_language/manage-database/#delete-measurements-with-drop-measurement) queries, which are still allowed, InfluxQL database management commands are not supported. diff --git a/content/influxdb/v2/reference/api/influxdb-1x/dbrp.md b/content/influxdb/v2/api-guide/influxdb-1x/dbrp.md similarity index 95% rename from content/influxdb/v2/reference/api/influxdb-1x/dbrp.md rename to content/influxdb/v2/api-guide/influxdb-1x/dbrp.md index 3d5296d4c..86a0136b3 100644 --- a/content/influxdb/v2/reference/api/influxdb-1x/dbrp.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/dbrp.md @@ -13,6 +13,8 @@ related: - /influxdb/v2/reference/api/influxdb-1x/write - /influxdb/v2/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint - /influxdb/v2/query-data/influxql/ +aliases: + - /influxdb/v2/reference/api/influxdb-1x/dbrp/ --- The InfluxDB 1.x data model includes [databases](/influxdb/v1/concepts/glossary/#database) @@ -82,9 +84,10 @@ the DBRP mapping service checks for a bucket mapped to the database and retentio - If a mapped bucket is found, data is written to the bucket. - If an unmapped bucket with a name matching: - - **database/retention policy** exists, a DBRP mapping is added to the bucket, + + - `database/retention policy` exists, a DBRP mapping is added to the bucket, and data is written to the bucket. - - **database** exists (without a specified retention policy), the default + - `database` exists (without a specified retention policy), the default database retention policy is used, a DBRP mapping is added to the bucket, and data is written to the bucket. diff --git a/content/influxdb/v2/reference/api/influxdb-1x/query.md b/content/influxdb/v2/api-guide/influxdb-1x/query.md similarity index 88% rename from content/influxdb/v2/reference/api/influxdb-1x/query.md rename to content/influxdb/v2/api-guide/influxdb-1x/query.md index 79bc12dbd..5c8b30e2d 100644 --- a/content/influxdb/v2/reference/api/influxdb-1x/query.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/query.md @@ -15,6 +15,8 @@ list_code_example: | related: - /influxdb/v2/query-data/influxql +aliases: + - /influxdb/v2/reference/api/influxdb-1x/query/ --- The `/query` 1.x compatibility endpoint queries InfluxDB {{< current-version >}} using **InfluxQL**. @@ -92,6 +94,8 @@ The following precisions are available: - [Return query results with millisecond Unix timestamps](#return-query-results-with-millisecond-unix-timestamps) - [Execute InfluxQL queries from a file](#execute-influxql-queries-from-a-file) +{{% code-placeholders "API_TOKEN" %}} + ##### Query using basic authentication {{% oss-only %}} @@ -102,6 +106,9 @@ The following precisions are available: [Node.js](#nodejs) {{% /code-tabs %}} {{% code-tab-content %}} + + + ```sh {{% get-shared-text "api/v1-compat/auth/oss/basic-auth.sh" %}} ``` @@ -123,6 +130,9 @@ The following precisions are available: [Node.js](#nodejs) {{% /code-tabs %}} {{% code-tab-content %}} + + + ```sh {{% get-shared-text "api/v1-compat/auth/cloud/basic-auth.sh" %}} ``` @@ -138,18 +148,34 @@ The following precisions are available: {{% /cloud-only %}} ##### Query a non-default retention policy + + + ```sh curl --get http://localhost:8086/query \ - --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=mydb" \ --data-urlencode "rp=customrp" \ --data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1" ``` ##### Execute multiple queries + ```sh curl --get http://localhost:8086/query \ - --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=mydb" \ --data-urlencode "q=SELECT * FROM mem WHERE host=host1;SELECT mean(used_percent) FROM mem WHERE host=host1 GROUP BY time(10m)" ``` @@ -157,7 +183,7 @@ curl --get http://localhost:8086/query \ ##### Return query results with millisecond Unix timestamps ```sh curl --get http://localhost:8086/query \ - --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=mydb" \ --data-urlencode "rp=myrp" \ --data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1" \ @@ -167,11 +193,14 @@ curl --get http://localhost:8086/query \ ##### Execute InfluxQL queries from a file ```sh curl --get http://localhost:8086/query \ - --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Authorization: Token API_TOKEN" \ --data-urlencode "db=mydb" \ --data-urlencode "q@path/to/influxql.txt" \ --data-urlencode "async=true" ``` +{{% /code-placeholders %}} + Replace the following: -- *`INFLUX_API_TOKEN`*: InfluxDB API token + +- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your InfluxDB [API token](/influxdb/v2/admin/tokens/) diff --git a/content/influxdb/v2/reference/api/influxdb-1x/write.md b/content/influxdb/v2/api-guide/influxdb-1x/write.md similarity index 57% rename from content/influxdb/v2/reference/api/influxdb-1x/write.md rename to content/influxdb/v2/api-guide/influxdb-1x/write.md index ac6945968..eb9df477f 100644 --- a/content/influxdb/v2/reference/api/influxdb-1x/write.md +++ b/content/influxdb/v2/api-guide/influxdb-1x/write.md @@ -16,6 +16,8 @@ list_code_example: | related: - /influxdb/v2/reference/syntax/line-protocol +aliases: + - /influxdb/v2/reference/api/influxdb-1x/write/ --- The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud and InfluxDB OSS {{< current-version >}} @@ -30,8 +32,8 @@ to the `/write` endpoint. {{% cloud-only %}} {{% note %}} -If you have an existing bucket that doesn't follow the **database/retention-policy** naming convention, -you **must** [manually create a database and retention policy mapping](/influxdb/v2/query-data/influxql/dbrp/#create-dbrp-mappings) +If you have an existing bucket that doesn't follow the `database/retention-policy` naming convention, +you _must_ [manually create a database and retention policy mapping](/influxdb/v2/query-data/influxql/dbrp/#create-dbrp-mappings) to write data to that bucket with the `/write` compatibility API. {{% /note %}} @@ -42,9 +44,9 @@ to write data to that bucket with the `/write` compatibility API. {{% oss-only %}} Use one of the following authentication methods: -* **token authentication** -* **basic authentication with username and password** -* **query string authentication with username and password** +- **token authentication** +- **basic authentication with username and password** +- **query string authentication with username and password** _For more information, see [Authentication](/influxdb/v2/reference/api/influxdb-1x/#authentication)._ @@ -120,79 +122,112 @@ The following precisions are available: ##### Write data using basic authentication -{{% oss-only %}} + + +{{% oss-only %}} + +{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} +```sh +curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ + --user "USERNAME:PASSWORD_OR_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" ``` +{{% /code-placeholders %}} {{% /oss-only %}} {{% cloud-only %}} - +{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} ```sh -curl --request POST https://cloud2.influxdata.com/write?db=mydb \ - --user "exampleuser@influxdata.com:INFLUX_API_TOKEN" \ +curl --request POST https://cloud2.influxdata.com/write?db=DATABASE_NAME \ + --user "exampleuser@influxdata.com:API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" ``` +{{% /code-placeholders %}} {{% /cloud-only %}} ##### Write data using token authentication + +{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} ```sh -curl --request POST http://localhost:8086/write?db=mydb \ - --header "Authorization: Token INFLUX_API_TOKEN" \ +curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ + --header "Authorization: Token API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" ``` +{{% /code-placeholders %}} ##### Write data to a non-default retention policy +{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} ```sh -curl --request POST http://localhost:8086/write?db=mydb&rp=customrp \ - --header "Authorization: Token INFLUX_API_TOKEN" \ +curl --request POST "http://localhost:8086/write?db=DATABASE_NAME&rp=RETENTION_POLICY" \ + --header "Authorization: Token API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000" ``` - - +{{% /code-placeholders %}} ##### Write multiple lines of line protocol + +{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} ```sh -curl --request POST http://localhost:8086/write?db=mydb \ - --header "Authorization: Token INFLUX_API_TOKEN" \ +curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ + --header "Authorization: Token API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000 measurement,host=host2 field1=14i,field2=12.7 1577836800000000000 measurement,host=host3 field1=5i,field2=6.8 1577836800000000000" ``` +{{% /code-placeholders %}} ##### Write data with millisecond Unix timestamps + +{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} ```sh -curl --request POST http://localhost:8086/write?db=mydb&precision=ms \ - --header "Authorization: Token INFLUX_API_TOKEN" \ +curl --request POST "http://localhost:8086/write?db=DATABASE_NAME&precision=ms" \ + --header "Authorization: Token API_TOKEN" \ --data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000" ``` +{{% /code-placeholders %}} ##### Use curl to write data from a file + +{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} ```sh -curl --request POST http://localhost:8086/write?db=mydb \ - --header "Authorization: Token INFLUX_API_TOKEN" \ +curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ + --header "Authorization: Token API_TOKEN" \ --data-binary @path/to/line-protocol.txt ``` +{{% /code-placeholders %}} {{% oss-only %}} Replace the following: -- *`INFLUX_USERNAME`*: [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) -- *`INFLUX_PASSWORD_OR_TOKEN`*: [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) -- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/v2/reference/glossary/#token) + +- {{% code-placeholder-key %}}`DATABASE_NAME` and `RETENTION_POLICY`{{% /code-placeholder-key %}}: the [database and retention policy mapping (DBRP)](/influxdb/v2/reference/api/influxdb-1x/dbrp/) for the InfluxDB v2 bucket that you want to write to +- {{% code-placeholder-key %}}`USERNAME`{{% /code-placeholder-key %}}: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) +- {{% code-placeholder-key %}}`PASSWORD_OR_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) +- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/) {{% /oss-only %}} {{% cloud-only %}} Replace the following: -- *`exampleuser@influxdata.com`*: the email address that you signed up with -- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) + +- {{% code-placeholder-key %}}`DATABASE_NAME` and `RETENTION_POLICY`{{% /code-placeholder-key %}}: the [database and retention policy mapping (DBRP)](/influxdb/v2/reference/api/influxdb-1x/dbrp/) for the InfluxDB v2 bucket that you want to write to +- {{% code-placeholder-key %}}}`exampleuser@influxdata.com`{{% /code-placeholder-key %}}: the email address that you signed up with +- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/) {{% /cloud-only %}} diff --git a/content/influxdb/v2/api-guide/tutorials/python.md b/content/influxdb/v2/api-guide/tutorials/python.md index 78f96e1f2..e8aa3cc72 100644 --- a/content/influxdb/v2/api-guide/tutorials/python.md +++ b/content/influxdb/v2/api-guide/tutorials/python.md @@ -251,7 +251,7 @@ def create_authorization(device_id) -> Authorization: write = Permission(action="write", resource=org_resource) permissions = [read, write] authorization = Authorization(org_id=org_id, permissions=permissions, description=desc_prefix) - request = authorization_api.create_authorization(authorization) + request = authorization_api.create_authorization(authorization=authorization) return request ``` diff --git a/content/influxdb/v2/get-started/query.md b/content/influxdb/v2/get-started/query.md index 6f7c268f4..bb276e000 100644 --- a/content/influxdb/v2/get-started/query.md +++ b/content/influxdb/v2/get-started/query.md @@ -472,7 +472,7 @@ Use the **`influx` CLI**, or **InfluxDB API** to execute InfluxQL queries. {{% note %}} -#### The InflxuDB UI does not support InfluxQL +#### The influxdb UI does not support InfluxQL The InfluxDB {{< current-version >}} UI does not provide a way to query data with InfluxQL. For a user interface that builds and executes InfluxQL queries, consider using diff --git a/content/influxdb/v2/get-started/visualize.md b/content/influxdb/v2/get-started/visualize.md index da363b082..29a294579 100644 --- a/content/influxdb/v2/get-started/visualize.md +++ b/content/influxdb/v2/get-started/visualize.md @@ -20,12 +20,12 @@ related: --- There are many tools you can use to visualize your time series data including the -InfluxDB user interface (UI), [Chronograf](), and +InfluxDB user interface (UI), [Chronograf](/influxdb/v2/tools/chronograf/), and [Grafana](/influxdb/v2/tools/grafana/). This tutorial walks you through using the **InfluxDB UI** to create a simple dashboard. Dashboards are a powerful way of displaying time series data and can help to -identify trends and anomalies. A dashboard is comprised of one or more +identify trends and anomalies. A dashboard is comprised of one or more dashboard cells. A **dashboard cell** visualizes the results of a query using one of the available [visualization types](/influxdb/v2/visualize-data/visualization-types/). @@ -59,7 +59,7 @@ With your new dashboard created and named, add a new dashboard cell: available. For this tutorial, use the default **Graph** visualization. 4. Use the query time range selector to select an absolute time range that - covers includes the time range of the + covers includes the time range of the [data written in "Get started writing to InfluxDB"](/influxdb/v2/get-started/write/#view-the-written-data): **2022-01-01T08:00:00Z** to **2022-01-01T20:00:01Z**. @@ -78,7 +78,7 @@ With your new dashboard created and named, add a new dashboard cell: - **Start**: 2022-01-01 08:00:00 - **Stop**: 2022-01-01 20:00:01 - + 3. Click **{{% caps %}}Apply Time Range{{% /caps %}}**. 5. Use the **Query Builder** to select the measurement, fields, and tags to query: @@ -110,7 +110,7 @@ each controlled by selections in your dashboard: ### Create a custom dashboard variable -Let's create a custom dashboard variable that we can use to change the field +Let's create a custom dashboard variable that we can use to change the field displayed by your dashboard cell. 1. Select **Settings > Variables** in the left navigation bar. @@ -183,5 +183,3 @@ Feel free to dive in deeper to each of these topics: - [Process data with InfluxDB](/influxdb/v2/process-data/) - [Visualize data with the InfluxDB UI](/influxdb/v2/visualize-data/) -If you have questions as you're getting started, reach out to us using the -available [Support and feedback](#bug-reports-and-feedback) channels. diff --git a/content/influxdb/v2/install/_index.md b/content/influxdb/v2/install/_index.md index 6c31336aa..c4408472d 100644 --- a/content/influxdb/v2/install/_index.md +++ b/content/influxdb/v2/install/_index.md @@ -16,10 +16,183 @@ process and visualize metrics and events. - [Download and install InfluxDB v2](#download-and-install-influxdb-v2) - [Start InfluxDB](#start-influxdb) -- [Download, install, and configure the `influx` CLI](#download-install-and-configure-influx-cli) +- [Download, install, and configure the `influx` CLI](#download-install-and-configure-the-influx-cli) -1. **Download and install InfluxDB v2**. - +## Download and install InfluxDB v2 + +{{< req text="Recommended:" color="magenta" >}}: Before you open and install packages and downloaded files, use SHA +checksum verification and GPG signature verification to ensure the files are +intact and authentic. + +InfluxDB installation instructions for some OS versions include steps to +verify downloaded files before you install them. + +For more information about SHA and GPG verifications, see the following: + +{{< expand-wrapper >}} + +{{% expand "Choose the InfluxData key-pair for your OS version" %}} + +_Before running the installation steps, substitute the InfluxData key-pair compatible +with your OS version:_ + +For newer releases (for example, Ubuntu 20.04 LTS and newer, Debian Buster +and newer) that support subkey verification: + +- Private key file: [`influxdata-archive.key`](https://repos.influxdata.com/influxdata-archive.key) +- Public key: `943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515` + +For older versions (for example, CentOS/RHEL 7, Ubuntu 18.04 LTS, or Debian +Stretch) that don't support subkeys for verification: + +- Private key file: [`influxdata-archive_compat.key`](https://repos.influxdata.com/influxdata-archive_compat.key) +- Public key: `393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c` + +{{% /expand %}} + +{{% expand "Verify download integrity using SHA-256" %}} + +For each released binary, InfluxData publishes the SHA checksum that +you can use to verify that the downloaded file is intact and hasn't been corrupted. + +To use the SHA checksum to verify the downloaded file, do the following: + +1. In the [downloads page](https://www.influxdata.com/downloads), + select the **Version** and **Platform** for your download, and then copy + the **SHA256:** checksum value. + +2. Compute the SHA checksum of the downloaded file and compare it to the + published checksum--for example, enter the following command in your terminal. + + + + + +{{% code-placeholders "9cb54d3940c37a8c2a908458543e629412505cc71db55094147fd39088b99c6c" %}} + +```bash +# Use 2 spaces to separate the checksum from the filename +echo "9cb54d3940c37a8c2a908458543e629412505cc71db55094147fd39088b99c6c influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz" \ +| sha256sum --check - +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`9cb54d3940c37a8c2a908458543e629412505cc71db55094147fd39088b99c6c`{{% /code-placeholder-key %}}: + the **SHA256:** checksum value that you copied from the downloads page + +If the checksums match, the output is the following; otherwise, an error message. + +``` +influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz: OK +``` + +{{% /expand %}} +{{% expand "Verify file integrity and authenticity using GPG" %}} + +InfluxData uses [GPG (GnuPG)](https://www.gnupg.org/software/) to sign released software and provides +public key and encrypted private key (`.key` file) pairs that you can use to +verify the integrity of packages and binaries from the InfluxData repository. + +Most operating systems include `gpg` by default. +_If `gpg` isn't available on your system, see +[GnuPG download](https://gnupg.org/download/) and install instructions._ + +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). +2. Download and import the InfluxData public key. + + `gpg --import` outputs to stderr. + The following example shows how to import the key, redirect the output to stdout, + and then check for the expected key name: + + + +{{% code-placeholders "https://repos.influxdata.com/influxdata-archive.key" %}} + +```sh +curl --silent --location \ + https://repos.influxdata.com/influxdata-archive.key \ + | gpg --import - 2>&1 \ + | grep 'InfluxData Package Signing Key ' +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`https://repos.influxdata.com/influxdata-archive.key`{{% /code-placeholder-key %}}: + the InfluxData private key file compatible with your OS version + +If successful, the output is the following: + + + +``` +gpg: key 7C3D57159FC2F927: public key "InfluxData Package Signing Key " imported +``` + +3. Download the signature file for the release by appending `.asc` to the download URL, + and then use `gpg` to verify the download signature--for example, enter the + following in your terminal: + + + + ```sh + curl --silent --location \ + https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz.asc \ + | gpg --verify - ~/Downloads/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz \ + 2>&1 | grep 'InfluxData Package Signing Key ' + ``` + + - `curl --silent --location`: Follows any server redirects and fetches the + signature file silently (without progress meter). + - `gpg --verify -`: Reads the signature from stdin and uses it to verify the + the downloaded `influxdbv2` binary. + + If successful, the output is the following: + + + + ``` + gpg: Good signature from "InfluxData Package Signing Key " [unknown] + ``` + +_For security, InfluxData periodically rotates keys and publishes the new key pairs._ + +{{% /expand %}} +{{< /expand-wrapper >}} + +The following instructions include steps for downloading, verifying, and installing +{{< product-name >}}: {{< tabs-wrapper >}} {{% tabs %}} @@ -51,25 +224,18 @@ The InfluxDB server ([`influxd`](/influxdb/v2/reference/cli/influxd/)) and the [`influx` CLI](/influxdb/v2/reference/cli/influx/) are packaged and versioned separately. -_You'll install the `influx CLI` in a [later step](#download-and-install-the-influx-cli)._ +_You'll install the `influx CLI` in a [later step](#download-install-and-configure-the-influx-cli)._ {{% /note %}} ### Install using Homebrew - ```sh brew update brew install influxdb ``` -{{% note %}} -Homebrew also installs `influxdb-cli` as a dependency. -For information about using the `influx` CLI, see the -[`influx` CLI reference documentation](/influxdb/v2/reference/cli/influx/). -{{% /note %}} - ### Manually download and install for macOS 1. In your browser or your terminal, download the InfluxDB package. @@ -78,28 +244,42 @@ For information about using the `influx` CLI, see the ```sh # Download using cURL - curl -LO https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz \ - --output-dir ~/Downloads + curl --location -O \ + "https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz" ``` -2. Unpackage the InfluxDB binary. +2. {{< req text="Recommended:" color="magenta" >}}: Verify the integrity of the download--for example, enter the + following command in your terminal: + +{{% code-placeholders "964e1de641a43a0e1743aa5ead243e935a05631ba0bc570fb8bff486542173c1" %}} + +```sh +# Use 2 spaces to separate the checksum from the filename +echo "964e1de641a43a0e1743aa5ead243e935a05631ba0bc570fb8bff486542173c1 influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz" \ +| shasum --algorithm 256 --quiet --check - +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`964e1de641a43a0e1743aa5ead243e935a05631ba0bc570fb8bff486542173c1`{{% /code-placeholder-key %}}: the SHA checksum from the [downloads page](https://www.influxdata.com/downloads/#telegraf) + +3. Unpackage the InfluxDB binary. Do one of the following: - In **Finder**, double-click the downloaded package file. - In your terminal (for example, **Terminal** or **[iTerm2](https://www.iterm2.com/)**), use `tar` to unpackage the file--for example, enter the following command to extract it into the current directory: - - ```sh # Unpackage contents to the current working directory - tar zxvf ~/Downloads/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz + tar zxvf ./influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz ``` -3. Optional: Place the `influxd` binary in your `$PATH`--for example, copy the binary to `/usr/local/bin`: - - +4. Optional: Place the `influxd` binary in your `$PATH`--for example, copy the binary to `/usr/local/bin`: + ```sh # (Optional) Copy the influxd binary to your $PATH sudo cp influxdb2-{{< latest-patch >}}/influxd /usr/local/bin/ @@ -110,7 +290,6 @@ For information about using the `influx` CLI, see the If you choose not to move the `influxd` binary into your `$PATH`, enter the path to the binary to start the server--for example: - ```sh ./influxdb2-{{< latest-patch >}}/influxd ``` @@ -119,63 +298,14 @@ For information about using the `influx` CLI, see the {{% expand "Recommended – Set appropriate directory permissions" %}} To prevent unwanted access to data, set the permissions on the influxdb `data-dir` to not be world readable. -If installing on a server, set a umask of `0027` to properly permission all newly created files--for example, enter the following command in your terminal: +If installing on a server, set a umask of `0027` to properly permission all +newly created files--for example, enter the following command in your terminal: - -```sh +```bash chmod 0750 ~/.influxdbv2 ``` -{{% /expand %}} -{{% expand "Recommended – Verify the authenticity of the downloaded binary" %}} - -For added security, use `gpg` to verify the signature of your download. -(Most operating systems include the `gpg` command by default. -If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/) for installation instructions.) - -1. Download and import InfluxData's public key. - `gpg --import` outputs to stderr. - The following example shows how to import the key, redirect the output to stdout, - and then check for the expected key name: - - - - ```sh - curl -s https://repos.influxdata.com/influxdata-archive_compat.key \ - | gpg --import - 2>&1 \ - | grep 'InfluxData Package Signing Key ' - ``` - - If successful, the output is similar to the following: - - - - ``` - gpg: key D8FF8E1F7DF8B07E: public key "InfluxData Package Signing Key " imported - ``` - -2. Download the signature file for the release by adding `.asc` to the download URL, - and then use `gpg` to verify the download signature--for example: - - ```sh - curl -s https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz.asc \ - | gpg --verify - ~/Downloads/influxdb2-{{< latest-patch >}}_darwin_amd64.tar.gz \ - 2>&1 | grep 'InfluxData Package Signing Key ' - ``` - - If successful, the output is the following: - - - - ``` - gpg: Good signature from "InfluxData Package Signing Key " [unknown] - ``` - {{% /expand %}} {{< /expand-wrapper >}} @@ -191,6 +321,8 @@ If you rename the binaries, all references to `influxd` and `influx` in this doc {{% tab-content %}} + + To install {{% product-name %}} on Linux, do one of the following: - [Install InfluxDB as a service with systemd](#install-influxdb-as-a-service-with-systemd) @@ -204,54 +336,74 @@ The InfluxDB server ([`influxd`](/influxdb/v2/reference/cli/influxd/)) and the [`influx` CLI](/influxdb/v2/reference/cli/influx/) are packaged and versioned separately. -_You'll install the `influx CLI` in a [later step](#download-and-install-the-influx-cli)._ +_You'll install the `influx CLI` in a [later step](#download-install-and-configure-the-influx-cli)._ {{% /note %}} ### Install InfluxDB as a service with systemd -1. Download and install the appropriate `.deb` or `.rpm` file using a URL from the - [InfluxData downloads page](https://www.influxdata.com/downloads/) - with the following commands: +1. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-os-version). - ```sh - # Ubuntu/Debian AMD64 - curl -LO https://download.influxdata.com/influxdb/releases/influxdb2_{{< latest-patch >}}-1_amd64.deb - sudo dpkg -i influxdb2_{{< latest-patch >}}-1_amd64.deb +2. Run the command for your OS version to install the InfluxData key, + add the InfluxData repository, and install `influxdb`. + + _Before running the command, replace the checksum and key filename with the + key-pair from the preceding step._ + + ```bash + # Ubuntu and Debian + # Add the InfluxData key to verify downloads and add the repository + curl --silent --location -O \ + https://repos.influxdata.com/influxdata-archive.key + echo "943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515 influxdata-archive.key" \ + | sha256sum --check - && cat influxdata-archive.key \ + | gpg --dearmor \ + | 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' \ + | tee /etc/apt/sources.list.d/influxdata.list + # Install influxdb + sudo apt-get update && sudo apt-get install influxdb2 ``` - ```sh - # Ubuntu/Debian ARM64 - curl -LO https://download.influxdata.com/influxdb/releases/influxdb2_{{< latest-patch >}}-1_arm64.deb - sudo dpkg -i influxdb2_{{< latest-patch >}}-1_arm64.deb - ``` - - ```sh - # Red Hat/CentOS/Fedora x86-64 (x64, AMD64) - curl -LO https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-1.x86_64.rpm - sudo yum localinstall influxdb2-{{< latest-patch >}}-1.x86_64.rpm - ``` - - ```sh - # Red Hat/CentOS/Fedora AArch64 (ARMv8-A) - curl -LO https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}-1.aarch64.rpm - sudo yum localinstall influxdb2-{{< latest-patch >}}-1.aarch64.rpm - ``` - -2. Start the InfluxDB service: - + ```bash + # RedHat and CentOS + # Add the InfluxData key to verify downloads + curl --silent --location -O \ + https://repos.influxdata.com/influxdata-archive.key \ + && echo "943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515 influxdata-archive.key" \ + | sha256sum --check - && cat influxdata-archive.key \ + | gpg --dearmor \ + | tee /etc/pki/rpm-gpg/RPM-GPG-KEY-influxdata > /dev/null - ```sh + # Add the InfluxData repository to the repository list. + cat < + ```bash sudo service influxdb start ``` Installing the InfluxDB package creates a service file at `/lib/systemd/system/influxdb.service` to start InfluxDB as a background service on startup. -3. To verify that the service is running correctly, restart your system and then enter the following command in your terminal: +4. To verify that the service is running correctly, restart your system and then enter the following command in your terminal: - ```sh + + ```bash sudo service influxdb status ``` @@ -277,6 +429,7 @@ You can use systemd to customize [InfluxDB configuration options](/influxdb/v2/r ```sh ARG1="--http-bind-address :8087" ARG2="--storage-wal-fsync-delay=15m" + ``` 2. Edit the `/lib/systemd/system/influxdb.service` file to pass the variables to the `ExecStart` value: @@ -296,39 +449,113 @@ _If necessary, adjust the example file paths and utilities for your system._ InfluxDB v2 (amd64) InfluxDB v2 (arm) + + + + ```sh # Use curl to download the amd64 binary. - curl -LO \ + curl --location -O \ https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz ``` + + ```sh # Use curl to download the arm64 binary. - curl -LO \ + curl --location -O \ https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_arm64.tar.gz ``` -2. Extract the downloaded binary--for example, enter the following command +2. [Choose the InfluxData key-pair for your OS version](#choose-the-influxdata-key-pair-for-your-system). + +3. {{< req text="Recommended:" color="magenta" >}}: Verify the authenticity of the downloaded binary--for example, + enter the following command in your terminal. + + _Before running the command for your system, replace + `https://repos.influxdata.com/influxdata-archive.key` with the key URL + from the preceding step._ + + + + ```bash + # amd64 + # Download and import the key + curl --silent --location https://repos.influxdata.com/influxdata-archive.key \ + | gpg --import - 2>&1 \ + | grep 'InfluxData Package Signing Key ' \ + && + # Download and verify the binary's signature file + curl --silent --location "https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz.asc" \ + | gpg --verify - influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz \ + 2>&1 | grep 'InfluxData Package Signing Key ' + ``` + + + ```bash + # arm64 + # Download and import the key + curl --silent --location https://repos.influxdata.com/influxdata-archive.key \ + | gpg --import - 2>&1 \ + | grep 'InfluxData Package Signing Key ' \ + && + # Download and verify the binary's signature file + curl --silent --location "https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_arm64.tar.gz.asc" \ + | gpg --verify - influxdb2-{{< latest-patch >}}_linux_arm64.tar.gz \ + 2>&1 | grep 'InfluxData Package Signing Key ' + ``` + + If successful, the output is similar to the following: + + + + ``` + gpg: Good signature from "InfluxData Package Signing Key " [unknown] + ``` + +4. Extract the downloaded binary--for example, enter the following command for your system: - ```sh + ```bash # amd64 tar xvzf ./influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz ``` - ```sh + ```bash # arm64 tar xvzf ./influxdb2-{{< latest-patch >}}_linux_arm64.tar.gz ``` -3. Optional: Place the extracted `influxd` executable binary in your system `$PATH`. +5. Optional: Place the extracted `influxd` executable binary in your system `$PATH`. - ```sh + ```bash # amd64 sudo cp ./influxdb2-{{< latest-patch >}}/usr/bin/influxd /usr/local/bin/ ``` - ```sh + ```bash # arm64 sudo cp ./influxdb2-{{< latest-patch >}}/usr/bin/influxd /usr/local/bin/ ``` @@ -338,7 +565,7 @@ _If necessary, adjust the example file paths and utilities for your system._ - ```sh + ```bash ./influxdb2-{{< latest-patch >}}/usr/bin/influxd ``` @@ -359,57 +586,6 @@ command in your terminal: chmod 0750 ~/.influxdbv2 ``` -{{% /expand %}} -{{% expand "Recommended – Verify the authenticity of downloaded binary" %}} - -For added security, use `gpg` to verify the signature of your download. -(Most operating systems include the `gpg` command by default. -To install `gpg`, see the [GnuPG installation instructions](https://gnupg.org/download/)). - -1. Download and import InfluxData's public key. - `gpg --import` outputs to stderr. - The following example shows how to import the key, redirect the output to stdout, - and then check for the expected key name: - - - - - - ```sh - curl -s https://repos.influxdata.com/influxdata-archive_compat.key \ - | gpg --import - 2>&1 \ - | grep 'InfluxData Package Signing Key ' - ``` - - If successful, the output is similar to the following: - - - - ``` - gpg: key D8FF8E1F7DF8B07E: public key "InfluxData Package Signing Key " imported - ``` - -2. Download the signature file for the release by adding `.asc` to the download - URL, and then use `gpg` to verify the download signature--for example: - - ```sh - curl -sL https://download.influxdata.com/influxdb/releases/influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz.asc \ - | gpg --verify - influxdb2-{{< latest-patch >}}_linux_amd64.tar.gz \ - 2>&1 | grep 'InfluxData Package Signing Key ' - ``` - - If successful, the output is the following: - - - - ``` - gpg: Good signature from "InfluxData Package Signing Key " [unknown] - ``` - {{% /expand %}} {{< /expand-wrapper >}} @@ -444,7 +620,7 @@ The InfluxDB server ([`influxd`](/influxdb/v2/reference/cli/influxd/)) and the [`influx` CLI](/influxdb/v2/reference/cli/influx/) are packaged and versioned separately. -_You'll install the `influx CLI` in a [later step](#download-and-install-the-influx-cli)._ +_You'll install the `influx CLI` in a [later step](#download-install-and-configure-the-influx-cli)._ {{% /note %}} @@ -513,7 +689,7 @@ container._ -```sh +```bash docker run \ --name influxdb2 \ --publish 8086:8086 \ @@ -584,7 +760,7 @@ command to interact with the `influx` and `influxd` CLIs inside the container. -```sh +```bash docker exec -it ` ``` @@ -592,14 +768,14 @@ docker exec -it ` -```sh +```bash # List CLI configurations docker exec -it influxdb2 influx config ls ``` -```sh +```bash # View the server configuration docker exec -it influxdb2 influx server-config # Inspect server details @@ -630,14 +806,14 @@ InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) a - ```sh + ```bash # with minikube minikube start ``` - ```sh + ```bash # with kind kind create cluster ``` @@ -646,7 +822,7 @@ InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) a - ```sh + ```bash kubectl apply -f https://raw.githubusercontent.com/influxdata/docs-v2/master/static/downloads/influxdb-k8-minikube.yaml ``` @@ -659,7 +835,7 @@ InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) a - ```sh + ```bash kubectl get pods -n influxdb ``` @@ -667,7 +843,7 @@ InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) a - ```sh + ```bash kubectl describe service -n influxdb influxdb ``` @@ -677,7 +853,7 @@ InfluxData also makes [Helm charts](https://github.com/influxdata/helm-charts) a - ```sh + ```bash kubectl port-forward -n influxdb service/influxdb 8086:8086 ``` @@ -692,12 +868,12 @@ To run InfluxDB on Raspberry Pi, you need: - a Raspberry Pi 4+ or 400 - a 64-bit operating system. - _Recommended_ : a [64-bit version of Ubuntu](https://ubuntu.com/download/raspberry-pi) + {{< req text="Recommended:" color="magenta" >}}: a [64-bit version of Ubuntu](https://ubuntu.com/download/raspberry-pi) of Ubuntu Desktop or Ubuntu Server compatible with 64-bit Raspberry Pi. ### Install Linux binaries -Follow the [Linux installation instructions](/influxdb/v2/install/?t=linux) +Follow the [Linux installation instructions](/influxdb/v2/install/?t=Linux#install-linux) to install InfluxDB on a Raspberry Pi. ### Monitor your Raspberry Pi @@ -718,10 +894,9 @@ to collect and send data to: {{< /tabs-wrapper >}} -2. **Start InfluxDB**. - +## Start InfluxDB - If it isn't already running, follow the instructions to start InfluxDB on your system: +If it isn't already running, follow the instructions to start InfluxDB on your system: {{< tabs-wrapper >}} {{% tabs %}} @@ -739,7 +914,7 @@ To start InfluxDB, run the `influxd` daemon: -```sh +```bash influxd ``` @@ -777,9 +952,7 @@ We are in the process of updating the build process to ensure released binaries After running `influxd`, you might see an error in the log output like the following: - - -```sh +```text too many open files ``` @@ -798,7 +971,7 @@ If the binary was manually downloaded and added to the system `$PATH`, start the -```sh +```bash influxd ``` @@ -835,13 +1008,14 @@ the following message: To use the Docker CLI to start an existing container, enter the following command: -```sh + +```bash docker start influxdb2 ``` Replace `influxdb2` with the name of your container. -To start a new container, follow instructions to [install and set up InfluxDB in a container](?t=docker#install-and-setup-influxdb-in-a-container). +To start a new container, follow instructions to [install and set up InfluxDB in a container](?t=docker#install-and-set-up-influxdb-in-a-container). {{% /tab-content %}} @@ -865,7 +1039,9 @@ To start InfluxDB using Kubernetes, follow instructions to [install InfluxDB in {{% expand "Configure the port or address" %}} By default, the InfluxDB UI and HTTP API use port `8086`. -To specify a different port or address, override the [`http-bind-address` option](/influxdb/v2/reference/config-options/#http-bind-address) when starting `influxd`--for example: +To specify a different port or address, override the +[`http-bind-address` option](/influxdb/v2/reference/config-options/#http-bind-address) +when starting `influxd`--for example: {{< code-tabs-wrapper >}} {{% code-tabs %}} @@ -876,7 +1052,7 @@ To specify a different port or address, override the [`http-bind-address` option -```sh +```bash influxd --http-bind-address ``` @@ -911,7 +1087,7 @@ To opt-out of sending telemetry data back to InfluxData, specify the -```sh +```bash influxd --reporting-disabled ``` @@ -932,13 +1108,15 @@ influxd --reporting-disabled For information about InfluxDB v2 default settings and how to override them, see [InfluxDB configuration options](/influxdb/v2/reference/config-options/). -3. {{< req text="Recommended:" color="magenta" >}} **Download, install, and configure the `influx` CLI**. - - We recommend installing the `influx` CLI, which provides a simple way to interact with InfluxDB from a - command line. - For detailed installation and setup instructions, - see [Use the influx CLI](/influxdb/v2/tools/influx-cli/). +With InfluxDB installed and initialized, [get started](/influxdb/v2/get-started/) writing and querying data. + +## Download, install, and configure the `influx` CLI + +{{< req text="Recommended:" color="magenta" >}}: Install the `influx` CLI, +which provides a simple way to interact with InfluxDB from a command line. +For detailed installation and setup instructions, +see [Use the influx CLI](/influxdb/v2/tools/influx-cli/). {{% note %}} @@ -950,5 +1128,3 @@ versioned separately. Some install methods (for example, the InfluxDB Docker Hub image) include both. {{% /note %}} - -With InfluxDB installed and initialized, [get started](/influxdb/v2/get-started/) writing and querying data. diff --git a/content/influxdb/v2/install/upgrade/v1-to-v2/automatic-upgrade.md b/content/influxdb/v2/install/upgrade/v1-to-v2/automatic-upgrade.md index 14df1c5e0..6dc3fea9b 100644 --- a/content/influxdb/v2/install/upgrade/v1-to-v2/automatic-upgrade.md +++ b/content/influxdb/v2/install/upgrade/v1-to-v2/automatic-upgrade.md @@ -18,7 +18,7 @@ related: --- Use the `influxd upgrade` command to upgrade InfluxDB 1.x to InfluxDB {{< current-version >}}. -The [`influxd upgrade`]((/influxdb/v2/reference/cli/influxd/upgrade/)) command is +The [`influxd upgrade`](/influxdb/v2/reference/cli/influxd/upgrade/) command is part of the **v2 `influxd` service** and provides an in-place upgrade from InfluxDB 1.x to InfluxDB {{< current-version >}}. @@ -148,7 +148,9 @@ If using an admin user for visualization or Chronograf administrative functions, **create a new read-only user before upgrading**: ##### Create a read-only 1.x user -```sh + + +```bash > CREATE USER WITH PASSWORD '' > GRANT READ ON TO "" ``` @@ -230,7 +232,8 @@ and are ready to proceed, follow these steps to upgrade your InfluxDB 1.x to Inf 2. Stop your running InfluxDB 1.x instance. Make a backup copy of all 1.x data before upgrading: - ```sh + + ```bash cp -R .influxdb/ .influxdb_bak/ ``` @@ -239,7 +242,10 @@ and are ready to proceed, follow these steps to upgrade your InfluxDB 1.x to Inf 4. If your 1.x configuration file is at the [default location](/influxdb/v1/administration/config/#using-the-configuration-file), run: - ```sh + + + + ```bash influxd upgrade ``` @@ -251,7 +257,9 @@ When installed from a `.deb` package, InfluxDB 1.x and 2.x run under the `influx If you've installed both versions from `.deb` packages, run the upgrade command as the `influxdb` user: -```sh + + +```bash sudo -u influxdb influxd upgrade ``` @@ -259,18 +267,22 @@ sudo -u influxdb influxd upgrade If your 1.x configuration file is not at the default location, run: - ```sh + + + ```bash influxd upgrade --config-file ``` To store the upgraded {{< current-version >}} configuration file in a custom location, include the `--v2-config-path` flag: - ```sh + + + ```bash influxd upgrade --v2-config-path ``` -5. Follow the prompts to set up a new InfluxDB {{< current-version >}} instance. +1. Follow the prompts to set up a new InfluxDB {{< current-version >}} instance. ``` Welcome to InfluxDB {{< current-version >}} upgrade! diff --git a/content/influxdb/v2/install/use-docker-compose.md b/content/influxdb/v2/install/use-docker-compose.md index 17cc0fccd..0bc1b9de3 100644 --- a/content/influxdb/v2/install/use-docker-compose.md +++ b/content/influxdb/v2/install/use-docker-compose.md @@ -54,9 +54,9 @@ Follow steps to set up and run InfluxDB using Docker Compose and `secrets`: environment: DOCKER_INFLUXDB_INIT_MODE: setup DOCKER_INFLUXDB_INIT_USERNAME_FILE: /run/secrets/influxdb2-admin-username - DOCKER_INFLUXDB_INIT_PASSWORD_FILE: /run/secrets/influxdb2-admin-password + DOCKER_INFLUXDB_INIT_PASSWORD_FILE: /run/secrets/influxdb2-admin-password DOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE: /run/secrets/influxdb2-admin-token - DOCKER_INFLUXDB_INIT_ORG: docs + DOCKER_INFLUXDB_INIT_ORG: docs DOCKER_INFLUXDB_INIT_BUCKET: home secrets: - influxdb2-admin-username @@ -114,15 +114,15 @@ Follow steps to set up and run InfluxDB using Docker Compose and `secrets`: At runtime, the `influxdb` image: 1. Mounts `secrets` files from your host filesystem to `/run/secrets/` -in the container. +in the container. 2. Assigns the environment variables to the specified files--for example: - ```yaml - environment: - DOCKER_INFLUXDB_INIT_USERNAME_FILE: /run/secrets/influxdb2-admin-username - DOCKER_INFLUXDB_INIT_PASSWORD_FILE: /run/secrets/influxdb2-admin-password - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE: /run/secrets/influxdb2-admin-token - ``` + ```yaml + environment: + DOCKER_INFLUXDB_INIT_USERNAME_FILE: /run/secrets/influxdb2-admin-username + DOCKER_INFLUXDB_INIT_PASSWORD_FILE: /run/secrets/influxdb2-admin-password + DOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE: /run/secrets/influxdb2-admin-token + ``` 3. Retrieves the secrets from the mounted files and runs setup. 4. Starts InfluxDB. @@ -131,17 +131,21 @@ in the container. If successful, InfluxDB initializes the user, password, organization, bucket, and _[Operator token](/influxdb/v2/admin/tokens/#operator-token)_, and then -logs to stdout. +logs to stdout. You can view the InfluxDB UI at . -_Although Docker prevents inadvertently exposing secrets (for example, in +{{% warn %}} + +Although Docker prevents inadvertently exposing secrets (for example, in `docker inspect` output), a -user that has access to the running container's filesystem can view the secrets._ +user that has access to the running container's filesystem can view the secrets. + +{{% /warn %}} ### Run InfluxDB CLI commands in a container After you start a container using the `influxdb` Docker Hub image, you can [use `docker exec` with the `influx` and `influxd` -CLIs](/influxdb/v2/install/#run-influxdb-cli-commands-in-a-container) inside the +CLIs](/influxdb/v2/install/?t=Docker#run-influxdb-cli-commands-in-a-container) inside the container. ### Manage files in mounted volumes diff --git a/content/influxdb/v2/query-data/flux/_index.md b/content/influxdb/v2/query-data/flux/_index.md index 6d98e91bf..8fd735b15 100644 --- a/content/influxdb/v2/query-data/flux/_index.md +++ b/content/influxdb/v2/query-data/flux/_index.md @@ -7,7 +7,7 @@ menu: influxdb_v2: name: Query with Flux parent: Query data -alias: +aliases: - /influxdb/v2/query-data/guides/ --- diff --git a/content/influxdb/v2/query-data/flux/rate.md b/content/influxdb/v2/query-data/flux/rate.md index 8d90c805f..fe0f86f75 100644 --- a/content/influxdb/v2/query-data/flux/rate.md +++ b/content/influxdb/v2/query-data/flux/rate.md @@ -22,7 +22,7 @@ list_query_example: rate_of_change Use [`derivative()`](/flux/v0/stdlib/universe/derivative/) to calculate the rate of change between subsequent values or -[`aggregate.rate()`](/flux/v0/stdlib/experimental/to/aggregate/rate/) +[`aggregate.rate()`](/flux/v0/stdlib/experimental/aggregate/rate/) to calculate the average rate of change per window of time. If time between points varies, these functions normalize points to a common time interval making values easily comparable. @@ -113,7 +113,7 @@ include negative values. ## Average rate of change per window of time -Use the [`aggregate.rate()` function](/flux/v0/stdlib/experimental/to/aggregate/rate/) +Use the [`aggregate.rate()` function](/flux/v0/stdlib/experimental/aggregate/rate/) to calculate the average rate of change per window of time. ```js diff --git a/content/influxdb/v2/query-data/influxql/explore-data/group-by.md b/content/influxdb/v2/query-data/influxql/explore-data/group-by.md index 2843d8b6b..54b11eed1 100644 --- a/content/influxdb/v2/query-data/influxql/explore-data/group-by.md +++ b/content/influxdb/v2/query-data/influxql/explore-data/group-by.md @@ -224,10 +224,11 @@ measurement. {{% expand "Group query results by tags that start with `l`" %}} ```sql -SELECT "water_level",location FROM "h2o_feet" GROUP BY /l/ +SELECT MAX("water_level"),location FROM "h2o_feet" GROUP BY /l/ ``` -This query uses a regular expression to group by tags that start with `l`. With the sample NOAA water dataset, results are grouped by the `location` tag. +This query uses a regular expression to group by tags that start with `l`. +With the sample NOAA water dataset, results are grouped by the `location` tag. {{% /expand %}} diff --git a/content/influxdb/v2/query-data/influxql/explore-data/regular-expressions.md b/content/influxdb/v2/query-data/influxql/explore-data/regular-expressions.md index f2bcafa73..8a4bce275 100644 --- a/content/influxdb/v2/query-data/influxql/explore-data/regular-expressions.md +++ b/content/influxdb/v2/query-data/influxql/explore-data/regular-expressions.md @@ -39,8 +39,8 @@ as those without. SELECT // FROM // WHERE [ // | //] GROUP BY // ``` -Regular expressions are surrounded by `/` characters and use -[Golang's regular expression syntax](http://golang.org/pkg/regexp/syntax/). +Regular expressions are surrounded by `/` characters and use the +[Go regular expression syntax](http://golang.org/pkg/regexp/syntax/). ## Supported operators @@ -49,6 +49,22 @@ Regular expressions are surrounded by `/` characters and use ### Examples + + {{< expand-wrapper >}} {{% expand "Use a regular expression to specify field keys and tag keys in the SELECT clause" %}} @@ -57,7 +73,20 @@ Regular expressions are surrounded by `/` characters and use SELECT /l/ FROM "h2o_feet" LIMIT 1 ``` + + Output: + {{% influxql/table-meta %}} Name: h2o_feet {{% /influxql/table-meta %}} @@ -77,6 +106,40 @@ The syntax `//::[field | tag]` is not supported. {{% /expand %}} +{{% expand "Use a regular expression to specify field keys and tag keys in function arguments" %}} + +```sql +SELECT MAX(/_level/) FROM "h2o_feet" LIMIT 1 +``` + + + +Output: + +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | max_water_level | +| :------------------- | ---------------------:| +| 2019-08-28T07:24:00Z | 9.964 + +This query uses the InfluxQL [`MAX()` selector function](/influxdb/v2/query-data/influxql/functions/selectors/#max) +to find the greatest field value out of all field keys that match the regular expression. + +{{% /expand %}} + {{% expand "Use a regular expression to specify measurements in the FROM clause" %}} ```sql diff --git a/content/influxdb/v2/query-data/influxql/explore-data/select.md b/content/influxdb/v2/query-data/influxql/explore-data/select.md index 2bf50f9c9..6c43ab5c9 100644 --- a/content/influxdb/v2/query-data/influxql/explore-data/select.md +++ b/content/influxdb/v2/query-data/influxql/explore-data/select.md @@ -58,7 +58,7 @@ Other supported features include: ### `FROM` clause The `SELECT` clause specifies the measurement to query. -This clause supports several formats for specifying a [measurement(s)](/influxdb/v2/reference/glossary/#measurement): +This clause supports several formats for specifying a [measurement](/influxdb/v2/reference/glossary/#measurement): - `FROM ` - Returns data from a measurement. - `FROM ,` - Returns data from more than one measurement. @@ -319,97 +319,19 @@ Name: h2o_feet ## Regular expressions -InfluxQL supports using regular expressions when specifying: +InfluxQL supports using [regular expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/) when specifying: - [field keys](/influxdb/v2/reference/glossary/#field-key) and [tag keys](/influxdb/v2/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/v2/query-data/influxql/explore-data/select/) - [measurements](/influxdb/v2/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/v2/query-data/influxql/explore-data/select/#from-clause) - [tag values](/influxdb/v2/reference/glossary/#tag-value) and string [field values](/influxdb/v2/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/v2/query-data/influxql/explore-data/where/). - [tag keys](/influxdb/v2/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/v2/query-data/influxql/explore-data/group-by/) -Currently, InfluxQL does not support using regular expressions to match -non-string field values in the -`WHERE` clause, -[databases](/influxdb/v2/reference/glossary/#database), and -[retention policies](/influxdb/v2/reference/glossary/#retention-policy-rp). - -{{% note %}} -**Note:** Regular expression comparisons are more computationally intensive than exact -string comparisons. Queries with regular expressions are not as performant -as those without. -{{% /note %}} - ## Syntax ```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` -Regular expressions are surrounded by `/` characters and use -[Golang's regular expression syntax](http://golang.org/pkg/regexp/syntax/). - -## Supported operators - -`=~`: matches against -`!~`: doesn't match against - -## Examples - -{{< expand-wrapper >}} -{{% expand "Use a regular expression to specify field keys and tag keys in the SELECT statement" %}} -#### Use a regular expression to specify field keys and tag keys in the SELECT statement - -```sql -SELECT /l/ FROM "h2o_feet" LIMIT 1 -``` -Output: -{{% influxql/table-meta %}} -Name: h2o_feet -{{% /influxql/table-meta %}} - -| time | level description | location | water_level | -| :-------------- |:----------------------| :-------------------| ------------------:| -| 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | - -The query selects all [field keys](/influxdb/v2/reference/glossary/#field-key) -and [tag keys](/influxdb/v2/reference/glossary/#tag-key) that include an `l`. -Note that the regular expression in the `SELECT` clause must match at least one -field key in order to return results for a tag key that matches the regular -expression. - -Currently, there is no syntax to distinguish between regular expressions for -field keys and regular expressions for tag keys in the `SELECT` clause. -The syntax `//::[field | tag]` is not supported. - -{{% /expand %}} - -{{% expand "Use a regular expression to specify measurements in the FROM clause" %}} - -```sql -SELECT MEAN("degrees") FROM /temperature/ -``` -Output: -{{% influxql/table-meta %}} -Name: average_temperature -{{% /influxql/table-meta %}} - -| time | mean| -| :-------------- |----------------------:| -| 1970-01-01T00:00:00Z | 79.9847293223 - - -{{% influxql/table-meta %}} -Name: h2o_temperature -{{% /influxql/table-meta %}} - -| time | mean| -| :-------------- |----------------------:| -| 1970-01-01T00:00:00Z | 64.9980273540 | - - -This query uses the InfluxQL [MEAN() function](/influxdb/v2/query-data/influxql/functions/aggregates/#mean) to calculate the average `degrees` for every [measurement](/influxdb/v2/reference/glossary/#measurement) in the `noaa` database that contains the word `temperature`. - -{{% /expand %}} - -{{< /expand-wrapper >}} +See [regular expressions](/influxdb/v2/query-data/influxql/explore-data/regular-expressions/) for more information. ## Data types and cast operations diff --git a/content/influxdb/v2/query-data/influxql/functions/transformations.md b/content/influxdb/v2/query-data/influxql/functions/transformations.md index 7b86bfcb7..031e3441d 100644 --- a/content/influxdb/v2/query-data/influxql/functions/transformations.md +++ b/content/influxdb/v2/query-data/influxql/functions/transformations.md @@ -1,6 +1,6 @@ --- title: InfluxQL transformation functions -list_title: Tranfsormation functions +list_title: Transformation functions description: > Use transformation functions modify and return values each row of queried data. menu: diff --git a/content/influxdb/v2/reference/api/_index.md b/content/influxdb/v2/reference/api/_index.md index 3e873d6ad..69ebe1c37 100644 --- a/content/influxdb/v2/reference/api/_index.md +++ b/content/influxdb/v2/reference/api/_index.md @@ -1,5 +1,5 @@ --- -title: InfluxDB v2 API +title: InfluxDB HTTP API description: > The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB, such as writing and querying data, and managing resources within an InfluxDB instance. @@ -7,13 +7,17 @@ description: > menu: influxdb_v2: parent: Reference + name: InfluxDB HTTP API weight: 3 influxdb/v2/tags: [api] aliases: - /influxdb/v2/concepts/api/ +related: + - /influxdb/v2/api-guide/api_intro/ + - /influxdb/v2/api-guide/influxdb-1x/ --- -The InfluxDB v2 API provides a programmatic interface for interactions such as writing and querying data, and managing resources in {{% product-name %}}. +The InfluxDB HTTP API provides a programmatic interface for interactions such as writing and querying data, and managing resources in {{% product-name %}}. Access the InfluxDB HTTP API using the `/api/v2/` endpoint or InfluxDB v1 endpoints for {{% product-name %}} @@ -37,6 +41,6 @@ and visit the `/docs` endpoint in a browser ([localhost:8086/docs](http://localh InfluxDB v1 API for {{% product-name %}} -The InfluxDB HTTP API includes [InfluxDB v1 compatibility endpoints](/influxdb/v2/reference/api/influxdb-1x/) +The InfluxDB HTTP API includes InfluxDB v1 compatibility endpoints that work with InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. diff --git a/content/influxdb/v2/reference/cli/influx/_index.md b/content/influxdb/v2/reference/cli/influx/_index.md index 30fcce5a1..0c0e557be 100644 --- a/content/influxdb/v2/reference/cli/influx/_index.md +++ b/content/influxdb/v2/reference/cli/influx/_index.md @@ -91,12 +91,12 @@ brew list | grep influxdb-cli 1. **Download the `influx` CLI package.** - influx CLI v{{< latest-patch cli=true >}} (macOS) + influx CLI v{{< latest-patch cli=true >}} (macOS) 2. **Unpackage the downloaded package.** Do one of the following: - + - Double-click the downloaded package file in **Finder**. - Run the following command in a macOS command prompt application such **Terminal** or **[iTerm2](https://www.iterm2.com/)**: @@ -140,17 +140,17 @@ brew list | grep influxdb-cli #### Download from your browser - influx CLI v{{< latest-patch cli=true >}} (amd64) - influx CLI v{{< latest-patch cli=true >}} (arm) + influx CLI v{{< latest-patch cli=true >}} (amd64) + influx CLI v{{< latest-patch cli=true >}} (arm) #### Download from the command line ```sh # amd64 - wget https://download.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz + wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz # arm - wget https://download.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz + wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz ``` 4. **Unpackage the downloaded package.** @@ -191,10 +191,10 @@ Command Prompt is not fully compatible. 1. **Download the `influx` CLI package.** - influx CLI v{{< latest-patch cli=true >}} (Windows) + influx CLI v{{< latest-patch cli=true >}} (Windows) 2. **Expand the downloaded archive.** - + Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename it if desired. ```powershell diff --git a/content/influxdb/v2/reference/cli/influx/bucket/create.md b/content/influxdb/v2/reference/cli/influx/bucket/create.md index 0425d8c1c..2c5d85eb1 100644 --- a/content/influxdb/v2/reference/cli/influx/bucket/create.md +++ b/content/influxdb/v2/reference/cli/influx/bucket/create.md @@ -105,11 +105,10 @@ influx bucket create \ ##### Create a bucket with an explicit schema -{{% cloud %}} -[Explicit bucket schemas](/influxdb/cloud/reference/cli/influx/bucket-schema) are only -supported in **InfluxDB Cloud**. -For more information, see [Manage bucket schema](/influxdb/cloud/admin/buckets/bucket-schema/). -{{% /cloud %}} +> [!Important] +> [Explicit bucket schemas](/influxdb/cloud/reference/cli/influx/bucket-schema) are only +> supported in **InfluxDB Cloud**. +> For more information, see [Manage bucket schema](/influxdb/cloud/admin/buckets/bucket-schema/). ```sh {{< get-shared-text "bucket-schema/bucket-schema-type.sh" >}} diff --git a/content/influxdb/v2/reference/cli/influx/remote/_index.md b/content/influxdb/v2/reference/cli/influx/remote/_index.md index 2be9d03e6..4c2c63bcc 100644 --- a/content/influxdb/v2/reference/cli/influx/remote/_index.md +++ b/content/influxdb/v2/reference/cli/influx/remote/_index.md @@ -12,9 +12,11 @@ related: - /influxdb/v2/write-data/replication --- -{{% cloud %}} -Configure InfluxDB Edge Data Replication remotes and replication streams to replicate data from InfluxDB OSS to remote buckets on InfluxDB Cloud, InfluxDB Enterprise, or another InfluxDB OSS instance. Currently, you cannot configure remotes and replication streams on InfluxDB Cloud. -{{% /cloud %}} +> [!Important] +> Configure InfluxDB Edge Data Replication remotes and replication streams to +> replicate data from InfluxDB OSS to remote buckets on InfluxDB Cloud, InfluxDB +> Enterprise, or another InfluxDB OSS instance. Currently, you cannot configure +> remotes and replication streams on InfluxDB Cloud. Use the `influx remote` command to manage connections to remote instances of InfluxDB. Remote connections are used to replicate data on write at the bucket level. diff --git a/content/influxdb/v2/reference/cli/influx/remote/create.md b/content/influxdb/v2/reference/cli/influx/remote/create.md index f1b210e7a..57b072415 100644 --- a/content/influxdb/v2/reference/cli/influx/remote/create.md +++ b/content/influxdb/v2/reference/cli/influx/remote/create.md @@ -11,9 +11,8 @@ related: - /influxdb/v2/reference/cli/influx/replication --- -{{% cloud %}} -Replication remotes and replication streams can only be configured for InfluxDB OSS. -{{% /cloud %}} +> [!Important] +> Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx remote create` command creates a new remote InfluxDB connection for replicating data. diff --git a/content/influxdb/v2/reference/cli/influx/remote/delete.md b/content/influxdb/v2/reference/cli/influx/remote/delete.md index 47e2f655d..4608c9ae7 100644 --- a/content/influxdb/v2/reference/cli/influx/remote/delete.md +++ b/content/influxdb/v2/reference/cli/influx/remote/delete.md @@ -11,9 +11,8 @@ related: - /influxdb/v2/reference/cli/influx/replication --- -{{% cloud %}} -Replication remotes and replication streams can only be configured for InfluxDB OSS. -{{% /cloud %}} +> [!Important] +> Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx remote delete` command delete an existing remote InfluxDB connection used for replication. diff --git a/content/influxdb/v2/reference/cli/influx/remote/list.md b/content/influxdb/v2/reference/cli/influx/remote/list.md index 35f914bec..f6a689e00 100644 --- a/content/influxdb/v2/reference/cli/influx/remote/list.md +++ b/content/influxdb/v2/reference/cli/influx/remote/list.md @@ -11,9 +11,8 @@ related: - /influxdb/v2/reference/cli/influx/replication --- -{{% cloud %}} -Replication remotes and replication streams can only be configured for InfluxDB OSS. -{{% /cloud %}} +> [!Important] +> Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx remote list` command lists all remote InfluxDB connections used for replication. diff --git a/content/influxdb/v2/reference/cli/influx/remote/update.md b/content/influxdb/v2/reference/cli/influx/remote/update.md index 890ec8f3d..a34ec7006 100644 --- a/content/influxdb/v2/reference/cli/influx/remote/update.md +++ b/content/influxdb/v2/reference/cli/influx/remote/update.md @@ -12,9 +12,8 @@ related: --- -{{% cloud %}} -Replication remotes and replication streams can only be configured for InfluxDB OSS. -{{% /cloud %}} +> [!Important] +> Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx remote update` command updates an existing InfluxDB remote connection used for replicating data. diff --git a/content/influxdb/v2/reference/cli/influx/replication/create.md b/content/influxdb/v2/reference/cli/influx/replication/create.md index 036715191..f79fc0849 100644 --- a/content/influxdb/v2/reference/cli/influx/replication/create.md +++ b/content/influxdb/v2/reference/cli/influx/replication/create.md @@ -9,10 +9,8 @@ weight: 101 influxdb/v2/tags: [write] --- -{{% cloud %}} -Replication remotes and replication streams can only be configured for InfluxDB OSS. -{{% /cloud %}} - +> [!Important] +> Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx replication create` command creates a new InfluxDB replication stream. diff --git a/content/influxdb/v2/reference/cli/influx/replication/delete.md b/content/influxdb/v2/reference/cli/influx/replication/delete.md index 2df1ee614..4b57f9619 100644 --- a/content/influxdb/v2/reference/cli/influx/replication/delete.md +++ b/content/influxdb/v2/reference/cli/influx/replication/delete.md @@ -9,9 +9,8 @@ weight: 102 influxdb/v2/tags: [write, replication] --- -{{% cloud %}} -Replication remotes and replication streams can only be configured for InfluxDB OSS. -{{% /cloud %}} +> [!Important] +> Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx replication delete` command deletes an InfluxDB replication stream. diff --git a/content/influxdb/v2/reference/cli/influx/replication/list.md b/content/influxdb/v2/reference/cli/influx/replication/list.md index 4bbe22076..8144c9adc 100644 --- a/content/influxdb/v2/reference/cli/influx/replication/list.md +++ b/content/influxdb/v2/reference/cli/influx/replication/list.md @@ -9,9 +9,8 @@ weight: 102 influxdb/v2/tags: [write, replication] --- -{{% cloud %}} -Replication remotes and replication streams can only be configured for InfluxDB OSS. -{{% /cloud %}} +> [!Important] +> Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx replication list` command lists all InfluxDB replication streams and their corresponding metrics. diff --git a/content/influxdb/v2/reference/cli/influx/replication/update.md b/content/influxdb/v2/reference/cli/influx/replication/update.md index aff267e29..27c10b3b2 100644 --- a/content/influxdb/v2/reference/cli/influx/replication/update.md +++ b/content/influxdb/v2/reference/cli/influx/replication/update.md @@ -9,9 +9,8 @@ weight: 102 influxdb/v2/tags: [write, replication] --- -{{% cloud %}} -Replication remotes and replication streams can only be configured for InfluxDB OSS. -{{% /cloud %}} +> [!Important] +> Replication remotes and replication streams can only be configured for InfluxDB OSS. The `influx replication update` command updates an InfluxDB replication stream. diff --git a/content/influxdb/v2/reference/cli/influx/write/_index.md b/content/influxdb/v2/reference/cli/influx/write/_index.md index e0cea7868..4a879f53f 100644 --- a/content/influxdb/v2/reference/cli/influx/write/_index.md +++ b/content/influxdb/v2/reference/cli/influx/write/_index.md @@ -99,6 +99,7 @@ In **extended annotated CSV**, measurements, fields, and values and their types - [via stdin](#write-line-protocol-via-stdin) - [from a file](#write-line-protocol-from-a-file) +- [and skip header lines](#skip-header-lines-in-a-file) - [from multiple files](#write-line-protocol-from-multiple-files) - [from a URL](#write-line-protocol-from-a-url) - [from multiple URLs](#write-line-protocol-from-multiple-urls) @@ -135,6 +136,14 @@ influx write \ --file path/to/line-protocol.txt ``` +##### Skip header lines in a file +```sh +influx write \ + --bucket example-bucket \ + --file path/to/line-protocol.txt + --skipHeader 8 +``` + ##### Write line protocol from multiple files ```sh influx write \ diff --git a/content/influxdb/v2/reference/cli/influxd/recovery/auth/create-operator.md b/content/influxdb/v2/reference/cli/influxd/recovery/auth/create-operator.md index 6970594ef..8cb178b0e 100644 --- a/content/influxdb/v2/reference/cli/influxd/recovery/auth/create-operator.md +++ b/content/influxdb/v2/reference/cli/influxd/recovery/auth/create-operator.md @@ -35,7 +35,7 @@ influxd recovery auth create-operator [flags] ##### Generate a new operator token ```sh -influxd \ +influxd recovery auth create-operator \ --org example-org \ --username example-user ``` \ No newline at end of file diff --git a/content/influxdb/v2/reference/config-options.md b/content/influxdb/v2/reference/config-options.md index 71ce2fafe..b5a6a2479 100644 --- a/content/influxdb/v2/reference/config-options.md +++ b/content/influxdb/v2/reference/config-options.md @@ -34,23 +34,20 @@ Server configuration commands require an [Operator token](/influxdb/v2/admin/tok Use the [`influx server-config` command](/influxdb/v2/reference/cli/influx/server-config/) to retrieve your runtime server configuration. - - - ```sh influx server-config ``` @@ -226,7 +223,7 @@ _Typically, InfluxData internal use only._ influxd --assets-path=/path/to/custom/assets-dir ``` - ```sh @@ -825,7 +823,7 @@ potentially hurt performance. influxd --http-write-timeout=10s ``` - @@ -320,4 +320,4 @@ To install `influx` shell completion scripts, see ## Use influx CLI commands _For information about `influx` CLI commands, see the -[`influx` CLI reference documentation](/influxdb/v2/reference/cli/influx/)._ \ No newline at end of file +[`influx` CLI reference documentation](/influxdb/v2/reference/cli/influx/)._ diff --git a/content/influxdb/v2/tools/influxql-shell.md b/content/influxdb/v2/tools/influxql-shell.md index dd4e44ff8..7823d23b6 100644 --- a/content/influxdb/v2/tools/influxql-shell.md +++ b/content/influxdb/v2/tools/influxql-shell.md @@ -136,7 +136,7 @@ Within the InfluxQL shell, execute any InfluxQL query supported by InfluxDB {{< For information about what queries are supported see [InfluxQL support in InfluxDB {{< current-version >}}](/influxdb/v2/query-data/influxql/#influxql-support). -View the [InfluxQL documentation (InfluxDB 1.8)](/influxdb/v1/query_language/) +View the [InfluxQL documentation (1.11)](/influxdb/v1/query_language/) for in-depth documentation about the query language. ## Use and configure display formats diff --git a/content/influxdb/v2/tools/notebooks/clean-data.md b/content/influxdb/v2/tools/notebooks/clean-data.md index 0e215ed74..df0588155 100644 --- a/content/influxdb/v2/tools/notebooks/clean-data.md +++ b/content/influxdb/v2/tools/notebooks/clean-data.md @@ -23,9 +23,8 @@ normalizes degree-based wind directions to cardinal directions, and then writes the normalized data to a bucket. {{< cloud-only >}} -{{% cloud %}} -**Note**: Using sample data counts towards your total InfluxDB Cloud usage. -{{% /cloud %}} +> [!Important] +> **Note**: Using sample data counts towards your total InfluxDB Cloud usage. {{< /cloud-only >}} 1. [Create a new notebook](/influxdb/v2/tools/notebooks/create-notebook/). diff --git a/content/influxdb/v2/visualize-data/dashboards/_index.md b/content/influxdb/v2/visualize-data/dashboards/_index.md index 674b859ed..2efb73307 100644 --- a/content/influxdb/v2/visualize-data/dashboards/_index.md +++ b/content/influxdb/v2/visualize-data/dashboards/_index.md @@ -14,7 +14,7 @@ Create, edit, and manage dashboards from the **Dashboards** tab in the left navi {{< children >}} -## View your dashboard ID +### View your dashboard ID Use the InfluxDB UI or `influx` CLI to view your dashboard ID. diff --git a/content/influxdb/v2/write-data/best-practices/optimize-writes.md b/content/influxdb/v2/write-data/best-practices/optimize-writes.md index fff176d8a..c5c43f66f 100644 --- a/content/influxdb/v2/write-data/best-practices/optimize-writes.md +++ b/content/influxdb/v2/write-data/best-practices/optimize-writes.md @@ -127,6 +127,5 @@ For example: "5MB / 5min" can be also expressed as `17476.266666667Bs`, `1MB/1mi If the rate limit format is invalid, `influx write` prints out the format and an exact regular expression. The `--rate-limit` flag can be also used with [`influx write dryrun`](/influxdb/v2/reference/cli/influx/write/dryrun/). -{{% cloud %}} -By default, the free tier rate limit in InfluxDB Cloud is `1MB/min`. -{{% /cloud %}} +> [!Important] +> By default, the free tier rate limit in InfluxDB Cloud is `1MB/min`. diff --git a/content/influxdb/v2/write-data/migrate-data/migrate-cloud-to-oss.md b/content/influxdb/v2/write-data/migrate-data/migrate-cloud-to-oss.md index a4ea7e3a3..333a44e71 100644 --- a/content/influxdb/v2/write-data/migrate-data/migrate-cloud-to-oss.md +++ b/content/influxdb/v2/write-data/migrate-data/migrate-cloud-to-oss.md @@ -21,10 +21,9 @@ The following guide provides instructions for setting up an InfluxDB OSS task that queries data from an InfluxDB Cloud bucket in time-based batches and writes each batch to an InfluxDB OSS bucket. -{{% cloud %}} -All queries against data in InfluxDB Cloud are subject to your organization's -[rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). -{{% /cloud %}} +> [!Important] +> All queries against data in InfluxDB Cloud are subject to your organization's +> [rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - [Set up the migration](#set-up-the-migration) - [Migration task](#migration-task) diff --git a/content/influxdb/v2/write-data/migrate-data/migrate-oss.md b/content/influxdb/v2/write-data/migrate-data/migrate-oss.md index 97cc84cff..2f9796973 100644 --- a/content/influxdb/v2/write-data/migrate-data/migrate-oss.md +++ b/content/influxdb/v2/write-data/migrate-data/migrate-oss.md @@ -17,13 +17,13 @@ To migrate data from an InfluxDB OSS bucket to another InfluxDB OSS or InfluxDB Cloud bucket, export your data as line protocol and write it to your other InfluxDB bucket. -{{% cloud %}} -#### InfluxDB Cloud write limits -If migrating data from InfluxDB OSS to InfluxDB Cloud, you are subject to your -[InfluxDB Cloud organization's rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). -Consider exporting your data in time-based batches to limit the file size -of exported line protocol to match your InfluxDB Cloud organization's limits. -{{% /cloud %}} +> [!Important] +> +> #### InfluxDB Cloud write limits +> If migrating data from InfluxDB OSS to InfluxDB Cloud, you are subject to your +> [InfluxDB Cloud organization's rate limits and adjustable quotas](/influxdb/cloud/account-management/limits/). +> Consider exporting your data in time-based batches to limit the file size +> of exported line protocol to match your InfluxDB Cloud organization's limits. 1. [Find the InfluxDB OSS bucket ID](/influxdb/{{< current-version-link >}}/organizations/buckets/view-buckets/) that contains data you want to migrate. diff --git a/content/influxdb/v2/write-data/no-code/load-data.md b/content/influxdb/v2/write-data/no-code/load-data.md index df2c213a3..07e795df2 100644 --- a/content/influxdb/v2/write-data/no-code/load-data.md +++ b/content/influxdb/v2/write-data/no-code/load-data.md @@ -17,7 +17,6 @@ Load data from the following sources in the InfluxDB user interface (UI): - [Line protocol](#load-data-using-line-protocol) - [Client libraries](#load-data-from-a-client-library-in-the-ui) - [Telegraf plugins](#load-data-from-a-telegraf-plugin-in-the-ui) -- {{% cloud-only %}}[Native MQTT subscriptions](#set-up-a-native-mqtt-subscription){{% /cloud-only %}} ### Load CSV or line protocol in UI @@ -76,11 +75,16 @@ Load CSV or line protocol data by uploading a file or pasting the data manually - **Create a new configuration**: Enter a configuration name and select an output bucket, and then click **Continue Configuring**. - **Add to an existing configuration**: Select an existing Telegraf configuration to add this plugin to, and then click **Add to Existing Config**. 5. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. -6. Adjust configuration settings as needed. To find configuration settings for a specific plugin, see [Telegraf plugins](/telegraf/latest/plugins/). -7. Click **Save and Test**. -8. The **Test Your Configuration** page provides instructions for how to start +6. Adjust configuration settings as needed. + The configuration includes settings for the [InfluxDB v2 output plugin](/telegraf/v1/plugins/#output-influxdb_v2) to write to your bucket. + To find configuration settings for a specific plugin, see [Telegraf plugins](/telegraf/latest/plugins/). +7. Click **Save and Test**. Your input plugin configuration is appended to the default agent settings and the InfluxDB output plugin configuration. +8. The **Test Your Configuration** page provides instructions for how to start Telegraf using the generated configuration. _See [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf) below for detailed information about what each step does._ -9. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. +9. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully sending data to InfluxDB. Once confirmed, a **Connection Found!** message appears. -10. Click **Finish**. Your Telegraf configuration name and the associated bucket name appear in the list of Telegraf configurations. +10. Click **Finish**. + Your Telegraf configuration name and the associated bucket name appear in the list of Telegraf configurations. +11. To view or edit the configuration, click the configuration name. +12. To view default settings used to write data to InfluxDB, click **InfluxDB Output Plugin**. diff --git a/content/influxdb/v2/write-data/no-code/scrape-data/_index.md b/content/influxdb/v2/write-data/no-code/scrape-data/_index.md index eb10f934b..5a0b7aee9 100644 --- a/content/influxdb/v2/write-data/no-code/scrape-data/_index.md +++ b/content/influxdb/v2/write-data/no-code/scrape-data/_index.md @@ -21,10 +21,8 @@ then write the scraped data to an InfluxDB bucket. Scrapers can collect data from any HTTP(S)-accessible endpoint that provides data in the [Prometheus data format](https://prometheus.io/docs/instrumenting/exposition_formats/). -{{% cloud %}} -Scrapers are not available in InfluxDB Cloud. -{{% /cloud %}} - +> [!Important] +> Scrapers are not available in InfluxDB Cloud. The following articles provide information about creating and managing InfluxDB data scrapers: diff --git a/content/influxdb/v2/write-data/oss-to-cloud.md b/content/influxdb/v2/write-data/oss-to-cloud.md index d08cfbe3c..40f903532 100644 --- a/content/influxdb/v2/write-data/oss-to-cloud.md +++ b/content/influxdb/v2/write-data/oss-to-cloud.md @@ -23,11 +23,11 @@ To replicate all writes to an InfluxDB OSS instance to an InfluxDB Cloud instanc use [InfluxDB replication streams](/influxdb/v2/write-data/replication/). {{% /note %}} -{{% cloud %}} -#### InfluxDB Cloud rate limits -Write requests to InfluxDB Cloud are subject to the rate limits associated with your -[InfluxDB Cloud pricing plan](/influxdb/cloud/account-management/pricing-plans/). -{{% /cloud %}} +> [!Important] +> +> #### InfluxDB Cloud rate limits +> Write requests to InfluxDB Cloud are subject to the rate limits associated with your +> [InfluxDB Cloud pricing plan](/influxdb/cloud/account-management/pricing-plans/). 1. Query data from InfluxDB OSS. 2. _(Optional)_ [Filter](/flux/v0/stdlib/universe/filter/) or process data to write to InfluxDB Cloud. diff --git a/content/kapacitor/v1/reference/about_the_project/release-notes.md b/content/kapacitor/v1/reference/about_the_project/release-notes.md index 6e77a4eb6..4fb722a07 100644 --- a/content/kapacitor/v1/reference/about_the_project/release-notes.md +++ b/content/kapacitor/v1/reference/about_the_project/release-notes.md @@ -9,6 +9,23 @@ aliases: - /kapacitor/v1/about_the_project/releasenotes-changelog/ --- +## v1.7.6 {date="2024-10-28"} + +### Features + +- Kafka Handler set and send SASL extensions. +- Kafka Handler SASL OAUTH token refreshing. + +### Bug Fixes + +- Using UTC timezone for alert levels. + +### Dependency updates + +- Upgrade Go to 1.22.7. + +--- + ## v1.7.5 {date="2024-06-12"} ### Dependency updates diff --git a/content/kapacitor/v1/reference/event_handlers/kafka.md b/content/kapacitor/v1/reference/event_handlers/kafka.md index f6515d08f..1c8064d98 100644 --- a/content/kapacitor/v1/reference/event_handlers/kafka.md +++ b/content/kapacitor/v1/reference/event_handlers/kafka.md @@ -37,6 +37,7 @@ Below is an example configuration: # Optional SASL configuration sasl-username = "xxxxx" sasl-password = "xxxxxxxx" + sasl-extensions = {} sasl-mechanism = "" sasl-version = "" # Use if sasl-mechanism is GSSAPI. GSSAPI is for organizations using Kerberos. @@ -46,7 +47,16 @@ Below is an example configuration: sasl-gssapi-kerberos-config-path = "/" sasl-gssapi-key-tab-path = "" sasl-gssapi-realm = "realm" - # Use if sasl-mechanism is `OAUTHBEARER` (experimental). + # Options if sasl-mechanism is OAUTHBEARER + sasl-oauth-service = "auth0" + sasl-oauth-client-id = "xxxxxxx" + sasl-oauth-client-secret = "xxxxxxxx" + sasl-oauth-token-url = "dedicated-auth0-token-url" + sasl-oauth-token-expiry-margin = "10s" + sasl-oauth-scopes = "" + sasl-oauth-tenant-id = "" + [kafka.sasl-oauth-parameters] + audience = "development" sasl-access-token = "" ``` @@ -102,8 +112,16 @@ Username to use for SASL authentication. #### sasl-password Password to use for SASL authentication. +### sasl-extensions +Arbitrary key value string pairs to pass as a TOML table + #### sasl-mechanism -SASL mechanism type. Options include `GSSAPI`, `OAUTHBEARER`, `PLAIN`. +SASL mechanism type. Options are: +- `GSSAPI` +- `OAUTHBEARER` +- `PLAIN` +- `SCRAM-SHA-256` +- `SCRAM-SHA-512` #### sasl-version SASL protocol version. @@ -126,8 +144,37 @@ Path to the Kerberos key tab. #### sasl-gssapi-realm Default Kerberos realm. +### Options if sasl-mechanism is OAUTHBEARER +#### sasl-oauth-service +The service name to use when authenticating with SASL/OAUTH. +One of: + - `""` (empty) or `custom` + - `auth0` + - `azuread` + +#### sasl-oauth-client-id +The client ID to use when authenticating with SASL/OAUTH. + +#### sasl-oauth-client-secret +The client secret to use when authenticating with SASL/OAUTH. + +#### sasl-oauth-token-url +The token URL to use when sasl-oauth-service is `custom` or `auth0`. Leave empty otherwise. + +#### sasl-oauth-token-expiry-margin +The margin for the token's expiration time. + +#### sasl-oauth-scopes +Optional scopes to use when authenticating with SASL/OAUTH. + +#### sasl-oauth-tenant-id +Tenant ID for the AzureAD service. + +#### [kafka.sasl-oauth-parameters] +The optional key/value params for SASL/OAUTH. e.g. audience for AUTH0 + #### sasl-access-token -Used if the SASL mechanism is `OAUTHBEARER` (experimental). +Static OAUTH token. Use this instead of other OAUTH params. ## Options The following Kafka event handler options can be set in a diff --git a/content/platform/install-and-deploy/install/oss-install.md b/content/platform/install-and-deploy/install/oss-install.md index 485031117..e4bc6808f 100644 --- a/content/platform/install-and-deploy/install/oss-install.md +++ b/content/platform/install-and-deploy/install/oss-install.md @@ -2,7 +2,8 @@ title: Install the InfluxData 1.x TICK stack (OSS) list_title: TICK stack (OSS) description: Install and configure the open source InfluxData 1.x TICK stack – Telegraf, InfluxDB, Chronograf, and Kapacitor. -alias: /platform/installation/oss-install +aliases: + - /platform/installation/oss-install menu: platform: name: TICK stack (OSS) diff --git a/content/shared/README.md b/content/shared/README.md new file mode 100644 index 000000000..232c6a7fc --- /dev/null +++ b/content/shared/README.md @@ -0,0 +1,25 @@ +# Shared content + +This section is for content shared across multiple products and versions. +The `/shared/_index.md` frontmatter, marks the `/shared` directory and its +children as draft so they +don't get rendered when the site is built, but the contents of each shared +documented is included in pages that use the file as a `source` in their +frontmatter. + +## Use shared content + +1. Create a new folder for the content in the `content/shared/` directory. +2. Copy the markdown files into the new folder. +3. Remove the frontmatter from the markdown files in the shared directory. If the first line starts with a shortcode, add an HTML comment before the first line, otherwise hugo will err. +4. In each of the files that use the shared content, add a source to the frontmatter that points to the shared markdown file—for example: + + ```markdown + source: /shared/influxql-v3-reference/regular-expressions.md + ``` + +5. In the doc body, remove the shared Markdown text and add a comment that points to the shared file, in case someone happens upon the page in the repo--for example, in `/content/3/core/reference/influxql/regular-expressions.md`, add the following: + + diff --git a/content/shared/_index.md b/content/shared/_index.md new file mode 100644 index 000000000..c5c894fad --- /dev/null +++ b/content/shared/_index.md @@ -0,0 +1,14 @@ +--- +title: Shared pages +cascade: + draft: true +--- + +This section is for content shared across multiple products and versions. +The `/shared` directory and all of its children are marked as draft so they +don't get rendered when the site is built, but the contents of each shared +documented is included in pages that use the file as a `source` in their +frontmatter. + +See the `/shared/README.md` for instructions on creating and using shared content. + diff --git a/content/shared/influxql-v3-reference/_index.md b/content/shared/influxql-v3-reference/_index.md new file mode 100644 index 000000000..cb9cf4b35 --- /dev/null +++ b/content/shared/influxql-v3-reference/_index.md @@ -0,0 +1,769 @@ +InfluxQL (Influx Query Language) is an SQL-like query language used to interact +with InfluxDB and work with times series data. + +> [!Important] +> #### InfluxQL feature support +> +> InfluxQL is being rearchitected to work with the InfluxDB v3 storage engine. +> This process is ongoing and some InfluxQL features are still being implemented. +> For information about the current implementation status of InfluxQL features, +> see [InfluxQL feature support](/influxdb/version/reference/influxql/feature-support/). + +- [Notation](#notation) +- [Query representation](#query-representation) + - [Characters](#characters) + - [Letters and digits](#letters-and-digits) + - [Identifiers](#identifiers) + - [Keywords](#keywords) + - [Literals](#literals) +- [Queries](#queries) +- [Statements](#statements) +- [Clauses](#clauses) +- [Expressions](#expressions) +- [Comments](#comments) +- [Other](#other) +- [Result set](#result-set) + + + +## Notation + +The syntax is specified using Extended Backus-Naur Form ("EBNF"). +EBNF is the same notation used in the [Go programming language specification](https://golang.org/ref/spec). + +```go +Production = production_name "=" [ Expression ] "." . +Expression = Alternative { "|" Alternative } . +Alternative = Term { Term } . +Term = production_name | token [ "…" token ] | Group | Option | Repetition . +Group = "(" Expression ")" . +Option = "[" Expression "]" . +Repetition = "{" Expression "}" . +``` + +Notation operators in order of increasing precedence: + +``` +| alternation +() grouping +[] option (0 or 1 times) +{} repetition (0 to n times) +``` + +## Query representation + +### Characters + +InfluxQL is Unicode text encoded in [UTF-8](http://en.wikipedia.org/wiki/UTF-8). + +``` +newline = /* the Unicode code point U+000A */ . +unicode_char = /* an arbitrary Unicode code point except newline */ . +``` + +### Letters and digits + +Letters are the set of ASCII letters and the underscore (`_`, U+005F). + +Only decimal digits are supported. + +``` +letter = ascii_letter | "_" . +ascii_letter = "A" … "Z" | "a" … "z" . +digit = "0" … "9" . +``` + +### Identifiers + +Identifiers are tokens that refer to +[database](/influxdb/version/reference/glossary/#database) names, +[retention policy](/influxdb/version/reference/glossary/#retention-policy-rp) names, +[measurement](/influxdb/version/reference/glossary/#measurement) names, +[tag keys](/influxdb/version/reference/glossary/#tag-key), and +[field keys](/influxdb/version/reference/glossary/#field-key). + +The rules are as follows: + +- Double-quoted identifiers can contain any Unicode character except for a new line. +- Double-quoted identifiers can also contain escaped `"` characters (that is, `\"`) +- Double-quoted identifiers can include InfluxQL [keywords](#keywords). +- Unquoted identifiers must start with an upper or lowercase ASCII character or "_". +- Unquoted identifiers may contain only ASCII letters, decimal digits, and "_". + +``` +identifier = unquoted_identifier | quoted_identifier . +unquoted_identifier = ( letter ) { letter | digit } . +quoted_identifier = `"` unicode_char { unicode_char } `"` . +``` + +#### Examples + +``` +cpu +_cpu_stats +"1h" +"anything really" +"1_Crazy-1337.identifier>NAME👍" +``` + +### Keywords + +``` +ALL ALTER ANY AS ASC BEGIN +BY CREATE CONTINUOUS DATABASE DATABASES DEFAULT +DELETE DESC DESTINATIONS DIAGNOSTICS DISTINCT DROP +DURATION END EVERY EXPLAIN FIELD FOR +FROM GRANT GRANTS GROUP GROUPS IN +INF INSERT INTO KEY KEYS KILL +LIMIT SHOW MEASUREMENT MEASUREMENTS NAME OFFSET +ON ORDER PASSWORD POLICY POLICIES PRIVILEGES +QUERIES QUERY READ REPLICATION RESAMPLE RETENTION +REVOKE SELECT SERIES SET SHARD SHARDS +SLIMIT SOFFSET STATS SUBSCRIPTION SUBSCRIPTIONS TAG +TO USER USERS VALUES WHERE WITH +WRITE +``` + +If you use an InfluxQL keyword as an +[identifier](/influxdb/version/reference/glossary/#identifier), +double-quote the identifier in every query. + +The `time` keyword is a special case. +`time` can be a +database name, +[measurement](/influxdb/version/reference/glossary/#measurement) name, +[retention policy](/influxdb/version/reference/glossary/#retention-policy-rp) name, and +[user](/influxdb/version/reference/glossary/#user) name. + +In those cases, you don't need to double-quote `time` in queries. + +`time` can't be a [field key](/influxdb/version/reference/glossary/#field-key) or +[tag key](/influxdb/version/reference/glossary/#tag-key); +InfluxDB rejects writes with `time` as a field key or tag key and returns an error. + + +### Literals + +#### Integers + +InfluxQL supports decimal integer literals. +Hexadecimal and octal literals aren't currently supported. + +``` +int_lit = ( "1" … "9" ) { digit } . +``` + +#### Floats + +InfluxQL supports floating-point literals. +Exponents aren't currently supported. + +``` +float_lit = int_lit "." int_lit . +``` + +#### Strings + +String literals must be surrounded by single quotes. +Strings may contain `'` characters as long as they are escaped (that is, , `\'`) + +``` +string_lit = `'` { unicode_char } `'` . +``` + +#### Durations + +Duration literals specify a length of time. +An integer literal followed immediately (with no spaces) by one of the duration units listed below is interpreted as a duration literal. +Durations can be specified with mixed units. + +##### Duration units + +| Units | Meaning | +| ------ | --------------------------------------- | +| ns | nanoseconds (1 billionth of a second) | +| u or µ | microseconds (1 millionth of a second) | +| ms | milliseconds (1 thousandth of a second) | +| s | second | +| m | minute | +| h | hour | +| d | day | +| w | week | + +``` +duration_lit = int_lit duration_unit . +duration_unit = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" . +``` + +#### Dates & Times + +Unlike other notations used in InfluxQL, the date and time literal format isn't specified by EBNF. +InfluxQL date and time is specified using Go's time parsing format and +[reference date](https://pkg.go.dev/time#pkg-constants) written in the format required by InfluxQL. +The reference date time is: + +InfluxQL reference date time: January 2nd, 2006 at 3:04:05 PM + +``` +time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02" . +``` + +#### Booleans + +``` +bool_lit = TRUE | FALSE . +``` + +#### Regular Expressions + +``` +regex_lit = "/" { unicode_char } "/" . +``` + +**Comparators:** +`=~` matches against +`!~` doesn't match against + +> [!Note] +> +> InfluxQL supports using regular expressions when specifying: +> +> - [field keys](/influxdb/version/reference/glossary/#field-key) and [tag keys](/influxdb/version/reference/glossary/> #tag-key) in the [`SELECT` clause](/influxdb/version/reference/influxql/select/) +> - [measurements](/influxdb/version/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/version/reference/> influxql/select/#from-clause) +> - [tag values](/influxdb/version/reference/glossary/#tag-value) and +> string [field values](/influxdb/version/reference/glossary/#field-value) +> in the [`WHERE` clause](/influxdb/version/reference/influxql/where/) +> - [tag keys](/influxdb/version/reference/glossary/#tag-key) in the +> [`GROUP BY` clause](/influxdb/version/reference/influxql/group-by/) +> +> Currently, InfluxQL doesn't support using regular expressions to match non-string +> field values in the `WHERE` clause, [databases](/influxdb/version/reference/glossary/#database), +> and [retention polices](/influxdb/version/reference/glossary/#retention-policy-rp). + +## Queries + +A query is composed of one or more statements separated by a semicolon (`;`). + +``` +query = statement { ";" statement } . + +statement = explain_stmt | + explain_analyze_stmt | + select_stmt | + show_field_keys_stmt | + show_measurements_stmt | + show_retention_policies_stmt | + show_tag_keys_stmt | + show_tag_values_with_key = stmt . +``` + + + +## Statements + +### EXPLAIN + +Parses and plans the query, and then prints a summary of estimated costs. + +Many SQL engines use the `EXPLAIN` statement to show join order, join algorithms, and predicate and expression pushdown. +Since InfluxQL doesn't support joins, the cost of an InfluxQL query is typically a function of the total series accessed, the number of iterator accesses to a TSM file, and the number of TSM blocks that need to be scanned. + +A query plan generated by `EXPLAIN` contains the following elements: + +- expression +- auxiliary fields +- number of shards +- number of series +- cached values +- number of files +- number of blocks +- size of blocks + +``` +explain_stmt = "EXPLAIN" select_stmt . +``` + +#### Example + +```sql +> explain select sum(pointReq) from "_internal"."monitor"."write" group by hostname; +> QUERY PLAN +------ +EXPRESSION: sum(pointReq::integer) +NUMBER OF SHARDS: 2 +NUMBER OF SERIES: 2 +CACHED VALUES: 110 +NUMBER OF FILES: 1 +NUMBER OF BLOCKS: 1 +SIZE OF BLOCKS: 931 +``` + +### EXPLAIN ANALYZE + +Executes the specified `SELECT` statement and returns data about the query performance and storage during runtime, visualized as a tree. Use this statement to analyze query performance and storage, including [execution time](#execution-time) and [planning time](#planning-time), and the [iterator type](#iterator-type) and [cursor type](#cursor-type). + +For example, if you execute the following statement: + +```sql +> explain analyze select mean(usage_steal) from cpu where time >= '2018-02-22T00:00:00Z' and time < '2018-02-22T12:00:00Z' +``` + +The output is similar to the following: + +```sql +EXPLAIN ANALYZE +--------------- +. +└── select + ├── execution_time: 2.25823ms + ├── planning_time: 18.381616ms + ├── total_time: 20.639846ms + └── field_iterators + ├── labels + │ └── statement: SELECT mean(usage_steal::float) FROM telegraf."default".cpu + └── expression + ├── labels + │ └── expr: mean(usage_steal::float) + └── create_iterator + ├── labels + │ ├── measurement: cpu + │ └── shard_id: 608 + ├── cursors_ref: 779 + ├── cursors_aux: 0 + ├── cursors_cond: 0 + ├── float_blocks_decoded: 431 + ├── float_blocks_size_bytes: 1003552 + ├── integer_blocks_decoded: 0 + ├── integer_blocks_size_bytes: 0 + ├── unsigned_blocks_decoded: 0 + ├── unsigned_blocks_size_bytes: 0 + ├── string_blocks_decoded: 0 + ├── string_blocks_size_bytes: 0 + ├── boolean_blocks_decoded: 0 + ├── boolean_blocks_size_bytes: 0 + └── planning_time: 14.805277ms``` +``` + +> [!Note] +> `EXPLAIN ANALYZE` ignores query output, so the cost of serialization to JSON or +> CSV isn't accounted for. + +##### execution_time + +Shows the amount of time the query took to execute, including reading the time series data, performing operations as data flows through iterators, and draining processed data from iterators. Execution time doesn't include the time taken to serialize the output into JSON or other formats. + +##### planning_time + +Shows the amount of time the query took to plan. +Planning a query in InfluxDB requires a number of steps. Depending on the complexity of the query, planning can require more work and consume more CPU and memory resources than executing the query. For example, the number of series keys required to execute a query affects how quickly the query is planned and how much memory the planning requires. + +First, InfluxDB determines the effective time range of the query and selects the shards to access. +Next, for each shard and each measurement, InfluxDB performs the following steps: + +1. Select matching series keys from the index, filtered by tag predicates in the `WHERE` clause. +2. Group filtered series keys into tag sets based on the `GROUP BY` dimensions. +3. Enumerate each tag set and create a cursor and iterator for each series key. +4. Merge iterators and return the merged result to the query executor. + +##### iterator type + +`EXPLAIN ANALYZE` supports the following iterator types: + +- `create_iterator` node represents work done by the local influxd instance──a complex composition of nested iterators combined and merged to produce the final query output. +- (InfluxDB Enterprise only) `remote_iterator` node represents work done on remote machines. + +For more information about iterators, see [Understanding iterators](#understanding-iterators). + +##### cursor type + +`EXPLAIN ANALYZE` distinguishes 3 cursor types. While the cursor types have the same data structures and equal CPU and I/O costs, each cursor type is constructed for a different reason and separated in the final output. Consider the following cursor types when tuning a statement: + +- cursor_ref: Reference cursor created for `SELECT` projections that include a function, such as `last()` or `mean()`. +- cursor_aux: Auxiliary cursor created for simple expression projections (not selectors or an aggregation). For example, `SELECT foo FROM m` or `SELECT foo+bar FROM m`, where `foo` and `bar` are fields. +- cursor_cond: Condition cursor created for fields referenced in a `WHERE` clause. + +For more information about cursors, see [Understanding cursors](#understanding-cursors). + +##### block types + +`EXPLAIN ANALYZE` separates storage block types, and reports the total number of +blocks decoded and their size (in bytes) on disk. The following block types are supported: + +| Type | Description | +| :--------- | :------------------------------------ | +| `float` | 64-bit IEEE-754 floating-point number | +| `integer` | 64-bit signed integer | +| `unsigned` | 64-bit unsigned integer | +| `boolean` | 1-bit, LSB encoded | +| `string` | UTF-8 string | + +### SELECT + +``` +select_stmt = "SELECT" fields from_clause [ where_clause ] + [ group_by_clause ] [ order_by_clause ] [ limit_clause ] + [ offset_clause ] [ slimit_clause ] [ soffset_clause ] [ timezone_clause ] . +``` + +#### Example + +Select from measurements grouped by the day with a timezone + +```sql +SELECT mean("value") FROM "cpu" GROUP BY region, time(1d) fill(0) tz('America/Chicago') +``` + + + + + + + +### SHOW FIELD KEYS + +``` +show_field_keys_stmt = "SHOW FIELD KEYS" [on_clause] [ from_clause ] . +``` + +#### Examples + +```sql +-- show field keys and field value data types from all measurements +SHOW FIELD KEYS + +-- show field keys and field value data types from specified measurement +SHOW FIELD KEYS FROM "cpu" +``` + +### SHOW MEASUREMENTS + +``` +show_measurements_stmt = "SHOW MEASUREMENTS" [on_clause] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . +``` + +#### Examples + +```sql +-- show all measurements +SHOW MEASUREMENTS + +-- show measurements where region tag = 'uswest' AND host tag = 'serverA' +SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' + +-- show measurements that start with 'h2o' +SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ +``` + + + + + + + +### SHOW TAG KEYS + +``` +show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ] + [ limit_clause ] [ offset_clause ] . +``` + +#### Examples + +```sql +-- show all tag keys +SHOW TAG KEYS + +-- show all tag keys from the cpu measurement +SHOW TAG KEYS FROM "cpu" + +-- show all tag keys from the cpu measurement where the region key = 'uswest' +SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' + +-- show all tag keys where the host key = 'serverA' +SHOW TAG KEYS WHERE "host" = 'serverA' +``` + +### SHOW TAG VALUES + +``` +show_tag_values_stmt = "SHOW TAG VALUES" [on_clause] [ from_clause ] with_tag_clause [ where_clause ] + [ limit_clause ] [ offset_clause ] . +``` + +#### Examples + +```sql +-- show all tag values across all measurements for the region tag +SHOW TAG VALUES WITH KEY = "region" + +-- show tag values from the cpu measurement for the region tag +SHOW TAG VALUES FROM "cpu" WITH KEY = "region" + +-- show tag values across all measurements for all tag keys that do not include the letter c +SHOW TAG VALUES WITH KEY !~ /.*c.*/ + +-- show tag values from the cpu measurement for region & host tag keys where service = 'redis' +SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' +``` + + + +## Clauses + +``` +from_clause = "FROM" measurements . + +group_by_clause = "GROUP BY" dimensions fill(fill_option). + +limit_clause = "LIMIT" int_lit . + +offset_clause = "OFFSET" int_lit . + +slimit_clause = "SLIMIT" int_lit . + +soffset_clause = "SOFFSET" int_lit . + +timezone_clause = tz(string_lit) . + +on_clause = "ON" db_name . + +order_by_clause = "ORDER BY" sort_fields . + +where_clause = "WHERE" expr . + +with_measurement_clause = "WITH MEASUREMENT" ( "=" measurement | "=~" regex_lit ) . + +with_tag_clause = "WITH KEY" ( "=" tag_key | "!=" tag_key | "=~" regex_lit | "IN (" tag_keys ")" ) . +``` + +## Expressions + +``` +binary_op = "+" | "-" | "*" | "/" | "%" | "&" | "|" | "^" | "AND" | + "OR" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" . + +expr = unary_expr { binary_op unary_expr } . + +unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit | + float_lit | bool_lit | duration_lit | regex_lit . +``` + +## Default time range + +The default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to _now_. + +## Comments + +Use comments with InfluxQL statements to describe your queries. + +- A single line comment begins with two hyphens (`--`) and ends where InfluxDB detects a line break. + This comment type cannot span several lines. +- A multi-line comment begins with `/*` and ends with `*/`. This comment type can span several lines. + Multi-line comments do not support nested multi-line comments. + +## Other + +``` +alias = "AS" identifier . + +back_ref = ( policy_name ".:MEASUREMENT" ) | + ( db_name "." [ policy_name ] ".:MEASUREMENT" ) . + +db_name = identifier . + +dimension = expr . + +dimensions = dimension { "," dimension } . + +field_key = identifier . + +field = expr [ alias ] . + +fields = field { "," field } . + +fill_option = "null" | "none" | "previous" | int_lit | float_lit | "linear" . + +host = string_lit . + +measurement = measurement_name | + ( policy_name "." measurement_name ) | + ( db_name "." [ policy_name ] "." measurement_name ) . + +measurements = measurement { "," measurement } . + +measurement_name = identifier | regex_lit . + +policy_name = identifier . + +retention_policy = identifier . + +retention_policy_name = "NAME" identifier . + +series_id = int_lit . + +sort_field = field_key [ ASC | DESC ] . + +sort_fields = sort_field { "," sort_field } . + +tag_key = identifier . + +tag_keys = tag_key { "," tag_key } . + +var_ref = measurement . +``` diff --git a/content/shared/influxql-v3-reference/feature-support.md b/content/shared/influxql-v3-reference/feature-support.md new file mode 100644 index 000000000..3d6d5f48b --- /dev/null +++ b/content/shared/influxql-v3-reference/feature-support.md @@ -0,0 +1,158 @@ +InfluxQL is being rearchitected to work with the InfluxDB v3 storage engine. +This process is ongoing and some InfluxQL features are still being implemented. +This page provides information about the current implementation status of +InfluxQL features. + +- [In-progress features](#in-progress-features) + - [SLIMIT clause](#slimit-clause) + - [SOFFSET clause](#soffset-clause) + - [Metaqueries](#metaqueries) +- [Function support](#function-support) + - [Aggregate functions](#aggregate-functions) + - [Selector functions](#selector-functions) + - [Transformations](#transformations) + - [Technical and predictive analysis](#technical-and-predictive-analysis) + +## In-progress features + +### SLIMIT clause + +InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause, +which limits the number of [series](/influxdb/version/reference/glossary/#series) +returned in query results. + + + +### SOFFSET clause + +InfluxQL in {{< product-name >}} does not currently support the `SOFFSET` clause, +which specifies the number of [series](/influxdb/version/reference/glossary/#series) +to skip before returning results. + + + +### Metaqueries + +InfluxQL metaqueries return information about the schema of time series data +stored in InfluxDB. +The following table provides information about what metaqueries are available in +{{< product-name >}}: + +| Metaquery | Supported | +| :------------------------------------------------------------ | :----------------------: | +| SHOW DATABASES | | +| **SHOW RETENTION POLICIES** | **{{< icon "check" >}}** | +| **SHOW MEASUREMENTS** | **{{< icon "check" >}}** | +| SHOW SERIES | | +| SHOW SERIES CARDINALITY | | +| **SHOW TAG KEYS** | **{{< icon "check" >}}** | +| SHOW TAG KEY CARDINALITY | | +| **SHOW TAG VALUES** | **{{< icon "check" >}}** | +| SHOW TAG VALUES CARDINALITY | | +| **SHOW FIELD KEYS** | **{{< icon "check" >}}** | +| SHOW FIELD KEYS CARDINALITY | | + +> [!Note] +> +> #### Cardinality metaqueries +> +> With the InfluxDB v3 storage engine, series cardinality is no longer a limiting +> factor for database performance. +> Cardinality-related metaqueries will likely not be supported with the InfluxDB v3 +> storage engine. + +## Function support + +### Aggregate functions + +| Function | Supported | +| :---------------------------------------------------------------------------------------- | :----------------------: | +| [COUNT()](/influxdb/version/reference/influxql/functions/aggregates/#count) | **{{< icon "check" >}}** | +| [DISTINCT()](/influxdb/version/reference/influxql/functions/aggregates/#distinct) | **{{< icon "check" >}}** | +| INTEGRAL() | | +| [MEAN()](/influxdb/version/reference/influxql/functions/aggregates/#mean) | **{{< icon "check" >}}** | +| [MEDIAN()](/influxdb/version/reference/influxql/functions/aggregates/#median) | **{{< icon "check" >}}** | +| [MODE()](/influxdb/version/reference/influxql/functions/aggregates/#mode) | **{{< icon "check" >}}** | +| [SPREAD()](/influxdb/version/reference/influxql/functions/aggregates/#spread) | **{{< icon "check" >}}** | +| [STDDEV()](/influxdb/version/reference/influxql/functions/aggregates/#stddev) | **{{< icon "check" >}}** | +| [SUM()](/influxdb/version/reference/influxql/functions/aggregates/#sum) | **{{< icon "check" >}}** | + + + +### Selector functions + +| Function | Supported | +| :------------------------------------------------------------------------------------------- | :----------------------: | +| [BOTTOM()](/influxdb/version/reference/influxql/functions/selectors/#bottom) | **{{< icon "check" >}}** | +| [FIRST()](/influxdb/version/reference/influxql/functions/selectors/#first) | **{{< icon "check" >}}** | +| [LAST()](/influxdb/version/reference/influxql/functions/selectors/#last) | **{{< icon "check" >}}** | +| [MAX()](/influxdb/version/reference/influxql/functions/selectors/#max) | **{{< icon "check" >}}** | +| [MIN()](/influxdb/version/reference/influxql/functions/selectors/#min) | **{{< icon "check" >}}** | +| [PERCENTILE()](/influxdb/version/reference/influxql/functions/selectors/#percentile) | **{{< icon "check" >}}** | +| SAMPLE() | | +| [TOP()](/influxdb/version/reference/influxql/functions/selectors/#top) | **{{< icon "check" >}}** | + + + +### Transformations + +| Function | Supported | +| :--------------------------------------------------------------------------------------------------------------------------- | :----------------------: | +| [ABS()](/influxdb/version/reference/influxql/functions/transformations/#abs) | **{{< icon "check" >}}** | +| [ACOS()](/influxdb/version/reference/influxql/functions/transformations/#acos) | **{{< icon "check" >}}** | +| [ASIN()](/influxdb/version/reference/influxql/functions/transformations/#asin) | **{{< icon "check" >}}** | +| [ATAN()](/influxdb/version/reference/influxql/functions/transformations/#atan) | **{{< icon "check" >}}** | +| [ATAN2()](/influxdb/version/reference/influxql/functions/transformations/#atan2) | **{{< icon "check" >}}** | +| [CEIL()](/influxdb/version/reference/influxql/functions/transformations/#ceil) | **{{< icon "check" >}}** | +| [COS()](/influxdb/version/reference/influxql/functions/transformations/#cos) | **{{< icon "check" >}}** | +| [CUMULATIVE_SUM()](/influxdb/version/reference/influxql/functions/transformations/#cumulative_sum) | **{{< icon "check" >}}** | +| [DERIVATIVE()](/influxdb/version/reference/influxql/functions/transformations/#derivative) | **{{< icon "check" >}}** | +| [DIFFERENCE()](/influxdb/version/reference/influxql/functions/transformations/#difference) | **{{< icon "check" >}}** | +| [ELAPSED()](/influxdb/version/reference/influxql/functions/transformations/#elapsed) | **{{< icon "check" >}}** | +| [EXP()](/influxdb/version/reference/influxql/functions/transformations/#exp) | **{{< icon "check" >}}** | +| [FLOOR()](/influxdb/version/reference/influxql/functions/transformations/#floor) | **{{< icon "check" >}}** | +| [LN()](/influxdb/version/reference/influxql/functions/transformations/#ln) | **{{< icon "check" >}}** | +| [LOG()](/influxdb/version/reference/influxql/functions/transformations/#log) | **{{< icon "check" >}}** | +| [LOG2()](/influxdb/version/reference/influxql/functions/transformations/#log2) | **{{< icon "check" >}}** | +| [LOG10()](/influxdb/version/reference/influxql/functions/transformations/#log10) | **{{< icon "check" >}}** | +| [MOVING_AVERAGE()](/influxdb/version/reference/influxql/functions/transformations/#moving_average) | **{{< icon "check" >}}** | +| [NON_NEGATIVE_DERIVATIVE()](/influxdb/version/reference/influxql/functions/transformations/#non_negative_derivative) | **{{< icon "check" >}}** | +| [NON_NEGATIVE_DIFFERENCE()](/influxdb/version/reference/influxql/functions/transformations/#non_negative_difference) | **{{< icon "check" >}}** | +| [POW()](/influxdb/version/reference/influxql/functions/transformations/#pow) | **{{< icon "check" >}}** | +| [ROUND()](/influxdb/version/reference/influxql/functions/transformations/#round) | **{{< icon "check" >}}** | +| [SIN()](/influxdb/version/reference/influxql/functions/transformations/#sin) | **{{< icon "check" >}}** | +| [SQRT()](/influxdb/version/reference/influxql/functions/transformations/#sqrt) | **{{< icon "check" >}}** | +| [TAN()](/influxdb/version/reference/influxql/functions/transformations/#tan) | **{{< icon "check" >}}** | + +### Technical and predictive analysis + +| Function | Supported | +| :-------------------------------------------------------------------- | :-------: | +| CHANDE_MOMENTUM_OSCILLATOR() | | +| DOUBLE_EXPONENTIAL_MOVING_AVERAGE() | | +| EXPONENTIAL_MOVING_AVERAGE() | | +| HOLT_WINTERS() | | +| HOLT_WINTERS_WITH_FIT() | | +| KAUFMANS_EFFICIENCY_RATIO() | | +| KAUFMANS_ADAPTIVE_MOVING_AVERAGE() | | +| RELATIVE_STRENGTH_INDEX() | | +| TRIPLE_EXPONENTIAL_MOVING_AVERAGE() | | +| TRIPLE_EXPONENTIAL_DERIVATIVE() | | + + + +### Date and time functions + +| Function | Supported | +| :------------------------------------------------------------------------------- | :----------------------: | +| [now()](/influxdb/version/reference/influxql/functions/date-time/#now) | **{{< icon "check" >}}** | +| [time()](/influxdb/version/reference/influxql/functions/date-time/#time) | **{{< icon "check" >}}** | +| [tz()](/influxdb/version/reference/influxql/functions/date-time/#tz) | **{{< icon "check" >}}** | + +### Miscellaneous functions + +| Function | Supported | +| :-------------------------------------------------------------------------- | :----------------------: | +| [fill()](/influxdb/version/reference/influxql/functions/misc/#fill) | **{{< icon "check" >}}** | diff --git a/content/shared/influxql-v3-reference/functions/_index.md b/content/shared/influxql-v3-reference/functions/_index.md new file mode 100644 index 000000000..c0407a364 --- /dev/null +++ b/content/shared/influxql-v3-reference/functions/_index.md @@ -0,0 +1,74 @@ +Use InfluxQL functions to aggregate, select, transform, analyze, and predict data. + +> [!Note] +> +> #### Missing InfluxQL functions +> +> Some InfluxQL functions are in the process of being rearchitected to work with +> the InfluxDB v3 storage engine. If a function you need is not here, check the +> [InfluxQL feature support page](/influxdb/version/reference/influxql/feature-support/#function-support) +> for more information. + +## InfluxQL functions (by type) + +- [Aggregates](/influxdb/version/reference/influxql/functions/aggregates/) + - [COUNT()](/influxdb/version/reference/influxql/functions/aggregates/#count) + - [DISTINCT()](/influxdb/version/reference/influxql/functions/aggregates/#distinct) + - [MEAN()](/influxdb/version/reference/influxql/functions/aggregates/#mean) + - [MEDIAN()](/influxdb/version/reference/influxql/functions/aggregates/#median) + - [MODE()](/influxdb/version/reference/influxql/functions/aggregates/#mode) + - [SPREAD()](/influxdb/version/reference/influxql/functions/aggregates/#spread) + - [STDDEV()](/influxdb/version/reference/influxql/functions/aggregates/#stddev) + - [SUM()](/influxdb/version/reference/influxql/functions/aggregates/#sum) + +- [Selectors](/influxdb/version/reference/influxql/functions/selectors/) + - [BOTTOM()](/influxdb/version/reference/influxql/functions/selectors/#bottom) + - [FIRST()](/influxdb/version/reference/influxql/functions/selectors/#first) + - [LAST()](/influxdb/version/reference/influxql/functions/selectors/#last) + - [MAX()](/influxdb/version/reference/influxql/functions/selectors/#max) + - [MIN()](/influxdb/version/reference/influxql/functions/selectors/#min) + - [PERCENTILE()](/influxdb/version/reference/influxql/functions/selectors/#percentile) + - [TOP()](/influxdb/version/reference/influxql/functions/selectors/#top) + +- [Transformations](/influxdb/version/reference/influxql/functions/transformations/) + - [ABS()](/influxdb/version/reference/influxql/functions/transformations/#abs) + - [ACOS()](/influxdb/version/reference/influxql/functions/transformations/#acos) + - [ASIN()](/influxdb/version/reference/influxql/functions/transformations/#asin) + - [ATAN()](/influxdb/version/reference/influxql/functions/transformations/#atan) + - [ATAN2()](/influxdb/version/reference/influxql/functions/transformations/#atan2) + - [CEIL()](/influxdb/version/reference/influxql/functions/transformations/#ceil) + - [COS()](/influxdb/version/reference/influxql/functions/transformations/#cos) + - [CUMULATIVE_SUM()](/influxdb/version/reference/influxql/functions/transformations/#cumulative_sum) + - [DERIVATIVE()](/influxdb/version/reference/influxql/functions/transformations/#derivative) + - [DIFFERENCE()](/influxdb/version/reference/influxql/functions/transformations/#difference) + - [EXP()](/influxdb/version/reference/influxql/functions/transformations/#exp) + - [FLOOR()](/influxdb/version/reference/influxql/functions/transformations/#floor) + - [HISTOGRAM()](/influxdb/version/reference/influxql/functions/transformations/#histogram) + - [LN()](/influxdb/version/reference/influxql/functions/transformations/#ln) + - [LOG()](/influxdb/version/reference/influxql/functions/transformations/#log) + - [LOG2()](/influxdb/version/reference/influxql/functions/transformations/#log2) + - [LOG10()](/influxdb/version/reference/influxql/functions/transformations/#log10) + - [MOVING_AVERAGE()](/influxdb/version/reference/influxql/functions/transformations/#moving_average) + - [NON_NEGATIVE_DERIVATIVE()](/influxdb/version/reference/influxql/functions/transformations/#non_negative_derivative) + - [NON_NEGATIVE_DIFFERENCE()](/influxdb/version/reference/influxql/functions/transformations/#non_negative_difference) + - [POW()](/influxdb/version/reference/influxql/functions/transformations/#pow) + - [ROUND()](/influxdb/version/reference/influxql/functions/transformations/#round) + - [SIN()](/influxdb/version/reference/influxql/functions/transformations/#sin) + - [SQRT()](/influxdb/version/reference/influxql/functions/transformations/#sqrt) + - [TAN()](/influxdb/version/reference/influxql/functions/transformations/#tan) + +- [Date and time](/influxdb/version/reference/influxql/functions/date-time/) + - [now()](/influxdb/version/reference/influxql/functions/date-time/#now) + - [time()](/influxdb/version/reference/influxql/functions/date-time/#time) +- [Miscellaneous](/influxdb/version/reference/influxql/functions/misc/) + - [fill()](/influxdb/version/reference/influxql/functions/misc/#fill) + + + + + + + + + + diff --git a/content/shared/influxql-v3-reference/functions/aggregates.md b/content/shared/influxql-v3-reference/functions/aggregates.md new file mode 100644 index 000000000..0895aa0cf --- /dev/null +++ b/content/shared/influxql-v3-reference/functions/aggregates.md @@ -0,0 +1,915 @@ +Use aggregate functions to assess, aggregate, and return values in your data. +Aggregate functions return one row containing the aggregate values from each InfluxQL group. + +_Examples use the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +- [COUNT()](#count) +- [DISTINCT()](#distinct) +- [MEAN()](#mean) +- [MEDIAN()](#median) +- [MODE()](#mode) +- [SPREAD()](#spread) +- [STDDEV()](#stddev) +- [SUM()](#sum) + + + + +> [!Important] +> #### Missing InfluxQL functions +> +> Some InfluxQL functions are in the process of being rearchitected to work with +> the InfluxDB v3 storage engine. If a function you need is not here, check the +> [InfluxQL feature support page](/influxdb/version/reference/influxql/feature-support/#function-support) +> for more information. + +## COUNT() + +Returns the number of non-null [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +COUNT(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports all field types. + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Count the number of non-null values in a field" %}} + +```sql +SELECT COUNT(temp) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | ----: | +| 1970-01-01T00:00:00Z | 26 | + +{{% /expand %}} + +{{% expand "Count the number of non-null values in each field" %}} + +```sql +SELECT COUNT(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | count_co | count_hum | count_temp | +| :------------------- | -------: | --------: | ---------: | +| 1970-01-01T00:00:00Z | 26 | 26 | 26 | + +{{% /expand %}} + +{{% expand "Count the number of non-null values in fields where the field key matches a regular expression" %}} + +```sql +SELECT COUNT(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | count_hum | count_temp | +| :------------------- | --------: | ---------: | +| 1970-01-01T00:00:00Z | 26 | 26 | + +{{% /expand %}} + +{{% expand "Count distinct values for a field" %}} + +InfluxQL supports nesting [`DISTINCT()`](#distinct) in `COUNT()`. + +```sql +SELECT COUNT(DISTINCT(co)) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | ----: | +| 1970-01-01T00:00:00Z | 12 | + +{{% /expand %}} + +{{% expand "Count the number of non-null field values within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + COUNT(temp) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | ----: | +| 2022-01-01T06:00:00Z | 4 | +| 2022-01-01T12:00:00Z | 6 | +| 2022-01-01T18:00:00Z | 3 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## DISTINCT() + +Returns the list of unique [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +DISTINCT(field_key) +``` + +#### Arguments + +- **field_key**: Field key to return distinct values from. + Supports all field types. + +#### Notable behaviors + +- InfluxQL supports nesting `DISTINCT()` with [`COUNT()`](#count-distinct-values-for-a-field). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "List the distinct field values" %}} + +```sql +SELECT DISTINCT(co) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | distinct | +| :------------------- | -------: | +| 1970-01-01T00:00:00Z | 0 | +| 1970-01-01T00:00:00Z | 1 | +| 1970-01-01T00:00:00Z | 3 | +| 1970-01-01T00:00:00Z | 4 | +| 1970-01-01T00:00:00Z | 7 | +| 1970-01-01T00:00:00Z | 5 | +| 1970-01-01T00:00:00Z | 9 | +| 1970-01-01T00:00:00Z | 18 | +| 1970-01-01T00:00:00Z | 14 | +| 1970-01-01T00:00:00Z | 22 | +| 1970-01-01T00:00:00Z | 17 | +| 1970-01-01T00:00:00Z | 26 | + +{{% /expand %}} +{{< /expand-wrapper >}} + + + +## MEAN() + +Returns the arithmetic mean (average) of [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +MEAN(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Calculate the mean value of a field" %}} + +```sql +SELECT MEAN(temp) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 22.396153846153844 | + +{{% /expand %}} + +{{% expand "Calculate the mean value of each field" %}} + +```sql +SELECT MEAN(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | mean_co | mean_hum | mean_temp | +| :------------------- | ----------------: | -------: | -----------------: | +| 1970-01-01T00:00:00Z | 5.269230769230769 | 36.15 | 22.396153846153844 | + +{{% /expand %}} + +{{% expand "Calculate the mean value of fields where the field key matches a regular expression" %}} + +```sql +SELECT MEAN(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | mean_hum | mean_temp | +| :------------------- | -------: | -----------------: | +| 1970-01-01T00:00:00Z | 36.15 | 22.396153846153844 | + +{{% /expand %}} + +{{% expand "Calculate the mean value of a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + MEAN(temp) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 2022-01-01T06:00:00Z | 22.275 | +| 2022-01-01T12:00:00Z | 22.649999999999995 | +| 2022-01-01T18:00:00Z | 23.033333333333335 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## MEDIAN() + +Returns the middle value from a sorted list of [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +MEDIAN(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. + +#### Notable behaviors + +- `MEDIAN()` is nearly equivalent to + [`PERCENTILE(field_key, 50)`](/influxdb/version/reference/influxql/functions/selectors/#percentile), + except `MEDIAN()` returns the average of the two middle field values if the + field contains an even number of values. + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Calculate the median value of a field" %}} + +```sql +SELECT MEDIAN(temp) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | median | +| :------------------- | -----: | +| 1970-01-01T00:00:00Z | 22.45 | + +{{% /expand %}} + +{{% expand "Calculate the median value of each field" %}} + +```sql +SELECT MEDIAN(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | median_co | median_hum | median_temp | +| :------------------- | --------: | ---------: | ----------: | +| 1970-01-01T00:00:00Z | 1 | 36.05 | 22.45 | + +{{% /expand %}} + +{{% expand "Calculate the median value of fields where the field key matches a regular expression" %}} + + +```sql +SELECT MEDIAN(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | median_hum | median_temp | +| :------------------- | ---------: | ----------: | +| 1970-01-01T00:00:00Z | 36.05 | 22.45 | + +{{% /expand %}} + +{{% expand "Calculate the median value of a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + MEDIAN(temp) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | median | +| :------------------- | -----------------: | +| 2022-01-01T06:00:00Z | 22.549999999999997 | +| 2022-01-01T12:00:00Z | 22.7 | +| 2022-01-01T18:00:00Z | 23.1 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## MODE() + +Returns the most frequent value in a list of +[field values](/influxdb/version/reference/glossary/#field-value). + +```sql +MODE(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports all field types. + +#### Notable behaviors + +- `MODE()` returns the field value with the earliest + [timestamp](/influxdb/version/reference/glossary/#timestamp) + if there's a tie between two or more values for the maximum number of occurrences. + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the mode value of a field" %}} + +```sql +SELECT MODE(co) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | mode | +| :------------------- | ---: | +| 1970-01-01T00:00:00Z | 0 | + +{{% /expand %}} + +{{% expand "Calculate the mode value of each field" %}} + +```sql +SELECT MODE(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | mode_co | mode_hum | mode_temp | +| :------------------- | ------: | -------: | --------: | +| 1970-01-01T00:00:00Z | 0 | 36 | 22.7 | + +{{% /expand %}} + +{{% expand "Calculate the mode of field keys that match a regular expression" %}} + +```sql +SELECT MODE(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | mode_hum | mode_temp | +| :------------------- | -------: | --------: | +| 1970-01-01T00:00:00Z | 36 | 22.7 | + +{{% /expand %}} + +{{% expand "Calculate the mode a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + MODE(co) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | mode | +| :------------------- | ---: | +| 2022-01-01T06:00:00Z | 0 | +| 2022-01-01T12:00:00Z | 1 | +| 2022-01-01T18:00:00Z | 18 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## SPREAD() + +Returns the difference between the minimum and maximum +[field values](/influxdb/version/reference/glossary/#field-value). + +```sql +SPREAD(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the spread of a field" %}} + +```sql +SELECT SPREAD(temp) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | spread | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 2.3000000000000007 | + +{{% /expand %}} + +{{% expand "Calculate the spread of each field" %}} + +```sql +SELECT SPREAD(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | spread_co | spread_hum | spread_temp | +| :------------------- | --------: | ---------: | -----------------: | +| 1970-01-01T00:00:00Z | 26 | 1 | 2.3000000000000007 | + +{{% /expand %}} + +{{% expand "Calculate the spread of field keys that match a regular expression" %}} + +```sql +SELECT SPREAD(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | spread_hum | spread_temp | +| :------------------- | ---------: | -----------------: | +| 1970-01-01T00:00:00Z | 1 | 2.3000000000000007 | + +{{% /expand %}} + +{{% expand "Calculate the spread of a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + SPREAD(co) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | spread | +| :------------------- | -----: | +| 2022-01-01T06:00:00Z | 0 | +| 2022-01-01T12:00:00Z | 9 | +| 2022-01-01T18:00:00Z | 8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## STDDEV() + +Returns the standard deviation of [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +STDDEV(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Calculate the standard deviation of a field" %}} + +```sql +SELECT STDDEV(temp) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | stddev | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 0.5553238833191091 | + +{{% /expand %}} + +{{% expand "Calculate the standard deviation of each field" %}} + +```sql +SELECT STDDEV(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | stddev_co | stddev_hum | stddev_temp | +| :------------------- | ----------------: | ------------------: | -----------------: | +| 1970-01-01T00:00:00Z | 7.774613519951676 | 0.25495097567963926 | 0.5553238833191091 | + +{{% /expand %}} + +{{% expand "Calculate the standard deviation of fields where the field key matches a regular expression" %}} + +```sql +SELECT STDDEV(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | stddev_hum | stddev_temp | +| :------------------- | ------------------: | -----------------: | +| 1970-01-01T00:00:00Z | 0.25495097567963926 | 0.5553238833191091 | + +{{% /expand %}} + +{{% expand "Calculate the standard deviation of a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + STDDEV(co) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | stddev | +| :------------------- | -----------------: | +| 2022-01-01T06:00:00Z | 0 | +| 2022-01-01T12:00:00Z | 3.6742346141747673 | +| 2022-01-01T18:00:00Z | 4 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## SUM() + +Returns the sum of [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +SUM(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Calculate the sum of values in a field" %}} + +```sql +SELECT SUM(co) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | sum | +| :------------------- | --: | +| 1970-01-01T00:00:00Z | 137 | + +{{% /expand %}} + +{{% expand "Calculate the sum of values in each field" %}} + +```sql +SELECT SUM(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | sum_co | sum_hum | sum_temp | +| :------------------- | -----: | ------: | -------: | +| 1970-01-01T00:00:00Z | 137 | 939.9 | 582.3 | + +{{% /expand %}} + +{{% expand "Calculate the sum of values for fields where the field key matches a regular expression" %}} + +```sql +SELECT SUM(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | sum_hum | sum_temp | +| :------------------- | ------: | -------: | +| 1970-01-01T00:00:00Z | 939.9 | 582.3 | + +{{% /expand %}} + +{{% expand "Calculate the sum of values in a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + SUM(co) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | sum | +| :------------------- | --: | +| 2022-01-01T06:00:00Z | 0 | +| 2022-01-01T12:00:00Z | 21 | +| 2022-01-01T18:00:00Z | 66 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/functions/date-time.md b/content/shared/influxql-v3-reference/functions/date-time.md new file mode 100644 index 000000000..2647bdb5f --- /dev/null +++ b/content/shared/influxql-v3-reference/functions/date-time.md @@ -0,0 +1,133 @@ +Use InfluxQL date and time functions to perform time-related operations. + +- [now()](#now) +- [time()](#time) +- [tz()](#tz) + +## now() + +Returns the current system time (UTC). +_Supported only in the [`WHERE` clause](/influxdb/version/reference/influxql/where/)._ + +```sql +now() +``` + +## time() + +Used in the [`GROUP BY` clause](/influxdb/version/reference/influxql/group-by/) +to group data into time-based intervals, also known as "windows", using the specified interval. +Timestamps in the `time` column are updated to the start boundary of the window +they're in and grouped by `time`. +Windows use preset round-number boundaries based on the specified interval that +are independent of time conditions in the +[`WHERE` clause](/influxdb/version/reference/influxql/where/). + +This operation can be used to do the following: + +- Downsample data by aggregating multiple points in each window into a single + point per window. +- Normalize irregular time series data to occur at regular intervals. + +_Supported only in the [`GROUP BY` clause](/influxdb/version/reference/influxql/group-by/)._ + +```sql +time(interval[, offset]) +``` + +#### Arguments + +- **interval**: Duration literal that specifies the window interval. +- **offset**: Duration literal that shifts preset time boundaries forward or backward. + Can be positive or negative. _Default is `0s`._ + +##### Examples {#time-examples} + +{{< expand-wrapper >}} + +{{% expand "Downsample data into time-based intervals" %}} + +The following example uses the +[Bitcoin price sample dataset](/influxdb/version/reference/sample-data/#bitcoin-price-data). + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'GBP' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-15T00:00:00Z' +GROUP BY time(2d) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 2023-05-01T00:00:00Z | 23680.120447159094 | +| 2023-05-03T00:00:00Z | 24048.71484033149 | +| 2023-05-05T00:00:00Z | 24461.9194901099 | +| 2023-05-07T00:00:00Z | 23796.43801933702 | +| 2023-05-09T00:00:00Z | 23118.709889285707 | +| 2023-05-11T00:00:00Z | 22465.008364444446 | +| 2023-05-13T00:00:00Z | 22499.464763186803 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## tz() + +Applies a timezone offset to timestamps in query results. +Offsets include any seasonal offset such as Daylight Savings Time (DST) or +British Summer Time (BST). +_Supported only in the [time zone clause](/influxdb/version/reference/influxql/time-and-timezone/#time-zone-clause)._ + +```sql +tz(time_zone) +``` + +#### Arguments + +- **time_zone**: Timezone string literal to adjust times to. + Uses timezone names defined in the + [Internet Assigned Numbers Authority time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). + +#### Examples {#tz-examples} + +{{< expand-wrapper >}} + +{{% expand "Return the UTC offset for Chicago's time zone" %}} + +The following example uses the +[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +tz('America/Chicago') +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------------ | --: | ---: | :------ | ---: | +| 2022-01-01T02:00:00-06:00 | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T03:00:00-06:00 | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T04:00:00-06:00 | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T05:00:00-06:00 | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T06:00:00-06:00 | 0 | 36 | Kitchen | 22.5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/functions/misc.md b/content/shared/influxql-v3-reference/functions/misc.md new file mode 100644 index 000000000..3bb523161 --- /dev/null +++ b/content/shared/influxql-v3-reference/functions/misc.md @@ -0,0 +1,232 @@ +Use InfluxQL miscellaneous functions to perform different operations in +InfluxQL queries. + +- [fill()](#fill) + +## fill() + +Fills _null_ field values returned from empty time windows in `GROUP BY time()` +queries with a specified fill value. + +_Supported only in the [`GROUP BY` clause](/influxdb/version/reference/influxql/group-by/)._ + +```sql +fill(behavior) +``` + +#### Arguments + +- **behavior**: Defines the behavior of the fill operation. + If no `FILL` clause is included, the default behavior is `fill(null)`. + + The following options are available: + + - **numeric literal**: Replaces null values with the specified numeric literal. + - **linear**: Uses linear interpolation between existing values to replace null values. + - **none**: Removes rows with null field values. + - **null**: Keeps null values and associated timestamps. + - **previous**: Replaces null values with the most recent non-null value. + +#### Examples {#fill-examples} + +The following example uses the +[Bitcoin price sample dataset](/influxdb/version/reference/sample-data/#bitcoin-price-data). + +{{< tabs-wrapper >}} +{{% tabs "small" %}} +[fill(numeric_literal)](#) +[fill(linear)](#) +[fill(none)](#) +[fill(null)](#) +[fill(previous)](#) +{{% /tabs %}} +{{% tab-content %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-01T02:00:00Z' +GROUP BY + time(30m) + fill(0) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---------: | +| 2023-05-01T00:00:00Z | 29319.9092 | +| 2023-05-01T00:30:00Z | 29307.4416 | +| 2023-05-01T01:00:00Z | 0 | +| 2023-05-01T01:30:00Z | 29263.2886 | + +{{% /tab-content %}} +{{% tab-content %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-01T02:00:00Z' +GROUP BY + time(30m) + fill(linear) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---------: | +| 2023-05-01T00:00:00Z | 29319.9092 | +| 2023-05-01T00:30:00Z | 29307.4416 | +| 2023-05-01T01:00:00Z | 29285.3651 | +| 2023-05-01T01:30:00Z | 29263.2886 | + +{{% /tab-content %}} +{{% tab-content %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-01T02:00:00Z' +GROUP BY + time(30m) + fill(none) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---------: | +| 2023-05-01T00:00:00Z | 29319.9092 | +| 2023-05-01T00:30:00Z | 29307.4416 | +| 2023-05-01T01:30:00Z | 29263.2886 | + +{{% /tab-content %}} +{{% tab-content %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-01T02:00:00Z' +GROUP BY + time(30m) + fill(null) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---------: | +| 2023-05-01T00:00:00Z | 29319.9092 | +| 2023-05-01T00:30:00Z | 29307.4416 | +| 2023-05-01T01:00:00Z | | +| 2023-05-01T01:30:00Z | 29263.2886 | + +{{% /tab-content %}} +{{% tab-content %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-01T02:00:00Z' +GROUP BY + time(30m) + fill(previous) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---------: | +| 2023-05-01T00:00:00Z | 29319.9092 | +| 2023-05-01T00:30:00Z | 29307.4416 | +| 2023-05-01T01:00:00Z | 29307.4416 | +| 2023-05-01T01:30:00Z | 29263.2886 | + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + + + diff --git a/content/shared/influxql-v3-reference/functions/selectors.md b/content/shared/influxql-v3-reference/functions/selectors.md new file mode 100644 index 000000000..ac5bf7bbf --- /dev/null +++ b/content/shared/influxql-v3-reference/functions/selectors.md @@ -0,0 +1,1051 @@ +Use selector functions to assess, select, and return values in your data. +Selector functions return one or more rows with the selected values from each +InfluxQL group. + +_Examples use the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +- [BOTTOM()](#bottom) +- [FIRST()](#first) +- [LAST()](#last) +- [MAX()](#max) +- [MIN()](#min) +- [PERCENTILE()](#percentile) +- [TOP()](#top) +- [Notable behaviors of selector functions](#notable-behaviors-of-selector-functions) + + + +> [!Important] +> #### Missing InfluxQL functions +> +> Some InfluxQL functions are in the process of being rearchitected to work with +> the InfluxDB v3 storage engine. If a function you need is not here, check the +> [InfluxQL feature support page](/influxdb/version/reference/influxql/feature-support/#function-support) +> for more information. + +## BOTTOM() + +Returns the smallest `N` [field values](/influxdb/version/reference/glossary/#field-value). +`BOTTOM()` supports int64 and float64 field value [data types](/influxdb/version/reference/glossary/#field-value). + +```sql +BOTTOM(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) +``` + +> [!Note] +> **Note:** `BOTTOM()` returns the field value with the earliest timestamp if +> there's a tie between two or more values for the smallest value. + +#### Arguments + +- **field_expression**: Expression to identify the field to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key) + or constant. +- **tag_expression**: Expression to identify a tag key to segment by. + Can be a [tag key](/influxdb/version/reference/glossary/#tag-key) + or constant. Comma-delimit multiple tags. +- **N**: Number of results to return from each InfluxQL group or specified tag segment. + +#### Notable behaviors + +- `BOTTOM()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). +- `BOTTOM()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Select the bottom three values of a field" %}} + +```sql +SELECT BOTTOM(temp, 3) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} +{{% influxdb/custom-timestamps %}} + +| time | bottom | +| :------------------- | -----: | +| 2022-01-01T08:00:00Z | 21 | +| 2022-01-01T08:00:00Z | 21.1 | +| 2022-01-01T09:00:00Z | 21.4 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select the bottom field value for two unique tag values" %}} + +```sql +SELECT BOTTOM(temp, room, 2) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} +{{% influxdb/custom-timestamps %}} + +| time | bottom | room | +| :------------------- | -----: | :---------- | +| 2022-01-01T08:00:00Z | 21 | Kitchen | +| 2022-01-01T08:00:00Z | 21.1 | Living Room | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select the bottom three field values and the tag value associated with each" %}} + +```sql +SELECT BOTTOM(temp, 3), room FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} +{{% influxdb/custom-timestamps %}} + +| time | bottom | room | +| :------------------- | -----: | ----------- | +| 2022-01-01T08:00:00Z | 21 | Kitchen | +| 2022-01-01T08:00:00Z | 21.1 | Living Room | +| 2022-01-01T09:00:00Z | 21.4 | Living Room | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select the bottom field values for unique tag values and within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} +```sql +SELECT + BOTTOM(temp, room, 2) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +GROUP BY time(2h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | bottom | room | +| :------------------- | -----: | :---------- | +| 2022-01-01T08:00:00Z | 21 | Kitchen | +| 2022-01-01T08:00:00Z | 21.1 | Living Room | +| 2022-01-01T10:00:00Z | 21.8 | Living Room | +| 2022-01-01T11:00:00Z | 22.4 | Kitchen | +| 2022-01-01T12:00:00Z | 22.2 | Living Room | +| 2022-01-01T12:00:00Z | 22.5 | Kitchen | + +{{% /influxdb/custom-timestamps %}} + +Notice that when grouping by time, `BOTTOM()` +[maintains the point's original timestamp](#timestamps-when-grouping-by-time). + +{{% /expand %}} +{{< /expand-wrapper >}} + +## FIRST() + +Returns the [field value](/influxdb/version/reference/glossary/#field-value) with the oldest timestamp. + +```sql +FIRST(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports all field [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). + +#### Notable behaviors + +- `FIRST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Select the first value for a field" %}} + +```sql +SELECT FIRST(temp) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | first | +| :------------------- | ----: | +| 2022-01-01T08:00:00Z | 21.1 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} + +{{% expand "Select the first value from each field" %}} + +```sql +SELECT FIRST(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | first_co | first_hum | first_temp | +| :------------------- | -------: | --------: | ---------: | +| 1970-01-01T00:00:00Z | 0 | 35.9 | 21.1 | + +{{% /expand %}} + +{{% expand "Select the first value from field keys that match a regular expression" %}} + +```sql +SELECT FIRST(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | first_hum | first_temp | +| :------------------- | --------: | ---------: | +| 1970-01-01T00:00:00Z | 35.9 | 21.1 | + +{{% /expand %}} + +{{% expand "Select the first value from a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + FIRST(temp) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | first | +| :------------------- | ----: | +| 2022-01-01T06:00:00Z | 21 | +| 2022-01-01T12:00:00Z | 22.5 | +| 2022-01-01T18:00:00Z | 23.3 | + +{{% /influxdb/custom-timestamps %}} + +Notice that when grouping by time, `FIRST()` +[overrides the point's original timestamp](#timestamps-when-grouping-by-time). + +{{% /expand %}} +{{< /expand-wrapper >}} + +## LAST() + +Returns the [field value](/influxdb/version/reference/glossary/#field-value) with the most recent timestamp. + +```sql +LAST(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports all field [data types](/influxdb/v2/query-data/influxql/explore-data/select/#data-types). + +#### Notable behaviors + +- `LAST()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time) + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the last value for a field" %}} + +```sql +SELECT LAST(temp) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | last | +| :------------------- | ---: | +| 2022-01-01T20:00:00Z | 22.7 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} + +{{% expand "Select the last value from each field" %}} + +```sql +SELECT LAST(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | last_co | last_hum | last_temp | +| :------------------- | ------: | -------: | --------: | +| 1970-01-01T00:00:00Z | 26 | 36.5 | 22.7 | + +{{% /expand %}} + +{{% expand "Select the last value from field keys that match a regular expression" %}} + +```sql +SELECT LAST(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | last_hum | last_temp | +| :------------------- | -------: | --------: | +| 1970-01-01T00:00:00Z | 36.5 | 22.7 | + +{{% /expand %}} + +{{% expand "Select the last value from a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + LAST(temp) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | last | +| :------------------- | ---: | +| 2022-01-01T06:00:00Z | 22.4 | +| 2022-01-01T12:00:00Z | 22.7 | +| 2022-01-01T18:00:00Z | 22.7 | + +{{% /influxdb/custom-timestamps %}} + +Notice that when grouping by time, `LAST()` +[overrides the point's original timestamp](#timestamps-when-grouping-by-time). + +{{% /expand %}} +{{< /expand-wrapper >}} + +## MAX() + +Returns the greatest [field value](/influxdb/version/reference/glossary/#field-value). + +```sql +MAX(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. + +#### Notable behaviors + +- `MAX()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the maximum value from a field" %}} + +```sql +SELECT MAX(co) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | max | +| :------------------- | --: | +| 2022-01-01T20:00:00Z | 26 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} + +{{% expand "Select the maximum value from each field" %}} + +```sql +SELECT MAX(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | max_co | max_hum | max_temp | +| :------------------- | -----: | ------: | -------: | +| 1970-01-01T00:00:00Z | 26 | 36.9 | 23.3 | + +{{% /expand %}} + +{{% expand "Select the maximum value from field keys that match a regular expression" %}} + +```sql +SELECT MAX(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | max_hum | max_temp | +| :------------------- | ------: | -------: | +| 1970-01-01T00:00:00Z | 36.9 | 23.3 | + +{{% /expand %}} + +{{% expand "Select the maximum value from a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + MAX(temp) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | max | +| :------------------- | ---: | +| 2022-01-01T06:00:00Z | 23 | +| 2022-01-01T12:00:00Z | 22.8 | +| 2022-01-01T18:00:00Z | 23.3 | + +{{% /influxdb/custom-timestamps %}} + +Notice that when grouping by time, `MAX()` +[overrides the point's original timestamp](#timestamps-when-grouping-by-time). + +{{% /expand %}} +{{< /expand-wrapper >}} + +## MIN() + +Returns the lowest [field value](/influxdb/version/reference/glossary/#field-value). + +```sql +MIN(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. + +#### Notable behaviors + +- `MIN()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the minimum value from a field" %}} + +```sql +SELECT MIN(temp) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | min | +| :------------------- | --: | +| 2022-01-01T08:00:00Z | 21 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} + +{{% expand "Select the minimum value from each field" %}} + +```sql +SELECT MIN(*) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | min_co | min_hum | min_temp | +| :------------------- | -----: | ------: | -------: | +| 1970-01-01T00:00:00Z | 0 | 35.9 | 21 | + +{{% /expand %}} + +{{% expand "Select the minimum value from field keys that match a regular expression" %}} + +```sql +SELECT MIN(/^[th]/) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | min_hum | min_temp | +| :------------------- | ------: | -------: | +| 1970-01-01T00:00:00Z | 35.9 | 21 | + +{{% /expand %}} + +{{% expand "Select the minimum value from a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + MIN(temp) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | min | +| :------------------- | ---: | +| 2022-01-01T06:00:00Z | 21 | +| 2022-01-01T12:00:00Z | 22.4 | +| 2022-01-01T18:00:00Z | 22.7 | + +{{% /influxdb/custom-timestamps %}} + +Notice that when grouping by time, `MIN()` +[overrides the point's original timestamp](#timestamps-when-grouping-by-time). + +{{% /expand %}} +{{< /expand-wrapper >}} + +## PERCENTILE() + +Returns the `N`th percentile [field value](/influxdb/version/reference/glossary/#field-value). + +```sql +PERCENTILE(field_expression, N) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. +- **N**: Percentile to return. + Must be an integer or float value **greater than 0 and less than or equal to 100**. + +#### Notable behaviors + +- `PERCENTILE()` [overrides original timestamps when grouping by time](#timestamps-when-grouping-by-time). +- `PERCENTILE(example_field, 100)` is equivalent to [`MAX(example_field)`](#max). +- `PERCENTILE(example_field, 50)` is nearly equivalent to + [`MEDIAN(example_field)`](/influxdb/version/reference/influxql/functions/aggregates/#median), + except `MEDIAN()` returns the average of the two middle values if the field + contains an even number of values. +- `PERCENTILE(example_field, 0)` returns _null_. + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the 50th percentile value from a field" %}} + +```sql +SELECT PERCENTILE(temp, 50) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | percentile | +| :------------------- | ---------: | +| 2022-01-01T11:00:00Z | 22.4 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} + +{{% expand "Select the 50th percentile value from each field" %}} + +```sql +SELECT PERCENTILE(*, 50) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | percentile_co | percentile_hum | percentile_temp | +| :------------------- | ------------: | -------------: | --------------: | +| 1970-01-01T00:00:00Z | 1 | 36 | 22.4 | + +{{% /expand %}} + +{{% expand "Select the 50th percentile value from field keys that match a regular expression" %}} + +```sql +SELECT PERCENTILE(/^[th]/, 50) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | percentile_hum | percentile_temp | +| :------------------- | -------------: | --------------: | +| 1970-01-01T00:00:00Z | 36 | 22.4 | + +{{% /expand %}} + +{{% expand "Select the 50th percentile value from a field within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + PERCENTILE(temp, 50) +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY time(6h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | percentile | +| :------------------- | ---------: | +| 2022-01-01T06:00:00Z | 22.4 | +| 2022-01-01T12:00:00Z | 22.7 | +| 2022-01-01T18:00:00Z | 23.1 | + +{{% /influxdb/custom-timestamps %}} + +Notice that when grouping by time, `PERCENTILE()` +[overrides the point's original timestamp](#timestamps-when-grouping-by-time). + +{{% /expand %}} +{{< /expand-wrapper >}} + + + +## TOP() + +Returns the greatest `N` [field values](/influxdb/version/reference/glossary/#field-value). +`TOP()` supports int64 and float64 field value [data types](/influxdb/version/reference/glossary/#field-value). + +```sql +TOP(field_expression[, tag_expression_1[, ..., tag_expression_n]], N) +``` + +> [!Note] +> **Note:** `TOP()` returns the field value with the earliest timestamp if there's +> a tie between two or more values for the greatest value. + +#### Arguments + +- **field_expression**: Expression to identify the field to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key) + or constant. +- **tag_expression**: Expression to identify a tag key to segment by. + Can be a [tag key](/influxdb/version/reference/glossary/#tag-key) + or constant. Comma-delimit multiple tags. +- **N**: Number of results to return from each InfluxQL group or specified tag segment. + +#### Notable behaviors + +- `TOP()` [maintains original timestamps when grouping by time](#timestamps-when-grouping-by-time). +- `TOP()` [may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Select the top three values of a field" %}} + +```sql +SELECT TOP(temp, 3) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} +{{% influxdb/custom-timestamps %}} + +| time | top | +| :------------------- | ---: | +| 2022-01-01T09:00:00Z | 23 | +| 2022-01-01T18:00:00Z | 23.3 | +| 2022-01-01T19:00:00Z | 23.1 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select the top field value for two unique tag values" %}} + +```sql +SELECT TOP(temp, room, 2) FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} +{{% influxdb/custom-timestamps %}} + +| time | top | room | +| :------------------- | ---: | :---------- | +| 2022-01-01T18:00:00Z | 23.3 | Kitchen | +| 2022-01-01T18:00:00Z | 22.8 | Living Room | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select the top three field values and the tag value associated with each" %}} + +```sql +SELECT TOP(temp, 3), room FROM home +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} +{{% influxdb/custom-timestamps %}} + +| time | top | room | +| :------------------- | ---: | :------ | +| 2022-01-01T09:00:00Z | 23 | Kitchen | +| 2022-01-01T18:00:00Z | 23.3 | Kitchen | +| 2022-01-01T19:00:00Z | 23.1 | Kitchen | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select the top field values for unique tag values and within time windows (grouped by time)" %}} + +{{% influxdb/custom-timestamps %}} +```sql +SELECT + TOP(temp, room, 2) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +GROUP BY time(2h) +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | top | room | +| :------------------- | ---: | :---------- | +| 2022-01-01T09:00:00Z | 23 | Kitchen | +| 2022-01-01T09:00:00Z | 21.4 | Living Room | +| 2022-01-01T10:00:00Z | 22.7 | Kitchen | +| 2022-01-01T11:00:00Z | 22.2 | Living Room | +| 2022-01-01T12:00:00Z | 22.5 | Kitchen | +| 2022-01-01T12:00:00Z | 22.2 | Living Room | + +{{% /influxdb/custom-timestamps %}} + +Notice that when grouping by time, `TOP()` +[maintains the point's original timestamp](#timestamps-when-grouping-by-time). + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Notable behaviors of selector functions + +- [Timestamps when grouping by time](#timestamps-when-grouping-by-time) +- [Selector functions may return fewer points than expected](#selector-functions-may-return-fewer-points-than-expected) + +### Timestamps when grouping by time + +When using selector functions with a `GROUP BY time()` clause, most selector +functions return the timestamp of the starting boundary for each time interval. +However functions with an `N` argument that specifies the number of results to +return per group maintain the original timestamp of each returned point. + +{{< flex >}} +{{% flex-content %}} + +###### Return the start time of each time interval + +- [FIRST()](#first) +- [LAST()](#last) +- [MAX()](#max) +- [MIN()](#min) +- [PERCENTILE()](#percentile) + +{{% /flex-content %}} +{{% flex-content %}} + +###### Maintain the original timestamp + +- [BOTTOM()](#bottom) +- [TOP()](#top) + + +{{% /flex-content %}} +{{< /flex >}} + +### Selector functions may return fewer points than expected + +Queries that use the following selector functions with an `N` argument may +return fewer points than expected. + +- [BOTTOM()](#bottom) +- [TOP()](#top) + + +If the InfluxQL group or specified tag key contains `X` points or unique tag +values and `X` is less than `N`, the function returns `X` results instead of `N` +for each group or tag value. + +{{< expand-wrapper >}} +{{% expand "View example for `FN(field_key, N)`" %}} + +The example below selects the bottom 5 temperatures from the Kitchen between +{{% influxdb/custom-timestamps-span %}}2022-01-01T08:00:00Z{{% /influxdb/custom-timestamps-span %}} +and {{% influxdb/custom-timestamps-span %}}2022-01-01T10:00:00Z{{% /influxdb/custom-timestamps-span %}}. +There are only 3 points recorded for the Kitchen during the queried time range, +so the query returns 3 points instead of 5. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT BOTTOM(temp, 5) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' + AND room = 'Kitchen' +``` + +| time | bottom | +| :------------------- | -----: | +| 2022-01-01T08:00:00Z | 21 | +| 2022-01-01T09:00:00Z | 23 | +| 2022-01-01T10:00:00Z | 22.7 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{% expand "View example for `FN(field_key, tag_key, N)`" %}} + +The example below selects the top temperature from 3 unique values of the `room` tag. +However, the `room` tag only has 2 unique values, so results only contain 2 values. + +```sql +SELECT TOP(temp, room, 3) FROM home +``` + +{{% influxdb/custom-timestamps %}} + +| time | top | room | +| :------------------- | ---: | :---------- | +| 2022-01-01T18:00:00Z | 23.3 | Kitchen | +| 2022-01-01T18:00:00Z | 22.8 | Living Room | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/functions/technical-analysis.md b/content/shared/influxql-v3-reference/functions/technical-analysis.md new file mode 100644 index 000000000..c81d0efbd --- /dev/null +++ b/content/shared/influxql-v3-reference/functions/technical-analysis.md @@ -0,0 +1,1900 @@ +Use technical analysis functions to apply algorithms to your time series data. +Many of these algorithms are often used to analyze financial and investment data, +but have application in other use cases as well. + +- [Predictive analysis](#predictive-analysis): + - [HOLT_WINTERS()](#holt_winters) +- [Technical analysis](#technical-analysis-functions): + - [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) + - [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) + - [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) + - [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) + - [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) + - [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) + - [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) + - [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) + +## Predictive analysis + +Predictive analysis functions are a type of technical analysis algorithms that +predict and forecast future values. + +### HOLT_WINTERS() + +Returns N number of predicted [field values](/influxdb/version/reference/glossary/#field-value) +using the [Holt-Winters](https://www.otexts.org/fpp/7/5) seasonal method. +`HOLT_WINTERS_WITH_FIT()` returns the fitted values in addition to `N` seasonally +adjusted predicted field values. + +Input data points must occur at regular time intervals. +To ensure regular time intervals, `HOLT_WINTERS` requires an aggregate expression +as input and a a `GROUP BY time()` to apply the aggregate operation at regular intervals. + +Use `HOLT_WINTERS()` to: + +- Predict when data values will cross a given threshold +- Compare predicted values with actual values to detect anomalies in your data + +```sql +HOLT_WINTERS[_WITH_FIT](aggregate_expression, N, S) +``` + +#### Arguments {#arguments-holt-winters} + +- **aggregate_expression**: Aggregate operation on a specified expression. + The operation can use any [aggregate function](/influxdb/version/reference/influxql/functions/aggregate/). + The expression can operate on a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports **numeric fields**. +- **N**: Number of values to predict. + Predicted values occur at the same interval specified in the `GROUP BY time()` clause. +- **S**: Seasonal pattern length (number of values per season) to use when + adjusting for seasonal patterns. + To _not_ seasonally adjust predicted values, set `S` to `0` or `1.` + +#### Notable behaviors + +- In some cases, you may receive fewer than `N` predicted points. + This typically occurs when the seasonal adjustment (`S`) is invalid or when + input data is not suited for the Holt Winters algorithm. + +#### Examples + +The following examples use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +{{< expand-wrapper >}} +{{% expand "Use Holt Winters to predict field values with seasonal adjustment" %}} + +```sql +SELECT + HOLT_WINTERS(MEAN(temp_avg), 12, 12) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T00:00:00Z' +GROUP BY time(30d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | holt_winters | +| :------------------- | -----------------: | +| 2023-01-23T00:00:00Z | 52.141810685706844 | +| 2023-02-22T00:00:00Z | 55.41941302100692 | +| 2023-03-24T00:00:00Z | 59.74300473524414 | +| 2023-04-23T00:00:00Z | 59.91932719987093 | +| 2023-05-23T00:00:00Z | 56.03083957191051 | +| 2023-06-22T00:00:00Z | 59.98437978757551 | +| 2023-07-22T00:00:00Z | 60.903170945334175 | +| 2023-08-21T00:00:00Z | 60.75738169893358 | +| 2023-09-20T00:00:00Z | 56.619132830933445 | +| 2023-10-20T00:00:00Z | 56.10559366563841 | +| 2023-11-19T00:00:00Z | 56.248977829575935 | +| 2023-12-19T00:00:00Z | 56.075540144158985 | + +{{% /expand %}} +{{% expand "Use Holt Winters to predict field values with no seasonal adjustment" %}} + +```sql +SELECT + HOLT_WINTERS(MEAN(temp_avg), 12, 0) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T00:00:00Z' +GROUP BY time(30d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | holt_winters | +| :------------------- | ----------------: | +| 2023-01-23T00:00:00Z | 58.55632627159769 | +| 2023-02-22T00:00:00Z | 58.55632627159944 | +| 2023-03-24T00:00:00Z | 58.55632627160024 | +| 2023-04-23T00:00:00Z | 58.55632627160061 | +| 2023-05-23T00:00:00Z | 58.55632627160079 | +| 2023-06-22T00:00:00Z | 58.55632627160087 | +| 2023-07-22T00:00:00Z | 58.5563262716009 | +| 2023-08-21T00:00:00Z | 58.55632627160092 | +| 2023-09-20T00:00:00Z | 58.55632627160093 | +| 2023-10-20T00:00:00Z | 58.55632627160094 | +| 2023-11-19T00:00:00Z | 58.55632627160094 | +| 2023-12-19T00:00:00Z | 58.55632627160094 | + +{{% /expand %}} + +{{% expand "Use Holt Winters to predict field values with fitted values" %}} + +```sql +SELECT + HOLT_WINTERS_WITH_FIT(MEAN(temp_avg), 12, 12) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2021-01-01T00:00:00Z' + AND time <= '2022-12-31T00:00:00Z' +GROUP BY time(30d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | holt_winters_with_fit | +| :------------------- | --------------------: | +| 2020-12-04T00:00:00Z | 50.5 | +| 2021-01-03T00:00:00Z | 53.280924101779426 | +| 2021-02-02T00:00:00Z | 52.099111942046704 | +| 2021-03-04T00:00:00Z | 55.84541855092053 | +| 2021-04-03T00:00:00Z | 60.06803481717513 | +| 2021-05-03T00:00:00Z | 60.414989273392976 | +| 2021-06-02T00:00:00Z | 58.265755948192606 | +| 2021-07-02T00:00:00Z | 63.12426388001118 | +| 2021-08-01T00:00:00Z | 64.34281315294628 | +| 2021-08-31T00:00:00Z | 62.701261106938865 | +| 2021-09-30T00:00:00Z | 58.39095413696881 | +| 2021-10-30T00:00:00Z | 57.571954549171174 | +| 2021-11-29T00:00:00Z | 57.72622091917164 | +| 2021-12-29T00:00:00Z | 56.21981843845102 | +| 2022-01-28T00:00:00Z | 52.592076197024845 | +| 2022-02-27T00:00:00Z | 55.20608671167453 | +| 2022-03-29T00:00:00Z | 59.01290245961656 | +| 2022-04-28T00:00:00Z | 59.10660216049941 | +| 2022-05-28T00:00:00Z | 55.87577637598558 | +| 2022-06-27T00:00:00Z | 59.10005762573857 | +| 2022-07-27T00:00:00Z | 60.04395791516323 | +| 2022-08-26T00:00:00Z | 59.76994469907478 | +| 2022-09-25T00:00:00Z | 56.21467016861341 | +| 2022-10-25T00:00:00Z | 55.76538052914458 | +| 2022-11-24T00:00:00Z | 55.95817013792435 | +| 2022-12-24T00:00:00Z | 55.78474730739332 | +| 2023-01-23T00:00:00Z | 52.33558076070284 | +| 2023-02-22T00:00:00Z | 55.15350456137378 | +| 2023-03-24T00:00:00Z | 58.95292137832944 | +| 2023-04-23T00:00:00Z | 59.15381228655361 | +| 2023-05-23T00:00:00Z | 55.77542228450764 | +| 2023-06-22T00:00:00Z | 59.05797349347727 | +| 2023-07-22T00:00:00Z | 59.87830149275526 | +| 2023-08-21T00:00:00Z | 59.718176562030116 | +| 2023-09-20T00:00:00Z | 56.13817596332756 | +| 2023-10-20T00:00:00Z | 55.626497950276445 | +| 2023-11-19T00:00:00Z | 55.81338302167719 | +| 2023-12-19T00:00:00Z | 55.75008713518608 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Technical analysis functions + +Technical analysis functions apply widely used algorithms to your data. +While they are primarily used in finance and investing, they have +application in other industries. + +- [Notable behaviors of technical analysis functions](#notable-behaviors-of-technical-analysis-functions) +- [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) +- [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) +- [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) +- [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) +- [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) +- [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) +- [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) +- [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) + +### Notable behaviors of technical analysis functions + +#### Must use aggregate or selector functions when grouping by time + +All technical analysis functions support `GROUP BY` clauses that group by tags, +but do not directly support `GROUP BY` clauses that group by time. +To use technical analysis functions with with a `GROUP BY time()` clause, apply +an [aggregate](/influxdb/version/reference/influxql/functions/aggregates/) +or [selector](/influxdb/version/reference/influxql/functions/selectors/) +function to the **field_expression** argument. +The technical analysis function operates on the result of the aggregate or +selector operation. + +--- + +### CHANDE_MOMENTUM_OSCILLATOR() + +The Chande Momentum Oscillator (CMO) is a technical momentum indicator developed by Tushar Chande. +The CMO indicator is created by calculating the difference between the sum of all +recent higher data points and the sum of all recent lower data points, +then dividing the result by the sum of all data movement over a given time period. +The result is multiplied by 100 to give the -100 to +100 range. +{{% cite %}}[Source](https://www.fidelity.com/learning-center/trading-investing/technical-analysis/technical-indicator-guide/cmo){{% /cite %}} + +```sql +CHANDE_MOMENTUM_OSCILLATOR(field_expression, period[, hold_period[, warmup_type]]) +``` + +#### Arguments {#arguments-cmo} + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **period**: Number of values to use as the sample size for the algorithm. + Supports integers greater than or equal to 1. + This also controls the exponential decay rate (α) used to determine the weight + of an historical value. + With a period of `3`, the algorithm uses the current value and the previous + two values. +- **hold_period**: Number of values the algorithm needs before emitting results. + Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. + Must be an integer greater than or equal to `-1`. + + | Warmup type | Default hold_period | + | :---------- | :------------------ | + | exponential | `period` | + | simple | `period` | + | none | `period - 1` | + +- **warmup_type**: Controls how the algorithm initializes the first `period` values. + Supports the following warmup types: + + - **exponential**: _(Default)_ Exponential moving average of the first `period` + values with scaling alpha (α). + When this method is used and `hold_period` is unspecified or -1, the + algorithm may start emitting points after a much smaller sample size than with _simple_. + - **simple**: Simple moving average of the first `period` values. + - **none**: The algorithm does not perform any warmup at all. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to a field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + CHANDE_MOMENTUM_OSCILLATOR(temp, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | chande_momentum_oscillator | +| :------------------- | -------------------------: | +| 2022-01-01T11:00:00Z | 53.84615384615377 | +| 2022-01-01T12:00:00Z | 55.5555555555555 | +| 2022-01-01T13:00:00Z | -19.999999999999858 | +| 2022-01-01T14:00:00Z | 14.285714285714432 | +| 2022-01-01T15:00:00Z | 59.99999999999972 | +| 2022-01-01T16:00:00Z | -14.285714285714432 | +| 2022-01-01T17:00:00Z | -14.285714285714432 | +| 2022-01-01T18:00:00Z | 38.46153846153834 | +| 2022-01-01T19:00:00Z | 28.57142857142868 | +| 2022-01-01T20:00:00Z | 20 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to each field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + CHANDE_MOMENTUM_OSCILLATOR(*, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | chande_momentum_oscillator_co | chande_momentum_oscillator_hum | chande_momentum_oscillator_temp | +| :------------------- | ----------------------------: | -----------------------------: | ------------------------------: | +| 2022-01-01T11:00:00Z | 0 | 20 | 53.84615384615377 | +| 2022-01-01T12:00:00Z | 0 | 20 | 55.5555555555555 | +| 2022-01-01T13:00:00Z | 100 | 42.85714285714228 | -19.999999999999858 | +| 2022-01-01T14:00:00Z | 100 | 24.999999999999332 | 14.285714285714432 | +| 2022-01-01T15:00:00Z | 100 | 25.000000000000444 | 59.99999999999972 | +| 2022-01-01T16:00:00Z | 100 | 0 | -14.285714285714432 | +| 2022-01-01T17:00:00Z | 100 | -100 | -14.285714285714432 | +| 2022-01-01T18:00:00Z | 100 | 50.0000000000003 | 38.46153846153834 | +| 2022-01-01T19:00:00Z | 100 | 28.5714285714285 | 28.57142857142868 | +| 2022-01-01T20:00:00Z | 100 | 38.461538461538545 | 20 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a custom hold period" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + CHANDE_MOMENTUM_OSCILLATOR(temp, 4, 6) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | chande_momentum_oscillator | +| :------------------- | -------------------------: | +| 2022-01-01T14:00:00Z | 14.285714285714432 | +| 2022-01-01T15:00:00Z | 59.99999999999972 | +| 2022-01-01T16:00:00Z | -14.285714285714432 | +| 2022-01-01T17:00:00Z | -14.285714285714432 | +| 2022-01-01T18:00:00Z | 38.46153846153834 | +| 2022-01-01T19:00:00Z | 28.57142857142868 | +| 2022-01-01T20:00:00Z | 20 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a default non-default warmup type" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + CHANDE_MOMENTUM_OSCILLATOR(temp, 4, -1, 'simple') +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | chande_momentum_oscillator | +| :------------------- | -------------------------: | +| 2022-01-01T12:00:00Z | 94.9367088607595 | +| 2022-01-01T13:00:00Z | 95.04132231404957 | +| 2022-01-01T14:00:00Z | 95.04132231404955 | +| 2022-01-01T15:00:00Z | 92.68218929543389 | +| 2022-01-01T16:00:00Z | 83.79002019036625 | +| 2022-01-01T17:00:00Z | 84.72964405398058 | +| 2022-01-01T18:00:00Z | 86.77405015296912 | +| 2022-01-01T19:00:00Z | 76.28466518769179 | +| 2022-01-01T20:00:00Z | 53.322717259176535 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to time windows (grouped by time)" %}} + +The following example use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +```sql +SELECT + CHANDE_MOMENTUM_OSCILLATOR(MEAN(temp_avg), 4) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T23:59:59Z' +GROUP BY time(90d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | chande_momentum_oscillator | +| :------------------- | -------------------------: | +| 2020-07-07T00:00:00Z | 100 | +| 2020-10-05T00:00:00Z | 21.498959056210964 | +| 2021-01-03T00:00:00Z | 2.0072053525475924 | +| 2021-04-03T00:00:00Z | -6.190741773563866 | +| 2021-07-02T00:00:00Z | -8.924485125858132 | +| 2021-09-30T00:00:00Z | 1.2078830260648301 | +| 2021-12-29T00:00:00Z | -5.181655747468743 | +| 2022-03-29T00:00:00Z | -2.3768115942029 | +| 2022-06-27T00:00:00Z | 6.511381683430422 | +| 2022-09-25T00:00:00Z | -7.7487391104997485 | +| 2022-12-24T00:00:00Z | 2.928763268960232 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### DOUBLE_EXPONENTIAL_MOVING_AVERAGE() + +The Double Exponential Moving Average (DEMA) attempts to remove the inherent lag +associated with moving averages by placing more weight on recent values. +The name suggests this is achieved by applying a double exponential smoothing which is not the case. +The value of an [EMA](#exponential_moving_average) is doubled. +To keep the value in line with the actual data and to remove the lag, the value "EMA of EMA" +is subtracted from the previously doubled EMA. +{{% cite %}}[Source](https://en.wikipedia.org/wiki/Double_exponential_moving_average){{% /cite %}} + +```sql +DOUBLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) +``` + +#### Arguments {#arguments-dema} + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **period**: Number of values to use as the sample size for the algorithm. + Supports integers greater than or equal to 1. + This also controls the exponential decay rate (α) used to determine the weight + of an historical value. + With a period of `3`, the algorithm uses the current value and the previous + two values. +- **hold_period**: Number of values the algorithm needs before emitting results. + Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. + Must be an integer greater than or equal to `-1`. + + | Warmup type | Default hold_period | + | :---------- | :------------------ | + | exponential | `period - 1` | + | simple | `(period - 1) × 2` | + +- **warmup_type**: Controls how the algorithm initializes the first `period` values. + Supports the following warmup types: + + - **exponential**: _(Default)_ Exponential moving average of the first `period` + values with scaling alpha (α). + When this method is used and `hold_period` is unspecified or -1, the + algorithm may start emitting points after a much smaller sample size than with _simple_. + - **simple**: Simple moving average of the first `period` values. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | double_exponential_moving_average | +| :------------------- | --------------------------------: | +| 2022-01-01T11:00:00Z | 22.630333333333333 | +| 2022-01-01T12:00:00Z | 22.5854 | +| 2022-01-01T13:00:00Z | 22.747560000000004 | +| 2022-01-01T14:00:00Z | 22.814328 | +| 2022-01-01T15:00:00Z | 22.772071999999998 | +| 2022-01-01T16:00:00Z | 22.55332832 | +| 2022-01-01T17:00:00Z | 22.642048063999997 | +| 2022-01-01T18:00:00Z | 23.0672594816 | +| 2022-01-01T19:00:00Z | 23.12957407488 | +| 2022-01-01T20:00:00Z | 22.89127547648 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + DOUBLE_EXPONENTIAL_MOVING_AVERAGE(*, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | double_exponential_moving_average_co | double_exponential_moving_average_hum | double_exponential_moving_average_temp | +| :------------------- | -----------------------------------: | ------------------------------------: | -------------------------------------: | +| 2022-01-01T11:00:00Z | 0 | 36.056000000000004 | 22.630333333333333 | +| 2022-01-01T12:00:00Z | 0 | 36.019200000000005 | 22.5854 | +| 2022-01-01T13:00:00Z | 0.64 | 36.322880000000005 | 22.747560000000004 | +| 2022-01-01T14:00:00Z | 0.9279999999999999 | 36.332544000000006 | 22.814328 | +| 2022-01-01T15:00:00Z | 2.3232 | 36.266816000000006 | 22.772071999999998 | +| 2022-01-01T16:00:00Z | 5.49376 | 36.104463360000004 | 22.55332832 | +| 2022-01-01T17:00:00Z | 8.15616 | 36.029302272 | 22.642048063999997 | +| 2022-01-01T18:00:00Z | 15.0096384 | 36.573555916800004 | 23.0672594816 | +| 2022-01-01T19:00:00Z | 20.51534848 | 36.62971828224 | 23.12957407488 | +| 2022-01-01T20:00:00Z | 25.294948352 | 36.581181808640004 | 22.89127547648 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | double_exponential_moving_average | +| :------------------- | --------------------------------: | +| 2022-01-01T14:00:00Z | 22.814328 | +| 2022-01-01T15:00:00Z | 22.772071999999998 | +| 2022-01-01T16:00:00Z | 22.55332832 | +| 2022-01-01T17:00:00Z | 22.642048063999997 | +| 2022-01-01T18:00:00Z | 23.0672594816 | +| 2022-01-01T19:00:00Z | 23.12957407488 | +| 2022-01-01T20:00:00Z | 22.89127547648 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + DOUBLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | double_exponential_moving_average | +| :------------------- | --------------------------------: | +| 2022-01-01T14:00:00Z | 22.8312 | +| 2022-01-01T15:00:00Z | 22.792303999999998 | +| 2022-01-01T16:00:00Z | 22.5715328 | +| 2022-01-01T17:00:00Z | 22.65660992 | +| 2022-01-01T18:00:00Z | 23.078180096 | +| 2022-01-01T19:00:00Z | 23.137436544 | +| 2022-01-01T20:00:00Z | 22.89677901824 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} + +The following example use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +```sql +SELECT + DOUBLE_EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T23:59:59Z' +GROUP BY time(90d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | double_exponential_moving_average | +| :------------------- | --------------------------------: | +| 2020-07-07T00:00:00Z | 63.01034259259259 | +| 2020-10-05T00:00:00Z | 59.68671666666667 | +| 2021-01-03T00:00:00Z | 56.266558888888895 | +| 2021-04-03T00:00:00Z | 58.20687488888889 | +| 2021-07-02T00:00:00Z | 61.229622000000006 | +| 2021-09-30T00:00:00Z | 58.78596032888889 | +| 2021-12-29T00:00:00Z | 55.1067106968889 | +| 2022-03-29T00:00:00Z | 57.311773784533344 | +| 2022-06-27T00:00:00Z | 61.66637935722668 | +| 2022-09-25T00:00:00Z | 57.77452777735112 | +| 2022-12-24T00:00:00Z | 55.044203430886405 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### EXPONENTIAL_MOVING_AVERAGE() + +An exponential moving average (EMA) (or exponentially weighted moving average) +is a type of moving average similar to a +[simple moving average](/influxdb/version/reference/influxql/functions/transformations/#moving_average), +except more weight is given to the latest data. + +This type of moving average reacts faster to recent data changes than a simple moving average. +{{% cite %}}[Source](https://www.investopedia.com/terms/e/ema.asp){{% /cite %}} + +```sql +EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) +``` + +#### Arguments {#arguments-ema} + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **period**: Number of values to use as the sample size for the algorithm. + Supports integers greater than or equal to 1. + This also controls the exponential decay rate (α) used to determine the weight + of an historical value. + With a period of `3`, the algorithm uses the current value and the previous + two values. +- **hold_period**: Number of values the algorithm needs before emitting results. + Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. + Must be an integer greater than or equal to `-1`. + + | Warmup type | Default hold_period | + | :---------- | :------------------ | + | exponential | `period - 1` | + | simple | `period - 1` | + +- **warmup_type**: Controls how the algorithm initializes the first `period` values. + Supports the following warmup types: + + - **exponential**: _(Default)_ Exponential moving average of the first `period` + values with scaling alpha (α). + When this method is used and `hold_period` is unspecified or -1, the + algorithm may start emitting points after a much smaller sample size than with _simple_. + - **simple**: Simple moving average of the first `period` values. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to a field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + EXPONENTIAL_MOVING_AVERAGE(temp, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | exponential_moving_average | +| :------------------- | -------------------------: | +| 2022-01-01T11:00:00Z | 22.47 | +| 2022-01-01T12:00:00Z | 22.482 | +| 2022-01-01T13:00:00Z | 22.6092 | +| 2022-01-01T14:00:00Z | 22.68552 | +| 2022-01-01T15:00:00Z | 22.691312 | +| 2022-01-01T16:00:00Z | 22.5747872 | +| 2022-01-01T17:00:00Z | 22.624872319999998 | +| 2022-01-01T18:00:00Z | 22.894923392 | +| 2022-01-01T19:00:00Z | 22.9769540352 | +| 2022-01-01T20:00:00Z | 22.866172421119998 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to each field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + EXPONENTIAL_MOVING_AVERAGE(*, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | exponential_moving_average_co | exponential_moving_average_hum | exponential_moving_average_temp | +| :------------------- | ----------------------------: | -----------------------------: | ------------------------------: | +| 2022-01-01T11:00:00Z | 0 | 36.06 | 22.47 | +| 2022-01-01T12:00:00Z | 0 | 36.036 | 22.482 | +| 2022-01-01T13:00:00Z | 0.4 | 36.2216 | 22.6092 | +| 2022-01-01T14:00:00Z | 0.64 | 36.25296 | 22.68552 | +| 2022-01-01T15:00:00Z | 1.584 | 36.231776 | 22.691312 | +| 2022-01-01T16:00:00Z | 3.7504000000000004 | 36.1390656 | 22.5747872 | +| 2022-01-01T17:00:00Z | 5.85024 | 36.08343936 | 22.624872319999998 | +| 2022-01-01T18:00:00Z | 10.710144 | 36.410063616 | 22.894923392 | +| 2022-01-01T19:00:00Z | 15.2260864 | 36.4860381696 | 22.9769540352 | +| 2022-01-01T20:00:00Z | 19.53565184 | 36.49162290176 | 22.866172421119998 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | exponential_moving_average | +| :------------------- | -------------------------: | +| 2022-01-01T14:00:00Z | 22.68552 | +| 2022-01-01T15:00:00Z | 22.691312 | +| 2022-01-01T16:00:00Z | 22.5747872 | +| 2022-01-01T17:00:00Z | 22.624872319999998 | +| 2022-01-01T18:00:00Z | 22.894923392 | +| 2022-01-01T19:00:00Z | 22.9769540352 | +| 2022-01-01T20:00:00Z | 22.866172421119998 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | exponential_moving_average | +| :------------------- | -------------------------: | +| 2022-01-01T11:00:00Z | 22.275 | +| 2022-01-01T12:00:00Z | 22.365 | +| 2022-01-01T13:00:00Z | 22.538999999999998 | +| 2022-01-01T14:00:00Z | 22.6434 | +| 2022-01-01T15:00:00Z | 22.66604 | +| 2022-01-01T16:00:00Z | 22.559624 | +| 2022-01-01T17:00:00Z | 22.6157744 | +| 2022-01-01T18:00:00Z | 22.88946464 | +| 2022-01-01T19:00:00Z | 22.973678784 | +| 2022-01-01T20:00:00Z | 22.8642072704 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} + +The following example use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +```sql +SELECT + EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T23:59:59Z' +GROUP BY time(90d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | exponential_moving_average | +| :------------------- | -------------------------: | +| 2020-07-07T00:00:00Z | 59.971944444444446 | +| 2020-10-05T00:00:00Z | 58.65427777777778 | +| 2021-01-03T00:00:00Z | 56.77478888888889 | +| 2021-04-03T00:00:00Z | 57.86042888888889 | +| 2021-07-02T00:00:00Z | 59.836257333333336 | +| 2021-09-30T00:00:00Z | 58.657309955555554 | +| 2021-12-29T00:00:00Z | 56.38994152888889 | +| 2022-03-29T00:00:00Z | 57.44729825066667 | +| 2022-06-27T00:00:00Z | 60.13504561706667 | +| 2022-09-25T00:00:00Z | 58.085471814684446 | +| 2022-12-24T00:00:00Z | 56.30128308881067 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### KAUFMANS_EFFICIENCY_RATIO() + +Kaufman's Efficiency Ration, or simply "Efficiency Ratio" (ER), is calculated by +dividing the data change over a period by the absolute sum of the data movements +that occurred to achieve that change. +The resulting ratio ranges between 0 and 1 with higher values representing a +more efficient or trending market. + +The ER is very similar to the [Chande Momentum Oscillator](#chande_momentum_oscillator) (CMO). +The difference is that the CMO takes market direction into account, but if you +take the absolute CMO and divide by 100, you you get the Efficiency Ratio. +{{% cite %}}[Source](http://etfhq.com/blog/2011/02/07/kaufmans-efficiency-ratio/){{% /cite %}} + +```sql +KAUFMANS_EFFICIENCY_RATIO(field_expression, period[, hold_period]) +``` + +#### Arguments {#arguments-er} + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **period**: Number of values to use as the sample size for the algorithm. + Supports integers greater than or equal to 1. + This also controls the exponential decay rate (α) used to determine the weight + of an historical value. + With a period of `3`, the algorithm uses the current value and the previous + two values. +- **hold_period**: Number of values the algorithm needs before emitting results. + Default is the same as `period`. + Must be an integer greater than or equal to `1`. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to a field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + KAUFMANS_EFFICIENCY_RATIO(temp, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | kaufmans_efficiency_ratio | +| :------------------- | ------------------------: | +| 2022-01-01T12:00:00Z | 0.555555555555555 | +| 2022-01-01T13:00:00Z | 0.19999999999999857 | +| 2022-01-01T14:00:00Z | 0.14285714285714432 | +| 2022-01-01T15:00:00Z | 0.5999999999999972 | +| 2022-01-01T16:00:00Z | 0.14285714285714432 | +| 2022-01-01T17:00:00Z | 0.14285714285714432 | +| 2022-01-01T18:00:00Z | 0.38461538461538336 | +| 2022-01-01T19:00:00Z | 0.2857142857142868 | +| 2022-01-01T20:00:00Z | 0.2 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to each field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + KAUFMANS_EFFICIENCY_RATIO(*, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | kaufmans_efficiency_ratio_co | kaufmans_efficiency_ratio_hum | kaufmans_efficiency_ratio_temp | +| :------------------- | ---------------------------: | ----------------------------: | -----------------------------: | +| 2022-01-01T12:00:00Z | 0 | 0.2 | 0.555555555555555 | +| 2022-01-01T13:00:00Z | 1 | 0.4285714285714228 | 0.19999999999999857 | +| 2022-01-01T14:00:00Z | 1 | 0.24999999999999334 | 0.14285714285714432 | +| 2022-01-01T15:00:00Z | 1 | 0.25000000000000444 | 0.5999999999999972 | +| 2022-01-01T16:00:00Z | 1 | 0 | 0.14285714285714432 | +| 2022-01-01T17:00:00Z | 1 | 1 | 0.14285714285714432 | +| 2022-01-01T18:00:00Z | 1 | 0.500000000000003 | 0.38461538461538336 | +| 2022-01-01T19:00:00Z | 1 | 0.285714285714285 | 0.2857142857142868 | +| 2022-01-01T20:00:00Z | 1 | 0.38461538461538547 | 0.2 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` with a custom hold period" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + KAUFMANS_EFFICIENCY_RATIO(temp, 4, 6) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | kaufmans_efficiency_ratio | +| :------------------- | ------------------------: | +| 2022-01-01T14:00:00Z | 0.14285714285714432 | +| 2022-01-01T15:00:00Z | 0.5999999999999972 | +| 2022-01-01T16:00:00Z | 0.14285714285714432 | +| 2022-01-01T17:00:00Z | 0.14285714285714432 | +| 2022-01-01T18:00:00Z | 0.38461538461538336 | +| 2022-01-01T19:00:00Z | 0.2857142857142868 | +| 2022-01-01T20:00:00Z | 0.2 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to time windows (grouped by time)" %}} + +The following example use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +```sql +SELECT + KAUFMANS_EFFICIENCY_RATIO(MEAN(temp_avg), 4) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T23:59:59Z' +GROUP BY time(90d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | kaufmans_efficiency_ratio | +| :------------------- | ------------------------: | +| 2020-10-05T00:00:00Z | 0.21498959056210964 | +| 2021-01-03T00:00:00Z | 0.020072053525475923 | +| 2021-04-03T00:00:00Z | 0.06190741773563866 | +| 2021-07-02T00:00:00Z | 0.08924485125858131 | +| 2021-09-30T00:00:00Z | 0.0120788302606483 | +| 2021-12-29T00:00:00Z | 0.05181655747468743 | +| 2022-03-29T00:00:00Z | 0.023768115942028996 | +| 2022-06-27T00:00:00Z | 0.06511381683430421 | +| 2022-09-25T00:00:00Z | 0.07748739110499749 | +| 2022-12-24T00:00:00Z | 0.029287632689602317 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### KAUFMANS_ADAPTIVE_MOVING_AVERAGE() + +Kaufman's Adaptive Moving Average (KAMA) is a moving average designed to account +for sample noise or volatility. +KAMA will closely follow data points when the data swings are relatively small and noise is low. +KAMA will adjust when the data swings widen and follow data from a greater distance. +This trend-following indicator can be used to identify the overall trend, +time turning points and filter data movements. +{{% cite %}}[Source](http://stockcharts.com/school/doku.php?id=chart_school:technical_indicators:kaufman_s_adaptive_moving_average){{% /cite %}} + +```sql +KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_expression, period[, hold_period]) +``` + +#### Arguments {#arguments-kama} + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **period**: Number of values to use as the sample size for the algorithm. + Supports integers greater than or equal to 1. + This also controls the exponential decay rate (α) used to determine the weight + of an historical value. + With a period of `3`, the algorithm uses the current value and the previous + two values. +- **hold_period**: Number of values the algorithm needs before emitting results. + Default is the same as `period`. + Must be an integer greater than or equal to `1`. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to a field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + KAUFMANS_ADAPTIVE_MOVING_AVERAGE(temp, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | kaufmans_adaptive_moving_average | +| :------------------- | -------------------------------: | +| 2022-01-01T12:00:00Z | 22.415923627793976 | +| 2022-01-01T13:00:00Z | 22.429061002513993 | +| 2022-01-01T14:00:00Z | 22.43746706604819 | +| 2022-01-01T15:00:00Z | 22.48506721007708 | +| 2022-01-01T16:00:00Z | 22.48313945274385 | +| 2022-01-01T17:00:00Z | 22.488053855248438 | +| 2022-01-01T18:00:00Z | 22.559247409584806 | +| 2022-01-01T19:00:00Z | 22.589508047087516 | +| 2022-01-01T20:00:00Z | 22.59328743653712 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to each field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + KAUFMANS_ADAPTIVE_MOVING_AVERAGE(*, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | kaufmans_adaptive_moving_average_co | kaufmans_adaptive_moving_average_hum | kaufmans_adaptive_moving_average_temp | +| :------------------- | ----------------------------------: | -----------------------------------: | ------------------------------------: | +| 2022-01-01T12:00:00Z | 0 | 36 | 22.415923627793976 | +| 2022-01-01T13:00:00Z | 0.44444444444444453 | 36.052029136316335 | 22.429061002513993 | +| 2022-01-01T14:00:00Z | 0.6913580246913581 | 36.063497322866624 | 22.43746706604819 | +| 2022-01-01T15:00:00Z | 1.7174211248285327 | 36.06981031521873 | 22.48506721007708 | +| 2022-01-01T16:00:00Z | 4.065233958238074 | 36.069519741586184 | 22.48313945274385 | +| 2022-01-01T17:00:00Z | 6.258463310132264 | 36.03862207865899 | 22.488053855248438 | +| 2022-01-01T18:00:00Z | 11.476924061184592 | 36.153751327944484 | 22.559247409584806 | +| 2022-01-01T19:00:00Z | 16.153846700658107 | 36.17872350475971 | 22.589508047087516 | +| 2022-01-01T20:00:00Z | 20.52991483369895 | 36.206893865280215 | 22.59328743653712 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` with a custom hold period" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + KAUFMANS_ADAPTIVE_MOVING_AVERAGE(temp, 4, 6) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | kaufmans_adaptive_moving_average | +| :------------------- | -------------------------------: | +| 2022-01-01T14:00:00Z | 22.43746706604819 | +| 2022-01-01T15:00:00Z | 22.48506721007708 | +| 2022-01-01T16:00:00Z | 22.48313945274385 | +| 2022-01-01T17:00:00Z | 22.488053855248438 | +| 2022-01-01T18:00:00Z | 22.559247409584806 | +| 2022-01-01T19:00:00Z | 22.589508047087516 | +| 2022-01-01T20:00:00Z | 22.59328743653712 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to time windows (grouped by time)" %}} + +The following example use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +```sql +SELECT + KAUFMANS_ADAPTIVE_MOVING_AVERAGE(MEAN(temp_avg), 4) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T23:59:59Z' +GROUP BY time(90d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | kaufmans_adaptive_moving_average | +| :------------------- | -------------------------------: | +| 2020-10-05T00:00:00Z | 64.23776629054989 | +| 2021-01-03T00:00:00Z | 64.17743082167587 | +| 2021-04-03T00:00:00Z | 64.12884833681618 | +| 2021-07-02T00:00:00Z | 64.11026540732492 | +| 2021-09-30T00:00:00Z | 64.07304846623671 | +| 2021-12-29T00:00:00Z | 63.97149717822299 | +| 2022-03-29T00:00:00Z | 63.94081206327896 | +| 2022-06-27T00:00:00Z | 63.94324197904272 | +| 2022-09-25T00:00:00Z | 63.83284150412919 | +| 2022-12-24T00:00:00Z | 63.76394979616807 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### RELATIVE_STRENGTH_INDEX() + +The relative strength index (RSI) is a momentum indicator that compares the +magnitude of recent increases and decreases over a specified time period to +measure speed and change of data movements. +{{% cite %}}[Source](https://www.investopedia.com/terms/r/rsi.asp){{% /cite %}} + +```sql +RELATIVE_STRENGTH_INDEX(field_expression, period[, hold_period[, warmup_type]]) +``` + +#### Arguments {#arguments-rsi} + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **period**: Number of values to use as the sample size for the algorithm. + Supports integers greater than or equal to 1. + This also controls the exponential decay rate (α) used to determine the weight + of an historical value. + With a period of `3`, the algorithm uses the current value and the previous + two values. +- **hold_period**: Number of values the algorithm needs before emitting results. + Default is `-1`, which means the `hold_period` is the same as the `period`. + Must be an integer greater than or equal to `-1`. +- **warmup_type**: Controls how the algorithm initializes the first `period` values. + Supports the following warmup types: + + - **exponential**: _(Default)_ Exponential moving average of the first `period` + values with scaling alpha (α). + When this method is used and `hold_period` is unspecified or -1, the + algorithm may start emitting points after a much smaller sample size than with _simple_. + - **simple**: Simple moving average of the first `period` values. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to a field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + RELATIVE_STRENGTH_INDEX(temp, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | relative_strength_index | +| :------------------- | ----------------------: | +| 2022-01-01T12:00:00Z | 92.39130434782608 | +| 2022-01-01T13:00:00Z | 92.78350515463916 | +| 2022-01-01T14:00:00Z | 92.78350515463916 | +| 2022-01-01T15:00:00Z | 90.03334568358646 | +| 2022-01-01T16:00:00Z | 80.49022855250077 | +| 2022-01-01T17:00:00Z | 82.90606558962943 | +| 2022-01-01T18:00:00Z | 87.14940243872873 | +| 2022-01-01T19:00:00Z | 78.48983186121941 | +| 2022-01-01T20:00:00Z | 62.04865064241268 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to each field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + RELATIVE_STRENGTH_INDEX(*, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | relative_strength_index_co | relative_strength_index_hum | relative_strength_index_temp | +| :------------------- | -------------------------: | --------------------------: | ---------------------------: | +| 2022-01-01T12:00:00Z | | 98.11827956989245 | 92.39130434782608 | +| 2022-01-01T13:00:00Z | 100 | 98.23677581863977 | 92.78350515463916 | +| 2022-01-01T14:00:00Z | 100 | 95.04467912266443 | 92.78350515463916 | +| 2022-01-01T15:00:00Z | 100 | 93.02941956003185 | 90.03334568358646 | +| 2022-01-01T16:00:00Z | 100 | 88.05084037126848 | 80.49022855250077 | +| 2022-01-01T17:00:00Z | 100 | 88.05084037126848 | 82.90606558962943 | +| 2022-01-01T18:00:00Z | 100 | 91.63299959013992 | 87.14940243872873 | +| 2022-01-01T19:00:00Z | 100 | 80.85951627810859 | 78.48983186121941 | +| 2022-01-01T20:00:00Z | 100 | 76.8440852816889 | 62.04865064241268 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a custom hold period" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + RELATIVE_STRENGTH_INDEX(temp, 4, 6) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | relative_strength_index | +| :------------------- | ----------------------: | +| 2022-01-01T14:00:00Z | 92.78350515463916 | +| 2022-01-01T15:00:00Z | 90.03334568358646 | +| 2022-01-01T16:00:00Z | 80.49022855250077 | +| 2022-01-01T17:00:00Z | 82.90606558962943 | +| 2022-01-01T18:00:00Z | 87.14940243872873 | +| 2022-01-01T19:00:00Z | 78.48983186121941 | +| 2022-01-01T20:00:00Z | 62.04865064241268 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a default non-default warmup type" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + RELATIVE_STRENGTH_INDEX(temp, 4, -1, 'simple') +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | relative_strength_index | +| :------------------- | ----------------------: | +| 2022-01-01T12:00:00Z | 97.46835443037975 | +| 2022-01-01T13:00:00Z | 97.52066115702479 | +| 2022-01-01T14:00:00Z | 97.52066115702479 | +| 2022-01-01T15:00:00Z | 96.34109464771694 | +| 2022-01-01T16:00:00Z | 91.89501009518312 | +| 2022-01-01T17:00:00Z | 92.36482202699028 | +| 2022-01-01T18:00:00Z | 93.38702507648456 | +| 2022-01-01T19:00:00Z | 88.1423325938459 | +| 2022-01-01T20:00:00Z | 76.66135862958828 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `RELATIVE_STRENGTH_INDEX` to time windows (grouped by time)" %}} + +The following example use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +```sql +SELECT + RELATIVE_STRENGTH_INDEX(MEAN(temp_avg), 4) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T23:59:59Z' +GROUP BY time(90d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | relative_strength_index | +| :------------------- | ----------------------: | +| 2020-10-05T00:00:00Z | 69.9692046299246 | +| 2021-01-03T00:00:00Z | 63.37405020679043 | +| 2021-04-03T00:00:00Z | 70.82662989351107 | +| 2021-07-02T00:00:00Z | 74.90131747577793 | +| 2021-09-30T00:00:00Z | 56.212729394565066 | +| 2021-12-29T00:00:00Z | 46.095152535803514 | +| 2022-03-29T00:00:00Z | 60.709021374375894 | +| 2022-06-27T00:00:00Z | 69.93773053391476 | +| 2022-09-25T00:00:00Z | 44.87321655968338 | +| 2022-12-24T00:00:00Z | 41.845933101386215 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### TRIPLE_EXPONENTIAL_MOVING_AVERAGE() + +The triple exponential moving average (TEMA) filters out volatility from +conventional moving averages. +While the name implies that it's a triple exponential smoothing, it's actually a +composite of a [single exponential moving average](#exponential_moving_average), +a [double exponential moving average](#double_exponential_moving_average), +and a triple exponential moving average. +{{% cite %}}[Source](https://www.investopedia.com/terms/t/triple-exponential-moving-average.asp){{% /cite %}} + +```sql +TRIPLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type]]) +``` + +#### Arguments {#arguments-tema} + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **period**: Number of values to use as the sample size for the algorithm. + Supports integers greater than or equal to 1. + This also controls the exponential decay rate (α) used to determine the weight + of an historical value. + With a period of `3`, the algorithm uses the current value and the previous + two values. +- **hold_period**: Number of values the algorithm needs before emitting results. + Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. + Must be an integer greater than or equal to `-1`. + + | Warmup type | Default hold_period | + | :---------- | :------------------ | + | exponential | `period - 1` | + | simple | `(period - 1) × 3` | + +- **warmup_type**: Controls how the algorithm initializes the first `period` values. + Supports the following warmup types: + + - **exponential**: _(Default)_ Exponential moving average of the first `period` + values with scaling alpha (α). + When this method is used and `hold_period` is unspecified or -1, the + algorithm may start emitting points after a much smaller sample size than with _simple_. + - **simple**: Simple moving average of the first `period` values. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | triple_exponential_moving_average | +| :------------------- | --------------------------------: | +| 2022-01-01T11:00:00Z | 22.54347777777777 | +| 2022-01-01T12:00:00Z | 22.499126666666672 | +| 2022-01-01T13:00:00Z | 22.716772000000002 | +| 2022-01-01T14:00:00Z | 22.790124000000006 | +| 2022-01-01T15:00:00Z | 22.728720799999994 | +| 2022-01-01T16:00:00Z | 22.465986271999995 | +| 2022-01-01T17:00:00Z | 22.6128236096 | +| 2022-01-01T18:00:00Z | 23.142821016320013 | +| 2022-01-01T19:00:00Z | 23.163081365760007 | +| 2022-01-01T20:00:00Z | 22.834869660416004 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + TRIPLE_EXPONENTIAL_MOVING_AVERAGE(*, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | triple_exponential_moving_average_co | triple_exponential_moving_average_hum | triple_exponential_moving_average_temp | +| :------------------- | -----------------------------------: | ------------------------------------: | -------------------------------------: | +| 2022-01-01T11:00:00Z | 0 | 36.03026666666666 | 22.54347777777777 | +| 2022-01-01T12:00:00Z | 0 | 35.99608 | 22.499126666666672 | +| 2022-01-01T13:00:00Z | 0.7840000000000001 | 36.379856000000004 | 22.716772000000002 | +| 2022-01-01T14:00:00Z | 1.0432 | 36.353712 | 22.790124000000006 | +| 2022-01-01T15:00:00Z | 2.663040000000001 | 36.25279040000001 | 22.728720799999994 | +| 2022-01-01T16:00:00Z | 6.300159999999999 | 36.054262656000006 | 22.465986271999995 | +| 2022-01-01T17:00:00Z | 8.977536 | 35.98746094080001 | 22.6128236096 | +| 2022-01-01T18:00:00Z | 16.698608639999996 | 36.67902875136 | 23.142821016320013 | +| 2022-01-01T19:00:00Z | 22.122591232 | 36.68111467007999 | 23.163081365760007 | +| 2022-01-01T20:00:00Z | 26.541314662400005 | 36.579546917888 | 22.834869660416004 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, 6) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | triple_exponential_moving_average | +| :------------------- | --------------------------------: | +| 2022-01-01T14:00:00Z | 22.790124000000006 | +| 2022-01-01T15:00:00Z | 22.728720799999994 | +| 2022-01-01T16:00:00Z | 22.465986271999995 | +| 2022-01-01T17:00:00Z | 22.6128236096 | +| 2022-01-01T18:00:00Z | 23.142821016320013 | +| 2022-01-01T19:00:00Z | 23.163081365760007 | +| 2022-01-01T20:00:00Z | 22.834869660416004 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + TRIPLE_EXPONENTIAL_MOVING_AVERAGE(temp, 4, -1, 'simple') +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | triple_exponential_moving_average | +| :------------------- | --------------------------------: | +| 2022-01-01T17:00:00Z | 22.65201408 | +| 2022-01-01T18:00:00Z | 23.164150553600003 | +| 2022-01-01T19:00:00Z | 23.17404420096 | +| 2022-01-01T20:00:00Z | 22.84003200512 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to time windows (grouped by time)" %}} + +The following example use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +```sql +SELECT + TRIPLE_EXPONENTIAL_MOVING_AVERAGE(MEAN(temp_avg), 4) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T23:59:59Z' +GROUP BY time(90d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | triple_exponential_moving_average | +| :------------------- | --------------------------------: | +| 2020-07-07T00:00:00Z | 64.17547253086421 | +| 2020-10-05T00:00:00Z | 59.182219074074055 | +| 2021-01-03T00:00:00Z | 55.03945899999998 | +| 2021-04-03T00:00:00Z | 57.98342055555557 | +| 2021-07-02T00:00:00Z | 61.72370060000002 | +| 2021-09-30T00:00:00Z | 58.3235789128889 | +| 2021-12-29T00:00:00Z | 53.982153124088896 | +| 2022-03-29T00:00:00Z | 57.325663060373344 | +| 2022-06-27T00:00:00Z | 62.67482784650667 | +| 2022-09-25T00:00:00Z | 57.274230204423134 | +| 2022-12-24T00:00:00Z | 54.17634351477504 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### TRIPLE_EXPONENTIAL_DERIVATIVE() + +The triple exponential derivative indicator, commonly referred to as "TRIX," is +an oscillator used to identify oversold and overbought markets, and can also be +used as a momentum indicator. +TRIX calculates a [triple exponential moving average](#triple_exponential_moving_average) +of the [log](/influxdb/v2/query-data/influxql/functions/transformations/#log) +of the data input over the period of time. +The previous value is subtracted from the previous value. +This prevents cycles that are shorter than the defined period from being considered by the indicator. + +Like many oscillators, TRIX oscillates around a zero line. When used as an oscillator, +a positive value indicates an overbought market while a negative value indicates an oversold market. +When used as a momentum indicator, a positive value suggests momentum is increasing +while a negative value suggests momentum is decreasing. +Many analysts believe that when the TRIX crosses above the zero line it gives a +buy signal, and when it closes below the zero line, it gives a sell signal. +{{% cite %}}[Source](https://www.investopedia.com/articles/technical/02/092402.asp){{% /cite %}} + +```sql +TRIPLE_EXPONENTIAL_DERIVATIVE(field_expression, period[, hold_period[, warmup_type]]) +``` + +#### Arguments {#arguments-trix} + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **period**: Number of values to use as the sample size for the algorithm. + Supports integers greater than or equal to 1. + This also controls the exponential decay rate (α) used to determine the weight + of an historical value. + With a period of `3`, the algorithm uses the current value and the previous + two values. +- **hold_period**: Number of values the algorithm needs before emitting results. + Default is `-1`, which means the `hold_period` is determined by the `warmup_type` and `period`. + Must be an integer greater than or equal to `-1`. + + | Warmup type | Default hold_period | + | :---------- | :--------------------- | + | exponential | `period` | + | simple | `(period - 1) × 3 + 1` | + +- **warmup_type**: Controls how the algorithm initializes the first `period` values. + Supports the following warmup types: + + - **exponential**: _(Default)_ Exponential moving average of the first `period` + values with scaling alpha (α). + When this method is used and `hold_period` is unspecified or -1, the + algorithm may start emitting points after a much smaller sample size than with _simple_. + - **simple**: Simple moving average of the first `period` values. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to a field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | triple_exponential_derivative | +| :------------------- | ----------------------------: | +| 2022-01-01T12:00:00Z | 0.5731400170122969 | +| 2022-01-01T13:00:00Z | 0.5082054442170802 | +| 2022-01-01T14:00:00Z | 0.45740027258918126 | +| 2022-01-01T15:00:00Z | 0.36931756808027405 | +| 2022-01-01T16:00:00Z | 0.1953270968520826 | +| 2022-01-01T17:00:00Z | 0.13729679242548976 | +| 2022-01-01T18:00:00Z | 0.28596038472352703 | +| 2022-01-01T19:00:00Z | 0.3509641845184319 | +| 2022-01-01T20:00:00Z | 0.23932489811719915 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to each field" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + TRIPLE_EXPONENTIAL_DERIVATIVE(*, 4) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | triple_exponential_derivative_co | triple_exponential_derivative_hum | triple_exponential_derivative_temp | +| :------------------- | -------------------------------: | --------------------------------: | ---------------------------------: | +| 2022-01-01T12:00:00Z | | 0.011689978802653656 | 0.5731400170122969 | +| 2022-01-01T13:00:00Z | | 0.08193865253971477 | 0.5082054442170802 | +| 2022-01-01T14:00:00Z | 179.99999999999997 | 0.10794983570248107 | 0.45740027258918126 | +| 2022-01-01T15:00:00Z | 148.57142857142853 | 0.0905729924662868 | 0.36931756808027405 | +| 2022-01-01T16:00:00Z | 140.22988505747128 | 0.02876803922613469 | 0.1953270968520826 | +| 2022-01-01T17:00:00Z | 92.48803827751195 | -0.022670378539191294 | 0.13729679242548976 | +| 2022-01-01T18:00:00Z | 84.49217002237135 | 0.10699801078373206 | 0.28596038472352703 | +| 2022-01-01T19:00:00Z | 64.59469801081093 | 0.17000537478475408 | 0.3509641845184319 | +| 2022-01-01T20:00:00Z | 48.10094220759999 | 0.16771238737589567 | 0.23932489811719915 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a custom hold period" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4, 6) +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | triple_exponential_derivative | +| :------------------- | ----------------------------: | +| 2022-01-01T14:00:00Z | 0.45740027258918126 | +| 2022-01-01T15:00:00Z | 0.36931756808027405 | +| 2022-01-01T16:00:00Z | 0.1953270968520826 | +| 2022-01-01T17:00:00Z | 0.13729679242548976 | +| 2022-01-01T18:00:00Z | 0.28596038472352703 | +| 2022-01-01T19:00:00Z | 0.3509641845184319 | +| 2022-01-01T20:00:00Z | 0.23932489811719915 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a default non-default warmup type" %}} + +The following example uses the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT + TRIPLE_EXPONENTIAL_DERIVATIVE(temp, 4, -1, 'simple') +FROM home +WHERE + room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | triple_exponential_derivative | +| :------------------- | ----------------------------: | +| 2022-01-01T18:00:00Z | 0.3040309049773704 | +| 2022-01-01T19:00:00Z | 0.37510717611963784 | +| 2022-01-01T20:00:00Z | 0.2625157254706467 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to time windows (grouped by time)" %}} + +The following example use the +[NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather). + +```sql +SELECT + TRIPLE_EXPONENTIAL_DERIVATIVE(MEAN(temp_avg), 4) +FROM weather +WHERE + location = 'San Francisco' + AND time >= '2020-01-01T00:00:00Z' + AND time <= '2022-12-31T23:59:59Z' +GROUP BY time(90d) +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | triple_exponential_derivative | +| :------------------- | ----------------------------: | +| 2020-10-05T00:00:00Z | 1.8609138140919912 | +| 2021-01-03T00:00:00Z | 0.8545019640246121 | +| 2021-04-03T00:00:00Z | 0.6716861515154271 | +| 2021-07-02T00:00:00Z | 1.0528294030543783 | +| 2021-09-30T00:00:00Z | 0.6847349621789123 | +| 2021-12-29T00:00:00Z | -0.18257939931221046 | +| 2022-03-29T00:00:00Z | -0.1722392917734461 | +| 2022-06-27T00:00:00Z | 0.6038050639217252 | +| 2022-09-25T00:00:00Z | 0.21734485841473639 | +| 2022-12-24T00:00:00Z | -0.44578753427667595 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/functions/transformations.md b/content/shared/influxql-v3-reference/functions/transformations.md new file mode 100644 index 000000000..96b22a20f --- /dev/null +++ b/content/shared/influxql-v3-reference/functions/transformations.md @@ -0,0 +1,2738 @@ +InfluxQL transformation functions modify and return values in each row of queried data. + +- [ABS()](#abs) +- [ACOS()](#acos) +- [ASIN()](#asin) +- [ATAN()](#atan) +- [ATAN2()](#atan2) +- [CEIL()](#ceil) +- [COS()](#cos) +- [CUMULATIVE_SUM()](#cumulative_sum) +- [DERIVATIVE()](#derivative) +- [DIFFERENCE()](#difference) +- [ELAPSED()](#elapsed) +- [EXP()](#exp) +- [FLOOR()](#floor) +- [LN()](#ln) +- [LOG()](#log) +- [LOG2()](#log2) +- [LOG10()](#log10) +- [MOVING_AVERAGE()](#moving_average) +- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) +- [NON_NEGATIVE_DIFFERENCE()](#non_negative_difference) +- [POW()](#pow) +- [ROUND()](#round) +- [SIN()](#sin) +- [SQRT()](#sqrt) +- [TAN()](#tan) + +> [!Important] +> +> #### Missing InfluxQL functions +> +> Some InfluxQL functions are in the process of being rearchitected to work with +> the InfluxDB v3 storage engine. If a function you need is not here, check the +> [InfluxQL feature support page](/influxdb/version/reference/influxql/feature-support/#function-support) +> for more information. + +## Notable behaviors of transformation functions + +#### Must use aggregate or selector functions when grouping by time + +Most transformation functions support `GROUP BY` clauses that group by tags, +but do not directly support `GROUP BY` clauses that group by time. +To use transformation functions with with a `GROUP BY time()` clause, apply +an [aggregate](/influxdb/version/reference/influxql/functions/aggregates/) +or [selector](/influxdb/version/reference/influxql/functions/selectors/) +function to the **field_expression** argument. +The transformation operates on the result of the aggregate or selector operation. + +--- + +## ABS() + +Returns the absolute value of the field value. + +```sql +ABS(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `ABS()` to a field" %}} + +```sql +SELECT + a, + ABS(a) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | a | abs | +| :------------------- | -----------------: | ----------------: | +| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.33909108671076 | +| 2023-01-01T00:01:00Z | -0.774984088561186 | 0.774984088561186 | +| 2023-01-01T00:02:00Z | -0.921037167720451 | 0.921037167720451 | +| 2023-01-01T00:03:00Z | -0.73880754843378 | 0.73880754843378 | +| 2023-01-01T00:04:00Z | -0.905980032168252 | 0.905980032168252 | +| 2023-01-01T00:05:00Z | -0.891164752631417 | 0.891164752631417 | + +{{% /expand %}} + +{{% expand "Apply `ABS()` to each field" %}} + +```sql +SELECT ABS(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | abs_a | abs_b | +| :------------------- | ----------------: | -----------------: | +| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.163643058925645 | +| 2023-01-01T00:01:00Z | 0.774984088561186 | 0.137034364053949 | +| 2023-01-01T00:02:00Z | 0.921037167720451 | 0.482943221384294 | +| 2023-01-01T00:03:00Z | 0.73880754843378 | 0.0729732928756677 | +| 2023-01-01T00:04:00Z | 0.905980032168252 | 1.77857552719844 | +| 2023-01-01T00:05:00Z | 0.891164752631417 | 0.741147445214238 | + +{{% /expand %}} + +{{% expand "Apply `ABS()` to time windows (grouped by time)" %}} + +```sql +SELECT + ABS(MEAN(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | abs | +| :------------------- | -------------------: | +| 2023-01-01T00:00:00Z | 0.4345725888930678 | +| 2023-01-01T00:10:00Z | 0.12861008519618367 | +| 2023-01-01T00:20:00Z | 0.030168160597251192 | +| 2023-01-01T00:30:00Z | 0.02928699660831855 | +| 2023-01-01T00:40:00Z | 0.02211434600834538 | +| 2023-01-01T00:50:00Z | 0.15530468657783394 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ACOS() + +Returns the arccosine (in radians) of the field value. +Field values must be between -1 and 1. + +```sql +ACOS(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `ACOS()` to a field" %}} + +```sql +SELECT + a, + ACOS(a) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | a | acos | +| :------------------- | -----------------: | -----------------: | +| 2023-01-01T00:00:00Z | 0.33909108671076 | 1.2248457522250173 | +| 2023-01-01T00:01:00Z | -0.774984088561186 | 2.4574862443115 | +| 2023-01-01T00:02:00Z | -0.921037167720451 | 2.741531473732281 | +| 2023-01-01T00:03:00Z | -0.73880754843378 | 2.4020955294179256 | +| 2023-01-01T00:04:00Z | -0.905980032168252 | 2.7044854502651114 | +| 2023-01-01T00:05:00Z | -0.891164752631417 | 2.6707024029338 | + +{{% /expand %}} + +{{% expand "Apply `ACOS()` to each field" %}} + +```sql +SELECT ACOS(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | acos_a | acos_b | +| :------------------- | -----------------: | -----------------: | +| 2023-01-01T00:00:00Z | 1.2248457522250173 | 1.7351786975993897 | +| 2023-01-01T00:01:00Z | 2.4574862443115 | 1.433329416131427 | +| 2023-01-01T00:02:00Z | 2.741531473732281 | 2.074809114132046 | +| 2023-01-01T00:03:00Z | 2.4020955294179256 | 1.6438345403920092 | +| 2023-01-01T00:04:00Z | 2.7044854502651114 | | +| 2023-01-01T00:05:00Z | 2.6707024029338 | 0.7360183965088304 | + +{{% /expand %}} + +{{% expand "Apply `ACOS()` to time windows (grouped by time)" %}} + +```sql +SELECT + ACOS(MEAN(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | acos | +| :------------------- | -----------------: | +| 2023-01-01T00:00:00Z | 2.0203599837582877 | +| 2023-01-01T00:10:00Z | 1.441829029328407 | +| 2023-01-01T00:20:00Z | 1.5406235882252437 | +| 2023-01-01T00:30:00Z | 1.5415051418561052 | +| 2023-01-01T00:40:00Z | 1.5486801779072885 | +| 2023-01-01T00:50:00Z | 1.41486045205998 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ASIN() + +Returns the arcsine (in radians) of the field value. +Field values must be between -1 and 1. + +```sql +ASIN(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `ASIN()` to a field" %}} + +```sql +SELECT + a, + ASIN(a) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | a | asin | +| :------------------- | -----------------: | ------------------: | +| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.34595057456987915 | +| 2023-01-01T00:01:00Z | -0.774984088561186 | -0.8866899175166036 | +| 2023-01-01T00:02:00Z | -0.921037167720451 | -1.1707351469373848 | +| 2023-01-01T00:03:00Z | -0.73880754843378 | -0.8312992026230288 | +| 2023-01-01T00:04:00Z | -0.905980032168252 | -1.133689123470215 | +| 2023-01-01T00:05:00Z | -0.891164752631417 | -1.0999060761389035 | + +{{% /expand %}} + +{{% expand "Apply `ASIN()` to each field" %}} + +```sql +SELECT ASIN(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | asin_a | asin_b | +| :------------------- | ------------------: | -------------------: | +| 2023-01-01T00:00:00Z | 0.34595057456987915 | -0.1643823708044932 | +| 2023-01-01T00:01:00Z | -0.8866899175166036 | 0.1374669106634696 | +| 2023-01-01T00:02:00Z | -1.1707351469373848 | -0.5040127873371497 | +| 2023-01-01T00:03:00Z | -0.8312992026230288 | -0.07303821359711259 | +| 2023-01-01T00:04:00Z | -1.133689123470215 | | +| 2023-01-01T00:05:00Z | -1.0999060761389035 | 0.8347779302860662 | + +{{% /expand %}} + +{{% expand "Apply `ASIN()` to time windows (grouped by time)" %}} + +```sql +SELECT + ASIN(MEAN(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | asin | +| :------------------- | -------------------: | +| 2023-01-01T00:00:00Z | -0.44956365696339134 | +| 2023-01-01T00:10:00Z | 0.1289672974664895 | +| 2023-01-01T00:20:00Z | 0.030172738569652847 | +| 2023-01-01T00:30:00Z | 0.029291184938791334 | +| 2023-01-01T00:40:00Z | 0.022116148887608062 | +| 2023-01-01T00:50:00Z | 0.15593587473491674 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ATAN() + +Returns the arctangent (in radians) of the field value. + +```sql +ATAN(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `ATAN()` to a field" %}} + +```sql +SELECT + a, + ATAN(a) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | a | atan | +| :------------------- | -----------------: | ------------------: | +| 2023-01-01T00:00:00Z | 0.33909108671076 | 0.32692355076199897 | +| 2023-01-01T00:01:00Z | -0.774984088561186 | -0.659300127490126 | +| 2023-01-01T00:02:00Z | -0.921037167720451 | -0.7443170183837121 | +| 2023-01-01T00:03:00Z | -0.73880754843378 | -0.6362993731936669 | +| 2023-01-01T00:04:00Z | -0.905980032168252 | -0.7361091800814261 | +| 2023-01-01T00:05:00Z | -0.891164752631417 | -0.727912249468035 | + +{{% /expand %}} + +{{% expand "Apply `ATAN()` to each field" %}} + +```sql +SELECT ATAN(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | atan_a | atan_b | +| :------------------- | ------------------: | -------------------: | +| 2023-01-01T00:00:00Z | 0.32692355076199897 | -0.1622053541422186 | +| 2023-01-01T00:01:00Z | -0.659300127490126 | 0.13618613793696105 | +| 2023-01-01T00:02:00Z | -0.7443170183837121 | -0.4499093121666581 | +| 2023-01-01T00:03:00Z | -0.6362993731936669 | -0.07284417510130452 | +| 2023-01-01T00:04:00Z | -0.7361091800814261 | 1.0585985450688151 | +| 2023-01-01T00:05:00Z | -0.727912249468035 | 0.6378113578294793 | + +{{% /expand %}} + +{{% expand "Apply `ATAN()` to time windows (grouped by time)" %}} + +```sql +SELECT + ATAN(MEAN(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | atan | +| :------------------- | -------------------: | +| 2023-01-01T00:00:00Z | -0.4099506966510045 | +| 2023-01-01T00:10:00Z | 0.1279079463727065 | +| 2023-01-01T00:20:00Z | 0.030159013397288013 | +| 2023-01-01T00:30:00Z | 0.02927862748761639 | +| 2023-01-01T00:40:00Z | 0.022110742100818606 | +| 2023-01-01T00:50:00Z | 0.15407382461141705 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ATAN2() + +Returns the the arctangent of `y/x` in radians. + +```sql +ATAN2(expression_y, expression_x) +``` + +#### Arguments + +- **expression_y**: Expression to identify the `y` numeric value or one or more + fields to operate on. + Can be a number literal, [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. +- **expression_x**: Expression to identify the `x` numeric value or one or more + fields to operate on. + Can be a number literal, [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `ATAN2()` to a field divided by another field" %}} + +```sql +SELECT ATAN2(a, b) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | atan2 | +| :------------------- | -------------------: | +| 2023-01-01T00:00:00Z | 2.0204217911794937 | +| 2023-01-01T00:01:00Z | -1.395783190047229 | +| 2023-01-01T00:02:00Z | -2.053731408859953 | +| 2023-01-01T00:03:00Z | -1.669248713922653 | +| 2023-01-01T00:04:00Z | -0.47112754043763505 | +| 2023-01-01T00:05:00Z | -0.8770454978291377 | + +{{% /expand %}} + +{{% expand "Apply `ATAN2()` to each field divided by a numeric value" %}} + +```sql +SELECT ATAN2(*, 2) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | atan2_a | atan2_b | +| :------------------- | -------------------: | --------------------: | +| 2023-01-01T00:00:00Z | 0.16794843225523703 | -0.0816396675119722 | +| 2023-01-01T00:01:00Z | -0.36967737169970566 | 0.06841026268126137 | +| 2023-01-01T00:02:00Z | -0.4315666721698651 | -0.2369359777533473 | +| 2023-01-01T00:03:00Z | -0.35385538623378937 | -0.036470468100670846 | +| 2023-01-01T00:04:00Z | -0.4253376417906667 | 0.7268651162204586 | +| 2023-01-01T00:05:00Z | -0.41917415992493756 | 0.35488446257957357 | + +{{% /expand %}} + +{{% expand "Apply `ATAN2()` to time windows (grouped by time)" %}} + +```sql +SELECT + ATAN2(MEAN(a), MEAN(b)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | atan2 | +| :------------------- | -----------------: | +| 2023-01-01T00:00:00Z | -1.278967897411707 | +| 2023-01-01T00:10:00Z | 2.3520553840586773 | +| 2023-01-01T00:20:00Z | 2.226497789888965 | +| 2023-01-01T00:30:00Z | 3.0977773783018656 | +| 2023-01-01T00:40:00Z | 2.9285769547942677 | +| 2023-01-01T00:50:00Z | 0.9505419744107901 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## CEIL() + +Returns the subsequent value rounded up to the nearest integer. + +```sql +CEIL(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `CEIL()` to a field" %}} + +```sql +SELECT + b, + CEIL(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | ceil | +| :------------------- | ------------------: | ---: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | +| 2023-01-01T00:01:00Z | 0.137034364053949 | 1 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | + +{{% /expand %}} + +{{% expand "Apply `CEIL()` to each field" %}} + +```sql +SELECT CEIL(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | ceil_a | ceil_b | +| :------------------- | -----: | -----: | +| 2023-01-01T00:00:00Z | 1 | -0 | +| 2023-01-01T00:01:00Z | -0 | 1 | +| 2023-01-01T00:02:00Z | -0 | -0 | +| 2023-01-01T00:03:00Z | -0 | -0 | +| 2023-01-01T00:04:00Z | -0 | 2 | +| 2023-01-01T00:05:00Z | -0 | 1 | + +{{% /expand %}} + +{{% expand "Apply `CEIL()` to time windows (grouped by time)" %}} + +```sql +SELECT + CEIL(MEAN(b)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | ceil | +| :------------------- | ---: | +| 2023-01-01T00:00:00Z | 1 | +| 2023-01-01T00:10:00Z | -0 | +| 2023-01-01T00:20:00Z | -0 | +| 2023-01-01T00:30:00Z | -0 | +| 2023-01-01T00:40:00Z | -0 | +| 2023-01-01T00:50:00Z | 1 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## COS() + +Returns the cosine of the field value. + +```sql +COS(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `COS()` to a field" %}} + +```sql +SELECT + b, + COS(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | cos | +| :------------------- | ------------------: | -------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | 0.9866403278718959 | +| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.9906254752128878 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | 0.8856319645801471 | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | 0.9973386305831397 | +| 2023-01-01T00:04:00Z | 1.77857552719844 | -0.20628737691395405 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.7376943643170851 | + +{{% /expand %}} + +{{% expand "Apply `COS()` to each field" %}} + +```sql +SELECT COS(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | cos_a | cos_b | +| :------------------- | -----------------: | -------------------: | +| 2023-01-01T00:00:00Z | 0.9430573869206459 | 0.9866403278718959 | +| 2023-01-01T00:01:00Z | 0.7144321674550146 | 0.9906254752128878 | +| 2023-01-01T00:02:00Z | 0.6049946586273094 | 0.8856319645801471 | +| 2023-01-01T00:03:00Z | 0.7392720891861374 | 0.9973386305831397 | +| 2023-01-01T00:04:00Z | 0.616914561474936 | -0.20628737691395405 | +| 2023-01-01T00:05:00Z | 0.6285065034701617 | 0.7376943643170851 | + +{{% /expand %}} + +{{% expand "Apply `COS()` to time windows (grouped by time)" %}} + +```sql +SELECT + COS(MEAN(b)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | cos | +| :------------------- | -----------------: | +| 2023-01-01T00:00:00Z | 0.9914907269510592 | +| 2023-01-01T00:10:00Z | 0.9918765457796455 | +| 2023-01-01T00:20:00Z | 0.9997307399250498 | +| 2023-01-01T00:30:00Z | 0.7850670342365872 | +| 2023-01-01T00:40:00Z | 0.9947779847618986 | +| 2023-01-01T00:50:00Z | 0.9938532355205111 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## CUMULATIVE_SUM() + +Returns the running total of subsequent [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +CUMULATIVE_SUM(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `CUMULATIVE_SUM()` to a field" %}} + +```sql +SELECT CUMULATIVE_SUM(b) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | cumulative_sum | +| :------------------- | -------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | +| 2023-01-01T00:01:00Z | -0.02660869487169601 | +| 2023-01-01T00:02:00Z | -0.5095519162559901 | +| 2023-01-01T00:03:00Z | -0.5825252091316577 | +| 2023-01-01T00:04:00Z | 1.1960503180667823 | +| 2023-01-01T00:05:00Z | 1.9371977632810204 | + +{{% /expand %}} + +{{% expand "Apply `CUMULATIVE_SUM()` to each field" %}} + +```sql +SELECT CUMULATIVE_SUM(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | cumulative_sum_a | cumulative_sum_b | +| :------------------- | -------------------: | -------------------: | +| 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | +| 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | +| 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | +| 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | +| 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | +| 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | + +{{% /expand %}} + +{{% expand "Apply `CUMULATIVE_SUM()` to field keys that match a regular expression" %}} + +```sql +SELECT CUMULATIVE_SUM(/[ab]/) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | cumulative_sum_a | cumulative_sum_b | +| :------------------- | -------------------: | -------------------: | +| 2023-01-01T00:00:00Z | 0.33909108671076 | -0.163643058925645 | +| 2023-01-01T00:01:00Z | -0.43589300185042595 | -0.02660869487169601 | +| 2023-01-01T00:02:00Z | -1.3569301695708769 | -0.5095519162559901 | +| 2023-01-01T00:03:00Z | -2.095737718004657 | -0.5825252091316577 | +| 2023-01-01T00:04:00Z | -3.001717750172909 | 1.1960503180667823 | +| 2023-01-01T00:05:00Z | -3.892882502804326 | 1.9371977632810204 | + +{{% /expand %}} + +{{% expand "Apply `CUMULATIVE_SUM()` to time windows (grouped by time)" %}} + +```sql +SELECT + CUMULATIVE_SUM(SUM(b)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | cumulative_sum | +| :------------------- | -------------------: | +| 2023-01-01T00:00:00Z | 1.3054783385851743 | +| 2023-01-01T00:10:00Z | 0.029980276948385454 | +| 2023-01-01T00:20:00Z | -0.20208529969578404 | +| 2023-01-01T00:30:00Z | -6.882005145666267 | +| 2023-01-01T00:40:00Z | -7.904410787756402 | +| 2023-01-01T00:50:00Z | -6.795080184131271 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## DERIVATIVE() + +Returns the rate of change between subsequent [field values](/influxdb/version/reference/glossary/#field-value) +per `unit`. + +```sql +SELECT DERIVATIVE(field_expression[, unit]) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **unit**: Unit of time to use to calculate the rate of change. + Supports [duration literals](/influxdb/version/reference/influxql/#durations). + _Default is `1s` (per second)_. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Related functions + +- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `DERIVATIVE()` to a field to calculate the per second change" %}} + +```sql +SELECT DERIVATIVE(b) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | derivative | +| :------------------- | --------------------: | +| 2023-01-01T00:01:00Z | 0.005011290382993233 | +| 2023-01-01T00:02:00Z | -0.01033295975730405 | +| 2023-01-01T00:03:00Z | 0.006832832141810439 | +| 2023-01-01T00:04:00Z | 0.03085914700123513 | +| 2023-01-01T00:05:00Z | -0.017290468033070033 | +| 2023-01-01T00:06:00Z | -0.007557890705063634 | + +{{% /expand %}} + +{{% expand "Apply `DERIVATIVE()` to a field to calculate the per 5 minute change" %}} + +```sql +SELECT DERIVATIVE(b, 5m) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | derivative | +| :------------------- | ------------------: | +| 2023-01-01T00:01:00Z | 1.5033871148979698 | +| 2023-01-01T00:02:00Z | -3.0998879271912148 | +| 2023-01-01T00:03:00Z | 2.0498496425431316 | +| 2023-01-01T00:04:00Z | 9.257744100370537 | +| 2023-01-01T00:05:00Z | -5.187140409921009 | +| 2023-01-01T00:06:00Z | -2.26736721151909 | + +{{% /expand %}} + +{{% expand "Apply `DERIVATIVE()` to each field" %}} + +```sql +SELECT DERIVATIVE(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | derivative_a | derivative_b | +| :------------------- | ---------------------: | --------------------: | +| 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | +| 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | +| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | +| 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | +| 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | +| 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | + +{{% /expand %}} + +{{% expand "Apply `DERIVATIVE()` to field keys that match a regular expression" %}} + +```sql +SELECT DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | derivative_a | derivative_b | +| :------------------- | ---------------------: | --------------------: | +| 2023-01-01T00:01:00Z | -0.018567919587865765 | 0.005011290382993233 | +| 2023-01-01T00:02:00Z | -0.0024342179859877505 | -0.01033295975730405 | +| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | +| 2023-01-01T00:04:00Z | -0.0027862080622411984 | 0.03085914700123513 | +| 2023-01-01T00:05:00Z | 0.00024692132561391543 | -0.017290468033070033 | +| 2023-01-01T00:06:00Z | 0.016704951104985283 | -0.007557890705063634 | + +{{% /expand %}} + +{{% expand "Apply `DERIVATIVE()` to time windows (grouped by time)" %}} + +```sql +SELECT + DERIVATIVE(MEAN(b), 1m) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | derivative | +| :------------------- | --------------------: | +| 2023-01-01T00:10:00Z | -0.025809764002219633 | +| 2023-01-01T00:20:00Z | 0.010434324849926194 | +| 2023-01-01T00:30:00Z | -0.06447854269326314 | +| 2023-01-01T00:40:00Z | 0.05657514203880348 | +| 2023-01-01T00:50:00Z | 0.021317362457152655 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## DIFFERENCE() + +Returns the result of subtraction between subsequent [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +DIFFERENCE(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Related functions + +- [NON_NEGATIVE_DIFFERENCE()](#non_negative_difference) + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `DIFFERENCE()` to a field" %}} + +```sql +SELECT DIFFERENCE(b) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | difference | +| :------------------- | -------------------: | +| 2023-01-01T00:01:00Z | 0.300677422979594 | +| 2023-01-01T00:02:00Z | -0.619977585438243 | +| 2023-01-01T00:03:00Z | 0.40996992850862635 | +| 2023-01-01T00:04:00Z | 1.8515488200741077 | +| 2023-01-01T00:05:00Z | -1.0374280819842019 | +| 2023-01-01T00:06:00Z | -0.45347344230381803 | + +{{% /expand %}} + +{{% expand "Apply `DIFFERENCE()` to each field" %}} + +```sql +SELECT DIFFERENCE(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | difference_a | difference_b | +| :------------------- | -------------------: | -------------------: | +| 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | +| 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | +| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | +| 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | +| 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | +| 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | + +{{% /expand %}} + +{{% expand "Apply `DIFFERENCE()` to field keys that match a regular expression" %}} + +```sql +SELECT DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | difference_a | difference_b | +| :------------------- | -------------------: | -------------------: | +| 2023-01-01T00:01:00Z | -1.114075175271946 | 0.300677422979594 | +| 2023-01-01T00:02:00Z | -0.14605307915926502 | -0.619977585438243 | +| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | +| 2023-01-01T00:04:00Z | -0.1671724837344719 | 1.8515488200741077 | +| 2023-01-01T00:05:00Z | 0.014815279536834924 | -1.0374280819842019 | +| 2023-01-01T00:06:00Z | 1.002297066299117 | -0.45347344230381803 | + +{{% /expand %}} + +{{% expand "Apply `DIFFERENCE()` to time windows (grouped by time)" %}} + +```sql +SELECT + DIFFERENCE(MEAN(b)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | difference | +| :------------------- | ------------------: | +| 2023-01-01T00:10:00Z | -0.2580976400221963 | +| 2023-01-01T00:20:00Z | 0.10434324849926194 | +| 2023-01-01T00:30:00Z | -0.6447854269326314 | +| 2023-01-01T00:40:00Z | 0.5657514203880348 | +| 2023-01-01T00:50:00Z | 0.21317362457152655 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ELAPSED() + +Returns the difference between subsequent [field value's](/influxdb/version/reference/glossary/#field-value) +timestamps in a specified `unit` of time. + +```sql +ELAPSED(field_expression[, unit ]) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports all field types. +- **unit**: Unit of time to return the elapsed time in. + Supports [duration literals](/influxdb/version/reference/influxql/#durations). + _Default is `1ns` (nanoseconds)_. + +#### Notable behaviors + +- If the `unit` is greater than the elapsed time between points, `ELAPSED()` + returns `0`. +- `ELAPSED()` supports the `GROUP BY time()` clause but the query results aren't very useful. + An `ELAPSED()` query with a nested function and a `GROUP BY time()` clause + returns the interval specified in the `GROUP BY time()` clause. + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `ELAPSED()` to a field and return elapsed time in nanoseconds" %}} + +```sql +SELECT ELAPSED(b) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | elapsed | +| :------------------- | ----------: | +| 2023-01-01T00:01:00Z | 60000000000 | +| 2023-01-01T00:02:00Z | 60000000000 | +| 2023-01-01T00:03:00Z | 60000000000 | +| 2023-01-01T00:04:00Z | 60000000000 | +| 2023-01-01T00:05:00Z | 60000000000 | +| 2023-01-01T00:06:00Z | 60000000000 | + +{{% /expand %}} + +{{% expand "Apply `ELAPSED()` to a field and return elapsed time in seconds" %}} + +```sql +SELECT ELAPSED(b, 1s) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | elapsed | +| :------------------- | ------: | +| 2023-01-01T00:01:00Z | 60 | +| 2023-01-01T00:02:00Z | 60 | +| 2023-01-01T00:03:00Z | 60 | +| 2023-01-01T00:04:00Z | 60 | +| 2023-01-01T00:05:00Z | 60 | +| 2023-01-01T00:06:00Z | 60 | + +{{% /expand %}} + +{{% expand "Apply `ELAPSED()` to each field" %}} + +```sql +SELECT ELAPSED(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | elapsed_a | elapsed_b | +| :------------------- | ----------: | ----------: | +| 2023-01-01T00:01:00Z | 60000000000 | 60000000000 | +| 2023-01-01T00:02:00Z | 60000000000 | 60000000000 | +| 2023-01-01T00:03:00Z | 60000000000 | 60000000000 | +| 2023-01-01T00:04:00Z | 60000000000 | 60000000000 | +| 2023-01-01T00:05:00Z | 60000000000 | 60000000000 | +| 2023-01-01T00:06:00Z | 60000000000 | 60000000000 | + +{{% /expand %}} + +{{% expand "Apply `ELAPSED()` to field keys that match a regular expression" %}} + +```sql +SELECT ELAPSED(/[ab]/, 1s) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | elapsed_a | elapsed_b | +| :------------------- | --------: | --------: | +| 2023-01-01T00:01:00Z | 60 | 60 | +| 2023-01-01T00:02:00Z | 60 | 60 | +| 2023-01-01T00:03:00Z | 60 | 60 | +| 2023-01-01T00:04:00Z | 60 | 60 | +| 2023-01-01T00:05:00Z | 60 | 60 | +| 2023-01-01T00:06:00Z | 60 | 60 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## EXP() + +Returns the exponential of the field value. + +```sql +EXP(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `EXP()` to a field" %}} + +```sql +SELECT + a, + EXP(a) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | a | exp | +| :------------------- | -----------------: | ------------------: | +| 2023-01-01T00:00:00Z | 0.33909108671076 | 1.4036711951820788 | +| 2023-01-01T00:01:00Z | -0.774984088561186 | 0.460711111517308 | +| 2023-01-01T00:02:00Z | -0.921037167720451 | 0.39810592427186076 | +| 2023-01-01T00:03:00Z | -0.73880754843378 | 0.4776831901055915 | +| 2023-01-01T00:04:00Z | -0.905980032168252 | 0.40414561525252984 | +| 2023-01-01T00:05:00Z | -0.891164752631417 | 0.4101777188333968 | + +{{% /expand %}} + +{{% expand "Apply `EXP()` to each field" %}} + +```sql +SELECT EXP(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | exp_a | exp_b | +| :------------------- | ------------------: | -----------------: | +| 2023-01-01T00:00:00Z | 1.4036711951820788 | 0.8490450268435884 | +| 2023-01-01T00:01:00Z | 0.460711111517308 | 1.14686755886191 | +| 2023-01-01T00:02:00Z | 0.39810592427186076 | 0.6169648527893578 | +| 2023-01-01T00:03:00Z | 0.4776831901055915 | 0.929625657322271 | +| 2023-01-01T00:04:00Z | 0.40414561525252984 | 5.921415512753404 | +| 2023-01-01T00:05:00Z | 0.4101777188333968 | 2.09834186598405 | + +{{% /expand %}} + +{{% expand "Apply `EXP()` to time windows (grouped by time)" %}} + +```sql +SELECT + EXP(MEAN(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | exp | +| :------------------- | -----------------: | +| 2023-01-01T00:00:00Z | 0.6475413743155294 | +| 2023-01-01T00:10:00Z | 1.137246608416461 | +| 2023-01-01T00:20:00Z | 1.030627830373793 | +| 2023-01-01T00:30:00Z | 1.029720078241656 | +| 2023-01-01T00:40:00Z | 1.0223606806499268 | +| 2023-01-01T00:50:00Z | 1.1680137850180072 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## FLOOR() + +Returns the subsequent value rounded down to the nearest integer. + +```sql +FLOOR(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `FLOOR()` to a field" %}} + +```sql +SELECT + b, + FLOOR(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | floor | +| :------------------- | ------------------: | ----: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | -1 | +| 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | -1 | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | -1 | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 1 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | 0 | + +{{% /expand %}} + +{{% expand "Apply `FLOOR()` to each field" %}} + +```sql +SELECT FLOOR(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | floor_a | floor_b | +| :------------------- | ------: | ------: | +| 2023-01-01T00:00:00Z | 0 | -1 | +| 2023-01-01T00:01:00Z | -1 | 0 | +| 2023-01-01T00:02:00Z | -1 | -1 | +| 2023-01-01T00:03:00Z | -1 | -1 | +| 2023-01-01T00:04:00Z | -1 | 1 | +| 2023-01-01T00:05:00Z | -1 | 0 | + +{{% /expand %}} + +{{% expand "Apply `FLOOR()` to time windows (grouped by time)" %}} + +```sql +SELECT + FLOOR(SUM(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | floor | +| :------------------- | ----: | +| 2023-01-01T00:00:00Z | -5 | +| 2023-01-01T00:10:00Z | 1 | +| 2023-01-01T00:20:00Z | 0 | +| 2023-01-01T00:30:00Z | 0 | +| 2023-01-01T00:40:00Z | 0 | +| 2023-01-01T00:50:00Z | 1 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## LN() + +Returns the natural logarithm of the field value. +Field values must be greater than or equal to 0. + +```sql +LN(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `LN()` to a field" %}} + +```sql +SELECT + b, + LN(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | ln | +| :------------------- | ------------------: | ------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | | +| 2023-01-01T00:01:00Z | 0.137034364053949 | -1.98752355209665 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5758127783016702 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2995556920844895 | + +{{% /expand %}} + +{{% expand "Apply `LN()` to each field" %}} + +```sql +SELECT LN(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | ln_a | ln_b | +| :------------------- | ------------------: | ------------------: | +| 2023-01-01T00:00:00Z | -1.0814865153308908 | | +| 2023-01-01T00:01:00Z | | -1.98752355209665 | +| 2023-01-01T00:02:00Z | | | +| 2023-01-01T00:03:00Z | | | +| 2023-01-01T00:04:00Z | | 0.5758127783016702 | +| 2023-01-01T00:05:00Z | | -0.2995556920844895 | + +{{% /expand %}} + +{{% expand "Apply `LN()` to time windows (grouped by time)" %}} + +```sql +SELECT + LN(SUM(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | ln | +| :------------------- | ------------------: | +| 2023-01-01T00:00:00Z | | +| 2023-01-01T00:10:00Z | 0.25161504572793725 | +| 2023-01-01T00:20:00Z | -1.1983831026157092 | +| 2023-01-01T00:30:00Z | -1.2280265702380913 | +| 2023-01-01T00:40:00Z | -1.5089436474159283 | +| 2023-01-01T00:50:00Z | 0.4402187212890264 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## LOG() + +Returns the logarithm of the field value with base `b`. +Field values must be greater than or equal to 0. + +```sql +LOG(field_expression, b) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. +- **b**: Logarithm base to use in the operation. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `LOG()` to a field with a base of 3" %}} + +```sql +SELECT + b, + LOG(b, 3) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | log | +| :------------------- | ------------------: | ------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | | +| 2023-01-01T00:01:00Z | 0.137034364053949 | -1.8091219009630797 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.5241273780031629 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.2726673414946528 | + +{{% /expand %}} + +{{% expand "Apply `LOG()` to each field with a base of 5" %}} + +```sql +SELECT LOG(*, 5) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | log_a | log_b | +| :------------------- | ------------------: | -------------------: | +| 2023-01-01T00:00:00Z | -0.6719653532302217 | | +| 2023-01-01T00:01:00Z | | -1.2349178161776593 | +| 2023-01-01T00:02:00Z | | | +| 2023-01-01T00:03:00Z | | | +| 2023-01-01T00:04:00Z | | 0.3577725949246566 | +| 2023-01-01T00:05:00Z | | -0.18612441633827553 | + +{{% /expand %}} + +{{% expand "Apply `LOG()` to time windows (grouped by time)" %}} + +```sql +SELECT + LOG(SUM(a), 10) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | log | +| :------------------- | ------------------: | +| 2023-01-01T00:00:00Z | | +| 2023-01-01T00:10:00Z | 0.10927502592347751 | +| 2023-01-01T00:20:00Z | -0.5204511686721008 | +| 2023-01-01T00:30:00Z | -0.5333251630849791 | +| 2023-01-01T00:40:00Z | -0.6553258995757036 | +| 2023-01-01T00:50:00Z | 0.1911845614863297 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## LOG2() + +Returns the logarithm of the field value to the base 2. +Field values must be greater than or equal to 0. + +```sql +LOG2(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `LOG2()` to a field" %}} + +```sql +SELECT + b, + LOG2(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | log2 | +| :------------------- | ------------------: | ------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | | +| 2023-01-01T00:01:00Z | 0.137034364053949 | -2.8673903722598544 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.8307222397363156 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.4321675114403543 | + +{{% /expand %}} + +{{% expand "Apply `LOG2()` to each field" %}} + +```sql +SELECT LOG2(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | log2_a | log2_b | +| :------------------- | -----------------: | ------------------: | +| 2023-01-01T00:00:00Z | -1.560255232456162 | | +| 2023-01-01T00:01:00Z | | -2.8673903722598544 | +| 2023-01-01T00:02:00Z | | | +| 2023-01-01T00:03:00Z | | | +| 2023-01-01T00:04:00Z | | 0.8307222397363156 | +| 2023-01-01T00:05:00Z | | -0.4321675114403543 | + +{{% /expand %}} + +{{% expand "Apply `LOG2()` to time windows (grouped by time)" %}} + +```sql +SELECT + LOG2(SUM(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | log2 | +| :------------------- | ------------------: | +| 2023-01-01T00:00:00Z | | +| 2023-01-01T00:10:00Z | 0.36300377868474476 | +| 2023-01-01T00:20:00Z | -1.7289013592288134 | +| 2023-01-01T00:30:00Z | -1.7716678429623767 | +| 2023-01-01T00:40:00Z | -2.1769455171078644 | +| 2023-01-01T00:50:00Z | 0.6351013661101591 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## LOG10() + +Returns the logarithm of the field value to the base 10. +Field values must be greater than or equal to 0. + +```sql +LOG10(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `LOG10()` to a field" %}} + +```sql +SELECT + b, + LOG10(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | log10 | +| :------------------- | ------------------: | ------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | | +| 2023-01-01T00:01:00Z | 0.137034364053949 | -0.8631705113283253 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.25007231222579585 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | -0.1300953840950034 | + +{{% /expand %}} + +{{% expand "Apply `LOG10()` to each field" %}} + +```sql +SELECT LOG10(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | log10_a | log10_b | +| :------------------- | -------------------: | ------------------: | +| 2023-01-01T00:00:00Z | -0.46968362586098245 | | +| 2023-01-01T00:01:00Z | | -0.8631705113283253 | +| 2023-01-01T00:02:00Z | | | +| 2023-01-01T00:03:00Z | | | +| 2023-01-01T00:04:00Z | | 0.25007231222579585 | +| 2023-01-01T00:05:00Z | | -0.1300953840950034 | + +{{% /expand %}} + +{{% expand "Apply `LOG10()` to time windows (grouped by time)" %}} + +```sql +SELECT + LOG10(SUM(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | log10 | +| :------------------- | ------------------: | +| 2023-01-01T00:00:00Z | | +| 2023-01-01T00:10:00Z | 0.10927502592347751 | +| 2023-01-01T00:20:00Z | -0.520451168672101 | +| 2023-01-01T00:30:00Z | -0.5333251630849791 | +| 2023-01-01T00:40:00Z | -0.6553258995757036 | +| 2023-01-01T00:50:00Z | 0.19118456148632973 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## MOVING_AVERAGE() + +Returns the rolling average across a window of subsequent [field values](/influxdb/version/reference/glossary/#field-value). + +```sql +MOVING_AVERAGE(field_expression, N) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports all field types. +- **N**: Number of field values to use when calculating the moving average. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `MOVING_AVERAGE()` to a field" %}} + +```sql +SELECT MOVING_AVERAGE(a, 3) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | moving_average | +| :------------------- | ------------------: | +| 2023-01-01T00:02:00Z | -0.4523100565236256 | +| 2023-01-01T00:03:00Z | -0.8116096015718056 | +| 2023-01-01T00:04:00Z | -0.8552749161074944 | +| 2023-01-01T00:05:00Z | -0.8453174444111498 | +| 2023-01-01T00:06:00Z | -0.5620041570439896 | +| 2023-01-01T00:07:00Z | -0.3569778402485757 | + +{{% /expand %}} + +{{% expand "Apply `MOVING_AVERAGE()` to each field" %}} + +```sql +SELECT MOVING_AVERAGE(*, 3) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | moving_average_a | moving_average_b | +| :------------------- | ------------------: | -------------------: | +| 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | +| 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | +| 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | +| 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | +| 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | +| 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | + +{{% /expand %}} + +{{% expand "Apply `MOVING_AVERAGE()` to field keys that match a regular expression" %}} + +```sql +SELECT MOVING_AVERAGE(/[ab]/, 3) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | moving_average_a | moving_average_b | +| :------------------- | ------------------: | -------------------: | +| 2023-01-01T00:02:00Z | -0.4523100565236256 | -0.16985063875199669 | +| 2023-01-01T00:03:00Z | -0.8116096015718056 | -0.13962738340200423 | +| 2023-01-01T00:04:00Z | -0.8552749161074944 | 0.40755300431282615 | +| 2023-01-01T00:05:00Z | -0.8453174444111498 | 0.815583226512337 | +| 2023-01-01T00:06:00Z | -0.5620041570439896 | 0.9357989917743662 | +| 2023-01-01T00:07:00Z | -0.3569778402485757 | 0.15985821845558748 | + +{{% /expand %}} + +{{% expand "Apply `MOVING_AVERAGE()` to time windows (grouped by time)" %}} + +```sql +SELECT + MOVING_AVERAGE(SUM(a), 3) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | moving_average | +| :------------------- | ------------------: | +| 2023-01-01T00:20:00Z | -0.9193144769987766 | +| 2023-01-01T00:30:00Z | 0.626884141339178 | +| 2023-01-01T00:40:00Z | 0.27189834404638374 | +| 2023-01-01T00:50:00Z | 0.6890200973149928 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## NON_NEGATIVE_DERIVATIVE() + +Returns only non-negative rate of change between subsequent +[field values](/influxdb/version/reference/glossary/#field-value). +Negative rates of change return _null_. + +```sql +NON_NEGATIVE_DERIVATIVE(field_expression[, unit]) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. +- **unit**: Unit of time to use to calculate the rate of change. + Supports [duration literals](/influxdb/version/reference/influxql/#durations). + _Default is `1s` (per second)_. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Related functions + +- [DERIVATIVE()](#derivative) + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per second change" %}} + +```sql +SELECT NON_NEGATIVE_DERIVATIVE(b) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_derivative | +| :------------------- | ----------------------: | +| 2023-01-01T00:01:00Z | 0.005011290382993233 | +| 2023-01-01T00:03:00Z | 0.006832832141810439 | +| 2023-01-01T00:04:00Z | 0.03085914700123513 | +| 2023-01-01T00:08:00Z | 0.0227877053636946 | +| 2023-01-01T00:10:00Z | 0.001676063810538834 | +| 2023-01-01T00:11:00Z | 0.014999637478226817 | + +{{% /expand %}} + +{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to a field to calculate the per 5 minute change" %}} + +```sql +SELECT NON_NEGATIVE_DERIVATIVE(b, 5m) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_derivative | +| :------------------- | ----------------------: | +| 2023-01-01T00:01:00Z | 1.5033871148979698 | +| 2023-01-01T00:03:00Z | 2.0498496425431316 | +| 2023-01-01T00:04:00Z | 9.257744100370537 | +| 2023-01-01T00:08:00Z | 6.836311609108379 | +| 2023-01-01T00:10:00Z | 0.5028191431616502 | +| 2023-01-01T00:11:00Z | 4.499891243468045 | + +{{% /expand %}} + +{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to each field" %}} + +```sql +SELECT NON_NEGATIVE_DERIVATIVE(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_derivative_a | non_negative_derivative_b | +| :------------------- | ------------------------: | ------------------------: | +| 2023-01-01T00:01:00Z | | 0.005011290382993233 | +| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | +| 2023-01-01T00:04:00Z | | 0.03085914700123513 | +| 2023-01-01T00:05:00Z | 0.00024692132561391543 | | +| 2023-01-01T00:06:00Z | 0.016704951104985283 | | +| 2023-01-01T00:08:00Z | | 0.0227877053636946 | +| 2023-01-01T00:09:00Z | 0.018437240876186967 | | +| 2023-01-01T00:10:00Z | | 0.001676063810538834 | +| 2023-01-01T00:11:00Z | | 0.014999637478226817 | +| 2023-01-01T00:13:00Z | 0.006694752202850366 | | +| 2023-01-01T00:14:00Z | 0.011836797386191167 | | + +{{% /expand %}} + +{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to field keys that match a regular expression" %}} + +```sql +SELECT NON_NEGATIVE_DERIVATIVE(/[ab]/) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_derivative_a | non_negative_derivative_b | +| :------------------- | ------------------------: | ------------------------: | +| 2023-01-01T00:01:00Z | | 0.005011290382993233 | +| 2023-01-01T00:03:00Z | 0.0030371603214445152 | 0.006832832141810439 | +| 2023-01-01T00:04:00Z | | 0.03085914700123513 | +| 2023-01-01T00:05:00Z | 0.00024692132561391543 | | +| 2023-01-01T00:06:00Z | 0.016704951104985283 | | +| 2023-01-01T00:08:00Z | | 0.0227877053636946 | +| 2023-01-01T00:09:00Z | 0.018437240876186967 | | +| 2023-01-01T00:10:00Z | | 0.001676063810538834 | +| 2023-01-01T00:11:00Z | | 0.014999637478226817 | +| 2023-01-01T00:13:00Z | 0.006694752202850366 | | +| 2023-01-01T00:14:00Z | 0.011836797386191167 | | + +{{% /expand %}} + +{{% expand "Apply `NON_NEGATIVE_DERIVATIVE()` to time windows (grouped by time)" %}} + +```sql +SELECT + NON_NEGATIVE_DERIVATIVE(MEAN(b), 1m) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_derivative | +| :------------------- | ----------------------: | +| 2023-01-01T00:20:00Z | 0.010434324849926194 | +| 2023-01-01T00:40:00Z | 0.05657514203880348 | +| 2023-01-01T00:50:00Z | 0.021317362457152655 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## NON_NEGATIVE_DIFFERENCE() + +Returns only non-negative result of subtraction between subsequent +[field values](/influxdb/version/reference/glossary/#field-value). +Negative differences return _null_. + +```sql +NON_NEGATIVE_DIFFERENCE(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, regular expression, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Related functions + +- [DIFFERENCE()](#difference) + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to a field" %}} + +```sql +SELECT NON_NEGATIVE_DIFFERENCE(b) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_difference | +| :------------------- | ----------------------: | +| 2023-01-01T00:01:00Z | 0.300677422979594 | +| 2023-01-01T00:03:00Z | 0.40996992850862635 | +| 2023-01-01T00:04:00Z | 1.8515488200741077 | +| 2023-01-01T00:08:00Z | 1.367262321821676 | +| 2023-01-01T00:10:00Z | 0.10056382863233004 | +| 2023-01-01T00:11:00Z | 0.899978248693609 | + +{{% /expand %}} + +{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to each field" %}} + +```sql +SELECT NON_NEGATIVE_DIFFERENCE(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_difference_a | non_negative_difference_b | +| :------------------- | ------------------------: | ------------------------: | +| 2023-01-01T00:01:00Z | | 0.300677422979594 | +| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | +| 2023-01-01T00:04:00Z | | 1.8515488200741077 | +| 2023-01-01T00:05:00Z | 0.014815279536834924 | | +| 2023-01-01T00:06:00Z | 1.002297066299117 | | +| 2023-01-01T00:08:00Z | | 1.367262321821676 | +| 2023-01-01T00:09:00Z | 1.106234452571218 | | +| 2023-01-01T00:10:00Z | | 0.10056382863233004 | +| 2023-01-01T00:11:00Z | | 0.899978248693609 | +| 2023-01-01T00:13:00Z | 0.401685132171022 | | +| 2023-01-01T00:14:00Z | 0.71020784317147 | | + +{{% /expand %}} + +{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to field keys that match a regular expression" %}} + +```sql +SELECT NON_NEGATIVE_DIFFERENCE(/[ab]/) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_difference_a | non_negative_difference_b | +| :------------------- | ------------------------: | ------------------------: | +| 2023-01-01T00:01:00Z | | 0.300677422979594 | +| 2023-01-01T00:03:00Z | 0.18222961928667092 | 0.40996992850862635 | +| 2023-01-01T00:04:00Z | | 1.8515488200741077 | +| 2023-01-01T00:05:00Z | 0.014815279536834924 | | +| 2023-01-01T00:06:00Z | 1.002297066299117 | | +| 2023-01-01T00:08:00Z | | 1.367262321821676 | +| 2023-01-01T00:09:00Z | 1.106234452571218 | | +| 2023-01-01T00:10:00Z | | 0.10056382863233004 | +| 2023-01-01T00:11:00Z | | 0.899978248693609 | +| 2023-01-01T00:13:00Z | 0.401685132171022 | | +| 2023-01-01T00:14:00Z | 0.71020784317147 | | + +{{% /expand %}} + +{{% expand "Apply `NON_NEGATIVE_DIFFERENCE()` to time windows (grouped by time)" %}} + +```sql +SELECT + NON_NEGATIVE_DIFFERENCE(MEAN(b)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | non_negative_difference | +| :------------------- | ----------------------: | +| 2023-01-01T00:20:00Z | 0.10434324849926194 | +| 2023-01-01T00:40:00Z | 0.5657514203880348 | +| 2023-01-01T00:50:00Z | 0.21317362457152655 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## POW() + +Returns the field value to the power of `x`. + +```sql +POW(field_expression, x) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. +- **x**: Power to raise to. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `POW()` to a field with a power of 3" %}} + +```sql +SELECT + b, + POW(b, 3) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | pow | +| :------------------- | ------------------: | ---------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.004382205777325515 | +| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.002573288422171338 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.1126388541916811 | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0003885901893904874 | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 5.626222933751733 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.4071119474284653 | + +{{% /expand %}} + +{{% expand "Apply `POW()` to each field with a power of 5" %}} + +```sql +SELECT POW(*, 5) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | pow_a | pow_b | +| :------------------- | -------------------: | -----------------------: | +| 2023-01-01T00:00:00Z | 0.004483135555212479 | -0.00011735131084020357 | +| 2023-01-01T00:01:00Z | -0.2795528536239978 | 0.000048322282876973225 | +| 2023-01-01T00:02:00Z | -0.6628050073932118 | -0.026271227986693114 | +| 2023-01-01T00:03:00Z | -0.22011853819169455 | -0.000002069282189962477 | +| 2023-01-01T00:04:00Z | -0.6103699296012646 | 17.797604890097084 | +| 2023-01-01T00:05:00Z | -0.5620694808926487 | 0.22362640363833164 | + +{{% /expand %}} + +{{% expand "Apply `POW()` to time windows (grouped by time)" %}} + +```sql +SELECT + POW(SUM(a), 10) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | pow | +| :------------------- | -----------------------: | +| 2023-01-01T00:00:00Z | 2402278.159218532 | +| 2023-01-01T00:10:00Z | 12.380844221267186 | +| 2023-01-01T00:20:00Z | 0.000006244365466732681 | +| 2023-01-01T00:30:00Z | 0.0000046424621235691315 | +| 2023-01-01T00:40:00Z | 2.7973126174031977e-7 | +| 2023-01-01T00:50:00Z | 81.6292140233699 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ROUND() + +Returns a field value rounded to the nearest integer. + +```sql +ROUND(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `ROUND()` to a field" %}} + +```sql +SELECT + b, + ROUND(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | round | +| :------------------- | ------------------: | ----: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | -0 | +| 2023-01-01T00:01:00Z | 0.137034364053949 | 0 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | -0 | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0 | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 2 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | 1 | + +{{% /expand %}} + +{{% expand "Apply `ROUND()` to each field" %}} + +```sql +SELECT ROUND(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | round_a | round_b | +| :------------------- | ------: | ------: | +| 2023-01-01T00:00:00Z | 0 | -0 | +| 2023-01-01T00:01:00Z | -1 | 0 | +| 2023-01-01T00:02:00Z | -1 | -0 | +| 2023-01-01T00:03:00Z | -1 | -0 | +| 2023-01-01T00:04:00Z | -1 | 2 | +| 2023-01-01T00:05:00Z | -1 | 1 | + +{{% /expand %}} + +{{% expand "Apply `ROUND()` to time windows (grouped by time)" %}} + +```sql +SELECT + ROUND(SUM(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | round | +| :------------------- | ----: | +| 2023-01-01T00:00:00Z | -4 | +| 2023-01-01T00:10:00Z | 1 | +| 2023-01-01T00:20:00Z | 0 | +| 2023-01-01T00:30:00Z | 0 | +| 2023-01-01T00:40:00Z | 0 | +| 2023-01-01T00:50:00Z | 2 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## SIN() + +Returns the sine of a field value. + +```sql +SIN(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `SIN()` to a field" %}} + +```sql +SELECT + b, + SIN(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | sin | +| :------------------- | ------------------: | ------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.1629136686003898 | +| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13660588515594851 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.4643877941052164 | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.0729085450859347 | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 0.9784914502058565 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.6751348197618099 | + +{{% /expand %}} + +{{% expand "Apply `SIN()` to each field" %}} + +```sql +SELECT SIN(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | sin_a | sin_b | +| :------------------- | ------------------: | ------------------: | +| 2023-01-01T00:00:00Z | 0.3326300722640741 | -0.1629136686003898 | +| 2023-01-01T00:01:00Z | -0.6997047077914582 | 0.13660588515594851 | +| 2023-01-01T00:02:00Z | -0.7962295291135749 | -0.4643877941052164 | +| 2023-01-01T00:03:00Z | -0.673406844448706 | -0.0729085450859347 | +| 2023-01-01T00:04:00Z | -0.7870301289278495 | 0.9784914502058565 | +| 2023-01-01T00:05:00Z | -0.7778043295686337 | 0.6751348197618099 | + +{{% /expand %}} + +{{% expand "Apply `SIN()` to time windows (grouped by time)" %}} + +```sql +SELECT + SIN(SUM(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | sin | +| :------------------- | ------------------: | +| 2023-01-01T00:00:00Z | 0.933528830283535 | +| 2023-01-01T00:10:00Z | 0.9597472276784815 | +| 2023-01-01T00:20:00Z | 0.29712628761434723 | +| 2023-01-01T00:30:00Z | 0.2887011711003489 | +| 2023-01-01T00:40:00Z | 0.21934537994884437 | +| 2023-01-01T00:50:00Z | 0.9998424824522808 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## SQRT() + +Returns the square root of a field value. +Field values must be greater than or equal to 0. +Negative field values return null. + +```sql +SQRT(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `SQRT()` to a field" %}} + +```sql +SELECT + b, + SQRT(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | sqrt | +| :------------------- | ------------------: | -----------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | | +| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.370181528515334 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | | +| 2023-01-01T00:04:00Z | 1.77857552719844 | 1.3336324558132349 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.860899207349059 | + +{{% /expand %}} + +{{% expand "Apply `SQRT()` to each field" %}} + +```sql +SELECT SQRT(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | sqrt_a | sqrt_b | +| :------------------- | -----------------: | -----------------: | +| 2023-01-01T00:00:00Z | 0.5823152811928947 | | +| 2023-01-01T00:01:00Z | | 0.370181528515334 | +| 2023-01-01T00:02:00Z | | | +| 2023-01-01T00:03:00Z | | | +| 2023-01-01T00:04:00Z | | 1.3336324558132349 | +| 2023-01-01T00:05:00Z | | 0.860899207349059 | + +{{% /expand %}} + +{{% expand "Apply `SQRT()` to time windows (grouped by time)" %}} + +```sql +SELECT + SQRT(SUM(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | sqrt | +| :------------------- | -----------------: | +| 2023-01-01T00:00:00Z | | +| 2023-01-01T00:10:00Z | 1.134063865909604 | +| 2023-01-01T00:20:00Z | 0.5492555015405052 | +| 2023-01-01T00:30:00Z | 0.5411746169982342 | +| 2023-01-01T00:40:00Z | 0.4702589287652642 | +| 2023-01-01T00:50:00Z | 1.2462130097934059 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## TAN() + +Returns the tangent of the field value. + +```sql +TAN(field_expression) +``` + +#### Arguments + +- **field_expression**: Expression to identify one or more fields to operate on. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, or wildcard (`*`). + Supports numeric field types. + +#### Notable behaviors + +- [Must use aggregate or selector functions when grouping by time](#must-use-aggregate-or-selector-functions-when-grouping-by-time). + +#### Examples + +The following examples use the +[Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data). + +{{< expand-wrapper >}} +{{% expand "Apply `TAN()` to a field" %}} + +```sql +SELECT + b, + TAN(b) +FROM numbers +LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | b | tan | +| :------------------- | ------------------: | -------------------: | +| 2023-01-01T00:00:00Z | -0.163643058925645 | -0.16511961248511045 | +| 2023-01-01T00:01:00Z | 0.137034364053949 | 0.13789861917955581 | +| 2023-01-01T00:02:00Z | -0.482943221384294 | -0.5243575352718546 | +| 2023-01-01T00:03:00Z | -0.0729732928756677 | -0.07310309943905952 | +| 2023-01-01T00:04:00Z | 1.77857552719844 | -4.743341375725582 | +| 2023-01-01T00:05:00Z | 0.741147445214238 | 0.9151958486043346 | + +{{% /expand %}} + +{{% expand "Apply `TAN()` to each field" %}} + +```sql +SELECT TAN(*) FROM numbers LIMIT 6 +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | tan_a | tan_b | +| :------------------- | ------------------: | -------------------: | +| 2023-01-01T00:00:00Z | 0.3527145610408791 | -0.16511961248511045 | +| 2023-01-01T00:01:00Z | -0.9793857830953787 | 0.13789861917955581 | +| 2023-01-01T00:02:00Z | -1.3160934857179802 | -0.5243575352718546 | +| 2023-01-01T00:03:00Z | -0.9109052733075013 | -0.07310309943905952 | +| 2023-01-01T00:04:00Z | -1.2757522322802637 | -4.743341375725582 | +| 2023-01-01T00:05:00Z | -1.2375438046768912 | 0.9151958486043346 | + +{{% /expand %}} + +{{% expand "Apply `TAN()` to time windows (grouped by time)" %}} + +```sql +SELECT + TAN(SUM(a)) +FROM numbers +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-01-01T01:00:00Z' +GROUP BY time(10m) +``` + +{{% influxql/table-meta %}} +name: numbers +{{% /influxql/table-meta %}} + +| time | tan | +| :------------------- | ------------------: | +| 2023-01-01T00:00:00Z | -2.603968631156288 | +| 2023-01-01T00:10:00Z | 3.4171098358131733 | +| 2023-01-01T00:20:00Z | 0.31117972731464494 | +| 2023-01-01T00:30:00Z | 0.30154101138968664 | +| 2023-01-01T00:40:00Z | 0.22482036866737865 | +| 2023-01-01T00:50:00Z | 56.3338223288096 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/group-by.md b/content/shared/influxql-v3-reference/group-by.md new file mode 100644 index 000000000..a60b1ae0d --- /dev/null +++ b/content/shared/influxql-v3-reference/group-by.md @@ -0,0 +1,625 @@ +Use the `GROUP BY` clause to group data by one or more specified +[tags](/influxdb/version/reference/glossary/#tag) or into specified time intervals. +`GROUP BY` requires an [aggregate](/influxdb/version/reference/influxql/functions/aggregates/) +or [selector](/influxdb/version/reference/influxql/functions/selectors/) +function in the `SELECT` statement. + + + +- [Syntax](#syntax) +- [GROUP BY clause behaviors](#group-by-clause-behaviors) +- [GROUP BY tags](#group-by-tags) + - [GROUP BY tags examples](#group-by-tags-examples) +- [GROUP BY time](#group-by-time) + - [GROUP by time and fill gaps](#group-by-time-and-fill-gaps) + - [GROUP BY time examples](#group-by-time-examples) + - [GROUP BY time with offset](#group-by-time-with-offset) + - [GROUP BY time and fill gaps](#group-by-time-and-fill-gaps) +- [Result set](#result-set) + - [Default time range](#default-time-range) +- [Notable behaviors of the GROUP BY clause](#notable-behaviors-of-the-group-by-clause) + - [Cannot group by fields](#cannot-group-by-fields) + - [Tag order does not matter](#tag-order-does-not-matter) + - [Grouping by tag and no time range returns unexpected timestamps](#grouping-by-tag-and-no-time-range-returns-unexpected-timestamps) + - [Data grouped by time may return unexpected timestamps](#data-grouped-by-time-may-return-unexpected-timestamps) + - [Example data](#example-data) + - [Query results](#query-results) + - [Fill with no data in the queried time range](#fill-with-no-data-in-the-queried-time-range) + - [Fill with previous if no previous value exists](#fill-with-previous-if-no-previous-value-exists) + - [Fill with linear interpolation if there are not two values to interpolate between](#fill-with-linear-interpolation-if-there-are-not-two-values-to-interpolate-between) + + + +## Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_expression_n] +``` + +- **group_expression**: Expression to identify tags or time intervals to group by. + Can be a [tag key](/influxdb/version/reference/glossary/#tag-key), + constant, [regular expression](/influxdb/version/reference/influxql/regular-expressions/), + wildcard (`*`), or [function expression](/influxdb/version/reference/influxql/functions/). + +## GROUP BY clause behaviors + +- `GROUP BY tag_key` - Groups data by a specific tag +- `GROUP BY tag_key1, tag_key2` - Groups data by more than one tag +- `GROUP BY *` - Groups data by all [tags](/influxdb/version/reference/glossary/#tag) +- `GROUP BY /regex/` - Groups data by tag keys that match the regular expression +- `GROUP BY time()` - Groups data into time intervals (windows) + +> [!Note] +> If a query includes `WHERE` and `GROUP BY`, the `GROUP BY` clause must appear after +> the `WHERE` clause. + +## GROUP BY tags + +Groups data by one or more tag columns. + +### GROUP BY tags examples + +The following examples use the +[Bitcoin price sample data](/influxdb/version/reference/sample-data/#bitcoin-price-data). + +{{< expand-wrapper >}} + +{{% expand "Group data by a single tag" %}} + +```sql +SELECT MEAN(*) FROM bitcoin GROUP BY code +``` + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=EUR +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 27328.848667840004 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=GBP +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 23441.832453919982 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=USD +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 28054.160950480004 | + +{{% /expand %}} + +{{% expand "Group data by more than one tag" %}} + +```sql +SELECT MEAN(*) FROM bitcoin GROUP BY code, description +``` + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=EUR, description=Euro +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 27328.848667840004 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=GBP, description=British Pound Sterling +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 23441.832453919982 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=USD, description=United States Dollar +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 28054.160950480004 | + +{{% /expand %}} + +{{% expand "Group data by all tags" %}} + +```sql +SELECT MEAN(*) FROM bitcoin GROUP BY * +``` + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=EUR, crypto=bitcoin, description=Euro, symbol=€ +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 27328.848667840004 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=GBP, crypto=bitcoin, description=British Pound Sterling, symbol=£ +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 23441.832453919982 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=USD, crypto=bitcoin, description=United States Dollar, symbol=$ +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 28054.160950480004 | + +{{% /expand %}} + +{{% expand "Group data by tag keys that match a regular expression" %}} + +```sql +SELECT MEAN(*) FROM bitcoin GROUP BY /^[cd]/ +``` + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=EUR, crypto=bitcoin, description=Euro +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 27328.848667840004 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=GBP, crypto=bitcoin, description=British Pound Sterling +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 23441.832453919982 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=USD, crypto=bitcoin, description=United States Dollar +{{% /influxql/table-meta %}} + +| time | mean_price | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 28054.160950480004 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## GROUP BY time + +`GROUP BY time()` groups data by into specified time intervals, also known as "windows", +and applies the [aggregate](/influxdb/version/reference/influxql/functions/aggregates/) +and [selector](/influxdb/version/reference/influxql/functions/selectors/) +functions in the `SELECT` clause to each interval. +Use the [`time()` function](/influxdb/version/reference/influxql/functions/date-time/#time) +to specify the time interval to group by. + +```sql +SELECT_clause FROM_clause WHERE GROUP BY time(time_interval[, offset])[, group_expression (...)] [fill(behavior)] +``` + +`GROUP BY time()` intervals use preset round-number time boundaries that +are independent of time conditions in the [`WHERE` clause](/influxdb/version/reference/influxql/where/). +**Output data uses window start boundaries as the aggregate timestamps.** +Use the `offset` argument of the `time()` function to shift time boundaries forward or +backward in time. + +### GROUP by time and fill gaps + +When grouping by time, if a window in the queried time range does not contain data, +results return a row for the empty window containing the timestamp of the empty +window and _null_ values for each queried field. +Use the [`fill()` function](/influxdb/version/reference/influxql/functions/misc/#fill) +_at the end of the `GROUP BY` clause_ to replace _null_ field values. +If no `FILL` clause is included, the default behavior is `fill(null)`. + +`fill()` provides the following behaviors for filling values: + +- **numeric literal**: Replaces null values with the specified numeric literal. +- **linear**: Uses linear interpolation between existing values to replace null values. +- **none**: Removes rows with null field values. +- **null**: Keeps null values and associated timestamps. +- **previous**: Replaces null values with the most recent non-null value. + +_See the [`fill()` documentation](/influxdb/version/reference/influxql/functions/misc/#fill) +for detailed examples._ + +### GROUP BY time examples + +The following examples use the +[Bitcoin price sample data](/influxdb/version/reference/sample-data/#bitcoin-price-data). + +{{< expand-wrapper >}} + +{{% expand "Group and aggregate query results into 1 hour windows" %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-15T00:00:00Z' +GROUP BY time(1h) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 2023-05-01T00:00:00Z | 24494.27265 | +| 2023-05-01T01:00:00Z | 24452.1698 | +| 2023-05-01T02:00:00Z | 23902.666124999996 | +| 2023-05-01T03:00:00Z | 23875.211349999998 | +| 2023-05-01T04:00:00Z | 23855.6441 | +| ... | ... | + + +{{% /expand %}} + +{{% expand "Group and aggregate query results into 1 week intervals by tag" %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-15T00:00:00Z' +GROUP BY time(1w), code +``` + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=EUR +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 2023-04-27T00:00:00Z | 27681.21808576779 | +| 2023-05-04T00:00:00Z | 27829.413580354256 | +| 2023-05-11T00:00:00Z | 26210.24799033149 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=GBP +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 2023-04-27T00:00:00Z | 23744.083925842704 | +| 2023-05-04T00:00:00Z | 23871.201395652173 | +| 2023-05-11T00:00:00Z | 22482.33174723755 | + +{{% influxql/table-meta %}} +name: bitcoin +tags: code=USD +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 2023-04-27T00:00:00Z | 28415.88231123595 | +| 2023-05-04T00:00:00Z | 28568.010941384844 | +| 2023-05-11T00:00:00Z | 26905.87242099449 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +###### GROUP BY time with offset + +{{< expand-wrapper >}} +{{% expand "Group and aggregate query results into 1 hour intervals and offset time boundaries by +15 minutes" %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-02T00:00:00Z' +GROUP BY time(1h, 15m) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 2023-04-30T23:15:00Z | | +| 2023-05-01T00:15:00Z | 29313.6754 | +| 2023-05-01T01:15:00Z | 28932.0882 | +| 2023-05-01T02:15:00Z | 28596.375225000003 | +| 2023-05-01T03:15:00Z | 28578.915075 | +| ... | ... | + +_Note that `offset` forces the first time boundary to be outside +the queried time range so the query returns no results for that first interval._ + +{{% /expand %}} + +{{% expand "Group and aggregate query results into 1 hour intervals and offset time boundaries by -15 minutes" %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-02T00:00:00Z' +GROUP BY time(1h, -15m) +``` +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 2023-04-30T23:45:00Z | 29319.9092 | +| 2023-05-01T00:45:00Z | 29285.3651 | +| 2023-05-01T01:45:00Z | 28607.202666666668 | +| 2023-05-01T02:45:00Z | 28576.056175 | +| 2023-05-01T03:45:00Z | 28566.96315 | +| ... | ... | + +{{% /expand %}} +{{< /expand-wrapper >}} + +###### GROUP BY time and fill gaps + +{{< expand-wrapper >}} +{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps with `0`" %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-01T02:00:00Z' +GROUP BY + time(30m) + fill(0) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| -------------------- | ---------- | +| 2023-05-01T00:00:00Z | 29319.9092 | +| 2023-05-01T00:30:00Z | 29307.4416 | +| 2023-05-01T01:00:00Z | 0 | +| 2023-05-01T01:30:00Z | 29263.2886 | + +{{% /expand %}} + +{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps using linear interpolation" %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-01T02:00:00Z' +GROUP BY + time(30m) + fill(linear) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| -------------------- | ---------- | +| 2023-05-01T00:00:00Z | 29319.9092 | +| 2023-05-01T00:30:00Z | 29307.4416 | +| 2023-05-01T01:00:00Z | 29285.3651 | +| 2023-05-01T01:30:00Z | 29263.2886 | + +{{% /expand %}} + +{{% expand "Group and aggregate query results into 30 minute intervals and fill gaps with previous values" %}} + +```sql +SELECT + MEAN(price) +FROM bitcoin +WHERE + code = 'USD' + AND time >= '2023-05-01T00:00:00Z' + AND time < '2023-05-01T02:00:00Z' +GROUP BY + time(30m) + fill(previous) +``` + +{{% influxql/table-meta %}} +name: bitcoin +{{% /influxql/table-meta %}} + +| time | mean | +| -------------------- | ---------- | +| 2023-05-01T00:00:00Z | 29319.9092 | +| 2023-05-01T00:30:00Z | 29307.4416 | +| 2023-05-01T01:00:00Z | 29307.4416 | +| 2023-05-01T01:30:00Z | 29263.2886 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Result set + +If at least one row satisfies the query, {{% product-name %}} returns row data in the query result set. +If a query uses a `GROUP BY` clause, the result set includes the following: + +- Columns listed in the query's `SELECT` clause +- A `time` column that contains the timestamp for the record or the group +- An `iox::measurement` column that contains the record's measurement (table) name +- Columns listed in the query's `GROUP BY` clause; each row in the result set contains the values used for grouping + +### Default time range + +If a query doesn't specify a time range in the +[`WHERE` clause](/influxdb/version/reference/influxql/where/), InfluxDB uses the +[default time range](/influxdb/version/reference/influxql/#default-time-range) for filtering and grouping by time. +If a query includes the `GROUP BY` clause and doesn't specify a time range in the +`WHERE` clause, the default time group is the +[default time range](/influxdb/version/reference/influxql/#default-time-range), and the `time` column in the result set contains the start of the range--for example: + +```sql +SELECT mean(temp) FROM home GROUP BY room +``` + +{{% influxql/table-meta %}} +name: home +tags: room=Kitchen +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 22.623076923076926 | + +{{% influxql/table-meta %}} +name: home +tags: room=Living Room +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ----------------: | +| 1970-01-01T00:00:00Z | 22.16923076923077 | + +## Notable behaviors of the GROUP BY clause + +### Cannot group by fields + +InfluxQL does not support grouping data by **fields**. + +### Tag order does not matter + +The order that tags are listed in the `GROUP BY` clause does not affect how +data is grouped. + +### Grouping by tag and no time range returns unexpected timestamps + +The `time` column contains the start of the [default time range](#default-time-range). + +### Data grouped by time may return unexpected timestamps + +Because `GROUP BY time()` intervals use preset round-number time boundaries that +are independent of time conditions in the [`WHERE` clause](/influxdb/version/reference/influxql/where/), +results may include timestamps outside of the queried time range. +Results represent only data with timestamps in the specified time range, but +output timestamps are determined by by the preset time boundaries. + +The following example groups data by 1-hour intervals, but the time range defined +in the `WHERE` clause covers only part of a window: + +```sql +SELECT MEAN(field) +FROM example +WHERE + time >= '2022-01-01T00:30:00Z' + AND time <= '2022-01-01T01:30:00Z' +GROUP BY time(1h) +``` + +> [!Note] +> **Note**: The timestamp in the first row of query results data occurs before the start of +> the queried time range. +> [See why](#why-do-these-results-include-timestamps-outside-of-the-queried-time-range). + +{{% influxdb/custom-timestamps %}} +{{< flex >}} +{{% flex-content %}} +#### Example data + +| time | field | +| :------------------- | ----: | +| 2022-01-01T00:00:00Z | 8 | +| 2022-01-01T00:15:00Z | 4 | +| 2022-01-01T00:30:00Z | 0 | +| 2022-01-01T00:45:00Z | 8 | +| 2022-01-01T01:00:00Z | 5 | +| 2022-01-01T01:15:00Z | 0 | +| 2022-01-01T01:30:00Z | 8 | +| 2022-01-01T01:45:00Z | 8 | +| 2022-01-01T02:00:00Z | 9 | +| 2022-01-01T02:15:00Z | 6 | +| 2022-01-01T02:30:00Z | 3 | +| 2022-01-01T02:45:00Z | 0 | + +{{% /flex-content %}} +{{% flex-content %}} + +#### Query results + +| time | field | +| :------------------- | ----: | +| 2022-01-01T00:00:00Z | 4 | +| 2022-01-01T01:00:00Z | 5.25 | +| 2022-01-01T02:00:00Z | 6 | + +{{% /flex-content %}} +{{< /flex >}} +{{% /influxdb/custom-timestamps %}} + +{{< expand-wrapper >}} +{{% expand "Why do these results include timestamps outside of the queried time range?" %}} + +`GROUP BY time()` creates windows with predefined time boundaries based on the +specified interval. These boundaries are not determined by the queried time +range, however, aggregate values in query results are calculated using only +values that are in the queried time range. + +{{< html-diagram/influxql-windows >}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +### Fill with no data in the queried time range + +Queries ignore `fill()` if no data exists in the queried time range. +This is the expected behavior. + +### Fill with previous if no previous value exists + +`fill(previous)` doesn’t fill null values if there is no previous value in +the queried time range. + +### Fill with linear interpolation if there are not two values to interpolate between + +`fill(linear)` doesn't fill null values if there are no values before or after +the null value in the queried time range. diff --git a/content/shared/influxql-v3-reference/internals.md b/content/shared/influxql-v3-reference/internals.md new file mode 100644 index 000000000..e4395592d --- /dev/null +++ b/content/shared/influxql-v3-reference/internals.md @@ -0,0 +1,154 @@ +Learn about the implementation of InfluxQL to understand how +results are processed and how to create efficient queries: + +- [Query life cycle](#query-life-cycle) +- [Understanding iterators](#understanding-iterators) +- [Cursors](#cursors) +- [Auxiliary fields](#auxiliary-fields) +- [Built-in iterators](#built-in-iterators) +- [Call iterators](#call-iterators) + +## Query life cycle + +1. InfluxQL query string is tokenized and then parsed into an abstract syntax + tree (AST). This is the code representation of the query itself. + +2. The AST is passed to the `QueryExecutor` which directs queries to the + appropriate handlers. For example, queries related to meta data are executed + by the **meta service** and `SELECT` statements are executed by the shards + themselves. + +3. The query engine then determines the shards that match the `SELECT` + statement's time range. From these shards, iterators are created for each + field in the statement. + +4. Iterators are passed to the emitter which drains them and joins the resulting + points. The emitter's job is to convert simple time/value points into the + more complex result objects that are returned to the client. + +### Understanding iterators + +Iterators provide a simple interface for looping over a set of points. +For example, this is an iterator over Float points: + +``` +type FloatIterator interface { + Next() *FloatPoint +} +``` + +These iterators are created through the `IteratorCreator` interface: + +``` +type IteratorCreator interface { + CreateIterator(opt *IteratorOptions) (Iterator, error) +} +``` + +The `IteratorOptions` provide arguments about field selection, time ranges, +and dimensions that the iterator creator can use when planning an iterator. +The `IteratorCreator` interface is used at many levels such as the `Shards`, +`Shard`, and `Engine`. This allows optimizations to be performed when applicable +such as returning a precomputed `COUNT()`. + +Iterators aren't just for reading raw data from storage, though. Iterators can be +composed so that they provide additional functionality around an input +iterator. For example, a `DistinctIterator` can compute the distinct values for +each time window for an input iterator. Or a `FillIterator` can generate +additional points that are missing from an input iterator. + +This composition also lends itself well to aggregation. +For example, in the following SQL, `MEAN(value)` is a `MeanIterator` that wraps an iterator from the +underlying shards: + +```sql +SELECT MEAN(value) FROM cpu GROUP BY time(10m) +``` + +The following example wraps `MEAN(value)` with an additional iterator (`DERIVATIVE()`) to determine +the derivative of the mean: + +```sql +SELECT DERIVATIVE(MEAN(value), 20m) FROM cpu GROUP BY time(10m) +``` + +### Cursors + +A **cursor** identifies data by shard in tuples (time, value) for a single series (measurement, tag set and field). The cursor traverses data stored as a log-structured merge-tree and handles deduplication across levels, tombstones for deleted data, and merging the cache (Write Ahead Log). A cursor sorts the `(time, value)` tuples by time in ascending or descending order. + +For example, a query that evaluates one field for 1,000 series over 3 shards constructs a minimum of 3,000 cursors (1,000 per shard). + +### Auxiliary fields + +Because InfluxQL allows users to use selector functions such as `FIRST()`, +`LAST()`, `MIN()`, and `MAX()`, the engine must provide a way to return related +data at the same time with the selected point. + +Let's look at the following query: + +```sql +SELECT FIRST(value), host FROM cpu GROUP BY time(1h) +``` + +We are selecting the first `value` that occurs every hour but we also want to +retrieve the `host` associated with that point. Since the `Point` types only +specify a single typed `Value` for efficiency, we push the `host` into the +auxiliary fields of the point. These auxiliary fields are attached to the point +until it is passed to the emitter where the fields get split off to their own +iterator. + +### Built-in iterators + +There are many helper iterators that let us build queries: + +* Merge Iterator - This iterator combines one or more iterators into a single + new iterator of the same type. This iterator guarantees that all points + within a window will be output before starting the next window, but does not + provide ordering guarantees within the window. This allows for fast access + for aggregate queries that don't need stronger sorting guarantees. + +* Sorted Merge Iterator - Like `MergeIterator`, this iterator combines one or more iterators + into a new iterator of the same type. However, this iterator guarantees + time ordering of every point. This makes it slower than the `MergeIterator` + but this ordering guarantee is required for non-aggregate queries which + return the raw data points. + +* Limit Iterator - This iterator limits the number of points per name or tag + group. This is the implementation of the `LIMIT` & `OFFSET` syntax. + +* Fill Iterator - This iterator injects extra points if they are missing from + the input iterator. It can provide `null` points, points with the previous + value, or points with a specific value. + +* Buffered Iterator - This iterator provides the ability to "unread" a point + back onto a buffer so it can be read again next time. This is used extensively + to provide lookahead for windowing. + +* Reduce Iterator - This iterator calls a reduction function for each point in + a window. When the window is complete, then all points for that window are + output. This is used for simple aggregate functions such as `COUNT()`. + +* Reduce Slice Iterator - This iterator collects all points for a window first, + and then passes them all to a reduction function at once. The results are + returned from the iterator. This is used for aggregate functions such as + `DERIVATIVE()`. + +* Transform Iterator - This iterator calls a transform function for each point + from an input iterator. This is used for executing binary expressions. + +* Dedupe Iterator - This iterator only outputs unique points. Because it is resource-intensive, this iterator is only used for small queries such as meta query statements. + +### Call iterators + +Function calls in InfluxQL are implemented at two levels: + +- Some calls can be +wrapped at multiple layers to improve efficiency. For example, a `COUNT()` can +be performed at the shard level and then multiple `CountIterator`s can be +wrapped with another `CountIterator` to compute the count of all shards. These +iterators can be created using `NewCallIterator()`. + +- Some iterators are more complex or need to be implemented at a higher level. +For example, the `DERIVATIVE()` function needs to retrieve all points for a window +before performing the calculation. This iterator is created by the engine itself +and is never requested to be created by the lower levels. diff --git a/content/shared/influxql-v3-reference/limit-and-slimit.md b/content/shared/influxql-v3-reference/limit-and-slimit.md new file mode 100644 index 000000000..3b3ffae34 --- /dev/null +++ b/content/shared/influxql-v3-reference/limit-and-slimit.md @@ -0,0 +1,242 @@ +Use `LIMIT` to limit the number of **rows** returned per InfluxQL group. +Use `SLIMIT` to limit the number of [series](/influxdb/version/reference/glossary/#series) +returned in query results. + +- [LIMIT clause](#limit-clause) + - [Syntax](#limit-syntax) + - [Examples](#limit-examples) +- [SLIMIT clause](#slimit-clause) + + + + + + +## LIMIT clause + +The `LIMIT` clause limits the number of rows to return from each InfluxQL group. +If the query doesn't include a [`GROUP BY` clause](/influxdb/version/reference/influxql/group-by/), +the entire result set is considered a single group. +If a query [groups data by time](/influxdb/version/reference/influxql/group-by/#group-by-time), +limits are applied after aggregate and selector operations are applied to each +time window. + +### Syntax {#limit-syntax} + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT N +``` + +#### Arguments + +- **N**: Maximum number of points to return from each InfluxQL group. + If `N` is greater than the number of points in a group, + all points from the group are returned. + +### Examples {#limit-examples} + +The following examples use the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +{{< expand-wrapper >}} + +{{% expand "Limit the number of rows returned" %}} + +```sql +SELECT * FROM home LIMIT 3 +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :---------- | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Limit the number of rows returned from each InfluxQL group" %}} + +```sql +SELECT + MEAN(*) +FROM home +GROUP BY + time(2h), + room +LIMIT 3 +``` + +{{% influxdb/custom-timestamps %}} +{{% influxql/table-meta %}} +name: home +tags: room=Kitchen +{{% /influxql/table-meta %}} + +| time | mean_co | mean_hum | mean_temp | +| :------------------- | ------: | -------: | -----------------: | +| 2022-01-01T08:00:00Z | 0 | 36.05 | 22 | +| 2022-01-01T10:00:00Z | 0 | 36.05 | 22.549999999999997 | +| 2022-01-01T12:00:00Z | 0.5 | 36.25 | 22.65 | + +{{% influxql/table-meta %}} +name: home +tags: room=Living Room +{{% /influxql/table-meta %}} + +| time | mean_co | mean_hum | mean_temp | +| :------------------- | ------: | -------: | -----------------: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | 21.25 | +| 2022-01-01T10:00:00Z | 0 | 36 | 22 | +| 2022-01-01T12:00:00Z | 0 | 35.95 | 22.299999999999997 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{< /expand-wrapper >}} + +## SLIMIT clause + +> [!Important] +> InfluxQL is being rearchitected to work with the InfluxDB v3 storage engine. +> This process is ongoing and some InfluxQL features, such as `SLIMIT` are still +> being implemented. For more information, see +> [InfluxQL feature support](/influxdb/version/reference/influxql/feature-support/). + + diff --git a/content/shared/influxql-v3-reference/math-operators.md b/content/shared/influxql-v3-reference/math-operators.md new file mode 100644 index 000000000..05d679a65 --- /dev/null +++ b/content/shared/influxql-v3-reference/math-operators.md @@ -0,0 +1,268 @@ +Use InfluxQL mathematical operators to perform mathematical operations in InfluxQL queries. +Mathematical operators follow the [standard order of operations](https://golang.org/ref/spec#Operator_precedence). +Parentheses take precedence to division and multiplication, which takes precedence to addition and subtraction. +For example `5 / 2 + 3 * 2 = (5 / 2) + (3 * 2)` and `5 + 2 * 3 - 2 = 5 + (2 * 3) - 2`. + +- [Addition](#addition) +- [Subtraction](#subtraction) +- [Multiplication](#multiplication) +- [Division](#division) +- [Modulo](#modulo) +- [Bitwise AND](#bitwise-and) +- [Bitwise OR](#bitwise-or) +- [Bitwise Exclusive-OR](#bitwise-exclusive-or) +- [Unsupported Operators](#unsupported-operators) +- [Notable behaviors of mathematical operators](#notable-behaviors-of-mathematical-operators) + +## Addition + +Add two numeric operands. Operands may be an identifier, constant, or literal +numeric value. + +```sql +SELECT A + 5 FROM example + +SELECT A + B FROM example + +SELECT * FROM example WHERE A + 5 > 10 + +SELECT * FROM example WHERE A + B > 10 +``` + +## Subtraction + +Subtract one numeric operand from another. Operands may be an identifier, +constant, or literal numeric value. + +```sql +SELECT 1 - A FROM example + +SELECT B - A FROM example + +SELECT * FROM example WHERE 1 - A <= 3 + +SELECT * FROM example WHERE B - A <= 3 +``` + +## Multiplication + +Multiply two numeric operands. Operands may be an identifier, constant, or literal +numeric value. + +```sql +SELECT A * 10 FROM example + +SELECT A * B FROM example + +SELECT * FROM example WHERE A * 10 >= 20 + +SELECT * FROM example WHERE A * B >= 20 +``` + +Multiplication distributes across other operators. + +```sql +SELECT 10 * (A + B + C) FROM example + +SELECT 10 * (A - B - C) FROM example + +SELECT 10 * (A + B - C) FROM example +``` + +## Division + +Divide one numeric operand by another. Operands may be an identifier, constant, +or literal numeric value. + +```sql +SELECT A / 10 FROM example + +SELECT A / B FROM example + +SELECT * FROM example WHERE A / 10 <= 2 + +SELECT * FROM example WHERE A / B <= 2 +``` + +Division distributes across other operators. + +```sql +SELECT 10 / (A + B + C) FROM example + +SELECT 10 / (A - B - C) FROM example + +SELECT 10 / (A + B - C) FROM example +``` + +## Modulo + +Perform a modulo operation with two numeric operands. Operands may be an +identifier, constant, or literal numeric value. + +```sql +SELECT A % 2 FROM example + +SELECT A % B FROM example + +SELECT A FROM example WHERE A % 2 = 0 + +SELECT A, B FROM example WHERE A % B = 0 +``` + +## Bitwise AND + +Perform a bitwise `AND` operation on two operands _of the same type_. +Supported types are **integers** and **booleans**. +Operands may be an identifier, constant, literal integer value, or literal boolean value. + +```sql +SELECT A & 255 FROM example + +SELECT A & B FROM example + +SELECT (A ^ true) & B FROM example + +SELECT * FROM example WHERE A & 15 > 0 +``` + +## Bitwise OR + +Perform a bitwise `OR` operation on two operands _of the same type_. +Supported types are **integers** and **booleans**. +Operands may be an identifier, constant, literal integer value, or literal boolean value. + +```sql +SELECT A | 5 FROM example + +SELECT A | B FROM example + +SELECT * FROM example WHERE "bitfield" | 12 = 12 +``` + +## Bitwise Exclusive-OR + +Perform a bitwise `Exclusive-OR` operation on two operands _of the same type_. +Supported types are **integers** and **booleans**. +Operands may be an identifier, constant, literal integer value, or literal boolean value. + +```sql +SELECT A ^ 255 FROM example + +SELECT A ^ B FROM example + +SELECT * FROM example WHERE "bitfield" ^ 6 > 0 +``` + +## Unsupported Operators + +### Inequalities + +Using any of `=`,`!=`,`<`,`>`,`<=`,`>=`,`<>` in the `SELECT` statement yields +empty results for all types. +Comparison operators can only be used in the `WHERE` clause. + +### Logical Operators + +Using any of `!|`,`NAND`,`XOR`,`NOR` yield a parser error. + +Additionally using `AND`, `OR` in the `SELECT` clause of a query will not behave +as mathematical operators and simply yield empty results, as they are InfluxQL tokens. +However, you can apply the bitwise operators `&`, `|` and `^` to boolean values. + +### Bitwise Not + +There is no bitwise-not operator, because the results you expect depend on the width of your bitfield. +InfluxQL does not know how wide your bitfield is, so cannot implement a suitable +bitwise-not operator. + +For example, if your bitfield is 8 bits wide, then the integer 1 represents the bits `0000 0001`. +The bitwise-not of this should return the bits `1111 1110` (that is, the integer 254) +However, if your bitfield is 16 bits wide, then the integer 1 represents the bits `0000 0000 0000 0001`. +The bitwise-not of this should return the bits `1111 1111 1111 1110` (that is, the integer 65534) + +#### Solution + +You can implement a bitwise-not operation by using the `^` (bitwise xor) operator +together with the number representing all-ones for your word-width: + +For 8-bit data: + +```sql +SELECT A ^ 255 FROM example +``` + +For 16-bit data: + +```sql +SELECT A ^ 65535 FROM example +``` + +For 32-bit data: + +```sql +SELECT A ^ 4294967295 FROM example +``` + +In each case, the constant you need can be calculated as `(2 ** width) - 1`. + +## Notable behaviors of mathematical operators + +- [Mathematical operators with wildcards and regular expressions](#mathematical-operators-with-wildcards-and-regular-expressions) +- [Mathematical operators with functions](#mathematical-operators-with-functions) + +### Mathematical operators with wildcards and regular expressions + +InfluxQL does not support combining mathematical operations with a wildcard (`*`) +or [regular expression](/influxdb/version/reference/influxql/regular-expressions/) +in the `SELECT` clause. +The following queries are invalid and the output is an error: + +Perform a mathematical operation on a wildcard. + +```sql +SELECT * + 2 FROM "nope" +-- ERR: unsupported expression with wildcard: * + 2 +``` + +Perform a mathematical operation on a wildcard within a function. + +```sql +SELECT COUNT(*) / 2 FROM "nope" +-- ERR: unsupported expression with wildcard: count(*) / 2 +``` + +Perform a mathematical operation on a regular expression. + +```sql +SELECT /A/ + 2 FROM "nope" +-- ERR: error parsing query: found +, expected FROM at line 1, char 12 +``` + +Perform a mathematical operation on a regular expression within a function. + +```sql +SELECT COUNT(/A/) + 2 FROM "nope" +-- ERR: unsupported expression with regex field: count(/A/) + 2 +``` + +### Mathematical operators with functions + +InfluxQL does not support mathematical operators inside of function calls. +Note that InfluxQL only allows functions in the `SELECT` clause. + +For example, the following will work: + +```sql +SELECT 10 * mean("value") FROM "cpu" +``` + +However, the following query will return a parse error: + +```sql +SELECT mean(10 * "value") FROM "cpu" +-- Error: expected field argument in mean() +``` + +> [!Tip] +> InfluxQL supports [subqueries](/influxdb/v2/query-data/influxql/explore-data/subqueries/) +> which offer similar functionality to using mathematical operators inside a function call. diff --git a/content/shared/influxql-v3-reference/offset-and-soffset.md b/content/shared/influxql-v3-reference/offset-and-soffset.md new file mode 100644 index 000000000..2df0fe35b --- /dev/null +++ b/content/shared/influxql-v3-reference/offset-and-soffset.md @@ -0,0 +1,224 @@ +Use `OFFSET` to specify the number of [rows](/influxdb/version/reference/glossary/#series) +to skip in each InfluxQL group before returning results. +Use `SOFFSET` to specify the number of [series](/influxdb/version/reference/glossary/#series) +to skip before returning results. + + - [OFFSET clause](#offset-clause) + - [Syntax](#offset-syntax) + - [Notable OFFSET clause behaviors](#notable-offset-clause-behaviors) + - [Examples](#offset-examples) + - [SOFFSET clause](#soffset-clause) + + + + +## `OFFSET` clause + +The `OFFSET` clause skips `N` rows in each InfluxQL group before returning results. +Offsets honor row limits specified in the +[`LIMIT` clause](/influxdb/version/reference/influxql/limit-and-slimit/#limit-clause) +and display the limited number of rows after the specified offset. +Use `LIMIT` and `OFFSET` together to paginate query results. + +### Syntax {#offset-syntax} + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] OFFSET N [SLIMIT_clause] [SOFFSET_clause] +``` + +#### Arguments + +- **N**: Number of rows to skip in each InfluxQL group before returning results. + +### Notable OFFSET clause behaviors + +- If there is no `LIMIT` clause in a query with an `OFFSET` clause, the query + returns a single row per InfluxQL group at the specified offset. +- If the query doesn't include a [`GROUP BY` clause](/influxdb/version/reference/influxql/group-by/), + the entire result set is considered a single group and is returned in full. +- If a query [groups data by time](/influxdb/version/reference/influxql/group-by/#group-by-time), + the offset is applied after aggregate and selector operations are applied to each + time window. +- If the [`WHERE` clause](/influxdb/version/reference/influxql/where/) + includes a time range and the `OFFSET` clause causes InfluxQL to return points + with timestamps outside of that time range, InfluxQL returns no results. + +### Examples {#offset-examples} + +The following examples use the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +{{< expand-wrapper >}} + +{{% expand "Return the nth row" %}} + +```sql +SELECT * FROM home OFFSET 3 +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :---------- | ---: | +| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Paginate results by 3 and return the 2nd page of results" %}} + +```sql +SELECT * FROM home WHERE room = 'Kitchen' LIMIT 3 OFFSET 3 +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :------ | ---: | +| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | +| 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Paginate results from each series by 3 and return the 2nd page of each series" %}} + +```sql +SELECT * FROM home GROUP BY * LIMIT 3 OFFSET 3 +``` + +{{% influxdb/custom-timestamps %}} + +{{% influxql/table-meta %}} +name: home +tags: room=Kitchen +{{% /influxql/table-meta %}} + +| time | co | hum | temp | +| :------------------- | --: | ---: | ---: | +| 2022-01-01T11:00:00Z | 0 | 36 | 22.4 | +| 2022-01-01T12:00:00Z | 0 | 36 | 22.5 | +| 2022-01-01T13:00:00Z | 1 | 36.5 | 22.8 | + +{{% influxql/table-meta %}} +name: home +tags: room=Living Room +{{% /influxql/table-meta %}} + +| time | co | hum | temp | +| :------------------- | --: | ---: | ---: | +| 2022-01-01T11:00:00Z | 0 | 36 | 22.2 | +| 2022-01-01T12:00:00Z | 0 | 35.9 | 22.2 | +| 2022-01-01T13:00:00Z | 0 | 36 | 22.4 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{< /expand-wrapper >}} + +## `SOFFSET` clause + +> [!Important] +> InfluxQL is being rearchitected to work with the InfluxDB v3 storage engine. +> This process is ongoing and some InfluxQL features, such as `SOFFSET` are still +> being implemented. For more information, see +> [InfluxQL feature support](/influxdb/version/reference/influxql/feature-support/). + + diff --git a/content/shared/influxql-v3-reference/order-by.md b/content/shared/influxql-v3-reference/order-by.md new file mode 100644 index 000000000..7942e9119 --- /dev/null +++ b/content/shared/influxql-v3-reference/order-by.md @@ -0,0 +1,91 @@ +Use the `ORDER BY` clause to sort data by time in ascending or descending order. +InfluxQL only supports sorting data by `time`. + +- [Syntax](#syntax) +- [Examples](#examples) + +## Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [ASC|DESC] +``` + +- If the the `ORDER BY` clause is not included, the default behavior is to sort data by + time in **ascending** order: `ORDER BY time ASC`. +- If the query includes [`WHERE`](/influxdb/version/reference/influxql/where/) + and [`GROUP BY`](/influxdb/version/reference/influxql/group-by/) clauses, + the `ORDER BY` clause must come **after** these clauses. + +#### Sort orders + +- **ASC (ascending)**: The first row in the results has the oldest timestamp. + The last row in the results has the most recent timestamp. +- **DESC (descending)**: The first row in the results has the most recent timestamp. + The last row in the results has the oldest timestamp. + +## Examples + +The following examples use the +[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +{{< expand-wrapper >}} + +{{% expand "Sort data with the oldest points first" %}} + +> [!Tip] +> Ordering data by time in ascending order is the default behavior. +> Including `ORDER BY time ASC` in the query isn't necessary, but it is supported. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +ORDER BY time ASC +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :------ | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Sort data with the newest points first" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +ORDER BY time DESC +``` + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :------ | ---: | +| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | +| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{< /expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/quoting.md b/content/shared/influxql-v3-reference/quoting.md new file mode 100644 index 000000000..9bbc3ebe6 --- /dev/null +++ b/content/shared/influxql-v3-reference/quoting.md @@ -0,0 +1,42 @@ +InfluxQL supports both single and double quotation marks, but they each function +differently and serve different purposes. + +- [Single quotes](#single-quotes) +- [Double quotes](#double-quotes) + +## Single quotes + +Use single quotation marks (`'`) in the +[string literal](/influxdb/version/reference/influxql/#strings) and +[timestamp literal](/influxdb/version/reference/influxql/#dates--times) syntax. + +In the following example, the `WHERE` clause evaluates the value of the `room` tag. +Tags only contain string values, so the right operand of the predicate expression +should be a string literal. + +```sql +... WHERE room = 'Kitchen' +``` + +## Double quotes + +Use double quotation marks (`"`) to quote [identifiers](/influxdb/version/reference/influxql/#identifiers). +Identifiers **must** be double-quoted in the following cases: + +- The identifier contains non-word characters. + Word characters are defined as `[a-z,A-Z,0-9,_]`. +- The identifier is case-sensitive. +- The identifier contains [InfluxQL keywords](/influxdb/version/reference/influxql/#keywords). +- The identifier begins with a digit. + +Double-quoted identifiers can also: + +- Contain any Unicode character except for a new line. +- Contain escaped `"` characters (for example: `\"`). +- Include [InfluxQL keywords](/influxdb/version/reference/influxql/#keywords). + +**While not always necessary, we recommend that you double quote identifiers.** + +> [!Important] +> InfluxQL quoting guidelines differ from +> [line protocol quoting guidelines](/influxdb/version/reference/syntax/line-protocol/#quotes). diff --git a/content/shared/influxql-v3-reference/regular-expressions.md b/content/shared/influxql-v3-reference/regular-expressions.md new file mode 100644 index 000000000..13acb02c6 --- /dev/null +++ b/content/shared/influxql-v3-reference/regular-expressions.md @@ -0,0 +1,193 @@ +Regular expressions are a sequence of characters used to identify patterns in +identifiers and string values. +InfluxQL supports regular expressions in the following operations: + +- Identifying **fields** and **tags** to query in the + [`SELECT` clause](/influxdb/version/reference/influxql/select/). +- Identifying **measurements** to query in the + [`FROM` clause](/influxdb/version/reference/influxql/select/#from-clause). +- Testing **tag values** and **string field values** in the + [`WHERE` clause](/influxdb/version/reference/influxql/where/). +- Identifying **tag keys** to group by in the + [`GROUP BY` clause](/influxdb/version/reference/influxql/group-by/) + +> [!Important] +> +> #### Query performance +> +> Regular expression comparisons are more computationally intensive than exact +> string comparisons. Queries with regular expressions are not as performant +> as those without. + +## Regular expression syntax + +InfluxQL Regular expressions are surrounded by `/` characters and use the +[Go regular expression syntax](http://golang.org/pkg/regexp/syntax/). + +```sql +/regular_expression/ +``` + +### Regular expression flags + +Regular expression flags modify the pattern-matching behavior of the expression. +InfluxQL supports the following regular expression flags: + +| Flag | Description | +| :--- | :------------------------------------------------------------------------------ | +| i | case-insensitive | +| m | multi-line mode: `^` and `$` match begin/end line in addition to begin/end text | +| s | let `.` match `\n` | +| U | ungreedy: swap meaning of `x*` and `x*?`, `x+` and `x+?`, etc. | + +Include regular expression flags at the beginning of your regular expression +pattern enclosed in parentheses (`()`) and preceded by a question mark (`?`). + +```sql +/(?iU)foo*/ +``` + +## Regular expression operators + +InfluxQL provides the following regular expression operators that test if a +string operand matches a regular expression: + +- `=~`: Returns true if the string matches the regular expression +- `!~`: Returns true if the string does not match the regular expression + +InfluxQL regular expression operators are used to test string column values in +the [`WHERE` clause](/influxdb/version/reference/influxql/where/). + +## Regular expression examples + +The examples below use the following sample data sets: + +- [NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data) +- [Get started home sensor data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) + +{{< expand-wrapper >}} + +{{% expand "Use a regular expression to specify field keys and tag keys in the SELECT clause" %}} + +```sql +SELECT /^t/ FROM weather +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | temp_avg | temp_max | temp_min | +| :------------------- | -------: | -------: | -------: | +| 2020-01-01T00:00:00Z | 52 | 66 | 44 | +| 2020-01-01T00:00:00Z | 53 | 59 | 47 | +| 2020-01-01T00:00:00Z | 50 | 57 | 44 | +| 2020-01-02T00:00:00Z | 54 | 61 | 49 | +| 2020-01-02T00:00:00Z | 51 | 60 | 44 | +| 2020-01-02T00:00:00Z | 53 | 66 | 42 | +| ... | ... | ... | ... | + +{{% /expand %}} + +{{% expand "Use a regular expression to specify measurements in the FROM clause" %}} + +```sql +SELECT /^t/ FROM /^[hw]/ +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | temp | temp_avg | temp_max | temp_min | +| :------------------- | ---: | -------: | -------: | -------: | +| 2020-01-01T00:00:00Z | | 52 | 66 | 44 | +| 2020-01-01T00:00:00Z | | 53 | 59 | 47 | +| 2020-01-01T00:00:00Z | | 50 | 57 | 44 | +| 2020-01-02T00:00:00Z | | 54 | 61 | 49 | +| 2020-01-02T00:00:00Z | | 51 | 60 | 44 | +| 2020-01-02T00:00:00Z | | 53 | 66 | 42 | +| ... | ... | ... | ... | ... | + +{{% /expand %}} + +{{% expand "Use a regular expression to specify tag values in the WHERE clause" %}} + +```sql +SELECT * FROM weather WHERE location !~ /^[S]/ +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | location | precip | temp_avg | temp_max | temp_min | wind_avg | +| :------------------- | :------- | -----: | -------: | -------: | -------: | -------: | +| 2020-01-01T00:00:00Z | Concord | 0 | 52 | 66 | 44 | 3.13 | +| 2020-01-01T00:00:00Z | Hayward | 0 | 50 | 57 | 44 | 2.24 | +| 2020-01-02T00:00:00Z | Concord | 0 | 53 | 66 | 42 | 3.13 | +| 2020-01-02T00:00:00Z | Hayward | 0 | 51 | 60 | 44 | 3.8 | +| 2020-01-03T00:00:00Z | Concord | 0 | 49 | 60 | 38 | 2.68 | +| 2020-01-03T00:00:00Z | Hayward | 0 | 50 | 62 | 41 | 3.13 | +| ... | ... | ... | ... | ... | ... | ... | + +{{% /expand %}} + +{{% expand "Use a regular expression to specify a tag with no value in the WHERE clause" %}} + +```sql +SELECT * FROM home, weather WHERE location !~ /./ +``` + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | +| :------------------- | --: | ---: | -------- | ------ | :---------- | ---: | -------- | -------- | -------- | -------- | +| 2022-01-01T08:00:00Z | 0 | 35.9 | | | Kitchen | 21 | | | | | +| 2022-01-01T08:00:00Z | 0 | 35.9 | | | Living Room | 21.1 | | | | | +| 2022-01-01T09:00:00Z | 0 | 36.2 | | | Kitchen | 23 | | | | | +| 2022-01-01T09:00:00Z | 0 | 35.9 | | | Living Room | 21.4 | | | | | +| 2022-01-01T10:00:00Z | 0 | 36.1 | | | Kitchen | 22.7 | | | | | +| 2022-01-01T10:00:00Z | 0 | 36 | | | Living Room | 21.8 | | | | | +| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | + +{{% /expand %}} + +{{% expand "Use a regular expression to specify tag keys in the GROUP BY clause" %}} + +```sql +SELECT MAX(precip) FROM weather GROUP BY /^l/ +``` + +{{% influxql/table-meta %}} +name: weather +tags: location=Concord +{{% /influxql/table-meta %}} + +| time | max | +| :------------------- | ---: | +| 2021-10-24T00:00:00Z | 4.53 | + +{{% influxql/table-meta %}} +name: weather +tags: location=Hayward +{{% /influxql/table-meta %}} + +| time | max | +| :------------------- | ---: | +| 2022-12-31T00:00:00Z | 4.34 | + +{{% influxql/table-meta %}} +name: weather +tags: location=San Francisco +{{% /influxql/table-meta %}} + +| time | max | +| :------------------- | ---: | +| 2021-10-24T00:00:00Z | 4.02 | + +{{% /expand %}} + +{{< /expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/select.md b/content/shared/influxql-v3-reference/select.md new file mode 100644 index 000000000..c0a3c0566 --- /dev/null +++ b/content/shared/influxql-v3-reference/select.md @@ -0,0 +1,444 @@ +Use the `SELECT` statement to query data from one or more +[measurements](/influxdb/version/reference/glossary/#measurement). +The `SELECT` statement **requires** a [`SELECT` clause](#select-clause) and a +[`FROM` clause](#from-clause). + +- [Syntax](#syntax) + - [SELECT clause](#select-clause) + - [FROM clause](#from-clause) +- [Notable SELECT statement behaviors](#notable-select-statement-behaviors) +- [Data types and casting operations](#data-types-and-casting-operations) +- [SELECT statement examples](#select-statement-examples) + + +## Syntax + +```sql +SELECT field_expression[, ..., field_expression_n[, tag_expression[, ..., tag_expression_n]]] FROM measurement_expression[, ..., measurement_expression_n] +``` + +### SELECT clause + +The `SELECT` clause supports several formats for identifying data to query. +It requires one or more **field expressions** and optional **tag expressions**. + +- **field_expression**: Expression to identify one or more fields to return in query results. + Can be a [field key](/influxdb/version/reference/glossary/#field-key), + constant, [regular expression](/influxdb/version/reference/influxql/regular-expressions/), + [wildcard (`*`)](#wildcard-expressions-in-select-clauses), or + [function expression](/influxdb/version/reference/influxql/functions/) and any + combination of arithmetic operators. +- **tag_expression**: Expression to identify one or more tags to return in query results. + Can be a [tag key](/influxdb/version/reference/glossary/#tag-key) or constant. + +#### Select clause behaviors + +- `SELECT field_key` - Returns a specific field. +- `SELECT field_key1, field_key2` - Returns two specific fields. +- `SELECT field_key, tag_key` - Returns a specific field and tag. +- `SELECT *` - Returns all [fields](/influxdb/version/reference/glossary/#field) + and [tags](/influxdb/version/reference/glossary/#tag). + _See [Wildcard expressions](#wildcard-expressions)._ +- `SELECT /^[t]/` - Returns all [fields](/influxdb/version/reference/glossary/#field) + and [tags](/influxdb/version/reference/glossary/#tag) with keys that + match the regular expression. At least one field key must match the regular + expression. If no field keys match the regular expression, no results are + returned. + +### FROM clause + +The `FROM` clause specifies the +[measurement](/influxdb/version/reference/glossary/#measurement) or +[subquery](/influxdb/version/reference/influxql/subqueries/) to query. +It requires one or more comma-delimited +[measurement expressions](#measurement_expression) or [subqueries](#subquery). + +#### measurement_expression + +A measurement expression identifies a measurement to query. +It can be a measurement name, fully-qualified measurement, constant, or +a [regular expression](/influxdb/version/reference/influxql/regular-expressions/). + +- **Measurement name**: When using just the measurement name, InfluxQL assumes + the default retention policy of the database specified in the query request. + + ```sql + FROM measurement + ``` + +- **Fully-qualified measurement**: A fully qualified measurement includes a + database name, retention policy name, and measurement name, each separated by + a period (`.`). If the retention policy is not specified, InfluxQL uses the + default retention policy for the specified database. + +```sql +FROM database.retention_policy.measurement + +-- Fully-qualified measurement with default retention policy +FROM database..measurement +``` + +> [!Important] +> +> #### InfluxQL retention policies +> +> In {{< product-name >}}, **retention policies** are not part of the data model +> like they are in InfluxDB 1.x. +> Each {{< product-name >}} database has a **retention period** which defines the +> maximum age of data to retain in the database. To use fully-qualified +> measurements in InfluxQL queries, use the following naming convention when +> [creating a database](/influxdb/version/admin/databases/create/): +> +> ``` +> database_name/retention_policy +> ``` + +#### Subquery + +An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. +The outer query queries results returned by the inner query (subquery). + +For more information, see [InfluxQL subqueries](/influxdb/version/reference/influxql/subqueries/). + +## Notable SELECT statement behaviors + +- [Must query at least one field](#must-query-at-least-one-field) +- [Wildcard expressions](#wildcard-expressions) +- [Cannot include both aggregate and non-aggregate field expressions](#cannot-include-both-aggregate-and-non-aggregate-field-expressions) + +### Must query at least one field + +A query requires at least one [field key](/influxdb/version/reference/glossary/#field-key) +in the `SELECT` clause to return data. +If the `SELECT` clause includes only [tag keys](/influxdb/version/reference/glossary/#tag-key), +the query returns an empty result. +When using regular expressions in the `SELECT` clause, if regular expression +matches only tag keys and no field keys, the query returns an empty result. + +To return data associated with tag keys, include at least one field key in the +`SELECT` clause. + +### Wildcard expressions + +When using a wildcard expression (`*`) in the `SELECT` clause, the query returns +all tags and fields. +If a [function](/influxdb/version/reference/influxql/functions/) is +applied to a wildcard expression, the query returns all _fields_ with +the function applied, but does not return _tags_ unless they are included in +the `SELECT` clause. + +### Cannot include both aggregate and non-aggregate field expressions + +The `SELECT` statement cannot include an aggregate field expression +(one that uses an [aggregate](/influxdb/version/reference/influxql/functions/aggregates/) +or [selector](/influxdb/version/reference/influxql/functions/aggregates/) +function) **and** a non-aggregate field expression. +For example, in the following query, an aggregate function is applied to one +field, but not the other: + +```sql +SELECT mean(temp), hum FROM home +``` + +This query returns an error. +For more information, see [error about mixing aggregate and non-aggregate queries](/enterprise_influxdb/v1/troubleshooting/errors/#error-parsing-query-mixing-aggregate-and-non-aggregate-queries-is-not-supported). + +## Data types and casting operations + +The [`SELECT` clause](#select-clause) supports specifying a +[field's](/influxdb/version/reference/glossary/#field) type and basic +casting operations with the `::` syntax. + +```sql +SELECT field_expression::type FROM measurement_expression +``` + +The `::` syntax allows users to perform basic cast operations in queries. +Currently, InfluxQL supports casting _numeric_ [field values](/influxdb/version/reference/glossary/#field-value) +to other numeric types. +Casting to an **identifier type** acts as a filter on results and returns only +columns of that specific identifier type along with the `time` column. + +{{< flex >}} +{{% flex-content "third" %}} + +##### Numeric types + +- `float` +- `integer` +- `unsigned` + +{{% /flex-content %}} +{{% flex-content "third" %}} + +##### Non-numeric types + +- `string` +- `boolean` + +{{% /flex-content %}} +{{% flex-content "third" %}} + +##### Identifier types + +- `field` +- `tag` + +{{% /flex-content %}} +{{< /flex >}} + +> [!Important] +> InfluxQL returns no data if the query attempts to cast a numeric value to a +> non-numeric type and vice versa. + +When casting a float value to an integer or unsigned integer, the float value +is truncated at the decimal point. No rounding is performed. + +## SELECT statement examples + +The examples below use the following sample data sets: + +- [Get started home sensor data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +- [NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data) + +{{< expand-wrapper >}} +{{% expand "Select all fields and tags from a measurement" %}} + +```sql +SELECT * FROM home +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :---------- | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | +| ... | ... | ... | ... | ... | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select specific tags and fields from a measurement" %}} + +```sql +SELECT temp, hum, room FROM home +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | temp | hum | room | +| :------------------- | ---: | ---: | :---------- | +| 2022-01-01T08:00:00Z | 21 | 35.9 | Kitchen | +| 2022-01-01T08:00:00Z | 21.1 | 35.9 | Living Room | +| 2022-01-01T09:00:00Z | 23 | 36.2 | Kitchen | +| 2022-01-01T09:00:00Z | 21.4 | 35.9 | Living Room | +| 2022-01-01T10:00:00Z | 22.7 | 36.1 | Kitchen | +| 2022-01-01T10:00:00Z | 21.8 | 36 | Living Room | +| ... | ... | ... | ... | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select all fields from a measurement" %}} + +```sql +SELECT *::field FROM home +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | hum | temp | +| :------------------- | --: | ---: | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | 21 | +| 2022-01-01T08:00:00Z | 0 | 35.9 | 21.1 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | 23 | +| 2022-01-01T09:00:00Z | 0 | 35.9 | 21.4 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | 22.7 | +| 2022-01-01T10:00:00Z | 0 | 36 | 21.8 | +| ... | ... | ... | ... | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select a field from a measurement and perform basic arithmetic" %}} + +```sql +SELECT (temp * (9 / 5)) + 32 FROM home +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | temp | +| :------------------- | ----------------: | +| 2022-01-01T08:00:00Z | 69.80000000000001 | +| 2022-01-01T08:00:00Z | 69.98 | +| 2022-01-01T09:00:00Z | 73.4 | +| 2022-01-01T09:00:00Z | 70.52 | +| 2022-01-01T10:00:00Z | 72.86 | +| 2022-01-01T10:00:00Z | 71.24000000000001 | +| ... | ... | + +{{% /influxdb/custom-timestamps %}} + +> [!Note] +> **Note:** InfluxDB follows the standard order of operations. +> See [InfluxQL mathematical operators](/influxdb/version/reference/influxql/math-operators/) +> for more on supported operators. + +{{% /expand %}} + +{{% expand "Select all data from more than one measurement" %}} + +```sql +SELECT * FROM home, weather +``` + +{{% influxql/table-meta %}} +Name: weather +{{% /influxql/table-meta %}} + +| time | co | hum | location | precip | room | temp | temp_avg | temp_max | temp_min | wind_avg | +| :------------------- | --: | --: | :------------ | -----: | :--- | ---: | -------: | -------: | -------: | -------: | +| 2020-01-01T00:00:00Z | | | Concord | 0 | | | 52 | 66 | 44 | 3.13 | +| 2020-01-01T00:00:00Z | | | San Francisco | 0 | | | 53 | 59 | 47 | 14.32 | +| 2020-01-01T00:00:00Z | | | Hayward | 0 | | | 50 | 57 | 44 | 2.24 | +| 2020-01-02T00:00:00Z | | | San Francisco | 0 | | | 54 | 61 | 49 | 5.82 | +| 2020-01-02T00:00:00Z | | | Hayward | 0 | | | 51 | 60 | 44 | 3.8 | +| 2020-01-02T00:00:00Z | | | Concord | 0 | | | 53 | 66 | 42 | 3.13 | +| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | + +{{% /expand %}} + +{{% expand "Select all data from a fully-qualified measurement (with default retention policy)" %}} + +```sql +SELECT * FROM "get-started"..home +``` + +{{% influxql/table-meta %}} +Name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :---------- | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | +| ... | ... | ... | ... | ... | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Type-casting examples + +{{< expand-wrapper >}} + +{{% expand "Cast an integer field to a float" %}} + +```sql +SELECT co::float FROM home +``` + +{{% /expand %}} + +{{% expand "Cast a float field to an integer" %}} + +```sql +SELECT temp::integer FROM home +``` + +{{% /expand %}} + +{{% expand "Cast a float field to an unsigned integer" %}} + +```sql +SELECT temp::unsigned FROM home +``` + +{{% /expand %}} + +{{< /expand-wrapper >}} + + diff --git a/content/shared/influxql-v3-reference/show.md b/content/shared/influxql-v3-reference/show.md new file mode 100644 index 000000000..b607b2393 --- /dev/null +++ b/content/shared/influxql-v3-reference/show.md @@ -0,0 +1,145 @@ +Use InfluxQL `SHOW` statements to query schema information from a database. + +- [SHOW RETENTION POLICIES](#show-retention-policies) +- [SHOW MEASUREMENTS](#show-measurements) +- [SHOW FIELD KEYS](#show-field-keys) +- [SHOW TAG KEYS](#show-tag-keys) +- [SHOW TAG VALUES](#show-tag-values) + +## SHOW RETENTION POLICIES + +Use the `SHOW RETENTION POLICIES` statement to list retention policies associated +with a database. +Each database has a single retention policy--`autogen`. + +> [!Note] +> In {{< product-name >}}, retention policies are not part of the +> data structure but are expected by InfluxQL and used in fully-qualified measurements +> in the [`FROM` clause](/influxdb/version/reference/influxql/select/#from-clause). +> The data returned for each retention policy does not represent the actual +> retention-related attributes of the database. The values are placeholder values +> meant only for InfluxQL feature parity. +> +> For information about database data retention, see +> [List databases](/influxdb/version/admin/databases/list/). + +```sql +SHOW RETENTION POLICIES [ON ] +``` + +#### Examples + +```sql +-- Show retention policies in the database specified in the query request +SHOW RETENTION POLICIES + +-- Show retention policies in a specific database +SHOW RETENTION POLICIES ON "example-database" +``` + +## SHOW MEASUREMENTS + +Use the `SHOW MEASUREMENTS` statement to list measurements in a database. + +```sql +SHOW MEASUREMENTS [with_measurement_clause] [where_clause] [limit_clause] [offset_clause] +``` + +#### Examples + +```sql +-- Show all measurements +SHOW MEASUREMENTS + +-- Show measurements where region tag = 'uswest' AND host tag = 'serverA' +SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA' + +-- Show measurements that start with 'h2o' +SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/ +``` + +## SHOW FIELD KEYS + +Use the `SHOW FIELD KEYS` statement to list all field keys in a measurement. + +```sql +SHOW FIELD KEYS [from_clause] +``` + +#### Examples + +```sql +-- Show field keys and field value data types from all measurements +SHOW FIELD KEYS + +-- Show field keys and field value data types from specified measurement +SHOW FIELD KEYS FROM "cpu" +``` + +## SHOW TAG KEYS + +Use the `SHOW TAG KEYS` statement to list tag keys in a measurement. + +```sql +SHOW TAG KEYS [from_clause] [where_clause] [limit_clause] [offset_clause] +``` + +#### Examples + +```sql +-- Show all tag keys +SHOW TAG KEYS + +-- Show all tag keys from the cpu measurement +SHOW TAG KEYS FROM "cpu" + +-- Show all tag keys from the cpu measurement where the region key = 'uswest' +SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' + +-- Show all tag keys where the host key = 'serverA' +SHOW TAG KEYS WHERE "host" = 'serverA' +``` + +## SHOW TAG VALUES + +Use the `SHOW TAG VALUES` statement to list values of specified tags in a database. + +```sql +SHOW TAG VALUES [from_clause] WITH KEY = [where_clause] [limit_clause] [offset_clause] +``` + +By default, the `SHOW TAG VALUES` statement only returns unique tag values from +**the last day**. To modify the time range, include a +[`WHERE` clause with a time-based predicate](/influxdb/version/reference/influxql/where/#time-ranges). + +> [!Important] +> +> #### Include a FROM clause +> +> We strongly recommend including a `FROM` clause with the `SHOW TAG VALUES` +> statement that specifies 1-50 tables to query. +> Without a `FROM` clause, the InfluxDB query engine must read data from all +> tables and return unique tag values from each. +> +> Depending on the number of tables in your database and the number of unique tag +> values in each table, excluding a `FROM` clause can result in poor query performance, +> query timeouts, or unnecessary resource allocation that may affect other queries. + +#### Examples + +```sql +-- Show tag values from the cpu measurement for the region tag +SHOW TAG VALUES FROM "cpu" WITH KEY = "region" + +-- Show tag values from the cpu measurement for the region tag for a custom time range +SHOW TAG VALUES FROM "cpu" WITH KEY = "region" WHERE time > -7d + +-- Show tag values from multiple measurements for the region tag +SHOW TAG VALUES FROM "cpu", "memory", "disk" WITH KEY = "region" + +-- Show tag values from the cpu measurement for all tag keys that do not include the letter c +SHOW TAG VALUES FROM "cpu" WITH KEY !~ /.*c.*/ + +-- Show tag values from the cpu measurement for region & host tag keys where service = 'redis' +SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' +``` diff --git a/content/shared/influxql-v3-reference/subqueries.md b/content/shared/influxql-v3-reference/subqueries.md new file mode 100644 index 000000000..befdfd710 --- /dev/null +++ b/content/shared/influxql-v3-reference/subqueries.md @@ -0,0 +1,228 @@ +An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. +The outer query queries results returned by the inner query (subquery). + +- [Syntax](#syntax) +- [Examples](#examples) +- [Notable subquery behaviors](#notable-subquery-behaviors) + +> [!Important] +> InfluxQL does not support a `HAVING` clause, however InfluxQL subqueries offer +> functionality similar to the [SQL `HAVING` clause](/influxdb/version/reference/sql/having/). + +## Syntax + +```sql +SELECT_clause FROM ( SELECT_statement ) [...] +``` + +When using subqueries, InfluxQL **performs the inner query first**, then performs +the outer query. + +The outer query requires a [`SELECT` clause](/influxdb/version/reference/influxql/select/#select-clause) +and a [`FROM` clause](/influxdb/version/reference/influxql/select/#from-clause). +The inner query is enclosed in parentheses in the outer query's `FROM` clause. + +InfluxQL supports multiple nested subqueries: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] +``` + +## Examples + +> [!Note] +> +> #### Sample data +> +> The examples below use the following sample data sets: +> +> - [Get started home sensor data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +> - [Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data) + +{{< expand-wrapper >}} + +{{% expand "Apply an aggregate function to an aggregated result set" %}} + +```sql +SELECT + SUM(max) +FROM + ( + SELECT + MAX(temp) + FROM + home + GROUP BY + room + ) +``` + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | sum | +| :------------------- | ---: | +| 1970-01-01T00:00:00Z | 46.1 | + +{{% /expand %}} + +{{% expand "Calculate the average difference between two fields" %}} + +```sql +SELECT + MEAN(difference) +FROM + ( + SELECT + a - b AS difference + FROM + numbers + ) +``` + +{{% influxql/table-meta %}} +Table: numbers +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -------------------: | +| 1970-01-01T00:00:00Z | -0.03629771779732732 | + +{{% /expand %}} + +{{% expand "Filter aggregate values based on a threshold" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + co_change +FROM + ( + SELECT + SPREAD(co) AS co_change + FROM + home + GROUP BY + room, + time(2h) + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + AND co_change >= 4 +``` + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | co_chnage | +| :------------------- | --------: | +| 2022-01-01T18:00:00Z | 4 | +| 2022-01-01T18:00:00Z | 5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Perform additional aggregate operations on aggregate values" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + SUM(co_derivative) AS sum_derivative +FROM + ( + SELECT + DERIVATIVE(MEAN(co)) AS co_derivative + FROM + home + GROUP BY + time(12m), + room + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY + room +``` + +{{% /influxdb/custom-timestamps %}} + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | room | sum_derivative | +| :------------------- | :---------- | -------------: | +| 1970-01-01T00:00:00Z | Kitchen | 5.2 | +| 1970-01-01T00:00:00Z | Living Room | 3.4 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Notable subquery behaviors + +- [Apply time bounds to the outer query to improve performance](#apply-time-bounds-to-the-outer-query-to-improve-performance) +- [Cannot use multiple SELECT statements in a subquery](#cannot-use-multiple-select-statements-in-a-subquery) + +### Apply time bounds to the outer query to improve performance + +To improve the performance of InfluxQL queries that use subqueries and a +specified time range, apply the `WHERE` clause with time-based predicates to the +outer query rather than the inner query. +For example--the following queries return the same results, but **the query with +time-based predicate on the outer query is more performant than the query with +time-based predicate on the inner query**: + +{{% influxdb/custom-timestamps %}} + +#### Time bounds on the outer query {note="(Recommended)"} + +```sql +SELECT + inner_value AS value +FROM + ( + SELECT + raw_value as inner_value + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +``` + +#### Time bounds on the inner query + +```sql +SELECT + inner_value AS value +FROM + ( + SELECT + raw_value as inner_value + WHERE + time >= '2022-07-19T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + ) +``` +{{% /influxdb/custom-timestamps %}} + +### Cannot use multiple SELECT statements in a subquery + +InfluxQL does not support multiple +[`SELECT` statements](/influxdb/version/reference/influxql/select/) +per subquery: + +```sql +SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] +``` + +However, InfluxQL does support multiple nested subqueries per outer query: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] + ------------------ ---------------- + Subquery 1 Subquery 2 +``` diff --git a/content/shared/influxql-v3-reference/time-and-timezone.md b/content/shared/influxql-v3-reference/time-and-timezone.md new file mode 100644 index 000000000..8ba494b1b --- /dev/null +++ b/content/shared/influxql-v3-reference/time-and-timezone.md @@ -0,0 +1,354 @@ +InfluxQL is designed for working with time series data and includes features specifically for working with time. +You can review the following ways to work with time and timestamps in your InfluxQL queries: + +- [Time syntax](#time-syntax) + - [Add and subtract time values](#add-and-subtract-time-values) +- [Query time range](#query-time-range) + - [Supported operators](#supported-operators) +- [Query examples](#query-examples) +- [Time zone clause](#time-zone-clause) +- [Notable behaviors](#notable-behaviors) + - [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) + - [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) + - [Cannot use parameters for durations](#cannot-use-parameters-for-durations) + +## Time syntax + +InfluxQL supports the following timestamp literal syntaxes: + +```sql +'2006-01-02T15:04:05.00Z' -- RFC3339 date-time string +'2006-01-02 15:04:05.00' -- RFC3339-like date-time string +1136189045000000000 -- Unix nanosecond epoch time +1136189045s -- Unix epoch time +``` + +- **RFC3339 date-time string**: + [String literal](/influxdb/version/reference/influxql/#strings) using + the RFC3339 timestamp format, `YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`. +- **RFC3339-like date-time string**: + [String literal](/influxdb/version/reference/influxql/#strings) using + the RFC3339-like timestamp format, `YYYY-MM-DD HH:MM:SS.nnnnnnnnn`. +- **Unix nanosecond epoch time**: + [Integer](/influxdb/version/reference/influxql/#integers) that + represents the number of nanoseconds elapsed since the + [Unix epoch](/influxdb/version/reference/glossary/#unix-epoch). +- **Unix epoch time**: + [Duration literal](/influxdb/version/reference/influxql/#durations) + that represents the number of specified time units elapsed since the + [Unix epoch](/influxdb/version/reference/glossary/#unix-epoch). + _[View supported duration units](/influxdb/version/reference/influxql/#durations)_. + +##### Supported timestamp values + +| | RFC3339 | Unix nanosecond time | +| ----------- | :----------------------------: | -------------------: | +| **Maximum** | 2262-04-11T23:47:16.854775807Z | 9223372036854775807 | +| **Minimum** | 1677-09-21T00:12:43.145224193Z | -9223372036854775807 | + +### Add and subtract time values + +Timestamp values support addition and subtraction operations with +[duration literals](/influxdb/version/reference/influxql/#durations). +Add (`+`) or subtract (`-`) a duration to or from a timestamp to return an +updated timestamp. + +```sql +'2023-01-01T00:00:00Z' + 2h -- Resolves to 2023-01-01T02:00:00Z +'2023-01-01 00:00:00' - 20h -- Resolves to 2022-12-31T04:00:00Z +1672531200000000000 + 1y -- Resolves to 2024-01-01T00:00:00Z +``` + +> [!Important] +> InfluxQL requires a whitespace between the `+` operators `-` and the duration literal. + +## Query time range + +To specify the time range of a query, use conditional expressions in the +[`WHERE` clause](/influxdb/version/reference/influxql/where/) that +compare the value of the `time` column to an absolute timestamp or a relative +timestamp. + +- **Absolute time range**: Define query time bounds with timestamp literals + + ```sql + WHERE time >= '2023-01-01T00:00:00Z' AND time <= '2023-07-01T00:00:00Z' + WHERE time >= '2023-01-01 00:00:00' AND time <= '2023-07-01 00:00:00' + WHERE time >= 1672531200000000000 AND time <= 1688169600000000000 + WHERE time >= 1672531200s and time <= 1688169600000ms + ``` + +- **Relative time range**: Define query time bounds with a duration literal + added to or subtracted from timestamp literals. + + > [!Tip] + > Use `now()` to return the current system time (UTC). + + ```sql + -- Query data from the last day + WHERE time >= now() - 1d + + -- Query data from the previous week + WHERE time >= now() - 1w AND time <= now() - 2w + + -- Query data relative to a specific time + WHERE time >= '2023-01-01' - 1w AND time <= '2023-01-01' + 1w + ``` + +### Supported operators + +Conditional expressions with time operands support the following comparison operators: + +| Operator | Meaning | +|:--------:|:------- | +| `=` | equal to | +| `<>` | not equal to | +| `!=` | not equal to | +| `>` | greater than | +| `>=` | greater than or equal to | +| `<` | less than | +| `<=` | less than or equal to | + +> [!Important] +> InfluxQL supports the `AND` logical operator to define query time bounds, but +> does not support using the `OR` logical operator to query multiple time ranges. + +## Query examples + +The following examples use the +[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +{{< expand-wrapper >}} + +{{% expand "Specify a time range with RFC3339 date-time strings" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :------ | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Specify a time range with RFC3339-like date-time strings" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01 08:00:00' + AND time <= '2022-01-01 12:00:00' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :------ | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} + +{{% expand "Specify a time range with nanosecond epoch timestamps" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + room = 'Kitchen' + AND time >= 1641024000000000000 + AND time <= 1641038400000000000 +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :------ | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Specify a time range with second-precision epoch timestamps" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + room = 'Kitchen' + AND time >= 1641024000s + AND time <= 1641038400s +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :------ | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T11:00:00Z | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T12:00:00Z | 0 | 36 | Kitchen | 22.5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Specify a time range relative to a timestamp" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :---------- | ---: | +| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | +| 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | +| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | +| 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | +| 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | +| 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Specify a time range relative to now" %}} + +```sql +SELECT * FROM home WHERE time >= now() - 2h +``` + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Time zone clause + +By default, InfluxDB stores and returns timestamps in UTC. +Use the time zone clause and the `tz()` function to apply a time zone offset to +UTC times and return timestamps in the specified time zone including any applicable +seasonal offset such as Daylight Savings Time (DST) or British Summer Time (BST). + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('time_zone') +``` + +- **time_zone**: Time zone string literal to adjust times to. + Uses time zone names defined in the + [Internet Assigned Numbers Authority time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). + +### Time zone example + +{{< expand-wrapper >}} + +{{% expand "Return the UTC offset for Chicago's time zone" %}} +{{% influxdb/custom-timestamps %}} + +The following example uses the +[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +```sql +SELECT * +FROM home +WHERE + room = 'Kitchen' + AND time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +tz('America/Chicago') +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------------ | --: | ---: | :------ | ---: | +| 2022-01-01T02:00:00-06:00 | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T03:00:00-06:00 | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T04:00:00-06:00 | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T05:00:00-06:00 | 0 | 36 | Kitchen | 22.4 | +| 2022-01-01T06:00:00-06:00 | 0 | 36 | Kitchen | 22.5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Notable behaviors + +- [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) +- [Querying future data with a `GROUP BY time()` clause](#querying-future-data-with-a-group-by-time-clause) +- [Cannot use parameters for durations](#cannot-use-parameters-for-durations) + +### Cannot query multiple time ranges + +InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. +For example, the following query returns no results: + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') + OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') +``` + +{{% /influxdb/custom-timestamps %}} + +### Querying future data with a `GROUP BY time()` clause + +Queries that do not specify time bounds in the `WHERE` clause and do not include +a `GROUP BY time()` clause use the [minimum and maximum timestamps](#supported-timestamp-values) +as the default time range. +If the query includes a `GROUP BY time()` clause, the default time range is +between `1677-09-21T00:12:43.145224193Z` and +[`now()`](/influxdb/version/reference/influxql/functions/date-time/#now). + +To query data with timestamps that occur in the future (after `now()`), +provide an explicit upper bound in the `WHERE` clause. + +### Cannot use parameters for durations + +Currently, InfluxDB doesn't support using parameters for durations in +[parameterized queries](/influxdb/version/query-data/parameterized-queries/). diff --git a/content/shared/influxql-v3-reference/where.md b/content/shared/influxql-v3-reference/where.md new file mode 100644 index 000000000..af5468482 --- /dev/null +++ b/content/shared/influxql-v3-reference/where.md @@ -0,0 +1,353 @@ +Use the `WHERE` clause to filter data based on +[field values](/influxdb/version/reference/glossary/#field), +[tag values](/influxdb/version/reference/glossary/#tag), and +[timestamps](/influxdb/version/reference/glossary/#timestamp). + +- [Syntax](#syntax) +- [Operators](#comparison-operators) + - [Comparison operators](#comparison-operators) + - [Logical operators](#logical-operators) +- [Time ranges](#time-ranges) +- [Regular expressions](#regular-expressions) +- [WHERE clause examples](#where-clause-examples) +- [Notable behaviors](#notable-behaviors) + - [Single and double quotes](#single-and-double-quotes) + - [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) + +## Syntax + +```sql +SELECT_clause FROM_clause WHERE [(AND|OR) [...]] +``` + +- **conditional_expression**: Comparison between two operands that evaluates to + `true` or `false`. Comparison logic is determined by + [operators](#operators) used in the expression. + These expressions can operate on InfluxDB fields, tags, and timestamps. + Use logical operators (`AND`, `OR`) to chain multiple conditional expressions + together. + +## Operators + +Operators evaluate the relationship between two operands and return +`true` or `false`. + +### Comparison operators + +| Operator | Meaning | Supported data types | +| :------: | :--------------------------------- | :---------------------- | +| `=` | Equal to | all | +| `<>` | Not equal to | all | +| `!=` | Not equal to | all | +| `>` | Greater than | numeric, timestamp | +| `>=` | Greater than or equal to | numeric, timestamp | +| `<` | Less than | numeric, timestamp | +| `<=` | Less than or equal to | numeric, timestamp | +| `=~` | Matches a regular expression | strings | +| `!~` | Doesn't match a regular expression | strings | + +### Logical operators + +| Operator | Meaning | +| :------- | :---------------------------------------------------------------------- | +| `AND` | Returns `true` if both operands are `true`. Otherwise, returns `false`. | +| `OR` | Returns `true` if any operand is `true`. Otherwise, returns `false`. | + +## Time ranges + +Use the `WHERE` clause to specify a time range to query. +If a time range isn't specified in the `WHERE` clause, the [default time range](/influxdb/version/reference/influxql/#default-time-range) is used. + +Timestamps are stored in the `time` column. +Use comparison operators to compare the value of the `time` column to a +timestamp literal, integer (Unix nanosecond timestamp), or [expression](/influxdb/version/reference/glossary/#expression). + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Timestamp](#) +[Integer](#) +[Expression](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +WHERE + time >= '2023-01-01T00:00:00Z' + AND time < '2023-07-01T00:00:00Z' +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +WHERE + time >= 1672531200000000000 + AND time < 1688169600000000000 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +WHERE + time >= now() - 1d + AND time < now() +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +See [Time syntax](/influxdb/version/reference/influxql/time-and-timezone/#time-syntax) +for information on how to specify alternative time ranges in the `WHERE` clause. + +> [!Important] +> InfluxQL [does not support querying multiple time ranges](#cannot-query-multiple-time-ranges). + +## Regular expressions + +Regular expressions can be used to evaluate _string_ values in the `WHERE` clause +using regular expression comparison operators: + +- `=~`: Matches a regular expression +- `!~`: Doesn't match a regular expression + +```sql +SELECT * FROM home WHERE room =~ /^K/ +``` + +For more information about InfluxQL regular expression syntax, see +[InfluxQL regular expressions](/influxdb/version/reference/influxql/regular-expressions/). + +## WHERE clause examples + +The following examples use the +[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). + +{{< expand-wrapper >}} +{{% expand "Select data with a specific tag value" %}} + +```sql +SELECT * FROM home WHERE room = 'Living Room' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :---------- | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | +| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | +| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | +| 2022-01-01T11:00:00Z | 0 | 36 | Living Room | 22.2 | +| 2022-01-01T12:00:00Z | 0 | 35.9 | Living Room | 22.2 | +| ... | ... | ... | ... | ... | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select data from a specific time range" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :---------- | ---: | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Kitchen | 21 | +| 2022-01-01T08:00:00Z | 0 | 35.9 | Living Room | 21.1 | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T09:00:00Z | 0 | 35.9 | Living Room | 21.4 | +| 2022-01-01T10:00:00Z | 0 | 36.1 | Kitchen | 22.7 | +| 2022-01-01T10:00:00Z | 0 | 36 | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select data from a relative time range" %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * FROM home WHERE time >= '2022-01-01T20:00:00Z' - 2h +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :---------- | ---: | +| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | +| 2022-01-01T18:00:00Z | 9 | 36.2 | Living Room | 22.8 | +| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | +| 2022-01-01T19:00:00Z | 14 | 36.3 | Living Room | 22.5 | +| 2022-01-01T20:00:00Z | 26 | 36.5 | Kitchen | 22.7 | +| 2022-01-01T20:00:00Z | 17 | 36.4 | Living Room | 22.2 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select field values above a threshold" %}} + +```sql +SELECT co FROM home WHERE co > 9 +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | +| :------------------- | --: | +| 2022-01-01T18:00:00Z | 18 | +| 2022-01-01T19:00:00Z | 14 | +| 2022-01-01T19:00:00Z | 22 | +| 2022-01-01T20:00:00Z | 17 | +| 2022-01-01T20:00:00Z | 26 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select specific field values" %}} + +```sql +SELECT room, co FROM home WHERE co = 9 +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | room | co | +| :------------------- | :---------- | --: | +| 2022-01-01T17:00:00Z | Kitchen | 9 | +| 2022-01-01T18:00:00Z | Living Room | 9 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select field values based on arithmetic" %}} + +```sql +SELECT room, co FROM home WHERE co - 10 > 5 +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | room | co | +| :------------------- | :---------- | --: | +| 2022-01-01T18:00:00Z | Kitchen | 18 | +| 2022-01-01T19:00:00Z | Kitchen | 22 | +| 2022-01-01T20:00:00Z | Living Room | 17 | +| 2022-01-01T20:00:00Z | Kitchen | 26 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select data with field values above a threshold and a specific tag value" %}} + +```sql +SELECT * FROM home WHERE temp > 22.7 AND room = 'Kitchen' +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | hum | room | temp | +| :------------------- | --: | ---: | :------ | ---: | +| 2022-01-01T09:00:00Z | 0 | 36.2 | Kitchen | 23 | +| 2022-01-01T13:00:00Z | 1 | 36.5 | Kitchen | 22.8 | +| 2022-01-01T14:00:00Z | 1 | 36.3 | Kitchen | 22.8 | +| 2022-01-01T18:00:00Z | 18 | 36.9 | Kitchen | 23.3 | +| 2022-01-01T19:00:00Z | 22 | 36.6 | Kitchen | 23.1 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Select data based on the relationship between columns" %}} + +```sql +SELECT co, temp FROM home WHERE co > temp +``` + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +{{% influxdb/custom-timestamps %}} + +| time | co | temp | +| :------------------- | --: | ---: | +| 2022-01-01T20:00:00Z | 26 | 22.7 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +## Notable behaviors + +- [Single and double quotes](#single-and-double-quotes) +- [Cannot query multiple time ranges](#cannot-query-multiple-time-ranges) + +### Single and double quotes + +In InfluxQL, single quotation marks (`'`) and double quotation marks (`"`) work +differently and can alter the way a `WHERE` clause functions. +Single quotes are used in [string](/influxdb/version/reference/influxql/#strings) +and [timestamp](/influxdb/version/reference/influxql/#dates--times) literals. +Double quotes are used to quote [identifiers](/influxdb/version/reference/influxql/#identifiers), +(time, field, and tag column names). + +For example, the following conditional expression compares the value of the +`location` _column_ to the _literal string_, `London`: + +```sql +"location" = 'London' +``` + +The following conditional expression compares the value of the `location` _column_ +to the value of the `London` _column_: + +```sql +"location" = "London" +``` + +Misused double and single quotes in the `WHERE` clause often results in unexpected +empty query results. +For more information about quotation marks, see +[InfluxQL quotation](/influxdb/version/reference/influxql/quoting/). + +### Cannot query multiple time ranges + +InfluxDB does not support using `OR` in the `WHERE` clause to query multiple time ranges. +For example, the following query returns no results: + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + (time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z') + OR (time >= '2022-01-01T18:00:00Z' AND time <= '2022-01-01T20:00:00Z') +``` + +{{% /influxdb/custom-timestamps %}} diff --git a/content/shared/sql-reference/_index.md b/content/shared/sql-reference/_index.md new file mode 100644 index 000000000..6f82512ab --- /dev/null +++ b/content/shared/sql-reference/_index.md @@ -0,0 +1,684 @@ + + +{{% product-name %}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. + +- [Identifiers](#identifiers) +- [Quoting and case sensitivity](#quoting-and-case-sensitivity) +- [Literals](#literals) +- [Duration units](#duration-units) +- [Operators](#operators) +- [Keywords](#keywords) +- [Conditional expressions](#conditional-expressions) +- [Statements and clauses](#statements-and-clauses) +- [Comments](#comments) +- [Functions](#functions) + +## Identifiers + +An identifier is a token which refers to the name of an InfluxDB database object, such as a **measurement** or a column name (**time**, **tag keys**, or **field keys**). + +## Quoting + +Use double quotes on [identifiers](#identifiers) to treat them as case-sensitive. +Use single quotes on string literals. + +General quoting guidelines: + +- Single quote RFC3339 and RFC3339-like time values. +- Do _not_ quote Unix epoch time values (integers cast to a timestamp). +- Double-quote mixed case, [camel case](https://en.wikipedia.org/wiki/Camel_case) or case-sensitive identifiers. +- Double-quote identifiers that contain special characters or whitespace characters. + +##### Quoting examples + +```sql +-- Double-quote identifiers that contain whitespace +SELECT "water temperature", "buoy location" FROM buoy + +-- Double-quote measurement names with special characters +SELECT * FROM "h2o-temperature" + +-- Double-quote identifiers that should be treated as case-sensitive +SELECT "pH" FROM "Water" +``` + +> [!Note] +> **Note:** We recommend always double-quoting identifiers, regardless of case-sensitivity. + +Unquoted identifiers **are not** case-sensitive and match any measurement, tag key, or field key with the same characters, despite case. +For example, if you have two fields in a measurement named `ph` and `pH`, the unquoted identifier, `pH` will match both. +To query in a case-sensitive manner, double-quote identifiers. + +## Literals + +A literal is an explicit value not represented by an identifier. + +### String literals + +String literals are surrounded by single quotes. + +```sql +'santa_monica' +'pH' +'average temperature' +``` + +### Numeric literals + +Number literals are positive or negative numbers that are either exact numbers or floats. + +```sql +-- Integers +10 ++10 +-10 + +-- Unsigned integers +10::BIGINT UNSIGNED ++10::BIGINT UNSIGNED + +-- Floats +10.78654 +-100.56 +``` + +### Date and time literals + +The following date and time literals are supported: + +```sql +'2022-01-31T06:30:30.123Z' -- (RFC3339) +'2022-01-31T06:30:30.123' -- (RFC3339-like) +'2022-01-31 06:30:30.123' -- (RFC3339-like) +'2022-01-31 06:30:30' -- ((RFC3339-like, no fractional seconds) +1643610630123000000::TIMESTAMP -- (Unix epoch nanosecond cast to a timestamp) +``` + +### Boolean literals + +Boolean literals are either `TRUE` or `FALSE`. + +## Duration units + +Interval literals specify a length or unit of time. + +```sql +INTERVAL '4 minutes' +INTERVAL '12 days 6 hours 30 minutes' +``` + +The following units of time are supported: + +- nanoseconds +- microseconds +- milliseconds +- seconds +- minutes +- hours +- days +- weeks +- months +- years +- century + +## Operators + +Operators are reserved words or characters which perform certain operations, including comparisons and arithmetic. + +### Arithmetic operators + +Arithmetic operators take two numeric values (either literals or variables) and +perform a calculation that returns a single numeric value. + +| Operator | Description | Example | Result | +| :------: | :------------- | ------- | -----: | +| `+` | Addition | `2 + 2` | `4` | +| `-` | Subtraction | `4 - 2` | `2` | +| `*` | Multiplication | `2 * 3` | `6` | +| `/` | Division | `6 / 3` | `2` | +| `%` | Modulo | `7 % 2` | `1` | + +### Comparison operators + +Comparison operators evaluate the relationship between the left and right operands and `TRUE` or `FALSE`. + +| Operator | Meaning | Example | +| :------: | :------------------------------------------------------- | :----------------- | +| `=` | Equal to | `123 = 123` | +| `<>` | Not equal to | `123 <> 456` | +| `!=` | Not equal to | `123 != 456` | +| `>` | Greater than | `3 > 2` | +| `>=` | Greater than or equal to | `3 >= 2` | +| `<` | Less than | `1 < 2` | +| `<=` | Less than or equal to | `1 <= 2` | +| `~` | Matches a regular expression | `'abc' ~ 'a.*'` | +| `~\*` | Matches a regular expression _(case-insensitive)_ | `'Abc' ~\* 'A.*'` | +| `!~` | Does not match a regular expression | `'abc' !~ 'd.*'` | +| `!~\*` | Does not match a regular expression _(case-insensitive)_ | `'Abc' !~\* 'a.*'` | + +### Logical operators + +| Operator | Meaning | +| :-------: | :------------------------------------------------------------------------- | +| `AND` | Returns true if both operands are true. Otherwise, returns false. | +| `BETWEEN` | Returns true if the left operand is within the range of the right operand. | +| `EXISTS` | Returns true if the operand is not null. | +| `IN` | Returns true if the left operand is in the right operand list. | +| `LIKE` | Returns true if the left operand matches the right operand pattern string. | +| `NOT` | Negates the subsequent expression. | +| `OR` | Returns true if any operand is true. Otherwise, returns false. | + +### Bitwise operators + +Bitwise operators perform bitwise operations on bit patterns or binary numerals. + +| Operator | Meaning | Example | Result | +| :------: | :------------------ | :------- | -----: | +| `&` | Bitwise and | `5 & 3` | `1` | +| `\|` | Bitwise or | `5 \| 3` | `7` | +| `^` | Bitwise xor | `5 ^ 3` | `6` | +| `>>` | Bitwise shift right | `5 >> 3` | `0` | +| `<<` | Bitwise shift left | `5 << 3` | `40` | + +### Other operators + +| Operator | Meaning | Example | Result | +| :------------: | :----------------------- | :-------------------------------------------------------------------------------------- | :------------ | +| `\|\|` | Concatenates strings | `'Hello' \|\| ' world'` | `Hello world` | +| `AT TIME ZONE` | Apply a time zone offset | _[View example](/influxdb/version/reference/sql/operators/other/#at-time-zone)_ | | + +## Keywords + +The following reserved keywords cannot be used as identifiers. + +```sql +AND +ALL +ANALYZE +AS +ASC +AT TIME ZONE +BETWEEN +BOTTOM +CASE +DESC +DISTINCT +EXISTS +EXPLAIN +FROM +GROUP BY +HAVING +IN +INNER JOIN +JOIN +LEFT JOIN +LIKE +LIMIT +NOT +EXISTS +NOT IN +OR +ORDER BY +FULL OUTER JOIN +RIGHT JOIN +SELECT +TOP +TYPE +UNION +UNION ALL +WHERE +WITH +``` + +## Conditional expressions + +Conditional expressions evaluate conditions based on input values. +The following conditional expressions are supported: + +| Expression | Description | +| :--------- | :----------------------------------------------------------------- | +| CASE | Allows for use of WHEN-THEN-ELSE statements. | +| COALESCE | Returns the first non-NULL expression in a specified list. | +| NULLIF | Returns a NULL value if value1 = value2. Otherwise returns value1. | + +## Statements and clauses + +InfluxDB SQL supports the following basic syntax for queries: + +```sql +[ WITH with_query [, …] ] +SELECT [ ALL | DISTINCT ] select_expr [, …] +[ FROM from_item [, …] ] +[ JOIN join_item [, …] ] +[ WHERE condition ] +[ GROUP BY grouping_element [, …] ] +[ HAVING condition] +[ UNION [ ALL ] ] +[ ORDER BY expression [ ASC | DESC ][, …] ] +[ LIMIT count ] +``` + +### SELECT statement and FROM clause + +Use the SQL `SELECT` statement to query data from a specific measurement or measurements. The `FROM` clause always accompanies the `SELECT` statement. + +#### Examples + +```sql +SELECT * FROM "h2o_feet" +``` +### WHERE clause + +Use the `WHERE` clause to filter results based on `fields`, `tags`, and `timestamps`. +Use predicates to evaluate each row. +Rows that evaluate as `TRUE` are returned in the result set. +Rows that evaluate as `FALSE` are omitted from the result set. + +#### Examples + +```sql +SELECT * FROM "h2o_feet" WHERE "water_level" <= 9 +``` +```sql +SELECT + * +FROM + "h2o_feet" +WHERE + "location" = 'santa_monica' + AND "level description" = 'below 3 feet' +``` + +### JOIN clause + +Use the `JOIN` clause to join data from multiple measurements (tables). +For more information about joins, see +[JOIN clause](/influxdb/version/reference/sql/join/). +The following join types are supported: + +{{< flex >}} +{{< flex-content "quarter" >}} + +

INNER JOIN

+ {{< svg svg="static/svgs/join-diagram.svg" class="inner small center" >}} +
+{{< /flex-content >}} +{{< flex-content "quarter" >}} + +

LEFT [OUTER] JOIN

+ {{< svg svg="static/svgs/join-diagram.svg" class="left small center" >}} +
+{{< /flex-content >}} +{{< flex-content "quarter" >}} + +

RIGHT [OUTER] JOIN

+ {{< svg svg="static/svgs/join-diagram.svg" class="right small center" >}} +
+{{< /flex-content >}} +{{< flex-content "quarter" >}} + +

FULL [OUTER] JOIN

+ {{< svg svg="static/svgs/join-diagram.svg" class="full small center" >}} +
+{{< /flex-content >}} +{{< /flex >}} + +{{< expand-wrapper >}} +{{% expand "INNER JOIN" %}} + +Inner joins combine rows from tables on the left and right side of the join +based on common column values defined in the `ON` clause. Rows that don't have +matching column values are not included in the output table. + +```sql +SELECT + * +FROM + home +INNER JOIN home_actions ON + home.room = home_actions.room + AND home.time = home_actions.time; +``` + +{{% /expand %}} +{{% expand "LEFT [OUTER] JOIN" %}} + +A left outer join returns all rows from the left side of the join and only +returns data from the right side of the join in rows with matching column values +defined in the `ON` clause. + +```sql +SELECT + * +FROM + home +LEFT OUTER JOIN home_actions ON + home.room = home_actions.room + AND home.time = home_actions.time; +``` + +{{% /expand %}} +{{% expand "RIGHT [OUTER] JOIN" %}} + +A right outer join returns all rows from the right side of the join and only +returns data from the left side of the join in rows with matching column values +defined in the `ON` clause. + +```sql +SELECT + * +FROM + home +RIGHT OUTER JOIN home_actions ON + home.room = home_actions.room + AND home.time = home_actions.time; +``` + +{{% /expand %}} +{{% expand "FULL [OUTER] JOIN" %}} + +A full outer join returns all data from the left and right sides of the join and +combines rows with matching column values defined in the `ON` clause. + +```sql +SELECT + * +FROM + home +FULL OUTER JOIN home_actions ON + home.room = home_actions.room + AND home.time = home_actions.time; +``` +{{% /expand %}} +{{< /expand-wrapper >}} + +### GROUP BY clause + +Use the `GROUP BY` clause to group query results based on specified column values. `GROUP BY` **requires** an aggregate or selector function in the `SELECT` statement. + +#### Examples + +```sql +SELECT + MEAN("water_level"), + "location" +FROM + "h2o_feet" +GROUP BY + "location" +``` + +### HAVING clause + + Use the `HAVING` clause to filter query results based on a specified condition. + The `HAVING` clause must _follow_ the `GROUP BY` clause, but _precede_ the `ORDER BY` clause. + +#### Examples + +```sql +SELECT + MEAN("water_level"), + "location" +FROM + "h2o_feet" +GROUP BY + "location" +HAVING + MEAN("water_level") > 4 +ORDER BY + "location" +``` + +### UNION clause + +The `UNION` clause combines the results of two or more `SELECT` statements without returning any duplicate rows. `UNION ALL` returns all results, including duplicates. + +#### Examples + +```sql +SELECT + 'pH' +FROM + "h2o_pH" +UNION ALL +SELECT + "location" +FROM + "h2o_quality" +``` + +### ORDER BY clause + +The `ORDER BY` clause orders results by specified columns and order. +Sort data based on fields, tags, and timestamps. +The following orders are supported: + +- `ASC`: ascending _(default)_ +- `DESC`: descending + +#### Examples + +```sql +SELECT + "water_level", + "location" +FROM + "h2o_feet" +ORDER BY + "location", + "time" DESC +``` + +### LIMIT clause + +The `LIMIT` clause limits the number of rows to return. +The defined limit should be a non-negative integer. + +#### Examples + +```sql +SELECT + "water_level", + "location" +FROM + "h2o_feet" +LIMIT + 10 +``` + +### WITH clause + +The `WITH` clause provides a way to write auxiliary statements for use in a larger query. +It can help break down large, complicated queries into simpler forms. + +```sql +WITH summary_data as +(SELECT degrees, location, time + FROM average_temperature) +SELECT * FROM summary_data +``` + +### OVER clause + +The `OVER` clause is used with SQL window functions. +A **window function** performs a calculation across a set of table rows that are related in some way to the current row. + While similar to aggregate functions, window functions output results into rows retaining their separate identities. + +```sql +SELECT + time, + water_level +FROM + ( + SELECT + time, + "water_level", + row_number() OVER ( + order by + water_level desc + ) as rn + FROM + h2o_feet + ) +WHERE + rn <= 3; +``` + +## Comments + +Use comments to describe and add detail or notes to your queries. + +- Single line comments use the double hyphen `--` symbol. Single line comments end with a line break. +- Multi-line comments begin with `/*` and end with ` */`. + +```sql +-- Single-line comment + +/* + * Multi-line comment + */ +``` + +## Schema information + +{{% product-name %}} supports the following metadata schema queries: + +```sql +SHOW tables + +SHOW columns FROM +``` + +## Functions + +Following is a list of supported functions by type. + +### Aggregate functions + +An aggregate function performs a calculation or computation on a set of data values in a column and returns a single value. + +| Function | Description | +| :------- | :--------------------------------------------------------- | +| COUNT() | Returns returns the number of rows from a field or tag key | +| AVG() | Returns the average value of a column | +| SUM() | Returns the summed value of a column | +| MEAN() | Returns the mean value of a column | +| MIN() | Returns the smallest value of the selected column | +| MAX() | Returns the largest value of the selected column | + +#### Examples + +```sql + +SELECT COUNT("water_level") +FROM "h2o_feet" + +SELECT AVG("water_level"), "location" +FROM "h2o_feet" +GROUP BY "location" + +SELECT SUM("water_level"), "location" +FROM "h2o_feet" +GROUP BY "location" +``` + +### Selector functions + +Selector functions are unique to InfluxDB. They behave like aggregate functions in that they take a row of data and compute it down to a single value. However, selectors are unique in that they return a **time value** in addition to the computed value. In short, selectors return an aggregated value along with a timestamp. + +| Function | Description | +| :--------------- | :-------------------------------------------------------------- | +| SELECTOR_FIRST() | Returns the first value of a selected column and timestamp. | +| SELECTOR_LAST() | Returns the last value of a selected column and timestamp. | +| SELECTOR_MIN() | Returns the smallest value of a selected column and timestamp. | +| SELECTOR_MAX() | Returns the largest value of a selected column and timestamp. | + +#### Examples + +```sql +SELECT +SELECTOR_MAX("pH", time)['value'], +SELECTOR_MAX("pH", time)['time'] +FROM "h2o_pH" + +SELECT +SELECTOR_LAST("water_level", time)['value'], +SELECTOR_LAST("water_level", time)['time'] +FROM "h2o_feet" +WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19T00:00:00Z' + +``` + +### Date and time functions + +| Function | Description | +| :----------- | :---------------------------------------------------------------------------------------------- | +| DATE_BIN() | Bins the input timestamp into a specified interval. | +| DATE_TRUNC() | Truncates a timestamp expression based on the date part specified, such as hour, day, or month. | +| DATE_PART() | Returns the specified part of a date. | +| NOW() | Returns the current time (UTC). | + +#### Examples + +```sql +SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z') AS "_time", +SUM(water_level) +FROM "h2o_feet" +GROUP BY "_time" +``` + +```sql +SELECT DATE_TRUNC('month',time) AS "date", +SUM(water_level) +FROM "h2o_feet" +GROUP BY time +``` + +### Approximate functions + +| Function | Description | +| :--------------------------------- | :-------------------------------------------------------------------------------------------- | +| APPROX_MEDIAN | Returns the approximate median of input values. | +| APPROX_DISTINCT | Returns the approximate count of the number of distinct values. Implemented only for strings. | +| APPROX_PERCENTILE_CONT | Returns the approximate percentile of input values. | +| APPROX_PERCENTILE_CONT_WITH_WEIGHT | Returns the approximate percentile of input values with weight. | + + +### Math functions + +| Function | Description | +| :------- | :------------------------------------------------------------------------------- | +| ABS() | Absolute value | +| ACOS() | Inverse cosine | +| ASIN() | Inverse sine | +| ATAN() | Inverse tangent | +| ATAN2() | Inverse tangent of y / x | +| CEIL() | Returns the smallest integer value greater than or equal to the specified number | +| COS() | Cosine | +| EXP() | Exponential | +| FLOOR() | Nearest integer less than or equal to the specified number | +| LN() | Natural logarithm | +| LOG10() | Base 10 logarithm | +| LOG2() | Base 2 logarithm | +| POWER() | Returns the value of a number raised to the power of the number | +| ROUND() | Round to the nearest integer | +| SIGNUM() | Sign of the argument (-1, 0, +1) | +| SINE() | Sine | +| SQRT() | Returns the square root of a number | +| TAN() | Tangent | +| TRUNC() | Truncates a number to the specified number of decimal places | + +### Conditional functions + +| Function | Description | +| :------- | :--------------------------------------------------------------------------------------------------------- | +| COALESCE | Returns the first argument that is not null. If all arguments are null, then `COALESCE` will return nulls. | +| NULLIF | Returns a null value if value1 equals value2, otherwise returns value1. | + + +### Regular expression functions + +| Function | Description | +| :------------- | :---------------------------------------------------------------------------- | +| REGEXP_MATCH | Matches a regular expression against a string and returns matched substrings. | +| REGEXP_REPLACE | Replaces substrings that match a regular expression by a new substring. | diff --git a/content/shared/sql-reference/data-types.md b/content/shared/sql-reference/data-types.md new file mode 100644 index 000000000..4d6c714d4 --- /dev/null +++ b/content/shared/sql-reference/data-types.md @@ -0,0 +1,212 @@ + + +{{< product-name >}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) +implementation of SQL. +Data types define the type of values that can be stored in table columns. +In InfluxDB's SQL implementation, a **measurement** is structured as a table, +and **tags**, **fields** and **timestamps** are exposed as columns. + +## SQL and Arrow data types + +In SQL, each column, expression, and parameter has a data type. +A data type is an attribute that specifies the type of data that the object can hold. +DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. +All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html). + +Both SQL and Arrow data types play an important role in how data is operated on +during query execution and returned in query results. + +> [!Note] +> When performing casting operations, cast to the SQL data type unless you use +> [`arrow_cast()`](/influxdb/version/reference/sql/functions/misc/#arrow_cast) +> to cast to a specific Arrow type. +> Names and identifiers in SQL are _case-insensitive_ by default. For example: +> +> ```sql +> SELECT +> '99'::BIGINT, +> '2019-09-18T00:00:00Z'::timestamp +> ``` + +- [String types](#string-types) +- [Numeric types](#numeric-types) + - [Integers](#integers) + - [Unsigned integers](#unsigned-integers) + - [Floats](#floats) +- [Date and time data types](#date-and-time-data-types) + - [Timestamp](#timestamp) + - [Interval](#interval) +- [Boolean types](#boolean-types) +- [Unsupported SQL types](#unsupported-sql-types) +- [Data types compatible with parameters](#data-types-compatible-with-parameters) + +## String types + +| SQL data type | Arrow data type | Description | +| :------------ | :-------------- | --------------------------------- | +| STRING | UTF8 | Character string, variable-length | +| CHAR | UTF8 | Character string, fixed-length | +| VARCHAR | UTF8 | Character string, variable-length | +| TEXT | UTF8 | Variable unlimited length | + +##### Example string literals + +```sql +'abcdefghijk' +'time' +'h2o_temperature' +``` + +## Numeric types + +The following numeric types are supported: + +| SQL data type | Arrow data type | Description | +| :-------------- | :-------------- | :--------------------------- | +| BIGINT | INT64 | 64-bit signed integer | +| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | +| DOUBLE | FLOAT64 | 64-bit floating-point number | + +### Integers + +InfluxDB SQL supports the 64-bit signed integers: + +**Minimum signed integer**: `-9223372036854775808` +**Maximum signed integer**: `9223372036854775807` + +##### Example integer literals + +```sql +234 +-446 +5 +``` + +### Unsigned integers + +InfluxDB SQL supports the 64-bit unsigned integers: + +**Minimum unsigned integer**: `0` +**Maximum unsigned integer**: `18446744073709551615` + +##### Example unsigned integer literals + +Unsigned integer literals are comprised of an integer cast to the `BIGINT UNSIGNED` type: + +```sql +234::BIGINT UNSIGNED +458374893::BIGINT UNSIGNED +5::BIGINT UNSIGNED +``` + +### Floats + +InfluxDB SQL supports the 64-bit double floating point values. +Floats can be a decimal point, decimal integer, or decimal fraction. + +##### Example float literals + +```sql +23.8 +-446.89 +5.00 +0.033 +``` + +## Date and time data types + +InfluxDB SQL supports the following DATE/TIME data types: + +| SQL data type | Arrow data type | Description | +| :------------ | :--------------------------------- | :-------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with no time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | + +### Timestamp + +A time type is a single point in time using nanosecond precision. + +The following date and time formats are supported: + +```sql +YYYY-MM-DDT00:00:00.000Z +YYYY-MM-DDT00:00:00.000-00:00 +YYYY-MM-DD 00:00:00.000-00:00 +YYYY-MM-DDT00:00:00Z +YYYY-MM-DD 00:00:00.000 +YYYY-MM-DD 00:00:00 +``` + +##### Example timestamp literals + +```sql +'2023-01-02T03:04:06.000Z' +'2023-01-02T03:04:06.000-00:00' +'2023-01-02 03:04:06.000-00:00' +'2023-01-02T03:04:06Z' +'2023-01-02 03:04:06.000' +'2023-01-02 03:04:06' +``` + +### Interval + +The INTERVAL data type can be used with the following precision: + +- nanosecond +- microsecond +- millisecond +- second +- minute +- hour +- day +- week +- month +- year +- century + +##### Example interval literals +```sql +INTERVAL '10 minutes' +INTERVAL '1 year' +INTERVAL '2 days 1 hour 31 minutes' +``` + +## Boolean types + +Booleans store TRUE or FALSE values. + +| SQL data type | Arrow data type | Description | +| :------------ | :-------------- | :------------------- | +| BOOLEAN | Boolean | True or false values | + +##### Example boolean literals + +```sql +true +TRUE +false +FALSE +``` + +## Unsupported SQL types + +The following SQL types are not currently supported: + +- UUID +- BLOB +- CLOB +- BINARY +- VARBINARY +- REGCLASS +- NVARCHAR +- CUSTOM +- ARRAY +- ENUM +- SET +- DATETIME +- BYTEA + +## Data types compatible with parameters + +For information about data types that can be substituted by parameters, +see how to [use parameterized queries with SQL](/influxdb/version/query-data/sql/parameterized-queries/). diff --git a/content/shared/sql-reference/explain.md b/content/shared/sql-reference/explain.md new file mode 100644 index 000000000..9a746562c --- /dev/null +++ b/content/shared/sql-reference/explain.md @@ -0,0 +1,108 @@ +The `EXPLAIN` command returns the [logical plan](/influxdb/version/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb/version/reference/internals/query-plan/#physical-plan) for the +specified SQL statement. + +```sql +EXPLAIN [ANALYZE] [VERBOSE] statement +``` + +- [`EXPLAIN`](#explain) + - [Example `EXPLAIN`](#example-explain) +- [`EXPLAIN ANALYZE`](#explain-analyze) + - [Example `EXPLAIN ANALYZE`](#example-explain-analyze) +- [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose) + - [Example `EXPLAIN ANALYZE VERBOSE`](#example-explain-analyze-verbose) + +## `EXPLAIN` + +Returns the logical plan and physical (execution) plan of a statement. +To output more details, use `EXPLAIN VERBOSE`. + +`EXPLAIN` doesn't execute the statement. +To execute the statement and view runtime metrics, use [`EXPLAIN ANALYZE`](#explain-analyze). + +### Example `EXPLAIN` + +```sql +EXPLAIN +SELECT + room, + avg(temp) AS temp +FROM home +GROUP BY room +``` + +{{< expand-wrapper >}} +{{% expand "View `EXPLAIN` example output" %}} + +| | plan_type | plan | +|---:|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0 | logical_plan | Projection: home.room, AVG(home.temp) AS temp | +| | | Aggregate: groupBy=[[home.room]], aggr=[[AVG(home.temp)]] | +| | | TableScan: home projection=[room, temp] | +| 1 | physical_plan | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp] | +| | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)] | +| | | CoalesceBatchesExec: target_batch_size=8192 | +| | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8 | +| | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)] | +| | | ParquetExec: file_groups={8 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet, 70434/116281/b7a9e7c57fbfc3bba9427e4b3e35c89e001e2e618b0c7eb9feb4d50a3932f4db/d29370d4-262f-0d32-2459-fe7b099f682f.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], ...]}, projection=[room, temp] | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## `EXPLAIN ANALYZE` + +Executes a statement and returns the execution plan and runtime metrics of the statement. +The report includes the [logical plan](/influxdb/version/reference/internals/query-plan/#logical-plan) and the [physical plan](/influxdb/version/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution. + +If the plan requires reading lots of data files, `EXPLAIN` and `EXPLAIN ANALYZE` may truncate the list of files in the report. +To output more information, including intermediate plans and paths for all scanned Parquet files, use [`EXPLAIN ANALYZE VERBOSE`](#explain-analyze-verbose). + +### Example `EXPLAIN ANALYZE` + +```sql +EXPLAIN ANALYZE +SELECT + room, + avg(temp) AS temp +FROM home +WHERE time >= '2023-01-01' AND time <= '2023-12-31' +GROUP BY room +``` + +{{< expand-wrapper >}} +{{% expand "View `EXPLAIN ANALYZE` example output" %}} + +| | plan_type | plan | +|---:|:------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0 | Plan with Metrics | ProjectionExec: expr=[room@0 as room, AVG(home.temp)@1 as temp], metrics=[output_rows=2, elapsed_compute=4.768µs] | +| | | AggregateExec: mode=FinalPartitioned, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=140.405µs] | +| | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=2, elapsed_compute=6.821µs] | +| | | RepartitionExec: partitioning=Hash([room@0], 8), input_partitions=8, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=2, elapsed_compute=18.408µs, repart_time=59.698µs, fetch_time=1.057882762s, send_time=5.83µs] | +| | | AggregateExec: mode=Partial, gby=[room@0 as room], aggr=[AVG(home.temp)], ordering_mode=Sorted, metrics=[output_rows=2, elapsed_compute=137.577µs] | +| | | RepartitionExec: partitioning=RoundRobinBatch(8), input_partitions=6, preserve_order=true, sort_exprs=room@0 ASC, metrics=[output_rows=46, elapsed_compute=26.637µs, repart_time=6ns, fetch_time=399.971411ms, send_time=6.658µs] | +| | | ProjectionExec: expr=[room@0 as room, temp@2 as temp], metrics=[output_rows=46, elapsed_compute=3.102µs] | +| | | CoalesceBatchesExec: target_batch_size=8192, metrics=[output_rows=46, elapsed_compute=25.585µs] | +| | | FilterExec: time@1 >= 1672531200000000000 AND time@1 <= 1703980800000000000, metrics=[output_rows=46, elapsed_compute=26.51µs] | +| | | ParquetExec: file_groups={6 groups: [[70434/116281/404d73cea0236530ea94f5470701eb814a8f0565c0e4bef5a2d2e33dfbfc3567/1be334e8-0af8-00da-2615-f67cd4be90f7.parquet], [70434/116281/c14418ba28a22a3abb693a1cb326a63b62dc611aec58c9bed438fdafd3bc5882/8b29ae98-761f-0550-2fe4-ee77503658e9.parquet], [70434/116281/fa677477eed622ae8123da1251aa7c351f801e2ee2f0bc28c0fe3002a30b3563/65bb4dc3-04e1-0e02-107a-90cee83c51b0.parquet], [70434/116281/db162bdd30261019960dd70da182e6ebd270284569ecfb5deffea7e65baa0df9/2505e079-67c5-06d9-3ede-89aca542dd18.parquet], [70434/116281/0c025dcccae8691f5fd70b0f131eea4ca6fafb95a02f90a3dc7bb015efd3ab4f/3f3e44c3-b71e-0ca4-3dc7-8b2f75b9ff86.parquet], ...]}, projection=[room, time, temp], output_ordering=[room@0 ASC, time@1 ASC], predicate=time@6 >= 1672531200000000000 AND time@6 <= 1703980800000000000, pruning_predicate=time_max@0 >= 1672531200000000000 AND time_min@1 <= 1703980800000000000, required_guarantees=[], metrics=[output_rows=46, elapsed_compute=6ns, predicate_evaluation_errors=0, bytes_scanned=3279, row_groups_pruned_statistics=0, file_open_errors=0, file_scan_errors=0, pushdown_rows_filtered=0, num_predicate_creation_errors=0, row_groups_pruned_bloom_filter=0, page_index_rows_filtered=0, time_elapsed_opening=398.462968ms, time_elapsed_processing=1.626106ms, time_elapsed_scanning_total=1.36822ms, page_index_eval_time=33.474µs, pushdown_eval_time=14.267µs, time_elapsed_scanning_until_data=1.27694ms] | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## `EXPLAIN ANALYZE VERBOSE` + +Executes a statement and returns the execution plan, runtime metrics, and additional details helpful for debugging the statement. + +The report includes the following: + +- the [logical plan](/influxdb/version/reference/internals/query-plan/#logical-plan) +- the [physical plan](/influxdb/version/reference/internals/query-plan/#physical-plan) annotated with execution counters, number of rows produced, and runtime metrics sampled during the query execution +- Information truncated in the `EXPLAIN` report--for example, the paths for all [Parquet files retrieved for the query](/influxdb/version/reference/internals/query-plan/#file_groups). +- All intermediate physical plans that DataFusion and the [Querier](/influxdb/version/reference/internals/storage-engine/#querier) generate before generating the final physical plan--helpful in debugging to see when an [`ExecutionPlan` node](/influxdb/version/reference/internals/query-plan/#executionplan-nodes) is added or removed, and how InfluxDB optimizes the query. + +### Example `EXPLAIN ANALYZE VERBOSE` + +```SQL +EXPLAIN ANALYZE VERBOSE SELECT temp FROM home +WHERE time >= now() - INTERVAL '7 days' AND room = 'Kitchen' +ORDER BY time +``` diff --git a/content/shared/sql-reference/functions/_index.md b/content/shared/sql-reference/functions/_index.md new file mode 100644 index 000000000..6aa92bf02 --- /dev/null +++ b/content/shared/sql-reference/functions/_index.md @@ -0,0 +1,3 @@ + + +{{< children >}} \ No newline at end of file diff --git a/content/shared/sql-reference/functions/aggregate.md b/content/shared/sql-reference/functions/aggregate.md new file mode 100644 index 000000000..b6b26fa1e --- /dev/null +++ b/content/shared/sql-reference/functions/aggregate.md @@ -0,0 +1,1453 @@ +SQL aggregate functions aggregate values in a specified column for each +group or SQL partition and return a single row per group containing the +aggregate value. + +- [General aggregate functions](#general-aggregate-functions) + - [array_agg](#array_agg) + - [avg](#avg) + - [bit_and](#bit_and) + - [bit_or](#bit_or) + - [bit_xor](#bit_xor) + - [bool_and](#bool_and) + - [bool_or](#bool_or) + - [count](#count) + - [first_value](#first_value) + - [last_value](#last_value) + - [max](#max) + - [mean](#mean) + - [median](#median) + - [min](#min) + - [sum](#sum) +- [Statistical aggregate functions](#statistical-aggregate-functions) + - [corr](#corr) + - [covar](#covar) + - [covar_pop](#covar_pop) + - [covar_samp](#covar_samp) + - [regr_avgx](#regr_avgx) + - [regr_avgy](#regr_avgy) + - [regr_count](#regr_count) + - [regr_intercept](#regr_intercept) + - [regr_r2](#regr_r2) + - [regr_slope](#regr_slope) + - [regr_sxx](#regr_sxx) + - [regr_syy](#regr_syy) + - [regr_sxy](#regr_sxy) + - [stddev](#stddev) + - [stddev_pop](#stddev_pop) + - [stddev_samp](#stddev_samp) + - [var](#var) + - [var_pop](#var_pop) + - [var_samp](#var_samp) +- [Approximate aggregate functions](#approximate-aggregate-functions) + - [approx_distinct](#approx_distinct) + - [approx_median](#approx_median) + - [approx_percentile_cont](#approx_percentile_cont) + - [approx_percentile_cont_with_weight](#approx_percentile_cont_with_weight) + +--- + +## General aggregate functions + +- [array_agg](#array_agg) +- [avg](#avg) +- [bit_and](#bit_and) +- [bit_or](#bit_or) +- [bit_xor](#bit_xor) +- [bool_and](#bool_and) +- [bool_or](#bool_or) +- [count](#count) +- [first_value](#first_value) +- [last_value](#last_value) +- [max](#max) +- [mean](#mean) +- [median](#median) +- [min](#min) +- [sum](#sum) + +### array_agg + +Returns an array created from the expression elements. + +> [!Note] +> `array_agg` returns a `LIST` arrow type which is not supported by InfluxDB. +> To use with InfluxDB, use bracket notation to reference the index of an element +> in the returned array. Arrays are 1-indexed. + +```sql +array_agg(expression) +``` + +#### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `array_agg` query example" %}} + +_The following example uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + array_agg(temp)[3] AS '3rd_temp' +FROM home +GROUP BY room +``` + +| room | 3rd_temp | +| :---------- | -------: | +| Kitchen | 22.7 | +| Living Room | 21.8 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### avg + +Returns the average of numeric values in the specified column. + +```sql +avg(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### Aliases + +- `mean` + +{{< expand-wrapper >}} +{{% expand "View `avg` query example" %}} + +```sql +SELECT + location, + avg(water_level) AS water_level_avg +FROM h2o_feet +GROUP BY location +``` + +| location | water_level_avg | +| :----------- | -----------------: | +| coyote_creek | 5.359142420303919 | +| santa_monica | 3.5307120942458843 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### bit_and + +Computes the bitwise `AND` of all non-null input values. + +```sql +bit_and(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `bit_and` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + bit_and(precip::BIGINT) AS precip_bit_and +FROM weather +GROUP BY location +``` + +| location | precip_bit_and | +| :------------ | -------------: | +| Concord | 0 | +| Hayward | 0 | +| San Francisco | 0 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### bit_or + +Computes the bitwise OR of all non-null input values. + +```sql +bit_or(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `bit_or` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + bit_or(precip::BIGINT) AS precip_bit_or +FROM weather +GROUP BY location +``` + +| location | precip_bit_or | +| :------------ | ------------: | +| Concord | 7 | +| Hayward | 7 | +| San Francisco | 7 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### bit_xor + +Computes the bitwise exclusive OR of all non-null input values. + +```sql +bit_xor(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `bit_xor` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + bit_xor(precip::BIGINT) AS precip_bit_xor +FROM weather +GROUP BY location +``` + +| location | precip_bit_xor | +| :------------ | -------------: | +| Concord | 4 | +| Hayward | 6 | +| San Francisco | 4 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### bool_and + +Returns `true` if _all_ non-null input values are `true`, otherwise returns `false`. + +```sql +bool_and(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `bool_and` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + bool_and(precip > 0) AS precip_bool_and +FROM weather +GROUP BY location +``` + +| location | precip_bool_and | +| :------------ | --------------: | +| Concord | false | +| Hayward | false | +| San Francisco | false | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### bool_or + +Returns `true` if _any_ non-null input value is `true`, otherwise returns `false`. + +```sql +bool_or(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `bool_or` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + bool_or(precip > 0) AS precip_bool_or +FROM weather +GROUP BY location +``` + +| location | precip_bool_or | +| :------------ | -------------: | +| Concord | true | +| Hayward | true | +| San Francisco | true | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### count + +Returns the number of rows in the specified column. + +Count includes _null_ values in the total count. +To exclude _null_ values from the total count, include ` IS NOT NULL` +in the `WHERE` clause. + +```sql +count(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `count` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + count(precip) AS precip_count +FROM weather +GROUP BY location +``` + +| location | precip_count | +| :------------ | -----------: | +| Concord | 1094 | +| Hayward | 1096 | +| San Francisco | 1096 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### first_value + +Returns the first element in an aggregation group according to the specified ordering. +If no ordering is specified, returns an arbitrary element from the group. + +```sql +first_value(expression [ORDER BY expression]) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `first_value` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + first_value(temp_max ORDER BY time) AS temp_max_first_value +FROM weather +GROUP BY location +``` + +| location | temp_max_first_value | +| :------------ | -------------------: | +| Concord | 59 | +| Hayward | 57 | +| San Francisco | 66 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### last_value + +Returns the last element in an aggregation group according to the specified ordering. +If no ordering is specified, returns an arbitrary element from the group. + +```sql +last_value(expression [ORDER BY expression]) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `last_value` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + last_value(temp_max ORDER BY time) AS temp_max_last_value +FROM weather +GROUP BY location +``` + +| location | temp_max_last_value | +| :------------ | ------------------: | +| Concord | 59 | +| Hayward | 58 | +| San Francisco | 62 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### max + +Returns the maximum value in the specified column. + +```sql +max(expression) +``` + +_To return both the maximum value and its associated timestamp, use +[`selector_max`](/influxdb/version/reference/sql/functions/selector/#selector_max)._ + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `max` query example" %}} + +```sql +SELECT + location, + max(water_level) AS water_level_max +FROM h2o_feet +GROUP BY location +``` + +| location | water_level_max | +| :----------- | --------------: | +| santa_monica | 7.205 | +| coyote_creek | 9.964 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### mean + +_Alias of [avg](#avg)._ + +### median + +Returns the median value in the specified column. + +``` +median(expression) +``` + +#### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `median` query example" %}} + +```sql +SELECT + location, + median(water_level) AS water_level_max +FROM h2o_feet +GROUP BY location +``` + +| location | water_level_median | +| :----------- | -----------------: | +| coyote_creek | 5.4645 | +| santa_monica | 3.471 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### min + +Returns the minimum value in the specified column. + +```sql +min(expression) +``` + +_To return both the minimum value and its associated timestamp, use +[`selector_max`](/influxdb/version/reference/sql/functions/selector/#selector_min)._ + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `min` query example" %}} + +```sql +SELECT + location, + min(water_level) AS water_level_min +FROM h2o_feet +GROUP BY location +``` + +| location | water_level_min | +| :----------- | --------------: | +| coyote_creek | -0.61 | +| santa_monica | -0.243 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### sum + +Returns the sum of all values in the specified column. + +```sql +sum(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `sum` query example" %}} + +```sql +SELECT + location, + sum(water_level) AS water_level_sum +FROM h2o_feet +GROUP BY location +``` + +| location | water_level_sum | +| :----------- | -----------------: | +| santa_monica | 27024.070369358 | +| coyote_creek | 40750.918963991004 | + +{{% /expand %}} +{{< /expand-wrapper >}} + + +## Statistical aggregate functions + +- [corr](#corr) +- [covar](#covar) +- [covar_pop](#covar_pop) +- [covar_samp](#covar_samp) +- [regr_avgx](#regr_avgx) +- [regr_avgy](#regr_avgy) +- [regr_count](#regr_count) +- [regr_intercept](#regr_intercept) +- [regr_r2](#regr_r2) +- [regr_slope](#regr_slope) +- [regr_sxx](#regr_sxx) +- [regr_syy](#regr_syy) +- [regr_sxy](#regr_sxy) +- [stddev](#stddev) +- [stddev_pop](#stddev_pop) +- [stddev_samp](#stddev_samp) +- [var](#var) +- [var_pop](#var_pop) +- [var_samp](#var_samp) + +### corr + +Returns the coefficient of correlation between two numeric values. + +```sql +corr(expression1, expression2) +``` + +##### Arguments + +- **expression1**: First column or literal value to operate on. +- **expression2**: Second column or literal value to operate on. + +{{< expand-wrapper >}} +{{% expand "View `corr` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + corr(hum, temp) AS correlation +FROM home +GROUP BY room +``` + +| room | correlation | +| :---------- | ------------------: | +| Living Room | 0.43665270457835725 | +| Kitchen | 0.6741766954929539 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### covar + +Returns the covariance of a set of number pairs. + +```sql +covar(expression1, expression2) +``` + +##### Arguments + +- **expression1**: First column or literal value to operate on. +- **expression2**: Second column or literal value to operate on. + +{{< expand-wrapper >}} +{{% expand "View `covar` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + covar(hum, temp) AS covar +FROM home +GROUP BY room +``` + +| room | covar | +| :---------- | ------------------: | +| Living Room | 0.03346153846153959 | +| Kitchen | 0.11134615384615432 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### covar_pop + +Returns the population covariance of a set of number pairs. + +```sql +covar_pop(expression1, expression2) +``` + +##### Arguments + +- **expression1**: First column or literal value to operate on. +- **expression2**: Second column or literal value to operate on. + +{{< expand-wrapper >}} +{{% expand "View `covar_pop` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + covar_pop(hum, temp) AS covar_pop +FROM home +GROUP BY room +``` + +| room | covar_pop | +| :---------- | -------------------: | +| Kitchen | 0.10278106508875783 | +| Living Room | 0.030887573964498087 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### covar_samp + +Returns the sample covariance of a set of number pairs. + +```sql +covar_samp(expression1, expression2) +``` + +##### Arguments + +- **expression1**: First column or literal value to operate on. +- **expression2**: Second column or literal value to operate on. + +{{< expand-wrapper >}} +{{% expand "View `covar_samp` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + covar_samp(hum, temp) AS covar_samp +FROM home +GROUP BY room +``` + +| room | covar_samp | +| :---------- | ------------------: | +| Kitchen | 0.11134615384615432 | +| Living Room | 0.03346153846153959 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_avgx + +Computes the average of the independent variable (input), `expression_x`, for the +non-null dependent variable, `expression_y`. + +```sql +regr_avgx(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_avgx` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_avgx(temp_min, temp_max) AS temp_regr_avgx +FROM weather +GROUP BY location +``` + +| location | temp_regr_avgx | +| :------------ | ----------------: | +| Concord | 75.54379562043796 | +| Hayward | 69.14808043875686 | +| San Francisco | 67.59945255474454 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_avgy + +Computes the average of the dependent variable (output), `expression_y`, for the +non-null dependent variable, `expression_y`. + +```sql +regr_avgy(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_avgy` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_avgy(temp_min, temp_max) AS temp_regr_avgy +FROM weather +GROUP BY location +``` + +| location | temp_regr_avgy | +| :------------ | -----------------: | +| Concord | 50.153284671532845 | +| Hayward | 50.913162705667276 | +| San Francisco | 51.52372262773722 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_count + +Counts the number of non-null paired data points. + +```sql +regr_count(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_count` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_count(temp_min, temp_max) AS temp_regr_count +FROM weather +GROUP BY location +``` + +| location | temp_regr_count | +| :------------ | --------------: | +| Concord | 1096 | +| Hayward | 1094 | +| San Francisco | 1096 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_intercept + +Computes the y-intercept of the linear regression line. +For the equation `(y = kx + b)`, this function returns `b`. + +```sql +regr_intercept(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_intercept` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_intercept(temp_min, temp_max) AS temp_regr_intercept +FROM weather +GROUP BY location +``` + +| location | temp_regr_intercept | +| :------------ | ------------------: | +| Concord | 11.636281392206769 | +| Hayward | 12.876956842745152 | +| San Francisco | 19.125237647086607 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_r2 + +Computes the square of the correlation coefficient between the independent and +dependent variables. + +```sql +regr_r2(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_r2` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_r2(temp_min, temp_max) AS temp_regr_r2 +FROM weather +GROUP BY location +``` + +| location | temp_regr_r2 | +| :------------ | -----------------: | +| Concord | 0.6474628308450441 | +| Hayward | 0.5166296626320914 | +| San Francisco | 0.5032317511200297 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_slope + +Returns the slope of the linear regression line for non-null pairs in aggregate columns. +Given input column `Y` and `X`: `regr_slope(Y, X)` returns the slope +(`k` in `Y = k*X + b`) using minimal RSS fitting. + +``` sql +regr_slope(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: Y expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: X expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_slope` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_slope(temp_min, temp_max) AS temp_regr_slope +FROM weather +GROUP BY location +``` + +| location | temp_regr_slope | +| :------------ | -----------------: | +| Concord | 0.5098632252058237 | +| Hayward | 0.5500688612261629 | +| San Francisco | 0.4792714105844738 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_sxx + +Computes the sum of squares of the independent variable. + +```sql +regr_sxx(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_sxx` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_sxx(temp_min, temp_max) AS temp_regr_sxx +FROM weather +GROUP BY location +``` + +| location | temp_regr_sxx | +| :------------ | -----------------: | +| Concord | 210751.89781021897 | +| Hayward | 99644.01096892142 | +| San Francisco | 77413.15967153282 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_syy + +Computes the sum of squares of the dependent variable. + +```sql +regr_syy(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_syy` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_syy(temp_min, temp_max) AS temp_regr_syy +FROM weather +GROUP BY location +``` + +| location | temp_regr_syy | +| :------------ | -----------------: | +| Concord | 84618.24817518248 | +| Hayward | 58358.750457038404 | +| San Francisco | 35335.38321167884 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### regr_sxy + +Computes the sum of products of paired data points. + +```sql +regr_sxy(expression_y, expression_x) +``` + +#### Arguments + +- **expression_y**: Dependent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Independent variable. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `regr_sxy` query example" %}} + +_The following example uses the +[NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data)._ + +```sql +SELECT + location, + regr_sxy(temp_min, temp_max) AS temp_regr_sxy +FROM weather +GROUP BY location +``` + +| location | temp_regr_sxy | +| :------------ | -----------------: | +| Concord | 107454.64233576645 | +| Hayward | 54811.06764168191 | +| San Francisco | 37101.914233576645 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### stddev + +Returns the standard deviation of a set of numbers. + +```sql +stddev(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `stddev` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + stddev(co) AS stddev +FROM home +GROUP BY room +``` + +| room | stddev | +| :---------- | ----------------: | +| Living Room | 5.885662718931967 | +| Kitchen | 9.321879418735037 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### stddev_pop + +Returns the population standard deviation of a set of numbers. + +```sql +stddev_pop(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `stddev_pop` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + stddev_pop(co) AS stddev_pop +FROM home +GROUP BY room +``` + +| room | stddev_pop | +| :---------- | ----------------: | +| Kitchen | 8.956172047894082 | +| Living Room | 5.654761830612032 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### stddev_samp + +Returns the sample standard deviation of a set of numbers. + +```sql +stddev_samp(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `stddev_samp` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + stddev_samp(co) AS stddev_samp +FROM home +GROUP BY room +``` + +| room | stddev_samp | +| :---------- | ----------------: | +| Living Room | 5.885662718931967 | +| Kitchen | 9.321879418735037 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### var + +Returns the statistical variance of a set of numbers. + +```sql +var(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `var` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + var(co) AS var +FROM home +GROUP BY room +``` + +| room | var | +| :---------- | ----------------: | +| Living Room | 34.64102564102564 | +| Kitchen | 86.89743589743587 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### var_pop + +Returns the statistical population variance of a set of numbers. + +```sql +var_pop(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `var_pop` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + var_pop(co) AS var_pop +FROM home +GROUP BY room +``` + +| room | var_pop | +| :---------- | -----------------: | +| Living Room | 31.976331360946745 | +| Kitchen | 80.21301775147927 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### var_samp + +Returns the statistical sample variance of a set of numbers. + +```sql +var_samp(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `var_samp` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + var_samp(co) AS var_samp +FROM home +GROUP BY room +``` + +| room | var_samp | +| :---------- | ----------------: | +| Kitchen | 86.89743589743587 | +| Living Room | 34.64102564102564 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Approximate aggregate functions + +- [approx_distinct](#approx_distinct) +- [approx_median](#approx_median) +- [approx_percentile_cont](#approx_percentile_cont) +- [approx_percentile_cont_with_weight](#approx_percentile_cont_with_weight) + +### approx_distinct + +Returns the approximate number of distinct input values calculated using the +HyperLogLog algorithm. + +```sql +approx_distinct(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `approx_distinct` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + approx_distinct(co::string) AS approx_distinct +FROM home +GROUP BY room +``` + +| room | approx_distinct | +| :---------- | --------------: | +| Living Room | 7 | +| Kitchen | 8 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### approx_median + +Returns the approximate median (50th percentile) of input values. +It is an alias of `approx_percentile_cont(x, 0.5)`. + +```sql +approx_median(expression) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `approx_median` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + approx_median(temp) AS approx_median +FROM home +GROUP BY room +``` + +| room | approx_median | +| :---------- | ------------: | +| Kitchen | 22.7 | +| Living Room | 22.3 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### approx_percentile_cont + +Returns the approximate percentile of input values using the t-digest algorithm. + +```sql +approx_percentile_cont(expression, percentile, centroids) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). +- **centroids**: Number of centroids to use in the t-digest algorithm. _Default is 100_. + + If there are this number or fewer unique values, you can expect an exact result. + A higher number of centroids results in a more accurate approximation, but + requires more memory to compute. + +{{< expand-wrapper >}} +{{% expand "View `approx_percentile_cont` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + approx_percentile_cont(temp, 0.99) AS "99th_percentile" +FROM home +GROUP BY room +``` + +| room | 99th_percentile | +| :---------- | --------------: | +| Kitchen | 23.3 | +| Living Room | 22.8 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### approx_percentile_cont_with_weight + +Returns the weighted approximate percentile of input values using the +t-digest algorithm. + +```sql +approx_percentile_cont_with_weight(expression, weight, percentile) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **weight**: Expression to use as weight. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **percentile**: Percentile to compute. Must be a float value between 0 and 1 (inclusive). + +{{< expand-wrapper >}} +{{% expand "View `approx_percentile_cont_with_weight` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + approx_percentile_cont_with_weight(temp, co, 0.99) AS "co_weighted_99th_percentile" +FROM home +GROUP BY room +``` + +| room | co_weighted_99th_percentile | +| :---------- | --------------------------: | +| Kitchen | 23.3 | +| Living Room | 22.8 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/functions/conditional.md b/content/shared/sql-reference/functions/conditional.md new file mode 100644 index 000000000..e8abb272b --- /dev/null +++ b/content/shared/sql-reference/functions/conditional.md @@ -0,0 +1,132 @@ +The {{< product-name >}} SQL implementation supports the following conditional +functions for conditionally handling _null_ values: + +- [coalesce](#coalesce) +- [ifnull](#ifnull) +- [nullif](#nullif) +- [nvl](#nvl) + +## coalesce + +Returns the first of its arguments that is not _null_. +Returns _null_ if all arguments are _null_. +This function is often used to substitute a default value for _null_ values. + +```sql +coalesce(expression1[, ..., expression_n]) +``` + +##### Arguments + +- **expression1, expression_n**: + Expression to use if previous expressions are _null_. + Can be a constant, column, or function, and any combination of arithmetic operators. + Pass as many expression arguments as necessary. + +{{< expand-wrapper >}} +{{% expand "View `coalesce` query example" %}} + +```sql +SELECT + val1, + val2, + val3, + coalesce(val1, val2, val3, 'quz') AS coalesce +FROM + (values ('foo', 'bar', 'baz'), + (NULL, 'bar', 'baz'), + (NULL, NULL, 'baz'), + (NULL, NULL, NULL) + ) data(val1, val2, val3) +``` + +| val1 | val2 | val3 | coalesce | +| :--: | :--: | :--: | :------: | +| foo | bar | baz | foo | +| | bar | baz | bar | +| | | baz | baz | +| | | | quz | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ifnull + +_Alias of [nvl](#nvl)._ + +## nullif + +Returns _null_ if _expression1_ equals _expression2_; otherwise it returns _expression1_. +This can be used to perform the inverse operation of [`coalesce`](#coalesce). + +```sql +nullif(expression1, expression2) +``` + +##### Arguments + +- **expression1**: Expression to compare and return if equal to expression2. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression2**: Expression to compare to expression1. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `nullif` query example" %}} + +```sql +SELECT + value, + nullif(value, 'baz') AS nullif +FROM + (values ('foo'), + ('bar'), + ('baz') + ) data(value) +``` + +| value | nullif | +| :---- | :----- | +| foo | foo | +| bar | bar | +| baz | | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## nvl + +Returns _expression2_ if _expression1_ is _null_; otherwise it returns _expression1_. + +```sql +nvl(expression1, expression2) +``` + +##### Arguments + +- **expression1**: Return this expression if not _null_. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression2**: Return this expression if _expression1_ is _null_. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `nvl` query example" %}} + +```sql +SELECT + value, + nvl(value, 'baz') AS nvl +FROM + (values ('foo'), + ('bar'), + (NULL) + ) data(value) +``` + +| value | nvl | +| :---- | :-- | +| foo | foo | +| bar | bar | +| | baz | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/functions/math.md b/content/shared/sql-reference/functions/math.md new file mode 100644 index 000000000..9c1e93eff --- /dev/null +++ b/content/shared/sql-reference/functions/math.md @@ -0,0 +1,1270 @@ +The {{< product-name >}} SQL implementation supports the following math functions for +performing mathematic operations: + +- [abs](#abs) +- [acos](#acos) +- [acosh](#acosh) +- [asin](#asin) +- [asinh](#asinh) +- [atan](#atan) +- [atanh](#atanh) +- [atan2](#atan2) +- [cbrt](#cbrt) +- [ceil](#ceil) +- [cos](#cos) +- [cosh](#cosh) +- [degrees](#degrees) +- [exp](#exp) +- [factorial](#factorial) +- [floor](#floor) +- [gcd](#gcd) +- [isnan](#isnan) +- [iszero](#iszero) +- [lcm](#lcm) +- [ln](#ln) +- [log](#log) +- [log10](#log10) +- [log2](#log2) +- [nanvl](#nanvl) +- [pi](#pi) +- [power](#power) +- [pow](#pow) +- [radians](#radians) +- [random](#random) +- [round](#round) +- [signum](#signum) +- [sin](#sin) +- [sinh](#sinh) +- [sqrt](#sqrt) +- [tan](#tan) +- [tanh](#tanh) +- [trunc](#trunc) + +## abs + +Returns the absolute value of a number. + +```sql +abs(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `abs` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT abs(temp) AS abs FROM home LIMIT 3 +``` + +| abs | +| ---: | +| 21 | +| 23 | +| 22.7 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## acos + +Returns the arc cosine or inverse cosine of a number. + +```sql +acos(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `acos` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT acos(temp * .01) AS acos FROM home LIMIT 3 +``` + +| acos | +| -----------------: | +| 1.359221367036801 | +| 1.3387186439321834 | +| 1.3418001704498232 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## acosh + +Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. + +```sql +acosh(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `acosh` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT acosh(temp) AS acosh FROM home LIMIT 3 +``` + +| acosh | +| -----------------: | +| 3.737102242198924 | +| 3.8281684713331012 | +| 3.8150265878962055 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## asin + +Returns the arc sine or inverse sine of a number. + +```sql +asin(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `asin` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT asin(temp * .01) AS asin FROM home LIMIT 3 +``` + +| asin | +| ------------------: | +| 0.2115749597580956 | +| 0.23207768286271319 | +| 0.22899615634507337 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## asinh + +Returns the area hyperbolic sine or inverse hyperbolic sine of a number. + +```sql +asinh(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `asinh` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT asinh(temp) AS asinh FROM home LIMIT 3 +``` + +| asinh | +| -----------------: | +| 3.7382360302615427 | +| 3.8291136516208812 | +| 3.8159969160459988 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## atan + +Returns the arc tangent or inverse tangent of a number. + +```sql +atan(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `atan` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT atan(temp * .01) AS atan FROM home LIMIT 3 +``` + +| atan | +| ------------------: | +| 0.206992194219821 | +| 0.22606838799388393 | +| 0.22321725383717603 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## atanh + +Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. + +```sql +atanh(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `atanh` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT atanh(temp * .01) AS atanh FROM home LIMIT 3 +``` + +| atanh | +| ------------------: | +| 0.21317134656485978 | +| 0.2341894667593668 | +| 0.23102419806174476 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## atan2 + +Returns the arc tangent or inverse tangent of `expression_y / expression_x`. + +```sql +atan2(expression_y, expression_x) +``` + +##### Arguments + +- **expression_y**: First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `atan2` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT atan2(temp, hum) AS atan2 FROM home LIMIT 3 +``` + +| atan2 | +| -----------------: | +| 0.5292859396993504 | +| 0.5660139100632452 | +| 0.5613335864315844 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## cbrt + +Returns the cube root of a number. + +```sql +cbrt(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `cbrt` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT cbrt(temp) AS cbrt FROM home LIMIT 3 +``` + +| cbrt | +| -----------------: | +| 2.7589241763811208 | +| 2.843866979851566 | +| 2.831448188528187 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ceil + +Returns the nearest integer greater than or equal to a number. + +```sql +ceil(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `ceil` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT ceil(temp) AS ceil FROM home LIMIT 3 +``` + +| ceil | +| ---: | +| 21 | +| 23 | +| 23 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## cos + +Returns the cosine of a number. + +```sql +cos(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `cos` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT cos(temp) AS cos FROM home LIMIT 3 +``` + +| cos | +| ------------------: | +| -0.5477292602242684 | +| -0.5328330203333975 | +| -0.7591100556583898 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## cosh + +Returns the hyperbolic cosine of a number. + +```sql +cosh(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `cosh` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT cosh(temp) AS cosh FROM home LIMIT 3 +``` + +| cosh | +| -----------------: | +| 659407867.2416073 | +| 4872401723.124452 | +| 3609563974.9715896 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## degrees + +Converts radians to degrees. + +```sql +degrees(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `degrees` query example" %}} + +_The following example uses the +[Random numbers sample dataset](/influxdb/version/reference/sample-data/#random-numbers-sample-data)._ + +```sql +SELECT degrees(a) AS degrees FROM numbers LIMIT 3 +``` + +| degrees | +| ------------------: | +| 19.428488139031185 | +| -44.403317464348774 | +| -52.771542485064785 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## exp + +Returns the base-e exponential of a number. + +```sql +exp(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to use as the exponent. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `exp` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT exp(temp) AS exp FROM home LIMIT 3 +``` + +| exp | +| -----------------: | +| 1318815734.4832146 | +| 9744803446.248903 | +| 7219127949.943179 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## factorial + +Returns 1 if value is less than 2. + +```sql +factorial(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Must be an integer (`BIGINT`). + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `factorial` query example" %}} + +_The following example uses the +[Random numbers sample dataset](/influxdb/version/reference/sample-data/#random-numbers-sample-data)._ + +```sql +SELECT factorial((b + 2)::BIGINT) AS factorial FROM numbers LIMIT 3 +``` + +| factorial | +| --------: | +| 1 | +| 2 | +| 1 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## floor + +Returns the nearest integer less than or equal to a number. + +```sql +floor(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `floor` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT floor(temp) AS floor FROM home LIMIT 3 +``` + +| floor | +| ----: | +| 21 | +| 23 | +| 22 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## gcd + +Returns the greatest common divisor of `expression_x` and `expression_y`. +Returns `0` if both inputs are zero. + +```sql +gcd(expression_x, expression_y) +``` + +##### Arguments + +- **expression_x**: First numeric expression to operate on. + Must be an integer (`BIGINT`). + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Second numeric expression to operate on. + Must be an integer (`BIGINT`). + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `gcd` query example" %}} + +_The following example uses the +[Random numbers sample dataset](/influxdb/version/reference/sample-data/#random-numbers-sample-data)._ + +```sql +SELECT gcd((a * 5)::BIGINT, (b * 5)::BIGINT) AS gcd FROM numbers LIMIT 3 +``` + +| gcd | +| --------: | +| 1 | +| 3 | +| 2 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## isnan + +Returns `true` if a given number is ±NaN, otherwise returns `false`. + +```sql +isnan(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Must be a float (`DOUBLE`). + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `isnan` query example" %}} + +_The following example uses the +[Table value constructor](/influxdb/version/reference/sql/table-value-constructor/) +to simulate sample data._ + +```sql +SELECT isnan(a) +FROM + (VALUES (4.56), + ('NaN'::DOUBLE), + (16.2) + ) AS data(a) +``` + +| isnan | +| ----: | +| false | +| true | +| false | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## iszero + +Returns `true` if the given number is ±0.0, otherwise returns `false`. + +```sql +iszero(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `iszero` query example" %}} + +_The following example uses the +[Table value constructor](/influxdb/version/reference/sql/table-value-constructor/) +to simulate sample data._ + +```sql +SELECT iszero(a) +FROM + (VALUES (0), + (1), + (2) + ) AS data(a) +``` + +| iszero | +| -----: | +| true | +| false | +| false | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## lcm + +Returns the least common multiple of `expression_x` and `expression_y`. +Returns `0` if either input is zero. + +```sql +lcm(expression_x, expression_y) +``` + +##### Arguments + +- **expression_x**: First numeric expression to operate on. + Must be an integer (`BIGINT`). + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Second numeric expression to operate on. + Must be an integer (`BIGINT`). + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `lcm` query example" %}} + +_The following example uses the +[Random numbers sample dataset](/influxdb/version/reference/sample-data/#random-numbers-sample-data)._ + +```sql +SELECT lcm((a * 10)::BIGINT, (b * 10)::BIGINT) AS lcm FROM numbers LIMIT 3 +``` + +| lcm | +| --: | +| 3 | +| 7 | +| 36 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ln + +Returns the natural logarithm of a number. + +```sql +ln(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `ln` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT ln(temp) AS ln FROM home LIMIT 3 +``` + +| ln | +| -----------------: | +| 3.044522437723423 | +| 3.1354942159291497 | +| 3.122364924487357 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## log + +Returns the base-x logarithm of a number. + +``` +log([base, ]numeric_expression) +``` + +#### Arguments + +- **base**: Base numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + Default is `10`. +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `log` query example" %}} + +_The following example uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + temp, + log(2, temp) AS temp_log2, + log(4, temp) AS temp_log4, + log(temp) AS temp_log10 +FROM home +LIMIT 3 +``` + +| temp | temp_log2 | temp_log4 | temp_log10 | +| :--- | ----------------: | -----------------: | -----------------: | +| 21 | 4.392317422778761 | 2.1961587113893803 | 1.322219294733919 | +| 23 | 4.523561956057013 | 2.2617809780285065 | 1.3617278360175928 | +| 22.7 | 4.504620392403553 | 2.2523101962017766 | 1.3560258571931225 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## log10 + +Returns the base-10 logarithm of a number. + +```sql +log10(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `log10` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT log10(temp) AS log10 FROM home LIMIT 3 +``` + +| log10 | +| -----------------: | +| 1.3222192947339193 | +| 1.3617278360175928 | +| 1.3560258571931227 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## log2 + +Returns the base-2 logarithm of a number. + +```sql +log2(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `log2` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT log2(temp) AS log2 FROM home LIMIT 3 +``` + +| log2 | +| ----------------: | +| 4.392317422778761 | +| 4.523561956057013 | +| 4.504620392403552 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## nanvl + +Returns the first argument if it’s not `±NaN`. +Otherwise returns the second argument. + +```sql +nanvl(expression_x, expression_y) +``` + +##### Arguments + +- **expression_x**: Numeric expression to return if it’s not `NaN`. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Numeric expression to return if the first expression is `NaN`. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `nanvl` query example" %}} + +_The following example uses the +[Table value constructor](/influxdb/version/reference/sql/table-value-constructor/) +to simulate sample data._ + +```sql +SELECT nanvl(a, 0.0) AS nanvl +FROM + (VALUES (4.56), + ('NaN'::DOUBLE), + (16.2) + ) AS data(a) +``` + +| nanvl | +| ----: | +| 4.56 | +| 0 | +| 16.2 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## pi + +Returns an approximate value of π. + +```sql +pi() +``` + +{{< expand-wrapper >}} +{{% expand "View `pi` query example" %}} + +```sql +SELECT pi() AS pi +``` + +| pi | +| :---------------- | +| 3.141592653589793 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## power + +Returns a base expression raised to the power of an exponent. + +```sql +power(base, exponent) +``` + +##### Aliases + +- `pow` + +##### Arguments + +- **base**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **exponent**: Exponent numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `power` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT power(temp, hum * .1) AS power FROM home LIMIT 3 +``` + +| power | +| -----------------: | +| 55817.099910217476 | +| 85007.01501569824 | +| 78569.38332452129 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## `pow` + +_Alias of [power](#power)._ + +## radians + +Converts degrees to radians. + +```sql +radians(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `radians` query example" %}} + +_The following example uses the +[Random numbers sample dataset](/influxdb/version/reference/sample-data/#random-numbers-sample-data)._ + +```sql +SELECT radians(b) AS radians FROM numbers LIMIT 3 +``` + +| radians | +| --------------------: | +| -0.0028561101762876 | +| 0.0023917008411179744 | +| -0.008428949313343818 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## random + +Returns a random float value between 0 and 1. +The random seed is unique to each row. + +```sql +random() +``` + +{{< expand-wrapper >}} +{{% expand "View `random` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT temp * random() AS random FROM home LIMIT 3 +``` + +> [!Note] +> Due to the nature of the function, your results will not match the results below. + +| random | +| -----------------: | +| 0.5030770374815072 | +| 12.938847036567514 | +| 2.8204596545385385 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## round + +Rounds a number to the nearest integer. + +```sql +round(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `round` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT round(temp) AS round FROM home LIMIT 3 +``` + +| round | +| ----: | +| 21 | +| 23 | +| 23 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## signum + +Returns the sign of a number. +Negative numbers return `-1`. +Zero and positive numbers return `1`. + +```sql +signum(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `signum` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT signum(temp - 23) AS signum FROM home LIMIT 3 +``` + +| signum | +| -----: | +| -1 | +| 1 | +| -1 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## sin + +Returns the sine of a number. + +```sql +sin(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `sin` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT sin(temp) AS sin FROM home LIMIT 3 +``` + +| sin | +| ------------------: | +| 0.8366556385360561 | +| -0.8462204041751706 | +| -0.6509623056662469 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## sinh + +Returns the hyperbolic sine of a number. + +```sql +sinh(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `sinh ` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT sinh(temp) AS sinh FROM home LIMIT 3 +``` + +| sinh | +| -----------------: | +| 659407867.2416073 | +| 4872401723.124452 | +| 3609563974.9715896 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## sqrt + +Returns the square root of a number. + +```sql +sqrt(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `sqrt` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT sqrt(temp) AS sqrt FROM home LIMIT 3 +``` + +| sqrt | +| ----------------: | +| 4.58257569495584 | +| 4.795831523312719 | +| 4.764451699828638 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## tan + +Returns the tangent of a number. + +```sql +tan(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `tan` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT tan(temp) AS tan FROM home LIMIT 3 +``` + +| tan | +| ------------------: | +| -1.5274985276366035 | +| 1.5881530833912738 | +| 0.8575335036257101 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## tanh + +Returns the hyperbolic tangent of a number. + +```sql +tanh(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `tanh` query example" %}} + +_The following example uses the +[Random numbers sample dataset](/influxdb/version/reference/sample-data/#random-numbers-sample-data)._ + +```sql +SELECT tanh(a) AS tanh FROM numbers LIMIT 3 +``` + +| tanh | +| ------------------: | +| 0.32666571332086836 | +| -0.6498182711525403 | +| -0.7263877015335474 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## trunc + +Truncates a number toward zero (at the decimal point). + +```sql +trunc(numeric_expression) +``` + +##### Arguments + +- **numeric_expression**: Numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `trunc` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT trunc(temp) AS trunc FROM home LIMIT 3 +``` + +| trunc | +| ----: | +| 21 | +| 23 | +| 22 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/functions/misc.md b/content/shared/sql-reference/functions/misc.md new file mode 100644 index 000000000..309a27d7d --- /dev/null +++ b/content/shared/sql-reference/functions/misc.md @@ -0,0 +1,234 @@ +The {{< product-name >}} SQL implementation supports the following miscellaneous functions +for performing a variety of operations: + +- [arrow_cast](#arrow_cast) +- [arrow_typeof](#arrow_typeof) +- [interpolate](#interpolate) +- [locf](#locf) + + +## arrow_cast + +Casts a value to a specific Arrow data type. + +```sql +arrow_cast(expression, datatype) +``` + +#### Arguments + +- **expression**: Expression to cast. + Can be a constant, column, or function, and any combination of arithmetic or + string operators. +- **datatype**: [Arrow data type](/influxdb/version/reference/sql/data-types/#sql-and-arrow-data-types) + to cast to. + +{{< expand-wrapper >}} +{{% expand "View `arrow_cast` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + arrow_cast(time, 'Int64') AS time, + arrow_cast(temp, 'Utf8') AS temp, + arrow_cast(co, 'Float64')AS co +FROM home +LIMIT 1 +``` + +| time | temp | co | +| :------------------ | ---: | --: | +| 1641024000000000000 | 21.0 | 0 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## arrow_typeof + +Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) +of the expression: + +```sql +arrow_typeof(expression) +``` + +##### Arguments + +- **expression**: Expression to evaluate. + Can be a constant, column, or function, and any combination of arithmetic or + string operators. + +{{< expand-wrapper >}} +{{% expand "View `arrow_typeof` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + arrow_typeof(time) AS time, + arrow_typeof(room) AS room, + arrow_typeof(temp) AS temp, + arrow_typeof(co) AS co +FROM home +LIMIT 1 +``` + +| time | room | temp | co | +| :-------------------------- | :---------------------- | :------ | :---- | +| Timestamp(Nanosecond, None) | Dictionary(Int32, Utf8) | Float64 | Int64 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## interpolate + +Fills null values in a specified aggregated column by interpolating values +from existing values. +Must be used with [`date_bin_gapfill`](/influxdb/version/reference/sql/functions/time-and-date/#date_bin_gapfill). + +```sql +interpolate(aggregate_expression) +``` + +##### Arguments + +- **aggregate_expression**: Aggregate operation on a specified expression. + The operation can use any [aggregate function](/influxdb/version/reference/sql/functions/aggregate/). + The expression can be a constant, column, or function, and any combination of + arithmetic operators supported by the aggregate function. + +##### Related functions + +[date_bin_gapfill](/influxdb/version/reference/sql/functions/time-and-date/#date_bin_gapfill), +[locf](#locf) + +{{< expand-wrapper >}} +{{% expand "View `interpolate` query example" %}} + +_The following example uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as _time, + room, + interpolate(avg(temp)) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY _time, room +``` + +| _time | room | AVG(home.temp) | +| :------------------- | :---------- | -------------: | +| 2022-01-01T08:00:00Z | Kitchen | 21 | +| 2022-01-01T08:30:00Z | Kitchen | 22 | +| 2022-01-01T09:00:00Z | Kitchen | 23 | +| 2022-01-01T09:30:00Z | Kitchen | 22.85 | +| 2022-01-01T10:00:00Z | Kitchen | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 21.1 | +| 2022-01-01T08:30:00Z | Living Room | 21.25 | +| 2022-01-01T09:00:00Z | Living Room | 21.4 | +| 2022-01-01T09:30:00Z | Living Room | 21.6 | +| 2022-01-01T10:00:00Z | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## locf + +Fills null values in a specified aggregated column by carrying the last observed +value forward. +Must be used with [`date_bin_gapfill`](/influxdb/version/reference/sql/functions/time-and-date/#date_bin_gapfill). + +_LOCF is an initialism of "last observation carried forward."_ + +```sql +locf(aggregate_expression) +``` + +##### Arguments + +- **aggregate_expression**: Aggregate operation on a specified expression. + The operation can use any [aggregate function](/influxdb/version/reference/sql/functions/aggregate/). + The expression can be a constant, column, or function, and any combination of + arithmetic operators supported by the aggregate function. + +##### Related functions + +[date_bin_gapfill](/influxdb/version/reference/sql/functions/time-and-date/#date_bin_gapfill), +[interpolate](#interpolate) + +{{< expand-wrapper >}} +{{% expand "View `locf` query example" %}} + +_The following example uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as _time, + room, + locf(avg(temp)) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY _time, room +``` + +| _time | room | AVG(home.temp) | +| :------------------- | :---------- | -------------: | +| 2022-01-01T08:00:00Z | Kitchen | 21 | +| 2022-01-01T08:30:00Z | Kitchen | 21 | +| 2022-01-01T09:00:00Z | Kitchen | 23 | +| 2022-01-01T09:30:00Z | Kitchen | 23 | +| 2022-01-01T10:00:00Z | Kitchen | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 21.1 | +| 2022-01-01T08:30:00Z | Living Room | 21.1 | +| 2022-01-01T09:00:00Z | Living Room | 21.4 | +| 2022-01-01T09:30:00Z | Living Room | 21.4 | +| 2022-01-01T10:00:00Z | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + + diff --git a/content/shared/sql-reference/functions/regular-expression.md b/content/shared/sql-reference/functions/regular-expression.md new file mode 100644 index 000000000..861b23233 --- /dev/null +++ b/content/shared/sql-reference/functions/regular-expression.md @@ -0,0 +1,139 @@ +The {{< product-name >}} SQL implementation uses the +[PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions) +regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax) +(excluding some features such as look-around and back-references) and supports +the following regular expression functions: + +- [regexp_like](#regexp_like) +- [regexp_match](#regexp_match) +- [regexp_replace](#regexp_replace) + +## regexp_like + +True if a regular expression has at least one match in a string; +false otherwise. + +```sql +regexp_like(str, regexp[, flags]) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **regexp**: Regular expression to test against the string expression. + Can be a constant, column, or function. +- **flags**: Optional regular expression flags that control the behavior of the + regular expression. The following flags are supported: + - **i**: (insensitive) Ignore case when matching. + - **m**: (multi-line) `^` and `$` match the beginning and end of a line, respectively. + - **s**: (single-line) `.` matches newline (`\n`). + - **R**: (CRLF) When multi-line mode is enabled, `\r\n` is used to delimit lines. + - **U**: (ungreedy) Swap the meaning of `x*` and `x*?`. + +{{< expand-wrapper >}} +{{% expand "View `regexp_like` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + regexp_like(room::STRING, 'R', 'i') AS regexp_like +FROM home +``` + +| room | regexp_like | +| :---------- | :---------- | +| Kitchen | false | +| Living Room | true | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## regexp_match + +Returns a list of regular expression matches in a string. + +```sql +regexp_match(str, regexp, flags) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **regexp**: Regular expression to match against. + Can be a constant, column, or function. +- **flags**: Regular expression flags that control the behavior of the + regular expression. The following flags are supported. + - **i**: (insensitive) Ignore case when matching. + +{{< expand-wrapper >}} +{{% expand "View `regexp_match` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +> [!Note] +> `regexp_match` returns a _list_ Arrow type, which is not supported by InfluxDB. +> Use _bracket notation_ to reference a value in the list. +> Lists use 1-based indexing. + +```sql +SELECT DISTINCT + room, + regexp_match(room::STRING, '.{3}')[1] AS regexp_match +FROM home +``` + +| room | regexp_match | +| :---------- | :----------- | +| Kitchen | Kit | +| Living Room | Liv | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## regexp_replace + +Replaces substrings in a string that match a regular expression. + +```sql +regexp_replace(str, regexp, replacement, flags) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **regexp**: Regular expression to match against. + Can be a constant, column, or function. +- **replacement**: Replacement string expression. + Can be a constant, column, or function, and any combination of string operators. +- **flags**: Regular expression flags that control the behavior of the + regular expression. The following flags are supported. + - **g**: (global) Search globally and don't return after the first match. + - **i**: (insensitive) Ignore case when matching. + +{{< expand-wrapper >}} +{{% expand "View `regexp_replace` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + regexp_replace(room::STRING, '\sRoom', '', 'gi') AS regexp_replace +FROM home +``` + +| room | regexp_replace | +| :---------- | :------------- | +| Kitchen | Kitchen | +| Living Room | Living | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/functions/selector.md b/content/shared/sql-reference/functions/selector.md new file mode 100644 index 000000000..228ae57aa --- /dev/null +++ b/content/shared/sql-reference/functions/selector.md @@ -0,0 +1,186 @@ +SQL selector functions are designed to work with time series data. +They behave similarly to aggregate functions in that they take a collection of +data and return a single value. +However, selectors are unique in that they return a _struct_ that contains +a **time value** in addition to the computed value. + +- [How do selector functions work?](#how-do-selector-functions-work) +- [Selector functions](#selector-functions) + - [selector_min](#selector_min) + - [selector_max](#selector_max) + - [selector_first](#selector_first) + - [selector_last](#selector_last) + +## How do selector functions work? + +Each selector function returns an [Arrow _struct_](https://arrow.apache.org/docs/format/Columnar.html#struct-layout) +(similar to a JSON object) representing a single time and value from the +specified column in the each group. +What time and value get returned depend on the logic in the selector function. +For example, `selector_first` returns the value of specified column in the first row of the group. +`selector_max` returns the maximum value of the specified column in the group. + +### Selector struct schema + +The struct returned from a selector function has two properties: + +- **time**: `time` value in the selected row +- **value**: value of the specified column in the selected row + +```js +{time: 2023-01-01T00:00:00Z, value: 72.1} +``` + +### Selector functions in use + +In your `SELECT` statement, execute a selector function and use bracket notation +to reference properties of the [returned struct](#selector-struct-schema) to +populate the column value: + +```sql +SELECT + selector_first(temp, time)['time'] AS time, + selector_first(temp, time)['value'] AS temp, + room +FROM home +GROUP BY room +``` + +## Selector functions + +- [selector_min](#selector_min) +- [selector_max](#selector_max) +- [selector_first](#selector_first) +- [selector_last](#selector_last) + +### selector_min + +Returns the smallest value of a selected column and a timestamp. + +```sql +selector_min(expression, timestamp) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of string or + arithmetic operators. +- **timestamp**: Time expression. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `selector_min` query example" %}} + +```sql +SELECT + selector_min(water_level, time)['time'] AS time, + selector_min(water_level, time)['value'] AS water_level +FROM h2o_feet +``` + +| time | water_level | +| :------------------- | ----------: | +| 2019-08-28T14:30:00Z | -0.61 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### selector_max + +Returns the largest value of a selected column and a timestamp. + +```sql +selector_max(expression, timestamp) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of string or + arithmetic operators. +- **timestamp**: Time expression. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `selector_max` query example" %}} + +```sql +SELECT + selector_max(water_level, time)['time'] AS time, + selector_max(water_level, time)['value'] AS water_level +FROM h2o_feet +``` + +| time | water_level | +| :------------------- | ----------: | +| 2019-08-28T07:24:00Z | 9.964 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### selector_first + +Returns the first value ordered by time ascending. + +```sql +selector_first(expression, timestamp) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of string or + arithmetic operators. +- **timestamp**: Time expression. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `selector_first` query example" %}} + +```sql +SELECT + selector_first(water_level, time)['time'] AS time, + selector_first(water_level, time)['value'] AS water_level +FROM h2o_feet +``` + +| time | water_level | +| :------------------- | ----------: | +| 2019-08-28T07:24:00Z | 9.964 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### selector_last + +Returns the last value ordered by time ascending. + +```sql +selector_last(expression, timestamp) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of string or + arithmetic operators. +- **timestamp**: Time expression. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `selector_last` query example" %}} + +```sql +SELECT + selector_last(water_level, time)['time'] AS time, + selector_last(water_level, time)['value'] AS water_level +FROM h2o_feet +``` + +| time | water_level | +| :------------------- | ----------: | +| 2019-09-17T21:42:00Z | 4.938 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/functions/string.md b/content/shared/sql-reference/functions/string.md new file mode 100644 index 000000000..3011eb836 --- /dev/null +++ b/content/shared/sql-reference/functions/string.md @@ -0,0 +1,1488 @@ +The {{< product-name >}} SQL implementation supports the following string functions for +operating on string values: + +- [ascii](#ascii) +- [bit_length](#bit_length) +- [btrim](#btrim) +- [char_length](#char_length) +- [character_length](#character_length) +- [concat](#concat) +- [concat_ws](#concat_ws) +- [chr](#chr) +- [ends_with](#ends_with) +- [find_in_set](#find_in_set) +- [initcap](#initcap) +- [instr](#instr) +- [left](#left) +- [length](#length) +- [levenshtein](#levenshtein) +- [lower](#lower) +- [lpad](#lpad) +- [ltrim](#ltrim) +- [md5](#md5) +- [octet_length](#octet_length) +- [overlay](#overlay) +- [position](#position) +- [repeat](#repeat) +- [replace](#replace) +- [reverse](#reverse) +- [right](#right) +- [rpad](#rpad) +- [rtrim](#rtrim) +- [split_part](#split_part) +- [starts_with](#starts_with) +- [strpos](#strpos) +- [substr](#substr) +- [substr_index](#substr_index) +- [to_hex](#to_hex) +- [translate](#translate) +- [trim](#trim) +- [upper](#upper) +- [uuid](#uuid) + +## ascii + +Returns the ASCII value of the first character in a string. + +> [!Note] +> `ascii` returns a 32-bit integer. +> To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/version/query-data/sql/cast-types/#cast-to-an-integer). + +```sql +ascii(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[chr](#chr) + +{{< expand-wrapper >}} +{{% expand "View `ascii` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + ascii(room)::BIGINT AS ascii +FROM home +``` + +| room | ascii | +| :---------- | ----: | +| Kitchen | 75 | +| Living Room | 76 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## bit_length + +Returns the bit length of a string. + +> [!Note] +> `bit_length` returns a 32-bit integer. +> To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/version/query-data/sql/cast-types/#cast-to-an-integer). + +```sql +bit_length(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[length](#length), [octet_length](#octet_length) + +{{< expand-wrapper >}} +{{% expand "View `bit_length` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + bit_length(room)::BIGINT AS bit_length +FROM home +``` + +| room | bit_length | +| :---------- | ---------: | +| Living Room | 88 | +| Kitchen | 56 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## btrim + +Trims the specified trim string from the start and end of a string. +If no trim string is provided, all whitespace is removed from the start and end +of the input string. + +```sql +btrim(str[, trim_str]) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **trim_str**: String expression to trim from the beginning and end of the input string. + Can be a constant, column, or function, and any combination of arithmetic operators. + _Default is whitespace characters_. + +##### Related functions + +[ltrim](#ltrim), +[rtrim](#rtrim), +[trim](#trim) + +{{< expand-wrapper >}} +{{% expand "View `btrim` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + btrim(room::STRING, ' Room') AS btrim +FROM home +``` + +| room | btrim | +| :---------- | :------ | +| Living Room | Living | +| Kitchen | Kitchen | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## char_length + +_Alias of [length](#length)._ + +## character_length + +_Alias of [length](#length)._ + +## concat + +Concatenates multiple strings together. + +```sql +concat(str[, ..., str_n]) +``` + +##### Arguments + +- **str**: String expression to concatenate. + Can be a constant, column, or function, and any combination of string operators. +- **str_n**: Subsequent string expression to concatenate. + +##### Related functions + +[contcat_ws](#contcat_ws) + +{{< expand-wrapper >}} +{{% expand "View `concat` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + concat('At ', time::STRING, ', the ', room, ' was ', temp::STRING, '°C.') AS concat +FROM home +LIMIT 3 +``` + +{{% influxdb/custom-timestamps %}} + +| concat | +| :---------------------------------------------- | +| At 2022-01-01T08:00:00, the Kitchen was 21.0°C. | +| At 2022-01-01T09:00:00, the Kitchen was 23.0°C. | +| At 2022-01-01T10:00:00, the Kitchen was 22.7°C. | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## concat_ws + +Concatenates multiple strings together with a specified separator. + +```sql +concat_ws(separator, str[, ..., str_n]) +``` + +##### Arguments + +- **separator**: Separator to insert between concatenated strings. +- **str**: String expression to concatenate. + Can be a constant, column, or function, and any combination of string operators. +- **str_n**: Subsequent string expression to concatenate. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[concat](#concat) + +{{< expand-wrapper >}} +{{% expand "View `concat_ws` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + concat_ws(' -- ', time::STRING, room, temp::STRING) AS concat_ws +FROM home +LIMIT 3 +``` + +{{% influxdb/custom-timestamps %}} + +| concat_ws | +| :----------------------------------------- | +| 2022-01-01T08:00:00 \-\- Kitchen \-\- 21.0 | +| 2022-01-01T09:00:00 \-\- Kitchen \-\- 23.0 | +| 2022-01-01T10:00:00 \-\- Kitchen \-\- 22.7 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## chr + +Returns the character with the specified ASCII or Unicode code value. + +``` +chr(expression) +``` + +#### Arguments + +- **expression**: Expression containing the ASCII or Unicode code value to operate on. + Can be a constant, column, or function, and any combination of arithmetic or + string operators. + +##### Related functions + +[ascii](#ascii) + +{{< expand-wrapper >}} +{{% expand "View `chr` query example" %}} + +```sql +SELECT + ascii, + chr(ascii) AS chr +FROM + (values (112), + (75), + (214) + ) data(ascii) +``` + +| ascii | chr | +| :---- | :-: | +| 112 | p | +| 75 | K | +| 214 | Ö | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ends_with + +Tests if a string ends with a substring. + +```sql +ends_with(str, substr) +``` + +##### Arguments + +- **str**: String expression to test. + Can be a constant, column, or function, and any combination of string operators. +- **substr**: Substring to test for. + +{{< expand-wrapper >}} +{{% expand "View `ends_with` query example" %}} + +```sql +SELECT + string, + ends_with(string, 'USA') AS ends_with +FROM + (values ('New York, USA'), + ('London, UK'), + ('San Francisco, USA') + ) data(string) +``` + +| string | ends_with | +| :----------------- | :-------- | +| New York, USA | true | +| London, UK | false | +| San Francisco, USA | true | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## find_in_set + +Returns the position of a string in a comma-delimited list of substrings. +Returns 0 if the string is not in the list of substrings. + +```sql +find_in_set(str, strlist) +``` + +##### Arguments + +- **str**: String expression to find in `strlist`. +- **strlist**: A string containing a comma-delimited list of substrings. + +{{< expand-wrapper >}} +{{% expand "View `find_in_set` query example" %}} + +```sql +SELECT + string, + find_in_set(string, 'Isaac,John,Sara') AS find_in_set +FROM + (values ('John'), + ('Sarah'), + ('Isaac') + ) data(string) +``` + +| string | find_in_set | +| :----- | ----------: | +| John | 2 | +| Sarah | 0 | +| Isaac | 1 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## initcap + +Capitalizes the first character in each word in the input string. +Words are delimited by non-alphanumeric characters. + +```sql +initcap(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[lower](#lower), +[upper](#upper) + +{{< expand-wrapper >}} +{{% expand "View `initcap` query example" %}} + +```sql +SELECT + string, + initcap(string) AS initcap +FROM + (values ('hello world'), + ('hello-world'), + ('hello_world') + ) data(string) +``` + +| string | initcap | +| :---------- | :---------- | +| hello world | Hello World | +| hello-world | Hello-World | +| hello_world | Hello_World | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## instr + +Returns the location where a substring first appears in a string (starting at 1). +If the substring is not in the string, the function returns 0. + +```sql +instr(str, substr) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **substr**: Substring expression to search for. + Can be a constant, column, or function, and any combination of string operators. + +{{< expand-wrapper >}} +{{% expand "View `instr` query example" %}} + +```sql +SELECT + string, + instr(string, 'neighbor') AS instr +FROM + (values ('good neighbor'), + ('bad neighbor'), + ('next-door neighbor'), + ('friend') + ) data(string) +``` + +| string | instr | +| :----------------- | ----: | +| good neighbor | 6 | +| bad neighbor | 5 | +| next-door neighbor | 11 | +| friend | 0 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## left + +Returns a specified number of characters from the left side of a string. + +```sql +left(str, n) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **n**: Number of characters to return. + +##### Related functions + +[right](#right) + +{{< expand-wrapper >}} +{{% expand "View `left` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + left(room::STRING, 3) AS left +FROM home +``` + +| room | left | +| :---------- | :--- | +| Kitchen | Kit | +| Living Room | Liv | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## length + +Returns the number of characters in a string. + +> [!Note] +> `char_length` returns a 32-bit integer. +> To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/version/query-data/sql/cast-types/#cast-to-an-integer). + +```sql +length(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Aliases + +- char\_length +- character\_length + +##### Related functions + +[bit_length](#bit_length), +[octet_length](#octet_length) + +{{< expand-wrapper >}} +{{% expand "View `length` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + length(room)::BIGINT AS length +FROM home +``` + +| room | length | +| :---------- | -----: | +| Kitchen | 7 | +| Living Room | 11 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## levenshtein + +Returns the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) +between two strings. + +```sql +levenshtein(str1, str2) +``` + +##### Arguments +- **str1**: First string expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **str2**: Second string expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +{{< expand-wrapper >}} +{{% expand "View `levenshtein` query example" %}} + +```sql +SELECT + string1, + string2, + levenshtein(string1, string2) AS levenshtein +FROM + (values ('kitten', 'sitting'), + ('puppy', 'jumping'), + ('cow', 'lowing') + ) data(string1, string2) +``` + +| string1 | string2 | levenshtein | +| :------ | :------ | ----------: | +| kitten | sitting | 3 | +| puppy | jumping | 5 | +| cow | lowing | 4 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## lower + +Converts a string to lower-case. + +```sql +lower(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[initcap](#initcap), +[upper](#upper) + +{{< expand-wrapper >}} +{{% expand "View `lower` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + lower(room::STRING) AS lower +FROM home +``` + +| room | lower | +| :---------- | :---------- | +| Kitchen | kitchen | +| Living Room | living room | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## lpad + +Pads the left side of a string with another string to a specified string length. + +```sql +lpad(str, n[, padding_str]) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **n**: String length to pad to. +- **padding_str**: String expression to pad with. + Can be a constant, column, or function, and any combination of string operators. + _Default is a space._ + +##### Related functions + +[rpad](#rpad) + +{{< expand-wrapper >}} +{{% expand "View `lpad` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + lpad(room::STRING, 14, '-') AS lpad +FROM home +``` + +| room | lpad | +| :---------- | :-------------------- | +| Kitchen | \-\-\-\-\-\-\-Kitchen | +| Living Room | \-\-\-Living Room | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## ltrim + +Removes leading spaces from a string. + +```sql +ltrim(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[btrim](#btrim), +[rtrim](#rtrim), +[trim](#trim) + +{{< expand-wrapper >}} +{{% expand "View `ltrim` query example" %}} + +```sql +SELECT + string, + ltrim(string) AS ltrim +FROM + (values (' Leading spaces'), + ('Trailing spaces '), + (' Leading and trailing spaces ') + ) data(string) +``` + +| string | ltrim | +| :-------------------------------------- | :-------------------------------------- | +|   Leading spaces | Leading spaces | +| Trailing spaces   | Trailing spaces   | +| Leading and trailing spaces   | Leading and trailing spaces   | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## md5 + +Computes an MD5 128-bit checksum for a string expression. + +```sql +md5(str) +``` + +##### Arguments + +- **expression**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +{{< expand-wrapper >}} +{{% expand "View `md5` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + md5(room) AS md5 +FROM home +``` + +| room | md5 | +| :---------- | :------------------------------- | +| Kitchen | 33fa00a66f2edf0d1c5697a9f8693ba8 | +| Living Room | f45b0e6aec165544faccaf2cad820542 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## octet_length + +Returns the length of a string in bytes. + +> [!Note] +> `length` returns a 32-bit integer. +> To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/version/query-data/sql/cast-types/#cast-to-an-integer). + +```sql +octet_length(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[bit_length](#bit_length), +[length](#length) + +{{< expand-wrapper >}} +{{% expand "View `octet_length` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + octet_length(room)::BIGINT AS octet_length +FROM home +``` + +| room | octet_length | +| :---------- | -----------: | +| Living Room | 11 | +| Kitchen | 7 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## overlay + +Replaces part of a string with another substring using a specified starting +position and number of characters to replace. + +```sql +overlay(str PLACING substr FROM pos [FOR count]) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **substr**: Substring to use to replace part of the specified string (`str`). + Can be a constant, column, or function, and any combination of string operators. +- **pos**: Start position of the substring replacement (`substr`). +- **count**: Number of characters in the string (`str`) to replace with the + substring (`substr`) beginning from the start position (`pos`). + If not specified, the function uses the length of the substring. + +{{< expand-wrapper >}} +{{% expand "View `overlay` query example" %}} + +```sql +SELECT + string, + overlay(string PLACING '****' FROM 1 FOR 12) AS overlay +FROM + (values ('2223000048410010'), + ('2222420000001113'), + ('4917484589897107') + ) data(string) +``` + +| string | overlay | +| :--------------- | :------- | +| 2223000048410010 | ****0010 | +| 2222420000001113 | ****1113 | +| 4917484589897107 | ****7107 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## position + +Returns the position of a substring in a string. + +```sql +position(substr IN str) +``` + +##### Arguments + +- **substr**: Substring expression to search for. + Can be a constant, column, or function, and any combination of string operators. +- **str**: String expression to search. + Can be a constant, column, or function, and any combination of string operators. + +{{< expand-wrapper >}} +{{% expand "View `position` query example" %}} + +```sql +SELECT + string, + position('oo' IN string) AS position +FROM + (values ('cool'), + ('scoop'), + ('ice cream') + ) data(string) +``` + +| string | position | +| :-------- | -------: | +| cool | 2 | +| scoop | 3 | +| ice cream | 0 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## repeat + +Returns a string with an input string repeated a specified number of times. + +```sql +repeat(str, n) +``` + +##### Arguments + +- **str**: String expression to repeat. + Can be a constant, column, or function, and any combination of string operators. +- **n**: Number of times to repeat the input string. + +{{< expand-wrapper >}} +{{% expand "View `repeat` query example" %}} + +```sql +SELECT + string, + repeat(string, 3) AS repeat +FROM + (values ('foo '), + ('bar '), + ('baz ') + ) data(string) +``` + +| string | repeat | +| :-------- | :---------- | +| foo  | foo foo foo | +| bar  | bar bar bar | +| baz  | baz baz baz | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## replace + +Replaces all occurrences of a specified substring in a string with a new substring. + +```sql +replace(str, substr, replacement) +``` + +##### Arguments + +- **str**: String expression to repeat. + Can be a constant, column, or function, and any combination of string operators. +- **substr**: Substring expression to replace in the input string. + Can be a constant, column, or function, and any combination of string operators. +- **replacement**: Replacement substring expression. + Can be a constant, column, or function, and any combination of string operators. + +{{< expand-wrapper >}} +{{% expand "View `replace` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + replace(room::STRING, ' ', '_') AS replace +FROM home +``` + +| room | replace | +| :---------- | :---------- | +| Kitchen | Kitchen | +| Living Room | Living_Room | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## reverse + +Reverses the character order of a string. + +```sql +reverse(str) +``` + +##### Arguments + +- **str**: String expression to repeat. + Can be a constant, column, or function, and any combination of string operators. + +{{< expand-wrapper >}} +{{% expand "View `reverse` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + reverse(room::STRING) AS reverse +FROM home +``` + +| room | reverse | +| :---------- | :---------- | +| Kitchen | nehctiK | +| Living Room | mooR gniviL | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## right + +Returns a specified number of characters from the right side of a string. + +```sql +right(str, n) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **n**: Number of characters to return. + +##### Related functions + +[left](#left) + +{{< expand-wrapper >}} +{{% expand "View `right` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + right(room::STRING, 3) AS right +FROM home +``` + +| room | right | +| :---------- | :---- | +| Living Room | oom | +| Kitchen | hen | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## rpad + +Pads the right side of a string with another string to a specified string length. + +```sql +rpad(str, n[, padding_str]) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **n**: String length to pad to. +- **padding_str**: String expression to pad with. + Can be a constant, column, or function, and any combination of string operators. + _Default is a space._ + +##### Related functions + +[lpad](#lpad) + +{{< expand-wrapper >}} +{{% expand "View `rpad` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + rpad(room::STRING, 14, '-') AS rpad +FROM home +``` + +| room | rpad | +| :---------- | :-------------------- | +| Kitchen | Kitchen\-\-\-\-\-\-\- | +| Living Room | Living Room\-\-\- | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## rtrim + +Removes trailing spaces from a string. + +```sql +rtrim(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[btrim](#btrim), +[ltrim](#ltrim), +[trim](#trim) + +{{< expand-wrapper >}} +{{% expand "View `rtrim` query example" %}} + +```sql +SELECT + string, + rtrim(string) AS rtrim +FROM + (values (' Leading spaces'), + ('Trailing spaces '), + (' Leading and trailing spaces ') + ) data(string) +``` + +| string | rtrim | +| :-------------------------------------- | :-------------------------------------- | +|   Leading spaces |   Leading spaces | +| Trailing spaces   | Trailing spaces | +| Leading and trailing spaces   |   Leading and trailing spaces | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## split_part + +Splits a string based on a specified delimiter and returns the substring in the +specified position. + +```sql +split_part(str, delimiter, pos) +``` + +##### Arguments + +- **str**: String expression to spit. + Can be a constant, column, or function, and any combination of string operators. +- **delimiter**: String or character to split on. +- **pos**: Position of the part to return. + +{{< expand-wrapper >}} +{{% expand "View `split_part` query example" %}} + +```sql +SELECT + url, + split_part(url, '.', 1) AS split_part +FROM + (values ('www.influxdata.com'), + ('docs.influxdata.com'), + ('community.influxdata.com') + ) data(url) +``` + +| url | split_part | +| :----------------------- | :--------- | +| www.influxdata.com | www | +| docs.influxdata.com | docs | +| community.influxdata.com | community | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## starts_with + +Tests if a string starts with a substring. + +```sql +starts_with(str, substr) +``` + +##### Arguments + +- **str**: String expression to test. + Can be a constant, column, or function, and any combination of string operators. +- **substr**: Substring to test for. + +{{< expand-wrapper >}} +{{% expand "View `starts_with` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + starts_with(room::STRING, 'Kit') AS starts_with +FROM home +``` + +| room | starts_with | +| :---------- | :---------- | +| Kitchen | true | +| Living Room | false | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## strpos + +Returns the starting position of a specified substring in a string. +Positions begin at 1. +If the substring does not exist in the string, the function returns 0. + +> [!Note] +> `strpos` returns a 32-bit integer. +> To use with InfluxDB, [cast the return value to 64-bit integer](/influxdb/version/query-data/sql/cast-types/#cast-to-an-integer). + +```sql +strpos(str, substr) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **substr**: Substring expression to search for. + Can be a constant, column, or function, and any combination of string operators. + +{{< expand-wrapper >}} +{{% expand "View `strpos` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + strpos(room::STRING, 'Room')::BIGINT AS strpos +FROM home +``` + +| room | strpos | +| :---------- | -----: | +| Kitchen | 0 | +| Living Room | 8 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## substr + +Extracts a substring of a specified number of characters from a specific +starting position in a string. + +```sql +substr(str, start_pos[, length]) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **start_pos**: Character position to start the substring at. + The first character in the string has a position of 1. +- **length**: Number of characters to extract. + If not specified, returns the rest of the string after the start position. + +{{< expand-wrapper >}} +{{% expand "View `substr` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + substr(room::STRING, 3, 5) AS substr +FROM home +``` + +| room | substr | +| :---------- | :--------- | +| Living Room | ving  | +| Kitchen | tchen | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## substr_index + +Returns the substring that occurs before or after the specified number (`count`) +of delimiter (`delimiter`) occurrences in a string (`str`). +If the count is positive, the function returns everything to the left of the +final delimiter (counting from the left). +If the count is negative, the function returns everything to the right of the +final delimiter (counting from the right). + +```sql +substr_index(str, delimiter, count) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **delimiter**: String expression to use to delimit substrings in the string (`str`). + Can be a constant, column, or function, and any combination of string operators. +- **count**: The Nth occurrence of the delimiter (`delimiter`) to split on. + Can be a constant, column, or function, and any combination of arithmetic operators. + Supports positive and negative numbers. + +{{< expand-wrapper >}} +{{% expand "View `substr_index` query example" %}} + +```sql +SELECT + url, + substr_index(url, '.', 1) AS subdomain, + substr_index(url, '.', -1) AS tld +FROM + (values ('docs.influxdata.com'), + ('community.influxdata.com'), + ('cloud2.influxdata.com') + ) data(url) +``` + +| url | subdomain | tld | +| :----------------------- | :-------- | :-- | +| docs.influxdata.com | docs | com | +| community.influxdata.com | community | com | +| arrow.apache.org | arrow | org | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## translate + +Translates characters in a string to specified translation characters. + +```sql +translate(str, chars, translation) +``` + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. +- **chars**: Characters to translate. +- **translation**: Translation characters. Translation characters replace only + characters at the same position in the **chars** string. + +{{< expand-wrapper >}} +{{% expand "View `translate` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + translate(room::STRING, 'Rom', 'sOn') AS translate +FROM home +``` + +| room | translate | +| :---------- | :---------- | +| Living Room | Living sOOn | +| Kitchen | Kitchen | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_hex + +Converts an integer to a hexadecimal string. + +```sql +to_hex(int) +``` + +##### Arguments + +- **int**: Integer expression to convert. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `to_hex` query example" %}} + +```sql +SELECT + int, + to_hex(int) AS to_hex +FROM + (values (123), + (345), + (678) + ) data(int) +``` + +| int | to_hex | +| :-- | -----: | +| 123 | 7b | +| 345 | 159 | +| 678 | 2a6 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## trim + +Removes leading and trailing spaces from a string. + +```sql +trim(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[btrim](#btrim), +[ltrim](#ltrim), +[rtrim](#rtrim) + +{{< expand-wrapper >}} +{{% expand "View `trim` query example" %}} + +```sql +SELECT + string, + trim(string) AS trim +FROM + (values (' Leading spaces'), + ('Trailing spaces '), + (' Leading and trailing spaces ') + ) data(string) +``` + +| string | trim | +| :-------------------------------------- | :-------------------------- | +|   Leading spaces | Leading spaces | +| Trailing spaces   | Trailing spaces | +| Leading and trailing spaces   | Leading and trailing spaces | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## upper + +Converts a string to upper-case. + +```sql +upper(str) +``` + +##### Arguments + +- **str**: String expression to operate on. + Can be a constant, column, or function, and any combination of string operators. + +##### Related functions + +[initcap](#initcap), +[lower](#lower) + +{{< expand-wrapper >}} +{{% expand "View `upper` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT DISTINCT + room, + upper(room::STRING) AS upper +FROM home +``` + +| room | upper | +| :---------- | :---------- | +| Living Room | LIVING ROOM | +| Kitchen | KITCHEN | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## uuid + +Returns a UUID v4 string value that is unique per row. + +```sql +uuid() +``` + +{{< expand-wrapper >}} +{{% expand "View `uuid` query example" %}} + +_The following example uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + room, + uuid() AS uuid +FROM (SELECT DISTINCT room FROM home) +``` + +| room | uuid | +| :---------- | :----------------------------------: | +| Kitchen | f0b41da9-e334-4b7d-b925-a54ca6b082f3 | +| Living Room | c31be90e-c4ed-4304-b633-47b969ef3ab6 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/functions/time-and-date.md b/content/shared/sql-reference/functions/time-and-date.md new file mode 100644 index 000000000..d7fedd40d --- /dev/null +++ b/content/shared/sql-reference/functions/time-and-date.md @@ -0,0 +1,1487 @@ +The {{< product-name >}} SQL implementation supports time and date functions +that are useful when working with time series data. + +- [current_date](#current_date) +- [current_time](#current_time) +- [date_bin](#date_bin) +- [date_bin_gapfill](#date_bin_gapfill) +- [date_bin_wallclock](#date_bin_wallclock) +- [date_bin_wallclock_gapfill](#date_bin_wallclock_gapfill) +- [date_trunc](#date_trunc) +- [datetrunc](#datetrunc) +- [date_part](#date_part) +- [datepart](#datepart) +- [extract](#extract) +- [from_unixtime](#from_unixtime) +- [make_date](#make_date) +- [now](#now) +- [today](#today) +- [to_char](#to_char) +- [to_date](#to_date) +- [to_local_time](#to_local_time) +- [to_timestamp](#to_timestamp) +- [to_timestamp_micros](#to_timestamp_micros) +- [to_timestamp_millis](#to_timestamp_millis) +- [to_timestamp_nanos](#to_timestamp_nanos) +- [to_timestamp_seconds](#to_timestamp_seconds) +- [to_unixtime](#to_unixtime) +- [tz](#tz) + +## current_date + +Returns the current UTC date. + +> [!Note] +> `current_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +> To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/version/query-data/sql/cast-types/). + +The `current_date()` return value is determined at query time and returns +the same date, no matter when in the query plan the function executes. + +``` +current_date() +``` + +{{< expand-wrapper >}} +{{% expand "View `current_date` query example" %}} + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + time, + temp, + current_date()::TIMESTAMP AS current_date +FROM home +WHERE + time > current_date()::TIMESTAMP - INTERVAL '5 years' +LIMIT 3 +``` + +{{% influxdb/custom-timestamps %}} + +| time | temp | current_date | +| :------------------- | ---: | :---------------------------- | +| 2022-01-01T08:00:00Z | 21 | {{< datetime/current-date >}} | +| 2022-01-01T09:00:00Z | 23 | {{< datetime/current-date >}} | +| 2022-01-01T10:00:00Z | 22.7 | {{< datetime/current-date >}} | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## current_time + +Returns the current UTC time. + +> [!Note] +> `current_date` returns a `TIME64` Arrow type, which isn't supported by InfluxDB. +> To use with InfluxDB, [cast the return value to a string](/influxdb/version/query-data/sql/cast-types/#cast-to-a-string-type). + +The `current_time()` return value is determined at query time and returns the same time, +no matter when in the query plan the function executes. + +``` +current_time() +``` + +{{< expand-wrapper >}} +{{% expand "View `current_time` query example" %}} + +_The following example uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +SELECT + time, + temp, + current_time()::STRING AS current_time +FROM home +LIMIT 3 +``` + +| time | temp | current_time | +| :------------------- | ---: | :---------------------------- | +| 2022-01-01T08:00:00Z | 21 | {{< datetime/current-time >}} | +| 2022-01-01T09:00:00Z | 23 | {{< datetime/current-time >}} | +| 2022-01-01T10:00:00Z | 22.7 | {{< datetime/current-time >}} | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## date_bin + +Calculates time intervals and returns the start of the interval nearest to the specified timestamp. +Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" +and applying an aggregate or selector function to each window. + +For example, if you "bin" or "window" data into 15-minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15-minute bin it is in: `2023-01-01T18:15:00Z`. + +```sql +date_bin(interval, expression[, origin_timestamp]) +``` + +##### Arguments: + +- **interval**: Bin interval. Supports the following interval units: + + - nanoseconds + - microseconds + - milliseconds + - seconds + - minutes + - hours + - days + - weeks + - months + - years + - century + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. +- **origin_timestamp**: Starting point used to determine bin boundaries. + _Default is the Unix epoch._ + +{{< expand-wrapper >}} +{{% expand "View `date_bin` query example" %}} + +The following query returns the daily average of water levels in the queried time range. + +```sql +SELECT + date_bin(INTERVAL '1 day', time, TIMESTAMP '1970-01-01 00:00:00Z') AS time, + avg("water_level") AS water_level_avg +FROM "h2o_feet" +WHERE + time >= timestamp '2019-09-10T00:00:00Z' + AND time <= timestamp '2019-09-20T00:00:00Z' +GROUP BY 1 +ORDER BY time DESC +``` + +| time | water_level_avg | +| :----------------------- | :----------------- | +| 2019-09-17T00:00:00.000Z | 4.370175687443861 | +| 2019-09-16T00:00:00.000Z | 4.6034785848437485 | +| 2019-09-15T00:00:00.000Z | 4.680651501506248 | +| 2019-09-14T00:00:00.000Z | 4.857683652395836 | +| 2019-09-13T00:00:00.000Z | 4.911051520291668 | +| 2019-09-12T00:00:00.000Z | 4.763990784533338 | +| 2019-09-11T00:00:00.000Z | 4.6582452515041695 | +| 2019-09-10T00:00:00.000Z | 4.608425018785421 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## date_bin_gapfill + +Calculates time intervals and returns the start of the interval nearest to the specified timestamp. +If no rows exist in a time interval, a new row is inserted with a `time` value +set to the interval start time, all columns in the `GROUP BY` clause populated, +and null values in aggregate columns. + +Use `date_bin_gapfill` with [`interpolate`](/influxdb/version/reference/sql/functions/misc/#interpolate) +or [`locf`](/influxdb/version/reference/sql/functions/misc/#locf) to +[fill gaps in data](/influxdb/version/query-data/sql/fill-gaps/) +at specified time intervals. + +```sql +date_bin_gapfill(interval, expression[, origin_timestamp]) +``` + +> [!Note] +> `date_bin_gapfill` requires [time bounds](/influxdb/version/query-data/sql/basic-query/#query-data-within-time-boundaries) +> in the `WHERE` clause. + +##### Arguments: + +- **interval**: Bin interval. Supports the following interval units: + + - nanoseconds + - microseconds + - milliseconds + - seconds + - minutes + - hours + - days + - weeks + - months + - years + - century + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. +- **origin_timestamp**: Starting point used to determine bin boundaries. + _Default is the Unix epoch._ + +##### Related functions + +[interpolate](/influxdb/version/reference/sql/functions/misc/#interpolate), +[locf](/influxdb/version/reference/sql/functions/misc/#locf) + +{{< expand-wrapper >}} +{{% expand "Use `date_bin_gapfill` to insert rows when no rows exists" %}} + +_The following example uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as _time, + room, + avg(temp) as temp +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY _time, room +``` + +| _time | room | temp | +| :------------------- | :---------- | ---: | +| 2022-01-01T08:00:00Z | Kitchen | 21 | +| 2022-01-01T08:30:00Z | Kitchen | | +| 2022-01-01T09:00:00Z | Kitchen | 23 | +| 2022-01-01T09:30:00Z | Kitchen | | +| 2022-01-01T10:00:00Z | Kitchen | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 21.1 | +| 2022-01-01T08:30:00Z | Living Room | | +| 2022-01-01T09:00:00Z | Living Room | 21.4 | +| 2022-01-01T09:30:00Z | Living Room | | +| 2022-01-01T10:00:00Z | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Use `date_bin_gapfill` to fill gaps in data" %}} + +Use `interpolate` and `locf` to fill the null values in rows inserted by +`date_bin_gapfill`. + +_The following examples use the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +{{< tabs-wrapper >}} +{{% tabs "small" %}} +[interpolate](#) +[locf](#) +{{% /tabs %}} +{{% tab-content %}} + +The example below uses [`interpolate`](/influxdb/version/reference/sql/functions/misc/#interpolate) +to fill null values by interpolating values between non-null values. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as _time, + room, + interpolate(avg(temp)) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY _time, room +``` + +| _time | room | AVG(home.temp) | +| :------------------- | :---------- | -------------: | +| 2022-01-01T08:00:00Z | Kitchen | 21 | +| 2022-01-01T08:30:00Z | Kitchen | 22 | +| 2022-01-01T09:00:00Z | Kitchen | 23 | +| 2022-01-01T09:30:00Z | Kitchen | 22.85 | +| 2022-01-01T10:00:00Z | Kitchen | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 21.1 | +| 2022-01-01T08:30:00Z | Living Room | 21.25 | +| 2022-01-01T09:00:00Z | Living Room | 21.4 | +| 2022-01-01T09:30:00Z | Living Room | 21.6 | +| 2022-01-01T10:00:00Z | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /tab-content %}} +{{% tab-content %}} + +The example below uses [`locf`](/influxdb/version/reference/sql/functions/misc/#locf) +to fill null values by carrying the last observed value forward. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as _time, + room, + locf(avg(temp)) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY _time, room +``` + +| _time | room | AVG(home.temp) | +| :------------------- | :---------- | -------------: | +| 2022-01-01T08:00:00Z | Kitchen | 21 | +| 2022-01-01T08:30:00Z | Kitchen | 21 | +| 2022-01-01T09:00:00Z | Kitchen | 23 | +| 2022-01-01T09:30:00Z | Kitchen | 23 | +| 2022-01-01T10:00:00Z | Kitchen | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 21.1 | +| 2022-01-01T08:30:00Z | Living Room | 21.1 | +| 2022-01-01T09:00:00Z | Living Room | 21.4 | +| 2022-01-01T09:30:00Z | Living Room | 21.4 | +| 2022-01-01T10:00:00Z | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## date_bin_wallclock + +Calculates time intervals using the timezone of a specified time value and +returns the start of the interval nearest to the specified timestamp. +Use `date_bin_wallclock` to downsample time series data by grouping rows into +time-based "bins" or "windows" that are based off "wall clock" times in a +specific timezone and applying an aggregate or selector function to each window. + +### Time zone shifts + +Many regions use time zone shifts (such as daylight saving time (DST)). +If a wall clock time bin starts at a time that does not exist in the specified +time zone, the timestamp is adjusted to the time that is the same offset from +the start of the day in that time zone. + +If a wall clock time represents an ambiguous time in the region then the +behavior depends on the size of the specified interval. If the interval is +larger than the difference between the two possible timestamps, then the earlier +timestamp is used. Otherwise, the function uses the timestamp that matches the +UTC offset of the input timestamp. + +```sql +date_bin_wallclock(interval, expression[, origin_timestamp]) +``` + +##### Arguments: + +- **interval**: Bin interval. Supports the following interval units: + + - nanoseconds + - microseconds + - milliseconds + - seconds + - minutes + - hours + - days + - weeks + + > [!Note] + > `date_bin_wallclock` does _not_ support month-, year-, or century-based intervals. + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + The output timestamp uses the time zone from this time expression. +- **origin_timestamp**: Starting point used to determine bin boundaries. + This must be a "wall clock" timestamp (no time zone). + _Default is the Unix epoch._ + + > [!Important] + > + > #### Avoid bins in time zone discontinuities + > + > [Time zone shifts](#time-zone-shifts) result in *discontinuities*–breaks + > in the continuity of time intervals (losing an hour or gaining an hour)–that + > can result in unexpected timestamps when using `date_bin_wallclock`. + > Avoid using an `interval` and `origin_timestamp` combination that results in a + > bin falling inside a time discontinuity. + > + > As a general rule, use either the default `origin_timestamp` or an origin + > timestamp with an offset relative to the Unix epoch that is equal to your + > specified `interval`. + > + > {{< expand-wrapper >}} +{{% expand "View time zone discontinuity example" %}} + +The following query illustrates how two timestamps, only one minute apart, +result in timestamps two hours apart when binned across a daylight saving +boundary: + +```sql +SELECT + tz('2020-10-25T02:29:00+01:00', 'Europe/Paris') AS original_time, + date_bin_wallclock( + INTERVAL '1 hour', + tz('2020-10-25T02:29:00+01:00', 'Europe/Paris'), + '1970-01-01T00:30:00' + ) AT TIME ZONE 'UTC' AS utc_bin_time +UNION +SELECT + tz('2020-10-25T02:30:00+01:00', 'Europe/Paris') AS original_time, + date_bin_wallclock( + INTERVAL '1 hour', + tz('2020-10-25T02:30:00+01:00', 'Europe/Paris'), + '1970-01-01T00:30:00' + ) AT TIME ZONE 'UTC' AS utc_bin_time +ORDER BY original_time; +``` + +| original_time | utc_bin_time | +| :------------------------ | :------------------- | +| 2020-10-25T02:29:00+01:00 | 2020-10-24T23:30:00Z | +| 2020-10-25T02:30:00+01:00 | 2020-10-25T01:30:00Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +{{< expand-wrapper >}} +{{% expand "View `date_bin_wallclock` query example" %}} + +The following query uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol) +and returns the 12-hour average temperature for each room using times in the +`America/Los_Angeles` time zone. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_wallclock(INTERVAL '12 hours', tz(time, 'America/Los_Angeles')) AS time, + room, + avg(temp) AS avg_temp +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY 1, room +``` + +| time | room | avg_temp | +| :------------------------ | :---------- | -----------------: | +| 2022-01-01T00:00:00-08:00 | Kitchen | 22.61666666666667 | +| 2022-01-01T12:00:00-08:00 | Kitchen | 22.7 | +| 2022-01-01T00:00:00-08:00 | Living Room | 22.166666666666668 | +| 2022-01-01T12:00:00-08:00 | Living Room | 22.2 | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## date_bin_wallclock_gapfill + +Calculates time intervals using the timezone of a specified time value and +returns the start of the interval nearest to the specified timestamp. +If no rows exist in a time interval, a new row is inserted with a `time` value +set to the interval start time, all columns in the `GROUP BY` clause populated, +and null values in aggregate columns. + +Use `date_bin_wallclock_gapfill` with [`interpolate`](/influxdb/version/reference/sql/functions/misc/#interpolate) +or [`locf`](/influxdb/version/reference/sql/functions/misc/#locf) to +[fill gaps in data](/influxdb/version/query-data/sql/fill-gaps/) +at specified time intervals in a specified time zone. + +### Time zone shifts + +Many regions use time zone shifts (such as daylight saving time (DST)). +If a wall clock time bin starts at a time that does not exist in the specified +time zone, the timestamp is adjusted to the time that is the same offset from +the start of the day in that time zone. + +If a wall clock time represents an ambiguous time in the region then the +behavior depends on the size of the specified interval. If the interval is +larger than the difference between the two possible timestamps, then the earlier +timestamp is used. Otherwise, the function uses the timestamp that matches the +UTC offset of the input timestamp. + +```sql +date_bin_wallclock_gapfill(interval, expression[, origin_timestamp]) +``` + +> [!Note] +> `date_bin_wallclock_gapfill` requires [time bounds](/influxdb/version/query-data/sql/basic-query/#query-data-within-time-boundaries) +> in the `WHERE` clause. + +##### Arguments: + +- **interval**: Bin interval. Supports the following interval units: + + - nanoseconds + - microseconds + - milliseconds + - seconds + - minutes + - hours + - days + - weeks + + > [!Note] + > `date_bin_wallclock_gapfill` does _not_ support month-, year-, or century-based intervals. + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + The output timestamp uses the time zone from this time expression. +- **origin_timestamp**: Starting point used to determine bin boundaries. + This must be a "wall clock" timestamp (no time zone). + _Default is the Unix epoch._ + + > [!Important] + > + > #### Avoid bins in time zone discontinuities + > + > [Time zone shifts](#time-zone-shifts) result in *discontinuities*–breaks + > in the continuity of time intervals (losing an hour or gaining an hour)–that + > can result in unexpected timestamps when using `date_bin_wallclock_gapfill`. + > Avoid using an `interval` and `origin_timestamp` combination that results in a + > bin falling inside a time discontinuity. + > + > As a general rule, use either the default `origin_timestamp` or an origin + > timestamp with an offset relative to the Unix epoch that is equal to your + > specified `interval`. + > + > [View time zone discontinuity example](#view-time-zone-discontinuity-example) + +##### Related functions + +[interpolate](/influxdb/version/reference/sql/functions/misc/#interpolate), +[locf](/influxdb/version/reference/sql/functions/misc/#locf) + +{{< expand-wrapper >}} +{{% expand "Use `date_bin_wallclock_gapfill` to insert rows when no rows exists" %}} + +_The following example uses the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_wallclock_gapfill(INTERVAL '30 minutes', tz(time, 'America/Los_Angeles')) as time, + room, + avg(temp) as temp +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY 1, room +``` + +| time | room | temp | +| :------------------------ | :---------- | ---: | +| 2022-01-01T00:00:00-08:00 | Kitchen | 21 | +| 2022-01-01T00:30:00-08:00 | Kitchen | | +| 2022-01-01T01:00:00-08:00 | Kitchen | 23 | +| 2022-01-01T01:30:00-08:00 | Kitchen | | +| 2022-01-01T02:00:00-08:00 | Kitchen | 22.7 | +| 2022-01-01T00:00:00-08:00 | Living Room | 21.1 | +| 2022-01-01T00:30:00-08:00 | Living Room | | +| 2022-01-01T01:00:00-08:00 | Living Room | 21.4 | +| 2022-01-01T01:30:00-08:00 | Living Room | | +| 2022-01-01T02:00:00-08:00 | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Use `date_bin_wallclock_gapfill` to fill gaps in data" %}} + +Use `interpolate` and `locf` to fill the null values in rows inserted by +`date_bin_wallclock_gapfill`. + +_The following examples use the sample data set provided in the +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +{{< tabs-wrapper >}} +{{% tabs "small" %}} +[interpolate](#) +[locf](#) +{{% /tabs %}} +{{% tab-content %}} + +The example below uses [`interpolate`](/influxdb/version/reference/sql/functions/misc/#interpolate) +to fill null values by interpolating values between non-null values. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_wallclock_gapfill(INTERVAL '30 minutes', tz(time, 'America/Los_Angeles')) as time, + room, + interpolate(avg(temp)) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY 1, room +``` + +| time | room | interpolate(avg(home.temp)) | +| :------------------------ | :---------- | --------------------------: | +| 2022-01-01T00:00:00-08:00 | Kitchen | 21 | +| 2022-01-01T00:30:00-08:00 | Kitchen | 22 | +| 2022-01-01T01:00:00-08:00 | Kitchen | 23 | +| 2022-01-01T01:30:00-08:00 | Kitchen | 22.85 | +| 2022-01-01T02:00:00-08:00 | Kitchen | 22.7 | +| 2022-01-01T00:00:00-08:00 | Living Room | 21.1 | +| 2022-01-01T00:30:00-08:00 | Living Room | 21.25 | +| 2022-01-01T01:00:00-08:00 | Living Room | 21.4 | +| 2022-01-01T01:30:00-08:00 | Living Room | 21.6 | +| 2022-01-01T02:00:00-08:00 | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /tab-content %}} +{{% tab-content %}} + +The example below uses [`locf`](/influxdb/version/reference/sql/functions/misc/#locf) +to fill null values by carrying the last observed value forward. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_wallclock_gapfill(INTERVAL '30 minutes', tz(time, 'America/Los_Angeles')) as time, + room, + locf(avg(temp)) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY 1, room +``` + +| time | room | locf(avg(home.temp)) | +| :------------------------ | :---------- | -------------------: | +| 2022-01-01T00:00:00-08:00 | Kitchen | 21 | +| 2022-01-01T00:30:00-08:00 | Kitchen | 21 | +| 2022-01-01T01:00:00-08:00 | Kitchen | 23 | +| 2022-01-01T01:30:00-08:00 | Kitchen | 23 | +| 2022-01-01T02:00:00-08:00 | Kitchen | 22.7 | +| 2022-01-01T00:00:00-08:00 | Living Room | 21.1 | +| 2022-01-01T00:30:00-08:00 | Living Room | 21.1 | +| 2022-01-01T01:00:00-08:00 | Living Room | 21.4 | +| 2022-01-01T01:30:00-08:00 | Living Room | 21.4 | +| 2022-01-01T02:00:00-08:00 | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## date_trunc + +Truncates a timestamp value to a specified precision. + +```sql +date_trunc(precision, expression) +``` + +##### Arguments: + +- **precision**: Time precision to truncate to. + The following precisions are supported: + + - year + - month + - week + - day + - hour + - minute + - second + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +##### Aliases + +- `datetrunc` + +{{< expand-wrapper >}} +{{% expand "View `date_trunc` query examples" %}} + +#### Use date_trunc to return hourly averages + +```sql +SELECT + avg(water_level) AS level, + date_trunc('hour', time) AS hour +FROM h2o_feet +WHERE + time >= timestamp '2019-09-10T00:00:00Z' + AND time <= timestamp '2019-09-12T00:00:00Z' +GROUP BY hour +ORDER BY hour +``` + +| hour | level | +| :----------------------- | :----------------- | +| 2019-09-10T00:00:00.000Z | 3.7248000000000006 | +| 2019-09-10T01:00:00.000Z | 3.8561499999999995 | +| 2019-09-10T02:00:00.000Z | 4.5405999999999995 | +| 2019-09-10T03:00:00.000Z | 5.5548072072500005 | +| 2019-09-10T04:00:00.000Z | 6.433900000000001 | +| 2019-09-10T05:00:00.000Z | 6.810949999999998 | + +#### Use date_trunc to return weekly averages + +```sql +SELECT + mean(water_level) as level, + date_trunc('week',time) AS week +FROM h2o_feet +WHERE + time >= timestamp '2019-08-01T00:00:00Z' + AND time <= timestamp '2019-10-31T00:00:00Z' +GROUP BY week +ORDER BY week +``` + +| level | week | +| :----------------- | :----------------------- | +| 4.3314415259020835 | 2019-08-12T00:00:00.000Z | +| 4.234838403584523 | 2019-08-19T00:00:00.000Z | +| 4.4184818559633925 | 2019-08-26T00:00:00.000Z | +| 4.405153386766021 | 2019-09-02T00:00:00.000Z | +| 4.725866897257734 | 2019-09-09T00:00:00.000Z | +| 4.499938596774042 | 2019-09-16T00:00:00.000Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## datetrunc + +_Alias of [date_trunc](#date_trunc)._ + +## date_part + +Returns the specified part of the date as an integer. + +```sql +date_part(part, expression) +``` + +##### Arguments: + +- **part**: Part of the date to return. + The following date parts are supported: + + - year + - month + - week _(week of the year)_ + - day _(day of the month)_ + - hour + - minute + - second + - millisecond + - microsecond + - nanosecond + - dow _(day of the week)_ + - day _(day of the year)_ + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +##### Aliases + +- `datepart` + +{{< expand-wrapper >}} +{{% expand "View `date_part` query examples" %}} + +```sql +SELECT + date_part('hour', time) AS hour, + time, + "level description", + location +FROM h2o_feet +WHERE + time >= timestamp '2019-08-17T02:54:00Z' + AND time <= timestamp '2019-08-17T03:06:00Z' +ORDER BY time +``` + +| hour | time | level description | location | +| :--: | :------------------- | :------------------- | :----------- | +| 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | coyote_creek | +| 2 | 2019-08-17T02:54:00Z | between 3 and 6 feet | santa_monica | +| 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | coyote_creek | +| 3 | 2019-08-17T03:00:00Z | between 3 and 6 feet | santa_monica | +| 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | coyote_creek | +| 3 | 2019-08-17T03:06:00Z | between 3 and 6 feet | santa_monica | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## datepart + +_Alias of [date_part](#date_part)._ + +## extract + +Returns a sub-field from a time value as an integer. +Similar to `date_part`, but with different arguments. + +```sql +extract(field FROM source) +``` + +##### Arguments + +- **field**: Part or field of the date to return. + The following date fields are supported: + + - year + - month + - week _(week of the year)_ + - day _(day of the month)_ + - hour + - minute + - second + - millisecond + - microsecond + - nanosecond + - dow _(day of the week)_ + - day _(day of the year)_ + +- **source**: Source time expression to operate on. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `extract` query example" %}} + +```sql +SELECT + extract(day from time) AS day +FROM + h2o_feet +LIMIT 1 +``` + +| day | +| :-- | +| 25 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## from_unixtime + +Converts an integer to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). +Input is parsed as a [Unix nanosecond timestamp](/influxdb/version/reference/glossary/#unix-timestamp) +and returns the corresponding RFC3339 timestamp. + +```sql +from_unixtime(expression) +``` + +##### Arguments: + +- **expression**: Integer expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +##### Related functions + +[to_unixtime](#to_unixtime) + +{{< expand-wrapper >}} +{{% expand "View `from_unixtime` query example" %}} + +```sql +SELECT + from_unixtime(1672531200000000000) AS RFC3339 +``` + +| RFC3339 | +| :------------------- | +| 2023-01-01T00:00:00Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## make_date + +Returns a date using the component parts (year, month, day). + +> [!Note] +> `make_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +> To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/version/query-data/sql/cast-types/). + +```sql +make_date(year, month, day) +``` + +##### Arguments + +- **year**: Year to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **month**: Month to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **day**: Day to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators + +{{< expand-wrapper >}} +{{% expand "View `make_date` query example" %}} + +```sql +SELECT make_date(2024, 01, 01)::STRING AS date +``` + +| date | +| :--------- | +| 2023-01-01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## now + +Returns the current UTC timestamp. + +The `now()` return value is determined at query time and returns the same timestamp, +no matter when in the query plan the function executes. + +```sql +now() +``` + +{{< expand-wrapper >}} +{{% expand "View `now` query example" %}} + +```sql +SELECT + "water_level", + "time" +FROM h2o_feet +WHERE + time <= now() - interval '12 minutes' +``` + +{{% /expand %}} +{{< /expand-wrapper >}} + +## today + +_Alias of [current_date](#current_date)._ + +## to_char + +Returns the string representation of a date, time, timestamp, or duration based on +a [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). + +> [!Note] +> Unlike the PostgreSQL `TO_CHAR()` function, this function does not support +> numeric formatting. + +```sql +to_char(expression, format) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function that results in a date, time, timestamp or duration. +- **format**: [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + to use to convert the expression. + +{{< expand-wrapper >}} +{{% expand "View `to_char` query example" %}} + +```sql +SELECT + to_char('2024-01-01T12:22:01Z'::TIMESTAMP, '%a %e-%b-%Y %H:%M:%S') AS datestring +``` + +| datestring | +| :----------------------- | +| Mon 1-Jan-2024 12:22:01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_date + +Converts a value to a date (`YYYY-MM-DD`). +Supports strings and numeric types as input. +Strings are parsed as `YYYY-MM-DD` unless another format is specified. +Numeric values are interpreted as days since the +[Unix epoch](/influxdb/version/reference/glossary/#unix-epoch). + +> [!Note] +> `to_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +> To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/version/query-data/sql/cast-types/). + +```sql +to_date(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `to_date` query example" %}} + +```sql +SELECT + to_date('1-Jan-2024', '%e-%b-%Y')::STRING AS date +``` + +| date | +| :--------- | +| 2024-01-01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_local_time + +Converts a timestamp with a timezone to a timestamp without a timezone +(no offset or timezone information). This function accounts for time shifts +like daylight saving time (DST). + +> [!Note] +> Use `to_local_time()` with [`date_bin()`](#date_bin) and +> [`date_bin_gapfill`](#date_bin_gapfill) to generate window boundaries based the +> local time zone rather than UTC. + +```sql +to_local_time(expression) +``` + +##### Arguments + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `to_local_time` query example" %}} + +```sql +SELECT + to_local_time('2024-01-01 00:00:00'::TIMESTAMP) AS "local time"; +``` + +| local time | +| :------------------- | +| 2024-01-01T00:00:00Z | + +{{% /expand %}} +{{% expand "View `to_local_time` query example with a time zone offset" %}} + +```sql +SELECT + to_local_time((arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))')) AT TIME ZONE 'America/Los_Angeles') AS "local time" +``` + +| local time | +| :------------------- | +| 2023-12-31T16:00:00Z | + +{{% /expand %}} +{{% expand "View `to_local_time` query example with `date_bin`" %}} + +```sql +SELECT + date_bin(interval '1 day', time, to_local_time(0::TIMESTAMP)) AT TIME ZONE 'America/Los_Angeles' AS time, + avg(f1), + avg(f2) +FROM + (VALUES (arrow_cast('2024-01-01 12:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 1.23, 4.56), + (arrow_cast('2024-01-01 13:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 2.46, 8.1), + (arrow_cast('2024-01-01 14:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 4.81, 16.2) + ) AS data(time, f1, f2) +GROUP BY 1 +``` + +| time | avg(data.f1) | avg(data.f2) | +| :------------------------ | -----------------: | -----------: | +| 2023-12-31T16:00:00-08:00 | 2.8333333333333335 | 9.62 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_timestamp + +Converts a value to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00Z`). +Supports timestamp, integer, and unsigned integer types as input. +Integers and unsigned integers are parsed as +[Unix nanosecond timestamps](/influxdb/version/reference/glossary/#unix-timestamp) +and return the corresponding RFC3339 timestamp. + +```sql +to_timestamp(expression) +``` + +##### Arguments: + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +{{< expand-wrapper >}} +{{% expand "View `to_timestamp` query example" %}} + +```sql +SELECT to_timestamp(1704067200000000000) +``` + +| to_timestamp(Int64(1704067200000000000)) | +| :--------------------------------------- | +| 2024-01-01T00:00:00Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_timestamp_micros + +Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). +Supports timestamp, integer, and unsigned integer types as input. +Integers and unsigned integers are parsed as +[Unix microsecond timestamps](/influxdb/version/reference/glossary/#unix-timestamp) +and return the corresponding RFC3339 timestamp. + +```sql +to_timestamp_micros(expression[, ..., format_n]) +``` + +##### Arguments: + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `to_timestamp_micros` query example" %}} + +```sql +SELECT to_timestamp_micros(1704067200000001) +``` + +| to_timestamp_micros(Int64(1704067200000001)) | +| :------------------------------------------- | +| 2024-01-01T00:00:00.000001Z | +{{% /expand %}} +{{% expand "View `to_timestamp_micros` example with string format parsing" %}} + +```sql +SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond +``` + +| microsecond | +| :-------------------------- | +| 2024-01-01T01:01:59.123456Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_timestamp_millis + +Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). +Supports timestamp, integer, and unsigned integer types as input. +Integers and unsigned integers are parsed as +[Unix millisecond timestamps](/influxdb/version/reference/glossary/#unix-timestamp) +and return the corresponding RFC3339 timestamp. + +```sql +to_timestamp_millis(expression[, ..., format_n]) +``` + +##### Arguments: + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `to_timestamp_millis` query example" %}} + +```sql +SELECT to_timestamp_millis(1704067200001) AS time +``` + +Results +| to_timestamp_millis(Int64(1704067200001)) | +| :---------------------------------------- | +| 2024-01-01T00:00:00.001Z | + +{{% /expand %}} +{{% expand "View `to_timestamp_millis` example with string format parsing" %}} + +```sql +SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond +``` + +| millisecond | +| :----------------------- | +| 2024-01-01T01:01:59.123Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_timestamp_nanos + +Converts a value to RFC3339 nanosecond timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). +Supports timestamp, integer, and unsigned integer types as input. +Integers and unsigned integers are parsed as +[Unix nanosecond timestamps](/influxdb/version/reference/glossary/#unix-timestamp) +and return the corresponding RFC3339 timestamp. + +```sql +to_timestamp_nanos(expression[, ..., format_n]) +``` + +##### Arguments: + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `to_timestamp_nanos` query example" %}} + +```sql +SELECT to_timestamp_nanos(1704067200000000001) +``` + +| to_timestamp_nanos(Int64(1704067200000000001)) | +| :--------------------------------------------- | +| 2024-01-01T00:00:00.000000001Z | +{{% /expand %}} +{{% expand "View `to_timestamp_nanos` example with string format parsing" %}} + +```sql +SELECT to_timestamp_nanos('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS nanosecond +``` + +| nanosecond | +| :----------------------------- | +| 2024-01-01T01:01:59.123456789Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_timestamp_seconds + +Converts a value to RFC3339 second timestamp format (`YYYY-MM-DDT00:00:00Z`). +Supports timestamp, integer, and unsigned integer types as input. +Integers and unsigned integers are parsed as +[Unix second timestamps](/influxdb/version/reference/glossary/#unix-timestamp) +and return the corresponding RFC3339 timestamp. + +```sql +to_timestamp_seconds(expression[, ..., format_n]) +``` + +##### Arguments: + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `to_timestamp_seconds` query example" %}} + +```sql +SELECT to_timestamp_seconds(1704067201) +``` + +| to_timestamp_seconds(Int64(1704067201)) | +| :-------------------------------------- | +| 2024-01-01T00:00:01Z | + +{{% /expand %}} +{{% expand "View `to_timestamp_seconds` example with string format parsing" %}} + +```sql +SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS second +``` + +| second | +| :------------------- | +| 2024-01-01T01:01:59Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_unixtime + +Converts a value to seconds since the [Unix epoch](/influxdb/version/reference/glossary/#unix-epoch). +Supports strings, timestamps, and floats as input. +Strings are parsed as [RFC3339Nano timestamps](/influxdb/version/reference/glossary/#rfc3339nano-timestamp) if no +[Rust Chrono format strings](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +are provided. + +```sql +to_unixtime(expression[, ..., format_n]) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +##### Related functions + +[from_unixtime](#from_unixtime) + +{{< expand-wrapper >}} +{{% expand "View `to_unixtime` query example" %}} + +```sql +SELECT to_unixtime('2024-01-01T01:01:59.123456789Z') AS unixtime +``` + +| unixtime | +| :--------- | +| 1704070919 | + +{{% /expand %}} +{{% expand "View `to_unixtime` example with string format parsing" %}} + +```sql +SELECT + to_unixtime('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS unixtime +``` + +| unixtime | +| :--------- | +| 1704070919 | + +{{% /expand %}} +{{< /expand-wrapper >}} + + +## tz + +Converts a timestamp to a provided timezone. If the second argument is not provided, it defaults to UTC. + +```sql +tz(time_expression[, timezone]) +``` + +##### Arguments + +- **time_expression**: time to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) + to cast the value into. Default is `'UTC'`. + The function returns the timestamp cast to the specified timezone. + If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `tz` query example" %}} + +```sql +SELECT tz('2024-01-01T01:00:00Z', 'America/New_York') AS time_tz +``` + +| time_tz | +| :----------------------- | +| 2024-10-01T02:00:00-04:00| + +{{% /expand %}} +{{% expand "View `tz` query example from Getting Started data" %}} + +```sql +SELECT tz(time, 'Australia/Sydney') AS time_tz, time FROM home ORDER BY time LIMIT 3; +``` + +| time_tz | time | +| :---------------------------------- | ------------------------------ | +| 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | +| 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | +| 1970-01-01T10:00:01.728982800+10:00 | 1970-01-01T00:00:01.728982800Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +##### Differences between tz and AT TIME ZONE + +`tz` and [`AT TIME ZONE`](/influxdb/version/reference/sql/operators/other/#at-time-zone) +differ when the input timestamp **does not** have a timezone. + +- When using an input timestamp that does not have a timezone (the default behavior in InfluxDB) with the + `AT TIME ZONE` operator, the operator returns the the same timestamp, but with a timezone offset + (also known as the "wall clock" time)--for example: + + ```sql + '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' + + -- Returns + 2024-01-01T00:00:00-08:00 + ``` + +- When using an input timestamp with a timezone, both the `tz()` function and the `AT TIME ZONE` + operator return the timestamp converted to the time in the specified timezone--for example: + + ```sql + '2024-01-01T00:00:00-00:00' AT TIME ZONE 'America/Los_Angeles' + tz('2024-01-01T00:00:00-00:00', 'America/Los_Angeles') + + -- Both return + 2023-12-31T16:00:00-08:00 + ``` + +- `tz()` always converts the input timestamp to the specified time zone. + If the input timestamp does not have a timezone, the function assumes it is a UTC timestamp--for example: + + ```sql + tz('2024-01-01 00:00:00'::TIMESTAMP, 'America/Los_Angeles') + -- Returns + 2023-12-31T16:00:00-08:00 + ``` + + ```sql + tz('2024-01-01T00:00:00+1:00', 'America/Los_Angeles') + -- Returns + 2023-12-31T15:00:00-08:00 + ``` + +{{< expand-wrapper >}} +{{% expand "View `tz` and `::timestamp` comparison" %}} +```sql +SELECT + '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp, + tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz; +``` +| time_timestamp | time_tz | +| :--------------------------- | :------------------------- | +| 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 | +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/group-by.md b/content/shared/sql-reference/group-by.md new file mode 100644 index 000000000..7720787dd --- /dev/null +++ b/content/shared/sql-reference/group-by.md @@ -0,0 +1,87 @@ +Use the `GROUP BY` clause to group data by values. + +`GROUP BY` is an optional clause used to group rows that have the same values for all columns and expressions in the list. +To output an aggregation for each group, include an aggregate or selector function in the `SELECT` statement. +When `GROUP BY` appears in a query, the `SELECT` list can only use columns that appear in the `GROUP BY` list +or in aggregate expressions. + +`GROUP BY` can use column aliases that are defined in the `SELECT` clause. +`GROUP BY` can't use an alias named `time`. +In a `GROUP BY` list, `time` always refers to the measurement `time` column. + +- [Syntax](#syntax) +- [Examples](#examples) + +## Syntax + +```sql +SELECT + AGGREGATE_FN(field1), + tag1 +FROM measurement +GROUP BY tag1 +``` + +## Examples + +### Group data by tag values + +```sql +SELECT + AVG("water_level") AS "avg_water_level", + "location" +FROM "h2o_feet" +GROUP BY "location" +``` + +{{< expand-wrapper >}}} +{{% expand "View example results" %}} + +| avg_water_level | location | +| ----------------: | ------------ | +| 5.359142420303919 | coyote_creek | +| 3.530712094245885 | santa_monica | + +{{% /expand %}} +{{< /expand-wrapper >}} + +Group results in 15 minute time intervals by tag: + +```sql +SELECT + "location", + DATE_BIN(INTERVAL '15 minutes', time, TIMESTAMP '2022-01-01 00:00:00Z') AS _time, + COUNT("water_level") AS count +FROM "h2o_feet" +WHERE + time >= timestamp '2019-09-17T00:00:00Z' + AND time <= timestamp '2019-09-17T01:00:00Z' +GROUP BY + _time, + location +ORDER BY + location, + _time +``` + +{{< expand-wrapper >}}} +{{% expand "View example results" %}} + +The query uses the `COUNT()` function to count the number of `water_level` points per 15 minute interval. +Results are then ordered by location and time. + +| location | _time | count | +| :----------- | :-------------------- | ----: | +| coyote_creek | 2019-09-16T23:45:00Z | 1 | +| coyote_creek | 2019-09-17T00:00:00Z | 2 | +| coyote_creek | 2019-09-17T00:15:00Z | 3 | +| coyote_creek | 2019-09-17T00:30:00Z | 2 | +| coyote_creek | 2019-09-17T00:45:00Z | 3 | +| santa_monica | 2019-09-16T23:45:00Z | 1 | +| santa_monica | 2019-09-17T00:00:00Z | 2 | +| santa_monica | 2019-09-17T00:15:00Z | 3 | +| santa_monica | 2019-09-17T00:30:00Z | 2 | +| santa_monica | 2019-09-17T00:45:00Z | 3 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/having.md b/content/shared/sql-reference/having.md new file mode 100644 index 000000000..a8b9d94b0 --- /dev/null +++ b/content/shared/sql-reference/having.md @@ -0,0 +1,72 @@ +The `HAVING` clause places conditions on results created by an aggregate operation on groups. +The `HAVING` clause must follow the `GROUP BY` clause and precede the `ORDER BY` clause. + +> [!Note] +> The `WHERE` clause filters rows based on specified conditions _before_ the aggregate operation. +> The `HAVING` clause filters rows based on specified conditions _after_ the aggregate operation has taken place. + +- [Syntax](#syntax) +- [Examples](#examples) + +## Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [HAVING_clause] [ORDER_BY_clause] +``` + +## Examples + +### Return rows with an aggregate value greater than a specified number + +```sql +SELECT + MEAN("water_level") AS "mean_water_level", "location" +FROM + "h2o_feet" +GROUP BY + "location" +HAVING + "mean_water_level" > 5 +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +The query returns on rows with values in the `mean_water_level` greater than 5 _after_ the aggregate operation. + +| location | mean_water_level | +| :----------- | :---------------- | +| coyote_creek | 5.359142420303919 | +{{% /expand %}} +{{< /expand-wrapper >}} + +### Return the average result greater than a specified number from a specific time range + +```sql +SELECT + AVG("water_level") AS "avg_water_level", + "time" +FROM + "h2o_feet" +WHERE + time >= '2019-09-01T00:00:00Z' AND time <= '2019-09-02T00:00:00Z' +GROUP BY + "time" +HAVING + "avg_water_level" > 6.82 +ORDER BY + "time" +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +The query calculates the average water level per time and only returns rows with an average greater than 6.82 during the specified time range. + +| time | avg_water_level | +| :------------------- | -----------------: | +| 2019-09-01T22:06:00Z | 6.8225 | +| 2019-09-01T22:12:00Z | 6.8405000000000005 | +| 2019-09-01T22:30:00Z | 6.8505 | +| 2019-09-01T22:36:00Z | 6.8325 | +{{% /expand %}} +{{< /expand-wrapper >}} \ No newline at end of file diff --git a/content/shared/sql-reference/information-schema.md b/content/shared/sql-reference/information-schema.md new file mode 100644 index 000000000..05765da5a --- /dev/null +++ b/content/shared/sql-reference/information-schema.md @@ -0,0 +1,135 @@ +The underlying query engine for the InfluxDB SQL implementation, +[DataFusion](https://arrow.apache.org/datafusion/index.html), provides commands +that return metadata related to your data schema. +To access this information, use the `SHOW TABLES`, `SHOW COLUMNS`, and +`SHOW ALL` commands or query views in the [ISO](https://www.iso.org/) SQL +`information_schema` schema. + +In the context of InfluxDB, a [measurement](/influxdb/version/reference/glossary/#measurement) +is represented as a table. Time, [tags](/influxdb/version/reference/glossary/#tag), +and [fields](/influxdb/version/reference/glossary/#field) are each represented +by columns in a table. + +- [SHOW TABLES](#show-tables) + - [Example SHOW TABLES output](#example-show-tables-output) +- [SHOW COLUMNS](#show-columns) + - [Example SHOW COLUMNS output](#example-show-columns-output) +- [SHOW ALL](#show-all) + - [Example SHOW ALL output](#view-show-all-example-output) + +## SHOW TABLES + +Returns information about tables (measurements) in an InfluxDB bucket. + +```sql +SHOW TABLES +``` + +You can also query the `information_schema.tables` view: + +```sql +SELECT * FROM information_schema.tables +``` + +#### Example SHOW TABLES output + +_Measurements are those that use the **`iox` table schema**._ + +| table_catalog | table_schema | table_name | table_type | +| :------------ | :----------------- | :---------- | :--------- | +| public | iox | home | BASE TABLE | +| public | system | queries | BASE TABLE | +| public | information_schema | tables | VIEW | +| public | information_schema | views | VIEW | +| public | information_schema | columns | VIEW | +| public | information_schema | df_settings | VIEW | + +## SHOW COLUMNS + +Returns information about the schema of a table (measurement) in an InfluxDB bucket. + +```sql +SHOW COLUMNS FROM example_table +``` + +You can also query the `information_schema.columns` view: + +```sql +SELECT + table_catalog, + table_schema, + table_name, + column_name, + data_type, + is_nullable +FROM information_schema.columns +WHERE table_name = 'example_table' +``` + +#### Example SHOW COLUMNS output + +| table_catalog | table_schema | table_name | column_name | data_type | is_nullable | +| :------------ | :----------- | :--------- | :---------- | :-------------------------- | :---------- | +| public | iox | home | co | Int64 | YES | +| public | iox | home | hum | Float64 | YES | +| public | iox | home | room | Dictionary(Int32, Utf8) | YES | +| public | iox | home | temp | Float64 | YES | +| public | iox | home | time | Timestamp(Nanosecond, None) | NO | + +## SHOW ALL + +Returns the configuration options of the current session. + +```sql +SHOW ALL +``` + +You can also query the `information_schema.df_settings` view: + +```sql +SELECT * FROM information_schema.df_settings +``` + +{{< expand-wrapper >}} +{{% expand "View `SHOW ALL` example output" %}} + +| name | setting | +| :-------------------------------------------------------- | :------- | +| datafusion.catalog.create_default_catalog_and_schema | true | +| datafusion.catalog.default_catalog | public | +| datafusion.catalog.default_schema | iox | +| datafusion.catalog.format | | +| datafusion.catalog.has_header | false | +| datafusion.catalog.information_schema | true | +| datafusion.catalog.location | | +| datafusion.execution.batch_size | 8192 | +| datafusion.execution.coalesce_batches | true | +| datafusion.execution.collect_statistics | false | +| datafusion.execution.parquet.enable_page_index | false | +| datafusion.execution.parquet.metadata_size_hint | | +| datafusion.execution.parquet.pruning | true | +| datafusion.execution.parquet.pushdown_filters | true | +| datafusion.execution.parquet.reorder_filters | true | +| datafusion.execution.parquet.skip_metadata | true | +| datafusion.execution.target_partitions | 4 | +| datafusion.execution.time_zone | +00:00 | +| datafusion.explain.logical_plan_only | false | +| datafusion.explain.physical_plan_only | false | +| datafusion.optimizer.enable_round_robin_repartition | true | +| datafusion.optimizer.filter_null_join_keys | false | +| datafusion.optimizer.hash_join_single_partition_threshold | 1048576 | +| datafusion.optimizer.max_passes | 3 | +| datafusion.optimizer.prefer_hash_join | true | +| datafusion.optimizer.repartition_aggregations | true | +| datafusion.optimizer.repartition_file_min_size | 10485760 | +| datafusion.optimizer.repartition_file_scans | true | +| datafusion.optimizer.repartition_joins | true | +| datafusion.optimizer.repartition_sorts | false | +| datafusion.optimizer.repartition_windows | true | +| datafusion.optimizer.skip_failed_rules | true | +| datafusion.optimizer.top_down_join_key_reordering | true | +| datafusion.sql_parser.enable_ident_normalization | true | +| datafusion.sql_parser.parse_float_as_decimal | false | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/join.md b/content/shared/sql-reference/join.md new file mode 100644 index 000000000..4911237fd --- /dev/null +++ b/content/shared/sql-reference/join.md @@ -0,0 +1,261 @@ +Use the `JOIN` clause to join data from different tables together based on +logical relationships. + +- [Syntax](#syntax) +- [Join types](#join-types) + - [INNER JOIN](#inner-join) + - [LEFT [OUTER] JOIN](#left-outer-join) + - [RIGHT [OUTER] JOIN](#right-outer-join) + - [FULL [OUTER] JOIN](#full-outer-join) +- [Troubleshoot joins](#troubleshoot-joins) + +## Syntax + +```sql +SELECT_clause +FROM +[INNER | LEFT [OUTER] | RIGHT [OUTER] | FULL [OUTER]] JOIN +ON +[WHERE_clause] +[GROUP_BY_clause] +[HAVING_clause] +[ORDER_BY_clause] +``` + +### Arguments + +- **left_join_items**: One or more tables specified in the `FROM` clause that + represent the left side of the join. +- **right_join_items**: One or more tables specified in the `JOIN` clause that + represent the right side of the join. +- **join_condition**: A predicate expression in the `ON` clause that uses the + `=` (equal to) comparison operator to compare column values from the left side + of the join to column values on the right side of the join. Rows with values + that match the defined predicate are joined using the specified + [join type](#join-types). + + +
+ +> [!Note] +> If both sides of the join include columns with the same name, you need to +> use the fully-qualified reference to prevent ambiguity. +> A _fully-qualified reference_ uses dot notation to reference both the table name +> and the column name--for example: `table_name.column_name` + +## Join types + +The following joins types are supported: + +{{< flex >}} +{{< flex-content "quarter" >}} + +

INNER JOIN

+ {{< svg svg="static/svgs/join-diagram.svg" class="inner small center" >}} +
+{{< /flex-content >}} +{{< flex-content "quarter" >}} + +

LEFT [OUTER] JOIN

+ {{< svg svg="static/svgs/join-diagram.svg" class="left small center" >}} +
+{{< /flex-content >}} +{{< flex-content "quarter" >}} + +

RIGHT [OUTER] JOIN

+ {{< svg svg="static/svgs/join-diagram.svg" class="right small center" >}} +
+{{< /flex-content >}} +{{< flex-content "quarter" >}} + +

FULL [OUTER] JOIN

+ {{< svg svg="static/svgs/join-diagram.svg" class="full small center" >}} +
+{{< /flex-content >}} +{{< /flex >}} + +#### Join sample tables + +The examples below illustrate join methods using the following tables: + +{{% influxdb/custom-timestamps %}} + +##### prod_line + +| time | station | produced | +| :------------------- | :-----: | -------: | +| 2022-01-01T08:00:00Z | B1 | 26 | +| 2022-01-01T09:00:00Z | B1 | 54 | +| 2022-01-01T10:00:00Z | B1 | 56 | +| 2022-01-01T11:00:00Z | B1 | | +| 2022-01-01T12:00:00Z | B1 | 82 | + +##### errors + +| time | station | level | message | +| :------------------- | :-----: | :---: | :------------------- | +| 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | +| 2022-01-01T11:00:00Z | B1 | crit | Station offline | + +{{% /influxdb/custom-timestamps %}} + +### INNER JOIN + +Inner joins combine rows from tables on the left and right side of the join +based on common column values defined in the `ON` clause. Rows that don't have +matching column values are not included in the output table. + +{{% influxdb/custom-timestamps %}} + +#### Inner join example + +{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} + +```sql +SELECT + * +FROM + prod_line +RIGHT JOIN errors ON + prod_line.time = errors.time + AND prod_line.station = errors.station +ORDER BY + prod_line.time +``` +##### Inner join results + +| time | station | produced | time | station | level | message | +| :------------------- | :-----: | -------: | :------------------- | :-----: | :---: | :------------------- | +| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | +| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | + +{{% /influxdb/custom-timestamps %}} + +### LEFT [OUTER] JOIN + +A left outer join returns all rows from the left side of the join and only +returns data from the right side of the join in rows with matching column values +defined in the `ON` clause. + +{{% influxdb/custom-timestamps %}} + +#### Left outer join example + +{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} + +```sql +SELECT + * +FROM + prod_line +LEFT JOIN errors ON + prod_line.time = errors.time + AND prod_line.station = errors.station +ORDER BY + prod_line.time +``` + +##### Left outer join results + +| time | station | produced | time | station | level | message | +| -------------------- | ------- | -------- | -------------------- | ------- | ----- | -------------------- | +| 2022-01-01T08:00:00Z | B1 | 26 | | | | | +| 2022-01-01T09:00:00Z | B1 | 54 | | | | | +| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | +| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | +| 2022-01-01T12:00:00Z | B1 | 82 | | | | | + +{{% /influxdb/custom-timestamps %}} + + +### RIGHT [OUTER] JOIN + +A right outer join returns all rows from the right side of the join and only +returns data from the left side of the join in rows with matching column values +defined in the `ON` clause. + +{{% influxdb/custom-timestamps %}} + +#### Right outer join example + +{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} + +```sql +SELECT + * +FROM + prod_line +RIGHT JOIN errors ON + prod_line.time = errors.time + AND prod_line.station = errors.station +ORDER BY + prod_line.time +``` + +##### Right outer join results + +| time | station | produced | time | station | level | message | +| :------------------- | :-----: | -------: | :------------------- | :-----: | :---: | :------------------- | +| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | +| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | + +{{% /influxdb/custom-timestamps %}} + +### FULL [OUTER] JOIN + +A full outer join returns all data from the left and right sides of the join and +combines rows with matching column values defined in the `ON` clause. +Data that is not available on each respective side of the join is NULL. + +{{% influxdb/custom-timestamps %}} + +#### Full outer join example + +{{% caption %}}[View sample tables](#join-sample-tables){{% /caption %}} + +```sql +SELECT + * +FROM + prod_line +FULL JOIN errors ON + prod_line.time = errors.time + AND prod_line.station = errors.station +ORDER BY + time +``` + +##### Full outer join results + +| time | station | produced | time | station | level | message | +| -------------------- | ------- | -------- | -------------------- | ------- | ----- | -------------------- | +| 2022-01-01T08:00:00Z | B1 | 26 | | | | | +| 2022-01-01T09:00:00Z | B1 | 54 | | | | | +| 2022-01-01T10:00:00Z | B1 | 56 | 2022-01-01T10:00:00Z | B1 | warn | Maintenance required | +| 2022-01-01T11:00:00Z | B1 | | 2022-01-01T11:00:00Z | B1 | crit | Station offline | +| 2022-01-01T12:00:00Z | B1 | 82 | | | | | + +{{% /influxdb/custom-timestamps %}} + +## Troubleshoot joins + +### Ambiguous reference to unqualified field + +If a column exists on both sides of the join and is used in in the `SELECT`, +`ON`, `WHERE`, `HAVING`, `GROUP BY`, or `ORDER BY` clause, you must use a +[fully-qualified reference](#fully-qualified-reference). For example, if both +sides of the join have a `time` column and you want to explicitly select a +time column, you must specifiy which side of the join to use the time column from: + +{{% code-callout "prod_line.time" "green" %}} +``` +SELECT + prod_line.time, + produced, + message, +FROM + prod_line +INNER JOIN errors ON + -- ... +``` +{{% /code-callout %}} diff --git a/content/shared/sql-reference/limit.md b/content/shared/sql-reference/limit.md new file mode 100644 index 000000000..b67ee6c70 --- /dev/null +++ b/content/shared/sql-reference/limit.md @@ -0,0 +1,65 @@ +The `LIMIT` clause limits the number of rows returned by a query to a specified non-negative integer. + +- [Syntax](#syntax) +- [Examples](#examples) + +## Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT +``` + +## Examples + +### Limit results to a maximum of five rows + +```sql +SELECT + "water_level","location", "time" +FROM + "h2o_feet" +LIMIT + 5 +``` +{{< expand-wrapper >}} +{{% expand "View example results" %}} +The query returns a maximum of 5 results. + +| location | time | water_level | +| :----------- | :----------------------- | ----------- | +| coyote_creek | 2019-08-28T00:00:00.000Z | 4.206 | +| coyote_creek | 2019-08-28T00:06:00.000Z | 4.052 | +| coyote_creek | 2019-08-28T00:12:00.000Z | 3.901 | +| coyote_creek | 2019-08-28T00:18:00.000Z | 3.773 | +| coyote_creek | 2019-08-28T00:24:00.000Z | 3.632 | +{{% /expand %}} +{{< /expand-wrapper >}} + +### Sort and limit results + +Use the `ORDER BY` and `LIMIT` clauses to first sort results by specified columns, +then limit the sorted results by a specified number. + +```sql +SELECT + "water_level", "location", "time" +FROM + "h2o_feet" +ORDER BY + "water_level" DESC +LIMIT + 3 +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +The query returns the highest 3 `water_level` readings in the `h2o_feet` measurement. + +| location | time | water_level | +| :----------- | :----------------------- | ----------- | +| coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | +| coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | +| coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | +{{% /expand %}} +{{< /expand-wrapper >}} + diff --git a/content/shared/sql-reference/operators/_index.md b/content/shared/sql-reference/operators/_index.md new file mode 100644 index 000000000..bdb03c1c5 --- /dev/null +++ b/content/shared/sql-reference/operators/_index.md @@ -0,0 +1,6 @@ +SQL operators are reserved words or characters which perform certain operations, +including comparisons and arithmetic. + +{{< children type="anchored-list" >}} + +{{< children hlevel="h2" >}} diff --git a/content/shared/sql-reference/operators/arithmetic.md b/content/shared/sql-reference/operators/arithmetic.md new file mode 100644 index 000000000..000ce7f58 --- /dev/null +++ b/content/shared/sql-reference/operators/arithmetic.md @@ -0,0 +1,135 @@ +Arithmetic operators take two numeric values (either literals or variables) +and perform a calculation that returns a single numeric value. + +| Operator | Description | | +| :------: | :------------- | :------------------------------------- | +| `+` | Addition | [{{< icon "link" >}}](#addition) | +| `-` | Subtraction | [{{< icon "link" >}}](#subtraction) | +| `*` | Multiplication | [{{< icon "link" >}}](#multiplication) | +| `/` | Division | [{{< icon "link" >}}](#division) | +| `%` | Modulo | [{{< icon "link" >}}](#modulo) | + +## + {#addition .monospace} + +The `+` operator adds two operands together and returns the sum. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 1 + 2 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| int64(1) + int64(2) | +| ------------------: | +| 3 | + +{{% /flex-content %}} +{{< /flex >}} + +## - {#subtraction .monospace} + +The `-` operator subtracts the right operand from the left operand and returns +the difference. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 4 - 2 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| int64(4) - int64(2) | +| ------------------: | +| 2 | + +{{% /flex-content %}} +{{< /flex >}} + +## * {#multiplication .monospace} + +The `*` operator multiplies two operands together and returns the product. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 2 * 3 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| int64(2) * int64(3) | +| ------------------: | +| 6 | + +{{% /flex-content %}} +{{< /flex >}} + +## / {#division .monospace} + +The `/` operator divides the left operand by the right operand and returns the quotient. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 6 / 3 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| int64(6) / int64(3) | +| ------------------: | +| 2 | + +{{% /flex-content %}} +{{< /flex >}} + +## % {#modulo .monospace} + +The `%` (modulo) operator divides the left operand by the right operand and returns the +remainder. If the left operand is not divisible by the right operand, it returns +the left operand. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 8 % 3 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(8) % Int64(3) | +| ------------------: | +| 2 | + +{{% /flex-content %}} +{{< /flex >}} + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 3 % 8 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(3) % Int64(8) | +| ------------------: | +| 3 | + +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/shared/sql-reference/operators/bitwise.md b/content/shared/sql-reference/operators/bitwise.md new file mode 100644 index 000000000..e60acf398 --- /dev/null +++ b/content/shared/sql-reference/operators/bitwise.md @@ -0,0 +1,132 @@ +Bitwise operators perform bitwise operations on bit patterns or binary numerals. + +| Operator | Meaning | | +| :------: | :------------------ | :------------------------------------------ | +| `&` | Bitwise and | [{{< icon "link" >}}](#bitwise-and) | +| `\|` | Bitwise or | [{{< icon "link" >}}](#bitwise-or) | +| `^` | Bitwise xor | [{{< icon "link" >}}](#bitwise-xor) | +| `>>` | Bitwise shift right | [{{< icon "link" >}}](#bitwise-shift-right) | +| `<<` | Bitwise shift left | [{{< icon "link" >}}](#bitwise-shift-left) | + +## & {#bitwise-and .monospace} + +The `&` (bitwise AND) operator compares each bit of the left operand to the +corresponding bit of the right operand. +If both bits are 1, the corresponding result bit is set to 1. +Otherwise, the corresponding result bit is set to 0. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 5 & 3 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(5) & Int64(3) | +| ------------------: | +| 1 | + +{{% /flex-content %}} +{{< /flex >}} + +## \| {#bitwise-or .monospace} + +The `|` (bitwise OR or inclusive OR) operator compares each bit of the left +operand to the corresponding bit of the right operand. +If either bit is 1, the corresponding result bit is set to 1. +Otherwise, the corresponding result bit is set to 0. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 5 | 3 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(5) \| Int64(3) | +| -------------------: | +| 7 | + +{{% /flex-content %}} +{{< /flex >}} + +## ^ {#bitwise-xor .monospace} + +The `^` (bitwise XOR or exclusive OR) operator compares each bit of the left +operand to the corresponding bit of the right operand. +If the bit in one of the operands is 0 and the bit in the other operand is 1, +the corresponding result bit is set to 1. +Otherwise, the corresponding result bit is set to 0. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 5 ^ 3 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(5) BIT_XOR Int64(3) | +| ------------------------: | +| 6 | + +{{% /flex-content %}} +{{< /flex >}} + +## \>\> {#bitwise-shift-right .monospace} + +The `>>` (bitwise shift right) operator shifts the bits in the left operand to +the right by the number of positions specified in the right operand. +For unsigned numbers, bit positions vacated by the shift operation are filled with 0. +For signed numbers, the sign bit is used to fill the vacated bit positions. +If the number is positive, the bit position is filled with 0. +If the number is negative, the bit position is filled with 1. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 5 >> 3 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(5) \>\> Int64(3) | +| ---------------------: | +| 0 | + +{{% /flex-content %}} +{{< /flex >}} + +## \<\< {#bitwise-shift-left .monospace} + +The `<<` (bitwise shift left) operator shifts the bits in the left operand to +the left by the number of positions specified in the right operand. +Bit positions vacated by the shift operation are filled with 0. +Bits that shift off the end are discarded, including the sign bit. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 5 << 3 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(5) \<\< Int64(3) | +| ---------------------: | +| 40 | + +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/shared/sql-reference/operators/comparison.md b/content/shared/sql-reference/operators/comparison.md new file mode 100644 index 000000000..1dc8fe84d --- /dev/null +++ b/content/shared/sql-reference/operators/comparison.md @@ -0,0 +1,262 @@ +Comparison operators evaluate the relationship between the left and right +operands and returns `true` or `false`. + + +| Operator | Meaning | | +| :------: | :------------------------------------------------------- | :------------------------------------------------------ | +| `=` | Equal to | [{{< icon "link" >}}](#equal-to) | +| `<>` | Not equal to | [{{< icon "link" >}}](#not-equal-to) | +| `!=` | Not equal to | [{{< icon "link" >}}](#not-equal-to) | +| `>` | Greater than | [{{< icon "link" >}}](#greater-than) | +| `>=` | Greater than or equal to | [{{< icon "link" >}}](#greater-than-or-equal) | +| `<` | Less than | [{{< icon "link" >}}](#less-than) | +| `<=` | Less than or equal to | [{{< icon "link" >}}](#less-than-or-equal) | +| `~` | Matches a regular expression | [{{< icon "link" >}}](#regexp-match) | +| `~*` | Matches a regular expression _(case-insensitive)_ | [{{< icon "link" >}}](#regexp-match-case-insensitive) | +| `!~` | Does not match a regular expression | [{{< icon "link" >}}](#regexp-nomatch) | +| `!~*` | Does not match a regular expression _(case-insensitive)_ | [{{< icon "link" >}}](#regexp-nomatch-case-insensitive) | + +## = {#equal-to .monospace} + +The `=` operator compares the left and right operands and, if equal, returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 123 = 123 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(123) = Int64(123) | +| :---------------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## !=, <> {#not-equal-to .monospace} + +The `!=` and `<>` operators compare the left and right operands and, if not equal, +returns `true`. Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 123 != 456 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(123) != Int64(456) | +| :----------------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 123 <> 456 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(123) != Int64(456) | +| :----------------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## > {#greater-than .monospace} + +The `>` operator compares the left and right operands and, if the left operand +is greater than the right operand, returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 3 > 2 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(3) > Int64(2) | +| :------------------ | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## >= {#greater-than-or-equal .monospace} + +The `>=` operator compares the left and right operands and, if the left operand +is greater than or equal to the right operand, returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 3 >= 2 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int64(3) >= Int64(2) | +| :------------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## < {#less-than .monospace} + +The `<` operator compares the left and right operands and, if the left operand +is less than the right operand, returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 1 < 2 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int641(1) < Int64(2) | +| :------------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## <= {#less-than-or-equal .monospace} + +The `<=` operator compares the left and right operands and, if the left operand +is less than or equal to the right operand, returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 1 <= 2 +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Int641(1) <= Int64(2) | +| :-------------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## ~ {#regexp-match .monospace} + +The `~` operator compares the left string operand to the right regular expression +operand and, if it matches (case-sensitive), returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 'abc' ~ 'a.*' +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Utf8("abc") ~ Utf8("a.*") | +| :------------------------ | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## ~* {#regexp-match-case-insensitive .monospace} + +The `~*` operator compares the left string operand to the right regular expression +operand and, if it matches (case-insensitive), returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 'Abc' ~* 'A.*' +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Utf8("Abc") ~* Utf8("A.*") | +| :------------------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## !~ {#regexp-nomatch .monospace} + +The `!~` operator compares the left string operand to the right regular expression +operand and, if it does not match (case-sensitive), returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 'abc' !~ 'd.*' +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Utf8("abc") !~ Utf8("d.*") | +| :------------------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +## !~* {#regexp-nomatch-case-insensitive .monospace} + +The `!~*` operator compares the left string operand to the right regular expression +operand and, if it does not match (case-insensitive), returns `true`. +Otherwise returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 'Abc' !~* 'a.*' +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Utf8("Abc") !~* Utf8("a.*") | +| :-------------------------- | +| false | + +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/shared/sql-reference/operators/logical.md b/content/shared/sql-reference/operators/logical.md new file mode 100644 index 000000000..092e19170 --- /dev/null +++ b/content/shared/sql-reference/operators/logical.md @@ -0,0 +1,438 @@ +Logical operators combine or manipulate conditions in a SQL query. + +| Operator | Meaning | | +| :-------: | :------------------------------------------------------------------------- | :------------------------------ | +| `AND` | Returns true if both operands are true. Otherwise, returns false. | [{{< icon "link" >}}](#and) | +| `BETWEEN` | Returns true if the left operand is within the range of the right operand. | [{{< icon "link" >}}](#between) | +| `EXISTS` | Returns true if the results of a subquery are not empty. | [{{< icon "link" >}}](#exists) | +| `IN` | Returns true if the left operand is in the right operand list. | [{{< icon "link" >}}](#in) | +| `LIKE` | Returns true if the left operand matches the right operand pattern string. | [{{< icon "link" >}}](#like) | +| `NOT` | Negates the subsequent expression. | [{{< icon "link" >}}](#not) | +| `OR` | Returns true if any operand is true. Otherwise, returns false. | [{{< icon "link" >}}](#or) | + +> [!Note] +> +> #### Sample data +> +> Query examples on this page use the following sample data sets: +> +> - [Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +> - [Home sensor actions sample data](/influxdb/version/reference/sample-data/#home-sensor-actions-data) + +## AND {.monospace} + +The `AND` operand returns `true` if both operands are `true`. Otherwise, it returns false. +This operator is typically used in the [`WHERE` clause](/influxdb/version/reference/sql/where/) +to combine multiple conditions. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT true AND false AS "AND condition" +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| AND condition | +| :------------ | +| false | + +{{% /flex-content %}} +{{< /flex >}} + +##### Examples + +{{< expand-wrapper >}} +{{% expand "`AND` operator in the `WHERE` clause" %}} + +```sql +SELECT * +FROM home +WHERE + co > 10 + AND room = 'Kitchen' +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :------ | ---: | :------------------- | +| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | +| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | +| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +## BETWEEN {.monospace} + +The `BETWEEN` operator returns `true` if the left numeric operand is within the +range specified in the right operand. Otherwise, it returns `false` + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 6 BETWEEN 5 AND 8 AS "BETWEEN condition" +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| BETWEEN condition | +| :---------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +##### Examples + +{{< expand-wrapper >}} +{{% expand "`BETWEEN` operator in the `WHERE` clause" %}} + +```sql +SELECT * +FROM home +WHERE + co BETWEEN 5 AND 10 +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | +| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | +| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | +| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +## EXISTS {.monospace} + +The `EXISTS` operator returns `true` if result of a +[correlated subquery](/influxdb/version/reference/sql/subqueries/#correlated-subqueries) +is not empty. Otherwise it returns `false`. + +_See [SQL subquery operators](/influxdb/version/reference/sql/subqueries/#subquery-operators)._ + +##### Examples + +{{< expand-wrapper >}} +{{% expand "`EXISTS` operator with a subquery in the `WHERE` clause" %}} + +```sql +SELECT * +FROM + home home_actions +WHERE EXISTS ( + SELECT * + FROM home + WHERE + home.co = home_actions.co - 1 +) +ORDER BY time +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | +| 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | +| 1 | 36.1 | Living Room | 22.3 | 2022-01-01T15:00:00Z | +| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | +| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | +| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +## IN {.monospace} + +The `IN` operator returns `true` if the left operand is in the right operand +list or subquery result. Otherwise, it returns `false`. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 'John' IN ('Jane', 'John') AS "IN condition" +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| IN condition | +| :----------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +_See [SQL subquery operators](/influxdb/version/reference/sql/subqueries/#subquery-operators)._ + +##### Examples + +{{< expand-wrapper >}} +{{% expand "`IN` operator with a list in the `WHERE` clause" %}} + +```sql +SELECT * +FROM home +WHERE + room IN ('Bathroom', 'Bedroom', 'Kitchen') +LIMIT 4 +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :------ | ---: | :------------------- | +| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | +| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | +| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | +| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{% expand "`IN` operator with a subquery in the `WHERE` clause" %}} + +```sql +SELECT * +FROM home +WHERE + room IN ( + SELECT DISTINCT room + FROM home_actions + ) +ORDER BY time +LIMIT 4 +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | +| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | +| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | +| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +## LIKE {.monospace} + +The `LIKE` operator returns `true` if the left operand matches the string pattern +specified in the right operand. +`LIKE` expressions support [SQL wildcard characters](#sql-wildcard-characters). + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 'John' LIKE 'J_%n' AS "LIKE condition" +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| LIKE condition | +| :------------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +{{< expand-wrapper >}} +{{% expand "`LIKE` operator in the `WHERE` clause" %}} + +```sql +SELECT * +FROM home +WHERE + room LIKE '%Room' +LIMIT 4 +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | +| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | +| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | +| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +### SQL wildcard characters + +The InfluxDB SQL implementation supports the following wildcard characters when +using the `LIKE` operator to match strings to a pattern. + +| Character | Description | +| :-------: | :--------------------------------- | +| `%` | Represents zero or more characters | +| `_` | Represents any single character | + +## NOT {.monospace} + +The `NOT` operator negates the subsequent expression. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT NOT true AS "NOT condition" +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| NOT condition | +| :------------ | +| false | + +{{% /flex-content %}} +{{< /flex >}} + +##### Examples + +{{< expand-wrapper >}} +{{% expand "`NOT IN`" %}} + +```sql +SELECT * +FROM home +WHERE + room NOT IN ('Kitchen', 'Bathroom') +LIMIT 4 +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | +| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | +| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | +| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "`NOT EXISTS`" %}} + +```sql +SELECT * +FROM + home home_actions +WHERE NOT EXISTS ( + SELECT * + FROM home + WHERE + home.co = home_actions.co + 4 +) +ORDER BY time +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | +| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | +| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | +| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | +| 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | +| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "`NOT BETWEEN`" %}} + +```sql +SELECT * +FROM home +WHERE + co NOT BETWEEN 1 AND 22 + AND room = 'Kitchen' +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :------ | ---: | :------------------- | +| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | +| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | +| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | +| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | +| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | +| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +## OR {.monospace} + +The `OR` operator returns `true` if any operand is `true`. +Otherwise, it returns `false`. +This operator is typically used in the [`WHERE` clause](/influxdb/version/reference/sql/where/) +to combine multiple conditions. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT true OR false AS "OR condition" +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| OR condition | +| :----------- | +| true | + +{{% /flex-content %}} +{{< /flex >}} + +##### Examples + +{{< expand-wrapper >}} +{{% expand "`OR` in the `WHERE` clause" %}} + +```sql +SELECT * +FROM home +WHERE + co > 20 + OR temp > 23 +``` + +{{% influxdb/custom-timestamps %}} + +| co | hum | room | temp | time | +| --: | ---: | :------ | ---: | :------------------- | +| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | +| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | +| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/operators/other.md b/content/shared/sql-reference/operators/other.md new file mode 100644 index 000000000..69f4b7b75 --- /dev/null +++ b/content/shared/sql-reference/operators/other.md @@ -0,0 +1,68 @@ +SQL supports miscellaneous operators that perform various operations. + +| Operator | Meaning | | +| :------: | :------------------ | :------------------------------------------ | +| `\|\|` | Concatenate strings | [{{< icon "link" >}}](#concatenate-strings) | + +## || {#concatenate-strings} + +The `||` operator concatenates two string operands into a single string. + +{{< flex >}} +{{% flex-content "two-thirds operator-example" %}} + +```sql +SELECT 'Hello' || ' world' AS "Concatenated" +``` + +{{% /flex-content %}} +{{% flex-content "third operator-example" %}} + +| Concatenated | +| :----------- | +| Hello world | + +{{% /flex-content %}} +{{< /flex >}} + +## AT TIME ZONE + +The `AT TIME ZONE` operator takes the timestamp in the left operand and returns +an equivalent timestamp with the updated time and offset of the time zone +specified in the right operand. +If no time zone is included in the input timestamp's +[Arrow data type](/influxdb/version/reference/sql/data-types/#sql-and-arrow-data-types), +the operator assumes the time is in the time zone specified. +Time zone offsets are provided by the operating system time zone database. + +```sql +SELECT time AT TIME ZONE 'America/Los_Angeles' FROM home +``` + +{{< expand-wrapper >}} +{{% expand "Convert a UTC timestamp to a specified timezone" %}} + +```sql +SELECT + arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))') + AT TIME ZONE 'America/Los_Angeles' AS 'Time with TZ offset' +``` + +| Time with TZ offset | +| :------------------------ | +| 2023-12-31T16:00:00-08:00 | + +{{% /expand %}} +{{% expand "Add a time zone offset to a timestamp without a specified timezone" %}} + +```sql +SELECT + '2024-01-01 00:00:00' AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' +``` + +| Local time with TZ offset | +| :------------------------ | +| 2024-01-01T00:00:00-08:00 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/order-by.md b/content/shared/sql-reference/order-by.md new file mode 100644 index 000000000..8048e8bc1 --- /dev/null +++ b/content/shared/sql-reference/order-by.md @@ -0,0 +1,86 @@ +The `ORDER BY` clause sort results by specified columns and order. +Sort data based on fields, tags, and timestamps. +The following orders are supported: + +- `ASC`: ascending _(default)_ +- `DESC`: descending + +- [Syntax](#syntax) +- [Examples](#examples) + +## Syntax + +```sql +[SELECT CLAUSE] [FROM CLAUSE] [ ORDER BY expression [ ASC | DESC ][, …] ] +``` + +> [!Note] +> **Note:** If your query includes a `GROUP BY` clause, the `ORDER BY` clause +> must appear **after** the `GROUP BY` clause. + +## Examples + +### Sort data by time with the most recent first + +```sql +SELECT + "water_level", "time" +FROM + "h2o_feet" +WHERE + "location" = 'coyote_creek' +ORDER BY + time DESC +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +| time | water_level | +| :----------------------- | :----------- | +| 2019-09-17T16:24:00.000Z | 3.235 | +| 2019-09-17T16:18:00.000Z | 3.314 | +| 2019-09-17T16:12:00.000Z | 3.402 | +| 2019-09-17T16:06:00.000Z | 3.497 | +| 2019-09-17T16:00:00.000Z | 3.599 | +| 2019-09-17T15:54:00.000Z | 3.704 | +{{% /expand %}} +{{< /expand-wrapper >}} + +### Sort data by tag or field values + +```sql +SELECT + "water_level", "time", "location" +FROM + "h2o_feet" +ORDER BY + "location", "water_level" DESC +``` + +### Sort data by selection order + +```sql +SELECT + "location","water_level", "time" +FROM + "h2o_feet" +ORDER BY + 1, 2 +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +The query sorts results the location of a column in the `SELECT` statement: +first by `location` (1), and second by `water_level` (2). + +| location | time | water_level | +| :----------- | :----------------------- | :---------- | +| coyote_creek | 2019-08-28T14:30:00.000Z | -0.61 | +| coyote_creek | 2019-08-29T15:18:00.000Z | -0.594 | +| coyote_creek | 2019-08-28T14:36:00.000Z | -0.591 | +| coyote_creek | 2019-08-28T14:24:00.000Z | -0.587 | +| coyote_creek | 2019-08-29T15:24:00.000Z | -0.571 | +| coyote_creek | 2019-08-27T13:42:00.000Z | -0.561 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/select.md b/content/shared/sql-reference/select.md new file mode 100644 index 000000000..df4d07ab9 --- /dev/null +++ b/content/shared/sql-reference/select.md @@ -0,0 +1,97 @@ +Use the `SELECT` statement to query data from an InfluxDB measurement. +The `SELECT` clause is required when querying data in SQL. + +- [Syntax](#syntax) +- [Examples](#examples) + +### Syntax + +```sql +SELECT a, b, "time" FROM +``` + +The SELECT clause supports the following: + + - `SELECT *` - return all tags, fields and timestamps. + - `SELECT DISTINCT` to return all distinct (different) values. + - `SELECT <"field" or "tag">` - returns a specified field or tag. + - `SELECT <"field" or "tag">, <"field" or "tag">` - returns more than one tag or field. + - `SELECT <"field"> AS a `- return the field as the alias. + +## Examples + +The following examples use data from the NOAA database. +To download the NOAA test data see [NOAA water sample data](/influxdb/v2/reference/sample-data/#noaa-water-sample-data). + +### Select all fields and tags from a measurement + +```sql +SELECT * FROM h2o_feet LIMIT 10 +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +| level description | location | time | water_level | +| :------------------------ | :----------- | :----------------------- | :---------- | +| at or greater than 9 feet | coyote_creek | 2019-09-01T00:00:00.000Z | 9.126144144 | +| at or greater than 9 feet | coyote_creek | 2019-09-01T00:06:00.000Z | 9.009 | +| between 6 and 9 feet | coyote_creek | 2019-09-01T00:12:00.000Z | 8.862 | +| between 6 and 9 feet | coyote_creek | 2019-09-01T00:18:00.000Z | 8.714 | +{{% /expand %}} +{{< /expand-wrapper >}} + +### Select specific tags and fields from a measurement + +```sql +SELECT "location", "water_level" FROM "h2o_feet" +``` + +{{< expand-wrapper >}} +{{% expand "View example results" "1" %}} +| location | water_level | +| :----------- | :---------- | +| coyote_creek | 9.126144144 | +| coyote_creek | 9.009 | +| coyote_creek | 8.862 | +| coyote_creek | 8.714 | +| coyote_creek | 8.547 | +{{% /expand %}} +{{< /expand-wrapper >}} + +### Select a field, tag and timestamp from a measurement + +```sql +SELECT "water_level", "location", "time" FROM "h2o_feet" +``` + +{{< expand-wrapper >}} +{{% expand "View example results" "2" %}} +| location | time | water_level | +| :----------- | :----------------------- | :---------- | +| coyote_creek | 2019-08-20T00:00:00.000Z | 8.638 | +| coyote_creek | 2019-08-20T00:06:00.000Z | 8.658 | +| coyote_creek | 2019-08-20T00:12:00.000Z | 8.678 | +{{% /expand %}} +{{< /expand-wrapper >}} + +### Select a field and perform basic arithmetic + +The following query takes the value of water_level, multiplies it by 3 and adds 5 to the result. + +```sql +SELECT ("water_level" * 3) + 5 FROM "h2o_feet" +``` + +{{< expand-wrapper >}} +{{% expand "View example results" "3" %}} +| water_level | +| :----------------- | +| 30.128 | +| 30.641000000000002 | +| 31.142000000000003 | +| 31.586 | +| 32.027 | +| 32.378432432 | +{{% /expand %}} +{{< /expand-wrapper >}} + diff --git a/content/shared/sql-reference/subqueries.md b/content/shared/sql-reference/subqueries.md new file mode 100644 index 000000000..adae0c0b4 --- /dev/null +++ b/content/shared/sql-reference/subqueries.md @@ -0,0 +1,735 @@ +Subqueries (also known as inner queries or nested queries) are queries within +a query. +Subqueries can be used in `SELECT`, `FROM`, `WHERE`, and `HAVING` clauses. + +- [Subquery operators](#subquery-operators) + - [[ NOT ] EXISTS](#-not--exists) + - [[ NOT ] IN](#-not--in) +- [SELECT clause subqueries](#select-clause-subqueries) +- [FROM clause subqueries](#from-clause-subqueries) +- [WHERE clause subqueries](#where-clause-subqueries) +- [HAVING clause subqueries](#having-clause-subqueries) +- [Subquery categories](#subquery-categories) + - [Correlated subqueries](#correlated-subqueries) + - [Non-correlated subqueries](#non-correlated-subqueries) + - [Scalar subqueries](#scalar-subqueries) + - [Non-scalar subqueries](#non-scalar-subqueries) + +> [!Note] +> #### Sample data +> +> Query examples on this page use the following sample data sets: +> +> - [Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +> - [Home sensor actions sample data](/influxdb/version/reference/sample-data/#home-sensor-actions-data) +> - [NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data) + +## Subquery operators + +- [[ NOT ] EXISTS](#-not--exists) +- [[ NOT ] IN](#-not--in) + +### [ NOT ] EXISTS + +The `EXISTS` operator returns all rows where a +_[correlated subquery](#correlated-subqueries)_ produces one or more matches for +that row. `NOT EXISTS` returns all rows where a _correlated subquery_ produces +zero matches for that row. Only _correlated subqueries_ are supported. + +#### Syntax {#-not-exists-syntax} + +```sql +[NOT] EXISTS (subquery) +``` + +### [ NOT ] IN + +The `IN` operator returns all rows where a given expression’s value can be found +in the results of a _[correlated subquery](#correlated-subqueries)_. +`NOT IN` returns all rows where a given expression’s value cannot be found in +the results of a subquery or list of values. + +#### Syntax {#-not-in-syntax} + +```sql +expression [NOT] IN (subquery|list-literal) +``` + +#### Examples {#-not-in-examples} + +{{< expand-wrapper >}} +{{% expand "View `IN` examples using a query" %}} +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[IN](#) +[NOT IN](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + time, + room, + temp +FROM + home +WHERE + room IN ( + SELECT + DISTINCT room + FROM + home_actions + ) +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + time, + room, + temp +FROM + home +WHERE + room NOT IN ( + SELECT + DISTINCT room + FROM + home_actions + ) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} +{{% /expand %}} + +{{% expand "View `IN` examples using a list literal" %}} +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[IN](#) +[NOT IN](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + time, + room, + temp +FROM home +WHERE room IN ('Bathroom', 'Bedroom', 'Kitchen') +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + time, + room, + temp +FROM home +WHERE room NOT IN ('Bathroom', 'Bedroom', 'Kitchen') +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} +{{% /expand %}} + +{{< /expand-wrapper >}} + +## SELECT clause subqueries + +`SELECT` clause subqueries use values returned from the inner query as part +of the outer query's `SELECT` list. +The `SELECT` clause only supports [scalar subqueries](#scalar-subqueries) that +return a single value per execution of the inner query. +The returned value can be unique per row. + +### Syntax {#select-subquery-syntax} + +```sql +SELECT [expression1[, expression2, ..., expressionN],] () +``` + +> [!Note] +> `SELECT` clause subqueries can be used as an alternative to `JOIN` operations. + +### Examples {#select-subquery-examples} + +{{< expand-wrapper >}} +{{% expand "`SELECT` clause with correlated subquery" %}} + +```sql +SELECT + time, + room, + co, + ( + SELECT + MAX(description) + FROM + home_actions + WHERE + time = home.time + AND room = home.room + AND level != 'ok' + ) AS "Alert Description" +FROM + home +ORDER BY + room, + time +``` + +#### Inner query results + +Because the inner query is a [correlated subquery](#correlated-subqueries), +the result depends on the values of `room` and `time` columns in the outer query. +The results below represent the action description for each `room` and `time` +combination with a `level` value that does not equal `ok`. + +{{% influxdb/custom-timestamps %}} +| time | room | MAX(home_actions.description) | +| :------------------- | :---------- | :------------------------------------------ | +| 2022-01-01T18:00:00Z | Kitchen | Carbon monoxide level above normal: 18 ppm. | +| 2022-01-01T19:00:00Z | Kitchen | Carbon monoxide level above normal: 22 ppm. | +| 2022-01-01T20:00:00Z | Kitchen | Carbon monoxide level above normal: 26 ppm. | +| 2022-01-01T19:00:00Z | Living Room | Carbon monoxide level above normal: 14 ppm. | +| 2022-01-01T20:00:00Z | Living Room | Carbon monoxide level above normal: 17 ppm. | +{{% /influxdb/custom-timestamps %}} + +#### Outer query results + +{{% influxdb/custom-timestamps %}} +| time | room | co | Alert Description | +| :------------------- | :---------- | --: | :------------------------------------------ | +| 2022-01-01T08:00:00Z | Kitchen | 0 | | +| 2022-01-01T09:00:00Z | Kitchen | 0 | | +| 2022-01-01T10:00:00Z | Kitchen | 0 | | +| 2022-01-01T11:00:00Z | Kitchen | 0 | | +| 2022-01-01T12:00:00Z | Kitchen | 0 | | +| 2022-01-01T13:00:00Z | Kitchen | 1 | | +| 2022-01-01T14:00:00Z | Kitchen | 1 | | +| 2022-01-01T15:00:00Z | Kitchen | 3 | | +| 2022-01-01T16:00:00Z | Kitchen | 7 | | +| 2022-01-01T17:00:00Z | Kitchen | 9 | | +| 2022-01-01T18:00:00Z | Kitchen | 18 | Carbon monoxide level above normal: 18 ppm. | +| 2022-01-01T19:00:00Z | Kitchen | 22 | Carbon monoxide level above normal: 22 ppm. | +| 2022-01-01T20:00:00Z | Kitchen | 26 | Carbon monoxide level above normal: 26 ppm. | +| 2022-01-01T08:00:00Z | Living Room | 0 | | +| 2022-01-01T09:00:00Z | Living Room | 0 | | +| 2022-01-01T10:00:00Z | Living Room | 0 | | +| 2022-01-01T11:00:00Z | Living Room | 0 | | +| 2022-01-01T12:00:00Z | Living Room | 0 | | +| 2022-01-01T13:00:00Z | Living Room | 0 | | +| 2022-01-01T14:00:00Z | Living Room | 0 | | +| 2022-01-01T15:00:00Z | Living Room | 1 | | +| 2022-01-01T16:00:00Z | Living Room | 4 | | +| 2022-01-01T17:00:00Z | Living Room | 5 | | +| 2022-01-01T18:00:00Z | Living Room | 9 | | +| 2022-01-01T19:00:00Z | Living Room | 14 | Carbon monoxide level above normal: 14 ppm. | +| 2022-01-01T20:00:00Z | Living Room | 17 | Carbon monoxide level above normal: 17 ppm. | +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## FROM clause subqueries + +`FROM` clause subqueries return a set of results that is then queried and +operated on by the outer query. + +### Syntax {#from-subquery-syntax} + +```sql +SELECT expression1[, expression2, ..., expressionN] FROM () +``` + +### Examples {#from-subquery-examples} + +{{< expand-wrapper >}} +{{% expand "View `FROM` clause subquery example" %}} + +The following query returns the average of maximum values per room. +The inner query returns the maximum value for each field from each room. +The outer query uses the results of the inner query and returns the average +maximum value for each field. + +```sql +SELECT + AVG(max_co) AS avg_max_co, + AVG(max_hum) AS avg_max_hum, + AVG(max_temp) AS avg_max_temp +FROM + ( + SELECT + room, + MAX(co) AS max_co, + MAX(hum) AS max_hum, + MAX(temp) AS max_temp + FROM + home + GROUP BY + room + ) +``` + +#### Inner query results + +| room | max_co | max_hum | max_temp | +| :---------- | -----: | ------: | -------: | +| Living Room | 17 | 36.4 | 22.8 | +| Kitchen | 26 | 36.9 | 23.3 | + +#### Outer query results + +| avg_max_co | avg_max_hum | avg_max_temp | +| ---------: | ----------: | -----------: | +| 21.5 | 36.7 | 23.1 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## WHERE clause subqueries + +[`WHERE` clause](/influxdb/version/reference/sql/where/) subqueries +compare an expression to the result of the subquery and return _true_ or _false_. +Rows that evaluate to _false_ or NULL are filtered from results. +The `WHERE` clause supports correlated and non-correlated subqueries +as well as scalar and non-scalar subqueries (depending on the the operator used +in the predicate expression). + +### Syntax {#where-subquery-syntax} + +```sql +SELECT + expression1[, expression2, ..., expressionN] +FROM + +WHERE + expression operator () +``` + +> [!Note] +> `WHERE` clause subqueries can be used as an alternative to `JOIN` operations. + +### Examples {#where-subquery-examples} +{{< expand-wrapper >}} +{{% expand "`WHERE` clause with scalar subquery" %}} + +The following query returns all points with `temp` values above the average +of all `temp` values. The subquery returns the average `temp` value. + +```sql +SELECT + * +FROM + home +WHERE + temp > ( + SELECT + AVG(temp) + FROM + home + ) +``` + +#### Inner query result + +| AVG(home.temp) | +| :----------------- | +| 22.396153846153844 | + +#### Outer query result + +{{% influxdb/custom-timestamps %}} +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | +| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | +| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | +| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | +| 1 | 36.5 | Kitchen | 22.8 | 2022-01-01T13:00:00Z | +| 1 | 36.3 | Kitchen | 22.8 | 2022-01-01T14:00:00Z | +| 3 | 36.2 | Kitchen | 22.7 | 2022-01-01T15:00:00Z | +| 7 | 36 | Kitchen | 22.4 | 2022-01-01T16:00:00Z | +| 9 | 36 | Kitchen | 22.7 | 2022-01-01T17:00:00Z | +| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | +| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | +| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | +| 0 | 36 | Living Room | 22.4 | 2022-01-01T13:00:00Z | +| 4 | 36 | Living Room | 22.4 | 2022-01-01T16:00:00Z | +| 5 | 35.9 | Living Room | 22.6 | 2022-01-01T17:00:00Z | +| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | +| 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{% expand "`WHERE` clause with non-scalar subquery" %}} + +Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and +can only return a single column. +The values in the returned column are evaluated as a list. + +The following query returns all points in the `home` measurement associated with +the same timestamps as `warn` level alerts in the `home_actions` measurement. + +```sql +SELECT + * +FROM + home +WHERE + time IN ( + SELECT + DISTINCT time + FROM + home_actions + WHERE + level = 'warn' + ) +``` + +#### Inner query result + +{{% influxdb/custom-timestamps %}} +| time | +| :------------------- | +| 2022-01-01T18:00:00Z | +| 2022-01-01T19:00:00Z | +| 2022-01-01T20:00:00Z | +{{% /influxdb/custom-timestamps %}} + +#### Outer query result + +{{% influxdb/custom-timestamps %}} +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 18 | 36.9 | Kitchen | 23.3 | 2022-01-01T18:00:00Z | +| 9 | 36.2 | Living Room | 22.8 | 2022-01-01T18:00:00Z | +| 26 | 36.5 | Kitchen | 22.7 | 2022-01-01T20:00:00Z | +| 17 | 36.4 | Living Room | 22.2 | 2022-01-01T20:00:00Z | +| 22 | 36.6 | Kitchen | 23.1 | 2022-01-01T19:00:00Z | +| 14 | 36.3 | Living Room | 22.5 | 2022-01-01T19:00:00Z | +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{% expand "`WHERE` clause with correlated subquery" %}} + +The following query returns rows with temperature values greater than the median +temperature value for each room. The subquery in the `WHERE` clause uses the +`room` value from the outer query to return the median `temp` value for that +specific room. + +```sql +SELECT + time, + room, + temp +FROM + home outer_query +WHERE + temp > ( + SELECT + median(temp) AS temp + FROM + home + WHERE + room = outer_query.room + GROUP BY + room + ) +ORDER BY room, time +``` + +#### Inner query result + +The result of the inner query depends on the value of `room` in the outer query, +but the following table contains the median `temp` value for each room. + +| room | temp | +| :---------- | ---: | +| Living Room | 22.3 | +| Kitchen | 22.7 | + +#### Outer query result + +{{% influxdb/custom-timestamps %}} +| time | room | temp | +| :------------------- | :---------- | ---: | +| 2022-01-01T09:00:00Z | Kitchen | 23 | +| 2022-01-01T13:00:00Z | Kitchen | 22.8 | +| 2022-01-01T14:00:00Z | Kitchen | 22.8 | +| 2022-01-01T18:00:00Z | Kitchen | 23.3 | +| 2022-01-01T19:00:00Z | Kitchen | 23.1 | +| 2022-01-01T13:00:00Z | Living Room | 22.4 | +| 2022-01-01T16:00:00Z | Living Room | 22.4 | +| 2022-01-01T17:00:00Z | Living Room | 22.6 | +| 2022-01-01T18:00:00Z | Living Room | 22.8 | +| 2022-01-01T19:00:00Z | Living Room | 22.5 | +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## HAVING clause subqueries + +[`HAVING` clause](/influxdb/version/reference/sql/having/) subqueries +compare an expression that uses aggregate values returned by aggregate functions +in the `SELECT` clause to the result of the subquery and return _true_ or _false_. +Rows that evaluate to _false_ or NULL are filtered from results. +The `HAVING` clause supports correlated and non-correlated subqueries +as well as scalar and non-scalar subqueries (depending on the the operator used +in the predicate expression). + +### Syntax {#having-subquery-syntax} + +```sql +SELECT + aggregate_expression1[, aggregate_expression2, ..., aggregate_expressionN] +FROM + +WHERE + +GROUP BY + column_expression1[, column_expression2, ..., column_expressionN] +HAVING + expression operator () +``` + +### Examples {#having-subquery-examples} + +{{< expand-wrapper >}} +{{% expand "`HAVING` clause with scalar subquery" %}} + +The following query returns all two hour blocks of time with average `temp` values +greater then the median `temp` value. + +```sql +SELECT + DATE_BIN(INTERVAL '2 hours', time) AS "2-hour block", + AVG(temp) AS avg_temp +FROM + home +GROUP BY + 1 +HAVING + avg_temp > ( + SELECT + MEDIAN(temp) + FROM + home + ) +``` + +#### Inner query result + +| MEDIAN(home.temp) | +| :---------------- | +| 22.45 | + +#### Outer query result + +{{% influxdb/custom-timestamps %}} +| 2-hour block | avg_temp | +| :------------------- | -------: | +| 2022-01-01T12:00:00Z | 22.475 | +| 2022-01-01T16:00:00Z | 22.525 | +| 2022-01-01T18:00:00Z | 22.925 | +| 2022-01-01T14:00:00Z | 22.525 | +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{% expand "`HAVING` clause with non-scalar subquery" %}} + +Non-scalar subqueries must use the `[NOT] IN` or `[NOT] EXISTS` operators and +can only return a single column. +The values in the returned column are evaluated as a list. + +The following query returns the maximum `co` and `temp` values within 2-hour +windows of time where the `time` value associated with time window is also +associated with a warning in the `home_actions` measurement. + +```sql +SELECT + date_bin(INTERVAL '2 hours', time) AS "2-hour block", + max(co) AS max_co, + max(temp) as max_temp +FROM + home +GROUP BY + 1, + room +HAVING + "2-hour block" IN ( + SELECT + DISTINCT time + FROM + home_actions + WHERE + level = 'warn' + ) +``` + +#### Inner query result + +{{% influxdb/custom-timestamps %}} +| time | +| :------------------- | +| 2022-01-01T18:00:00Z | +| 2022-01-01T19:00:00Z | +| 2022-01-01T20:00:00Z | +{{% /influxdb/custom-timestamps %}} + +#### Outer query result + +{{% influxdb/custom-timestamps %}} +| 2-hour block | max_co | max_temp | +| :------------------- | -----: | -------: | +| 2022-01-01T18:00:00Z | 14 | 22.8 | +| 2022-01-01T18:00:00Z | 22 | 23.3 | +| 2022-01-01T20:00:00Z | 17 | 22.2 | +| 2022-01-01T20:00:00Z | 26 | 22.7 | +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{% expand "`HAVING` clause with correlated subquery" %}} + +The following query returns 2-hour windows of time with average `temp` values +greater than the median `temp` value for each room. The subquery in the `HAVING` +clause uses the `room` value from the outer query to return the median `temp` value +for that specific room. + +```sql +SELECT + time, + room, + temp +FROM + home outer_query +WHERE + temp > ( + SELECT + median(temp) AS temp + FROM + home + WHERE + room = outer_query.room + GROUP BY + room + ) +ORDER BY room, time +``` + +#### Inner query result + +The result of the inner query depends on the value of `room` in the outer query, +but the following table contains the median `temp` value for each room. + +| room | temp | +| :---------- | ---: | +| Living Room | 22.3 | +| Kitchen | 22.7 | + +#### Outer query result + +{{% influxdb/custom-timestamps %}} +| 2-hour block | room | avg_temp | +| :------------------- | :---------- | -----------------: | +| 2022-01-01T14:00:00Z | Kitchen | 22.75 | +| 2022-01-01T18:00:00Z | Kitchen | 23.200000000000003 | +| 2022-01-01T16:00:00Z | Living Room | 22.5 | +| 2022-01-01T18:00:00Z | Living Room | 22.65 | +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Subquery categories + +SQL subqueries can be categorized as one or more of the following based on the +behavior of the subquery: + +- [correlated](#correlated-subqueries) or [non-correlated](#non-correlated-subqueries) +- [scalar](#scalar-subqueries) or [non-scalar](#non-scalar-subqueries) + +### Correlated subqueries + +In a **correlated** subquery, the inner query depends on the values of the +current row being processed. + +In the query below, the inner query (`SELECT temp_avg FROM weather WHERE location = home.room`) +depends on data (`home.room`) from the outer query +(`SELECT time, room, temp FROM home`) and is therefore a _correlated_ subquery. + +```sql +SELECT + time, + room, + temp +FROM + home +WHERE + temp = ( + SELECT + temp_avg + FROM + weather + WHERE + location = home.room + ) +``` + +> [!Important] +> +> #### Correlated subquery performance +> +> Because correlated subqueries depend on the outer query and typically must +> execute for each row returned by the outer query, correlated subqueries are +> **less performant** than non-correlated subqueries. + +### Non-correlated subqueries + +In a **non-correlated** subquery, the inner query _doesn't_ depend on the outer +query and executes independently. +The inner query executes first, and then passes the results to the outer query. + +In the query below, the inner query (`SELECT MIN(temp_avg) FROM weather`) can +run independently from the outer query (`SELECT time, temp FROM home`) and is +therefore a _non-correlated_ subquery. + +```sql +SELECT + time, + temp +FROM + home +WHERE + temp < ( + SELECT + MIN(temp_avg) + FROM + weather + ) +``` + +### Scalar subqueries + +A **scalar** subquery returns a single value (one column of one row). +If no rows are returned, the subquery returns NULL. + +The example subquery below returns the average value of a specified column. +This value is a single scalar value. + +```sql +SELECT * FROM home WHERE co > (SELECT avg(co) FROM home) +``` + +### Non-scalar subqueries + +A **non-scalar** subquery returns 0, 1, or multiple rows, each of which may +contain 1 or multiple columns. For each column, if there is no value to return, +the subquery returns NULL. If no rows qualify to be returned, the subquery +returns 0 rows. + +The example subquery below returns all distinct values in a column. +Multiple values are returned. + +```sql +SELECT * FROM home WHERE room IN (SELECT DISTINCT room FROM home_actions) +``` \ No newline at end of file diff --git a/content/shared/sql-reference/table-value-constructor.md b/content/shared/sql-reference/table-value-constructor.md new file mode 100644 index 000000000..d5f06ef2d --- /dev/null +++ b/content/shared/sql-reference/table-value-constructor.md @@ -0,0 +1,109 @@ +The table value constructor (TVC) uses the `VALUES` keyword to specify a set of +row value expressions to construct into a table. +The TVC can be used in the `FROM` clause +to build an ad hoc table at query time. + +```sql +VALUES (row_value_list)[,...n] +``` + +##### Arguments + +- **row_value_list**: + Comma-delimited list of column values. + Enclose each list in parentheses and separate multiple lists with commas. + Each list must have the same number of values and values must be in the same + order as columns in the table. + Each list must contain a value for each column. + +## Usage + +```sql +SELECT + expression[,...n] +FROM + (VALUES (row_value_list)[,...n]) [AS] table_name(column_name[,...n]) +``` + +> [!Note] +> When using the TVC, the `AS` keyword is optional and implied when naming the +> table and providing column names. + +## Examples + +- [Select data from an ad hoc table](#select-data-from-an-ad-hoc-table) + + +### Select data from an ad hoc table + +```sql +SELECT * +FROM + (VALUES ('2023-01-01 12:00:00'::TIMESTAMP, 1.23, 4.56), + ('2023-01-01 13:00:00'::TIMESTAMP, 2.46, 8.1), + ('2023-01-01 13:00:00'::TIMESTAMP, 4.81, 16.2) + ) AS data(time, f1, f2) +``` + +| time | f1 | f2 | +| :------------------- | ---: | ---: | +| 2023-01-01T12:00:00Z | 1.23 | 4.56 | +| 2023-01-01T13:00:00Z | 2.46 | 8.1 | +| 2023-01-01T13:00:00Z | 4.81 | 16.2 | + + diff --git a/content/shared/sql-reference/union.md b/content/shared/sql-reference/union.md new file mode 100644 index 000000000..be4b58939 --- /dev/null +++ b/content/shared/sql-reference/union.md @@ -0,0 +1,156 @@ +The `UNION` clause combines the results of two or more `SELECT` statements into +a single result set. +By default, `UNION` only keeps unique rows. +To keep all rows, including duplicates, use `UNION ALL`. + +- [Syntax](#syntax) +- [Examples](#examples) + +**When using the `UNION` clause**: + +- The number of columns in each result set must be the same. +- Columns must be in the same order and of the same or compatible data types. + +## Syntax + +```sql +SELECT expression[,...n] +FROM measurement_1 +UNION [ALL] +SELECT expression[,...n] +FROM measurement_2 +``` + +## Examples + +- [Union results from different measurements](#union-results-from-different-measurements) +- [Return the highest and lowest three results in a single result set](#return-the-highest-and-lowest-three-results-in-a-single-result-set) +- [Union query results with custom data](#union-query-results-with-custom-data) + +### Union results from different measurements + +```sql +( + SELECT + 'h2o_pH' AS measurement, + time, + "pH" AS "water_pH" + FROM "h2o_pH" + LIMIT 4 +) +UNION +( + SELECT + 'h2o_quality' AS measurement, + time, + index + FROM h2o_quality + LIMIT 4 +) +``` +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +| measurement | time | water_pH | +| :---------- | :------------------- | -------: | +| h2o_pH | 2019-08-27T00:12:00Z | 7 | +| h2o_pH | 2019-08-27T00:18:00Z | 8 | +| h2o_quality | 2019-09-11T01:06:00Z | 89 | +| h2o_pH | 2019-08-27T00:06:00Z | 7 | +| h2o_quality | 2019-09-11T00:00:00Z | 26 | +| h2o_quality | 2019-09-11T01:00:00Z | 19 | +| h2o_quality | 2019-09-11T00:48:00Z | 65 | +| h2o_pH | 2019-08-27T00:00:00Z | 8 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### Return the highest and lowest three results in a single result set + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol)._ + +```sql +( + SELECT + 'low' as type, + time, + co + FROM home + ORDER BY co ASC + LIMIT 3 +) +UNION +( + SELECT + 'high' as type, + time, + co + FROM home + ORDER BY co DESC + LIMIT 3 +) +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +| type | time | co | +| :--- | :------------------- | --: | +| high | 2022-01-01T20:00:00Z | 26 | +| high | 2022-01-01T19:00:00Z | 22 | +| high | 2022-01-01T18:00:00Z | 18 | +| low | 2022-01-01T14:00:00Z | 0 | +| low | 2022-01-01T10:00:00Z | 0 | +| low | 2022-01-01T08:00:00Z | 0 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### Union query results with custom data + +_The following example uses the sample data set provided in +[Get started with InfluxDB tutorial](/influxdb/version/get-started/write/#construct-line-protocol). +It also uses the [table value constructor](/influxdb/version/reference/sql/table-value-constructor/) +to build a table with custom data._ + +```sql +SELECT * +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +UNION +SELECT * FROM + (VALUES (0, 34.2, 'Bedroom', 21.1, '2022-01-01T08:00:00Z'::TIMESTAMP), + (0, 34.5, 'Bedroom', 21.2, '2022-01-01T09:00:00Z'::TIMESTAMP), + (0, 34.6, 'Bedroom', 21.5, '2022-01-01T10:00:00Z'::TIMESTAMP), + (0, 34.5, 'Bedroom', 21.8, '2022-01-01T11:00:00Z'::TIMESTAMP), + (0, 33.9, 'Bedroom', 22.0, '2022-01-01T12:00:00Z'::TIMESTAMP) + ) newRoom(co, hum, room, temp, time) +ORDER BY room, time +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +| co | hum | room | temp | time | +| --: | ---: | :---------- | ---: | :------------------- | +| 0 | 34.2 | Bedroom | 21.1 | 2022-01-01T08:00:00Z | +| 0 | 34.5 | Bedroom | 21.2 | 2022-01-01T09:00:00Z | +| 0 | 34.6 | Bedroom | 21.5 | 2022-01-01T10:00:00Z | +| 0 | 34.5 | Bedroom | 21.8 | 2022-01-01T11:00:00Z | +| 0 | 33.9 | Bedroom | 22 | 2022-01-01T12:00:00Z | +| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z | +| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z | +| 0 | 36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z | +| 0 | 36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z | +| 0 | 36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z | +| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z | +| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00Z | +| 0 | 36 | Living Room | 21.8 | 2022-01-01T10:00:00Z | +| 0 | 36 | Living Room | 22.2 | 2022-01-01T11:00:00Z | +| 0 | 35.9 | Living Room | 22.2 | 2022-01-01T12:00:00Z | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/where.md b/content/shared/sql-reference/where.md new file mode 100644 index 000000000..79ac64cee --- /dev/null +++ b/content/shared/sql-reference/where.md @@ -0,0 +1,120 @@ +Use the `WHERE` clause to filter results based on fields, tags, or timestamps. + +- [Syntax](#syntax) +- [Examples](#examples) + +## Syntax + +```sql +SELECT_clause FROM_clause WHERE [(AND|OR) [...]] +``` + +> [!Note] +> **Note:** Unlike InfluxQL, SQL **supports** `OR` in the `WHERE` clause to +> specify multiple conditions, including time ranges. + +## Examples + +Note that single quotes are required for string literals in the `WHERE` clause. + +### Filter data based on field values + +```sql +SELECT * +FROM "h2o_feet" +WHERE "water_level" >= 9.78 +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +The query returns data from the `h2o_feet` measurement with `water_level` field values +that are greater than or equal to 9.78. + +| level description | location | time | water_level | +| :------------------------ | :----------- | :----------------------- | :---------- | +| at or greater than 9 feet | coyote_creek | 2019-09-01T23:06:00.000Z | 9.8 | +| at or greater than 9 feet | coyote_creek | 2019-09-01T23:12:00.000Z | 9.829 | +| at or greater than 9 feet | coyote_creek | 2019-09-01T23:18:00.000Z | 9.862 | +| at or greater than 9 feet | coyote_creek | 2019-09-01T23:24:00.000Z | 9.892 | +| at or greater than 9 feet | coyote_creek | 2019-09-01T23:30:00.000Z | 9.902 | +| at or greater than 9 feet | coyote_creek | 2019-09-01T23:36:00.000Z | 9.898 | + +{{% /expand %}} +{{< /expand-wrapper >}} + + +### Filter data based on specific tag and field values + +```sql +SELECT * +FROM "h2o_feet" +WHERE "location" = 'santa_monica' and "level description" = 'below 3 feet' +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +The query returns all data from the `h2o_feet` measurement with the `location` tag key, `santa_monica`, +and a `level description` field value that equals `below 3 feet`. + +| level description | location | time | water_level | +| :---------------- | :----------- | :----------------------- | :---------- | +| below 3 feet | santa_monica | 2019-09-01T00:00:00.000Z | 1.529 | +| below 3 feet | santa_monica | 2019-09-01T00:06:00.000Z | 1.444 | +| below 3 feet | santa_monica | 2019-09-01T00:12:00.000Z | 1.335 | +| below 3 feet | santa_monica | 2019-09-01T00:18:00.000Z | 1.345 | +| below 3 feet | santa_monica | 2019-09-01T00:24:00.000Z | 1.27 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### Filter data within a specific time period + +```sql +SELECT * +FROM h2o_feet +WHERE "location" = 'santa_monica' +AND "time" >= '2019-08-19T12:00:00Z' AND "time" <= '2019-08-19T13:00:00Z' +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +The query returns results with timestamps greater than or equal to `08-19-2019T12:00:00Z` and +less than or equal to `08-19-2019T13:00:00Z`. + +| level description | location | time | water_level | +| :---------------- | :----------- | :----------------------- | :---------- | +| below 3 feet | santa_monica | 2019-08-19T12:00:00.000Z | 2.533 | +| below 3 feet | santa_monica | 2019-08-19T12:06:00.000Z | 2.543 | +| below 3 feet | santa_monica | 2019-08-19T12:12:00.000Z | 2.385 | +| below 3 feet | santa_monica | 2019-08-19T12:18:00.000Z | 2.362 | +| below 3 feet | santa_monica | 2019-08-19T12:24:00.000Z | 2.405 | +| below 3 feet | santa_monica | 2019-08-19T12:30:00.000Z | 2.398 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### Filter data using the OR operator + +```sql +SELECT * +FROM "h2o_feet" +WHERE "level description" = 'less than 3 feet' OR "water_level" < 2.5 +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +The query returns results with a `level description` field value equal to `less than 3 feet` or a `water_level` field value less than 2.5. + +| level description | location | time | water_level | +| :---------------- | :----------- | :----------------------- | :---------- | +| below 3 feet | coyote_creek | 2019-08-25T10:06:00.000Z | 2.398 | +| below 3 feet | coyote_creek | 2019-08-25T10:12:00.000Z | 2.234 | +| below 3 feet | coyote_creek | 2019-08-25T10:18:00.000Z | 2.064 | +| below 3 feet | coyote_creek | 2019-08-25T10:24:00.000Z | 1.893 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/v3-distributed-admin-custom-partitions/_index.md b/content/shared/v3-distributed-admin-custom-partitions/_index.md new file mode 100644 index 000000000..3f4a82508 --- /dev/null +++ b/content/shared/v3-distributed-admin-custom-partitions/_index.md @@ -0,0 +1,414 @@ +When writing data to {{< product-name >}}, the InfluxDB v3 storage engine stores data in [Apache Parquet](https://parquet.apache.org/) format in the [Object store](/influxdb/version/reference/internals/storage-engine/#object-store). Each Parquet file represents a _partition_--a logical grouping of data. +By default, InfluxDB partitions each table _by day_. +If this default strategy yields unsatisfactory performance for single-series queries, +you can define a custom partitioning strategy by specifying tag values and different time intervals to optimize query performance for your specific schema and workload. + +- [Advantages](#advantages) +- [Disadvantages](#disadvantages) +- [Limitations](#limitations) +- [Plan for custom partitioning](#plan-for-custom-partitioning) +- [How partitioning works](#how-partitioning-works) + - [Partition templates](#partition-templates) + - [Partition keys](#partition-keys) +- [Partitions in the query life cycle](#partitions-in-the-query-life-cycle) +- [Partition guides](#partition-guides) + {{< children type="anchored-list" >}} + +> [!Note] +> +> #### When to consider custom partitioning +> +> Consider custom partitioning if: +> +> 1. You have taken steps to [optimize your queries](/influxdb/version/query-data/troubleshoot-and-optimize/optimize-queries/), and +> 2. Performance for _single-series queries_ (querying for a specific [tag value](/influxdb/version/reference/glossary/#tag-value) or [tag set](/influxdb/version/reference/glossary/#tag-set)) is still unsatisfactory. +> +> Before choosing a partitioning strategy, weigh the [advantages](#advantages), [disadvantages](#disadvantages), and [limitations](#limitations) of custom partitioning. + +## Advantages + +The primary advantage of custom partitioning is that it lets you customize your +storage structure to improve query performance specific to your schema and workload. + +- **Optimized storage for improved performance on specific types of queries**. + For example, if queries often select data with a specific tag value, you can + partition by that tag to improve the performance of those queries. +- **Optimized storage for specific types of data**. For example, if the data you + store is sparse and the time ranges you query are often much larger than a day, + you could partition your data by month instead of by day. + +## Disadvantages + +Using custom partitioning may increase the load on other parts of the +[InfluxDB v3 storage engine](/influxdb/version/reference/internals/storage-engine/), +but you can scale each part individually to address the added load. + +{{% note %}} +_The weight of these disadvantages depends upon the cardinality of + tags and the specificity of time intervals used for partitioning._ +{{% /note %}} + +- **Increased load on the [Ingester](/influxdb/version/reference/internals/storage-engine/#ingester)** + as it groups data into smaller partitions and files. +- **Increased load on the [Catalog](/influxdb/version/reference/internals/storage-engine/#catalog)** + as more references to partition Parquet file locations are stored and queried. +- **Increased load on the [Compactor](/influxdb/version/reference/internals/storage-engine/#compactor)** + as it needs to compact more partition Parquet files. +- **Increased costs associated with [Object storage](/influxdb/version/reference/internals/storage-engine/#object-storage)** + as more partition Parquet files are created and stored. +- **Increased latency**. The amount of time for InfluxDB to process a query and return results increases linearly, although slightly, with the total partition count for a table. +- **Risk of decreased performance for queries that don't use tags in the WHERE clause**. + These queries might read many partitions and smaller files, which can degrade performance. + +## Limitations + +Custom partitioning has the following limitations: + +- Define database and table partitions only during creation; you can't update the partition strategy afterward. +- Include a time part in a partition template. +- You can partition by up to eight dimensions (seven tags and a time interval). + +## Plan for custom partitioning + +After you have considered the [advantages](#advantages), [disadvantages](#disadvantages), and [limitations](#limitations) of +custom partitioning, use the guides in this section to: + +1. Learn [how partitioning works](#how-partitioning-works) +2. Follow [best practices](/influxdb/version/admin/custom-partitions/best-practices/) for defining partitions and managing partition + growth +3. [Define custom partitions](/influxdb/version/admin/custom-partitions/define-custom-partitions/) for your data +4. Take steps to [limit the number of partition files](/influxdb/version/admin/custom-partitions/best-practices/#limit-the-number-of-partition-files) + +## How partitioning works + +### Partition templates + +A partition template defines the pattern used for _[partition keys](#partition-keys)_ +and determines the time interval that InfluxDB partitions data by. +Partition templates use tag values and +[Rust strftime date and time formatting syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). + +_For more detailed information, see [Partition templates](/influxdb/version/admin/custom-partitions/partition-templates/)._ + +### Partition keys + +A partition key uniquely identifies a partition. +A _[partition template](#partition-templates)_ defines the partition key format. +Partition keys are +composed of up to 8 dimensions (1 time part and up to 7 tag or tag bucket parts). +A partition key uses the partition key separator (`|`) to delimit parts. + +The default format for partition keys is `%Y-%m-%d` (for example, `2024-01-01`), +which creates 1 partition for each day. + +{{< expand-wrapper >}} +{{% expand "View example partition templates and keys" %}} + +Given the following line protocol with the following timestamps: + +- 2023-12-31T23:00:00Z +- 2024-01-01T00:00:00Z +- 2024-01-01T01:00:00Z + +```text +production,line=A,station=cnc temp=81.2,qty=35i 1704063600000000000 +production,line=A,station=wld temp=92.8,qty=35i 1704063600000000000 +production,line=B,station=cnc temp=101.1,qty=43i 1704063600000000000 +production,line=B,station=wld temp=102.4,qty=43i 1704063600000000000 +production,line=A,station=cnc temp=81.9,qty=36i 1704067200000000000 +production,line=A,station=wld temp=110.0,qty=22i 1704067200000000000 +production,line=B,station=cnc temp=101.8,qty=44i 1704067200000000000 +production,line=B,station=wld temp=105.7,qty=44i 1704067200000000000 +production,line=A,station=cnc temp=82.2,qty=35i 1704070800000000000 +production,line=A,station=wld temp=92.1,qty=30i 1704070800000000000 +production,line=B,station=cnc temp=102.4,qty=43i 1704070800000000000 +production,line=B,station=wld temp=106.5,qty=43i 1704070800000000000 +``` + +--- + +{{% flex %}} + + + +{{% flex-content "half" %}} + +##### Partition template parts + +- `%Y-%m-%d` time (by day, default format) + +{{% /flex-content %}} +{{% flex-content %}} + +##### Partition keys + +- `2023-12-31` +- `2024-01-01` + +{{% /flex-content %}} + + + +{{% /flex %}} + +--- + +{{% flex %}} + + + +{{% flex-content "half" %}} + +##### Partition template parts + +- `line` tag +- `%d %b %Y` time (by day, non-default format) + +{{% /flex-content %}} +{{% flex-content %}} + +##### Partition keys + +- `A | 31 Dec 2023` +- `B | 31 Dec 2023` +- `A | 01 Jan 2024` +- `B | 01 Jan 2024` + +{{% /flex-content %}} + + + +{{% /flex %}} + +--- + +{{% flex %}} + + + +{{% flex-content "half" %}} + +##### Partition template parts + +- `line` tag +- `station` tag +- `%Y-%m-%d` time (by day, default format) + +{{% /flex-content %}} +{{% flex-content %}} + +##### Partition keys + +- `A | cnc | 2023-12-31` +- `A | wld | 2023-12-31` +- `B | cnc | 2023-12-31` +- `B | wld | 2023-12-31` +- `A | cnc | 2024-01-01` +- `A | wld | 2024-01-01` +- `B | cnc | 2024-01-01` +- `B | wld | 2024-01-01` + +{{% /flex-content %}} + + + +{{% /flex %}} + +--- + +{{% flex %}} + + + +{{% flex-content "half" %}} + +##### Partition template parts + +- `line` tag +- `station,3` tag bucket +- `%Y-%m-%d` time (by day, default format) + +{{% /flex-content %}} +{{% flex-content %}} + +##### Partition keys + +- `A | 0 | 2023-12-31` +- `B | 0 | 2023-12-31` +- `A | 0 | 2024-01-01` +- `B | 0 | 2024-01-01` + +{{% /flex-content %}} + + + +{{% /flex %}} + +--- + +{{% flex %}} + + + +{{% flex-content "half" %}} + +##### Partition template parts + +- `line` tag +- `station` tag +- `%Y-%m` time (by month) + +{{% /flex-content %}} +{{% flex-content %}} + +##### Partition keys + +- `A | cnc | 2023-12` +- `A | wld | 2023-12` +- `B | cnc | 2023-12` +- `B | wld | 2023-12` +- `A | cnc | 2024-01` +- `A | wld | 2024-01` +- `B | cnc | 2024-01` +- `B | wld | 2024-01` + +{{% /flex-content %}} + + + +{{% /flex %}} + +--- + +{{% flex %}} + + + +{{% flex-content "half" %}} + +##### Partition template parts + +- `line` tag +- `station,50` tag bucket +- `%Y-%m` time (by month) + +{{% /flex-content %}} +{{% flex-content %}} + +##### Partition keys + +- `A | 47 | 2023-12` +- `A | 9 | 2023-12` +- `B | 47 | 2023-12` +- `B | 9 | 2023-12` +- `A | 47 | 2024-01` +- `A | 9 | 2024-01` +- `B | 47 | 2024-01` +- `B | 9 | 2024-01` + +{{% /flex-content %}} + + + +{{% /flex %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Partitions in the query life cycle + +When querying data: + +1. The [Catalog](/influxdb/version/reference/internals/storage-engine/#catalog) + provides the v3 query engine ([Querier](/influxdb/version/reference/internals/storage-engine/#querier)) + with the locations of partitions that contain the queried time series data. +2. The query engine reads all rows in the returned partitions to identify what + rows match the logic in the query and should be included in the query result. + +The faster the query engine can identify what partitions to read and then read +the data in those partitions, the more performant queries are. + +_For more information about the query lifecycle, see +[InfluxDB v3 query life cycle](/influxdb/version/reference/internals/storage-engine/#query-life-cycle)._ + +##### Query example + +Consider the following query that selects everything in the `production` table +where the `line` tag is `A` and the `station` tag is `cnc`: + +```sql +SELECT * +FROM production +WHERE + time >= now() - INTERVAL '1 week' + AND line = 'A' + AND station = 'cnc' +``` + +Using the default partitioning strategy (by day), the query engine +reads eight separate partitions (one partition for today and one for each of the +last seven days): + +- {{< datetime/current-date trimTime=true >}} +- {{< datetime/current-date offset=-1 trimTime=true >}} +- {{< datetime/current-date offset=-2 trimTime=true >}} +- {{< datetime/current-date offset=-3 trimTime=true >}} +- {{< datetime/current-date offset=-4 trimTime=true >}} +- {{< datetime/current-date offset=-5 trimTime=true >}} +- {{< datetime/current-date offset=-6 trimTime=true >}} +- {{< datetime/current-date offset=-7 trimTime=true >}} + +The query engine must scan _all_ rows in the partitions to identify rows +where `line` is `A` and `station` is `cnc`. This process takes valuable time +and results in less performant queries. + +However, including tags in your partitioning strategy allows the query engine to +identify partitions containing only the required tag values. +This avoids scanning rows for tag values. + +For example, if you partition data by `line`, `station`, and day, although +the number of files increases, the query engine can quickly identify and read +only those with data relevant to the query: + +{{% columns 4 %}} + +- A | cnc | {{< datetime/current-date trimTime=true >}} +- A | wld | {{< datetime/current-date trimTime=true >}} +- B | cnc | {{< datetime/current-date trimTime=true >}} +- B | wld | {{< datetime/current-date trimTime=true >}} +- A | cnc | {{< datetime/current-date offset=-1 trimTime=true >}} +- A | wld | {{< datetime/current-date offset=-1 trimTime=true >}} +- B | cnc | {{< datetime/current-date offset=-1 trimTime=true >}} +- B | wld | {{< datetime/current-date offset=-1 trimTime=true >}} +- A | cnc | {{< datetime/current-date offset=-2 trimTime=true >}} +- A | wld | {{< datetime/current-date offset=-2 trimTime=true >}} +- B | cnc | {{< datetime/current-date offset=-2 trimTime=true >}} +- B | wld | {{< datetime/current-date offset=-2 trimTime=true >}} +- A | cnc | {{< datetime/current-date offset=-3 trimTime=true >}} +- A | wld | {{< datetime/current-date offset=-3 trimTime=true >}} +- B | cnc | {{< datetime/current-date offset=-3 trimTime=true >}} +- B | wld | {{< datetime/current-date offset=-3 trimTime=true >}} +- A | cnc | {{< datetime/current-date offset=-4 trimTime=true >}} +- A | wld | {{< datetime/current-date offset=-4 trimTime=true >}} +- B | cnc | {{< datetime/current-date offset=-4 trimTime=true >}} +- B | wld | {{< datetime/current-date offset=-4 trimTime=true >}} +- A | cnc | {{< datetime/current-date offset=-5 trimTime=true >}} +- A | wld | {{< datetime/current-date offset=-5 trimTime=true >}} +- B | cnc | {{< datetime/current-date offset=-5 trimTime=true >}} +- B | wld | {{< datetime/current-date offset=-5 trimTime=true >}} +- A | cnc | {{< datetime/current-date offset=-6 trimTime=true >}} +- A | wld | {{< datetime/current-date offset=-6 trimTime=true >}} +- B | cnc | {{< datetime/current-date offset=-6 trimTime=true >}} +- B | wld | {{< datetime/current-date offset=-6 trimTime=true >}} +- A | cnc | {{< datetime/current-date offset=-7 trimTime=true >}} +- A | wld | {{< datetime/current-date offset=-7 trimTime=true >}} +- B | cnc | {{< datetime/current-date offset=-7 trimTime=true >}} +- B | wld | {{< datetime/current-date offset=-7 trimTime=true >}} + +{{% /columns %}} + +--- + +## Partition guides + +{{< children >}} diff --git a/content/shared/v3-distributed-admin-custom-partitions/best-practices.md b/content/shared/v3-distributed-admin-custom-partitions/best-practices.md new file mode 100644 index 000000000..d66afe901 --- /dev/null +++ b/content/shared/v3-distributed-admin-custom-partitions/best-practices.md @@ -0,0 +1,69 @@ +Use the following best practices when defining custom partitioning strategies +for your data stored in {{< product-name >}}. + +- [Partition by tags that you commonly query for a specific value](#partition-by-tags-that-you-commonly-query-for-a-specific-value) +- [Only partition by tags that _always_ have a value](#only-partition-by-tags-that-always-have-a-value) +- [Avoid over-partitioning](#avoid-over-partitioning) +- [Limit the number of partition files](#limit-the-number-of-partition-files) + - [Estimate the total partition count](#estimate-the-total-partition-count) + +## Partition by tags that you commonly query for a specific value + +Custom partitioning primarily benefits single series queries that look for a specific tag +value in the `WHERE` clause. +For example, if you often query data related to a +specific ID, partitioning by the tag that stores the ID helps the InfluxDB +query engine to more quickly identify what partitions contain the relevant data. + +{{% note %}} + +#### Use tag buckets for high-cardinality tags + +Partitioning using distinct values of tags with many (10K+) unique values can +actually hurt query performance as partitions are created for each unique tag value. +Instead, use [tag buckets](/influxdb/version/admin/custom-partitions/partition-templates/#tag-bucket-part-templates) +to partition by high-cardinality tags. +This method of partitioning groups tag values into "buckets" and partitions by bucket. +{{% /note %}} + +## Only partition by tags that _always_ have a value + +You should only partition by tags that _always_ have a value. +If points don't have a value for the tag, InfluxDB can't store them in the correct partitions and, at query time, must read all the partitions. + +## Avoid over-partitioning + +As you plan your partitioning strategy, keep in mind that over-partitioning your data can hurt query performance. If partitions are too granular, queries may need to retrieve and read many partitions from the [Object store](/influxdb/version/reference/internals/storage-engine/#object-store). + +- Balance the partition time interval with the actual amount of data written during each interval. If a single interval doesn't contain a lot of data, partition by larger time intervals. +- Avoid partitioning by tags that you typically don't use in your query workload. +- Avoid partitioning by distinct values of high-cardinality tags. Instead, [use tag buckets](#use-tag-buckets-for-high-cardinality-tags) to partition by these tags. + +## Limit the number of partition files + +Avoid exceeding **10,000** total partitions. +Limiting the total partition count can help manage system performance and costs. + +While planning your strategy, take the following steps to limit your total +partition count. +We currently recommend planning to keep the total partition count below 10,000. + +- [Estimate the total partition count](#estimate-the-total-partition-count) for the lifespan of your data +- **Set a [database retention period](/influxdb/version/admin/databases/#retention-period)** + to prevent the number of partitions from growing unbounded +- **Partition by month or year** to [avoid over-partitioning](#avoid-over-partitioning) +- **Don't partition on high cardinality tags** unless you also use [tag buckets](#use-tag-buckets-for-high-cardinality-tags) + +### Estimate the total partition count + +Use the following formula to estimate the total partition count over the +lifetime of the database (or retention period): + +```text +total_partition_count = (cardinality_of_partitioned_tag) * (data_lifespan / partition_duration) +``` + +- `total_partition_count`: The number of partition files in [Object storage](/influxdb/version/reference/internals/storage-engine/#object-storage) +- `cardinality_of_partitioned_tag`: The number of distinct values for a tag +- `data_lifespan`: The [database retention period](/influxdb/version/admin/databases/#retention-period), if set, or the expected lifetime of the database +- `partition_duration`: The partition time interval, defined by the [time part template](/influxdb/version/admin/custom-partitions/partition-templates/#time-part-templates) diff --git a/content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md b/content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md new file mode 100644 index 000000000..1676d2656 --- /dev/null +++ b/content/shared/v3-distributed-admin-custom-partitions/define-custom-partitions.md @@ -0,0 +1,156 @@ +Use the [`influxctl` CLI](/influxdb/version/reference/cli/influxctl/) +to define custom partition strategies when creating a database or table. +By default, {{< product-name >}} partitions data by day. + +The partitioning strategy of a database or table is determined by a +[partition template](/influxdb/version/admin/custom-partitions/#partition-templates) +which defines the naming pattern for [partition keys](/influxdb/version/admin/custom-partitions/#partition-keys). +Partition keys uniquely identify each partition. +When a partition template is applied to a database, it becomes the default template +for all tables in that database, but can be overridden when creating a +table. + +- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template) +- [Create a table with a custom partition template](#create-a-table-with-a-custom-partition-template) +- [Example partition templates](#example-partition-templates) + +{{% warn %}} + +#### Partition templates can only be applied on create + +You can only apply a partition template when creating a database or table. +You can't update a partition template on an existing resource. +{{% /warn %}} + +Use the following command flags to identify +[partition template parts](/influxdb/version/admin/custom-partitions/partition-templates/#tag-part-templates): + +- `--template-tag`: An [InfluxDB tag](/influxdb/version/reference/glossary/#tag) + to use in the partition template. +- `--template-tag-bucket`: An [InfluxDB tag](/influxdb/version/reference/glossary/#tag) + and number of "buckets" to group tag values into. + Provide the tag key and the number of buckets to bucket tag values into + separated by a comma: `tagKey,N`. +- `--template-timeformat`: A [Rust strftime date and time](/influxdb/version/admin/custom-partitions/partition-templates/#time-part-templates) + string that specifies the time format in the partition template and determines + the time interval to partition by. + +{{% note %}} +A partition template can include up to 7 total tag and tag bucket parts +and only 1 time part. +{{% /note %}} + +_View [partition template part restrictions](/influxdb/version/admin/custom-partitions/partition-templates/#restrictions)._ + +{{% note %}} +#### Always provide a time format when using custom partitioning + +When defining a custom partition template for your database or table using any +of the `influxctl` `--template-*` flags, always include the `--template-timeformat` +flag with a time format to use in your partition template. +Otherwise, InfluxDB omits time from the partition template and won't compact partitions. +{{% /note %}} + +## Create a database with a custom partition template + +The following example creates a new `example-db` database and applies a partition +template that partitions by distinct values of two tags (`room` and `sensor-type`), +bucketed values of the `customerID` tag, and by day using the time format `%Y-%m-%d`: + + + + +```sh +influxctl database create \ + --template-tag room \ + --template-tag sensor-type \ + --template-tag-bucket customerID,500 \ + --template-timeformat '%Y-%m-%d' \ + example-db +``` + +## Create a table with a custom partition template + +The following example creates a new `example-table` table in the specified +database and applies a partition template that partitions by distinct values of +two tags (`room` and `sensor-type`), bucketed values of the `customerID` tag, +and by month using the time format `%Y-%m`: + + + + +{{% code-placeholders "DATABASE_NAME" %}} + +```sh +influxctl table create \ + --template-tag room \ + --template-tag sensor-type \ + --template-tag-bucket customerID,500 \ + --template-timeformat '%Y-%m' \ + DATABASE_NAME \ + example-table +``` + +{{% /code-placeholders %}} + +Replace the following in your command: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [database](/influxdb/version/admin/databases/) + + + +## Example partition templates + +Given the following [line protocol](/influxdb/version/reference/syntax/line-protocol/) +with a `2024-01-01T00:00:00Z` timestamp: + +```text +prod,line=A,station=weld1 temp=81.9,qty=36i 1704067200000000000 +``` + +##### Partitioning by distinct tag values + +| Description | Tag parts | Time part | Resulting partition key | +| :---------------------- | :---------------- | :--------- | :----------------------- | +| By day (default) | | `%Y-%m-%d` | 2024-01-01 | +| By month | | `%Y-%m` | 2024-01 | +| By year | | `%Y` | 2024 | +| Single tag, by day | `line` | `%Y-%m-%d` | A \| 2024-01-01 | +| Single tag, by month | `line` | `%Y-%m` | A \| 2024-01 | +| Single tag, by year | `line` | `%Y` | A \| 2024 | +| Multiple tags, by day | `line`, `station` | `%Y-%m-%d` | A \| weld1 \| 2024-01-01 | +| Multiple tags, by month | `line`, `station` | `%Y-%m` | A \| weld1 \| 2024-01 | +| Multiple tags, by year | `line`, `station` | `%Y` | A \| weld1 \| 2024 | + +##### Partition by tag buckets + +| Description | Tag part | Tag bucket part | Time part | Resulting partition key | +| :---------------------------------- | :------- | :-------------- | :--------- | :---------------------- | +| Distinct tag, tag buckets, by day | `line` | `station,100` | `%Y-%m-%d` | A \| 3 \| 2024-01-01 | +| Distinct tag, tag buckets, by month | `line` | `station,500` | `%Y-%m` | A \| 303 \| 2024-01 | diff --git a/content/shared/v3-distributed-admin-custom-partitions/partition-templates.md b/content/shared/v3-distributed-admin-custom-partitions/partition-templates.md new file mode 100644 index 000000000..3fa748d40 --- /dev/null +++ b/content/shared/v3-distributed-admin-custom-partitions/partition-templates.md @@ -0,0 +1,124 @@ +Use partition templates to define the patterns used to generate partition keys. +A partition key uniquely identifies a partition and is used to name the partition +Parquet file in the [Object store](/influxdb/version/reference/internals/storage-engine/#object-store). + +A partition template consists of 1-8 _template parts_---dimensions to partition data by. +Three types of template parts exist: + +- **tag**: An [InfluxDB tag](/influxdb/version/reference/glossary/#tag) + to partition by. +- **tag bucket**: An [InfluxDB tag](/influxdb/version/reference/glossary/#tag) + and number of "buckets" to group tag values into. Data is partitioned by the + tag bucket rather than each distinct tag value. +- {{< req type="key" >}} **time**: A Rust strftime date and time string that specifies the time interval + to partition data by. The smallest unit of time included in the time part + template is the interval used to partition data. + +{{% note %}} +A partition template must include 1 [time part](#time-part-templates) +and can include up to 7 total [tag](#tag-part-templates) and [tag bucket](#tag-bucket-part-templates) parts. +{{% /note %}} + + +- [Restrictions](#restrictions) + - [Template part size limit](#template-part-size-limit) + - [Reserved keywords](#reserved-keywords) + - [Reserved Characters](#reserved-characters) +- [Tag part templates](#tag-part-templates) +- [Tag bucket part templates](#tag-bucket-part-templates) +- [Time part templates](#time-part-templates) + + +## Restrictions + +### Template part size limit + +Each template part is limited to 200 bytes in length. +Anything longer will be truncated at 200 bytes and appended with `#`. + +### Partition key size limit + +With the truncation of template parts, the maximum length of a partition key is +1,607 bytes (1.57 KiB). + +### Reserved keywords + +The following reserved keywords cannot be used in partition templates: + +- `time` + +### Reserved Characters + +If used in template parts, non-ASCII characters and the following reserved +characters must be [percent encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding): + +- `|`: Partition key part delimiter +- `!`: Null or missing partition key part +- `^`: Empty string partition key part +- `#`: Key part truncation marker +- `%`: Required for unambiguous reversal of percent encoding + +## Tag part templates + +Tag part templates consist of a _tag key_ to partition by. +Generated partition keys include the unique _tag value_ specific to each partition. + +A partition template may include a given tag key only once in template parts +that operate on tags (tag value and tag bucket)--for example: + +If a template partitions on unique values of `tag_A`, then +you can't use `tag_A` as a tag bucket part. + +## Tag bucket part templates + +Tag bucket part templates consist of a _tag key_ to partition by and the +_number of "buckets" to partition tag values into_--for example: + +``` +customerID,500 +``` + +Values of the `customerID` tag are bucketed into 500 distinct "buckets." +Each bucket is identified by the remainder of the tag value hashed into a 32-bit +integer divided by the specified number of buckets: + +```rust +hash(tagValue) % N +``` + +Generated partition keys include the unique _tag bucket identifier_ specific to +each partition. + +**Supported number of tag buckets**: 1-1,000 + +{{% note %}} +Tag buckets should be used to partition by high cardinality tags or tags with an +unknown number of distinct values. +{{% /note %}} + +A partition template may include a given tag key only once in template parts +that operate on tags (tag value and tag bucket)--for example: + +If a template partitions on unique values of `tag_A`, then +you can't use `tag_A` as a tag bucket part. + +## Time part templates + +Time part templates use a limited subset of the +[Rust strftime date and time formatting syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +to specify time format in partition keys. +Time part templates can be daily (`%Y-%m-%d`), monthly (`%Y-%m`), or yearly (`%Y`). +InfluxDB partitions data by the smallest unit of time included in the time part +template. + +InfluxDB supports only [date specifiers](#date-specifiers) in time part templates. + +### Date specifiers + +Time part templates allow only the following date specifiers: + +| Variable | Example | Description | +| :------: | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `%Y` | `2001` | The full proleptic Gregorian year, zero-padded to 4 digits. chrono supports years from -262144 to 262143. Note: years before 1 BCE or after 9999 CE, require an initial sign (+/-). | +| `%m` | `07` | Month number (01--12), zero-padded to 2 digits. | +| `%d` | `08` | Day number (01--31), zero-padded to 2 digits. | diff --git a/content/shared/v3-distributed-admin-custom-partitions/view-partitions.md b/content/shared/v3-distributed-admin-custom-partitions/view-partitions.md new file mode 100644 index 000000000..f0097583f --- /dev/null +++ b/content/shared/v3-distributed-admin-custom-partitions/view-partitions.md @@ -0,0 +1,169 @@ + +{{< product-name >}} stores partition information in InfluxDB v3 system tables. +Query partition information to view partition templates and verify partitions +are working as intended. + +- [Query partition information from system tables](#query-partition-information-from-system-tables) +- [Partition-related queries](#partition-related-queries) + +{{% warn %}} +#### Querying system tables may impact overall cluster performance + +Partition information is stored in InfluxDB v3 system tables. +Querying system tables may impact the overall write and query performance of +your {{< product-name omit=" Clustered" >}} cluster. + + + +#### System tables are subject to change + +System tables are not part of InfluxDB's stable API and may change with new releases. +The provided schema information and query examples are valid as of **September 24, 2024**. +If you detect a schema change or a non-functioning query example, please +[submit an issue](https://github.com/influxdata/docs-v2/issues/new/choose). + + + +{{% /warn %}} + +## Query partition information from system tables + +Use the [`influxctl query` command](/influxdb/version/reference/cli/influxctl/query/) +and SQL to query partition-related information from InfluxDB system tables. + Provide the following: + +- **Enable system tables** with the `--enable-system-tables` command flag. +- **Database token**: A [database token](/influxdb/version/admin/tokens/#database-tokens) + with read permissions on the specified database. Uses the `token` setting from + the [`influxctl` connection profile](/influxdb/version/reference/cli/influxctl/#configure-connection-profiles) + or the `--token` command flag. +- **Database name**: The name of the database to query information about. + Uses the `database` setting from the + [`influxctl` connection profile](/influxdb/version/reference/cli/influxctl/#configure-connection-profiles) + or the `--database` command flag. +- **SQL query**: The SQL query to execute. + Pass the query in one of the following ways: + + - a string on the command line + - a path to a file that contains the query + - a single dash (`-`) to read the query from stdin + +{{% code-placeholders "DATABASE_(TOKEN|NAME)|SQL_QUERY" %}} + +```bash +influxctl query \ + --enable-system-tables \ + --database DATABASE_NAME \ + --token DATABASE_TOKEN \ + "SQL_QUERY" +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: + A database token with read access to the specified database +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + The name of the database to query information about. +- {{% code-placeholder-key %}}`SQL_QUERY`{{% /code-placeholder-key %}}: + The SQL query to execute. For examples, see + [System query examples](#system-query-examples). + +When prompted, enter `y` to acknowledge the potential impact querying system +tables may have on your cluster. + +## Partition-related queries + +Use the following queries to return information about partitions in your +{{< product-name omit=" Clustered" >}} cluster. + +- [View partition templates of all tables](#view-partition-templates-of-all-tables) +- [View the partition template of a specific table](#view-the-partition-template-of-a-specific-table) +- [View all partitions for a table](#view-all-partitions-for-a-table) +- [View the number of partitions per table](#view-the-number-of-partitions-per-table) +- [View the number of partitions for a specific table](#view-the-number-of-partitions-for-a-specific-table) + +--- + +In the examples below, replace {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}} +with the name of the table you want to query information about. + +--- + +{{% code-placeholders "TABLE_NAME_(1|2|3)|TABLE_NAME" %}} + +### View the partition template of a specific table + +```sql +SELECT * FROM system.tables WHERE table_name = 'TABLE_NAME' +``` + +#### Example results + +| table_name | partition_template | +| :--------- | :----------------------------------------------------------------------------------------- | +| weather | `{"parts":[{"timeFormat":"%Y-%m-%d"},{"bucket":{"tagName":"location","numBuckets":250}}]}` | + +{{% note %}} +If a table doesn't include a partition template in the output of this command, +the table uses the default (1 day) partition strategy and doesn't partition +by tags or tag buckets. +{{% /note %}} + +### View all partitions for a table + +```sql +SELECT * FROM system.partitions WHERE table_name = 'TABLE_NAME' +``` + +### Example results + +| partition_id | table_name | partition_key | last_new_file_created_at | num_files | total_size_mb | +| -----------: | :--------- | :---------------- | -----------------------: | --------: | ------------: | +| 1362 | weather | 43 \| 2020-05-27 | 1683747418763813713 | 1 | 0 | +| 800 | weather | 234 \| 2021-08-02 | 1683747421899400796 | 1 | 0 | +| 630 | weather | 325 \| 2022-03-17 | 1683747417616689036 | 1 | 0 | +| 1401 | weather | 12 \| 2021-01-09 | 1683747417786122295 | 1 | 0 | +| 1012 | weather | 115 \| 2022-07-04 | 1683747417614219148 | 1 | 0 | + +### View the number of partitions per table + +```sql +SELECT + table_name, + COUNT(*) AS partition_count +FROM + system.partitions +WHERE + table_name IN ('TABLE_NAME_1', 'TABLE_NAME_2', 'TABLE_NAME_3') +GROUP BY + table_name +``` + +### Example results + +| table_name | partition_count | +| :--------- | --------------: | +| weather | 1096 | +| home | 24 | +| numbers | 1 | + +### View the number of partitions for a specific table + +```sql +SELECT + COUNT(*) AS partition_count +FROM + system.partitions +WHERE + table_name = 'TABLE_NAME' +``` + +### Example results + +| table_name | partition_count | +| :--------- | --------------: | +| weather | 1096 | + +{{% /code-placeholders %}} diff --git a/content/telegraf/v1/_index.md b/content/telegraf/v1/_index.md index 0a4ca612d..13e4089b7 100644 --- a/content/telegraf/v1/_index.md +++ b/content/telegraf/v1/_index.md @@ -5,7 +5,7 @@ description: > time series platform, used to collect and report metrics. Telegraf supports four categories of plugins -- input, output, aggregator, and processor. menu: telegraf_v1: - name: Telegraf v1.31 + name: Telegraf v1.32 weight: 1 related: - /resources/videos/intro-to-telegraf/ diff --git a/content/telegraf/v1/configuration.md b/content/telegraf/v1/configuration.md index efe742c27..3485c8778 100644 --- a/content/telegraf/v1/configuration.md +++ b/content/telegraf/v1/configuration.md @@ -22,22 +22,105 @@ See [Get started](/telegraf/v1/get_started/) to quickly get up and running with ## Generate a configuration file -A default Telegraf configuration file can be auto-generated by Telegraf: +The `telegraf config` command lets you generate a configuration file using Telegraf's list of plugins. -``` +- [Create a configuration with default input and output plugins](#create-a-configuration-with-default-input-and-output-plugins) +- [Create a configuration with specific input and output plugins](#create-a-configuration-with-specific-input-and-output-plugins) + +### Create a configuration with default input and output plugins + +To generate a configuration file with default input and output plugins enabled, +enter the following command in your terminal: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Linux and macOS](#) +[Windows](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```bash telegraf config > telegraf.conf ``` - -To generate a configuration file with specific inputs and outputs, you can use the -`--input-filter` and `--output-filter` flags: - +{{% /code-tab-content %}} +{{% code-tab-content %}} +```powershell +.\telegraf.exe config > telegraf.conf ``` -telegraf --input-filter cpu:mem:net:swap --output-filter influxdb:kafka config +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +The generated file contains settings for all available plugins--some are enabled and the rest are commented out. + +### Create a configuration file with specific input and output plugins + +To generate a configuration file that contains settings for only specific plugins, +use the `--input-filter` and `--output-filter` options to +specify [input plugins](/telegraf/v1/plugins/input_plugins) +and [output plugins](/telegraf/v1/plugins/output_plugins/). +Use a colon (`:`) to separate plugin names. + +#### Syntax + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Linux and macOS](#) +[Windows](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```bash +telegraf \ +--input-filter [:] \ +--output-filter [:] \ +config > telegraf.conf ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```powershell +.\telegraf.exe ` +--input-filter [:] ` +--output-filter [:] ` +config > telegraf.conf +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +#### Example + +The following example shows how to include configuration sections for the +[`inputs.cpu`](/telegraf/v1/plugins/#input-cpu), +[`inputs.http_listener_v2`](/telegraf/v1/plugins/#input-http_listener_v2), +[`outputs.influxdb_v2`](/telegraf/v1/plugins/#output-influxdb_v2), and +[`outputs.file`](/telegraf/v1/plugins/#output-file) plugins: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Linux and macOS](#) +[Windows](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```bash +telegraf \ +--input-filter cpu:http_listener_v2 \ +--output-filter influxdb_v2:file \ +config > telegraf.conf +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```powershell +.\telegraf.exe ` +--input-filter cpu:http_listener_v2 ` +--output-filter influxdb_v2:file ` +config > telegraf.conf +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +For more advanced configuration details, see the +[configuration documentation](/telegraf/v1/administration/configuration/). ## Configuration file locations -Use the `--config` flag to specify the configuration file location: +When starting Telegraf, use the `--config` flag to specify the configuration file location: - Filename and path, for example: `--config /etc/default/telegraf` - Remote URL endpoint, for example: `--config "http://remote-URL-endpoint"` @@ -46,9 +129,56 @@ Use the `--config-directory` flag to include files ending with `.conf` in the specified directory in the Telegraf configuration. On most systems, the default locations are `/etc/telegraf/telegraf.conf` for -the main configuration file and `/etc/telegraf/telegraf.d` for the directory of +the main configuration file and `/etc/telegraf/telegraf.d` (on Windows, `C:\"Program Files"\Telegraf\telegraf.d`) for the directory of configuration files. +Telegraf processes each configuration file separately, and +the effective configuration is the union of all the files. +If any file isn't a valid configuration, Telegraf returns an error. + +{{% warn %}} + +#### Telegraf doesn't support partial configurations + +Telegraf doesn't concatenate configuration files before processing them. +Each configuration file that you provide must be a valid configuration. + +If you want to use separate files to manage a configuration, you can use your +own custom code to concatenate and pre-process the files, and then provide the +complete configuration to Telegraf--for example: + +1. Configure plugin sections and assign partial configs a file extension different + from `.conf` to prevent Telegraf loading them--for example: + + ```toml + # main.opcua: Main configuration file + ... + [[inputs.opcua_listener]] + name = "PluginSection" + endpoint = "opc.tcp://10.0.0.53:4840" + ... + ``` + + ```toml + # group_1.opcua + [[inputs.opcua_listener.group]] + name = "SubSection1" + ... + ``` + + ```toml + # group_2.opcua + [[inputs.opcua_listener.group]] + name = "SubSection2" + ... + ``` + +2. Before you start Telegraf, run your custom script to concatenate `main.opcua`, `group_1.opcua`, + `group_2.opcua` into a valid `telegraf.conf`. +3. Start Telegraf with the complete, valid `telegraf.conf` configuration. + +{{% /warn %}} + ## Set environment variables Use environment variables anywhere in the configuration file by enclosing them in `${}`. @@ -63,6 +193,8 @@ You can also set environment variables using the Linux `export` command: `export Set environment variables in the Telegraf environment variables file (`/etc/default/telegraf`)--for example: + + ```sh USER="alice" INFLUX_URL="http://localhost:8086" @@ -72,7 +204,7 @@ INFLUX_PASSWORD="monkey123" In the Telegraf configuration file (`/etc/telegraf.conf`), reference the variables--for example: -```sh +```toml [global_tags] user = "${USER}" @@ -86,7 +218,7 @@ In the Telegraf configuration file (`/etc/telegraf.conf`), reference the variabl When Telegraf runs, the effective configuration is the following: -```sh +```toml [global_tags] user = "alice" @@ -94,7 +226,6 @@ When Telegraf runs, the effective configuration is the following: urls = "http://localhost:8086" skip_database_creation = true password = "monkey123" - ``` ## Global tags diff --git a/content/telegraf/v1/configure_plugins/input_plugins/_index.md b/content/telegraf/v1/configure_plugins/input_plugins/_index.md index 516dce22c..257a61913 100644 --- a/content/telegraf/v1/configure_plugins/input_plugins/_index.md +++ b/content/telegraf/v1/configure_plugins/input_plugins/_index.md @@ -12,6 +12,6 @@ menu: Telegraf input plugins are used with the InfluxData time series platform to collect metrics from the system, services, or third-party APIs. All metrics are gathered from the inputs you enable and configure in the [Telegraf configuration file](/telegraf/v1/configuration/). -For a complete list of input plugins and links to their detailed configuration options, see [input plugins](/telegraf/v1/plugins/inputs/). +For a complete list of input plugins and links to their detailed configuration options, see [input plugins](/telegraf/v1/plugins/#input-plugins). In addition to plugin-specific data formats, Telegraf supports a set of [common data formats](/telegraf/v1/data_formats/input/) available when configuring many of the Telegraf input plugins. diff --git a/content/telegraf/v1/configure_plugins/output_plugins/_index.md b/content/telegraf/v1/configure_plugins/output_plugins/_index.md index 9128a306f..f6f8019e9 100644 --- a/content/telegraf/v1/configure_plugins/output_plugins/_index.md +++ b/content/telegraf/v1/configure_plugins/output_plugins/_index.md @@ -11,6 +11,6 @@ menu: --- Output plugins define where Telegraf will deliver the collected metrics. Send metrics to InfluxDB or to a variety of other datastores, services, and message queues, including Graphite, OpenTSDB, Datadog, Librato, Kafka, MQTT, and NSQ. -For a complete list of output plugins and links to their detailed configuration options, see [output plugins](/telegraf/v1/plugins/outputs/). +For a complete list of output plugins and links to their detailed configuration options, see [output plugins](/telegraf/v1/plugins/#output-plugins). In addition to plugin-specific data formats, Telegraf supports a set of [common data formats](/telegraf/v1/data_formats/output/) available when configuring many of the Telegraf output plugins. diff --git a/content/telegraf/v1/install.md b/content/telegraf/v1/install.md index 696663572..b812ec401 100644 --- a/content/telegraf/v1/install.md +++ b/content/telegraf/v1/install.md @@ -13,32 +13,10 @@ aliases: This page provides directions for installing, starting, and configuring Telegraf. To install Telegraf, do the following: -- [Download Telegraf](#download) - [Review requirements](#requirements) -- [Complete the installation](#installation) +- [Download and install Telegraf](#download-and-install-telegraf) - [Custom compile Telegraf](#custom-compile) -## Download - -Download the latest Telegraf release at the [InfluxData download page](https://www.influxdata.com/downloads/). - -### Verify Linux releases using GPG - -InfluxData uses [GPG (GnuPG)](https://www.gnupg.org/software/) to sign released software and provides -public key and encrypted private key (`.key` file) pairs that you can use to verify the integrity of downloads from the InfluxData repository. - -Before running the [install](#install) sample code, substitute the key-pair compatible with your OS version: - -For newer OS releases (for example, Ubuntu 20.04 LTS and newer) that support subkey verification: - -- Private key file: `influxdata-archive.key` -- Public key: `943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515` - -For all Ubuntu and Debian versions, including older versions (for example, CentOS/RHEL 7, Ubuntu 18.04 LTS, or Debian Buster) that don't support subkeys for verification: - -- Private key file: `influxdata-archive_compat.key` -- Public key: `393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c` - ## Requirements Installation of the Telegraf package may require `root` or administrator privileges to complete successfully. @@ -60,7 +38,109 @@ Telegraf uses a host's local time in UTC to assign timestamps to data. Use the Network Time Protocol (NTP) to synchronize time between hosts. If hosts' clocks aren't synchronized with NTP, the timestamps on the data might be inaccurate. -## Install +## Download and install Telegraf + + + +{{< req text="Recommended:" color="magenta" >}}: Before you open and install packages and downloaded files, use SHA +checksum verification and GPG signature verification to ensure the files are +intact and authentic. + +SHA checksum and GPG signature verification are complementary checks. + +_For some Linux platforms, the [installation instructions](#download-and-install-instructions) include steps to verify downloaded packages and binaries._ + +For more information, see the following: + +{{< expand-wrapper >}} +{{% expand "Verify download integrity using SHA-256" %}} + +For each released binary, InfluxData publishes the SHA checksum that +you can use to verify that the downloaded file is intact and hasn't been corrupted. + +To use the SHA checksum to verify the downloaded file, do the following: + +1. In the [downloads page](https://www.influxdata.com/downloads), + select the **Version** and **Platform** for your download, and then copy + the SHA256 checksum for the file. + +2. Compute the SHA checksum of the downloaded file and compare it to the + checksum you copied in the preceding step--for example, enter the following + command in your terminal. + +### Syntax + + + +{{% code-placeholders "" %}} + +```bash +# Use 2 spaces to separate the checksum from the filename +echo " telegraf-{{% latest-patch %}}_linux_amd64.tar.gz" \ +| sha256sum -c - +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}``{{% /code-placeholder-key %}}: + the **SHA256:** checksum value that you copied from the downloads page + +### Example + +The following sample code uses `curl` to download Telegraf, and then +uses `sha256` to compare it to the checksum: + +{{% code-placeholders "260bc3170dbd6cce67575c1215a0b89b8447945106e2943d74e617d06b750c03" %}} + +```bash +curl -s --location -O \ +"https://dl.influxdata.com/telegraf/releases/telegraf-${telegraf_latest_patches_v1}_linux_amd64.tar.gz" +echo "260bc3170dbd6cce67575c1215a0b89b8447945106e2943d74e617d06b750c03 telegraf-${telegraf_latest_patches_v1}_linux_amd64.tar.gz" \ +| sha256sum -c - +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`260bc3170dbd6cce67575c1215a0b89b8447945106e2943d74e617d06b750c03`{{% /code-placeholder-key %}}: + the **SHA256:** checksum value that you copied from the downloads page + +If the checksums match, the output is the following; otherwise, an error message. + +``` +telegraf-{{% latest-patch %}}_linux_amd64.tar.gz: OK +``` + +{{% /expand %}} +{{% expand "Verify file integrity and authenticity using GPG" %}} + +InfluxData uses [GPG (GnuPG)](https://www.gnupg.org/software/) to sign released software and provides +public key and encrypted private key (`.key` file) pairs that you can use to +verify the integrity of packages and binaries from the InfluxData repository. + +Before running the [install](#install) sample code, substitute the key-pair compatible with your OS version: + +For newer OS releases (for example, Ubuntu 20.04 LTS and newer, Debian Buster +and newer) that support subkey verification: + +- Private key file: [`influxdata-archive.key`](https://repos.influxdata.com/influxdata-archive.key) +- Public key: `943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515` + +For older versions (for example, CentOS/RHEL 7, Ubuntu 18.04 LTS, or Debian +Stretch) that don't support subkeys for verification: + +- Private key file: [`influxdata-archive_compat.key`](https://repos.influxdata.com/influxdata-archive_compat.key) +- Public key: `393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c` + +_For security, InfluxData periodically rotates keys and publishes the new key pairs._ + +{{% /expand %}} +{{< /expand-wrapper >}} + + {{< tabs-wrapper >}} {{% tabs style="even-wrap" %}} @@ -68,56 +148,78 @@ aren't synchronized with NTP, the timestamps on the data might be inaccurate. [RedHat & CentOS](#) [SLES & openSUSE](#) [FreeBSD/PC-BSD](#) + [Linux binaries (AMD)](#) + [Linux binaries (ARM)](#) [macOS](#) [Windows](#) {{% /tabs %}} {{% tab-content %}} -Debian and Ubuntu users can install the latest stable version of Telegraf using the `apt-get` package manager. +Debian and Ubuntu users can install the latest stable version of Telegraf using +the `apt-get` package manager. - [Install from the InfluxData repository](#install-from-the-influxdata-repository) - [Install from a `.deb` file](#install-from-a-deb-file) -#### Install from the InfluxData repository +### Install from the InfluxData repository -Run the following commands using `apt-get` to install Telegraf from the InfluxData repository: +Run the following commands using `apt-get` to install Telegraf from the InfluxData +repository: {{< code-tabs-wrapper >}} {{% code-tabs %}} -[All versions](#) [Ubuntu 20.04 LTS and newer](#) +[Older than Ubuntu 20.04](#) {{% /code-tabs %}} - {{% code-tab-content %}} + + +```bash +curl --silent --location -O \ +https://repos.influxdata.com/influxdata-archive.key \ +&& echo "943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515 influxdata-archive.key" \ +| sha256sum -c - && 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 +sudo apt-get update && sudo apt-get install telegraf +``` + + +{{% /code-tab-content %}} +{{% code-tab-content %}} + + ```bash # influxdata-archive_compat.key GPG Fingerprint: 9D539D90D3328DC7D6C8D3B9D8FF8E1F7DF8B07E -curl -s https://repos.influxdata.com/influxdata-archive_compat.key > influxdata-archive_compat.key -echo '393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influxdata-archive_compat.key' | sha256sum -c && cat influxdata-archive_compat.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg > /dev/null -echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list +curl --silent --location -O \ +https://repos.influxdata.com/influxdata-archive_compat.key \ +&& echo "393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influxdata-archive_compat.key" \ +| sha256sum -c - \ +&& cat influxdata-archive_compat.key \ +| gpg --dearmor \ +| sudo tee /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg > /dev/null +echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.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 telegraf ``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```bash -curl -s https://repos.influxdata.com/influxdata-archive.key > influxdata-archive.key -echo '943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515 influxdata-archive.key' | sha256sum -c && 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 -sudo apt-get update && sudo apt-get install telegraf -``` + {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} -#### Install from a `.deb` file +### Install from a `.deb` file To manually install the Debian package from a `.deb` file: 1. Download the latest Telegraf `.deb` release - from the Telegraf section of the [downloads page](https://influxdata.com/downloads/). -2. Run the following command (making sure to supply the correct version number for the downloaded file): + from the [downloads page](https://influxdata.com/downloads/#telegraf). +2. Run the following command (making sure to supply the correct version number + for the downloaded file): - ```sh - sudo dpkg -i telegraf_{{< latest-patch >}}-1_amd64.deb + ```bash + sudo dpkg -i telegraf_{{% latest-patch %}}-1_amd64.deb ``` {{% /tab-content %}} @@ -129,22 +231,28 @@ To use the `yum` package manager to install the latest stable version of Telegra 1. In your terminal, enter the following command to add the InfluxData repository to the `yum` configuration: - ```bash - cat < + -2. Enter the following command to install `telegraf` from the repository. + ```bash + cat < + + + ```bash + sudo yum install telegraf + ``` The `telegraf` configuration file is installed at `/etc/telegraf/telegraf.conf`. @@ -155,19 +263,23 @@ The openSUSE Build Service provides RPM packages for SUSE Linux. To use the `zypper` package manager to install the latest stable version of Telegraf, follow these steps: -1. In your terminal, enter the following command to add the Go repository to the `zypper` configuration: +1. In your terminal, enter the following command to add the Go repository to the `zypper` configuration: - ```bash - # add go repository - zypper ar -f obs://devel:languages:go/ go - ``` + -2. Enter the following command to install `telegraf`. + ```bash + # add go repository + zypper ar -f obs://devel:languages:go/ go + ``` - ```bash - # install latest telegraf - zypper in telegraf - ``` +2. Enter the following command to install `telegraf`. + + + + ```bash + # install latest telegraf + zypper in telegraf + ``` {{% /tab-content %}} @@ -176,16 +288,70 @@ Telegraf is part of the FreeBSD package system. To use the `pkg` package manager to install the latest stable version of Telegraf, enter the following command: + + ```bash sudo pkg install telegraf ``` The `telegraf` configuration file is installed at `/usr/local/etc/telegraf.conf`. Examples are installed at `/usr/local/etc/telegraf.conf.sample`. - + {{% /tab-content %}} - {{% tab-content %}} + + +Choose from the following options to install Telegraf binary files for Linux AMD: + +- To install on Linux AMD32, see the [downloads page](https://www.influxdata.com/downloads/#telegraf). +- [Download and install on Linux AMD64](#download-and-install-on-linux-amd64) + +### Download and install on Linux AMD64 + +{{% code-placeholders "260bc3170dbd6cce67575c1215a0b89b8447945106e2943d74e617d06b750c03" %}} + +```bash +curl -s --location -O \ +https://dl.influxdata.com/telegraf/releases/telegraf-{{% latest-patch %}}_linux_amd64.tar.gz \ +&& echo "260bc3170dbd6cce67575c1215a0b89b8447945106e2943d74e617d06b750c03 telegraf-{{% latest-patch %}}_linux_amd64.tar.gz" \ +| sha256sum -c - +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`260bc3170dbd6cce67575c1215a0b89b8447945106e2943d74e617d06b750c03`{{% /code-placeholder-key %}}: the SHA checksum from the [downloads page](https://www.influxdata.com/downloads/#telegraf) + + +{{% /tab-content %}} +{{% tab-content %}} + +Choose from the following options to install Telegraf binary files for Linux ARM: + +- To install on Linux ARMv7(32-bit), see the [downloads page](https://www.influxdata.com/downloads/#telegraf). +- [Download and install on Linux ARMv8 (64-bit)](#download-and-install-on-linux-arm-64) + +### Download and install on Linux ARMv8 + +{{% code-placeholders "f0d8ccae539afa04b171d5268dbab21eef58bc51b5437689e347619e2097c824" %}} + +```bash +curl -s --location -O \ +https://dl.influxdata.com/telegraf/releases/telegraf-{{% latest-patch %}}_linux_arm64.tar.gz \ +&& echo "f0d8ccae539afa04b171d5268dbab21eef58bc51b5437689e347619e2097c824 telegraf-{{% latest-patch %}}_linux_arm64.tar.gz" \ +| sha256sum -c - +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`f0d8ccae539afa04b171d5268dbab21eef58bc51b5437689e347619e2097c824`{{% /code-placeholder-key %}}: the SHA checksum from the [downloads page](https://www.influxdata.com/downloads/#telegraf) + + +{{% /tab-content %}} +{{% tab-content %}} + Choose from the following options to install Telegraf for macOS: - To manually install Telegraf from a file, see the [downloads page](https://www.influxdata.com/downloads/). @@ -201,27 +367,29 @@ The `telegraf` binary installed by Homebrew differs from the macOS `.dmg` builds - `telegraf` (Homebrew) isn't a static binary. - `telegraf` (Homebrew) works with the Telegraf CPU plugin (due to Homebrew support for [Cgo](https://pkg.go.dev/cmd/cgo)). - The `.dmg` builds available on [downloads](https://www.influxdata.com/downloads/) don't support the CPU plugin. + The `.dmg` builds available on the [downloads page](https://www.influxdata.com/downloads/) don't support the CPU plugin. {{% /note %}} To install using Homebrew, do the following: -1. If you haven't already, follow the instructions to install the [Homebrew](http://brew.sh/) package manager. -2. Enter the following commands to update brew and install Telegraf: +1. If you haven't already, follow the instructions to install the [Homebrew](http://brew.sh/) package manager. +2. Enter the following commands to update brew and install Telegraf: - ```zsh - brew update && brew install telegraf - ``` + - The path where `brew` installs the `telegraf.conf` configuration file depends on your system architecture: + ```zsh + brew update && brew install telegraf + ``` - - ARM-based (Apple Silicon) systems: `/opt/homebrew/etc/telegraf.conf` - - Intel-based (x86_64) systems: `/usr/local/etc/telegraf.conf` + The path where `brew` installs the `telegraf.conf` configuration file depends on your system architecture: + + - ARM-based (Apple Silicon) systems: `/opt/homebrew/etc/telegraf.conf` + - Intel-based (x86_64) systems: `/usr/local/etc/telegraf.conf` 3. Choose one of the following methods to start Telegraf and begin collecting and processing metrics: - - [Run Telegraf in your terminal](#run-telegraf-in-your-terminal) - - [Run Telegraf as a service](#run-telegraf-as-a-service) + - [Run Telegraf in your terminal](#run-telegraf-in-your-terminal) + - [Run Telegraf as a service](#run-telegraf-as-a-service) ### Run Telegraf in your terminal @@ -234,6 +402,8 @@ To run `telegraf` in your terminal (in the foreground and not as a service), ent {{% /code-tabs %}} {{% code-tab-content %}} + + ```zsh telegraf -config /opt/homebrew/etc/telegraf.conf ``` @@ -241,6 +411,8 @@ telegraf -config /opt/homebrew/etc/telegraf.conf {{% /code-tab-content %}} {{% code-tab-content %}} + + ```zsh telegraf -config /usr/local/etc/telegraf.conf ``` @@ -295,79 +467,69 @@ see [Launch PowerShell as administrator](https://docs.microsoft.com/en-us/powers In PowerShell _as an administrator_, do the following: -1. Use the following commands to download the Telegraf Windows binary - and extract its contents to `C:\Program Files\InfluxData\telegraf\`: +1. Use the following commands to download the Telegraf Windows binary + and extract its contents to `C:\Program Files\InfluxData\telegraf\`: - ```powershell - wget ` - https://dl.influxdata.com/telegraf/releases/telegraf-{{% latest-patch %}}_windows_amd64.zip ` - -UseBasicParsing ` - -OutFile telegraf-{{< latest-patch >}}_windows_amd64.zip - Expand-Archive .\telegraf-{{% latest-patch %}}_windows_amd64.zip ` - -DestinationPath 'C:\Program Files\InfluxData\telegraf\' - ``` + ```powershell + wget ` + https://dl.influxdata.com/telegraf/releases/telegraf-{{% latest-patch %}}_windows_amd64.zip ` + -UseBasicParsing ` + -OutFile telegraf-{{% latest-patch %}}_windows_amd64.zip + Expand-Archive .\telegraf-{{% latest-patch %}}_windows_amd64.zip ` + -DestinationPath 'C:\Program Files\InfluxData\telegraf\' + ``` -2. Choose _one_ of the following steps to place your `telegraf.exe` and `telegraf.conf` files in `C:\Program Files\InfluxData\telegraf`: +2. Choose _one_ of the following steps to place your `telegraf.exe` and `telegraf.conf` files in `C:\Program Files\InfluxData\telegraf`: - - Move the `telegraf.exe` and `telegraf.conf` files from - `C:\Program Files\InfluxData\telegraf\telegraf-{{% latest-patch %}}` to the parent directory `C:\Program Files\InfluxData\telegraf`--for example: + - Move the `telegraf.exe` and `telegraf.conf` files from + `C:\Program Files\InfluxData\telegraf\telegraf-{{% latest-patch %}}` + to the parent directory `C:\Program Files\InfluxData\telegraf`--for example: - ```powershell - cd "C:\Program Files\InfluxData\telegraf"; - mv .\telegraf-{{% latest-patch %}}\telegraf.* . - ``` + ```powershell + cd "C:\Program Files\InfluxData\telegraf"; + mv .\telegraf-{{% latest-patch %}}\telegraf.* . + ``` - - **Or**, create a [Windows symbolic link (Symlink)](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/) for - `C:\Program Files\InfluxData\telegraf` that points to the extracted directory. + - **Or**, create a [Windows symbolic link (Symlink)](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/) for + `C:\Program Files\InfluxData\telegraf` that points to the extracted directory. - {{% note %}} + {{% note %}} The remaining instructions assume that `telegraf.exe` and `telegraf.conf` files are stored in `C:\Program Files\InfluxData\telegraf` or that you created a Symlink to point to this directory. - {{% /note %}} + {{% /note %}} -3. Optional: Enable a plugin to collect Windows-specific metrics--for example, uncomment the [`inputs.win_services` plugin](/telegraf/v1/plugins/#input-win_services) configuration line: +3. Optional: Enable a plugin to collect Windows-specific metrics--for example, uncomment the [`inputs.win_services` plugin](/telegraf/v1/plugins/#input-win_services) configuration line: - ```toml - ... - # # Input plugin to report Windows services info. - # # This plugin ONLY supports Windows - [[inputs.win_services]] - ... - ``` - -4. Run the following command to install Telegraf and the configuration as a Windows service. - For the `--config` option, pass the absolute path of the `telegraf.conf` configuration file. - - ```powershell - .\telegraf.exe --service install ` - --config "C:\Program Files\InfluxData\telegraf\telegraf.conf" - ``` - -5. To test that the installation works, enter the following command: - - ```powershell - .\telegraf.exe ` - --config C:\"Program Files"\InfluxData\telegraf\telegraf.conf --test - ``` - - When run in test mode (using the `--test` flag), Telegraf runs once, collects metrics, outputs them to the console, and then exits. It doesn't run processors, aggregators, or output plugins. -6. To start collecting data, run: - - ```powershell - .\telegraf.exe --service start - ``` - - + +4. Run the following command to install Telegraf and the configuration as a Windows service. + For the `--config` option, pass the absolute path of the `telegraf.conf` configuration file. + + ```powershell + .\telegraf.exe --service install ` + --config "C:\Program Files\InfluxData\telegraf\telegraf.conf" + ``` + +5. To test that the installation works, enter the following command: + + ```powershell + .\telegraf.exe ` + --config C:\"Program Files"\InfluxData\telegraf\telegraf.conf --test + ``` + + When run in test mode (using the `--test` flag), Telegraf runs once, collects metrics, outputs them to the console, and then exits. It doesn't run processors, aggregators, or output plugins. +6. To start collecting data, run: + + ```powershell + .\telegraf.exe --service start + ``` + ### Logging and troubleshooting @@ -388,9 +550,13 @@ The following commands are available: {{< /tab-content >}} {{< /tabs-wrapper >}} -## Generate a custom configuration file +## Generate a configuration file -The `telegraf config` command lets you generate a configuration file using Telegraf's list of plugins. +The `telegraf config` command lets you generate a configuration file from +Telegraf's [plugin list](/telegraf/v1/commands/plugins/). + +- [Create a configuration file with default input and output plugins](#create-a-configuration-file-with-default-input-and-output-plugins) +- [Create a configuration with specific input and output plugins](#create-a-configuration-file-with-specific-input-and-output-plugins) ### Create a configuration file with default input and output plugins @@ -414,11 +580,14 @@ telegraf config > telegraf.conf {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} -The generated file contains settings for all available plugins--some are enabled and the rest are commented out. - ### Create a configuration file with specific input and output plugins -To generate a configuration file that contains settings for only specific input and output plugins, specify `telegraf` plugin filters--for example: +To generate a configuration file that contains settings for only specific plugins, +use the `--input-filter` and `--output-filter` options to +specify [input plugins](/telegraf/v1/plugins/input_plugins) +and [output plugins](/telegraf/v1/plugins/output_plugins/)--for example: + +{{% code-placeholders "cpu|http|influxdb_v2|file" %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} @@ -428,25 +597,27 @@ To generate a configuration file that contains settings for only specific input {{% code-tab-content %}} ```bash telegraf \ ---input-filter [:] \ ---output-filter [:] \ +--input-filter cpu:http \ +--output-filter influxdb_v2:file \ config > telegraf.conf ``` {{% /code-tab-content %}} {{% code-tab-content %}} ```powershell .\telegraf.exe ` ---input-filter [:] ` ---output-filter [:] ` +--input-filter cpu:http ` +--output-filter influxdb_v2:file ` config > telegraf.conf ``` {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +{{% /code-placeholders %}} + For more advanced configuration details, see the [configuration documentation](/telegraf/v1/administration/configuration/). -## Custom-compile Telegraf +## Custom-compile Telegraf Use the Telegraf custom builder tool to compile Telegraf with only the plugins you need and reduce the Telegraf binary size. @@ -461,27 +632,39 @@ Use the Telegraf custom builder tool to compile Telegraf with only the plugins y ### Build the custom builder tool -1. Clone the Telegraf repository: +1. Clone the Telegraf repository and then change into the repository + directory--for example, enter the following command in your terminal: - ```bash - git clone https://github.com/influxdata/telegraf.git - ``` -2. Change directories into the top-level of the Telegraf repository: + - ```bash - cd telegraf - ``` -3. Build the Telegraf custom builder tool by entering the following command: + - ```bash - make build_tools - ``` + ```bash + git clone https://github.com/influxdata/telegraf.git && cd ./telegraf + ``` + +2. To build the Telegraf custom builder tool, enter the following command: + + + + ```bash + make build_tools + ``` ### Run the custom builder to create a `telegraf` binary -The custom builder builds a `telegraf` binary with only the plugins included in the specified configuration files or directories. +The custom builder builds a `telegraf` binary with only the plugins included in +the specified configuration files or directories. -Run the `custom_builder` tool with at least one `--config` or `--config-directory` flag to specify Telegraf configuration files to build from. +Run the `custom_builder` tool with at least one `--config` or `--config-directory` +flag to specify Telegraf configuration files to build from. - `--config`: accepts local file paths and URLs. - `--config-dir`: accepts local directory paths. @@ -492,12 +675,33 @@ You can include multiple `--config` and `--config-dir` flags. ##### Single Telegraf configuration + + + + + + ```bash ./tools/custom_builder/custom_builder --config /etc/telegraf.conf ``` ##### Single Telegraf configuration and Telegraf configuration directory + + + + + + ```bash ./tools/custom_builder/custom_builder \ --config /etc/telegraf.conf \ @@ -506,6 +710,8 @@ You can include multiple `--config` and `--config-dir` flags. ##### Remote Telegraf configuration + + ```bash ./tools/custom_builder/custom_builder \ --config http://url-to-remote-telegraf/telegraf.conf diff --git a/content/telegraf/v1/release-notes.md b/content/telegraf/v1/release-notes.md index f075ef0b9..babbbf37e 100644 --- a/content/telegraf/v1/release-notes.md +++ b/content/telegraf/v1/release-notes.md @@ -11,6 +11,399 @@ menu: weight: 60 --- +## v1.33.0 {date="2024-12-09"} + +### New Plugins + +- [#15754](https://github.com/influxdata/telegraf/pull/15754) `inputs.neoom_beaam` Add new plugin +- [#15869](https://github.com/influxdata/telegraf/pull/15869) `processors.batch` Add batch processor +- [#16144](https://github.com/influxdata/telegraf/pull/16144) `outputs.quix` Add plugin + +### Features + +- [#16010](https://github.com/influxdata/telegraf/pull/16010) `agent` Add --watch-interval option for polling config changes +- [#15948](https://github.com/influxdata/telegraf/pull/15948) `aggregators.basicstats` Add first field +- [#15891](https://github.com/influxdata/telegraf/pull/15891) `common.socket` Allow parallel parsing with a pool of workers +- [#16141](https://github.com/influxdata/telegraf/pull/16141) `inputs.amqp_consumer` Allow specification of queue arguments +- [#15950](https://github.com/influxdata/telegraf/pull/15950) `inputs.diskio` Add field io await and util +- [#15919](https://github.com/influxdata/telegraf/pull/15919) `inputs.kafka_consumer` Implement startup error behavior options +- [#15910](https://github.com/influxdata/telegraf/pull/15910) `inputs.memcached` Add support for external-store metrics +- [#15990](https://github.com/influxdata/telegraf/pull/15990) `inputs.mock` Add sine phase +- [#16040](https://github.com/influxdata/telegraf/pull/16040) `inputs.modbus` Allow grouping across register types +- [#15865](https://github.com/influxdata/telegraf/pull/15865) `inputs.prometheus` Allow to use secrets for credentials +- [#16230](https://github.com/influxdata/telegraf/pull/16230) `inputs.smart` Add Power on Hours and Cycle Count +- [#15935](https://github.com/influxdata/telegraf/pull/15935) `inputs.snmp` Add displayhint conversion +- [#16027](https://github.com/influxdata/telegraf/pull/16027) `inputs.snmp` Convert uneven bytes to int +- [#15976](https://github.com/influxdata/telegraf/pull/15976) `inputs.socket_listener` Use reception time as timestamp +- [#15853](https://github.com/influxdata/telegraf/pull/15853) `inputs.statsd` Allow reporting sets and timings count as floats +- [#11591](https://github.com/influxdata/telegraf/pull/11591) `inputs.vsphere` Add VM memory configuration +- [#16109](https://github.com/influxdata/telegraf/pull/16109) `inputs.vsphere` Add cpu temperature field +- [#15917](https://github.com/influxdata/telegraf/pull/15917) `inputs` Add option to choose the metric time source +- [#16242](https://github.com/influxdata/telegraf/pull/16242) `logging` Allow overriding message key for structured logging +- [#15742](https://github.com/influxdata/telegraf/pull/15742) `outputs.influxdb_v2` Add rate limit implementation +- [#15943](https://github.com/influxdata/telegraf/pull/15943) `outputs.mqtt` Add sprig functions for topic name generator +- [#16041](https://github.com/influxdata/telegraf/pull/16041) `outputs.postgresql` Allow limiting of column name length +- [#16258](https://github.com/influxdata/telegraf/pull/16258) `outputs` Add rate-limiting infrastructure +- [#16146](https://github.com/influxdata/telegraf/pull/16146) `outputs` Implement partial write errors +- [#15883](https://github.com/influxdata/telegraf/pull/15883) `outputs` Only copy metric if its not filtered out +- [#15893](https://github.com/influxdata/telegraf/pull/15893) `serializers.prometheusremotewrite` Log metric conversion errors + +### Bugfixes + +- [#16248](https://github.com/influxdata/telegraf/pull/16248) `inputs.netflow` Decode flags in TCP and IP headers correctly +- [#16257](https://github.com/influxdata/telegraf/pull/16257) `inputs.procstat` Handle running processes correctly across multiple filters +- [#16219](https://github.com/influxdata/telegraf/pull/16219) `logging` Add `Close()` func for redirectLogger +- [#16255](https://github.com/influxdata/telegraf/pull/16255) `logging` Clean up extra empty spaces when redirectLogger is used +- [#16274](https://github.com/influxdata/telegraf/pull/16274) `logging` Fix duplicated prefix and attrMsg in log message when redirectLogger is used + +### Dependency Updates + +- [#16232](https://github.com/influxdata/telegraf/pull/16232) `deps` Bump cloud.google.com/go/bigquery from 1.63.1 to 1.64.0 +- [#16235](https://github.com/influxdata/telegraf/pull/16235) `deps` Bump cloud.google.com/go/storage from 1.43.0 to 1.47.0 +- [#16198](https://github.com/influxdata/telegraf/pull/16198) `deps` Bump github.com/aws/aws-sdk-go-v2/service/cloudwatch from 1.42.2 to 1.43.1 +- [#16234](https://github.com/influxdata/telegraf/pull/16234) `deps` Bump github.com/aws/aws-sdk-go-v2/service/kinesis from 1.29.3 to 1.32.6 +- [#16201](https://github.com/influxdata/telegraf/pull/16201) `deps` Bump github.com/intel/powertelemetry from 1.0.1 to 1.0.2 +- [#16200](https://github.com/influxdata/telegraf/pull/16200) `deps` Bump github.com/rclone/rclone from 1.68.1 to 1.68.2 +- [#16199](https://github.com/influxdata/telegraf/pull/16199) `deps` Bump github.com/vishvananda/netns from 0.0.4 to 0.0.5 +- [#16236](https://github.com/influxdata/telegraf/pull/16236) `deps` Bump golang.org/x/net from 0.30.0 to 0.31.0 +- [#16250](https://github.com/influxdata/telegraf/pull/16250) `deps` Bump golangci-lint from v1.62.0 to v1.62.2 +- [#16233](https://github.com/influxdata/telegraf/pull/16233) `deps` Bump google.golang.org/grpc from 1.67.1 to 1.68.0 +- [#16202](https://github.com/influxdata/telegraf/pull/16202) `deps` Bump modernc.org/sqlite from 1.33.1 to 1.34.1 +- [#16203](https://github.com/influxdata/telegraf/pull/16203) `deps` Bump super-linter/super-linter from 7.1.0 to 7.2.0 + +## v1.32.3 {date="2024-11-18"} + +### Important Changes + +- PR [#16015](https://github.com/influxdata/telegraf/pull/16015) changes the + internal counters of the Bind plugin to unsigned integers (as in the server + implementation). For backward compatibility, + `report_counters_as_int` is `true` by default to avoid type conflicts on the + output side. _However, you should set `report_counters_as_int` to `false` as soon as + possible to avoid invalid values and parsing errors with the v3 XML + statistics._ + +### Bugfixes + +- [#16123](https://github.com/influxdata/telegraf/pull/16123) `agent` Restore setup order of stateful plugins to `Init()` then `SetState()` +- [#16111](https://github.com/influxdata/telegraf/pull/16111) `common.socket` Make sure the scanner buffer matches the read-buffer size +- [#16156](https://github.com/influxdata/telegraf/pull/16156) `common.socket` Use read buffer size config setting as a datagram reader buffer size +- [#16015](https://github.com/influxdata/telegraf/pull/16015) `inputs.bind` Convert counters to uint64 +- [#16171](https://github.com/influxdata/telegraf/pull/16171) `inputs.gnmi` Register connection statistics before creating client +- [#16197](https://github.com/influxdata/telegraf/pull/16197) `inputs.netflow` Cast TCP ports to uint16 +- [#16110](https://github.com/influxdata/telegraf/pull/16110) `inputs.ntpq` Avoid panic on empty lines and make sure -p is present +- [#16155](https://github.com/influxdata/telegraf/pull/16155) `inputs.snmp` Fix crash when trying to format fields from unknown OIDs +- [#16145](https://github.com/influxdata/telegraf/pull/16145) `inputs.snmp_trap` Remove timeout deprecation +- [#16108](https://github.com/influxdata/telegraf/pull/16108) `logger` Avoid setting the log-format default too early + +### Dependency Updates + +- [#16093](https://github.com/influxdata/telegraf/pull/16093) `deps` Bump cloud.google.com/go/pubsub from 1.42.0 to 1.45.1 +- [#16175](https://github.com/influxdata/telegraf/pull/16175) `deps` Bump github.com/aws/aws-sdk-go-v2/credentials from 1.17.37 to 1.17.44 +- [#16096](https://github.com/influxdata/telegraf/pull/16096) `deps` Bump github.com/gofrs/uuid/v5 from 5.2.0 to 5.3.0 +- [#16136](https://github.com/influxdata/telegraf/pull/16136) `deps` Bump github.com/golang-jwt/jwt/v4 from 4.5.0 to 4.5.1 +- [#16094](https://github.com/influxdata/telegraf/pull/16094) `deps` Bump github.com/gopacket/gopacket from 1.2.0 to 1.3.0 +- [#16133](https://github.com/influxdata/telegraf/pull/16133) `deps` Bump github.com/jackc/pgtype from 1.14.3 to 1.14.4 +- [#16131](https://github.com/influxdata/telegraf/pull/16131) `deps` Bump github.com/openconfig/gnmi from 0.10.0 to 0.11.0 +- [#16092](https://github.com/influxdata/telegraf/pull/16092) `deps` Bump github.com/prometheus/client_golang from 1.20.4 to 1.20.5 +- [#16178](https://github.com/influxdata/telegraf/pull/16178) `deps` Bump github.com/rclone/rclone from 1.67.0 to 1.68.1 +- [#16132](https://github.com/influxdata/telegraf/pull/16132) `deps` Bump github.com/shirou/gopsutil/v4 from 4.24.9 to 4.24.10 +- [#16176](https://github.com/influxdata/telegraf/pull/16176) `deps` Bump github.com/sijms/go-ora/v2 from 2.8.19 to 2.8.22 +- [#16134](https://github.com/influxdata/telegraf/pull/16134) `deps` Bump github.com/testcontainers/testcontainers-go/modules/kafka from 0.33.0 to 0.34.0 +- [#16174](https://github.com/influxdata/telegraf/pull/16174) `deps` Bump github.com/tidwall/gjson from 1.17.1 to 1.18.0 +- [#16135](https://github.com/influxdata/telegraf/pull/16135) `deps` Bump github.com/vmware/govmomi from 0.39.0 to 0.45.1 +- [#16095](https://github.com/influxdata/telegraf/pull/16095) `deps` Bump golang.org/x/sys from 0.25.0 to 0.26.0 +- [#16177](https://github.com/influxdata/telegraf/pull/16177) `deps` Bump golang.org/x/text from 0.19.0 to 0.20.0 +- [#16172](https://github.com/influxdata/telegraf/pull/16172) `deps` Bump golangci-lint from v1.61.0 to v1.62.0 + +## v1.32.2 {date="2024-10-28"} + +### Bugfixes + +- [#15966](https://github.com/influxdata/telegraf/pull/15966) `agent` Use a unique WAL file for plugin instances of the same type +- [#16074](https://github.com/influxdata/telegraf/pull/16074) `inputs.kafka_consumer` Fix deadlock +- [#16009](https://github.com/influxdata/telegraf/pull/16009) `inputs.netflow` Cast complex types to field compatible ones +- [#16026](https://github.com/influxdata/telegraf/pull/16026) `inputs.opcua` Allow to retry reads on invalid sessions +- [#16060](https://github.com/influxdata/telegraf/pull/16060) `inputs.procstat` Correctly use systemd-unit setting for finding them +- [#16008](https://github.com/influxdata/telegraf/pull/16008) `inputs.win_eventlog` Handle XML data fields' filtering the same way as event fields +- [#15968](https://github.com/influxdata/telegraf/pull/15968) `outputs.remotefile` Create a new serializer instance per output file +- [#16014](https://github.com/influxdata/telegraf/pull/16014) `outputs.syslog` Trim field-names belonging to explicit SDIDs correctly + +### Dependency Updates + +- [#15992](https://github.com/influxdata/telegraf/pull/15992) `deps` Bump cloud.google.com/go/bigquery from 1.62.0 to 1.63.1 +- [#16056](https://github.com/influxdata/telegraf/pull/16056) `deps` Bump github.com/Azure/azure-sdk-for-go/sdk/azcore from 1.14.0 to 1.16.0 +- [#16021](https://github.com/influxdata/telegraf/pull/16021) `deps` Bump github.com/IBM/sarama from 1.43.2 to 1.43.3 +- [#16019](https://github.com/influxdata/telegraf/pull/16019) `deps` Bump github.com/alitto/pond from 1.9.0 to 1.9.2 +- [#16018](https://github.com/influxdata/telegraf/pull/16018) `deps` Bump github.com/apache/thrift from 0.20.0 to 0.21.0 +- [#16054](https://github.com/influxdata/telegraf/pull/16054) `deps` Bump github.com/aws/aws-sdk-go-v2 from 1.32.1 to 1.32.2 +- [#15996](https://github.com/influxdata/telegraf/pull/15996) `deps` Bump github.com/aws/aws-sdk-go-v2/service/cloudwatch from 1.40.4 to 1.42.1 +- [#16055](https://github.com/influxdata/telegraf/pull/16055) `deps` Bump github.com/aws/aws-sdk-go-v2/service/cloudwatch from 1.42.1 to 1.42.2 +- [#16057](https://github.com/influxdata/telegraf/pull/16057) `deps` Bump github.com/aws/aws-sdk-go-v2/service/dynamodb from 1.34.9 to 1.36.2 +- [#16022](https://github.com/influxdata/telegraf/pull/16022) `deps` Bump github.com/docker/docker from 27.1.1+incompatible to 27.3.1+incompatible +- [#15993](https://github.com/influxdata/telegraf/pull/15993) `deps` Bump github.com/gosnmp/gosnmp from 1.37.0 to 1.38.0 +- [#15947](https://github.com/influxdata/telegraf/pull/15947) `deps` Bump github.com/gwos/tcg/sdk from v8.7.2 to v8.8.0 +- [#16053](https://github.com/influxdata/telegraf/pull/16053) `deps` Bump github.com/lxc/incus/v6 from 6.2.0 to 6.6.0 +- [#15994](https://github.com/influxdata/telegraf/pull/15994) `deps` Bump github.com/signalfx/golib/v3 from 3.3.53 to 3.3.54 +- [#15995](https://github.com/influxdata/telegraf/pull/15995) `deps` Bump github.com/snowflakedb/gosnowflake from 1.11.1 to 1.11.2 +- [#16020](https://github.com/influxdata/telegraf/pull/16020) `deps` Bump go.step.sm/crypto from 0.51.1 to 0.54.0 +- [#16023](https://github.com/influxdata/telegraf/pull/16023) `deps` Bump github.com/shirou/gopsutil from v3.24.4 to v4.24.9 + +## v1.32.1 {date="2024-10-07"} + +### Important Changes + +- PR [#15796](https://github.com/influxdata/telegraf/pull/15796) changes the + delivery state update of un-parseable messages from `ACK` to `NACK` without + requeueing. This way, those messages are not lost and can optionally be + handled using a dead-letter exchange by other means. +- Removal of old-style serializer creation. This should not directly affect + users as it is an API change; all serializers in Telegraf are already ported + to the new framework. If you experience any issues creating serializers, [contact us](/telegraf/v1/#bug-reports-and-feedback). + +### Bugfixes + +- [#15969](https://github.com/influxdata/telegraf/pull/15969) `agent` Fix buffer not flushing if all metrics are written +- [#15937](https://github.com/influxdata/telegraf/pull/15937) `config` Correctly print removal version info +- [#15900](https://github.com/influxdata/telegraf/pull/15900) `common.http` Keep timeout after creating oauth client +- [#15796](https://github.com/influxdata/telegraf/pull/15796) `inputs.amqp_consumer` NACKing messages on non-delivery related errors +- [#15923](https://github.com/influxdata/telegraf/pull/15923) `inputs.cisco_telemetry_mdt` Handle NXOS DME subtree telemetry format +- [#15907](https://github.com/influxdata/telegraf/pull/15907) `inputs.consul` Move config checking to Init method +- [#15982](https://github.com/influxdata/telegraf/pull/15982) `inputs.influxdb_v2_listener` Fix concurrent read/write dict +- [#15960](https://github.com/influxdata/telegraf/pull/15960) `inputs.vsphere` Add tags to VSAN ESA disks +- [#15921](https://github.com/influxdata/telegraf/pull/15921) `parsers.avro` Add mutex to cache access +- [#15965](https://github.com/influxdata/telegraf/pull/15965) `processors.aws_ec2` Remove leading slash and cancel worker only if it exists + +### Dependency Updates + +- [#15932](https://github.com/influxdata/telegraf/pull/15932) `deps` Bump cloud.google.com/go/monitoring from 1.20.2 to 1.21.1 +- [#15863](https://github.com/influxdata/telegraf/pull/15863) `deps` Bump github.com/Azure/azure-kusto-go from 0.15.3 to 0.16.1 +- [#15862](https://github.com/influxdata/telegraf/pull/15862) `deps` Bump github.com/Azure/azure-sdk-for-go/sdk/azcore from 1.13.0 to 1.14.0 +- [#15957](https://github.com/influxdata/telegraf/pull/15957) `deps` Bump github.com/aws/aws-sdk-go-v2/feature/ec2/imds from 1.16.12 to 1.16.14 +- [#15859](https://github.com/influxdata/telegraf/pull/15859) `deps` Bump github.com/aws/aws-sdk-go-v2/service/dynamodb from 1.34.4 to 1.34.9 +- [#15931](https://github.com/influxdata/telegraf/pull/15931) `deps` Bump github.com/boschrexroth/ctrlx-datalayer-golang from 1.3.0 to 1.3.1 +- [#15890](https://github.com/influxdata/telegraf/pull/15890) `deps` Bump github.com/harlow/kinesis-consumer from v0.3.6-0.20240606153816-553e2392fdf3 to v0.3.6-0.20240916192723-43900507c911 +- [#15904](https://github.com/influxdata/telegraf/pull/15904) `deps` Bump github.com/netsampler/goflow2/v2 from 2.1.5 to 2.2.1 +- [#15903](https://github.com/influxdata/telegraf/pull/15903) `deps` Bump github.com/p4lang/p4runtime from 1.3.0 to 1.4.0 +- [#15905](https://github.com/influxdata/telegraf/pull/15905) `deps` Bump github.com/prometheus/client_golang from 1.20.2 to 1.20.3 +- [#15930](https://github.com/influxdata/telegraf/pull/15930) `deps` Bump github.com/prometheus/client_golang from 1.20.3 to 1.20.4 +- [#15962](https://github.com/influxdata/telegraf/pull/15962) `deps` Bump github.com/prometheus/common from 0.55.0 to 0.60.0 +- [#15860](https://github.com/influxdata/telegraf/pull/15860) `deps` Bump github.com/snowflakedb/gosnowflake from 1.10.0 to 1.11.1 +- [#15954](https://github.com/influxdata/telegraf/pull/15954) `deps` Bump github.com/srebhan/protobufquery from 0.0.0-20230803132024-ae4c0d878e55 to 1.0.1 +- [#15929](https://github.com/influxdata/telegraf/pull/15929) `deps` Bump go.mongodb.org/mongo-driver from 1.16.0 to 1.17.0 +- [#15902](https://github.com/influxdata/telegraf/pull/15902) `deps` Bump golang.org/x/mod from 0.19.0 to 0.21.0 +- [#15955](https://github.com/influxdata/telegraf/pull/15955) `deps` Bump golang.org/x/oauth2 from 0.21.0 to 0.23.0 +- [#15861](https://github.com/influxdata/telegraf/pull/15861) `deps` Bump golang.org/x/term from 0.23.0 to 0.24.0 +- [#15856](https://github.com/influxdata/telegraf/pull/15856) `deps` Bump golangci-lint from v1.60.3 to v1.61.0 +- [#15933](https://github.com/influxdata/telegraf/pull/15933) `deps` Bump k8s.io/apimachinery from 0.30.1 to 0.31.1 +- [#15901](https://github.com/influxdata/telegraf/pull/15901) `deps` Bump modernc.org/sqlite from 1.32.0 to 1.33.1 + +## v1.32.0 {date="2024-09-09"} + +### Important Changes + +- This release contains a logging overhaul as well as some new features for + logging (see PRs [#15556](https://github.com/influxdata/telegraf/pull/15556), + [#15629](https://github.com/influxdata/telegraf/pull/15629), + [#15677](https://github.com/influxdata/telegraf/pull/15677), + [#15695](https://github.com/influxdata/telegraf/pull/15695) and + [#15751](https://github.com/influxdata/telegraf/pull/15751)). + As a consequence, the redundant `logtarget` setting is deprecated. `stderr` is + used if no `logfile` is provided, otherwise messages are logged to the given + file. To use Windows `eventlog`, set `logformat = "eventlog"`. +- This release contains a change in json_v2 parser config parsing: if the config is empty (doesn't define any rules), initialization will fail + (see PR [#15844](https://github.com/influxdata/telegraf/pull/15844)). +- This release contains a feature for a disk-backed metric buffer under the + `buffer_strategy` agent config (see + PR [#15564](https://github.com/influxdata/telegraf/pull/15564)). + _This feature is **experimental**. Please report any issues you encounter while using it._ + +### New Plugins + +- [#15700](https://github.com/influxdata/telegraf/pull/15700) `inputs.slurm` SLURM workload manager +- [#15602](https://github.com/influxdata/telegraf/pull/15602) `outputs.parquet` Parquet file writer +- [#15569](https://github.com/influxdata/telegraf/pull/15569) `outputs.remotefile` Output to remote location like S3 + +### Features + +- [#15732](https://github.com/influxdata/telegraf/pull/15732) `agent` Add config check sub-command +- [#15564](https://github.com/influxdata/telegraf/pull/15564) `agent` Add metric disk buffer +- [#15645](https://github.com/influxdata/telegraf/pull/15645) `agent` Enable watching for new configuration files +- [#15644](https://github.com/influxdata/telegraf/pull/15644) `agent` Watch for deleted files +- [#15695](https://github.com/influxdata/telegraf/pull/15695) `logging` Add 'trace' log-level +- [#15677](https://github.com/influxdata/telegraf/pull/15677) `logging` Allow to override log-level per plugin +- [#15751](https://github.com/influxdata/telegraf/pull/15751) `logging` Implement structured logging +- [#15640](https://github.com/influxdata/telegraf/pull/15640) `common.cookie` Allow usage of secrets in headers +- [#15636](https://github.com/influxdata/telegraf/pull/15636) `common.shim` Enable metric tracking within external plugins +- [#15570](https://github.com/influxdata/telegraf/pull/15570) `common.tls` Allow group aliases for cipher-suites +- [#15628](https://github.com/influxdata/telegraf/pull/15628) `inputs.amd_rocm_smi` Parse newer ROCm versions +- [#15519](https://github.com/influxdata/telegraf/pull/15519) `inputs.azure_monitor` Add client options parameter +- [#15544](https://github.com/influxdata/telegraf/pull/15544) `inputs.elasticsearch` Add support for custom headers +- [#15688](https://github.com/influxdata/telegraf/pull/15688) `inputs.elasticsearch` Gather enrich stats +- [#15834](https://github.com/influxdata/telegraf/pull/15834) `inputs.execd` Allow to provide logging prefixes on stderr +- [#15764](https://github.com/influxdata/telegraf/pull/15764) `inputs.http_listener_v2` Add unix socket mode +- [#15495](https://github.com/influxdata/telegraf/pull/15495) `inputs.ipmi_sensor` Collect additional commands +- [#15790](https://github.com/influxdata/telegraf/pull/15790) `inputs.kafka_consumer` Allow to select the metric time source +- [#15648](https://github.com/influxdata/telegraf/pull/15648) `inputs.modbus` Allow reading single bits of input and holding registers +- [#15528](https://github.com/influxdata/telegraf/pull/15528) `inputs.mqtt_consumer` Add variable length topic parsing +- [#15486](https://github.com/influxdata/telegraf/pull/15486) `inputs.mqtt_consumer` Implement startup error behaviors +- [#15749](https://github.com/influxdata/telegraf/pull/15749) `inputs.mysql` Add support for replica status +- [#15521](https://github.com/influxdata/telegraf/pull/15521) `inputs.netflow` Add more fields for sFlow extended gateway packets +- [#15396](https://github.com/influxdata/telegraf/pull/15396) `inputs.netflow` Add support for sFlow drop notification packets +- [#15468](https://github.com/influxdata/telegraf/pull/15468) `inputs.openstack` Allow collection without admin privileges +- [#15637](https://github.com/influxdata/telegraf/pull/15637) `inputs.opentelemetry` Add profiles support +- [#15423](https://github.com/influxdata/telegraf/pull/15423) `inputs.procstat` Add ability to collect per-process socket statistics +- [#15655](https://github.com/influxdata/telegraf/pull/15655) `inputs.s7comm` Implement startup-error behavior settings +- [#15600](https://github.com/influxdata/telegraf/pull/15600) `inputs.sql` Add SAP HANA SQL driver +- [#15424](https://github.com/influxdata/telegraf/pull/15424) `inputs.sqlserver` Introduce user specified ID parameter for ADD logins +- [#15687](https://github.com/influxdata/telegraf/pull/15687) `inputs.statsd` Expose allowed_pending_messages as internal stat +- [#15458](https://github.com/influxdata/telegraf/pull/15458) `inputs.systemd_units` Support user scoped units +- [#15702](https://github.com/influxdata/telegraf/pull/15702) `outputs.datadog` Add support for submitting alongside dd-agent +- [#15668](https://github.com/influxdata/telegraf/pull/15668) `outputs.dynatrace` Report metrics as a delta counter using regular expression +- [#15471](https://github.com/influxdata/telegraf/pull/15471) `outputs.elasticsearch` Allow custom template index settings +- [#15613](https://github.com/influxdata/telegraf/pull/15613) `outputs.elasticsearch` Support data streams +- [#15722](https://github.com/influxdata/telegraf/pull/15722) `outputs.kafka` Add option to add metric name as record header +- [#15689](https://github.com/influxdata/telegraf/pull/15689) `outputs.kafka` Add option to set producer message timestamp +- [#15787](https://github.com/influxdata/telegraf/pull/15787) `outputs.syslog` Implement startup error behavior options +- [#15697](https://github.com/influxdata/telegraf/pull/15697) `parsers.value` Add base64 datatype +- [#15795](https://github.com/influxdata/telegraf/pull/15795) `processors.aws_ec2` Allow to use instance metadata + +### Bugfixes + +- [#15661](https://github.com/influxdata/telegraf/pull/15661) `agent` Fix buffer directory config and document +- [#15788](https://github.com/influxdata/telegraf/pull/15788) `inputs.kinesis_consumer` Honor the configured endpoint +- [#15791](https://github.com/influxdata/telegraf/pull/15791) `inputs.mysql` Enforce float for all known floating-point information +- [#15743](https://github.com/influxdata/telegraf/pull/15743) `inputs.snmp` Avoid sending a nil to gosmi's GetEnumBitsFormatted +- [#15815](https://github.com/influxdata/telegraf/pull/15815) `logger` Handle trace level for standard log +- [#15781](https://github.com/influxdata/telegraf/pull/15781) `outputs.kinesis` Honor the configured endpoint +- [#15615](https://github.com/influxdata/telegraf/pull/15615) `outputs.remotefile` Resolve linter not checking error +- [#15740](https://github.com/influxdata/telegraf/pull/15740) `serializers.template` Unwrap metrics if required + +### Dependency Updates + +- [#15829](https://github.com/influxdata/telegraf/pull/15829) `deps` Bump github.com/BurntSushi/toml from 1.3.2 to 1.4.0 +- [#15775](https://github.com/influxdata/telegraf/pull/15775) `deps` Bump github.com/aws/aws-sdk-go-v2/feature/ec2/imds from 1.16.11 to 1.16.12 +- [#15733](https://github.com/influxdata/telegraf/pull/15733) `deps` Bump github.com/aws/aws-sdk-go-v2/service/cloudwatch from 1.38.7 to 1.40.3 +- [#15761](https://github.com/influxdata/telegraf/pull/15761) `deps` Bump github.com/aws/aws-sdk-go-v2/service/cloudwatch from 1.40.3 to 1.40.4 +- [#15827](https://github.com/influxdata/telegraf/pull/15827) `deps` Bump github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs from 1.37.3 to 1.38.0 +- [#15760](https://github.com/influxdata/telegraf/pull/15760) `deps` Bump github.com/aws/aws-sdk-go-v2/service/timestreamwrite from 1.25.5 to 1.27.4 +- [#15737](https://github.com/influxdata/telegraf/pull/15737) `deps` Bump github.com/eclipse/paho.mqtt.golang from 1.4.3 to 1.5.0 +- [#15734](https://github.com/influxdata/telegraf/pull/15734) `deps` Bump github.com/google/cel-go from 0.20.1 to 0.21.0 +- [#15777](https://github.com/influxdata/telegraf/pull/15777) `deps` Bump github.com/miekg/dns from 1.1.59 to 1.1.62 +- [#15828](https://github.com/influxdata/telegraf/pull/15828) `deps` Bump github.com/openconfig/goyang from 1.5.0 to 1.6.0 +- [#15735](https://github.com/influxdata/telegraf/pull/15735) `deps` Bump github.com/pion/dtls/v2 from 2.2.11 to 2.2.12 +- [#15779](https://github.com/influxdata/telegraf/pull/15779) `deps` Bump github.com/prometheus/client_golang from 1.19.1 to 1.20.2 +- [#15831](https://github.com/influxdata/telegraf/pull/15831) `deps` Bump github.com/prometheus/prometheus from 0.53.1 to 0.54.1 +- [#15736](https://github.com/influxdata/telegraf/pull/15736) `deps` Bump github.com/redis/go-redis/v9 from 9.5.1 to 9.6.1 +- [#15830](https://github.com/influxdata/telegraf/pull/15830) `deps` Bump github.com/seancfoley/ipaddress-go from 1.6.0 to 1.7.0 +- [#15842](https://github.com/influxdata/telegraf/pull/15842) `deps` Bump github.com/showwin/speedtest-go from 1.7.7 to 1.7.9 +- [#15778](https://github.com/influxdata/telegraf/pull/15778) `deps` Bump go.step.sm/crypto from 0.50.0 to 0.51.1 +- [#15776](https://github.com/influxdata/telegraf/pull/15776) `deps` Bump golang.org/x/net from 0.27.0 to 0.28.0 +- [#15757](https://github.com/influxdata/telegraf/pull/15757) `deps` Bump golang.org/x/sync from 0.7.0 to 0.8.0 +- [#15759](https://github.com/influxdata/telegraf/pull/15759) `deps` Bump gonum.org/v1/gonum from 0.15.0 to 0.15.1 +- [#15758](https://github.com/influxdata/telegraf/pull/15758) `deps` Bump modernc.org/sqlite from 1.30.0 to 1.32.0 +- [#15756](https://github.com/influxdata/telegraf/pull/15756) `deps` Bump super-linter/super-linter from 6.8.0 to 7.0.0 +- [#15826](https://github.com/influxdata/telegraf/pull/15826) `deps` Bump super-linter/super-linter from 7.0.0 to 7.1.0 +- [#15780](https://github.com/influxdata/telegraf/pull/15780) `deps` Bump tj-actions/changed-files from 44 to 45 + +## v1.31.3 {date="2024-08-12"} + +### Bugfixes + +- [#15552](https://github.com/influxdata/telegraf/pull/15552) `inputs.chrony` Use DGRAM for the unix socket +- [#15667](https://github.com/influxdata/telegraf/pull/15667) `inputs.diskio` Print warnings once, add details to messages +- [#15670](https://github.com/influxdata/telegraf/pull/15670) `inputs.mqtt_consumer` Restore trace logging option +- [#15696](https://github.com/influxdata/telegraf/pull/15696) `inputs.opcua` Reconnect if closed connection +- [#15724](https://github.com/influxdata/telegraf/pull/15724) `inputs.smartctl` Use --scan-open instead of --scan to provide correct device type info +- [#15649](https://github.com/influxdata/telegraf/pull/15649) `inputs.tail` Prevent deadlock when closing and max undelivered lines hit + +### Dependency Updates + +- [#15720](https://github.com/influxdata/telegraf/pull/15720) `deps` Bump Go from v1.22.5 to v1.22.6 +- [#15683](https://github.com/influxdata/telegraf/pull/15683) `deps` Bump cloud.google.com/go/bigquery from 1.61.0 to 1.62.0 +- [#15654](https://github.com/influxdata/telegraf/pull/15654) `deps` Bump cloud.google.com/go/monitoring from 1.19.0 to 1.20.2 +- [#15679](https://github.com/influxdata/telegraf/pull/15679) `deps` Bump cloud.google.com/go/monitoring from 1.20.2 to 1.20.3 +- [#15626](https://github.com/influxdata/telegraf/pull/15626) `deps` Bump github.com/antchfx/xmlquery from 1.4.0 to 1.4.1 +- [#15706](https://github.com/influxdata/telegraf/pull/15706) `deps` Bump github.com/apache/iotdb-client-go from 1.2.0-tsbs to 1.3.2 +- [#15651](https://github.com/influxdata/telegraf/pull/15651) `deps` Bump github.com/aws/aws-sdk-go-v2/credentials from 1.17.17 to 1.17.27 +- [#15703](https://github.com/influxdata/telegraf/pull/15703) `deps` Bump github.com/aws/aws-sdk-go-v2/service/kinesis from v1.27.4 to v1.29.3 +- [#15681](https://github.com/influxdata/telegraf/pull/15681) `deps` Bump github.com/docker/docker from 25.0.5-incompatible to 27.1.1-incompatible +- [#15650](https://github.com/influxdata/telegraf/pull/15650) `deps` Bump github.com/gofrs/uuid/v5 from 5.0.0 to 5.2.0 +- [#15705](https://github.com/influxdata/telegraf/pull/15705) `deps` Bump github.com/gorilla/websocket from 1.5.1 to 1.5.3 +- [#15708](https://github.com/influxdata/telegraf/pull/15708) `deps` Bump github.com/multiplay/go-ts3 from 1.1.0 to 1.2.0 +- [#15707](https://github.com/influxdata/telegraf/pull/15707) `deps` Bump github.com/prometheus-community/pro-bing from 0.4.0 to 0.4.1 +- [#15709](https://github.com/influxdata/telegraf/pull/15709) `deps` Bump github.com/prometheus/prometheus from 0.48.1 to 0.53.1 +- [#15680](https://github.com/influxdata/telegraf/pull/15680) `deps` Bump github.com/vmware/govmomi from 0.37.2 to 0.39.0 +- [#15682](https://github.com/influxdata/telegraf/pull/15682) `deps` Bump go.mongodb.org/mongo-driver from 1.14.0 to 1.16.0 +- [#15652](https://github.com/influxdata/telegraf/pull/15652) `deps` Bump go.step.sm/crypto from 0.47.1 to 0.50.0 +- [#15653](https://github.com/influxdata/telegraf/pull/15653) `deps` Bump google.golang.org/grpc from 1.64.1 to 1.65.0 +- [#15704](https://github.com/influxdata/telegraf/pull/15704) `deps` Bump super-linter/super-linter from 6.7.0 to 6.8.0 + +## v1.31.2 {date="2024-07-22"} + +### Bugfixes + +- [#15589](https://github.com/influxdata/telegraf/pull/15589) `common.socket` Switch to context to simplify closing +- [#15601](https://github.com/influxdata/telegraf/pull/15601) `inputs.ping` Check addr length to avoid crash +- [#15618](https://github.com/influxdata/telegraf/pull/15618) `inputs.snmp` Translate field correctly when not in table +- [#15586](https://github.com/influxdata/telegraf/pull/15586) `parsers.xpath` Allow resolving extensions +- [#15630](https://github.com/influxdata/telegraf/pull/15630) `tools.custom_builder` Handle multiple instances of the same plugin correctly + +### Dependency Updates + +- [#15582](https://github.com/influxdata/telegraf/pull/15582) `deps` Bump cloud.google.com/go/storage from 1.41.0 to 1.42.0 +- [#15623](https://github.com/influxdata/telegraf/pull/15623) `deps` Bump cloud.google.com/go/storage from 1.42.0 to 1.43.0 +- [#15607](https://github.com/influxdata/telegraf/pull/15607) `deps` Bump github.com/alitto/pond from 1.8.3 to 1.9.0 +- [#15625](https://github.com/influxdata/telegraf/pull/15625) `deps` Bump github.com/antchfx/xpath from 1.3.0 to 1.3.1 +- [#15622](https://github.com/influxdata/telegraf/pull/15622) `deps` Bump github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs from 1.34.3 to 1.37.3 +- [#15606](https://github.com/influxdata/telegraf/pull/15606) `deps` Bump github.com/hashicorp/consul/api from 1.26.1 to 1.29.1 +- [#15604](https://github.com/influxdata/telegraf/pull/15604) `deps` Bump github.com/jackc/pgx/v4 from 4.18.2 to 4.18.3 +- [#15581](https://github.com/influxdata/telegraf/pull/15581) `deps` Bump github.com/nats-io/nats-server/v2 from 2.10.16 to 2.10.17 +- [#15603](https://github.com/influxdata/telegraf/pull/15603) `deps` Bump github.com/openconfig/goyang from 1.0.0 to 1.5.0 +- [#15624](https://github.com/influxdata/telegraf/pull/15624) `deps` Bump github.com/sijms/go-ora/v2 from 2.8.4 to 2.8.19 +- [#15585](https://github.com/influxdata/telegraf/pull/15585) `deps` Bump github.com/testcontainers/testcontainers-go/modules/kafka from 0.30.0 to 0.31.0 +- [#15605](https://github.com/influxdata/telegraf/pull/15605) `deps` Bump github.com/tinylib/msgp from 1.1.9 to 1.2.0 +- [#15584](https://github.com/influxdata/telegraf/pull/15584) `deps` Bump github.com/urfave/cli/v2 from 2.27.1 to 2.27.2 +- [#15614](https://github.com/influxdata/telegraf/pull/15614) `deps` Bump google.golang.org/grpc from 1.64.0 to 1.64.1 +- [#15608](https://github.com/influxdata/telegraf/pull/15608) `deps` Bump super-linter/super-linter from 6.6.0 to 6.7.0 + +For versions earlier than v1.13 and earlier see +[CHANGELOG-1.13.md](CHANGELOG-1.13.md). + +## v1.31.1 {date="2024-07-01"} + +### Bugfixes + +- [#15488](https://github.com/influxdata/telegraf/pull/15488) `agent` Ignore startup-errors in test mode +- [#15568](https://github.com/influxdata/telegraf/pull/15568) `inputs.chrony` Handle ServerStats4 response +- [#15551](https://github.com/influxdata/telegraf/pull/15551) `inputs.chrony` Support local (reference) sources +- [#15565](https://github.com/influxdata/telegraf/pull/15565) `inputs.gnmi` Handle YANG namespaces in paths correctly +- [#15496](https://github.com/influxdata/telegraf/pull/15496) `inputs.http_response` Fix for IPv4 and IPv6 addresses when interface is set +- [#15493](https://github.com/influxdata/telegraf/pull/15493) `inputs.mysql` Handle custom TLS configs correctly +- [#15514](https://github.com/influxdata/telegraf/pull/15514) `logging` Add back constants for backward compatibility +- [#15531](https://github.com/influxdata/telegraf/pull/15531) `secretstores.oauth2` Ensure endpoint params is not nil + +### Dependency Updates + +- [#15483](https://github.com/influxdata/telegraf/pull/15483) `deps` Bump cloud.google.com/go/monitoring from 1.18.1 to 1.19.0 +- [#15559](https://github.com/influxdata/telegraf/pull/15559) `deps` Bump github.com/Azure/azure-kusto-go from 0.15.2 to 0.15.3 +- [#15489](https://github.com/influxdata/telegraf/pull/15489) `deps` Bump github.com/Azure/azure-sdk-for-go/sdk/azidentity from 1.5.1 to 1.6.0 +- [#15560](https://github.com/influxdata/telegraf/pull/15560) `deps` Bump github.com/Azure/go-autorest/autorest/azure/auth from 0.5.12 to 0.5.13 +- [#15480](https://github.com/influxdata/telegraf/pull/15480) `deps` Bump github.com/IBM/sarama from 1.43.1 to 1.43.2 +- [#15526](https://github.com/influxdata/telegraf/pull/15526) `deps` Bump github.com/aws/aws-sdk-go-v2/service/cloudwatch from 1.37.0 to 1.38.7 +- [#15527](https://github.com/influxdata/telegraf/pull/15527) `deps` Bump github.com/aws/aws-sdk-go-v2/service/dynamodb from 1.30.2 to 1.32.9 +- [#15558](https://github.com/influxdata/telegraf/pull/15558) `deps` Bump github.com/aws/aws-sdk-go-v2/service/dynamodb from 1.32.9 to 1.33.2 +- [#15448](https://github.com/influxdata/telegraf/pull/15448) `deps` Bump github.com/aws/aws-sdk-go-v2/service/ec2 from 1.161.1 to 1.162.1 +- [#15557](https://github.com/influxdata/telegraf/pull/15557) `deps` Bump github.com/go-ldap/ldap/v3 from 3.4.6 to 3.4.8 +- [#15523](https://github.com/influxdata/telegraf/pull/15523) `deps` Bump github.com/linkedin/goavro/v2 from 2.12.0 to 2.13.0 +- [#15484](https://github.com/influxdata/telegraf/pull/15484) `deps` Bump github.com/microsoft/go-mssqldb from 1.7.0 to 1.7.2 +- [#15561](https://github.com/influxdata/telegraf/pull/15561) `deps` Bump github.com/nats-io/nats-server/v2 from 2.10.14 to 2.10.16 +- [#15524](https://github.com/influxdata/telegraf/pull/15524) `deps` Bump github.com/prometheus/common from 0.53.0 to 0.54.0 +- [#15481](https://github.com/influxdata/telegraf/pull/15481) `deps` Bump github.com/prometheus/procfs from 0.15.0 to 0.15.1 +- [#15482](https://github.com/influxdata/telegraf/pull/15482) `deps` Bump github.com/rabbitmq/amqp091-go from 1.9.0 to 1.10.0 +- [#15525](https://github.com/influxdata/telegraf/pull/15525) `deps` Bump go.step.sm/crypto from 0.44.1 to 0.47.1 +- [#15479](https://github.com/influxdata/telegraf/pull/15479) `deps` Bump super-linter/super-linter from 6.5.1 to 6.6.0 + ## v1.31.0 {date="2024-06-10"} ### Important Changes diff --git a/data/flux_influxdb_minor_versions.yml b/data/flux_influxdb_minor_versions.yml new file mode 100644 index 000000000..abe9e0324 --- /dev/null +++ b/data/flux_influxdb_minor_versions.yml @@ -0,0 +1,24 @@ +# This is a list of all InfluxDB minor versions that support Flux. +# It is used by flux-build-scripts/update-flux-versions.js to generate the +# "Supported Versions" section of the Flux page. +# When new versions of InfluxDB are released that support Flux, this list should +# be updated. + +influxdb: + - '2.7' + - '2.6' + - '2.5' + - '2.4' + - '2.3' + - '2.2' + - '2.1' + - '2.0' + - '1.11' + - '1.8' + - '1.7' +enterprise: + - '1.11' + - '1.10' + - '1.9' + - '1.8' + - '1.7' \ No newline at end of file diff --git a/data/flux_influxdb_versions.yml b/data/flux_influxdb_versions.yml index 9d61ed2ed..6f9c22c64 100644 --- a/data/flux_influxdb_versions.yml +++ b/data/flux_influxdb_versions.yml @@ -5,11 +5,11 @@ # build/deploy process. flux: - latest: 0.194.4 + latest: 0.195.2 cloud: current: 0.194.3 oss: - '2.7': 0.194.4 + '2.7': 0.195.2 '2.6': 0.191.0 '2.5': 0.188.1 '2.4': 0.179.0 @@ -17,12 +17,13 @@ oss: '2.2': 0.162.0 '2.1': 0.139.0 '2.0': 0.131.0 + '1.11': 0.194.5 '1.8': 0.65.1 '1.7': 0.50.2 - nightly: 0.194.4 + nightly: 0.195.2 enterprise: - '1.11': 0.194.3 - '1.10': 0.188.0 + '1.11': 0.194.5 + '1.10': 0.194.5 '1.9': 0.161.0 '1.8': 0.65.1 '1.7': 0.50.2 diff --git a/data/flux_stdlib_frontmatter.yml b/data/flux_stdlib_frontmatter.yml index 200c2e545..4b92702e4 100644 --- a/data/flux_stdlib_frontmatter.yml +++ b/data/flux_stdlib_frontmatter.yml @@ -920,11 +920,49 @@ aliases: - /influxdb/v2/reference/flux/stdlib/experimental/mqtt/ - /influxdb/cloud/reference/flux/stdlib/experimental/mqtt/ + prepend: + block: warn + content: | + #### Only supported in InfluxDB Cloud (TSM) + + The `experimental/mqtt` package only supported in InfluxDB Cloud (TSM). + It is still available to import in InfluxDB OSS and Enterprise, but + functions will not successfully publish to an MQTT broker. + exclude_from: + nightly: true + oss: ^* + enterprise: ^* /flux/v0/stdlib/experimental/mqtt/to.md: | aliases: - /influxdb/v2/reference/flux/stdlib/experimental/mqtt/to/ - /influxdb/cloud/reference/flux/stdlib/experimental/mqtt/to/ + prepend: + block: warn + content: | + #### Only supported in InfluxDB Cloud (TSM) + + The `experimental/mqtt` package only supported in InfluxDB Cloud (TSM). + It is still available to import in InfluxDB OSS and Enterprise, but + functions will not successfully publish to an MQTT broker. + exclude_from: + nightly: true + oss: ^* + enterprise: ^* + +/flux/v0/stdlib/experimental/mqtt/publish.md: | + prepend: + block: warn + content: | + #### Only supported in InfluxDB Cloud (TSM) + + The `experimental/mqtt` package only supported in InfluxDB Cloud (TSM). + It is still available to import in InfluxDB OSS and Enterprise, but + functions will not successfully publish to an MQTT broker. + exclude_from: + nightly: true + oss: ^* + enterprise: ^* /flux/v0/stdlib/experimental/oee/_index.md: | aliases: diff --git a/data/notifications.yaml b/data/notifications.yaml index 6d8764090..35d8bef68 100644 --- a/data/notifications.yaml +++ b/data/notifications.yaml @@ -38,3 +38,40 @@ # - [The plan for InfluxDB 3.0 Open Source](https://influxdata.com/blog/the-plan-for-influxdb-3-0-open-source) # - [InfluxDB 3.0 benchmarks](https://influxdata.com/blog/influxdb-3-0-is-2.5x-45x-faster-compared-to-influxdb-open-source/) + +# - id: v3-enhancements-clustered-ga +# level: note +# scope: +# - / +# exclude: +# - /influxdb/cloud/ +# - /influxdb/v1/ +# - /influxdb/v2/ +# - /flux/v0/ +# - /telegraf/ +# - /kapacitor/ +# - /chronograf/ +# title: InfluxDB v3 enhancements and InfluxDB Clustered is now generally available +# slug: | +# New capabilities, including faster query performance and management +# tooling advance the InfluxDB v3 product line. +# InfluxDB Clustered is now generally available. +# message: | +# ### InfluxDB v3 performance and features + +# The InfluxDB v3 product line has seen significant enhancements in query +# performance and has made new management tooling available. These enhancements +# include an operational dashboard to monitor the health of your InfluxDB cluster, +# single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management +# APIs for tokens and databases. + +# [Learn about the new v3 enhancements](https://www.influxdata.com/blog/scaling-time-series-workloads-influxdb) + +# --- + +# ### InfluxDB Clustered general availability + +# InfluxDB Clustered is now generally available and gives you the power of +# InfluxDB v3 in your self-managed stack. + +# [Talk to us about InfluxDB Clustered](https://www.influxdata.com/products/influxdb-clustered/) diff --git a/data/products.yml b/data/products.yml index 6569cdc80..dba2e1620 100644 --- a/data/products.yml +++ b/data/products.yml @@ -8,21 +8,10 @@ influxdb: versions: - v2 - v1 - minor_versions: - - v2.7 - - v2.6 - - v2.5 - - v2.4 - - v2.3 - - v2.2 - - v2.1 - - v2.0 - - v1.8 - - v1.7 latest: v2.7 latest_patches: - v2: 2.7.10 - v1: 1.8.10 + v2: 2.7.11 + v1: 1.11.8 latest_cli: v2: 2.7.5 @@ -55,7 +44,7 @@ influxdb_cloud_dedicated: list_order: 3 latest: cloud-dedicated link: "https://www.influxdata.com/contact-sales-form/" - latest_cli: 2.9.6 + latest_cli: 2.9.8 placeholder_host: cluster-id.a.influxdb.io influxdb_clustered: @@ -75,9 +64,9 @@ telegraf: menu_category: other list_order: 6 versions: [v1] - latest: v1.31 + latest: v1.33 latest_patches: - v1: 1.31.0 + v1: 1.33.0 chronograf: name: Chronograf @@ -87,7 +76,7 @@ chronograf: versions: [v1] latest: v1.10 latest_patches: - v1: 1.10.5 + v1: 1.10.6 kapacitor: name: Kapacitor @@ -97,7 +86,7 @@ kapacitor: versions: [v1] latest: v1.7 latest_patches: - v1: 1.7.5 + v1: 1.7.6 enterprise_influxdb: name: "InfluxDB Enterprise" @@ -105,15 +94,9 @@ enterprise_influxdb: menu_category: self-managed list_order: 5 versions: [v1] - minor_versions: - - v1.11 - - v1.10 - - v1.9 - - v1.8 - - v1.7 latest: v1.11 latest_patches: - v1: 1.11.6 + v1: 1.11.8 flux: name: Flux diff --git a/data/telegraf_plugins.yml b/data/telegraf_plugins.yml index bb50068c5..2adac6e6f 100644 --- a/data/telegraf_plugins.yml +++ b/data/telegraf_plugins.yml @@ -1035,7 +1035,7 @@ input: introduced: 1.10.0 tags: [linux, macos, windows, build-deploy, containers] - - name: ldap + - name: LDAP id: ldap description: | This plugin gathers metrics from LDAP servers' monitoring (cn=Monitor) backend. @@ -1689,7 +1689,7 @@ input: tags: [linux, macos, windows, messaging] - name: Radius - id: Radius + id: radius description: | Collects authentication response time metrics from Radius. introduced: 1.26.0 @@ -1737,6 +1737,14 @@ input: introduced: 0.1.1 tags: [linux, macos, windows, data-stores] + - name: Redis sentinel + id: redis_sentinel + description: | + A plugin for Redis Sentinel to monitor multiple Sentinel instances that + are monitoring multiple Redis servers and replicas. + introduced: 1.22.0 + tags: [linux, macos, windows] + - name: RethinkDB id: rethinkdb description: | @@ -1797,7 +1805,7 @@ input: This plugin gathers information from Siemens PLC (Programmatic Logic Controller). introduced: 1.28.0 link: https://github.com/nicolasme/s7comm/blob/main/README.md - tags: [serial, iot] + tags: [linux, macos, windows, iot] - name: Slab id: slab @@ -1807,6 +1815,14 @@ input: link: https://github.com/influxdata/telegraf/blob/master/plugins/inputs/slab/README.md tags: [linux, system] + - name: SLURM + id: slurm + description: | + This plugin gather diag, jobs, nodes, partitions and reservation metrics + by leveraging SLURM's REST API as provided by the slurmrestd daemon + introduced: 1.32.0 + tags: [linux, macos, windows] + - name: S.M.A.R.T. id: smart description: | @@ -2431,6 +2447,14 @@ output: introduced: 0.13.1 tags: [linux, macos, windows, applications] + - name: IoTDB + id: iotdb + description: | + This output plugin saves Telegraf metrics to an Apache IoTDB backend, + supporting session connection and data insertion. + introduced: 1.24.0 + tags: [linux, macos, windows, data-stores] + - name: Librato id: librato description: | @@ -2548,6 +2572,13 @@ output: introduced: 0.1.9 tags: [linux, macos, windows, data-stores] + - name: Parquet + id: parquet + description: | + This plugin writes metrics to parquet files. By default, it groups metrics by name, and then writes each group to a separate file. If a metric schema doesn't match, the metrics are dropped. + introduced: 1.32.0 + tags: [linux, macos, windows, data-stores] + - name: Postgre SQL id: postgresql description: | @@ -2563,13 +2594,22 @@ output: introduced: 0.2.1 tags: [linux, macos, windows, applications] - - name: RedisTimeSeries + - name: Redis time series id: redistimeseries description: | - The RedisTimeSeries output plugin writes metrics to the RedisTimeSeries server. + The Redis time series output plugin writes metrics to the RedisTimeSeries server. introduced: 1.24.0 tags: [linux, macos, windows, networking] + - name: Remote file + id: remotefile + description: | + This plugin writes telegraf metrics to files in remote locations using + the rclone library. Multiple backends such as Amazon S3 or SFTP are + supported. + introduced: 1.32.0 + tags: [linux, macos, windows, data-stores] + - name: Riemann id: riemann description: | @@ -2668,13 +2708,6 @@ output: introduced: 1.19.0 tags: [web, servers] - - name: XML - id: xml - description: | - The XML parser plugin parses an XML string into metric fields using XPath expressions. - introduced: 1.18.0 - tags: [] - - name: Yandex Cloud Monitoring id: yandex_cloud_monitoring description: | @@ -2682,6 +2715,15 @@ output: introduced: 1.17.0 tags: [linux, macos, windows] + - name: Zabbix + id: zabbix + description: | + This plugin send metrics to Zabbix via traps. It has been tested with + versions 3.0, 4.0 and 6.0. It should work with newer versions as long as + Zabbix does not change the protocol. + introduced: 1.30.0 + tags: [linux, macos, windows, data-stores] + # %%%% %%%% %%%% %%%%% %%%%%% %%%% %%%% %%%%%% %%%% %%%%% %%%% # # %% %% %% %% %% %% %% %% %% %% %% %% %% %% %% %% # # %%%%%% %% %%% %% %%% %%%%% %%%% %% %%% %%%%%% %% %% %% %%%%% %%%% # @@ -2785,7 +2827,7 @@ aggregator: processor: - name: AWS EC2 Metadata - id: aws/ec2 + id: aws_ec2 description: | The AWS EC2 Metadata processor plugin appends metadata gathered from [AWS IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) to metrics associated with EC2 instances. introduced: 1.18.0 @@ -2987,6 +3029,13 @@ processor: introduced: 1.27.0 tags: [linux, macos, windows] + - name: SNMP lookup + id: snmp_lookup + description: | + Processor to look-up extra tags using SNMP + introduced: 1.30.0 + tags: [linux, macos, windows] + - name: Split id: split description: | diff --git a/flux-build-scripts/update-flux-versions.js b/flux-build-scripts/update-flux-versions.js index 4ec513c25..2dd1568b8 100644 --- a/flux-build-scripts/update-flux-versions.js +++ b/flux-build-scripts/update-flux-versions.js @@ -85,12 +85,11 @@ function isSemanticNewer(semverX, semverY) { } // Load product data from the product data file -const productData = yaml.load(fs.readFileSync(path.resolve(__dirname,'../data/products.yml'), 'utf8')) +const influxdbMinorVersions = yaml.load(fs.readFileSync(path.resolve(__dirname,'../data/flux_influxdb_minor_versions.yml'), 'utf8')) -// Update InfluxDB version arrays by removing 'v' from each version // Filter out InfluxDB Enterprise versions that don't have a Flux dependency in their go.mod -const ossVersionArr = productData.influxdb.minor_versions.map((element) => {return element.replace('v', '')}); -const enterpriseVersionArr = productData.enterprise_influxdb.minor_versions.map((element) => {return element.replace('v', '')}).filter(version => isSemanticNewer(version, '1.9')); +const ossVersionArr = influxdbMinorVersions.influxdb; +const enterpriseVersionArr = influxdbMinorVersions.enterprise.filter(version => isSemanticNewer(version, '1.9')); // Instantiate base Flux version variables var ossVersions = {}; diff --git a/hugo.staging.toml b/hugo.staging.toml deleted file mode 100644 index 432b438fa..000000000 --- a/hugo.staging.toml +++ /dev/null @@ -1,53 +0,0 @@ -baseURL = "https://test2.docs.influxdata.com/" -languageCode = "en-us" -title = "InfluxDB Documentation" - -# Git history information for lastMod-type functionality -enableGitInfo = true - -# Syntax Highlighting -pygmentsCodefences = true -pygmentsUseClasses = true - -# Preserve case in article tags -preserveTaxonomyNames = true - -# Generate a robots.txt -enableRobotsTXT = true - -# Custom staging params -[params] - environment = "staging" - -# Markdown rendering options -[blackfriday] -hrefTargetBlank = true -smartDashes = false - -[taxonomies] - "influxdb/v2/tag" = "influxdb/v2/tags" - "influxdb/cloud/tag" = "influxdb/cloud/tags" - "influxdb/cloud-serverless/tag" = "influxdb/cloud-serverless/tags" - "influxdb/cloud-dedicated/tag" = "influxdb/cloud-dedicated/tags" - "influxdb/clustered/tag" = "influxdb/clustered/tags" - "flux/v0/tag" = "flux/v0/tags" - -[markup] - [markup.goldmark] - [markup.goldmark.renderer] - unsafe = true - -[privacy] - [privacy.googleAnalytics] - anonymizeIP = false - disable = false - respectDoNotTrack = true - useSessionStorage = false - [privacy.youtube] - disable = false - privacyEnhanced = true - -[outputFormats.json] - mediaType = "application/json" - baseName = "pages" - isPlainText = true diff --git a/hugo.staging.yml b/hugo.staging.yml new file mode 100644 index 000000000..31a0e03e4 --- /dev/null +++ b/hugo.staging.yml @@ -0,0 +1,58 @@ +baseURL: https://test2.docs.influxdata.com/ +languageCode: en-us +title: InfluxDB Documentation + +# Git history information for lastMod-type functionality +enableGitInfo: true + +# Syntax Highlighting +pygmentsCodefences: true +pygmentsUseClasses: true + +# Preserve case in article tags +preserveTaxonomyNames: true + +# Generate a robots.txt +enableRobotsTXT: true + +# Custom staging params +params: + environment: staging + +# Markdown rendering options +blackfriday: + hrefTargetBlank: true + smartDashes: false + +taxonomies: + influxdb/v2/tag: influxdb/v2/tags + influxdb/cloud/tag: influxdb/cloud/tags + influxdb/cloud-serverless/tag: influxdb/cloud-serverless/tags + influxdb/cloud-dedicated/tag: influxdb/cloud-dedicated/tags + influxdb/clustered/tag: influxdb/clustered/tags + flux/v0/tag: flux/v0/tags + +markup: + goldmark: + renderer: + unsafe: true + extensions: + linkify: false + parser: + attribute: + block: true + +privacy: + googleAnalytics: + anonymizeIP: false + disable: false + respectDoNotTrack: true + useSessionStorage: false + youtube: + disable: false + privacyEnhanced: true +outputFormats: + json: + mediaType: application/json + baseName: pages + isPlainText: true diff --git a/hugo.toml b/hugo.toml deleted file mode 100644 index 1abf7d2c4..000000000 --- a/hugo.toml +++ /dev/null @@ -1,49 +0,0 @@ -baseURL = "https://docs.influxdata.com/" -languageCode = "en-us" -title = "InfluxDB Documentation" - -# Git history information for lastMod-type functionality -enableGitInfo = true - -# Syntax Highlighting -pygmentsCodefences = true -pygmentsUseClasses = true - -# Preserve case in article tags -preserveTaxonomyNames = true - -# Generate a robots.txt -enableRobotsTXT = true - -# Markdown rendering options -[blackfriday] -hrefTargetBlank = true -smartDashes = false - -[taxonomies] - "influxdb/v2/tag" = "influxdb/v2/tags" - "influxdb/cloud/tag" = "influxdb/cloud/tags" - "influxdb/cloud-serverless/tag" = "influxdb/cloud-serverless/tags" - "influxdb/cloud-dedicated/tag" = "influxdb/cloud-dedicated/tags" - "influxdb/clustered/tag" = "influxdb/clustered/tags" - "flux/v0/tag" = "flux/v0/tags" - -[markup] - [markup.goldmark] - [markup.goldmark.renderer] - unsafe = true - -[privacy] - [privacy.googleAnalytics] - anonymizeIP = false - disable = false - respectDoNotTrack = true - useSessionStorage = false - [privacy.youtube] - disable = false - privacyEnhanced = true - -[outputFormats.json] - mediaType = "application/json" - baseName = "pages" - isPlainText = true diff --git a/hugo.yml b/hugo.yml new file mode 100644 index 000000000..6258b52ea --- /dev/null +++ b/hugo.yml @@ -0,0 +1,54 @@ +baseURL: 'https://docs.influxdata.com/' +languageCode: en-us +title: InfluxDB Documentation + +# Git history information for lastMod-type functionality +enableGitInfo: true + +# Syntax Highlighting +pygmentsCodefences: true +pygmentsUseClasses: true + +# Preserve case in article tags +preserveTaxonomyNames: true + +# Generate a robots.txt +enableRobotsTXT: true + +# Markdown rendering options +blackfriday: + hrefTargetBlank: true + smartDashes: false + +taxonomies: + influxdb/v2/tag: influxdb/v2/tags + influxdb/cloud/tag: influxdb/cloud/tags + influxdb/cloud-serverless/tag: influxdb/cloud-serverless/tags + influxdb/cloud-dedicated/tag: influxdb/cloud-dedicated/tags + influxdb/clustered/tag: influxdb/clustered/tags + flux/v0/tag: flux/v0/tags + +markup: + goldmark: + renderer: + unsafe: true + extensions: + linkify: false + parser: + attribute: + block: true + +privacy: + googleAnalytics: + anonymizeIP: false + disable: false + respectDoNotTrack: true + useSessionStorage: false + youtube: + disable: false + privacyEnhanced: true +outputFormats: + json: + mediaType: application/json + baseName: pages + isPlainText: true diff --git a/layouts/_default/_markup/render-blockquote.html b/layouts/_default/_markup/render-blockquote.html new file mode 100644 index 000000000..1a27bb812 --- /dev/null +++ b/layouts/_default/_markup/render-blockquote.html @@ -0,0 +1,11 @@ +{{ if eq .Type "alert" }} +
+ {{/* Hugo render hooks add an opening paragraph tag if the .Text starts */}} + {{/* with a heading. This replaces the phantom paragraph tag. */}} + {{ replace .Text "

+{{ else }} +

+{{ .Text | safeHTML}} +
+{{ end }} \ No newline at end of file diff --git a/layouts/partials/article/content.html b/layouts/partials/article/content.html index 6173adc8e..14b62408a 100644 --- a/layouts/partials/article/content.html +++ b/layouts/partials/article/content.html @@ -1,10 +1,12 @@ {{ $productPathData := findRE "[^/]+.*?" .RelPermalink }} {{ $product := index $productPathData 0 }} {{ $version := index $productPathData 1 }} -{{ $influxdbOSS := and (eq $product "influxdb") (not (in $version "cloud")) }} +{{ $influxdbOSSv2 := and (eq $product "influxdb") (in $version "v2") }} {{ $influxdbCloud := and (eq $product "influxdb") (in $version "cloud") }} -{{ if $influxdbOSS }} +{{ if .Params.source }} + {{ readFile .Params.source | replaceRE (print $product "/version") (print $product "/" $version) | .RenderString | safeHTML }} +{{ else if $influxdbOSSv2 }} {{ .Content | replaceRE `(?Us)(
  • \s*<(?:div|span) class=\'cloud\-only\'>.*<\/(?:div|span)><\!\-\- close \-\-\>\s*
  • )` "" | replaceRE `(?Us)(<(?:div|span) class=\'cloud\-only\'>.*<\/(?:div|span)><\!\-\- close \-\-\>)` "" | safeHTML}} {{ else if $influxdbCloud }} {{ .Content | replaceRE `(?Us)(
  • \s*<(?:div|span) class=\'oss\-only\'>.*<\/(?:div|span)><\!\-\- close \-\-\>\s*
  • )` "" | replaceRE `(?Us)(<(?:div|span) class=\'oss\-only\'>.*<\/(?:div|span)><\!\-\- close \-\-\>)` "" | safeHTML}} diff --git a/layouts/partials/article/feedback.html b/layouts/partials/article/feedback.html index 41157dc8a..6677abccc 100644 --- a/layouts/partials/article/feedback.html +++ b/layouts/partials/article/feedback.html @@ -13,6 +13,8 @@ {{ .Scratch.Set "pageGithubLink" (print "https://github.com/influxdata/docs-v2/edit/master/content/" .File.Path) }} {{ if .Page.HasShortcode "duplicate-oss" }} {{ .Scratch.Set "pageGithubLink" (replaceRE "/cloud/" "/v2/" (.Scratch.Get "pageGithubLink")) }} + {{ else if .Params.Source }} + {{ .Scratch.Set "pageGithubLink" (print "https://github.com/influxdata/docs-v2/edit/master/content" .Params.source) }} {{ end }} {{ else }} {{ .Scratch.Set "pageGithubLink" (print "https://github.com/influxdata/docs-v2/edit/master/content/") }} diff --git a/layouts/partials/article/stable-version.html b/layouts/partials/article/stable-version.html index 0794eb6a1..28e7f27a6 100644 --- a/layouts/partials/article/stable-version.html +++ b/layouts/partials/article/stable-version.html @@ -1,6 +1,6 @@ {{ $productPathData := findRE "[^/]+.*?" .RelPermalink }} {{ $product := index $productPathData 0 }} -{{ $productName := (index .Site.Data.products $product).name }} +{{ $productName := cond (isset (index .Site.Data.products $product) "altname") (index .Site.Data.products $product).altname (index .Site.Data.products $product).name }} {{ $currentVersion := index $productPathData 1 }} {{ $latestV2 := index (.Site.Data.products.influxdb.versions) 0 }} diff --git a/layouts/partials/footer/javascript.html b/layouts/partials/footer/javascript.html index 4b4e310f5..3cf4bc3bd 100644 --- a/layouts/partials/footer/javascript.html +++ b/layouts/partials/footer/javascript.html @@ -18,12 +18,14 @@ {{ $fluxInfluxDBVersions := resources.Get "/js/flux-influxdb-versions.js" }} {{ $v3Wayfinding := resources.Get "/js/v3-wayfinding.js"}} {{ $codePlaceholders := resources.Get "/js/code-placeholders.js" }} +{{ $releaseTOC := resources.Get "/js/release-toc.js" }} {{ $footerjs := slice $versionSelector $contentInteractions $searchInteractions $listFilters $modals $influxdbURLs $featureCallouts $tabbedContent $apiLibs $notifications $keybindings $codeControls $pageFeedback $homepageInteractions $fluxInfluxDBVersions | resources.Concat "js/footer.bundle.js" | resources.Fingerprint }} {{ $fluxGroupKeyjs := $fluxGroupKeys | resources.Fingerprint }} {{ $dateTimejs := $dateTime | resources.Fingerprint }} {{ $influxdbGSTimestampsjs := $influxdbGSTimestamps | resources.Fingerprint }} {{ $v3Wayfindingjs := $v3Wayfinding | resources.Fingerprint }} {{ $codePlaceholdersjs := $codePlaceholders | resources.Fingerprint }} +{{ $releaseTOCjs := $releaseTOC | resources.Fingerprint }} {{ end }} + +{{ if .Page.HasShortcode "release-toc" }} + +{{ end }} + \ No newline at end of file diff --git a/layouts/partials/footer/modals/flux-influxdb-versions.html b/layouts/partials/footer/modals/flux-influxdb-versions.html index 722bfd019..2328efe37 100644 --- a/layouts/partials/footer/modals/flux-influxdb-versions.html +++ b/layouts/partials/footer/modals/flux-influxdb-versions.html @@ -41,20 +41,83 @@

    InfluxDB Open Source (OSS)

    + + {{ range $key, $value := $oss }} + {{ $versionSemVer := split $value "." }} + {{ $supported := cond (ge (index $versionSemVer 0) (index $introducedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $introducedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $introducedSemVer 2)) true false) false) false }} + {{ $deprecated := and (isset $.Page.Params "deprecated") (cond (ge (index $versionSemVer 0) (index $deprecatedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $deprecatedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $deprecatedSemVer 2)) true false) false) false) }} + {{ $nightlyExcluded := and (eq $key "nightly") $.Page.Params.exclude_from.nightly }} + {{ $excluded := or (gt (len (findRE (string $excludePatternOSS) $key)) 0) $nightlyExcluded }} + {{ if and (in $key "1.") (eq (len $key) 3) }} +
    +

    InfluxDB {{ $key }}

    +

    + {{ if $excluded }} + {{ else if $deprecated }} + {{ else if $supported }} + {{ end }} +

    +
    + {{ end }} + {{ end }} + + {{ range $key, $value := $oss }} {{ $versionSemVer := split $value "." }} {{ $supported := cond (ge (index $versionSemVer 0) (index $introducedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $introducedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $introducedSemVer 2)) true false) false) false }} {{ $deprecated := and (isset $.Page.Params "deprecated") (cond (ge (index $versionSemVer 0) (index $deprecatedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $deprecatedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $deprecatedSemVer 2)) true false) false) false) }} {{ $excluded := gt (len (findRE (string $excludePatternOSS) $key)) 0 }} -
    -

    InfluxDB {{ $key }}

    -

    - {{ if $excluded }} - {{ else if $deprecated }} - {{ else if $supported }} - {{ end }} + {{ if and (in $key "1.") (gt (len $key) 3) }} +

    +

    InfluxDB {{ $key }}

    +

    + {{ if $excluded }} + {{ else if $deprecated }} + {{ else if $supported }} + {{ end }} +

    -
    + {{ end }} + {{ end }} + + + {{ range $key, $value := $oss }} + {{ $versionSemVer := split $value "." }} + {{ $supported := cond (ge (index $versionSemVer 0) (index $introducedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $introducedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $introducedSemVer 2)) true false) false) false }} + {{ $deprecated := and (isset $.Page.Params "deprecated") (cond (ge (index $versionSemVer 0) (index $deprecatedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $deprecatedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $deprecatedSemVer 2)) true false) false) false) }} + {{ $nightlyExcluded := and (eq $key "nightly") $.Page.Params.exclude_from.nightly }} + {{ $excluded := or (gt (len (findRE (string $excludePatternOSS) $key)) 0) $nightlyExcluded }} + {{ if and (in $key "2.") (eq (len $key) 3) }} +
    +

    InfluxDB {{ $key }}

    +

    + {{ if $excluded }} + {{ else if $deprecated }} + {{ else if $supported }} + {{ end }} +

    +
    + {{ end }} + {{ end }} + + + {{ range $key, $value := $oss }} + {{ $versionSemVer := split $value "." }} + {{ $supported := cond (ge (index $versionSemVer 0) (index $introducedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $introducedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $introducedSemVer 2)) true false) false) false }} + {{ $deprecated := and (isset $.Page.Params "deprecated") (cond (ge (index $versionSemVer 0) (index $deprecatedSemVer 0)) (cond (ge (index $versionSemVer 1) (index $deprecatedSemVer 1)) (cond (ge (index $versionSemVer 2) (index $deprecatedSemVer 2)) true false) false) false) }} + {{ $nightlyExcluded := and (eq $key "nightly") $.Page.Params.exclude_from.nightly }} + {{ $excluded := or (gt (len (findRE (string $excludePatternOSS) $key)) 0) $nightlyExcluded }} + {{ if and (in $key "2.") (gt (len $key) 3) }} +
    +

    InfluxDB {{ $key }}

    +

    + {{ if $excluded }} + {{ else if $deprecated }} + {{ else if $supported }} + {{ end }} +

    +
    + {{ end }} {{ end }}
    diff --git a/layouts/partials/header/javascript.html b/layouts/partials/header/javascript.html index f257221be..b763b8ef1 100644 --- a/layouts/partials/header/javascript.html +++ b/layouts/partials/header/javascript.html @@ -1,9 +1,8 @@ {{ $jquery := resources.Get "js/jquery-3.5.0.min.js" }} -{{ $cookies := resources.Get "js/js.cookie.js" }} -{{ $docsCookies := resources.Get "js/cookies.js" }} +{{ $localStorage := resources.Get "js/local-storage.js" }} {{ $themes := resources.Get "js/docs-themes.js" }} {{ $sidebar := resources.Get "js/sidebar-toggle.js" }} -{{ $headerjs := slice $jquery $cookies $docsCookies $themes $sidebar | resources.Concat "js/header.bundle.js" | resources.Fingerprint }} +{{ $headerjs := slice $jquery $localStorage $themes $sidebar | resources.Concat "js/header.bundle.js" | resources.Fingerprint }} diff --git a/layouts/partials/topnav/version-selector.html b/layouts/partials/topnav/version-selector.html index b841e69fc..67c1e58b0 100644 --- a/layouts/partials/topnav/version-selector.html +++ b/layouts/partials/topnav/version-selector.html @@ -2,7 +2,7 @@ {{ $productPathData := findRE "[^/]+.*?" .RelPermalink }} {{ $product := index $productPathData 0 }} {{ $currentVersion := index $productPathData 1 }} -{{ $doNotIncludeVersion := slice "resources" "platform" }} +{{ $doNotIncludeVersion := slice "resources" "platform" "example" }} {{ if or (eq $product nil) (in $doNotIncludeVersion $product) }} {{ else }} diff --git a/layouts/shortcodes/cloud.html b/layouts/shortcodes/cloud.html deleted file mode 100644 index d43a614c5..000000000 --- a/layouts/shortcodes/cloud.html +++ /dev/null @@ -1,4 +0,0 @@ -{{ $_hugo_config := `{ "version": 1 }` }} -
    - {{ .Inner }} -
    diff --git a/layouts/shortcodes/enterprise.html b/layouts/shortcodes/enterprise.html deleted file mode 100644 index 47c3086e0..000000000 --- a/layouts/shortcodes/enterprise.html +++ /dev/null @@ -1,4 +0,0 @@ -{{ $_hugo_config := `{ "version": 1 }` }} -
    - {{ .Inner }} -
    diff --git a/layouts/shortcodes/release-toc.html b/layouts/shortcodes/release-toc.html new file mode 100644 index 000000000..ac2f249e1 --- /dev/null +++ b/layouts/shortcodes/release-toc.html @@ -0,0 +1,10 @@ +{{- $productPathData := findRE "[^/]+.*?" .Page.RelPermalink -}} +{{- $currentVersion := index $productPathData 1 -}} +{{- $show := .Get "show" | default 12 -}} + +
    +
      + +
    + Show more +
    \ No newline at end of file diff --git a/lefthook.yml b/lefthook.yml index 7608bc2f6..bc0a0b143 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -9,6 +9,11 @@ pre-push: pre-commit: parallel: true commands: + lint-markdown: + tags: lint + glob: "content/**/*.md" + run: | + docker compose run --rm --name remark-lint remark-lint '{staged_files}' cloud-lint: tags: lint,v2 glob: "content/influxdb/cloud/**/*.md" @@ -50,7 +55,7 @@ pre-commit: tags: test,codeblocks,v2 env: - SERVICE: cloud-pytest - run: docker compose run $SERVICE '{staged_files}' + run: docker compose run --rm --name $SERVICE $SERVICE '{staged_files}' cloud-dedicated-pytest: tags: test,codeblocks,v3 glob: content/influxdb/cloud-dedicated/**/*.md @@ -58,14 +63,14 @@ pre-commit: - SERVICE: cloud-dedicated-pytest run: | ./test/scripts/monitor-tests.sh start $SERVICE ; - docker compose run $SERVICE {staged_files} ; + docker compose run --name $SERVICE $SERVICE {staged_files} ; ./test/scripts/monitor-tests.sh stop $SERVICE cloud-serverless-pytest: tags: test,codeblocks,v3 glob: content/influxdb/cloud-serverless/**/*.md env: - SERVICE: cloud-serverless-pytest - run: docker compose run $SERVICE '{staged_files}' + run: docker compose run --rm --name $SERVICE $SERVICE '{staged_files}' clustered-pytest: tags: test,codeblocks,v3 glob: content/influxdb/clustered/**/*.md @@ -73,20 +78,20 @@ pre-commit: - SERVICE: clustered-pytest run: | ./test/scripts/monitor-tests.sh start $SERVICE ; - docker compose run $SERVICE {staged_files} ; + docker compose run --name $SERVICE $SERVICE {staged_files} ; ./test/scripts/monitor-tests.sh stop $SERVICE telegraf-pytest: tags: test,codeblocks glob: content/telegraf/**/*.md env: - SERVICE: telegraf-pytest - run: docker compose run $SERVICE '{staged_files}' + run: docker compose run --rm --name $SERVICE $SERVICE '{staged_files}' v2-pytest: tags: test,codeblocks,v2 glob: content/influxdb/v2/**/*.md env: - SERVICE: v2-pytest - run: docker compose run --rm $SERVICE '{staged_files}' + run: docker compose run --rm --name $SERVICE $SERVICE '{staged_files}' prettier: tags: frontend,style glob: "*.{css,js,ts,jsx,tsx}" diff --git a/static/downloads/home-sensor-data.csv b/static/downloads/home-sensor-data.csv index 1125a23ec..758229f3e 100644 --- a/static/downloads/home-sensor-data.csv +++ b/static/downloads/home-sensor-data.csv @@ -1,3 +1,4 @@ +#datatype measurement,tag,field,field,field,time measurement,room,temp,hum,co,time home,Living Room,21.1,35.9,0,1712822400 home,Kitchen,21.0,35.9,0,1712822400 diff --git a/static/downloads/home-sensor-data.lp b/static/downloads/home-sensor-data.lp new file mode 100644 index 000000000..716e60ae8 --- /dev/null +++ b/static/downloads/home-sensor-data.lp @@ -0,0 +1,26 @@ +home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1721548800 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1721548800 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1721552400 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1721552400 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1721556000 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1721556000 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1721559600 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1721559600 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1721563200 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1721563200 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1721566800 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1721566800 +home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1721570400 +home,room=Kitchen temp=22.8,hum=36.3,co=1i 1721570400 +home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1721574000 +home,room=Kitchen temp=22.7,hum=36.2,co=3i 1721574000 +home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1721577600 +home,room=Kitchen temp=22.4,hum=36.0,co=7i 1721577600 +home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1721581200 +home,room=Kitchen temp=22.7,hum=36.0,co=9i 1721581200 +home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1721584800 +home,room=Kitchen temp=23.3,hum=36.9,co=18i 1721584800 +home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1721588400 +home,room=Kitchen temp=23.1,hum=36.6,co=22i 1721588400 +home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1721592000 +home,room=Kitchen temp=22.7,hum=36.5,co=26i 1721592000 diff --git a/static/fonts/alert-icons.eot b/static/fonts/alert-icons.eot new file mode 100644 index 000000000..13e657b52 Binary files /dev/null and b/static/fonts/alert-icons.eot differ diff --git a/static/fonts/alert-icons.svg b/static/fonts/alert-icons.svg new file mode 100644 index 000000000..e205465e5 --- /dev/null +++ b/static/fonts/alert-icons.svg @@ -0,0 +1,15 @@ + + + +Generated by IcoMoon + + + + + + + + + + + \ No newline at end of file diff --git a/static/fonts/alert-icons.ttf b/static/fonts/alert-icons.ttf new file mode 100644 index 000000000..ec4b22201 Binary files /dev/null and b/static/fonts/alert-icons.ttf differ diff --git a/static/fonts/alert-icons.woff b/static/fonts/alert-icons.woff new file mode 100644 index 000000000..293b00a1d Binary files /dev/null and b/static/fonts/alert-icons.woff differ diff --git a/static/img/influx-logo-cubo-dark.png b/static/img/influx-logo-cubo-dark.png index 00f4f2b5f..d87fc95a4 100644 Binary files a/static/img/influx-logo-cubo-dark.png and b/static/img/influx-logo-cubo-dark.png differ diff --git a/test/Dockerfile.test-oss.centos b/test/Dockerfile.test-oss.centos new file mode 100644 index 000000000..1efab450e --- /dev/null +++ b/test/Dockerfile.test-oss.centos @@ -0,0 +1,47 @@ +# Description: Dockerfile for testing installation of InfluxDB and clients on CentOS Stream 9. + +# Example build command: +# docker buildx build -t influxdatadocs/oss-centos --file test/Dockerfile.test-oss.centos . + +# Example run command--logs are stored in the volume `influxdatadocs-oss-centos-log`: +# docker run --rm --mount type=volume,src=influxdatadocs-oss-centos-log,dst=/var/log/ influxdatadocs/oss-centos + +FROM dokken/centos-stream-9:latest AS influxdb +LABEL name="test-oss-centos" +LABEL description="InfluxData Docs Test OSS install on CentOS" + +LABEL "com.influxdata.docs"="https://docs.influxdata.com/influxdb/v2/install/?t=Linux" + +ARG INFLUXDB_LATEST_PATCH=2.7.10 +ARG TELEGRAF_LATEST_PATCH=1.32.3 +ARG PUBLIC_SHA=943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515 +# ARG basearch=aarch64 + +# Install InfluxDB keys to verify client installs. + +RUN curl --silent --location -O \ + https://repos.influxdata.com/influxdata-archive.key \ + && echo "${PUBLIC_SHA} influxdata-archive.key" \ + | sha256sum -c && cat influxdata-archive.key \ + | gpg --dearmor \ + | tee /etc/pki/rpm-gpg/RPM-GPG-KEY-influxdata > /dev/null + +# Follow the documentation to add the InfluxData repository to the list of repositories. +RUN cat < /var/log/influxd.log 2>&1 & while ! curl -s http://localhost:8086/health | grep -q '\"status\":\"pass\"'; do sleep 1; done; telegraf --config /etc/telegraf/telegraf.conf --test"] diff --git a/test/Dockerfile.test-oss.ubuntu b/test/Dockerfile.test-oss.ubuntu new file mode 100644 index 000000000..5c5761f8d --- /dev/null +++ b/test/Dockerfile.test-oss.ubuntu @@ -0,0 +1,42 @@ +# Description: Dockerfile for testing installation of InfluxDB and clients on Ubuntu. + +# Example build command: +# docker buildx build -t influxdatadocs/oss-ubuntu --file test/Dockerfile.test-oss.ubuntu . + +# Example run command--logs are stored in the volume `influxdatadocs-oss-ubuntu-log`: +# docker run --rm --mount type=volume,src=influxdatadocs-oss-ubuntu-log,dst=/var/log/ influxdatadocs/oss-ubuntu + + +FROM ubuntu:latest AS influxdb +LABEL name="test-oss-ubuntu" +LABEL description="InfluxData Docs Test OSS install on Ubuntu" + +LABEL "com.influxdata.docs"="https://docs.influxdata.com/influxdb/v2/install/?t=Linux" + +ARG PUBLIC_SHA=943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515 + +# Install gnupg2 and curl to verify client installs. +RUN apt-get update && apt-get install -y gnupg2 curl + +# Install InfluxDB keys to verify client installs. +RUN curl --silent --location -O \ + https://repos.influxdata.com/influxdata-archive.key \ + && echo "${PUBLIC_SHA} influxdata-archive.key" \ + | sha256sum -c && cat influxdata-archive.key \ + | gpg --dearmor \ + | 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' \ + | tee /etc/apt/sources.list.d/influxdata.list + +# Install InfluxDB and clients to use in tests. + +# Follow the Telegraf install instructions (https://docs.influxdata.com/telegraf/v1/install/?t=curl), except for sudo (which isn't available in Docker). +RUN apt-get update && apt-get install -y \ + influxdb2 \ + influxdb2-cli \ + telegraf + + +ENTRYPOINT ["/bin/bash"] +# Run InfluxDB in the background, wait for it to start, and then test Telegraf. +CMD ["-c", "echo $(telegraf version) && echo $(influxd version) && echo $(influx version)", "influxd > /var/log/influxd.log 2>&1 & while ! curl -s http://localhost:8086/health | grep -q '\"status\":\"pass\"'; do sleep 1; done; telegraf --config /etc/telegraf/telegraf.conf --test"] diff --git a/test/scripts/get-container-info.sh b/test/scripts/get-container-info.sh new file mode 100644 index 000000000..3b61ee206 --- /dev/null +++ b/test/scripts/get-container-info.sh @@ -0,0 +1,14 @@ +#!/bin/bash + +# Function to check if the script is running inside a Docker container +is_running_in_docker() { + if [ -f /.dockerenv ]; then + return 0 + fi + + if grep -qE '/docker|/lxc' /proc/1/cgroup; then + return 0 + fi + + return 1 +} diff --git a/test/scripts/prepare-content.sh b/test/scripts/prepare-content.sh index d678362a4..ae2ead0d8 100644 --- a/test/scripts/prepare-content.sh +++ b/test/scripts/prepare-content.sh @@ -35,7 +35,7 @@ function substitute_placeholders { yesterday_timestamp=$(date -u -d "$yesterday_datetime" +%s) # Replace the extracted timestamp with `yesterday_timestamp` - sed -i "s|$specific_timestamp|$yesterday_timestamp|g;" $file + sed -i "s|$specific_timestamp|$yesterday_timestamp|g;" $file fi done @@ -66,14 +66,15 @@ function substitute_placeholders { # Shell-specific replacements. ## In JSON Heredoc sed -i 's|"orgID": "ORG_ID"|"orgID": "$INFLUX_ORG"|g; - s|"name": "BUCKET_NAME"|"name": "$INFLUX_DATABASE"|g;' \ - $file + s|"name": "BUCKET_NAME"|"name": "$INFLUX_DATABASE"|g; + ' $file # Replace remaining placeholders with variables. # If the placeholder is inside of a Python os.getenv() function, don't replace it. # Note the specific use of double quotes for the os.getenv() arguments here. You'll need to use double quotes in your code samples for this to match. sed -i '/os.getenv("ACCOUNT_ID")/! s/ACCOUNT_ID/$ACCOUNT_ID/g; /os.getenv("API_TOKEN")/! s/API_TOKEN/$INFLUX_TOKEN/g; + /os.getenv("PASSWORD_OR_TOKEN")/! s/PASSWORD_OR_TOKEN/$INFLUX_TOKEN/g; /os.getenv("BUCKET_ID")/! s/--bucket-id BUCKET_ID/--bucket-id $INFLUX_BUCKET_ID/g; /os.getenv("BUCKET_NAME")/! s/BUCKET_NAME/$INFLUX_DATABASE/g; /os.getenv("CLUSTER_ID")/! s/CLUSTER_ID/$CLUSTER_ID/g; @@ -88,27 +89,41 @@ function substitute_placeholders { /os.getenv("ORG_ID")/! s/ORG_ID/$INFLUX_ORG/g; /os.getenv("PASSWORD")/! s/PASSWORD/$INFLUX_PASSWORD/g; /os.getenv("ORG_ID")/! s/ORG_ID/$INFLUX_ORG/g; - /os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY_NAME\|RETENTION_POLICY/$INFLUX_RETENTION_POLICY/g; + /os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY_NAME/$INFLUX_RETENTION_POLICY/g; + /os.getenv("RETENTION_POLICY")/! s/RETENTION_POLICY/$INFLUX_RETENTION_POLICY/g; /os.getenv("USERNAME")/! s/USERNAME/$INFLUX_USERNAME/g; + s/exampleuser@influxdata.com/$INFLUX_EMAIL_ADDRESS/g; s/CONFIG_NAME/CONFIG_$(shuf -i 0-100 -n1)/g; s/TEST_RUN/TEST_RUN_$(date +%s)/g; - s|/path/to/custom/assets-dir|/app/custom-assets|g;' \ - $file + s|NUMBER_OF_DAYS|365|g; + s|@path/to/line-protocol.txt|data/home-sensor-data.lp|g; + s|/path/to/custom/assets-dir|/app/custom-assets|g; + ' $file # v2-specific replacements. sed -i 's|https:\/\/us-west-2-1.aws.cloud2.influxdata.com|$INFLUX_HOST|g; - s|{{< latest-patch >}}|${influxdb_latest_patches_v2}|g; - s|{{< latest-patch cli=true >}}|${influxdb_latest_cli_v2}|g;' \ - $file + s|influxdb2-{{< latest-patch >}}|influxdb2-${influxdb_latest_patches_v2}|g; + s|{{< latest-patch cli=true >}}|${influxdb_latest_cli_v2}|g; + s|influxdb2-{{% latest-patch %}}|influxdb2-${influxdb_latest_patches_v2}|g; + s|{{% latest-patch cli=true %}}|${influxdb_latest_cli_v2}|g; + ' $file + + # Telegraf-specific replacements + sed -i 's|telegraf-{{< latest-patch >}}|telegraf-${telegraf_latest_patches_v1}|g; + s|telegraf-{{% latest-patch %}}|telegraf-${telegraf_latest_patches_v1}|g; + s/--input-filter \[:\]/--input-filter cpu:influxdb/g; + s/--output-filter \[:\]/--output-filter influxdb_v2:file/g; + ' $file # Skip package manager commands. sed -i 's|sudo dpkg.*$||g; - s|sudo yum.*$||g;' \ - $file + s|sudo yum.*$||g; + ' $file # Environment-specific replacements. - sed -i 's|sudo ||g;' \ - $file + # You can't use sudo with Docker. + sed -i 's|sudo ||g; + ' $file fi done } diff --git a/yarn.lock b/yarn.lock index cafc7ab6a..7dfdcf64f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3,32 +3,23 @@ "@babel/code-frame@^7.0.0": - version "7.24.7" - resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.24.7.tgz#882fd9e09e8ee324e496bd040401c6f046ef4465" - integrity sha512-BcYH1CVJBO9tvyIZ2jVeXgSIMvGZ2FDRvDdOIVQyuklNKSsx+eppDEBq/g47Ayw+RqNFE+URvOShmf+f/qwAlA== + version "7.26.2" + resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.26.2.tgz#4b5fab97d33338eff916235055f0ebc21e573a85" + integrity sha512-RJlIHRueQgwWitWgF8OdFYGZX328Ax5BCemNGlqHfplnRT9ESi8JkFlvaVYbS+UubVY6dpv87Fs2u5M29iNFVQ== dependencies: - "@babel/highlight" "^7.24.7" - picocolors "^1.0.0" - -"@babel/helper-validator-identifier@^7.24.7": - version "7.24.7" - resolved "https://registry.yarnpkg.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.24.7.tgz#75b889cfaf9e35c2aaf42cf0d72c8e91719251db" - integrity sha512-rR+PBcQ1SMQDDyF6X0wxtG8QyLCgUB0eRAGguqRLfkCA87l7yAP7ehq8SNj96OOGTO8OBV70KhuFYcIkHXOg0w== - -"@babel/highlight@^7.24.7": - version "7.24.7" - resolved "https://registry.yarnpkg.com/@babel/highlight/-/highlight-7.24.7.tgz#a05ab1df134b286558aae0ed41e6c5f731bf409d" - integrity sha512-EStJpq4OuY8xYfhGVXngigBJRWxftKX9ksiGDnmlY3o7B/V7KIAc9X4oiK87uPJSc/vs5L869bem5fhZa8caZw== - dependencies: - "@babel/helper-validator-identifier" "^7.24.7" - chalk "^2.4.2" + "@babel/helper-validator-identifier" "^7.25.9" js-tokens "^4.0.0" picocolors "^1.0.0" +"@babel/helper-validator-identifier@^7.25.9": + version "7.25.9" + resolved "https://registry.yarnpkg.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.25.9.tgz#24b64e2c3ec7cd3b3c547729b8d16871f22cbdc7" + integrity sha512-Ed61U6XJc3CVRfkERJWDz4dJwKe7iLmmJsbOGu9wSloNSFttHV0I8g6UAgb7qnK5ly5bGLPd4oXZlxCdANBOWQ== + "@evilmartians/lefthook@^1.7.1": - version "1.7.14" - resolved "https://registry.yarnpkg.com/@evilmartians/lefthook/-/lefthook-1.7.14.tgz#3fce9d4c91c23232f02bab592ce914713880bb8d" - integrity sha512-0FPRdmd7hIZXjTQKQjLnmqxx4xGRIM1oGN9pJ4PyI14tOqEAwstmLIbauqQpTVTj3MAPeylsQVXh9RGaq/F2/A== + version "1.8.5" + resolved "https://registry.yarnpkg.com/@evilmartians/lefthook/-/lefthook-1.8.5.tgz#ce4805e7a67374d953946ea93a666939019123e9" + integrity sha512-TuAL6W+bj2DqYxqm5JnFi3s7RnjpU/IUxxHFZWUHNytZ+HDQfkceogo+1DlSBFXFva2V21CSaDkeWJJHOmmECw== "@isaacs/cliui@^8.0.2": version "8.0.2" @@ -96,9 +87,9 @@ integrity sha512-37i+OaWTh9qeK4LSHPsyRC7NahnGotNuZvjLSgcPzblpHB3rrCJxAOgI5gCdKm7coonsaX1Of0ILiTcnZjbfxA== "@vvago/vale@^3.4.2": - version "3.7.0" - resolved "https://registry.yarnpkg.com/@vvago/vale/-/vale-3.7.0.tgz#fcae449cdd4ba2578f1242250d06226c84ce96f2" - integrity sha512-Jju27u/bQhQ0eogBTcTeqlpVF/5PejO3HFjuaD9tLVPgQ/1pb2pux0NMRq4idOtH8xotwyBO/dyPT9EbvnpGNQ== + version "3.9.1" + resolved "https://registry.yarnpkg.com/@vvago/vale/-/vale-3.9.1.tgz#8b34b30413ad087034fe171f6d8a21dc64a69bbe" + integrity sha512-EEit9vmdArdr+YE3+dnedX/KPecPV1spcwjRlsYH5FugREVkjyvx+TCwcxVlddJ1/tWS3vQ1DYWZBUZ8Hlikpg== dependencies: axios "^1.4.0" rimraf "^5.0.0" @@ -111,16 +102,9 @@ ansi-regex@^5.0.1: integrity sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ== ansi-regex@^6.0.1: - version "6.0.1" - resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-6.0.1.tgz#3183e38fae9a65d7cb5e53945cd5897d0260a06a" - integrity sha512-n5M855fKb2SsfMIiFFoVrABHJC8QtHwVx+mHWP3QcEqBHYienj5dHSgjbxtC0WEZXYt4wcD6zrQElDPhFuZgfA== - -ansi-styles@^3.2.1: - version "3.2.1" - resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-3.2.1.tgz#41fbb20243e50b12be0f04b8dedbf07520ce841d" - integrity sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA== - dependencies: - color-convert "^1.9.0" + version "6.1.0" + resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-6.1.0.tgz#95ec409c69619d6cb1b8b34f14b660ef28ebd654" + integrity sha512-7HSX4QQb4CspciLpVFwyRe79O3xsIZDDLER21kERQ71oaPodF8jL725AgJMFAYbooIqolJoRLuM81SpeUkpkvA== ansi-styles@^4.0.0: version "4.3.0" @@ -165,9 +149,9 @@ autoprefixer@>=10.2.5: postcss-value-parser "^4.2.0" axios@^1.4.0, axios@^1.7.4: - version "1.7.4" - resolved "https://registry.yarnpkg.com/axios/-/axios-1.7.4.tgz#4c8ded1b43683c8dd362973c393f3ede24052aa2" - integrity sha512-DukmaFRnY6AzAALSH4J2M3k6PkaC+MfaAGdEERRWcC9q3/TWQwLpHR8ZRLKTdQ3aBDL64EdluRDjJqKw+BPZEw== + version "1.7.9" + resolved "https://registry.yarnpkg.com/axios/-/axios-1.7.9.tgz#d7d071380c132a24accda1b2cfc1535b79ec650a" + integrity sha512-LhLcE7Hbiryz8oMDdDptSrWowmB4Bl6RCt6sIJKpRB4XtVf0iEgewX3au/pJqm+Py1kCASkb/FFKjxQaLtxJvw== dependencies: follow-redirects "^1.15.6" form-data "^4.0.0" @@ -237,14 +221,14 @@ braces@^3.0.3, braces@~3.0.2: fill-range "^7.1.1" browserslist@^4.23.3: - version "4.23.3" - resolved "https://registry.yarnpkg.com/browserslist/-/browserslist-4.23.3.tgz#debb029d3c93ebc97ffbc8d9cbb03403e227c800" - integrity sha512-btwCFJVjI4YWDNfau8RhZ+B1Q/VLoUITrm3RlP6y1tYGWIOa+InuYiRGXUBXo8nA1qKmHMyLB/iVQg5TT4eFoA== + version "4.24.2" + resolved "https://registry.yarnpkg.com/browserslist/-/browserslist-4.24.2.tgz#f5845bc91069dbd55ee89faf9822e1d885d16580" + integrity sha512-ZIc+Q62revdMcqC6aChtW4jz3My3klmCO1fEmINZY/8J3EpBg5/A/D0AKmBveUh6pgoeycoMkVMko84tuYS+Gg== dependencies: - caniuse-lite "^1.0.30001646" - electron-to-chromium "^1.5.4" + caniuse-lite "^1.0.30001669" + electron-to-chromium "^1.5.41" node-releases "^2.0.18" - update-browserslist-db "^1.1.0" + update-browserslist-db "^1.1.1" buffer-alloc-unsafe@^1.1.0: version "1.1.0" @@ -305,10 +289,10 @@ cacheable-request@^10.2.8: normalize-url "^8.0.0" responselike "^3.0.0" -caniuse-lite@^1.0.30001646: - version "1.0.30001651" - resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001651.tgz#52de59529e8b02b1aedcaaf5c05d9e23c0c28138" - integrity sha512-9Cf+Xv1jJNe1xPZLGuUXLNkE1BoDkqRqYyFJ9TDYSqhduqA4hu4oR9HluGoWYQC/aj8WHjsGVV+bwkh0+tegRg== +caniuse-lite@^1.0.30001646, caniuse-lite@^1.0.30001669: + version "1.0.30001686" + resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001686.tgz#0e04b8d90de8753188e93c9989d56cb19d902670" + integrity sha512-Y7deg0Aergpa24M3qLC5xjNklnKnhsmSyR/V89dLZ1n0ucJIFNs7PgR2Yfa/Zf6W79SbBicgtGxZr2juHkEUIA== careful-downloader@^3.0.0: version "3.0.0" @@ -329,15 +313,6 @@ chainsaw@~0.1.0: dependencies: traverse ">=0.3.0 <0.4" -chalk@^2.4.2: - version "2.4.2" - resolved "https://registry.yarnpkg.com/chalk/-/chalk-2.4.2.tgz#cd42541677a54333cf541a49108c1432b44c9424" - integrity sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ== - dependencies: - ansi-styles "^3.2.1" - escape-string-regexp "^1.0.5" - supports-color "^5.3.0" - chalk@^5.0.0: version "5.3.0" resolved "https://registry.yarnpkg.com/chalk/-/chalk-5.3.0.tgz#67c20a7ebef70e7f3970a01f90fa210cb6860385" @@ -372,13 +347,6 @@ cliui@^8.0.1: strip-ansi "^6.0.1" wrap-ansi "^7.0.0" -color-convert@^1.9.0: - version "1.9.3" - resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-1.9.3.tgz#bb71850690e1f136567de629d2d5471deda4c1e8" - integrity sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg== - dependencies: - color-name "1.1.3" - color-convert@^2.0.1: version "2.0.1" resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-2.0.1.tgz#72d3a68d598c9bdb3af2ad1e84f21d896abd4de3" @@ -386,11 +354,6 @@ color-convert@^2.0.1: dependencies: color-name "~1.1.4" -color-name@1.1.3: - version "1.1.3" - resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.3.tgz#a7d0558bd89c42f795dd42328f740831ca53bc25" - integrity sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw== - color-name@~1.1.4: version "1.1.4" resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2" @@ -419,9 +382,9 @@ core-util-is@~1.0.0: integrity sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ== cross-spawn@^7.0.0: - version "7.0.3" - resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.3.tgz#f73a85b9d5d41d045551c177e2882d4ac85728a6" - integrity sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w== + version "7.0.6" + resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.6.tgz#8a58fe78f00dcd70c370451759dfbfaf03e8ee9f" + integrity sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA== dependencies: path-key "^3.1.0" shebang-command "^2.0.0" @@ -435,11 +398,11 @@ crypto-random-string@^4.0.0: type-fest "^1.0.1" debug@^4.3.4: - version "4.3.6" - resolved "https://registry.yarnpkg.com/debug/-/debug-4.3.6.tgz#2ab2c38fbaffebf8aa95fdfe6d88438c7a13c52b" - integrity sha512-O/09Bd4Z1fBrU4VzkhFqVgpPzaGbw6Sm9FEkBT1A/YBXQFGuuSxa1dN2nxgxS34JmKXqYx8CZAwEVoJFImUXIg== + version "4.3.7" + resolved "https://registry.yarnpkg.com/debug/-/debug-4.3.7.tgz#87945b4151a011d76d95a198d7111c865c360a52" + integrity sha512-Er2nc/H7RrMXZBFCEim6TCmMk02Z8vLC2Rbi1KEBggpo0fS6l0S1nnapwmIi3yW/+GOJap1Krg4w0Hg80oCqgQ== dependencies: - ms "2.1.2" + ms "^2.1.3" decompress-response@^6.0.0: version "6.0.0" @@ -533,10 +496,10 @@ eastasianwidth@^0.2.0: resolved "https://registry.yarnpkg.com/eastasianwidth/-/eastasianwidth-0.2.0.tgz#696ce2ec0aa0e6ea93a397ffcf24aa7840c827cb" integrity sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA== -electron-to-chromium@^1.5.4: - version "1.5.12" - resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.12.tgz#ee31756eaa2e06f2aa606f170b7ad06dd402b4e4" - integrity sha512-tIhPkdlEoCL1Y+PToq3zRNehUaKp3wBX/sr7aclAWdIWjvqAe/Im/H0SiCM4c1Q8BLPHCdoJTol+ZblflydehA== +electron-to-chromium@^1.5.41: + version "1.5.71" + resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.71.tgz#d8b5dba1e55b320f2f4e9b1ca80738f53fcfec2b" + integrity sha512-dB68l59BI75W1BUGVTAEJy45CEVuEGy9qPVVQ8pnHyHMn36PLPPoE1mjLH+lo9rKulO3HC2OhbACI/8tCqJBcA== emoji-regex@^8.0.0: version "8.0.0" @@ -562,15 +525,10 @@ error-ex@^1.3.1: dependencies: is-arrayish "^0.2.1" -escalade@^3.1.1, escalade@^3.1.2: - version "3.1.2" - resolved "https://registry.yarnpkg.com/escalade/-/escalade-3.1.2.tgz#54076e9ab29ea5bf3d8f1ed62acffbb88272df27" - integrity sha512-ErCHMCae19vR8vQGe50xIsVomy19rg6gFu3+r3jkEO46suLMWBksvVyoGgQV+jOfl84ZSOSlmv6Gxa89PmTGmA== - -escape-string-regexp@^1.0.5: - version "1.0.5" - resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz#1b61c0562190a8dff6ae3bb2cf0200ca130b86d4" - integrity sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg== +escalade@^3.1.1, escalade@^3.2.0: + version "3.2.0" + resolved "https://registry.yarnpkg.com/escalade/-/escalade-3.2.0.tgz#011a3f69856ba189dffa7dc8fcce99d2a87903e5" + integrity sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA== fast-glob@^3.3.2: version "3.3.2" @@ -628,9 +586,9 @@ find-up@^6.3.0: path-exists "^5.0.0" follow-redirects@^1.15.6: - version "1.15.6" - resolved "https://registry.yarnpkg.com/follow-redirects/-/follow-redirects-1.15.6.tgz#7f815c0cda4249c74ff09e95ef97c23b5fd0399b" - integrity sha512-wWN62YITEaOpSK584EZXJafH1AGpO8RVgElfkuXbTOrPX4fIfOyEpW/CsiNd8JdYrAoOvafRTOEnvsO++qCqFA== + version "1.15.9" + resolved "https://registry.yarnpkg.com/follow-redirects/-/follow-redirects-1.15.9.tgz#a604fa10e443bf98ca94228d9eebcc2e8a2c8ee1" + integrity sha512-gew4GsXizNgdoRyqmyfMHyAmXsZDk6mHkSxZFCzW9gwlbtOW44CDtYavM+y+72qD/Vq2l550kMF52DT8fOLJqQ== foreground-child@^3.1.0: version "3.3.0" @@ -646,9 +604,9 @@ form-data-encoder@^2.1.2: integrity sha512-yDYSgNMraqvnxiEXO4hi88+YZxaHC6QKzb5N84iRCTDeRO7ZALpir/lVmf/uXUhnwUr2O4HU8s/n6x+yNjQkHw== form-data@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/form-data/-/form-data-4.0.0.tgz#93919daeaf361ee529584b9b31664dc12c9fa452" - integrity sha512-ETEklSGi5t0QMZuiXoA/Q6vcnxcLQP5vdugSpuAyi6SVGi2clPPp+xgEhuMaHC+zGgn31Kd235W35f7Hykkaww== + version "4.0.1" + resolved "https://registry.yarnpkg.com/form-data/-/form-data-4.0.1.tgz#ba1076daaaa5bfd7e99c1a6cb02aa0a5cff90d48" + integrity sha512-tzN8e4TX8+kkxGPK8D5u0FNmjPUjw3lwC9lSLxxoB/+GtsJG91CO8bSWy73APlgAZzZbXEYZJuxjkHH2w+Ezhw== dependencies: asynckit "^0.4.0" combined-stream "^1.0.8" @@ -798,11 +756,6 @@ graceful-fs@^4.1.10, graceful-fs@^4.1.2, graceful-fs@^4.1.6, graceful-fs@^4.2.0, resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.11.tgz#4183e4e8bf08bb6e05bbb2f7d2e0c8f712ca40e3" integrity sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ== -has-flag@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-3.0.0.tgz#b5d454dc2199ae225699f3467e5a07f3b955bafd" - integrity sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw== - hasown@^2.0.2: version "2.0.2" resolved "https://registry.yarnpkg.com/hasown/-/hasown-2.0.2.tgz#003eaf91be7adc372e84ec59dc37252cedb80003" @@ -831,9 +784,9 @@ http2-wrapper@^2.1.10: resolve-alpn "^1.2.0" hugo-extended@>=0.101.0: - version "0.132.2" - resolved "https://registry.yarnpkg.com/hugo-extended/-/hugo-extended-0.132.2.tgz#cca3d82d7ffd6145d535a787d3963215c8af075b" - integrity sha512-KsEeBOratmFHaX8RnJSnkrqy4HaYn+GctHJRtUtoZJZ/mE1knogBKeB4Ss6T3juBwBS9PVF7hb9XSkjeJUAo2Q== + version "0.139.2" + resolved "https://registry.yarnpkg.com/hugo-extended/-/hugo-extended-0.139.2.tgz#123ba6092ba8bb751c62545227238b62bbc47156" + integrity sha512-svbD47E2fkPVFEgNNx6zB5fPRZ0yPPgW4J/+OU0+1LS5nkSVVDpxWZe0od1g4Eekn/2TFSje1LBdojIJPeotnQ== dependencies: careful-downloader "^3.0.0" log-symbols "^5.1.0" @@ -875,9 +828,9 @@ is-binary-path@~2.1.0: binary-extensions "^2.0.0" is-core-module@^2.5.0: - version "2.15.0" - resolved "https://registry.yarnpkg.com/is-core-module/-/is-core-module-2.15.0.tgz#71c72ec5442ace7e76b306e9d48db361f22699ea" - integrity sha512-Dd+Lb2/zvk9SKy1TGCt1wFJFo/MWBPMX5x7KcvLajWTGuomczdQX61PvY5yK6SVACwpoexWo81IfFyoKY2QnTA== + version "2.15.1" + resolved "https://registry.yarnpkg.com/is-core-module/-/is-core-module-2.15.1.tgz#a7363a25bee942fefab0de13bf6aa372c82dcc37" + integrity sha512-z0vtXSwucUJtANQWldhbtbt7BnL0vxiFjIdDLAatwhDYty2bad6s+rijD6Ri4YuYJubLzIJLUidCh09e1djEVQ== dependencies: hasown "^2.0.2" @@ -979,9 +932,9 @@ jsonfile@^6.0.1: graceful-fs "^4.1.6" jsox@^1.2.119: - version "1.2.119" - resolved "https://registry.yarnpkg.com/jsox/-/jsox-1.2.119.tgz#decc12b6d3948d89460da6c5e144ee76c1d054ce" - integrity sha512-f37obwxWKKuylcaOzNlUlzfDvURSCpqTXs8yEivhvsp86D/DTIySxP4v5Qdlg24qCuzDSZ0mJr3krc/f7TZ/5A== + version "1.2.121" + resolved "https://registry.yarnpkg.com/jsox/-/jsox-1.2.121.tgz#e51c1f42188772a3493a56b805f64cbd06c39779" + integrity sha512-9Ag50tKhpTwS6r5wh3MJSAvpSof0UBr39Pto8OnzFT32Z/pAbxAsKHzyvsyMEHVslELvHyO/4/jaQELHk8wDcw== keyv@^4.5.3: version "4.5.4" @@ -991,9 +944,9 @@ keyv@^4.5.3: json-buffer "3.0.1" lilconfig@^3.1.1: - version "3.1.2" - resolved "https://registry.yarnpkg.com/lilconfig/-/lilconfig-3.1.2.tgz#e4a7c3cb549e3a606c8dcc32e5ae1005e62c05cb" - integrity sha512-eop+wDAvpItUys0FWkHIKeC9ybYrTGbU41U5K7+bttZZeohvnY7M9dZ5kB21GNWiFT2q1OoPTvncPCgSOVO5ow== + version "3.1.3" + resolved "https://registry.yarnpkg.com/lilconfig/-/lilconfig-3.1.3.tgz#a1bcfd6257f9585bf5ae14ceeebb7b559025e4c4" + integrity sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw== lines-and-columns@^1.1.6: version "1.2.4" @@ -1050,9 +1003,9 @@ merge2@^1.3.0: integrity sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg== micromatch@^4.0.4: - version "4.0.7" - resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.7.tgz#33e8190d9fe474a9895525f5618eee136d46c2e5" - integrity sha512-LPP/3KorzCwBxfeUuZmaR6bG2kdeHSbe0P2tY3FLRU4vYrjYz5hI4QZwV0njUx3jeuKe67YukQ1LSPZBKDqO/Q== + version "4.0.8" + resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.8.tgz#d66fa18f3a47076789320b9b1af32bd86d9fa202" + integrity sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA== dependencies: braces "^3.0.3" picomatch "^2.3.1" @@ -1140,15 +1093,15 @@ moo@^0.5.0: resolved "https://registry.yarnpkg.com/moo/-/moo-0.5.2.tgz#f9fe82473bc7c184b0d32e2215d3f6e67278733c" integrity sha512-iSAJLHYKnX41mKcJKjqvnAN9sf0LMDTXDEvFv+ffuRR9a1MIuXLjMNL6EsnDHSkKLTWNqQQ5uo61P4EbU4NU+Q== -ms@2.1.2: - version "2.1.2" - resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.2.tgz#d09d1f357b443f493382a8eb3ccd183872ae6009" - integrity sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w== +ms@^2.1.3: + version "2.1.3" + resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2" + integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== nanoid@^3.3.7: - version "3.3.7" - resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.7.tgz#d0c301a691bc8d54efa0a2226ccf3fe2fd656bd8" - integrity sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g== + version "3.3.8" + resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.8.tgz#b1be3030bee36aaff18bacb375e5cce521684baf" + integrity sha512-WNLf5Sd8oZxOm+TzppcYk8gVOgP+l58xNy58D0nbUnOxOWRWvlcCV4kUF7ltmI6PsrLl/BgKEyS4mqsGChFN0w== nearley@^2.20.1: version "2.20.1" @@ -1229,9 +1182,9 @@ p-locate@^6.0.0: p-limit "^4.0.0" package-json-from-dist@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/package-json-from-dist/-/package-json-from-dist-1.0.0.tgz#e501cd3094b278495eb4258d4c9f6d5ac3019f00" - integrity sha512-dATvCeZN/8wQsGywez1mzHtTlP22H8OEfPrVMLNr4/eGa+ijtLn/6M5f0dY8UKNrC2O9UCU6SSoG3qRKnt7STw== + version "1.0.1" + resolved "https://registry.yarnpkg.com/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz#4f1471a010827a86f94cfd9b0727e36d267de505" + integrity sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw== parse-json@^5.2.0: version "5.2.0" @@ -1276,10 +1229,10 @@ pend@~1.2.0: resolved "https://registry.yarnpkg.com/pend/-/pend-1.2.0.tgz#7a57eb550a6783f9115331fcf4663d5c8e007a50" integrity sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg== -picocolors@^1.0.0, picocolors@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/picocolors/-/picocolors-1.0.1.tgz#a8ad579b571952f0e5d25892de5445bcfe25aaa1" - integrity sha512-anP1Z8qwhkbmu7MFP5iTt+wQKXgwzf7zTyGlcdzabySa9vd0Xt392U0rVmz9poOaBj0uHJKyyo9/upk0HrEQew== +picocolors@^1.0.0, picocolors@^1.0.1, picocolors@^1.1.0, picocolors@^1.1.1: + version "1.1.1" + resolved "https://registry.yarnpkg.com/picocolors/-/picocolors-1.1.1.tgz#3d321af3eab939b083c8f929a1d12cda81c26b6b" + integrity sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA== picomatch@^2.0.4, picomatch@^2.2.1, picomatch@^2.3.1: version "2.3.1" @@ -1348,13 +1301,13 @@ postcss-value-parser@^4.2.0: integrity sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ== postcss@>=8.4.31: - version "8.4.41" - resolved "https://registry.yarnpkg.com/postcss/-/postcss-8.4.41.tgz#d6104d3ba272d882fe18fc07d15dc2da62fa2681" - integrity sha512-TesUflQ0WKZqAvg52PWL6kHgLKP6xB6heTOdoYM0Wt2UHyxNa4K25EZZMgKns3BH1RLVbZCREPpLY0rhnNoHVQ== + version "8.4.49" + resolved "https://registry.yarnpkg.com/postcss/-/postcss-8.4.49.tgz#4ea479048ab059ab3ae61d082190fabfd994fe19" + integrity sha512-OCVPnIObs4N29kxTjzLfUryOkvZEq+pf8jTF0lg8E7uETuWHA+v7j3c/xJmiqpX450191LlmZfUKkXxkTry7nA== dependencies: nanoid "^3.3.7" - picocolors "^1.0.1" - source-map-js "^1.2.0" + picocolors "^1.1.1" + source-map-js "^1.2.1" prettier-plugin-sql@^0.18.0: version "0.18.1" @@ -1367,9 +1320,9 @@ prettier-plugin-sql@^0.18.0: tslib "^2.6.2" prettier@^3.2.5: - version "3.3.3" - resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.3.3.tgz#30c54fe0be0d8d12e6ae61dbb10109ea00d53105" - integrity sha512-i2tDNA0O5IrMO757lfrdQZCc2jPNDVntV0m/+4whiDfWaTKfMNgR7Qz0NAeGz/nRqF4m5/6CLzbP4/liHt12Ew== + version "3.4.2" + resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.4.2.tgz#a5ce1fb522a588bf2b78ca44c6e6fe5aa5a2b13f" + integrity sha512-e9MewbtFo+Fevyuxn/4rrcDAaq0IYxPGLvObpQjiZBMAzB9IGmzlnG9RZy3FFas+eBMu2vA0CszMeduow5dIuQ== pretty-hrtime@^1.0.3: version "1.0.3" @@ -1552,10 +1505,10 @@ slash@^5.0.0, slash@^5.1.0: resolved "https://registry.yarnpkg.com/slash/-/slash-5.1.0.tgz#be3adddcdf09ac38eebe8dcdc7b1a57a75b095ce" integrity sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg== -source-map-js@^1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/source-map-js/-/source-map-js-1.2.0.tgz#16b809c162517b5b8c3e7dcd315a2a5c2612b2af" - integrity sha512-itJW8lvSA0TXEphiRoawsCksnlf8SyvmFzIhltqAHluXd88pkCd+cXJVHTDwdCr0IzwptSm035IHQktUu1QUMg== +source-map-js@^1.2.1: + version "1.2.1" + resolved "https://registry.yarnpkg.com/source-map-js/-/source-map-js-1.2.1.tgz#1ce5650fddd87abc099eda37dcff024c2667ae46" + integrity sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA== spdx-correct@^3.0.0: version "3.2.0" @@ -1584,9 +1537,9 @@ spdx-license-ids@^3.0.0: integrity sha512-jg25NiDV/1fLtSgEgyvVyDunvaNHbuwF9lfNV17gSmPFAlYzdfNBlLtLzXTevwkPj7DhGbmN9VnmJIgLnhvaBw== sql-formatter@^15.0.2: - version "15.4.0" - resolved "https://registry.yarnpkg.com/sql-formatter/-/sql-formatter-15.4.0.tgz#b4236760f96132ee786e0acb58bc5a740f11f1b9" - integrity sha512-h3uVulRmOfARvDejuSzs9GMbua/UmGCKiP08zyHT1PnG376zk9CHVsDAcKIc9TcIwIrDH3YULWwI4PrXdmLRVw== + version "15.4.6" + resolved "https://registry.yarnpkg.com/sql-formatter/-/sql-formatter-15.4.6.tgz#6e00e967ce86aa70daa0249097b2d3941e4e66f4" + integrity sha512-aH6kwvJpylljHqXe+zpie0Q5snL3uerDLLhjPEBjDCVK1NMRFq4nMJbuPJWYp08LaaaJJgBhShAdAfspcBYY0Q== dependencies: argparse "^2.0.1" get-stdin "=8.0.0" @@ -1654,13 +1607,6 @@ strip-dirs@^2.0.0: dependencies: is-natural-number "^4.0.1" -supports-color@^5.3.0: - version "5.5.0" - resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-5.5.0.tgz#e2e69a44ac8772f78a1ec0b35b689df6530efc8f" - integrity sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow== - dependencies: - has-flag "^3.0.0" - tar-stream@^1.5.2: version "1.6.2" resolved "https://registry.yarnpkg.com/tar-stream/-/tar-stream-1.6.2.tgz#8ea55dab37972253d9a9af90fdcd559ae435c555" @@ -1729,9 +1675,9 @@ to-regex-range@^5.0.1: integrity sha512-iawgk0hLP3SxGKDfnDJf8wTz4p2qImnyihM5Hh/sGvQ3K37dPi/w8sRhdNIxYA1TwFwc5mDhIJq+O0RsvXBKdQ== tslib@^2.6.2: - version "2.6.3" - resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.6.3.tgz#0438f810ad7a9edcde7a241c3d80db693c8cbfe0" - integrity sha512-xNvxJEOUiWPGhUuUdQgAJPKOOJfGnIyKySOc09XkKsgdUV/3E2zvwZYdejjmRgPCgcym1juLH3226yA7sEFJKQ== + version "2.8.1" + resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.8.1.tgz#612efe4ed235d567e8aba5f2a5fab70280ade83f" + integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w== type-fest@^1.0.1: version "1.4.0" @@ -1784,13 +1730,13 @@ unzipper@^0.10.14: readable-stream "~2.3.6" setimmediate "~1.0.4" -update-browserslist-db@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/update-browserslist-db/-/update-browserslist-db-1.1.0.tgz#7ca61c0d8650766090728046e416a8cde682859e" - integrity sha512-EdRAaAyk2cUE1wOf2DkEhzxqOQvFOoRJFNS6NeyJ01Gp2beMRpBAINjM2iDXE3KCuKhwnvHIQCJm6ThL2Z+HzQ== +update-browserslist-db@^1.1.1: + version "1.1.1" + resolved "https://registry.yarnpkg.com/update-browserslist-db/-/update-browserslist-db-1.1.1.tgz#80846fba1d79e82547fb661f8d141e0945755fe5" + integrity sha512-R8UzCaa9Az+38REPiJ1tXlImTJXlVfgHZsglwBD/k6nj76ctsH1E3q4doGrukiLQd3sGQYu56r5+lo5r94l29A== dependencies: - escalade "^3.1.2" - picocolors "^1.0.1" + escalade "^3.2.0" + picocolors "^1.1.0" util-deprecate@~1.0.1: version "1.0.2" @@ -1860,9 +1806,9 @@ yallist@^4.0.0: integrity sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A== yaml@^2.4.2: - version "2.5.0" - resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.5.0.tgz#c6165a721cf8000e91c36490a41d7be25176cf5d" - integrity sha512-2wWLbGbYDiSqqIKoPjar3MPgB94ErzCtrNE1FdqGuaO0pi2JGjmE8aW8TDZwzU7vuxcGRdL/4gPQwQ7hD5AMSw== + version "2.6.1" + resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.6.1.tgz#42f2b1ba89203f374609572d5349fb8686500773" + integrity sha512-7r0XPzioN/Q9kXBro/XPnA6kznR73DHq+GXh5ON7ZozRO6aMjbmiBuKste2wslTFkC5d1dw0GooOCepZXJ2SAg== yargs-parser@^21.1.1: version "21.1.1"