From 2a0144aee1f68fe83273efab688dc613cc318fd6 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 15 Feb 2024 16:09:12 -0600 Subject: [PATCH] fix: OSS API documentation documents InfluxDB Cloud features (https://github.com/influxdata/docs-v2/issues/5320) - Effectively removes property from OSS Query API. - Re-diverges Query schema, removing from OSS and keeping it in Cloud. - Re-diverges paths with oss- and cloud-specific schemas. --- contracts/cloud-diff.yml | 687 ++++++++++++++++++++++++-- contracts/cloud.json | 421 ++++++++-------- contracts/cloud.yml | 487 ++++++++++-------- contracts/common.yml | 269 ++-------- contracts/oss-diff.yml | 650 ++++++++++++++++++++++-- contracts/oss.json | 416 ++++++++-------- contracts/oss.yml | 460 +++++++++-------- contracts/ref/cloud.yml | 51 +- contracts/ref/oss.yml | 78 +-- src/cloud.yml | 4 + src/{common => cloud}/paths/query.yml | 12 +- src/cloud/schemas/Query.yml | 50 ++ src/common/_paths.yml | 2 - src/common/_schemas.yml | 2 - src/oss.yml | 4 + src/oss/paths/query.yml | 168 +++++++ src/oss/schemas/Query.yml | 23 + 17 files changed, 2631 insertions(+), 1153 deletions(-) rename src/{common => cloud}/paths/query.yml (94%) create mode 100644 src/cloud/schemas/Query.yml create mode 100644 src/oss/paths/query.yml create mode 100644 src/oss/schemas/Query.yml diff --git a/contracts/cloud-diff.yml b/contracts/cloud-diff.yml index fbf071370..f2a84109e 100644 --- a/contracts/cloud-diff.yml +++ b/contracts/cloud-diff.yml @@ -301,7 +301,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -351,7 +351,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -667,7 +667,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' post: @@ -778,7 +778,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' x-codeSamples: @@ -862,7 +862,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' patch: @@ -947,7 +947,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' x-codeSamples: @@ -2895,6 +2895,201 @@ paths: application/json: schema: $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' + /query: + post: + operationId: PostQuery + tags: + - Data I/O endpoints + - Query + summary: Query data + description: | + Retrieves data from buckets. + + Use this endpoint to send a Flux query request and retrieve data from a bucket. + + #### Rate limits (with InfluxDB Cloud) + + `read` rate limits apply. + For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). + + #### Related guides + + - [Query with the InfluxDB API]({{% INFLUXDB_DOCS_URL %}}/query-data/execute-queries/influx-api/) + - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) + parameters: + - $ref: '#/paths/~1users/get/parameters/0' + - in: header + name: Accept-Encoding + description: The content encoding (usually a compression algorithm) that the client can understand. + schema: + type: string + description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.' + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/json + - application/vnd.flux + - in: query + name: org + description: | + An organization name or ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + - in: query + name: orgID + description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ + --header 'Content-Type: application/vnd.flux' \ + --header 'Accept: application/csv \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' + requestBody: + description: Flux query or specification to execute + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/vnd.flux: + schema: + type: string + example: | + from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement") + responses: + '200': + description: Success. The response body contains query results. + headers: + Content-Encoding: + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. + schema: + type: string + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: 'The trace ID, if generated, of the request.' + schema: + type: string + description: Trace ID of a request. + content: + application/csv: + schema: + type: string + example: | + result,table,_start,_stop,_time,region,host,_value + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + '400': + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. + content: + application/json: + schema: + $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + '401': + $ref: '#/paths/~1tasks/get/responses/401' + '404': + description: | + Not found. + A requested resource was not found. + The response body contains the requested resource type and the name value + (if you passed it)--for example: + + - `"organization name \"my-org\" not found"` + - `"organization not found"`: indicates you passed an ID that did not match + an organization. + content: + application/json: + schema: + $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' + examples: + org-not-found: + summary: Organization name not found + value: + code: not found + message: organization name "my-org" not found + bucket-not-found: + summary: Bucket name not found + value: + code: not found + message: bucket "air_sensor" not found + orgID-not-found: + summary: Organization ID not found + value: + code: not found + message: organization not found + '429': + description: | + #### InfluxDB Cloud: + - returns this error if a **read** or **write** request exceeds your + plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum + [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits) + - returns `Retry-After` header that describes when to try the write again. + + #### InfluxDB OSS: + - doesn't return this error. + headers: + Retry-After: + description: Non-negative decimal integer indicating seconds to wait before retrying the request. + schema: + type: integer + format: int32 + '500': + $ref: '#/paths/~1users/get/responses/500' + default: + $ref: '#/paths/~1tasks/get/responses/default' /tasks: get: operationId: GetTasks @@ -3330,35 +3525,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - description: | - Not found. - A requested resource was not found. - The response body contains the requested resource type and the name value - (if you passed it)--for example: - - - `"organization name \"my-org\" not found"` - - `"organization not found"`: indicates you passed an ID that did not match - an organization. - content: - application/json: - schema: - $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' - examples: - org-not-found: - summary: Organization name not found - value: - code: not found - message: organization name "my-org" not found - bucket-not-found: - summary: Bucket name not found - value: - code: not found - message: bucket "air_sensor" not found - orgID-not-found: - summary: Organization ID not found - value: - code: not found - message: organization not found + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -3452,7 +3619,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -3485,7 +3652,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -4328,6 +4495,452 @@ components: type: array items: $ref: '#/components/schemas/MeasurementSchemaColumn' + Query: + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + description: Represents a source from a single file + type: object + properties: + type: + description: Type of AST node + type: string + name: + description: The name of the file. + type: string + package: + description: Defines a package identifier + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + name: + description: A valid Flux identifier + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + name: + type: string + imports: + description: A list of package imports + type: array + items: + description: Declares a package import + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + as: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + path: + description: Expressions begin and end with double quote marks + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + body: + description: List of Flux statements + type: array + items: + oneOf: + - description: A placeholder for statements for which no correct statement nodes can be created + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + text: + description: Raw source text + type: string + - description: Represents the declaration of a variable + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + id: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + init: + oneOf: + - description: Used to create and directly specify the elements of an array object + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + elements: + description: Elements of the array + type: array + items: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Used to create and directly specify the elements of a dictionary + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + elements: + description: Elements of the dictionary + type: array + items: + description: A key-value pair in a dictionary. + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + key: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + val: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Function expression + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + params: + description: Function parameters + type: array + items: + description: The value associated with a key + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + key: + oneOf: + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/imports/items/properties/path' + value: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + body: + oneOf: + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: A set of statements + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + body: + description: Block body + type: array + items: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items' + - description: uses binary operators to act on two operands in an expression + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + operator: + type: string + left: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + right: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Represents a function call + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + callee: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + arguments: + description: Function arguments + type: array + items: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: 'Selects one of two expressions, `Alternate` or `Consequent`, depending on a third boolean expression, `Test`' + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + test: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + alternate: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + consequent: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Represents the rule conditions that collectively evaluate to either true or false + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + operator: + type: string + left: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + right: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Represents accessing a property of an object + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + object: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + property: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init/oneOf/0/properties/elements/items/oneOf/1/properties/elements/items/properties/key/oneOf/2/properties/params/items/properties/key' + - description: Represents indexing into an array + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + array: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + index: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Allows the declaration of an anonymous object within a declaration + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + properties: + description: Object properties + type: array + items: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init/oneOf/0/properties/elements/items/oneOf/1/properties/elements/items/properties/key/oneOf/2/properties/params/items' + - description: Represents an expression wrapped in parenthesis + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + expression: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Call expression with pipe argument + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + argument: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + call: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init/oneOf/4' + - description: Uses operators to act on a single operand in an expression + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + operator: + type: string + argument: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Represents boolean values + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: boolean + - description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339nano-timestamp).' + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + format: date-time + - description: Represents the elapsed time between two instants as an int64 nanosecond count with syntax of golang's time.Duration + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + values: + description: Duration values + type: array + items: + description: A pair consisting of length of time and the unit of time measured. It is the atomic unit from which all duration literals are composed. + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + magnitude: + type: integer + unit: + type: string + - description: Represents floating point numbers according to the double representations defined by the IEEE-754-1985 + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: number + - description: Represents integer numbers + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + - description: 'Represents a specialized literal value, indicating the left hand value of a pipe expression' + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + - description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/imports/items/properties/path' + - description: Represents integer numbers + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + - description: Object property assignment + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + member: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init/oneOf/7' + init: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: May consist of an expression that doesn't return a value and is executed solely for its side-effects + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + expression: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Defines an expression to return + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + argument: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: A single variable declaration + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + assignment: + oneOf: + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1' + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/2' + - description: Declares a builtin identifier and its type + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + id: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + - description: Declares a Flux test case + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + assignment: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1' + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + params: + type: object + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + dialect: + description: | + Options for tabular data output. + Default output is [annotated CSV]({{% INFLUXDB_DOCS_URL %}}/reference/syntax/annotated-csv/#csv-response-format) with headers. + + For more information about tabular data **dialect**, + see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). + type: object + properties: + header: + description: 'If true, the results contain a header row.' + type: boolean + default: true + delimiter: + description: 'The separator used between cells. Default is a comma (`,`).' + type: string + default: ',' + maxLength: 1 + minLength: 1 + annotations: + description: | + Annotation rows to include in the results. + An _annotation_ is metadata associated with an object (column) in the data model. + + #### Related guides + + - See [Annotated CSV annotations]({{% INFLUXDB_DOCS_URL %}}/reference/syntax/annotated-csv/#annotations) for examples and more information. + + For more information about **annotations** in tabular data, + see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). + type: array + uniqueItems: true + items: + type: string + enum: + - group + - datatype + - default + commentPrefix: + description: The character prefixed to comment strings. Default is a number sign (`#`). + type: string + default: '#' + maxLength: 1 + minLength: 0 + dateTimeFormat: + description: | + The format for timestamps in results. + Default is [`RFC3339` date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp). + To include nanoseconds in timestamps, use `RFC3339Nano`. + + #### Example formatted date/time values + + | Format | Value | + |:------------|:----------------------------| + | `RFC3339` | `"2006-01-02T15:04:05Z07:00"` | + | `RFC3339Nano` | `"2006-01-02T15:04:05.999999999Z07:00"` | + type: string + default: RFC3339 + enum: + - RFC3339 + - RFC3339Nano + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time Tasks: type: object properties: diff --git a/contracts/cloud.json b/contracts/cloud.json index 25d3b7fc5..19c9e3184 100644 --- a/contracts/cloud.json +++ b/contracts/cloud.json @@ -5017,7 +5017,40 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Query" + "description": "Query InfluxDB with the Flux language", + "type": "object", + "required": [ + "query" + ], + "properties": { + "extern": { + "$ref": "#/components/schemas/File" + }, + "query": { + "description": "The query script to execute.", + "type": "string" + }, + "type": { + "description": "The type of query. Must be \"flux\".", + "type": "string", + "enum": [ + "flux" + ] + }, + "params": { + "type": "object", + "additionalProperties": true, + "description": "Key-value pairs passed as parameters during query execution.\n\nTo use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example:\n\n```json\n query: \"from(bucket: params.mybucket)\\\n |> range(start: params.rangeStart) |> limit(n:1)\"\n```\n\nand pass _`params`_ with the key-value pairs--for example:\n\n```json\n params: {\n \"mybucket\": \"environment\",\n \"rangeStart\": \"-30d\"\n }\n```\n\nDuring query execution, InfluxDB passes _`params`_ to your script and substitutes the values.\n\n#### Limitations\n\n- If you use _`params`_, you can't use _`extern`_.\n" + }, + "dialect": { + "$ref": "#/components/schemas/Dialect" + }, + "now": { + "description": "Specifies the time that should be reported as `now` in the query.\nDefault is the server `now` time.\n", + "type": "string", + "format": "date-time" + } + } } } } @@ -5129,163 +5162,6 @@ ] } }, - "/query": { - "post": { - "operationId": "PostQuery", - "tags": [ - "Data I/O endpoints", - "Query" - ], - "summary": "Query data", - "description": "Retrieves data from buckets.\n\nUse this endpoint to send a Flux query request and retrieve data from a bucket.\n\n#### Rate limits (with InfluxDB Cloud)\n\n`read` rate limits apply.\nFor more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/).\n\n#### Related guides\n\n- [Query with the InfluxDB API]({{% INFLUXDB_DOCS_URL %}}/query-data/execute-queries/influx-api/)\n- [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "header", - "name": "Accept-Encoding", - "description": "The content encoding (usually a compression algorithm) that the client can understand.", - "schema": { - "type": "string", - "description": "The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.", - "default": "identity", - "enum": [ - "gzip", - "identity" - ] - } - }, - { - "in": "header", - "name": "Content-Type", - "schema": { - "type": "string", - "enum": [ - "application/json", - "application/vnd.flux" - ] - } - }, - { - "in": "query", - "name": "org", - "description": "An organization name or ID.\n\n#### InfluxDB Cloud\n\n- Doesn't use the `org` parameter or `orgID` parameter.\n- Queries the bucket in the organization associated with the authorization (API token).\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or `orgID` parameter.\n- Queries the bucket in the specified organization.\n", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "orgID", - "description": "An organization ID.\n\n#### InfluxDB Cloud\n\n- Doesn't use the `org` parameter or `orgID` parameter.\n- Queries the bucket in the organization associated with the authorization (API token).\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or `orgID` parameter.\n- Queries the bucket in the specified organization.\n", - "schema": { - "type": "string" - } - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "label": "cURL", - "source": "curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \\\n--header 'Content-Type: application/vnd.flux' \\\n--header 'Accept: application/csv \\\n--header 'Authorization: Token INFLUX_API_TOKEN' \\\n--data 'from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")'\n" - } - ], - "requestBody": { - "description": "Flux query or specification to execute", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Query" - } - }, - "application/vnd.flux": { - "schema": { - "type": "string" - }, - "example": "from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")\n" - } - } - }, - "responses": { - "200": { - "description": "Success. The response body contains query results.", - "headers": { - "Content-Encoding": { - "description": "Lists encodings (usually compression algorithms) that have been applied to the response payload.", - "schema": { - "type": "string", - "description": "The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data.\n", - "default": "identity", - "enum": [ - "gzip", - "identity" - ] - } - }, - "Trace-Id": { - "description": "The trace ID, if generated, of the request.", - "schema": { - "type": "string", - "description": "Trace ID of a request." - } - } - }, - "content": { - "application/csv": { - "schema": { - "type": "string" - }, - "example": "result,table,_start,_stop,_time,region,host,_value\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62\n" - } - } - }, - "400": { - "description": "Bad request.\nThe response body contains detail about the error.\n\n#### InfluxDB OSS\n\n- Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "orgNotFound": { - "summary": "Organization not found", - "value": { - "code": "invalid", - "message": "failed to decode request body: organization not found" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "404": { - "$ref": "#/components/responses/ResourceNotFoundError" - }, - "429": { - "description": "#### InfluxDB Cloud:\n - returns this error if a **read** or **write** request exceeds your\n plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas)\n or if a **delete** request exceeds the maximum\n [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits)\n - returns `Retry-After` header that describes when to try the write again.\n\n#### InfluxDB OSS:\n - doesn't return this error.\n", - "headers": { - "Retry-After": { - "description": "Non-negative decimal integer indicating seconds to wait before retrying the request.", - "schema": { - "type": "integer", - "format": "int32" - } - } - } - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, "/buckets": { "get": { "operationId": "GetBuckets", @@ -13041,6 +12917,163 @@ } } }, + "/query": { + "post": { + "operationId": "PostQuery", + "tags": [ + "Data I/O endpoints", + "Query" + ], + "summary": "Query data", + "description": "Retrieves data from buckets.\n\nUse this endpoint to send a Flux query request and retrieve data from a bucket.\n\n#### Rate limits (with InfluxDB Cloud)\n\n`read` rate limits apply.\nFor more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/).\n\n#### Related guides\n\n- [Query with the InfluxDB API]({{% INFLUXDB_DOCS_URL %}}/query-data/execute-queries/influx-api/)\n- [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "header", + "name": "Accept-Encoding", + "description": "The content encoding (usually a compression algorithm) that the client can understand.", + "schema": { + "type": "string", + "description": "The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.", + "default": "identity", + "enum": [ + "gzip", + "identity" + ] + } + }, + { + "in": "header", + "name": "Content-Type", + "schema": { + "type": "string", + "enum": [ + "application/json", + "application/vnd.flux" + ] + } + }, + { + "in": "query", + "name": "org", + "description": "An organization name or ID.\n\n#### InfluxDB Cloud\n\n- Doesn't use the `org` parameter or `orgID` parameter.\n- Queries the bucket in the organization associated with the authorization (API token).\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or `orgID` parameter.\n- Queries the bucket in the specified organization.\n", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "orgID", + "description": "An organization ID.\n\n#### InfluxDB Cloud\n\n- Doesn't use the `org` parameter or `orgID` parameter.\n- Queries the bucket in the organization associated with the authorization (API token).\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or `orgID` parameter.\n- Queries the bucket in the specified organization.\n", + "schema": { + "type": "string" + } + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "label": "cURL", + "source": "curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \\\n--header 'Content-Type: application/vnd.flux' \\\n--header 'Accept: application/csv \\\n--header 'Authorization: Token INFLUX_API_TOKEN' \\\n--data 'from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")'\n" + } + ], + "requestBody": { + "description": "Flux query or specification to execute", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Query" + } + }, + "application/vnd.flux": { + "schema": { + "type": "string" + }, + "example": "from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")\n" + } + } + }, + "responses": { + "200": { + "description": "Success. The response body contains query results.", + "headers": { + "Content-Encoding": { + "description": "Lists encodings (usually compression algorithms) that have been applied to the response payload.", + "schema": { + "type": "string", + "description": "The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data.\n", + "default": "identity", + "enum": [ + "gzip", + "identity" + ] + } + }, + "Trace-Id": { + "description": "The trace ID, if generated, of the request.", + "schema": { + "type": "string", + "description": "Trace ID of a request." + } + } + }, + "content": { + "application/csv": { + "schema": { + "type": "string" + }, + "example": "result,table,_start,_stop,_time,region,host,_value\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62\n" + } + } + }, + "400": { + "description": "Bad request.\nThe response body contains detail about the error.\n\n#### InfluxDB OSS\n\n- Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "orgNotFound": { + "summary": "Organization not found", + "value": { + "code": "invalid", + "message": "failed to decode request body: organization not found" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "$ref": "#/components/responses/ResourceNotFoundError" + }, + "429": { + "description": "#### InfluxDB Cloud:\n - returns this error if a **read** or **write** request exceeds your\n plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas)\n or if a **delete** request exceeds the maximum\n [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits)\n - returns `Retry-After` header that describes when to try the write again.\n\n#### InfluxDB OSS:\n - doesn't return this error.\n", + "headers": { + "Retry-After": { + "description": "Non-negative decimal integer indicating seconds to wait before retrying the request.", + "schema": { + "type": "integer", + "format": "int32" + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, "/tasks": { "get": { "operationId": "GetTasks", @@ -13599,42 +13632,6 @@ } } }, - "Query": { - "description": "Query InfluxDB with the Flux language", - "type": "object", - "required": [ - "query" - ], - "properties": { - "extern": { - "$ref": "#/components/schemas/File" - }, - "query": { - "description": "The query script to execute.", - "type": "string" - }, - "type": { - "description": "The type of query. Must be \"flux\".", - "type": "string", - "enum": [ - "flux" - ] - }, - "params": { - "type": "object", - "additionalProperties": true, - "description": "Key-value pairs passed as parameters during query execution.\n\nTo use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example:\n\n```json\n query: \"from(bucket: params.mybucket)\\\n |> range(start: params.rangeStart) |> limit(n:1)\"\n```\n\nand pass _`params`_ with the key-value pairs--for example:\n\n```json\n params: {\n \"mybucket\": \"environment\",\n \"rangeStart\": \"-30d\"\n }\n```\n\nDuring query execution, InfluxDB passes _`params`_ to your script and substitutes the values.\n\n#### Limitations\n\n- If you use _`params`_, you can't use _`extern`_.\n" - }, - "dialect": { - "$ref": "#/components/schemas/Dialect" - }, - "now": { - "description": "Specifies the time that should be reported as `now` in the query.\nDefault is the server `now` time.\n", - "type": "string", - "format": "date-time" - } - } - }, "Package": { "description": "Represents a complete package source tree.", "type": "object", @@ -21822,6 +21819,42 @@ } } }, + "Query": { + "description": "Query InfluxDB with the Flux language", + "type": "object", + "required": [ + "query" + ], + "properties": { + "extern": { + "$ref": "#/components/schemas/File" + }, + "query": { + "description": "The query script to execute.", + "type": "string" + }, + "type": { + "description": "The type of query. Must be \"flux\".", + "type": "string", + "enum": [ + "flux" + ] + }, + "params": { + "type": "object", + "additionalProperties": true, + "description": "Key-value pairs passed as parameters during query execution.\n\nTo use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example:\n\n```json\n query: \"from(bucket: params.mybucket)\\\n |> range(start: params.rangeStart) |> limit(n:1)\"\n```\n\nand pass _`params`_ with the key-value pairs--for example:\n\n```json\n params: {\n \"mybucket\": \"environment\",\n \"rangeStart\": \"-30d\"\n }\n```\n\nDuring query execution, InfluxDB passes _`params`_ to your script and substitutes the values.\n\n#### Limitations\n\n- If you use _`params`_, you can't use _`extern`_.\n" + }, + "dialect": { + "$ref": "#/components/schemas/Dialect" + }, + "now": { + "description": "Specifies the time that should be reported as `now` in the query.\nDefault is the server `now` time.\n", + "type": "string", + "format": "date-time" + } + } + }, "Tasks": { "type": "object", "properties": { diff --git a/contracts/cloud.yml b/contracts/cloud.yml index 5695f8df5..6302c9a47 100644 --- a/contracts/cloud.yml +++ b/contracts/cloud.yml @@ -4077,7 +4077,56 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Query' + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + $ref: '#/components/schemas/File' + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + params: + type: object + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + dialect: + $ref: '#/components/schemas/Dialect' + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time responses: '200': description: | @@ -4175,173 +4224,6 @@ paths: "type": "flux" } EOF - /query: - post: - operationId: PostQuery - tags: - - Data I/O endpoints - - Query - summary: Query data - description: | - Retrieves data from buckets. - - Use this endpoint to send a Flux query request and retrieve data from a bucket. - - #### Rate limits (with InfluxDB Cloud) - - `read` rate limits apply. - For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). - - #### Related guides - - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/influx-api/) - - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Accept-Encoding - description: The content encoding (usually a compression algorithm) that the client can understand. - schema: - type: string - description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.' - default: identity - enum: - - gzip - - identity - - in: header - name: Content-Type - schema: - type: string - enum: - - application/json - - application/vnd.flux - - in: query - name: org - description: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - schema: - type: string - - in: query - name: orgID - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - schema: - type: string - x-codeSamples: - - lang: Shell - label: cURL - source: | - curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ - --header 'Content-Type: application/vnd.flux' \ - --header 'Accept: application/csv \ - --header 'Authorization: Token INFLUX_API_TOKEN' \ - --data 'from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement")' - requestBody: - description: Flux query or specification to execute - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - application/vnd.flux: - schema: - type: string - example: | - from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement") - responses: - '200': - description: Success. The response body contains query results. - headers: - Content-Encoding: - description: Lists encodings (usually compression algorithms) that have been applied to the response payload. - schema: - type: string - description: | - The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. - default: identity - enum: - - gzip - - identity - Trace-Id: - description: 'The trace ID, if generated, of the request.' - schema: - type: string - description: Trace ID of a request. - content: - application/csv: - schema: - type: string - example: | - result,table,_start,_stop,_time,region,host,_value - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 - '400': - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '429': - description: | - #### InfluxDB Cloud: - - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#global-limits) - - returns `Retry-After` header that describes when to try the write again. - - #### InfluxDB OSS: - - doesn't return this error. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - type: integer - format: int32 - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' /buckets: get: operationId: GetBuckets @@ -10731,6 +10613,173 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /query: + post: + operationId: PostQuery + tags: + - Data I/O endpoints + - Query + summary: Query data + description: | + Retrieves data from buckets. + + Use this endpoint to send a Flux query request and retrieve data from a bucket. + + #### Rate limits (with InfluxDB Cloud) + + `read` rate limits apply. + For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). + + #### Related guides + + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/influx-api/) + - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Accept-Encoding + description: The content encoding (usually a compression algorithm) that the client can understand. + schema: + type: string + description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.' + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/json + - application/vnd.flux + - in: query + name: org + description: | + An organization name or ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + - in: query + name: orgID + description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ + --header 'Content-Type: application/vnd.flux' \ + --header 'Accept: application/csv \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' + requestBody: + description: Flux query or specification to execute + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/vnd.flux: + schema: + type: string + example: | + from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement") + responses: + '200': + description: Success. The response body contains query results. + headers: + Content-Encoding: + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. + schema: + type: string + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: 'The trace ID, if generated, of the request.' + schema: + type: string + description: Trace ID of a request. + content: + application/csv: + schema: + type: string + example: | + result,table,_start,_stop,_time,region,host,_value + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + '400': + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '429': + description: | + #### InfluxDB Cloud: + - returns this error if a **read** or **write** request exceeds your + plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum + [global limit](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#global-limits) + - returns `Retry-After` header that describes when to try the write again. + + #### InfluxDB OSS: + - doesn't return this error. + headers: + Retry-After: + description: Non-negative decimal integer indicating seconds to wait before retrying the request. + schema: + type: integer + format: int32 + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' /tasks: get: operationId: GetTasks @@ -11326,57 +11375,6 @@ components: description: | The Flux query script to be analyzed. type: string - Query: - description: Query InfluxDB with the Flux language - type: object - required: - - query - properties: - extern: - $ref: '#/components/schemas/File' - query: - description: The query script to execute. - type: string - type: - description: The type of query. Must be "flux". - type: string - enum: - - flux - params: - type: object - additionalProperties: true - description: | - Key-value pairs passed as parameters during query execution. - - To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: - - ```json - query: "from(bucket: params.mybucket)\ - |> range(start: params.rangeStart) |> limit(n:1)" - ``` - - and pass _`params`_ with the key-value pairs--for example: - - ```json - params: { - "mybucket": "environment", - "rangeStart": "-30d" - } - ``` - - During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. - - #### Limitations - - - If you use _`params`_, you can't use _`extern`_. - dialect: - $ref: '#/components/schemas/Dialect' - now: - description: | - Specifies the time that should be reported as `now` in the query. - Default is the server `now` time. - type: string - format: date-time Package: description: Represents a complete package source tree. type: object @@ -17227,6 +17225,57 @@ components: type: array items: $ref: '#/components/schemas/MeasurementSchemaColumn' + Query: + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + $ref: '#/components/schemas/File' + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + params: + type: object + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + dialect: + $ref: '#/components/schemas/Dialect' + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time Tasks: type: object properties: diff --git a/contracts/common.yml b/contracts/common.yml index 2f96a1370..c60684b0a 100644 --- a/contracts/common.yml +++ b/contracts/common.yml @@ -3786,7 +3786,56 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Query' + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + $ref: '#/components/schemas/File' + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + params: + type: object + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + dialect: + $ref: '#/components/schemas/Dialect' + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time responses: '200': description: | @@ -3884,173 +3933,6 @@ paths: "type": "flux" } EOF - /query: - post: - operationId: PostQuery - tags: - - Data I/O endpoints - - Query - summary: Query data - description: | - Retrieves data from buckets. - - Use this endpoint to send a Flux query request and retrieve data from a bucket. - - #### Rate limits (with InfluxDB Cloud) - - `read` rate limits apply. - For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). - - #### Related guides - - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) - - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Accept-Encoding - description: The content encoding (usually a compression algorithm) that the client can understand. - schema: - type: string - description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.' - default: identity - enum: - - gzip - - identity - - in: header - name: Content-Type - schema: - type: string - enum: - - application/json - - application/vnd.flux - - in: query - name: org - description: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - schema: - type: string - - in: query - name: orgID - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - schema: - type: string - x-codeSamples: - - lang: Shell - label: cURL - source: | - curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ - --header 'Content-Type: application/vnd.flux' \ - --header 'Accept: application/csv \ - --header 'Authorization: Token INFLUX_API_TOKEN' \ - --data 'from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement")' - requestBody: - description: Flux query or specification to execute - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - application/vnd.flux: - schema: - type: string - example: | - from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement") - responses: - '200': - description: Success. The response body contains query results. - headers: - Content-Encoding: - description: Lists encodings (usually compression algorithms) that have been applied to the response payload. - schema: - type: string - description: | - The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. - default: identity - enum: - - gzip - - identity - Trace-Id: - description: 'The trace ID, if generated, of the request.' - schema: - type: string - description: Trace ID of a request. - content: - application/csv: - schema: - type: string - example: | - result,table,_start,_stop,_time,region,host,_value - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 - '400': - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '429': - description: | - #### InfluxDB Cloud: - - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) - - returns `Retry-After` header that describes when to try the write again. - - #### InfluxDB OSS: - - doesn't return this error. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - type: integer - format: int32 - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' /buckets: get: operationId: GetBuckets @@ -9433,57 +9315,6 @@ components: description: | The Flux query script to be analyzed. type: string - Query: - description: Query InfluxDB with the Flux language - type: object - required: - - query - properties: - extern: - $ref: '#/components/schemas/File' - query: - description: The query script to execute. - type: string - type: - description: The type of query. Must be "flux". - type: string - enum: - - flux - params: - type: object - additionalProperties: true - description: | - Key-value pairs passed as parameters during query execution. - - To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: - - ```json - query: "from(bucket: params.mybucket)\ - |> range(start: params.rangeStart) |> limit(n:1)" - ``` - - and pass _`params`_ with the key-value pairs--for example: - - ```json - params: { - "mybucket": "environment", - "rangeStart": "-30d" - } - ``` - - During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. - - #### Limitations - - - If you use _`params`_, you can't use _`extern`_. - dialect: - $ref: '#/components/schemas/Dialect' - now: - description: | - Specifies the time that should be reported as `now` in the query. - Default is the server `now` time. - type: string - format: date-time Package: description: Represents a complete package source tree. type: object diff --git a/contracts/oss-diff.yml b/contracts/oss-diff.yml index bac1d334b..ea93dbb1c 100644 --- a/contracts/oss-diff.yml +++ b/contracts/oss-diff.yml @@ -1243,7 +1243,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -2608,6 +2608,201 @@ paths: $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' default: $ref: '#/paths/~1config/get/responses/401' + /query: + post: + operationId: PostQuery + tags: + - Data I/O endpoints + - Query + summary: Query data + description: | + Retrieves data from buckets. + + Use this endpoint to send a Flux query request and retrieve data from a bucket. + + #### Rate limits (with InfluxDB Cloud) + + `read` rate limits apply. + For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). + + #### Related guides + + - [Query with the InfluxDB API]({{% INFLUXDB_DOCS_URL %}}/query-data/execute-queries/influx-api/) + - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) + parameters: + - $ref: '#/paths/~1ready/get/parameters/0' + - in: header + name: Accept-Encoding + description: The content encoding (usually a compression algorithm) that the client can understand. + schema: + type: string + description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.' + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/json + - application/vnd.flux + - in: query + name: org + description: | + An organization name or ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + - in: query + name: orgID + description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ + --header 'Content-Type: application/vnd.flux' \ + --header 'Accept: application/csv \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' + requestBody: + description: Flux query or specification to execute + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/vnd.flux: + schema: + type: string + example: | + from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement") + responses: + '200': + description: Success. The response body contains query results. + headers: + Content-Encoding: + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. + schema: + type: string + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: 'The trace ID, if generated, of the request.' + schema: + type: string + description: Trace ID of a request. + content: + application/csv: + schema: + type: string + example: | + result,table,_start,_stop,_time,region,host,_value + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + '400': + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. + content: + application/json: + schema: + $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + '401': + $ref: '#/paths/~1tasks/get/responses/401' + '404': + description: | + Not found. + A requested resource was not found. + The response body contains the requested resource type and the name value + (if you passed it)--for example: + + - `"organization name \"my-org\" not found"` + - `"organization not found"`: indicates you passed an ID that did not match + an organization. + content: + application/json: + schema: + $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' + examples: + org-not-found: + summary: Organization name not found + value: + code: not found + message: organization name "my-org" not found + bucket-not-found: + summary: Bucket name not found + value: + code: not found + message: bucket "air_sensor" not found + orgID-not-found: + summary: Organization ID not found + value: + code: not found + message: organization not found + '429': + description: | + #### InfluxDB Cloud: + - returns this error if a **read** or **write** request exceeds your + plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum + [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits) + - returns `Retry-After` header that describes when to try the write again. + + #### InfluxDB OSS: + - doesn't return this error. + headers: + Retry-After: + description: Non-negative decimal integer indicating seconds to wait before retrying the request. + schema: + type: integer + format: int32 + '500': + $ref: '#/paths/~1users/get/responses/500' + default: + $ref: '#/paths/~1config/get/responses/401' /remotes: get: operationId: GetRemoteConnections @@ -5054,35 +5249,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - description: | - Not found. - A requested resource was not found. - The response body contains the requested resource type and the name value - (if you passed it)--for example: - - - `"organization name \"my-org\" not found"` - - `"organization not found"`: indicates you passed an ID that did not match - an organization. - content: - application/json: - schema: - $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' - examples: - org-not-found: - summary: Organization name not found - value: - code: not found - message: organization name "my-org" not found - bucket-not-found: - summary: Bucket name not found - value: - code: not found - message: bucket "air_sensor" not found - orgID-not-found: - summary: Organization ID not found - value: - code: not found - message: organization not found + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -5128,7 +5295,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -5161,7 +5328,7 @@ paths: '401': $ref: '#/paths/~1tasks/get/responses/401' '404': - $ref: '#/paths/~1tasks~1%7BtaskID%7D/get/responses/404' + $ref: '#/paths/~1query/post/responses/404' '500': $ref: '#/paths/~1users/get/responses/500' default: @@ -5882,6 +6049,425 @@ components: - bucketName - defaultRetentionPolicy - retentionPolicies + Query: + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + description: Represents a source from a single file + type: object + properties: + type: + description: Type of AST node + type: string + name: + description: The name of the file. + type: string + package: + description: Defines a package identifier + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + name: + description: A valid Flux identifier + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + name: + type: string + imports: + description: A list of package imports + type: array + items: + description: Declares a package import + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + as: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + path: + description: Expressions begin and end with double quote marks + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + body: + description: List of Flux statements + type: array + items: + oneOf: + - description: A placeholder for statements for which no correct statement nodes can be created + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + text: + description: Raw source text + type: string + - description: Represents the declaration of a variable + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + id: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + init: + oneOf: + - description: Used to create and directly specify the elements of an array object + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + elements: + description: Elements of the array + type: array + items: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Used to create and directly specify the elements of a dictionary + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + elements: + description: Elements of the dictionary + type: array + items: + description: A key-value pair in a dictionary. + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + key: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + val: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Function expression + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + params: + description: Function parameters + type: array + items: + description: The value associated with a key + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + key: + oneOf: + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/imports/items/properties/path' + value: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + body: + oneOf: + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: A set of statements + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + body: + description: Block body + type: array + items: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items' + - description: uses binary operators to act on two operands in an expression + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + operator: + type: string + left: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + right: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Represents a function call + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + callee: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + arguments: + description: Function arguments + type: array + items: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: 'Selects one of two expressions, `Alternate` or `Consequent`, depending on a third boolean expression, `Test`' + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + test: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + alternate: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + consequent: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Represents the rule conditions that collectively evaluate to either true or false + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + operator: + type: string + left: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + right: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Represents accessing a property of an object + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + object: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + property: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init/oneOf/0/properties/elements/items/oneOf/1/properties/elements/items/properties/key/oneOf/2/properties/params/items/properties/key' + - description: Represents indexing into an array + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + array: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + index: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Allows the declaration of an anonymous object within a declaration + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + properties: + description: Object properties + type: array + items: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init/oneOf/0/properties/elements/items/oneOf/1/properties/elements/items/properties/key/oneOf/2/properties/params/items' + - description: Represents an expression wrapped in parenthesis + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + expression: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Call expression with pipe argument + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + argument: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + call: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init/oneOf/4' + - description: Uses operators to act on a single operand in an expression + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + operator: + type: string + argument: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Represents boolean values + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: boolean + - description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339nano-timestamp).' + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + format: date-time + - description: Represents the elapsed time between two instants as an int64 nanosecond count with syntax of golang's time.Duration + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + values: + description: Duration values + type: array + items: + description: A pair consisting of length of time and the unit of time measured. It is the atomic unit from which all duration literals are composed. + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + magnitude: + type: integer + unit: + type: string + - description: Represents floating point numbers according to the double representations defined by the IEEE-754-1985 + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: number + - description: Represents integer numbers + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + - description: 'Represents a specialized literal value, indicating the left hand value of a pipe expression' + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + - description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/imports/items/properties/path' + - description: Represents integer numbers + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + value: + type: string + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + - description: Object property assignment + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + member: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init/oneOf/7' + init: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: May consist of an expression that doesn't return a value and is executed solely for its side-effects + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + expression: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: Defines an expression to return + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + argument: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1/properties/init' + - description: A single variable declaration + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + assignment: + oneOf: + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1' + - $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/2' + - description: Declares a builtin identifier and its type + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + id: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/package/properties/name' + - description: Declares a Flux test case + type: object + properties: + type: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/type' + assignment: + $ref: '#/paths/~1query/post/requestBody/content/application~1json/schema/properties/extern/properties/body/items/oneOf/1' + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + dialect: + description: | + Options for tabular data output. + Default output is [annotated CSV]({{% INFLUXDB_DOCS_URL %}}/reference/syntax/annotated-csv/#csv-response-format) with headers. + + For more information about tabular data **dialect**, + see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). + type: object + properties: + header: + description: 'If true, the results contain a header row.' + type: boolean + default: true + delimiter: + description: 'The separator used between cells. Default is a comma (`,`).' + type: string + default: ',' + maxLength: 1 + minLength: 1 + annotations: + description: | + Annotation rows to include in the results. + An _annotation_ is metadata associated with an object (column) in the data model. + + #### Related guides + + - See [Annotated CSV annotations]({{% INFLUXDB_DOCS_URL %}}/reference/syntax/annotated-csv/#annotations) for examples and more information. + + For more information about **annotations** in tabular data, + see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). + type: array + uniqueItems: true + items: + type: string + enum: + - group + - datatype + - default + commentPrefix: + description: The character prefixed to comment strings. Default is a number sign (`#`). + type: string + default: '#' + maxLength: 1 + minLength: 0 + dateTimeFormat: + description: | + The format for timestamps in results. + Default is [`RFC3339` date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp). + To include nanoseconds in timestamps, use `RFC3339Nano`. + + #### Example formatted date/time values + + | Format | Value | + |:------------|:----------------------------| + | `RFC3339` | `"2006-01-02T15:04:05Z07:00"` | + | `RFC3339Nano` | `"2006-01-02T15:04:05.999999999Z07:00"` | + type: string + default: RFC3339 + enum: + - RFC3339 + - RFC3339Nano + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time RetentionPolicyManifests: type: array items: diff --git a/contracts/oss.json b/contracts/oss.json index 7710ad58e..fda08eb02 100644 --- a/contracts/oss.json +++ b/contracts/oss.json @@ -5018,7 +5018,40 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Query" + "description": "Query InfluxDB with the Flux language", + "type": "object", + "required": [ + "query" + ], + "properties": { + "extern": { + "$ref": "#/components/schemas/File" + }, + "query": { + "description": "The query script to execute.", + "type": "string" + }, + "type": { + "description": "The type of query. Must be \"flux\".", + "type": "string", + "enum": [ + "flux" + ] + }, + "params": { + "type": "object", + "additionalProperties": true, + "description": "Key-value pairs passed as parameters during query execution.\n\nTo use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example:\n\n```json\n query: \"from(bucket: params.mybucket)\\\n |> range(start: params.rangeStart) |> limit(n:1)\"\n```\n\nand pass _`params`_ with the key-value pairs--for example:\n\n```json\n params: {\n \"mybucket\": \"environment\",\n \"rangeStart\": \"-30d\"\n }\n```\n\nDuring query execution, InfluxDB passes _`params`_ to your script and substitutes the values.\n\n#### Limitations\n\n- If you use _`params`_, you can't use _`extern`_.\n" + }, + "dialect": { + "$ref": "#/components/schemas/Dialect" + }, + "now": { + "description": "Specifies the time that should be reported as `now` in the query.\nDefault is the server `now` time.\n", + "type": "string", + "format": "date-time" + } + } } } } @@ -5130,163 +5163,6 @@ ] } }, - "/query": { - "post": { - "operationId": "PostQuery", - "tags": [ - "Data I/O endpoints", - "Query" - ], - "summary": "Query data", - "description": "Retrieves data from buckets.\n\nUse this endpoint to send a Flux query request and retrieve data from a bucket.\n\n#### Rate limits (with InfluxDB Cloud)\n\n`read` rate limits apply.\nFor more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/).\n\n#### Related guides\n\n- [Query with the InfluxDB API]({{% INFLUXDB_DOCS_URL %}}/query-data/execute-queries/influx-api/)\n- [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "header", - "name": "Accept-Encoding", - "description": "The content encoding (usually a compression algorithm) that the client can understand.", - "schema": { - "type": "string", - "description": "The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.", - "default": "identity", - "enum": [ - "gzip", - "identity" - ] - } - }, - { - "in": "header", - "name": "Content-Type", - "schema": { - "type": "string", - "enum": [ - "application/json", - "application/vnd.flux" - ] - } - }, - { - "in": "query", - "name": "org", - "description": "An organization name or ID.\n\n#### InfluxDB Cloud\n\n- Doesn't use the `org` parameter or `orgID` parameter.\n- Queries the bucket in the organization associated with the authorization (API token).\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or `orgID` parameter.\n- Queries the bucket in the specified organization.\n", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "orgID", - "description": "An organization ID.\n\n#### InfluxDB Cloud\n\n- Doesn't use the `org` parameter or `orgID` parameter.\n- Queries the bucket in the organization associated with the authorization (API token).\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or `orgID` parameter.\n- Queries the bucket in the specified organization.\n", - "schema": { - "type": "string" - } - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "label": "cURL", - "source": "curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \\\n--header 'Content-Type: application/vnd.flux' \\\n--header 'Accept: application/csv \\\n--header 'Authorization: Token INFLUX_API_TOKEN' \\\n--data 'from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")'\n" - } - ], - "requestBody": { - "description": "Flux query or specification to execute", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Query" - } - }, - "application/vnd.flux": { - "schema": { - "type": "string" - }, - "example": "from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")\n" - } - } - }, - "responses": { - "200": { - "description": "Success. The response body contains query results.", - "headers": { - "Content-Encoding": { - "description": "Lists encodings (usually compression algorithms) that have been applied to the response payload.", - "schema": { - "type": "string", - "description": "The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data.\n", - "default": "identity", - "enum": [ - "gzip", - "identity" - ] - } - }, - "Trace-Id": { - "description": "The trace ID, if generated, of the request.", - "schema": { - "type": "string", - "description": "Trace ID of a request." - } - } - }, - "content": { - "application/csv": { - "schema": { - "type": "string" - }, - "example": "result,table,_start,_stop,_time,region,host,_value\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62\n" - } - } - }, - "400": { - "description": "Bad request.\nThe response body contains detail about the error.\n\n#### InfluxDB OSS\n\n- Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "orgNotFound": { - "summary": "Organization not found", - "value": { - "code": "invalid", - "message": "failed to decode request body: organization not found" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "404": { - "$ref": "#/components/responses/ResourceNotFoundError" - }, - "429": { - "description": "#### InfluxDB Cloud:\n - returns this error if a **read** or **write** request exceeds your\n plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas)\n or if a **delete** request exceeds the maximum\n [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits)\n - returns `Retry-After` header that describes when to try the write again.\n\n#### InfluxDB OSS:\n - doesn't return this error.\n", - "headers": { - "Retry-After": { - "description": "Non-negative decimal integer indicating seconds to wait before retrying the request.", - "schema": { - "type": "integer", - "format": "int32" - } - } - } - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, "/buckets": { "get": { "operationId": "GetBuckets", @@ -14828,6 +14704,163 @@ } } }, + "/query": { + "post": { + "operationId": "PostQuery", + "tags": [ + "Data I/O endpoints", + "Query" + ], + "summary": "Query data", + "description": "Retrieves data from buckets.\n\nUse this endpoint to send a Flux query request and retrieve data from a bucket.\n\n#### Rate limits (with InfluxDB Cloud)\n\n`read` rate limits apply.\nFor more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/).\n\n#### Related guides\n\n- [Query with the InfluxDB API]({{% INFLUXDB_DOCS_URL %}}/query-data/execute-queries/influx-api/)\n- [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "header", + "name": "Accept-Encoding", + "description": "The content encoding (usually a compression algorithm) that the client can understand.", + "schema": { + "type": "string", + "description": "The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.", + "default": "identity", + "enum": [ + "gzip", + "identity" + ] + } + }, + { + "in": "header", + "name": "Content-Type", + "schema": { + "type": "string", + "enum": [ + "application/json", + "application/vnd.flux" + ] + } + }, + { + "in": "query", + "name": "org", + "description": "An organization name or ID.\n\n#### InfluxDB Cloud\n\n- Doesn't use the `org` parameter or `orgID` parameter.\n- Queries the bucket in the organization associated with the authorization (API token).\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or `orgID` parameter.\n- Queries the bucket in the specified organization.\n", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "orgID", + "description": "An organization ID.\n\n#### InfluxDB Cloud\n\n- Doesn't use the `org` parameter or `orgID` parameter.\n- Queries the bucket in the organization associated with the authorization (API token).\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or `orgID` parameter.\n- Queries the bucket in the specified organization.\n", + "schema": { + "type": "string" + } + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "label": "cURL", + "source": "curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \\\n--header 'Content-Type: application/vnd.flux' \\\n--header 'Accept: application/csv \\\n--header 'Authorization: Token INFLUX_API_TOKEN' \\\n--data 'from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")'\n" + } + ], + "requestBody": { + "description": "Flux query or specification to execute", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Query" + } + }, + "application/vnd.flux": { + "schema": { + "type": "string" + }, + "example": "from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")\n" + } + } + }, + "responses": { + "200": { + "description": "Success. The response body contains query results.", + "headers": { + "Content-Encoding": { + "description": "Lists encodings (usually compression algorithms) that have been applied to the response payload.", + "schema": { + "type": "string", + "description": "The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data.\n", + "default": "identity", + "enum": [ + "gzip", + "identity" + ] + } + }, + "Trace-Id": { + "description": "The trace ID, if generated, of the request.", + "schema": { + "type": "string", + "description": "Trace ID of a request." + } + } + }, + "content": { + "application/csv": { + "schema": { + "type": "string" + }, + "example": "result,table,_start,_stop,_time,region,host,_value\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25\nmean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62\n" + } + } + }, + "400": { + "description": "Bad request.\nThe response body contains detail about the error.\n\n#### InfluxDB OSS\n\n- Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "orgNotFound": { + "summary": "Organization not found", + "value": { + "code": "invalid", + "message": "failed to decode request body: organization not found" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "404": { + "$ref": "#/components/responses/ResourceNotFoundError" + }, + "429": { + "description": "#### InfluxDB Cloud:\n - returns this error if a **read** or **write** request exceeds your\n plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas)\n or if a **delete** request exceeds the maximum\n [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits)\n - returns `Retry-After` header that describes when to try the write again.\n\n#### InfluxDB OSS:\n - doesn't return this error.\n", + "headers": { + "Retry-After": { + "description": "Non-negative decimal integer indicating seconds to wait before retrying the request.", + "schema": { + "type": "integer", + "format": "int32" + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, "/remotes": { "get": { "operationId": "GetRemoteConnections", @@ -15981,42 +16014,6 @@ } } }, - "Query": { - "description": "Query InfluxDB with the Flux language", - "type": "object", - "required": [ - "query" - ], - "properties": { - "extern": { - "$ref": "#/components/schemas/File" - }, - "query": { - "description": "The query script to execute.", - "type": "string" - }, - "type": { - "description": "The type of query. Must be \"flux\".", - "type": "string", - "enum": [ - "flux" - ] - }, - "params": { - "type": "object", - "additionalProperties": true, - "description": "Key-value pairs passed as parameters during query execution.\n\nTo use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example:\n\n```json\n query: \"from(bucket: params.mybucket)\\\n |> range(start: params.rangeStart) |> limit(n:1)\"\n```\n\nand pass _`params`_ with the key-value pairs--for example:\n\n```json\n params: {\n \"mybucket\": \"environment\",\n \"rangeStart\": \"-30d\"\n }\n```\n\nDuring query execution, InfluxDB passes _`params`_ to your script and substitutes the values.\n\n#### Limitations\n\n- If you use _`params`_, you can't use _`extern`_.\n" - }, - "dialect": { - "$ref": "#/components/schemas/Dialect" - }, - "now": { - "description": "Specifies the time that should be reported as `now` in the query.\nDefault is the server `now` time.\n", - "type": "string", - "format": "date-time" - } - } - }, "Package": { "description": "Represents a complete package source tree.", "type": "object", @@ -24023,6 +24020,37 @@ "retentionPolicies" ] }, + "Query": { + "description": "Query InfluxDB with the Flux language", + "type": "object", + "required": [ + "query" + ], + "properties": { + "extern": { + "$ref": "#/components/schemas/File" + }, + "query": { + "description": "The query script to execute.", + "type": "string" + }, + "type": { + "description": "The type of query. Must be \"flux\".", + "type": "string", + "enum": [ + "flux" + ] + }, + "dialect": { + "$ref": "#/components/schemas/Dialect" + }, + "now": { + "description": "Specifies the time that should be reported as `now` in the query.\nDefault is the server `now` time.\n", + "type": "string", + "format": "date-time" + } + } + }, "RetentionPolicyManifests": { "type": "array", "items": { diff --git a/contracts/oss.yml b/contracts/oss.yml index dd4c129b9..19e97552a 100644 --- a/contracts/oss.yml +++ b/contracts/oss.yml @@ -4065,7 +4065,56 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Query' + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + $ref: '#/components/schemas/File' + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + params: + type: object + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + dialect: + $ref: '#/components/schemas/Dialect' + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time responses: '200': description: | @@ -4163,173 +4212,6 @@ paths: "type": "flux" } EOF - /query: - post: - operationId: PostQuery - tags: - - Data I/O endpoints - - Query - summary: Query data - description: | - Retrieves data from buckets. - - Use this endpoint to send a Flux query request and retrieve data from a bucket. - - #### Rate limits (with InfluxDB Cloud) - - `read` rate limits apply. - For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). - - #### Related guides - - - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) - - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Accept-Encoding - description: The content encoding (usually a compression algorithm) that the client can understand. - schema: - type: string - description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.' - default: identity - enum: - - gzip - - identity - - in: header - name: Content-Type - schema: - type: string - enum: - - application/json - - application/vnd.flux - - in: query - name: org - description: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - schema: - type: string - - in: query - name: orgID - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - schema: - type: string - x-codeSamples: - - lang: Shell - label: cURL - source: | - curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ - --header 'Content-Type: application/vnd.flux' \ - --header 'Accept: application/csv \ - --header 'Authorization: Token INFLUX_API_TOKEN' \ - --data 'from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement")' - requestBody: - description: Flux query or specification to execute - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - application/vnd.flux: - schema: - type: string - example: | - from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement") - responses: - '200': - description: Success. The response body contains query results. - headers: - Content-Encoding: - description: Lists encodings (usually compression algorithms) that have been applied to the response payload. - schema: - type: string - description: | - The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. - default: identity - enum: - - gzip - - identity - Trace-Id: - description: 'The trace ID, if generated, of the request.' - schema: - type: string - description: Trace ID of a request. - content: - application/csv: - schema: - type: string - example: | - result,table,_start,_stop,_time,region,host,_value - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 - '400': - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '429': - description: | - #### InfluxDB Cloud: - - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) - - returns `Retry-After` header that describes when to try the write again. - - #### InfluxDB OSS: - - doesn't return this error. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - type: integer - format: int32 - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' /buckets: get: operationId: GetBuckets @@ -11992,6 +11874,173 @@ paths: $ref: '#/components/responses/GeneralServerError' default: $ref: '#/components/responses/GeneralServerError' + /query: + post: + operationId: PostQuery + tags: + - Data I/O endpoints + - Query + summary: Query data + description: | + Retrieves data from buckets. + + Use this endpoint to send a Flux query request and retrieve data from a bucket. + + #### Rate limits (with InfluxDB Cloud) + + `read` rate limits apply. + For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). + + #### Related guides + + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/latest/query-data/execute-queries/influx-api/) + - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Accept-Encoding + description: The content encoding (usually a compression algorithm) that the client can understand. + schema: + type: string + description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.' + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/json + - application/vnd.flux + - in: query + name: org + description: | + An organization name or ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + - in: query + name: orgID + description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ + --header 'Content-Type: application/vnd.flux' \ + --header 'Accept: application/csv \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' + requestBody: + description: Flux query or specification to execute + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/vnd.flux: + schema: + type: string + example: | + from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement") + responses: + '200': + description: Success. The response body contains query results. + headers: + Content-Encoding: + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. + schema: + type: string + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: 'The trace ID, if generated, of the request.' + schema: + type: string + description: Trace ID of a request. + content: + application/csv: + schema: + type: string + example: | + result,table,_start,_stop,_time,region,host,_value + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + '400': + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '429': + description: | + #### InfluxDB Cloud: + - returns this error if a **read** or **write** request exceeds your + plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/latest/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum + [global limit](https://docs.influxdata.com/influxdb/latest/account-management/limits/#global-limits) + - returns `Retry-After` header that describes when to try the write again. + + #### InfluxDB OSS: + - doesn't return this error. + headers: + Retry-After: + description: Non-negative decimal integer indicating seconds to wait before retrying the request. + schema: + type: integer + format: int32 + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' /remotes: get: operationId: GetRemoteConnections @@ -12842,57 +12891,6 @@ components: description: | The Flux query script to be analyzed. type: string - Query: - description: Query InfluxDB with the Flux language - type: object - required: - - query - properties: - extern: - $ref: '#/components/schemas/File' - query: - description: The query script to execute. - type: string - type: - description: The type of query. Must be "flux". - type: string - enum: - - flux - params: - type: object - additionalProperties: true - description: | - Key-value pairs passed as parameters during query execution. - - To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: - - ```json - query: "from(bucket: params.mybucket)\ - |> range(start: params.rangeStart) |> limit(n:1)" - ``` - - and pass _`params`_ with the key-value pairs--for example: - - ```json - params: { - "mybucket": "environment", - "rangeStart": "-30d" - } - ``` - - During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. - - #### Limitations - - - If you use _`params`_, you can't use _`extern`_. - dialect: - $ref: '#/components/schemas/Dialect' - now: - description: | - Specifies the time that should be reported as `now` in the query. - Default is the server `now` time. - type: string - format: date-time Package: description: Represents a complete package source tree. type: object @@ -18621,6 +18619,30 @@ components: - bucketName - defaultRetentionPolicy - retentionPolicies + Query: + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + $ref: '#/components/schemas/File' + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + dialect: + $ref: '#/components/schemas/Dialect' + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time RetentionPolicyManifests: type: array items: diff --git a/contracts/ref/cloud.yml b/contracts/ref/cloud.yml index cbd4ec568..a9738da9d 100644 --- a/contracts/ref/cloud.yml +++ b/contracts/ref/cloud.yml @@ -12781,7 +12781,56 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Query' + description: Query InfluxDB with the Flux language + properties: + dialect: + $ref: '#/components/schemas/Dialect' + extern: + $ref: '#/components/schemas/File' + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + format: date-time + type: string + params: + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + type: object + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + enum: + - flux + type: string + required: + - query + type: object description: Flux query to analyze responses: "200": diff --git a/contracts/ref/oss.yml b/contracts/ref/oss.yml index e55feeab1..5560514f0 100644 --- a/contracts/ref/oss.yml +++ b/contracts/ref/oss.yml @@ -3556,33 +3556,6 @@ components: Default is the server `now` time. format: date-time type: string - params: - additionalProperties: true - description: | - Key-value pairs passed as parameters during query execution. - - To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: - - ```json - query: "from(bucket: params.mybucket)\ - |> range(start: params.rangeStart) |> limit(n:1)" - ``` - - and pass _`params`_ with the key-value pairs--for example: - - ```json - params: { - "mybucket": "environment", - "rangeStart": "-30d" - } - ``` - - During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. - - #### Limitations - - - If you use _`params`_, you can't use _`extern`_. - type: object query: description: The query script to execute. type: string @@ -13277,7 +13250,56 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Query' + description: Query InfluxDB with the Flux language + properties: + dialect: + $ref: '#/components/schemas/Dialect' + extern: + $ref: '#/components/schemas/File' + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + format: date-time + type: string + params: + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + type: object + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + enum: + - flux + type: string + required: + - query + type: object description: Flux query to analyze responses: "200": diff --git a/src/cloud.yml b/src/cloud.yml index 080c39d7f..9787eb3a8 100644 --- a/src/cloud.yml +++ b/src/cloud.yml @@ -35,6 +35,8 @@ paths: $ref: './cloud/paths/orgs_orgID_usage.yml' /dashboards: $ref: './cloud/paths/dashboards.yml' + /query: + $ref: './cloud/paths/query.yml' /tasks: $ref: './cloud/paths/tasks.yml' "/tasks/{taskID}": @@ -72,6 +74,8 @@ components: $ref: './cloud/schemas/MeasurementSchemaList.yml' MeasurementSchemaUpdateRequest: $ref: './cloud/schemas/MeasurementSchemaUpdateRequest.yml' + Query: + $ref: './cloud/schemas/Query.yml' Tasks: $ref: "./cloud/schemas/Tasks.yml" Task: diff --git a/src/common/paths/query.yml b/src/cloud/paths/query.yml similarity index 94% rename from src/common/paths/query.yml rename to src/cloud/paths/query.yml index dd4ae9e7e..effec4b10 100644 --- a/src/common/paths/query.yml +++ b/src/cloud/paths/query.yml @@ -19,7 +19,7 @@ post: - [Query with the InfluxDB API]({{% INFLUXDB_DOCS_URL %}}/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) parameters: - - $ref: "../parameters/TraceSpan.yml" + - $ref: "../../common/parameters/TraceSpan.yml" - in: header name: Accept-Encoding description: The content encoding (usually a compression algorithm) that the client can understand. @@ -150,7 +150,7 @@ post: content: application/json: schema: - $ref: "../schemas/Error.yml" + $ref: "../../common/schemas/Error.yml" examples: orgNotFound: summary: Organization not found @@ -159,10 +159,10 @@ post: "message":"failed to decode request body: organization not found" } "401": - $ref: "../responses/AuthorizationError.yml" + $ref: "../../common/responses/AuthorizationError.yml" "404": - $ref: "../responses/ResourceNotFoundError.yml" + $ref: "../../common/responses/ResourceNotFoundError.yml" "500": - $ref: "../responses/InternalServerError.yml" + $ref: "../../common/responses/InternalServerError.yml" default: - $ref: "../responses/ServerError.yml" + $ref: "../../common/responses/ServerError.yml" diff --git a/src/cloud/schemas/Query.yml b/src/cloud/schemas/Query.yml new file mode 100644 index 000000000..d543a3a87 --- /dev/null +++ b/src/cloud/schemas/Query.yml @@ -0,0 +1,50 @@ + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + $ref: "../../common/schemas/File.yml" + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + params: + type: object + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + dialect: + $ref: "../../common/schemas/Dialect.yml" + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time diff --git a/src/common/_paths.yml b/src/common/_paths.yml index 3d9dcfd8d..2bc0dbe02 100644 --- a/src/common/_paths.yml +++ b/src/common/_paths.yml @@ -68,8 +68,6 @@ $ref: "./common/paths/query_suggestions_name.yml" /query/analyze: $ref: "./common/paths/query_analyze.yml" - /query: - $ref: "./common/paths/query.yml" /buckets: $ref: "./common/paths/buckets.yml" "/buckets/{bucketID}": diff --git a/src/common/_schemas.yml b/src/common/_schemas.yml index a532d32f7..7a526f4dc 100644 --- a/src/common/_schemas.yml +++ b/src/common/_schemas.yml @@ -1,7 +1,5 @@ LanguageRequest: $ref: "./common/schemas/LanguageRequest.yml" - Query: - $ref: "./common/schemas/Query.yml" Package: $ref: "./common/schemas/Package.yml" File: diff --git a/src/oss.yml b/src/oss.yml index 59e238276..7de16682a 100644 --- a/src/oss.yml +++ b/src/oss.yml @@ -91,6 +91,8 @@ paths: $ref: "./oss/paths/restore_shards_shardID.yml" "/config": $ref: "./oss/paths/config.yml" + /query: + $ref: './oss/paths/query.yml' /remotes: $ref: "./oss/paths/remotes.yml" /remotes/{remoteID}: @@ -140,6 +142,8 @@ components: $ref: "./oss/schemas/BucketMetadataManifests.yml" BucketMetadataManifest: $ref: "./oss/schemas/BucketMetadataManifest.yml" + Query: + $ref: "./oss/schemas/Query.yml" RetentionPolicyManifests: $ref: "./oss/schemas/RetentionPolicyManifests.yml" RetentionPolicyManifest: diff --git a/src/oss/paths/query.yml b/src/oss/paths/query.yml new file mode 100644 index 000000000..effec4b10 --- /dev/null +++ b/src/oss/paths/query.yml @@ -0,0 +1,168 @@ +post: + operationId: PostQuery + tags: + - Data I/O endpoints + - Query + summary: Query data + description: | + Retrieves data from buckets. + + Use this endpoint to send a Flux query request and retrieve data from a bucket. + + #### Rate limits (with InfluxDB Cloud) + + `read` rate limits apply. + For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). + + #### Related guides + + - [Query with the InfluxDB API]({{% INFLUXDB_DOCS_URL %}}/query-data/execute-queries/influx-api/) + - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) + parameters: + - $ref: "../../common/parameters/TraceSpan.yml" + - in: header + name: Accept-Encoding + description: The content encoding (usually a compression algorithm) that the client can understand. + schema: + type: string + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/json + - application/vnd.flux + - in: query + name: org + description: | + An organization name or ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + - in: query + name: orgID + description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + schema: + type: string + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ + --header 'Content-Type: application/vnd.flux' \ + --header 'Accept: application/csv \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' + + requestBody: + description: Flux query or specification to execute + content: + application/json: + schema: + $ref: "../schemas/Query.yml" + application/vnd.flux: + schema: + type: string + example: | + from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement") + responses: + "200": + description: Success. The response body contains query results. + headers: + Content-Encoding: + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. + schema: + type: string + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: The trace ID, if generated, of the request. + schema: + type: string + description: Trace ID of a request. + content: + application/csv: + schema: + type: string + example: | + result,table,_start,_stop,_time,region,host,_value + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + "429": + description: > + #### InfluxDB Cloud: + - returns this error if a **read** or **write** request exceeds your + plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum + [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits) + - returns `Retry-After` header that describes when to try the write again. + + #### InfluxDB OSS: + - doesn't return this error. + headers: + Retry-After: + description: Non-negative decimal integer indicating seconds to wait before retrying the request. + schema: + type: integer + format: int32 + "400": + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. + content: + application/json: + schema: + $ref: "../../common/schemas/Error.yml" + examples: + orgNotFound: + summary: Organization not found + value: { + "code":"invalid", + "message":"failed to decode request body: organization not found" + } + "401": + $ref: "../../common/responses/AuthorizationError.yml" + "404": + $ref: "../../common/responses/ResourceNotFoundError.yml" + "500": + $ref: "../../common/responses/InternalServerError.yml" + default: + $ref: "../../common/responses/ServerError.yml" diff --git a/src/oss/schemas/Query.yml b/src/oss/schemas/Query.yml new file mode 100644 index 000000000..dff4ee1cd --- /dev/null +++ b/src/oss/schemas/Query.yml @@ -0,0 +1,23 @@ + description: Query InfluxDB with the Flux language + type: object + required: + - query + properties: + extern: + $ref: "../../common/schemas/File.yml" + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + type: string + enum: + - flux + dialect: + $ref: "../../common/schemas/Dialect.yml" + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + type: string + format: date-time