diff --git a/.gitignore b/.gitignore index b69d13c23..b4f4314e1 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,4 @@ public node_modules *.log /resources -/content/**/api.html +/content/influxdb/*/api/** diff --git a/api-docs/cloud/swagger.yml b/api-docs/cloud/swagger.yml new file mode 100644 index 000000000..4212ce71e --- /dev/null +++ b/api-docs/cloud/swagger.yml @@ -0,0 +1,11761 @@ +openapi: "3.0.0" +info: + title: Influx API Service + version: 0.1.0 +servers: + - url: /api/v2 +paths: + /signin: + post: + operationId: PostSignin + summary: Exchange basic auth credentials for session + security: + - BasicAuth: [] + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "204": + description: Successfully authenticated + "401": + description: Unauthorized access + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "403": + description: user account is disabled + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unsuccessful authentication + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /signout: + post: + operationId: PostSignout + summary: Expire the current session + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "204": + description: Session successfully expired + "401": + description: Unauthorized access + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unsuccessful session expiry + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /: + get: + operationId: GetRoutes + summary: Map of all top level routes available + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + default: + description: All routes + content: + application/json: + schema: + $ref: "#/components/schemas/Routes" + /setup: + get: + operationId: GetSetup + tags: + - Setup + summary: Check if database has default user, org, bucket + description: Returns `true` if no default user, organization, or bucket has been created. + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "200": + description: allowed true or false + content: + application/json: + schema: + $ref: "#/components/schemas/IsOnboarding" + post: + operationId: PostSetup + tags: + - Setup + summary: Set up initial user, org and bucket + description: Post an onboarding request to set up initial user, org and bucket. + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Source to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/OnboardingRequest" + responses: + "201": + description: Created default user, bucket, org + content: + application/json: + schema: + $ref: "#/components/schemas/OnboardingResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /setup/user: + post: + operationId: PostSetupUser + tags: + - Setup + summary: Set up a new user, org and bucket + description: Post an onboarding request to set up a new user, org and bucket. + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Source to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/OnboardingRequest" + responses: + "201": + description: Created default user, bucket, org + content: + application/json: + schema: + $ref: "#/components/schemas/OnboardingResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /documents/templates: + get: + operationId: GetDocumentsTemplates + tags: + - Templates + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: org + description: Specifies the name of the organization of the template. + schema: + type: string + - in: query + name: orgID + description: Specifies the organization ID of the template. + schema: + type: string + responses: + "200": + description: A list of template documents + content: + application/json: + schema: + $ref: "#/components/schemas/Documents" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostDocumentsTemplates + tags: + - Templates + summary: Create a template + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Template that will be created + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/DocumentCreate" + responses: + "201": + description: Template created + content: + application/json: + schema: + $ref: "#/components/schemas/Document" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/documents/templates/{templateID}": + get: + operationId: GetDocumentsTemplatesID + tags: + - Templates + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: templateID + schema: + type: string + required: true + description: The template ID. + responses: + "200": + description: The template requested + content: + application/json: + schema: + $ref: "#/components/schemas/Document" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + put: + operationId: PutDocumentsTemplatesID + tags: + - Templates + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: templateID + schema: + type: string + required: true + description: The template ID. + requestBody: + description: Template that will be updated + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/DocumentUpdate" + responses: + "200": + description: The newly updated template + content: + application/json: + schema: + $ref: "#/components/schemas/Document" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteDocumentsTemplatesID + tags: + - Templates + summary: Delete a template + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: templateID + schema: + type: string + required: true + description: The template ID. + responses: + "204": + description: Delete has been accepted + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/documents/templates/{templateID}/labels": + get: + operationId: GetDocumentsTemplatesIDLabels + tags: + - Templates + summary: List all labels for a template + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: templateID + schema: + type: string + required: true + description: The template ID. + responses: + "200": + description: A list of all labels for a template + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostDocumentsTemplatesIDLabels + tags: + - Templates + summary: Add a label to a template + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: templateID + schema: + type: string + required: true + description: The template ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The label added to the template + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/documents/templates/{templateID}/labels/{labelID}": + delete: + operationId: DeleteDocumentsTemplatesIDLabelsID + tags: + - Templates + summary: Delete a label from a template + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: templateID + schema: + type: string + required: true + description: The template ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The label ID. + responses: + "204": + description: Delete has been accepted + "404": + description: Template not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /dbrps: + get: + operationId: GetDBRPs + tags: + - DBRPs + summary: List all database retention policy mappings + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: orgID + required: true + description: Specifies the organization ID to filter on + schema: + type: string + - in: query + name: id + description: Specifies the mapping ID to filter on + schema: + type: string + - in: query + name: bucketID + description: Specifies the bucket ID to filter on + schema: + type: string + - in: query + name: default + description: Specifies filtering on default + schema: + type: boolean + - in: query + name: db + description: Specifies the database to filter on + schema: + type: string + - in: query + name: rp + description: Specifies the retention policy to filter on + schema: + type: string + responses: + "200": + description: A list of all database retention policy mappings + content: + application/json: + schema: + $ref: "#/components/schemas/DBRPs" + "400": + description: if any of the parameter passed is invalid + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostDBRP + tags: + - DBRPs + summary: Add a database retention policy mapping + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: The database retention policy mapping to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/DBRP" + responses: + "201": + description: Database retention policy mapping created + content: + application/json: + schema: + $ref: "#/components/schemas/DBRP" + "400": + description: if any of the IDs in the mapping is invalid + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dbrps/{dbrpID}": + get: + operationId: GetDBRPsID + tags: + - DBRPs + summary: Retrieve a database retention policy mapping + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: orgID + required: true + description: Specifies the organization ID of the mapping + schema: + type: string + - in: path + name: dbrpID + schema: + type: string + required: true + description: The database retention policy mapping ID + responses: + "200": + description: The database retention policy requested + content: + application/json: + schema: + $ref: "#/components/schemas/DBRP" + "400": + description: if any of the IDs passed is invalid + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchDBRPID + tags: + - DBRPs + summary: Update a database retention policy mapping + requestBody: + description: Database retention policy update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/DBRPUpdate" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: orgID + required: true + description: Specifies the organization ID of the mapping + schema: + type: string + - in: path + name: dbrpID + schema: + type: string + required: true + description: The database retention policy mapping. + responses: + "200": + description: An updated mapping + content: + application/json: + schema: + $ref: "#/components/schemas/DBRP" + "404": + description: The mapping was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "400": + description: if any of the IDs passed is invalid + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteDBRPID + tags: + - DBRPs + summary: Delete a database retention policy + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: orgID + required: true + description: Specifies the organization ID of the mapping + schema: + type: string + - in: path + name: dbrpID + schema: + type: string + required: true + description: The database retention policy mapping + responses: + "204": + description: Delete has been accepted + "400": + description: if any of the IDs passed is invalid + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /telegraf/plugins: + get: + operationId: GetTelegrafPlugins + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: type + description: The type of plugin desired. + schema: + type: string + responses: + "200": + description: A list of Telegraf plugins. + content: + application/json: + schema: + $ref: "#/components/schemas/TelegrafPlugins" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /telegrafs: + get: + operationId: GetTelegrafs + tags: + - Telegrafs + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: orgID + description: The organization ID the Telegraf config belongs to. + schema: + type: string + responses: + "200": + description: A list of Telegraf configs + content: + application/json: + schema: + $ref: "#/components/schemas/Telegrafs" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTelegrafs + tags: + - Telegrafs + summary: Create a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Telegraf config to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TelegrafRequest" + responses: + "201": + description: Telegraf config created + content: + application/json: + schema: + $ref: "#/components/schemas/Telegraf" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/telegrafs/{telegrafID}": + get: + operationId: GetTelegrafsID + tags: + - Telegrafs + summary: Retrieve a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + - in: header + name: Accept + required: false + schema: + type: string + default: application/toml + enum: + - application/toml + - application/json + - application/octet-stream + responses: + "200": + description: Telegraf config details + content: + application/toml: + example: "[agent]\ninterval = \"10s\"" + schema: + type: string + application/json: + schema: + $ref: "#/components/schemas/Telegraf" + application/octet-stream: + example: "[agent]\ninterval = \"10s\"" + schema: + type: string + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + put: + operationId: PutTelegrafsID + tags: + - Telegrafs + summary: Update a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + requestBody: + description: Telegraf config update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TelegrafRequest" + responses: + "200": + description: An updated Telegraf config + content: + application/json: + schema: + $ref: "#/components/schemas/Telegraf" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteTelegrafsID + tags: + - Telegrafs + summary: Delete a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + responses: + "204": + description: Delete has been accepted + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/telegrafs/{telegrafID}/labels": + get: + operationId: GetTelegrafsIDLabels + tags: + - Telegrafs + summary: List all labels for a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + responses: + "200": + description: A list of all labels for a Telegraf config + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTelegrafsIDLabels + tags: + - Telegrafs + summary: Add a label to a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The label added to the Telegraf config + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/telegrafs/{telegrafID}/labels/{labelID}": + delete: + operationId: DeleteTelegrafsIDLabelsID + tags: + - Telegrafs + summary: Delete a label from a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The label ID. + responses: + "204": + description: Delete has been accepted + "404": + description: Telegraf config not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/telegrafs/{telegrafID}/members": + get: + operationId: GetTelegrafsIDMembers + tags: + - Users + - Telegrafs + summary: List all users with member privileges for a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + responses: + "200": + description: A list of Telegraf config members + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMembers" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTelegrafsIDMembers + tags: + - Users + - Telegrafs + summary: Add a member to a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + requestBody: + description: User to add as member + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Member added to Telegraf config + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMember" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/telegrafs/{telegrafID}/members/{userID}": + delete: + operationId: DeleteTelegrafsIDMembersID + tags: + - Users + - Telegrafs + summary: Remove a member from a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the member to remove. + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + responses: + "204": + description: Member removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/telegrafs/{telegrafID}/owners": + get: + operationId: GetTelegrafsIDOwners + tags: + - Users + - Telegrafs + summary: List all owners of a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + responses: + "200": + description: A list of Telegraf config owners + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwners" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTelegrafsIDOwners + tags: + - Users + - Telegrafs + summary: Add an owner to a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + requestBody: + description: User to add as owner + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Telegraf config owner added + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwner" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/telegrafs/{telegrafID}/owners/{userID}": + delete: + operationId: DeleteTelegrafsIDOwnersID + tags: + - Users + - Telegrafs + summary: Remove an owner from a Telegraf config + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the owner to remove. + - in: path + name: telegrafID + schema: + type: string + required: true + description: The Telegraf config ID. + responses: + "204": + description: Owner removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /scrapers: + get: + operationId: GetScrapers + tags: + - ScraperTargets + summary: Get all scraper targets + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: name + description: Specifies the name of the scraper target. + schema: + type: string + - in: query + name: id + description: List of scraper target IDs to return. If both `id` and `owner` are specified, only `id` is used. + schema: + type: array + items: + type: string + - in: query + name: orgID + description: Specifies the organization ID of the scraper target. + schema: + type: string + - in: query + name: org + description: Specifies the organization name of the scraper target. + schema: + type: string + responses: + "200": + description: All scraper targets + content: + application/json: + schema: + $ref: "#/components/schemas/ScraperTargetResponses" + post: + operationId: PostScrapers + summary: Create a scraper target + tags: + - ScraperTargets + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Scraper target to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ScraperTargetRequest" + responses: + "201": + description: Scraper target created + content: + application/json: + schema: + $ref: "#/components/schemas/ScraperTargetResponse" + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/scrapers/{scraperTargetID}": + get: + operationId: GetScrapersID + tags: + - ScraperTargets + summary: Get a scraper target by ID + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + required: true + schema: + type: string + description: The scraper target ID. + responses: + "200": + description: Scraper target updated + content: + application/json: + schema: + $ref: "#/components/schemas/ScraperTargetResponse" + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteScrapersID + tags: + - ScraperTargets + summary: Delete a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + required: true + schema: + type: string + description: The scraper target ID. + responses: + "204": + description: Scraper target deleted + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchScrapersID + summary: Update a scraper target + tags: + - ScraperTargets + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + required: true + schema: + type: string + description: The scraper target ID. + requestBody: + description: Scraper target update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ScraperTargetRequest" + responses: + "200": + description: Scraper target updated + content: + application/json: + schema: + $ref: "#/components/schemas/ScraperTargetResponse" + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/scrapers/{scraperTargetID}/labels": + get: + operationId: GetScrapersIDLabels + tags: + - ScraperTargets + summary: List all labels for a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + responses: + "200": + description: A list of all labels for a scraper target + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostScrapersIDLabels + tags: + - ScraperTargets + summary: Add a label to a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The newly added label + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/scrapers/{scraperTargetID}/labels/{labelID}": + delete: + operationId: DeleteScrapersIDLabelsID + tags: + - ScraperTargets + summary: Delete a label from a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The label ID. + responses: + "204": + description: Delete has been accepted + "404": + description: Scraper target not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/scrapers/{scraperTargetID}/members": + get: + operationId: GetScrapersIDMembers + tags: + - Users + - ScraperTargets + summary: List all users with member privileges for a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + responses: + "200": + description: A list of scraper target members + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMembers" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostScrapersIDMembers + tags: + - Users + - ScraperTargets + summary: Add a member to a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + requestBody: + description: User to add as member + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Member added to scraper targets + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMember" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/scrapers/{scraperTargetID}/members/{userID}": + delete: + operationId: DeleteScrapersIDMembersID + tags: + - Users + - ScraperTargets + summary: Remove a member from a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of member to remove. + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + responses: + "204": + description: Member removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/scrapers/{scraperTargetID}/owners": + get: + operationId: GetScrapersIDOwners + tags: + - Users + - ScraperTargets + summary: List all owners of a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + responses: + "200": + description: A list of scraper target owners + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwners" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostScrapersIDOwners + tags: + - Users + - ScraperTargets + summary: Add an owner to a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + requestBody: + description: User to add as owner + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Scraper target owner added + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwner" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/scrapers/{scraperTargetID}/owners/{userID}": + delete: + operationId: DeleteScrapersIDOwnersID + tags: + - Users + - ScraperTargets + summary: Remove an owner from a scraper target + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of owner to remove. + - in: path + name: scraperTargetID + schema: + type: string + required: true + description: The scraper target ID. + responses: + "204": + description: Owner removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /variables: + get: + operationId: GetVariables + tags: + - Variables + summary: Get all variables + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: org + description: The organization name. + schema: + type: string + - in: query + name: orgID + description: The organization ID. + schema: + type: string + responses: + "200": + description: All variables for an organization + content: + application/json: + schema: + $ref: "#/components/schemas/Variables" + "400": + description: Invalid request + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostVariables + summary: Create a variable + tags: + - Variables + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Variable to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Variable" + responses: + "201": + description: Variable created + content: + application/json: + schema: + $ref: "#/components/schemas/Variable" + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/variables/{variableID}": + get: + operationId: GetVariablesID + tags: + - Variables + summary: Get a variable + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: variableID + required: true + schema: + type: string + description: The variable ID. + responses: + "200": + description: Variable found + content: + application/json: + schema: + $ref: "#/components/schemas/Variable" + "404": + description: Variable not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteVariablesID + tags: + - Variables + summary: Delete a variable + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: variableID + required: true + schema: + type: string + description: The variable ID. + responses: + "204": + description: Variable deleted + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchVariablesID + summary: Update a variable + tags: + - Variables + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: variableID + required: true + schema: + type: string + description: The variable ID. + requestBody: + description: Variable update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Variable" + responses: + "200": + description: Variable updated + content: + application/json: + schema: + $ref: "#/components/schemas/Variable" + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + put: + operationId: PutVariablesID + summary: Replace a variable + tags: + - Variables + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: variableID + required: true + schema: + type: string + description: The variable ID. + requestBody: + description: Variable to replace + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Variable" + responses: + "200": + description: Variable updated + content: + application/json: + schema: + $ref: "#/components/schemas/Variable" + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/variables/{variableID}/labels": + get: + operationId: GetVariablesIDLabels + tags: + - Variables + summary: List all labels for a variable + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: variableID + schema: + type: string + required: true + description: The variable ID. + responses: + "200": + description: A list of all labels for a variable + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostVariablesIDLabels + tags: + - Variables + summary: Add a label to a variable + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: variableID + schema: + type: string + required: true + description: The variable ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The newly added label + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/variables/{variableID}/labels/{labelID}": + delete: + operationId: DeleteVariablesIDLabelsID + tags: + - Variables + summary: Delete a label from a variable + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: variableID + schema: + type: string + required: true + description: The variable ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The label ID to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Variable not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /write: + post: + operationId: PostWrite + tags: + - Write + summary: Write time series data into InfluxDB + requestBody: + description: Line protocol body + required: true + content: + text/plain: + schema: + type: string + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: header + name: Content-Encoding + description: When present, its value indicates to the database that compression is applied to the line-protocol body. + schema: + type: string + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + description: Content-Type is used to indicate the format of the data sent to the server. + schema: + type: string + description: Text/plain specifies the text line protocol; charset is assumed to be utf-8. + default: text/plain; charset=utf-8 + enum: + - text/plain + - text/plain; charset=utf-8 + - application/vnd.influx.arrow + - in: header + name: Content-Length + description: Content-Length is an entity header is indicating the size of the entity-body, in bytes, sent to the database. If the length is greater than the database max body configuration option, a 413 response is sent. + schema: + type: integer + description: The length in decimal number of octets. + - in: header + name: Accept + description: Specifies the return content format. + schema: + type: string + description: The return format for errors. + default: application/json + enum: + - application/json + - in: query + name: org + description: Specifies the destination organization for writes. Takes either the ID or Name interchangeably. If both `orgID` and `org` are specified, `org` takes precedence. + required: true + schema: + type: string + description: All points within batch are written to this organization. + - in: query + name: orgID + description: Specifies the ID of the destination organization for writes. If both `orgID` and `org` are specified, `org` takes precedence. + schema: + type: string + - in: query + name: bucket + description: The destination bucket for writes. + required: true + schema: + type: string + description: All points within batch are written to this bucket. + - in: query + name: precision + description: The precision for the unix timestamps within the body line-protocol. + schema: + $ref: "#/components/schemas/WritePrecision" + responses: + "204": + description: Write data is correctly formatted and accepted for writing to the bucket. + "400": + description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. + content: + application/json: + schema: + $ref: "#/components/schemas/LineProtocolError" + "401": + description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "403": + description: No token was sent and they are required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "413": + description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. + content: + application/json: + schema: + $ref: "#/components/schemas/LineProtocolLengthError" + "429": + description: Token is temporarily over quota. The Retry-After header describes when to try the write again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + "503": + description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /delete: + post: + summary: Delete time series data from InfluxDB + requestBody: + description: Predicate delete request + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/DeletePredicateRequest" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: org + description: Specifies the organization to delete data from. + schema: + type: string + description: Only points from this organization are deleted. + - in: query + name: bucket + description: Specifies the bucket to delete data from. + schema: + type: string + description: Only points from this bucket are deleted. + - in: query + name: orgID + description: Specifies the organization ID of the resource. + schema: + type: string + - in: query + name: bucketID + description: Specifies the bucket ID to delete data from. + schema: + type: string + description: Only points from this bucket ID are deleted. + responses: + "204": + description: delete has been accepted + "400": + description: invalid request. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "404": + description: the bucket or organization is not found. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "403": + description: no token was sent or does not have sufficient permissions. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /ready: + servers: + - url: / + get: + operationId: GetReady + tags: + - Ready + summary: Get the readiness of an instance at startup + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "200": + description: The instance is ready + content: + application/json: + schema: + $ref: "#/components/schemas/Ready" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /health: + servers: + - url: / + get: + operationId: GetHealth + tags: + - Health + summary: Get the health of an instance + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "200": + description: The instance is healthy + content: + application/json: + schema: + $ref: "#/components/schemas/HealthCheck" + "503": + description: The instance is unhealthy + content: + application/json: + schema: + $ref: "#/components/schemas/HealthCheck" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /sources: + post: + operationId: PostSources + tags: + - Sources + summary: Creates a source + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Source to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Source" + responses: + "201": + description: Created Source + content: + application/json: + schema: + $ref: "#/components/schemas/Source" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + get: + operationId: GetSources + tags: + - Sources + summary: Get all sources + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: org + description: The organization name. + schema: + type: string + responses: + "200": + description: All sources + content: + application/json: + schema: + $ref: "#/components/schemas/Sources" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /sources/{sourceID}: + delete: + operationId: DeleteSourcesID + tags: + - Sources + summary: Delete a source + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: sourceID + schema: + type: string + required: true + description: The source ID. + responses: + "204": + description: Delete has been accepted + "404": + description: View not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchSourcesID + tags: + - Sources + summary: Update a Source + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: sourceID + schema: + type: string + required: true + description: The source ID. + requestBody: + description: Source update + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Source" + responses: + "200": + description: Created Source + content: + application/json: + schema: + $ref: "#/components/schemas/Source" + "404": + description: Source not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + get: + operationId: GetSourcesID + tags: + - Sources + summary: Get a source + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: sourceID + schema: + type: string + required: true + description: The source ID. + responses: + "200": + description: A source + content: + application/json: + schema: + $ref: "#/components/schemas/Source" + "404": + description: Source not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /sources/{sourceID}/health: + get: + operationId: GetSourcesIDHealth + tags: + - Sources + summary: Get the health of a source + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: sourceID + schema: + type: string + required: true + description: The source ID. + responses: + "200": + description: The source is healthy + content: + application/json: + schema: + $ref: "#/components/schemas/HealthCheck" + "503": + description: The source is not healthy + content: + application/json: + schema: + $ref: "#/components/schemas/HealthCheck" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /sources/{sourceID}/buckets: + get: + operationId: GetSourcesIDBuckets + tags: + - Sources + - Buckets + summary: Get buckets in a source + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: sourceID + schema: + type: string + required: true + description: The source ID. + - in: query + name: org + description: The organization name. + schema: + type: string + responses: + "200": + description: A source + content: + application/json: + schema: + $ref: "#/components/schemas/Buckets" + "404": + description: Source not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /labels: + post: + operationId: PostLabels + tags: + - Labels + summary: Create a label + requestBody: + description: Label to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelCreateRequest" + responses: + "201": + description: Added label + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + get: + operationId: GetLabels + tags: + - Labels + summary: Get all labels + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: orgID + description: The organization ID. + schema: + type: string + responses: + "200": + description: All labels + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /labels/{labelID}: + get: + operationId: GetLabelsID + tags: + - Labels + summary: Get a label + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: labelID + schema: + type: string + required: true + description: The ID of the label to update. + responses: + "200": + description: A label + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchLabelsID + tags: + - Labels + summary: Update a label + requestBody: + description: Label update + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelUpdate" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: labelID + schema: + type: string + required: true + description: The ID of the label to update. + responses: + "200": + description: Updated label + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + "404": + description: Label not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteLabelsID + tags: + - Labels + summary: Delete a label + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: labelID + schema: + type: string + required: true + description: The ID of the label to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Label not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /dashboards: + post: + operationId: PostDashboards + tags: + - Dashboards + summary: Create a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Dashboard to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateDashboardRequest" + responses: + "201": + description: Added dashboard + content: + application/json: + schema: + oneOf: + - $ref: "#/components/schemas/Dashboard" + - $ref: "#/components/schemas/DashboardWithViewProperties" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + get: + operationId: GetDashboards + tags: + - Dashboards + summary: Get all dashboards + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/Limit" + - $ref: "#/components/parameters/Descending" + - in: query + name: owner + description: The owner ID. + schema: + type: string + - in: query + name: sortBy + description: The column to sort by. + schema: + type: string + enum: + - "ID" + - "CreatedAt" + - "UpdatedAt" + - in: query + name: id + description: List of dashboard IDs to return. If both `id` and `owner` are specified, only `id` is used. + schema: + type: array + items: + type: string + - in: query + name: orgID + description: The organization ID. + schema: + type: string + - in: query + name: org + description: The organization name. + schema: + type: string + responses: + "200": + description: All dashboards + content: + application/json: + schema: + $ref: "#/components/schemas/Dashboards" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}": + get: + operationId: GetDashboardsID + tags: + - Dashboards + summary: Get a Dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The ID of the dashboard to update. + - in: query + name: include + required: false + schema: + type: string + enum: + - properties + description: Includes the cell view properties in the response if set to `properties` + responses: + "200": + description: Get a single dashboard + content: + application/json: + schema: + oneOf: + - $ref: "#/components/schemas/Dashboard" + - $ref: "#/components/schemas/DashboardWithViewProperties" + "404": + description: Dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchDashboardsID + tags: + - Dashboards + summary: Update a dashboard + requestBody: + description: Patching of a dashboard + required: true + content: + application/json: + schema: + type: object + properties: + name: + description: optional, when provided will replace the name + type: string + description: + description: optional, when provided will replace the description + type: string + cells: + description: optional, when provided will replace all existing cells with the cells provided + $ref: "#/components/schemas/CellWithViewProperties" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The ID of the dashboard to update. + responses: + "200": + description: Updated dashboard + content: + application/json: + schema: + $ref: "#/components/schemas/Dashboard" + "404": + description: Dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteDashboardsID + tags: + - Dashboards + summary: Delete a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The ID of the dashboard to update. + responses: + "204": + description: Delete has been accepted + "404": + description: Dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/cells": + put: + operationId: PutDashboardsIDCells + tags: + - Cells + - Dashboards + summary: Replace cells in a dashboard + description: Replaces all cells in a dashboard. This is used primarily to update the positional information of all cells. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Cells" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The ID of the dashboard to update. + responses: + "201": + description: Replaced dashboard cells + content: + application/json: + schema: + $ref: "#/components/schemas/Dashboard" + "404": + description: Dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostDashboardsIDCells + tags: + - Cells + - Dashboards + summary: Create a dashboard cell + requestBody: + description: Cell that will be added + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateCell" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The ID of the dashboard to update. + responses: + "201": + description: Cell successfully added + content: + application/json: + schema: + $ref: "#/components/schemas/Cell" + "404": + description: Dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/cells/{cellID}": + patch: + operationId: PatchDashboardsIDCellsID + tags: + - Cells + - Dashboards + summary: Update the non-positional information related to a cell + description: Updates the non positional information related to a cell. Updates to a single cell's positional data could cause grid conflicts. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CellUpdate" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The ID of the dashboard to update. + - in: path + name: cellID + schema: + type: string + required: true + description: The ID of the cell to update. + responses: + "200": + description: Updated dashboard cell + content: + application/json: + schema: + $ref: "#/components/schemas/Cell" + "404": + description: Cell or dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteDashboardsIDCellsID + tags: + - Cells + - Dashboards + summary: Delete a dashboard cell + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The ID of the dashboard to delete. + - in: path + name: cellID + schema: + type: string + required: true + description: The ID of the cell to delete. + responses: + "204": + description: Cell successfully deleted + "404": + description: Cell or dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/cells/{cellID}/view": + get: + operationId: GetDashboardsIDCellsIDView + tags: + - Cells + - Dashboards + - Views + summary: Retrieve the view for a cell + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + - in: path + name: cellID + schema: + type: string + required: true + description: The cell ID. + responses: + "200": + description: A dashboard cells view + content: + application/json: + schema: + $ref: "#/components/schemas/View" + "404": + description: Cell or dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchDashboardsIDCellsIDView + tags: + - Cells + - Dashboards + - Views + summary: Update the view for a cell + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/View" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The ID of the dashboard to update. + - in: path + name: cellID + schema: + type: string + required: true + description: The ID of the cell to update. + responses: + "200": + description: Updated cell view + content: + application/json: + schema: + $ref: "#/components/schemas/View" + "404": + description: Cell or dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/labels": + get: + operationId: GetDashboardsIDLabels + tags: + - Dashboards + summary: list all labels for a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + responses: + "200": + description: A list of all labels for a dashboard + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostDashboardsIDLabels + tags: + - Dashboards + summary: Add a label to a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The label added to the dashboard + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/labels/{labelID}": + delete: + operationId: DeleteDashboardsIDLabelsID + tags: + - Dashboards + summary: Delete a label from a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The ID of the label to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Dashboard not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/members": + get: + operationId: GetDashboardsIDMembers + tags: + - Users + - Dashboards + summary: List all dashboard members + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + responses: + "200": + description: A list of users who have member privileges for a dashboard + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMembers" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostDashboardsIDMembers + tags: + - Users + - Dashboards + summary: Add a member to a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + requestBody: + description: User to add as member + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Added to dashboard members + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMember" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/members/{userID}": + delete: + operationId: DeleteDashboardsIDMembersID + tags: + - Users + - Dashboards + summary: Remove a member from a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the member to remove. + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + responses: + "204": + description: Member removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/owners": + get: + operationId: GetDashboardsIDOwners + tags: + - Users + - Dashboards + summary: List all dashboard owners + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + responses: + "200": + description: A list of users who have owner privileges for a dashboard + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwners" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostDashboardsIDOwners + tags: + - Users + - Dashboards + summary: Add an owner to a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + requestBody: + description: User to add as owner + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Added to dashboard owners + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwner" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/dashboards/{dashboardID}/owners/{userID}": + delete: + operationId: DeleteDashboardsIDOwnersID + tags: + - Users + - Dashboards + summary: Remove an owner from a dashboard + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the owner to remove. + - in: path + name: dashboardID + schema: + type: string + required: true + description: The dashboard ID. + responses: + "204": + description: Owner removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /query/ast: + post: + operationId: PostQueryAst + description: Analyzes flux query and generates a query specification. + tags: + - Query + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: header + name: Content-Type + schema: + type: string + enum: + - application/json + requestBody: + description: Analyzed Flux query to generate abstract syntax tree. + content: + application/json: + schema: + $ref: "#/components/schemas/LanguageRequest" + responses: + "200": + description: Abstract syntax tree of flux query. + content: + application/json: + schema: + $ref: "#/components/schemas/ASTResponse" + default: + description: Any response other than 200 is an internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /query/suggestions: + get: + operationId: GetQuerySuggestions + tags: + - Query + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "200": + description: Suggestions for next functions in call chain + content: + application/json: + schema: + $ref: "#/components/schemas/FluxSuggestions" + default: + description: Any response other than 200 is an internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/query/suggestions/{name}": + get: + operationId: GetQuerySuggestionsName + tags: + - Query + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: name + schema: + type: string + required: true + description: The name of the branching suggestion. + responses: + "200": + description: Suggestions for next functions in call chain + content: + application/json: + schema: + $ref: "#/components/schemas/FluxSuggestion" + default: + description: Any response other than 200 is an internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + summary: List all authorizations + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: userID + schema: + type: string + description: Only show authorizations that belong to a user ID. + - in: query + name: user + schema: + type: string + description: Only show authorizations that belong to a user name. + - in: query + name: orgID + schema: + type: string + description: Only show authorizations that belong to an organization ID. + - in: query + name: org + schema: + type: string + description: Only show authorizations that belong to a organization name. + responses: + "200": + description: A list of authorizations + content: + application/json: + schema: + $ref: "#/components/schemas/Authorizations" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostAuthorizations + tags: + - Authorizations + summary: Create an authorization + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Authorization to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Authorization" + responses: + "201": + description: Authorization created + content: + application/json: + schema: + $ref: "#/components/schemas/Authorization" + "400": + description: Invalid request + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /authorizations/{authID}: + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + summary: Retrieve an authorization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: authID + schema: + type: string + required: true + description: The ID of the authorization to get. + responses: + "200": + description: Authorization details + content: + application/json: + schema: + $ref: "#/components/schemas/Authorization" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + summary: Update an authorization to be active or inactive + requestBody: + description: Authorization to update + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AuthorizationUpdateRequest" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: authID + schema: + type: string + required: true + description: The ID of the authorization to update. + responses: + "200": + description: The active or inactie authorization + content: + application/json: + schema: + $ref: "#/components/schemas/Authorization" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + summary: Delete a authorization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: authID + schema: + type: string + required: true + description: The ID of the authorization to delete. + responses: + "204": + description: Authorization deleted + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /query/analyze: + post: + operationId: PostQueryAnalyze + tags: + - Query + summary: Analyze an InfluxQL or Flux query + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: header + name: Content-Type + schema: + type: string + enum: + - application/json + requestBody: + description: Flux or InfluxQL query to analyze + content: + application/json: + schema: + $ref: "#/components/schemas/Query" + responses: + "200": + description: Query analyze results. Errors will be empty if the query is valid. + content: + application/json: + schema: + $ref: "#/components/schemas/AnalyzeQueryResponse" + default: + description: Internal server error + headers: + X-Influx-Error: + description: Error string describing the problem + schema: + type: string + X-Influx-Reference: + description: Reference code unique to the error type + schema: + type: integer + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /query: + post: + operationId: PostQuery + tags: + - Query + summary: Query InfluxDB + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: header + name: Accept-Encoding + description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. + schema: + type: string + description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/json + - application/vnd.flux + - in: query + name: org + description: Specifies the name of the organization executing the query. Takes either the ID or Name interchangeably. If both `orgID` and `org` are specified, `org` takes precedence. + schema: + type: string + - in: query + name: orgID + description: Specifies the ID of the organization executing the query. If both `orgID` and `org` are specified, `org` takes precedence. + schema: + type: string + requestBody: + description: Flux query or specification to execute + content: + application/json: + schema: + oneOf: + - $ref: "#/components/schemas/Query" + - $ref: "#/components/schemas/InfluxQLQuery" + application/vnd.flux: + schema: + type: string + responses: + "200": + description: Query results + headers: + Content-Encoding: + description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body + schema: + type: string + description: Specifies that the response in the body is encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: The Trace-Id header reports the request's trace ID, if one was generated. + schema: + type: string + description: Specifies the request's trace ID. + content: + text/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 + application/vnd.influx.arrow: + schema: + type: string + format: binary + "429": + description: Token is temporarily over quota. The Retry-After header describes when to try the read again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Error processing query + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /buckets: + get: + operationId: GetBuckets + tags: + - Buckets + summary: List all buckets + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/Limit" + - $ref: "#/components/parameters/After" + - in: query + name: org + description: The organization name. + schema: + type: string + - in: query + name: orgID + description: The organization ID. + schema: + type: string + - in: query + name: name + description: Only returns buckets with a specific name. + schema: + type: string + responses: + "200": + description: A list of buckets + content: + application/json: + schema: + $ref: "#/components/schemas/Buckets" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostBuckets + tags: + - Buckets + summary: Create a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Bucket to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PostBucketRequest" + responses: + "201": + description: Bucket created + content: + application/json: + schema: + $ref: "#/components/schemas/Bucket" + 422: + description: Request body failed validation + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/buckets/{bucketID}": + get: + operationId: GetBucketsID + tags: + - Buckets + summary: Retrieve a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + responses: + "200": + description: Bucket details + content: + application/json: + schema: + $ref: "#/components/schemas/Bucket" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchBucketsID + tags: + - Buckets + summary: Update a bucket + requestBody: + description: Bucket update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Bucket" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + responses: + "200": + description: An updated bucket + content: + application/json: + schema: + $ref: "#/components/schemas/Bucket" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteBucketsID + tags: + - Buckets + summary: Delete a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The ID of the bucket to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Bucket not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/buckets/{bucketID}/labels": + get: + operationId: GetBucketsIDLabels + tags: + - Buckets + summary: List all labels for a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + responses: + "200": + description: A list of all labels for a bucket + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostBucketsIDLabels + tags: + - Buckets + summary: Add a label to a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The newly added label + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/buckets/{bucketID}/labels/{labelID}": + delete: + operationId: DeleteBucketsIDLabelsID + tags: + - Buckets + summary: delete a label from a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The ID of the label to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Bucket not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/buckets/{bucketID}/members": + get: + operationId: GetBucketsIDMembers + tags: + - Users + - Buckets + summary: List all users with member privileges for a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + responses: + "200": + description: A list of bucket members + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMembers" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostBucketsIDMembers + tags: + - Users + - Buckets + summary: Add a member to a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + requestBody: + description: User to add as member + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Member added to bucket + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMember" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/buckets/{bucketID}/members/{userID}": + delete: + operationId: DeleteBucketsIDMembersID + tags: + - Users + - Buckets + summary: Remove a member from a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the member to remove. + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + responses: + "204": + description: Member removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/buckets/{bucketID}/owners": + get: + operationId: GetBucketsIDOwners + tags: + - Users + - Buckets + summary: List all owners of a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + responses: + "200": + description: A list of bucket owners + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwners" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostBucketsIDOwners + tags: + - Users + - Buckets + summary: Add an owner to a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + requestBody: + description: User to add as owner + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Bucket owner added + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwner" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/buckets/{bucketID}/owners/{userID}": + delete: + operationId: DeleteBucketsIDOwnersID + tags: + - Users + - Buckets + summary: Remove an owner from a bucket + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the owner to remove. + - in: path + name: bucketID + schema: + type: string + required: true + description: The bucket ID. + responses: + "204": + description: Owner removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /orgs: + get: + operationId: GetOrgs + tags: + - Organizations + summary: List all organizations + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/Limit" + - $ref: "#/components/parameters/Descending" + - in: query + name: org + schema: + type: string + description: Filter organizations to a specific organization name. + - in: query + name: orgID + schema: + type: string + description: Filter organizations to a specific organization ID. + - in: query + name: userID + schema: + type: string + description: Filter organizations to a specific user ID. + responses: + "200": + description: A list of organizations + content: + application/json: + schema: + $ref: "#/components/schemas/Organizations" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostOrgs + tags: + - Organizations + summary: Create an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Organization to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Organization" + responses: + "201": + description: Organization created + content: + application/json: + schema: + $ref: "#/components/schemas/Organization" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/orgs/{orgID}": + get: + operationId: GetOrgsID + tags: + - Organizations + summary: Retrieve an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The ID of the organization to get. + responses: + "200": + description: Organization details + content: + application/json: + schema: + $ref: "#/components/schemas/Organization" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchOrgsID + tags: + - Organizations + summary: Update an organization + requestBody: + description: Organization update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Organization" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The ID of the organization to get. + responses: + "200": + description: Organization updated + content: + application/json: + schema: + $ref: "#/components/schemas/Organization" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteOrgsID + tags: + - Organizations + summary: Delete an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The ID of the organization to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Organization not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/orgs/{orgID}/secrets": + get: + operationId: GetOrgsIDSecrets + tags: + - Secrets + - Organizations + summary: List all secret keys for an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + responses: + "200": + description: A list of all secret keys + content: + application/json: + schema: + $ref: "#/components/schemas/SecretKeysResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchOrgsIDSecrets + tags: + - Secrets + - Organizations + summary: Update secrets in an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + requestBody: + description: Secret key value pairs to update/add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Secrets" + responses: + "204": + description: Keys successfully patched + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/orgs/{orgID}/secrets/delete": # had to make this because swagger wouldn't let me have a request body with a DELETE + post: + operationId: PostOrgsIDSecrets + tags: + - Secrets + - Organizations + summary: Delete secrets from an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + requestBody: + description: Secret key to delete + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SecretKeys" + responses: + "204": + description: Keys successfully patched + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/orgs/{orgID}/members": + get: + operationId: GetOrgsIDMembers + tags: + - Users + - Organizations + summary: List all members of an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + responses: + "200": + description: A list of organization members + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMembers" + "404": + description: Organization not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostOrgsIDMembers + tags: + - Users + - Organizations + summary: Add a member to an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + requestBody: + description: User to add as member + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Added to organization created + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMember" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/orgs/{orgID}/members/{userID}": + delete: + operationId: DeleteOrgsIDMembersID + tags: + - Users + - Organizations + summary: Remove a member from an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the member to remove. + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + responses: + "204": + description: Member removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/orgs/{orgID}/owners": + get: + operationId: GetOrgsIDOwners + tags: + - Users + - Organizations + summary: List all owners of an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + responses: + "200": + description: A list of organization owners + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwners" + "404": + description: Organization not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostOrgsIDOwners + tags: + - Users + - Organizations + summary: Add an owner to an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + requestBody: + description: User to add as owner + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Organization owner added + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwner" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/orgs/{orgID}/owners/{userID}": + delete: + operationId: DeleteOrgsIDOwnersID + tags: + - Users + - Organizations + summary: Remove an owner from an organization + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the owner to remove. + - in: path + name: orgID + schema: + type: string + required: true + description: The organization ID. + responses: + "204": + description: Owner removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /stacks: + get: + operationId: ListStacks + tags: + - InfluxDB Templates + summary: Grab a list of installed InfluxDB Templates + parameters: + - in: query + name: orgID + required: true + schema: + type: string + description: The organization id of the stacks + - in: query + name: name + schema: + type: string + description: A collection of names to filter the list by. + - in: query + name: stackID + schema: + type: string + description: A collection of stackIDs to filter the list by. + responses: + "200": + description: Influx stacks found + content: + application/json: + schema: + type: object + properties: + stacks: + type: array + items: + $ref: "#/components/schemas/Stack" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: CreateStack + tags: + - InfluxDB Templates + summary: Create a new stack + requestBody: + description: Stack to create. + required: true + content: + application/json: + schema: + type: object + properties: + orgID: + type: string + name: + type: string + description: + type: string + urls: + type: array + items: + type: string + responses: + "201": + description: InfluxDB Stack created + content: + application/json: + schema: + $ref: "#/components/schemas/Stack" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /stacks/{stack_id}: + get: + operationId: ReadStack + tags: + - InfluxDB Templates + summary: Grab a stack by its ID + parameters: + - in: path + name: stack_id + required: true + schema: + type: string + description: The stack id + responses: + "200": + description: Read an influx stack by ID + content: + application/json: + schema: + $ref: "#/components/schemas/Stack" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: UpdateStack + tags: + - InfluxDB Templates + summary: Update an InfluxDB Stack + parameters: + - in: path + name: stack_id + required: true + schema: + type: string + description: The stack id + requestBody: + description: Influx stack to update. + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + nullable: true + description: + type: string + nullable: true + templateURLs: + type: array + items: + type: string + nullable: true + additionalResources: + type: array + items: + type: object + properties: + resourceID: + type: string + kind: + type: string + templateMetaName: + type: string + required: ["kind", "resourceID"] + responses: + "200": + description: Influx stack updated + content: + application/json: + schema: + $ref: "#/components/schemas/Stack" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteStack + tags: + - InfluxDB Templates + summary: Delete a stack and remove all its associated resources + parameters: + - in: path + name: stack_id + required: true + schema: + type: string + description: The stack id + - in: query + name: orgID + required: true + schema: + type: string + description: The organization id of the user + responses: + "204": + description: Stack and all its associated resources are deleted + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /stacks/{stack_id}/uninstall: + post: + operationId: UninstallStack + tags: + - InfluxDB Templates + summary: Uninstall an InfluxDB Stack + parameters: + - in: path + name: stack_id + required: true + schema: + type: string + description: The stack id + responses: + "200": + description: Influx stack uninstalled + content: + application/json: + schema: + $ref: "#/components/schemas/Stack" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /templates/apply: + post: + operationId: ApplyTemplate + tags: + - InfluxDB Templates + summary: Apply or dry-run an InfluxDB Template + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TemplateApply" + application/x-jsonnet: + schema: + $ref: "#/components/schemas/TemplateApply" + text/yml: + schema: + $ref: "#/components/schemas/TemplateApply" + responses: + "200": + description: > + Influx package dry-run successful, no new resources created. + The provided diff and summary will not have IDs for resources + that do not exist at the time of the dry run. + content: + application/json: + schema: + $ref: "#/components/schemas/TemplateSummary" + "201": + description: > + Influx package applied successfully. Newly created resources created + available in summary. The diff compares the state of the world before + the package is applied with the changes the application will impose. + This corresponds to `"dryRun": true` + content: + application/json: + schema: + $ref: "#/components/schemas/TemplateSummary" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /templates/export: + post: + operationId: ExportTemplate + tags: + - InfluxDB Templates + summary: Export a new Influx Template + requestBody: + description: Export resources as an InfluxDB template. + required: false + content: + application/json: + schema: + oneOf: + - $ref: "#/components/schemas/TemplateExportByID" + - $ref: "#/components/schemas/TemplateExportByName" + responses: + "200": + description: InfluxDB template created + content: + application/json: + schema: + $ref: "#/components/schemas/Template" + application/x-yaml: + schema: + $ref: "#/components/schemas/Template" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /tasks: + get: + operationId: GetTasks + tags: + - Tasks + summary: List all tasks + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: query + name: name + description: Returns task with a specific name. + schema: + type: string + - in: query + name: after + schema: + type: string + description: Return tasks after a specified ID. + - in: query + name: user + schema: + type: string + description: Filter tasks to a specific user ID. + - in: query + name: org + schema: + type: string + description: Filter tasks to a specific organization name. + - in: query + name: orgID + schema: + type: string + description: Filter tasks to a specific organization ID. + - in: query + name: status + schema: + type: string + enum: + - active + - inactive + description: Filter tasks by a status--"inactive" or "active". + - in: query + name: limit + schema: + type: integer + minimum: 1 + maximum: 500 + default: 100 + description: The number of tasks to return + responses: + "200": + description: A list of tasks + content: + application/json: + schema: + $ref: "#/components/schemas/Tasks" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTasks + tags: + - Tasks + summary: Create a new task + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: Task to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TaskCreateRequest" + responses: + "201": + description: Task created + content: + application/json: + schema: + $ref: "#/components/schemas/Task" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}": + get: + operationId: GetTasksID + tags: + - Tasks + summary: Retrieve a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + responses: + "200": + description: Task details + content: + application/json: + schema: + $ref: "#/components/schemas/Task" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchTasksID + tags: + - Tasks + summary: Update a task + description: Update a task. This will cancel all queued runs. + requestBody: + description: Task update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TaskUpdateRequest" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + responses: + "200": + description: Task updated + content: + application/json: + schema: + $ref: "#/components/schemas/Task" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteTasksID + tags: + - Tasks + summary: Delete a task + description: Deletes a task and all associated records + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The ID of the task to delete. + responses: + "204": + description: Task deleted + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/runs": + get: + operationId: GetTasksIDRuns + tags: + - Tasks + summary: List runs for a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The ID of the task to get runs for. + - in: query + name: after + schema: + type: string + description: Returns runs after a specific ID. + - in: query + name: limit + schema: + type: integer + minimum: 1 + maximum: 500 + default: 100 + description: The number of runs to return + - in: query + name: afterTime + schema: + type: string + format: date-time + description: Filter runs to those scheduled after this time, RFC3339 + - in: query + name: beforeTime + schema: + type: string + format: date-time + description: Filter runs to those scheduled before this time, RFC3339 + responses: + "200": + description: A list of task runs + content: + application/json: + schema: + $ref: "#/components/schemas/Runs" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTasksIDRuns + tags: + - Tasks + summary: Manually start a task run, overriding the current schedule + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RunManually" + responses: + "201": + description: Run scheduled to start + content: + application/json: + schema: + $ref: "#/components/schemas/Run" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/runs/{runID}": + get: + operationId: GetTasksIDRunsID + tags: + - Tasks + summary: Retrieve a single run for a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + - in: path + name: runID + schema: + type: string + required: true + description: The run ID. + responses: + "200": + description: The run record + content: + application/json: + schema: + $ref: "#/components/schemas/Run" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteTasksIDRunsID + tags: + - Tasks + summary: Cancel a running task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + - in: path + name: runID + schema: + type: string + required: true + description: The run ID. + responses: + "204": + description: Delete has been accepted + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/runs/{runID}/retry": + post: + operationId: PostTasksIDRunsIDRetry + tags: + - Tasks + summary: Retry a task run + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + - in: path + name: runID + schema: + type: string + required: true + description: The run ID. + responses: + "200": + description: Run that has been queued + content: + application/json: + schema: + $ref: "#/components/schemas/Run" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/logs": + get: + operationId: GetTasksIDLogs + tags: + - Tasks + summary: Retrieve all logs for a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + responses: + "200": + description: All logs for a task + content: + application/json: + schema: + $ref: "#/components/schemas/Logs" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/runs/{runID}/logs": + get: + operationId: GetTasksIDRunsIDLogs + tags: + - Tasks + summary: Retrieve all logs for a run + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: ID of task to get logs for. + - in: path + name: runID + schema: + type: string + required: true + description: ID of run to get logs for. + responses: + "200": + description: All logs for a run + content: + application/json: + schema: + $ref: "#/components/schemas/Logs" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/labels": + get: + operationId: GetTasksIDLabels + tags: + - Tasks + summary: List all labels for a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + responses: + "200": + description: A list of all labels for a task + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTasksIDLabels + tags: + - Tasks + summary: Add a label to a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: A list of all labels for a task + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/labels/{labelID}": + delete: + operationId: DeleteTasksIDLabelsID + tags: + - Tasks + summary: Delete a label from a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The label ID. + responses: + "204": + description: Delete has been accepted + "404": + description: Task not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /flags: + get: + operationId: GetFlags + tags: + - Users + summary: Return the feature flags for the currently authenticated user + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "200": + description: Feature flags for the currently authenticated user + content: + application/json: + schema: + $ref: "#/components/schemas/Flags" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /me: + get: + operationId: GetMe + tags: + - Users + summary: Return the current authenticated user + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "200": + description: Currently authenticated user + content: + application/json: + schema: + $ref: "#/components/schemas/User" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /me/password: + put: + operationId: PutMePassword + tags: + - Users + summary: Update a password + security: + - BasicAuth: [] + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: New password + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PasswordResetBody" + responses: + "204": + description: Password successfully updated + default: + description: Unsuccessful authentication + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/members": + get: + operationId: GetTasksIDMembers + tags: + - Users + - Tasks + summary: List all task members + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + responses: + "200": + description: A list of users who have member privileges for a task + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMembers" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTasksIDMembers + tags: + - Users + - Tasks + summary: Add a member to a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + requestBody: + description: User to add as member + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Added to task members + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceMember" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/members/{userID}": + delete: + operationId: DeleteTasksIDMembersID + tags: + - Users + - Tasks + summary: Remove a member from a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the member to remove. + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + responses: + "204": + description: Member removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/owners": + get: + operationId: GetTasksIDOwners + tags: + - Users + - Tasks + summary: List all owners of a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + responses: + "200": + description: A list of users who have owner privileges for a task + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwners" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostTasksIDOwners + tags: + - Users + - Tasks + summary: Add an owner to a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + requestBody: + description: User to add as owner + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AddResourceMemberRequestBody" + responses: + "201": + description: Added to task owners + content: + application/json: + schema: + $ref: "#/components/schemas/ResourceOwner" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/tasks/{taskID}/owners/{userID}": + delete: + operationId: DeleteTasksIDOwnersID + tags: + - Users + - Tasks + summary: Remove an owner from a task + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the owner to remove. + - in: path + name: taskID + schema: + type: string + required: true + description: The task ID. + responses: + "204": + description: Owner removed + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /users: + get: + operationId: GetUsers + tags: + - Users + summary: List all users + parameters: + - $ref: "#/components/parameters/TraceSpan" + responses: + "200": + description: A list of users + content: + application/json: + schema: + $ref: "#/components/schemas/Users" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostUsers + tags: + - Users + summary: Create a user + parameters: + - $ref: "#/components/parameters/TraceSpan" + requestBody: + description: User to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/User" + responses: + "201": + description: User created + content: + application/json: + schema: + $ref: "#/components/schemas/User" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/users/{userID}": + get: + operationId: GetUsersID + tags: + - Users + summary: Retrieve a user + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The user ID. + responses: + "200": + description: User details + content: + application/json: + schema: + $ref: "#/components/schemas/User" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchUsersID + tags: + - Users + summary: Update a user + requestBody: + description: User update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/User" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the user to update. + responses: + "200": + description: User updated + content: + application/json: + schema: + $ref: "#/components/schemas/User" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteUsersID + tags: + - Users + summary: Delete a user + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The ID of the user to delete. + responses: + "204": + description: User deleted + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/users/{userID}/password": + post: + operationId: PostUsersIDPassword + tags: + - Users + summary: Update a password + security: + - BasicAuth: [] + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: userID + schema: + type: string + required: true + description: The user ID. + requestBody: + description: New password + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PasswordResetBody" + responses: + "204": + description: Password successfully updated + default: + description: Unsuccessful authentication + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /checks: + get: + operationId: GetChecks + tags: + - Checks + summary: Get all checks + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/Limit" + - in: query + name: orgID + required: true + description: Only show checks that belong to a specific organization ID. + schema: + type: string + responses: + "200": + description: A list of checks + content: + application/json: + schema: + $ref: "#/components/schemas/Checks" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: CreateCheck + tags: + - Checks + summary: Add new check + requestBody: + description: Check to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PostCheck" + responses: + "201": + description: Check created + content: + application/json: + schema: + $ref: "#/components/schemas/Check" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/checks/{checkID}": + get: + operationId: GetChecksID + tags: + - Checks + summary: Get a check + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: checkID + schema: + type: string + required: true + description: The check ID. + responses: + "200": + description: The check requested + content: + application/json: + schema: + $ref: "#/components/schemas/Check" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + put: + operationId: PutChecksID + tags: + - Checks + summary: Update a check + requestBody: + description: Check update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/Check" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: checkID + schema: + type: string + required: true + description: The check ID. + responses: + "200": + description: An updated check + content: + application/json: + schema: + $ref: "#/components/schemas/Check" + "404": + description: The check was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchChecksID + tags: + - Checks + summary: Update a check + requestBody: + description: Check update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CheckPatch" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: checkID + schema: + type: string + required: true + description: The check ID. + responses: + "200": + description: An updated check + content: + application/json: + schema: + $ref: "#/components/schemas/Check" + "404": + description: The check was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteChecksID + tags: + - Checks + summary: Delete a check + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: checkID + schema: + type: string + required: true + description: The check ID. + responses: + "204": + description: Delete has been accepted + "404": + description: The check was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/checks/{checkID}/labels": + get: + operationId: GetChecksIDLabels + tags: + - Checks + summary: List all labels for a check + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: checkID + schema: + type: string + required: true + description: The check ID. + responses: + "200": + description: A list of all labels for a check + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostChecksIDLabels + tags: + - Checks + summary: Add a label to a check + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: checkID + schema: + type: string + required: true + description: The check ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The label was added to the check + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/checks/{checkID}/labels/{labelID}": + delete: + operationId: DeleteChecksIDLabelsID + tags: + - Checks + summary: Delete label from a check + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: checkID + schema: + type: string + required: true + description: The check ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The ID of the label to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Check or label not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /notificationRules: + get: + operationId: GetNotificationRules + tags: + - NotificationRules + summary: Get all notification rules + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/Limit" + - in: query + name: orgID + required: true + description: Only show notification rules that belong to a specific organization ID. + schema: + type: string + - in: query + name: checkID + description: Only show notifications that belong to the specific check ID. + schema: + type: string + - in: query + name: tag + description: Only return notification rules that "would match" statuses which contain the tag key value pairs provided. + schema: + type: string + pattern: ^[a-zA-Z0-9_]+:[a-zA-Z0-9_]+$ + example: env:prod + responses: + "200": + description: A list of notification rules + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRules" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: CreateNotificationRule + tags: + - NotificationRules + summary: Add a notification rule + requestBody: + description: Notification rule to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PostNotificationRule" + responses: + "201": + description: Notification rule created + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/checks/{checkID}/query": + get: + operationId: GetChecksIDQuery + tags: + - Checks + summary: Get a check query + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: checkID + schema: + type: string + required: true + description: The check ID. + responses: + "200": + description: The check query requested + content: + application/json: + schema: + $ref: "#/components/schemas/FluxResponse" + "400": + description: Invalid request + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "404": + description: Check not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/notificationRules/{ruleID}": + get: + operationId: GetNotificationRulesID + tags: + - NotificationRules + summary: Get a notification rule + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: ruleID + schema: + type: string + required: true + description: The notification rule ID. + responses: + "200": + description: The notification rule requested + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + put: + operationId: PutNotificationRulesID + tags: + - NotificationRules + summary: Update a notification rule + requestBody: + description: Notification rule update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: ruleID + schema: + type: string + required: true + description: The notification rule ID. + responses: + "200": + description: An updated notification rule + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + "404": + description: The notification rule was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchNotificationRulesID + tags: + - NotificationRules + summary: Update a notification rule + requestBody: + description: Notification rule update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRuleUpdate" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: ruleID + schema: + type: string + required: true + description: The notification rule ID. + responses: + "200": + description: An updated notification rule + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + "404": + description: The notification rule was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteNotificationRulesID + tags: + - NotificationRules + summary: Delete a notification rule + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: ruleID + schema: + type: string + required: true + description: The notification rule ID. + responses: + "204": + description: Delete has been accepted + "404": + description: The check was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/notificationRules/{ruleID}/labels": + get: + operationId: GetNotificationRulesIDLabels + tags: + - NotificationRules + summary: List all labels for a notification rule + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: ruleID + schema: + type: string + required: true + description: The notification rule ID. + responses: + "200": + description: A list of all labels for a notification rule + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostNotificationRuleIDLabels + tags: + - NotificationRules + summary: Add a label to a notification rule + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: ruleID + schema: + type: string + required: true + description: The notification rule ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The label was added to the notification rule + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/notificationRules/{ruleID}/labels/{labelID}": + delete: + operationId: DeleteNotificationRulesIDLabelsID + tags: + - NotificationRules + summary: Delete label from a notification rule + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: ruleID + schema: + type: string + required: true + description: The notification rule ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The ID of the label to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Rule or label not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/notificationRules/{ruleID}/query": + get: + operationId: GetNotificationRulesIDQuery + tags: + - Rules + summary: Get a notification rule query + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: ruleID + schema: + type: string + required: true + description: The notification rule ID. + responses: + "200": + description: The notification rule query requested + content: + application/json: + schema: + $ref: "#/components/schemas/FluxResponse" + "400": + description: Invalid request + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "404": + description: Notification rule not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /notificationEndpoints: + get: + operationId: GetNotificationEndpoints + tags: + - NotificationEndpoints + summary: Get all notification endpoints + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/Limit" + - in: query + name: orgID + required: true + description: Only show notification endpoints that belong to specific organization ID. + schema: + type: string + responses: + "200": + description: A list of notification endpoints + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationEndpoints" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: CreateNotificationEndpoint + tags: + - NotificationEndpoints + summary: Add a notification endpoint + requestBody: + description: Notification endpoint to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PostNotificationEndpoint" + responses: + "201": + description: Notification endpoint created + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationEndpoint" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/notificationEndpoints/{endpointID}": + get: + operationId: GetNotificationEndpointsID + tags: + - NotificationEndpoints + summary: Get a notification endpoint + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: endpointID + schema: + type: string + required: true + description: The notification endpoint ID. + responses: + "200": + description: The notification endpoint requested + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationEndpoint" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + put: + operationId: PutNotificationEndpointsID + tags: + - NotificationEndpoints + summary: Update a notification endpoint + requestBody: + description: A new notification endpoint to replace the existing endpoint with + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationEndpoint" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: endpointID + schema: + type: string + required: true + description: The notification endpoint ID. + responses: + "200": + description: An updated notification endpoint + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationEndpoint" + "404": + description: The notification endpoint was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + patch: + operationId: PatchNotificationEndpointsID + tags: + - NotificationEndpoints + summary: Update a notification endpoint + requestBody: + description: Check update to apply + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationEndpointUpdate" + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: endpointID + schema: + type: string + required: true + description: The notification endpoint ID. + responses: + "200": + description: An updated notification endpoint + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationEndpoint" + "404": + description: The notification endpoint was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + delete: + operationId: DeleteNotificationEndpointsID + tags: + - NotificationEndpoints + summary: Delete a notification endpoint + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: endpointID + schema: + type: string + required: true + description: The notification endpoint ID. + responses: + "204": + description: Delete has been accepted + "404": + description: The endpoint was not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/notificationEndpoints/{endpointID}/labels": + get: + operationId: GetNotificationEndpointsIDLabels + tags: + - NotificationEndpoints + summary: List all labels for a notification endpoint + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: endpointID + schema: + type: string + required: true + description: The notification endpoint ID. + responses: + "200": + description: A list of all labels for a notification endpoint + content: + application/json: + schema: + $ref: "#/components/schemas/LabelsResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + post: + operationId: PostNotificationEndpointIDLabels + tags: + - NotificationEndpoints + summary: Add a label to a notification endpoint + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: endpointID + schema: + type: string + required: true + description: The notification endpoint ID. + requestBody: + description: Label to add + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/LabelMapping" + responses: + "201": + description: The label was added to the notification endpoint + content: + application/json: + schema: + $ref: "#/components/schemas/LabelResponse" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "/notificationEndpoints/{endpointID}/labels/{labelID}": + delete: + operationId: DeleteNotificationEndpointsIDLabelsID + tags: + - NotificationEndpoints + summary: Delete a label from a notification endpoint + parameters: + - $ref: "#/components/parameters/TraceSpan" + - in: path + name: endpointID + schema: + type: string + required: true + description: The notification endpoint ID. + - in: path + name: labelID + schema: + type: string + required: true + description: The ID of the label to delete. + responses: + "204": + description: Delete has been accepted + "404": + description: Endpoint or label not found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" +components: + parameters: + Offset: + in: query + name: offset + required: false + schema: + type: integer + minimum: 0 + Limit: + in: query + name: limit + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + Descending: + in: query + name: descending + required: false + schema: + type: boolean + default: false + SortBy: + in: query + name: sortBy + required: false + schema: + type: string + TraceSpan: + in: header + name: Zap-Trace-Span + description: OpenTracing span context + example: + trace_id: "1" + span_id: "1" + baggage: + key: value + required: false + schema: + type: string + After: + in: query + name: after + required: false + schema: + type: string + description: > + The last resource ID from which to seek from (but not including). + This is to be used instead of `offset`. + schemas: + LanguageRequest: + description: Flux query to be analyzed. + type: object + required: + - query + properties: + query: + description: Flux query script to be analyzed + type: string + Query: + description: Query influx using the Flux language + type: object + required: + - query + properties: + extern: + $ref: "#/components/schemas/File" + query: + description: 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's now time. + type: string + format: date-time + InfluxQLQuery: + description: Query influx using the InfluxQL language + type: object + required: + - query + properties: + query: + description: InfluxQL query execute. + type: string + type: + description: The type of query. Must be "influxql". + type: string + enum: + - influxql + bucket: + description: Bucket is to be used instead of the database and retention policy specified in the InfluxQL query. + type: string + Package: + description: Represents a complete package source tree. + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + path: + description: Package import path + type: string + package: + description: Package name + type: string + files: + description: Package files + type: array + items: + $ref: "#/components/schemas/File" + File: + description: Represents a source from a single file + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + name: + description: The name of the file. + type: string + package: + $ref: "#/components/schemas/PackageClause" + imports: + description: A list of package imports + type: array + items: + $ref: "#/components/schemas/ImportDeclaration" + body: + description: List of Flux statements + type: array + items: + $ref: "#/components/schemas/Statement" + PackageClause: + description: Defines a package identifier + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + name: + $ref: "#/components/schemas/Identifier" + ImportDeclaration: + description: Declares a package import + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + as: + $ref: "#/components/schemas/Identifier" + path: + $ref: "#/components/schemas/StringLiteral" + DeletePredicateRequest: + description: The delete predicate request. + type: object + required: [start, stop] + properties: + start: + description: RFC3339Nano + type: string + format: date-time + stop: + description: RFC3339Nano + type: string + format: date-time + predicate: + description: InfluxQL-like delete statement + example: tag1="value1" and (tag2="value2" and tag3!="value3") + type: string + Node: + oneOf: + - $ref: "#/components/schemas/Expression" + - $ref: "#/components/schemas/Block" + Block: + description: A set of statements + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + body: + description: Block body + type: array + items: + $ref: "#/components/schemas/Statement" + Statement: + oneOf: + - $ref: "#/components/schemas/BadStatement" + - $ref: "#/components/schemas/VariableAssignment" + - $ref: "#/components/schemas/MemberAssignment" + - $ref: "#/components/schemas/ExpressionStatement" + - $ref: "#/components/schemas/ReturnStatement" + - $ref: "#/components/schemas/OptionStatement" + - $ref: "#/components/schemas/BuiltinStatement" + - $ref: "#/components/schemas/TestStatement" + BadStatement: + description: A placeholder for statements for which no correct statement nodes can be created + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + text: + description: Raw source text + type: string + VariableAssignment: + description: Represents the declaration of a variable + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + id: + $ref: "#/components/schemas/Identifier" + init: + $ref: "#/components/schemas/Expression" + MemberAssignment: + description: Object property assignment + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + member: + $ref: "#/components/schemas/MemberExpression" + init: + $ref: "#/components/schemas/Expression" + ExpressionStatement: + description: May consist of an expression that does not return a value and is executed solely for its side-effects + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + expression: + $ref: "#/components/schemas/Expression" + ReturnStatement: + description: Defines an expression to return + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + argument: + $ref: "#/components/schemas/Expression" + OptionStatement: + description: A single variable declaration + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + assignment: + oneOf: + - $ref: "#/components/schemas/VariableAssignment" + - $ref: "#/components/schemas/MemberAssignment" + BuiltinStatement: + description: Declares a builtin identifier and its type + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + id: + $ref: "#/components/schemas/Identifier" + TestStatement: + description: Declares a Flux test case + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + assignment: + $ref: "#/components/schemas/VariableAssignment" + Expression: + oneOf: + - $ref: "#/components/schemas/ArrayExpression" + - $ref: "#/components/schemas/FunctionExpression" + - $ref: "#/components/schemas/BinaryExpression" + - $ref: "#/components/schemas/CallExpression" + - $ref: "#/components/schemas/ConditionalExpression" + - $ref: "#/components/schemas/LogicalExpression" + - $ref: "#/components/schemas/MemberExpression" + - $ref: "#/components/schemas/IndexExpression" + - $ref: "#/components/schemas/ObjectExpression" + - $ref: "#/components/schemas/ParenExpression" + - $ref: "#/components/schemas/PipeExpression" + - $ref: "#/components/schemas/UnaryExpression" + - $ref: "#/components/schemas/BooleanLiteral" + - $ref: "#/components/schemas/DateTimeLiteral" + - $ref: "#/components/schemas/DurationLiteral" + - $ref: "#/components/schemas/FloatLiteral" + - $ref: "#/components/schemas/IntegerLiteral" + - $ref: "#/components/schemas/PipeLiteral" + - $ref: "#/components/schemas/RegexpLiteral" + - $ref: "#/components/schemas/StringLiteral" + - $ref: "#/components/schemas/UnsignedIntegerLiteral" + - $ref: "#/components/schemas/Identifier" + ArrayExpression: + description: Used to create and directly specify the elements of an array object + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + elements: + description: Elements of the array + type: array + items: + $ref: "#/components/schemas/Expression" + FunctionExpression: + description: Function expression + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + params: + description: Function parameters + type: array + items: + $ref: "#/components/schemas/Property" + body: + $ref: "#/components/schemas/Node" + BinaryExpression: + description: uses binary operators to act on two operands in an expression + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + operator: + type: string + left: + $ref: "#/components/schemas/Expression" + right: + $ref: "#/components/schemas/Expression" + CallExpression: + description: Represents a function call + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + callee: + $ref: "#/components/schemas/Expression" + arguments: + description: Function arguments + type: array + items: + $ref: "#/components/schemas/Expression" + ConditionalExpression: + description: Selects one of two expressions, `Alternate` or `Consequent`, depending on a third boolean expression, `Test` + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + test: + $ref: "#/components/schemas/Expression" + alternate: + $ref: "#/components/schemas/Expression" + consequent: + $ref: "#/components/schemas/Expression" + LogicalExpression: + description: Represents the rule conditions that collectively evaluate to either true or false + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + operator: + type: string + left: + $ref: "#/components/schemas/Expression" + right: + $ref: "#/components/schemas/Expression" + MemberExpression: + description: Represents accessing a property of an object + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + object: + $ref: "#/components/schemas/Expression" + property: + $ref: "#/components/schemas/PropertyKey" + IndexExpression: + description: Represents indexing into an array + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + array: + $ref: "#/components/schemas/Expression" + index: + $ref: "#/components/schemas/Expression" + ObjectExpression: + description: Allows the declaration of an anonymous object within a declaration + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + properties: + description: Object properties + type: array + items: + $ref: "#/components/schemas/Property" + ParenExpression: + description: Represents an expression wrapped in parenthesis + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + expression: + $ref: "#/components/schemas/Expression" + PipeExpression: + description: Call expression with pipe argument + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + argument: + $ref: "#/components/schemas/Expression" + call: + $ref: "#/components/schemas/CallExpression" + UnaryExpression: + description: Uses operators to act on a single operand in an expression + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + operator: + type: string + argument: + $ref: "#/components/schemas/Expression" + BooleanLiteral: + description: Represents boolean values + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + value: + type: boolean + DateTimeLiteral: + description: Represents an instant in time with nanosecond precision using the syntax of golang's RFC3339 Nanosecond variant + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + value: + type: string + DurationLiteral: + 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: "#/components/schemas/NodeType" + values: + description: Duration values + type: array + items: + $ref: "#/components/schemas/Duration" + FloatLiteral: + description: Represents floating point numbers according to the double representations defined by the IEEE-754-1985 + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + value: + type: number + IntegerLiteral: + description: Represents integer numbers + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + value: + type: string + PipeLiteral: + description: Represents a specialized literal value, indicating the left hand value of a pipe expression + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + RegexpLiteral: + description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + value: + type: string + StringLiteral: + description: Expressions begin and end with double quote marks + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + value: + type: string + UnsignedIntegerLiteral: + description: Represents integer numbers + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + value: + type: string + Duration: + 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: "#/components/schemas/NodeType" + magnitude: + type: integer + unit: + type: string + Property: + description: The value associated with a key + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + key: + $ref: "#/components/schemas/PropertyKey" + value: + $ref: "#/components/schemas/Expression" + PropertyKey: + oneOf: + - $ref: "#/components/schemas/Identifier" + - $ref: "#/components/schemas/StringLiteral" + Identifier: + description: A valid Flux identifier + type: object + properties: + type: + $ref: "#/components/schemas/NodeType" + name: + type: string + NodeType: + description: Type of AST node + type: string + Dialect: + description: Dialect are options to change the default CSV output format; https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions + type: object + properties: + header: + description: If true, the results will contain a header row + type: boolean + default: true + delimiter: + description: Separator between cells; the default is , + type: string + default: "," + maxLength: 1 + minLength: 1 + annotations: + description: 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: Character prefixed to comment strings + type: string + default: "#" + maxLength: 1 + minLength: 0 + dateTimeFormat: + description: Format of timestamps + type: string + default: "RFC3339" + enum: + - RFC3339 + - RFC3339Nano + Permission: + required: [action, resource] + properties: + action: + type: string + enum: + - read + - write + resource: + $ref: "#/components/schemas/Resource" + Resource: + type: object + required: [type] + properties: + type: + type: string + enum: + - authorizations + - buckets + - dashboards + - orgs + - sources + - tasks + - telegrafs + - users + - variables + - scrapers + - secrets + - labels + - views + - documents + - notificationRules + - notificationEndpoints + - checks + - dbrp + id: + type: string + nullable: true + description: If ID is set that is a permission for a specific resource. if it is not set it is a permission for all resources of that resource type. + name: + type: string + nullable: true + description: Optional name of the resource if the resource has a name field. + orgID: + type: string + nullable: true + description: If orgID is set that is a permission for all resources owned my that org. if it is not set it is a permission for all resources of that resource type. + org: + type: string + nullable: true + description: Optional name of the organization of the organization with orgID. + AuthorizationUpdateRequest: + properties: + status: + description: If inactive the token is inactive and requests using the token will be rejected. + default: active + type: string + enum: + - active + - inactive + description: + type: string + description: A description of the token. + Authorization: + required: [orgID, permissions] + allOf: + - $ref: "#/components/schemas/AuthorizationUpdateRequest" + - type: object + properties: + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + orgID: + type: string + description: ID of org that authorization is scoped to. + permissions: + type: array + minItems: 1 + description: List of permissions for an auth. An auth must have at least one Permission. + items: + $ref: "#/components/schemas/Permission" + id: + readOnly: true + type: string + token: + readOnly: true + type: string + description: Passed via the Authorization Header and Token Authentication type. + userID: + readOnly: true + type: string + description: ID of user that created and owns the token. + user: + readOnly: true + type: string + description: Name of user that created and owns the token. + org: + readOnly: true + type: string + description: Name of the org token is scoped to. + links: + type: object + readOnly: true + example: + self: "/api/v2/authorizations/1" + user: "/api/v2/users/12" + properties: + self: + readOnly: true + $ref: "#/components/schemas/Link" + user: + readOnly: true + $ref: "#/components/schemas/Link" + Authorizations: + type: object + properties: + links: + readOnly: true + $ref: "#/components/schemas/Links" + authorizations: + type: array + items: + $ref: "#/components/schemas/Authorization" + PostBucketRequest: + properties: + orgID: + type: string + name: + type: string + description: + type: string + rp: + type: string + retentionRules: + $ref: "#/components/schemas/RetentionRules" + required: [orgID, name, retentionRules] + Bucket: + properties: + links: + type: object + readOnly: true + example: + labels: "/api/v2/buckets/1/labels" + members: "/api/v2/buckets/1/members" + org: "/api/v2/orgs/2" + owners: "/api/v2/buckets/1/owners" + self: "/api/v2/buckets/1" + write: "/api/v2/write?org=2&bucket=1" + properties: + labels: + description: URL to retrieve labels for this bucket + $ref: "#/components/schemas/Link" + members: + description: URL to retrieve members that can read this bucket + $ref: "#/components/schemas/Link" + org: + description: URL to retrieve parent organization for this bucket + $ref: "#/components/schemas/Link" + owners: + description: URL to retrieve owners that can read and write to this bucket. + $ref: "#/components/schemas/Link" + self: + description: URL for this bucket + $ref: "#/components/schemas/Link" + write: + description: URL to write line protocol for this bucket + $ref: "#/components/schemas/Link" + id: + readOnly: true + type: string + type: + readOnly: true + type: string + default: user + enum: + - user + - system + name: + type: string + description: + type: string + orgID: + type: string + rp: + type: string + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + retentionRules: + $ref: "#/components/schemas/RetentionRules" + labels: + $ref: "#/components/schemas/Labels" + required: [name, retentionRules] + Buckets: + type: object + properties: + links: + readOnly: true + $ref: "#/components/schemas/Links" + buckets: + type: array + items: + $ref: "#/components/schemas/Bucket" + RetentionRules: + type: array + description: Rules to expire or retain data. No rules means data never expires. + items: + $ref: "#/components/schemas/RetentionRule" + RetentionRule: + type: object + properties: + type: + type: string + default: expire + enum: + - expire + everySeconds: + type: integer + description: Duration in seconds for how long data will be kept in the database. + example: 86400 + minimum: 1 + required: [type, everySeconds] + Link: + type: string + format: uri + readOnly: true + description: URI of resource. + Links: + type: object + properties: + next: + $ref: "#/components/schemas/Link" + self: + $ref: "#/components/schemas/Link" + prev: + $ref: "#/components/schemas/Link" + required: [self] + Logs: + type: object + properties: + events: + readOnly: true + type: array + items: + $ref: "#/components/schemas/LogEvent" + LogEvent: + type: object + properties: + time: + readOnly: true + description: Time event occurred, RFC3339Nano. + type: string + format: date-time + message: + readOnly: true + description: A description of the event that occurred. + type: string + example: Halt and catch fire + Organization: + properties: + links: + type: object + readOnly: true + example: + self: "/api/v2/orgs/1" + members: "/api/v2/orgs/1/members" + owners: "/api/v2/orgs/1/owners" + labels: "/api/v2/orgs/1/labels" + secrets: "/api/v2/orgs/1/secrets" + buckets: "/api/v2/buckets?org=myorg" + tasks: "/api/v2/tasks?org=myorg" + dashboards: "/api/v2/dashboards?org=myorg" + properties: + self: + $ref: "#/components/schemas/Link" + members: + $ref: "#/components/schemas/Link" + owners: + $ref: "#/components/schemas/Link" + labels: + $ref: "#/components/schemas/Link" + secrets: + $ref: "#/components/schemas/Link" + buckets: + $ref: "#/components/schemas/Link" + tasks: + $ref: "#/components/schemas/Link" + dashboards: + $ref: "#/components/schemas/Link" + id: + readOnly: true + type: string + name: + type: string + description: + type: string + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + status: + description: If inactive the organization is inactive. + default: active + type: string + enum: + - active + - inactive + required: [name] + Organizations: + type: object + properties: + links: + $ref: "#/components/schemas/Links" + orgs: + type: array + items: + $ref: "#/components/schemas/Organization" + TemplateApply: + type: object + properties: + dryRun: + type: boolean + orgID: + type: string + stackID: + type: string + template: + type: object + properties: + contentType: + type: string + sources: + type: array + items: + type: string + contents: + $ref: "#/components/schemas/Template" + templates: + type: array + items: + type: object + properties: + contentType: + type: string + sources: + type: array + items: + type: string + contents: + $ref: "#/components/schemas/Template" + envRefs: + type: object + additionalProperties: + oneOf: + - type: string + - type: integer + - type: number + - type: boolean + secrets: + type: object + additionalProperties: + type: string + remotes: + type: array + items: + type: object + properties: + url: + type: string + contentType: + type: string + required: ["url"] + actions: + type: array + items: + oneOf: + - type: object + properties: + action: + type: string + enum: ["skipKind"] + properties: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + required: ["kind"] + - type: object + properties: + action: + type: string + enum: ["skipResource"] + properties: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + resourceTemplateName: + type: string + required: ["kind", "resourceTemplateName"] + TemplateKind: + type: string + enum: + - Bucket + - Check + - CheckDeadman + - CheckThreshold + - Dashboard + - Label + - NotificationEndpoint + - NotificationEndpointHTTP + - NotificationEndpointPagerDuty + - NotificationEndpointSlack + - NotificationRule + - Task + - Telegraf + - Variable + TemplateExportByID: + type: object + properties: + stackID: + type: string + orgIDs: + type: array + items: + type: object + properties: + orgID: + type: string + resourceFilters: + type: object + properties: + byLabel: + type: array + items: + type: string + byResourceKind: + type: array + items: + $ref: "#/components/schemas/TemplateKind" + resources: + type: object + properties: + id: + type: string + kind: + $ref: "#/components/schemas/TemplateKind" + name: + type: string + description: "if defined with id, name is used for resource exported by id. if defined independently, resources strictly matching name are exported" + required: [id, kind] + TemplateExportByName: + type: object + properties: + stackID: + type: string + orgIDs: + type: array + items: + type: object + properties: + orgID: + type: string + resourceFilters: + type: object + properties: + byLabel: + type: array + items: + type: string + byResourceKind: + type: array + items: + $ref: "#/components/schemas/TemplateKind" + resources: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + name: + type: string + required: [name, kind] + Template: + type: array + items: + type: object + properties: + apiVersion: + type: string + kind: + $ref: "#/components/schemas/TemplateKind" + meta: + type: object + properties: + name: + type: string + spec: + type: object + TemplateEnvReferences: + type: array + items: + type: object + properties: + resourceField: + type: string + description: Field the environment reference corresponds too + envRefKey: + type: string + description: Key identified as environment reference and is the key identified in the template + value: + description: Value provided to fulfill reference + nullable: true + oneOf: + - type: string + - type: integer + - type: number + - type: boolean + defaultValue: + description: Default value that will be provided for the reference when no value is provided + nullable: true + oneOf: + - type: string + - type: integer + - type: number + - type: boolean + required: [resourceField, envRefKey] + TemplateSummary: + type: object + properties: + sources: + type: array + items: + type: string + stackID: + type: string + summary: + type: object + properties: + buckets: + type: array + items: + type: object + properties: + id: + type: string + orgID: + type: string + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + name: + type: string + description: + type: string + retentionPeriod: + type: integer + labelAssociations: + type: array + items: + $ref: "#/components/schemas/TemplateSummaryLabel" + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + checks: + type: array + items: + allOf: + - $ref: "#/components/schemas/CheckDiscriminator" + - type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + labelAssociations: + type: array + items: + $ref: "#/components/schemas/TemplateSummaryLabel" + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + dashboards: + type: array + items: + type: object + properties: + id: + type: "string" + orgID: + type: "string" + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + name: + type: "string" + description: + type: "string" + labelAssociations: + type: array + items: + $ref: "#/components/schemas/TemplateSummaryLabel" + charts: + type: array + items: + $ref: "#/components/schemas/TemplateChart" + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + labels: + type: array + items: + $ref: "#/components/schemas/TemplateSummaryLabel" + labelMappings: + type: array + items: + type: object + properties: + status: + type: string + resourceTemplateMetaName: + type: string + resourceName: + type: string + resourceID: + type: string + resourceType: + type: string + labelTemplateMetaName: + type: string + labelName: + type: string + labelID: + type: string + missingEnvRefs: + type: array + items: + type: string + missingSecrets: + type: array + items: + type: string + notificationEndpoints: + type: array + items: + allOf: + - $ref: "#/components/schemas/NotificationEndpointDiscrimator" + - type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + labelAssociations: + type: array + items: + $ref: "#/components/schemas/TemplateSummaryLabel" + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + notificationRules: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + name: + type: string + description: + type: string + endpointTemplateMetaName: + type: string + endpointID: + type: string + endpointType: + type: string + every: + type: string + offset: + type: string + messageTemplate: + type: string + status: + type: string + statusRules: + type: array + items: + type: object + properties: + currentLevel: + type: string + previousLevel: + type: string + tagRules: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + operator: + type: string + labelAssociations: + type: array + items: + $ref: "#/components/schemas/TemplateSummaryLabel" + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + tasks: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + id: + type: string + name: + type: string + cron: + type: string + description: + type: string + every: + type: string + offset: + type: string + query: + type: string + status: + type: string + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + telegrafConfigs: + type: array + items: + allOf: + - $ref: "#/components/schemas/TelegrafRequest" + - type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + labelAssociations: + type: array + items: + $ref: "#/components/schemas/TemplateSummaryLabel" + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + variables: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + id: + type: string + orgID: + type: string + name: + type: string + description: + type: string + arguments: + $ref: "#/components/schemas/VariableProperties" + labelAssociations: + type: array + items: + $ref: "#/components/schemas/TemplateSummaryLabel" + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + diff: + type: object + properties: + buckets: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + stateStatus: + type: string + id: + type: string + templateMetaName: + type: string + new: + type: object + properties: + name: + type: string + description: + type: string + retentionRules: + $ref: "#/components/schemas/RetentionRules" + old: + type: object + properties: + name: + type: string + description: + type: string + retentionRules: + $ref: "#/components/schemas/RetentionRules" + checks: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + stateStatus: + type: string + id: + type: string + templateMetaName: + type: string + new: + $ref: "#/components/schemas/CheckDiscriminator" + old: + $ref: "#/components/schemas/CheckDiscriminator" + dashboards: + type: array + items: + type: object + properties: + stateStatus: + type: string + id: + type: string + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + new: + type: object + properties: + name: + type: string + description: + type: string + charts: + type: array + items: + $ref: "#/components/schemas/TemplateChart" + old: + type: object + properties: + name: + type: string + description: + type: string + charts: + type: array + items: + $ref: "#/components/schemas/TemplateChart" + labels: + type: array + items: + type: object + properties: + stateStatus: + type: string + kind: + $ref: "#/components/schemas/TemplateKind" + id: + type: string + templateMetaName: + type: string + new: + type: object + properties: + name: + type: string + color: + type: string + description: + type: string + old: + type: object + properties: + name: + type: string + color: + type: string + description: + type: string + labelMappings: + type: array + items: + type: object + properties: + status: + type: string + resourceType: + type: string + resourceID: + type: string + resourceTemplateMetaName: + type: string + resourceName: + type: string + labelID: + type: string + labelTemplateMetaName: + type: string + labelName: + type: string + notificationEndpoints: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + stateStatus: + type: string + id: + type: string + templateMetaName: + type: string + new: + $ref: "#/components/schemas/NotificationEndpointDiscrimator" + old: + $ref: "#/components/schemas/NotificationEndpointDiscrimator" + notificationRules: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + stateStatus: + type: string + id: + type: string + templateMetaName: + type: string + new: + type: object + properties: + name: + type: string + description: + type: string + endpointName: + type: string + endpointID: + type: string + endpointType: + type: string + every: + type: string + offset: + type: string + messageTemplate: + type: string + status: + type: string + statusRules: + type: array + items: + type: object + properties: + currentLevel: + type: string + previousLevel: + type: string + tagRules: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + operator: + type: string + old: + type: object + properties: + name: + type: string + description: + type: string + endpointName: + type: string + endpointID: + type: string + endpointType: + type: string + every: + type: string + offset: + type: string + messageTemplate: + type: string + status: + type: string + statusRules: + type: array + items: + type: object + properties: + currentLevel: + type: string + previousLevel: + type: string + tagRules: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + operator: + type: string + tasks: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + stateStatus: + type: string + id: + type: string + templateMetaName: + type: string + new: + type: object + properties: + name: + type: string + cron: + type: string + description: + type: string + every: + type: string + offset: + type: string + query: + type: string + status: + type: string + old: + type: object + properties: + name: + type: string + cron: + type: string + description: + type: string + every: + type: string + offset: + type: string + query: + type: string + status: + type: string + telegrafConfigs: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + stateStatus: + type: string + id: + type: string + templateMetaName: + type: string + new: + $ref: "#/components/schemas/TelegrafRequest" + old: + $ref: "#/components/schemas/TelegrafRequest" + variables: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + stateStatus: + type: string + id: + type: string + templateMetaName: + type: string + new: + type: object + properties: + name: + type: string + description: + type: string + args: + $ref: "#/components/schemas/VariableProperties" + old: + type: object + properties: + name: + type: string + description: + type: string + args: + $ref: "#/components/schemas/VariableProperties" + errors: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + reason: + type: string + fields: + type: array + items: + type: string + indexes: + type: array + items: + type: integer + TemplateSummaryLabel: + type: object + properties: + id: + type: string + orgID: + type: string + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + name: + type: string + properties: + type: object + properties: + color: + type: string + description: + type: string + envReferences: + $ref: "#/components/schemas/TemplateEnvReferences" + TemplateChart: + type: object + properties: + xPos: + type: integer + yPos: + type: integer + height: + type: integer + width: + type: integer + properties: # field name is properties + $ref: "#/components/schemas/ViewProperties" + Stack: + type: object + properties: + id: + type: string + orgID: + type: string + createdAt: + type: string + format: date-time + readOnly: true + events: + type: array + items: + type: object + properties: + eventType: + type: string + name: + type: string + description: + type: string + sources: + type: array + items: + type: string + resources: + type: array + items: + type: object + properties: + apiVersion: + type: string + resourceID: + type: string + kind: + $ref: "#/components/schemas/TemplateKind" + templateMetaName: + type: string + associations: + type: array + items: + type: object + properties: + kind: + $ref: "#/components/schemas/TemplateKind" + metaName: + type: string + links: + type: object + properties: + self: + type: string + urls: + type: array + items: + type: string + updatedAt: + type: string + format: date-time + readOnly: true + Runs: + type: object + properties: + links: + $ref: "#/components/schemas/Links" + runs: + type: array + items: + $ref: "#/components/schemas/Run" + Run: + properties: + id: + readOnly: true + type: string + taskID: + readOnly: true + type: string + status: + readOnly: true + type: string + enum: + - scheduled + - started + - failed + - success + - canceled + scheduledFor: + description: Time used for run's "now" option, RFC3339. + type: string + format: date-time + log: + description: An array of logs associated with the run. + type: array + readOnly: true + items: + type: object + properties: + runID: + type: string + time: + type: string + message: + type: string + startedAt: + readOnly: true + description: Time run started executing, RFC3339Nano. + type: string + format: date-time + finishedAt: + readOnly: true + description: Time run finished executing, RFC3339Nano. + type: string + format: date-time + requestedAt: + readOnly: true + description: Time run was manually requested, RFC3339Nano. + type: string + format: date-time + links: + type: object + readOnly: true + example: + self: "/api/v2/tasks/1/runs/1" + task: "/api/v2/tasks/1" + retry: "/api/v2/tasks/1/runs/1/retry" + properties: + self: + type: string + format: uri + task: + type: string + format: uri + retry: + type: string + format: uri + RunManually: + properties: + scheduledFor: + nullable: true + description: Time used for run's "now" option, RFC3339. Default is the server's now time. + type: string + format: date-time + Tasks: + type: object + properties: + links: + readOnly: true + $ref: "#/components/schemas/Links" + tasks: + type: array + items: + $ref: "#/components/schemas/Task" + Task: + type: object + properties: + id: + readOnly: true + type: string + type: + description: The type of task, this can be used for filtering tasks on list actions. + type: string + orgID: + description: The ID of the organization that owns this Task. + type: string + org: + description: The name of the organization that owns this Task. + type: string + name: + description: The name of the task. + type: string + description: + description: An optional description of the task. + type: string + status: + $ref: "#/components/schemas/TaskStatusType" + labels: + $ref: "#/components/schemas/Labels" + authorizationID: + description: The ID of the authorization used when this task communicates with the query engine. + type: string + flux: + description: The Flux script to run for this task. + type: string + every: + description: A simple task repetition schedule; parsed from Flux. + type: string + cron: + description: A task repetition schedule in the form '* * * * * *'; parsed from Flux. + type: string + offset: + description: Duration to delay after the schedule, before executing the task; parsed from flux, if set to zero it will remove this option and use 0 as the default. + type: string + latestCompleted: + description: Timestamp of latest scheduled, completed run, RFC3339. + type: string + format: date-time + readOnly: true + lastRunStatus: + readOnly: true + type: string + enum: + - failed + - success + - canceled + lastRunError: + readOnly: true + type: string + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + links: + type: object + readOnly: true + example: + self: "/api/v2/tasks/1" + owners: "/api/v2/tasks/1/owners" + members: "/api/v2/tasks/1/members" + labels: "/api/v2/tasks/1/labels" + runs: "/api/v2/tasks/1/runs" + logs: "/api/v2/tasks/1/logs" + properties: + self: + $ref: "#/components/schemas/Link" + owners: + $ref: "#/components/schemas/Link" + members: + $ref: "#/components/schemas/Link" + runs: + $ref: "#/components/schemas/Link" + logs: + $ref: "#/components/schemas/Link" + labels: + $ref: "#/components/schemas/Link" + required: [id, name, orgID, flux] + TaskStatusType: + type: string + enum: [active, inactive] + Invite: + properties: + id: + description: the idpe id of the invite + readOnly: true + type: string + email: + type: string + role: + type: string + enum: + - member + - owner + expiresAt: + format: date-time + type: string + links: + type: object + readOnly: true + example: + self: "/api/v2/invites/1" + properties: + self: + type: string + format: uri + required: [id, email, role] + Invites: + type: object + properties: + links: + type: object + properties: + self: + type: string + format: uri + invites: + type: array + items: + $ref: "#/components/schemas/Invite" + User: + properties: + id: + readOnly: true + type: string + oauthID: + type: string + name: + type: string + status: + description: If inactive the user is inactive. + default: active + type: string + enum: + - active + - inactive + links: + type: object + readOnly: true + example: + self: "/api/v2/users/1" + properties: + self: + type: string + format: uri + required: [name] + Users: + type: object + properties: + links: + type: object + properties: + self: + type: string + format: uri + users: + type: array + items: + $ref: "#/components/schemas/User" + Flags: + type: object + additionalProperties: true + ResourceMember: + allOf: + - $ref: "#/components/schemas/User" + - type: object + properties: + role: + type: string + default: member + enum: + - member + ResourceMembers: + type: object + properties: + links: + type: object + properties: + self: + type: string + format: uri + users: + type: array + items: + $ref: "#/components/schemas/ResourceMember" + ResourceOwner: + allOf: + - $ref: "#/components/schemas/User" + - type: object + properties: + role: + type: string + default: owner + enum: + - owner + ResourceOwners: + type: object + properties: + links: + type: object + properties: + self: + type: string + format: uri + users: + type: array + items: + $ref: "#/components/schemas/ResourceOwner" + FluxSuggestions: + type: object + properties: + funcs: + type: array + items: + $ref: "#/components/schemas/FluxSuggestion" + FluxSuggestion: + type: object + properties: + name: + type: string + params: + type: object + additionalProperties: + type: string + Routes: + properties: + authorizations: + type: string + format: uri + buckets: + type: string + format: uri + dashboards: + type: string + format: uri + external: + type: object + properties: + statusFeed: + type: string + format: uri + variables: + type: string + format: uri + me: + type: string + format: uri + flags: + type: string + format: uri + orgs: + type: string + format: uri + query: + type: object + properties: + self: + type: string + format: uri + ast: + type: string + format: uri + analyze: + type: string + format: uri + suggestions: + type: string + format: uri + setup: + type: string + format: uri + signin: + type: string + format: uri + signout: + type: string + format: uri + sources: + type: string + format: uri + system: + type: object + properties: + metrics: + type: string + format: uri + debug: + type: string + format: uri + health: + type: string + format: uri + tasks: + type: string + format: uri + telegrafs: + type: string + format: uri + users: + type: string + format: uri + write: + type: string + format: uri + Error: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + # This set of enumerations must remain in sync with the constants defined in errors.go + enum: + - internal error + - not found + - conflict + - invalid + - unprocessable entity + - empty value + - unavailable + - forbidden + - too many requests + - unauthorized + - method not allowed + message: + readOnly: true + description: Message is a human-readable message. + type: string + required: [code, message] + LineProtocolError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - internal error + - not found + - conflict + - invalid + - empty value + - unavailable + message: + readOnly: true + description: Message is a human-readable message. + type: string + op: + readOnly: true + description: Op describes the logical code operation during error. Useful for debugging. + type: string + err: + readOnly: true + description: Err is a stack of errors that occurred during processing of the request. Useful for debugging. + type: string + line: + readOnly: true + description: First line within sent body containing malformed data + type: integer + format: int32 + required: [code, message, op, err] + LineProtocolLengthError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - invalid + message: + readOnly: true + description: Message is a human-readable message. + type: string + maxLength: + readOnly: true + description: Max length in bytes for a body of line-protocol. + type: integer + format: int32 + required: [code, message, maxLength] + Field: + type: object + properties: + value: + description: >- + value is the value of the field. Meaning of the value is implied by + the `type` key + type: string + type: + description: >- + `type` describes the field type. `func` is a function. `field` is a field reference. + type: string + enum: + - func + - field + - integer + - number + - regex + - wildcard + alias: + description: >- + Alias overrides the field name in the returned response. Applies only + if type is `func` + type: string + args: + description: Args are the arguments to the function + type: array + items: + $ref: "#/components/schemas/Field" + BuilderConfig: + type: object + properties: + buckets: + type: array + items: + type: string + tags: + type: array + items: + $ref: "#/components/schemas/BuilderTagsType" + functions: + type: array + items: + $ref: "#/components/schemas/BuilderFunctionsType" + aggregateWindow: + type: object + properties: + period: + type: string + fillValues: + type: boolean + BuilderTagsType: + type: object + properties: + key: + type: string + values: + type: array + items: + type: string + aggregateFunctionType: + $ref: "#/components/schemas/BuilderAggregateFunctionType" + BuilderAggregateFunctionType: + type: string + enum: ["filter", "group"] + BuilderFunctionsType: + type: object + properties: + name: + type: string + DashboardQuery: + type: object + properties: + text: + type: string + description: The text of the Flux query. + editMode: + $ref: "#/components/schemas/QueryEditMode" + name: + type: string + builderConfig: + $ref: "#/components/schemas/BuilderConfig" + QueryEditMode: + type: string + enum: ["builder", "advanced"] + Axis: + type: object + description: The description of a particular axis for a visualization. + properties: + bounds: + type: array + minItems: 0 + maxItems: 2 + description: >- + The extents of an axis in the form [lower, upper]. Clients determine + whether bounds are to be inclusive or exclusive of their limits + items: + type: string + label: + description: Label is a description of this Axis + type: string + prefix: + description: Prefix represents a label prefix for formatting axis values. + type: string + suffix: + description: Suffix represents a label suffix for formatting axis values. + type: string + base: + description: Base represents the radix for formatting axis values. + type: string + enum: ["", "2", "10"] + scale: + $ref: "#/components/schemas/AxisScale" + AxisScale: + description: 'Scale is the axis formatting scale. Supported: "log", "linear"' + type: string + enum: ["log", "linear"] + DashboardColor: + type: object + description: Defines an encoding of data value into color space. + required: [id, type, hex, name, value] + properties: + id: + description: The unique ID of the view color. + type: string + type: + description: Type is how the color is used. + type: string + enum: + - min + - max + - threshold + - scale + - text + - background + hex: + description: The hex number of the color + type: string + maxLength: 7 + minLength: 7 + name: + description: The user-facing name of the hex color. + type: string + value: + description: The data value mapped to this color. + type: number + format: float + RenamableField: + description: Describes a field that can be renamed and made visible or invisible. + type: object + properties: + internalName: + description: The calculated name of a field. + readOnly: true + type: string + displayName: + description: The name that a field is renamed to by the user. + type: string + visible: + description: Indicates whether this field should be visible on the table. + type: boolean + XYViewProperties: + type: object + required: + - type + - geom + - queries + - shape + - axes + - colors + - legend + - note + - showNoteWhenEmpty + - position + properties: + timeFormat: + type: string + type: + type: string + enum: [xy] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + $ref: "#/components/schemas/DashboardColor" + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + axes: + $ref: "#/components/schemas/Axes" + legend: + $ref: "#/components/schemas/Legend" + xColumn: + type: string + yColumn: + type: string + shadeBelow: + type: boolean + hoverDimension: + type: string + enum: [auto, x, y, xy] + position: + type: string + enum: [overlaid, stacked] + geom: + $ref: "#/components/schemas/XYGeom" + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + XYGeom: + type: string + enum: [line, step, stacked, bar, monotoneX] + BandViewProperties: + type: object + required: + - type + - geom + - queries + - shape + - axes + - colors + - legend + - note + - showNoteWhenEmpty + properties: + timeFormat: + type: string + type: + type: string + enum: [band] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + $ref: "#/components/schemas/DashboardColor" + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + axes: + $ref: "#/components/schemas/Axes" + legend: + $ref: "#/components/schemas/Legend" + xColumn: + type: string + yColumn: + type: string + upperColumn: + type: string + mainColumn: + type: string + lowerColumn: + type: string + hoverDimension: + type: string + enum: [auto, x, y, xy] + geom: + $ref: "#/components/schemas/XYGeom" + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + LinePlusSingleStatProperties: + type: object + required: + - type + - queries + - shape + - axes + - colors + - legend + - note + - showNoteWhenEmpty + - prefix + - suffix + - decimalPlaces + - position + properties: + timeFormat: + type: string + type: + type: string + enum: [line-plus-single-stat] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + $ref: "#/components/schemas/DashboardColor" + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + axes: + $ref: "#/components/schemas/Axes" + legend: + $ref: "#/components/schemas/Legend" + xColumn: + type: string + yColumn: + type: string + shadeBelow: + type: boolean + hoverDimension: + type: string + enum: [auto, x, y, xy] + position: + type: string + enum: [overlaid, stacked] + prefix: + type: string + suffix: + type: string + decimalPlaces: + $ref: "#/components/schemas/DecimalPlaces" + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + MosaicViewProperties: + type: object + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - ySeriesColumns + - fillColumns + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + properties: + timeFormat: + type: string + type: + type: string + enum: [mosaic] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + type: string + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + xColumn: + type: string + ySeriesColumns: + type: array + items: + type: string + fillColumns: + type: array + items: + type: string + xDomain: + type: array + items: + type: number + maxItems: 2 + yDomain: + type: array + items: + type: number + maxItems: 2 + xAxisLabel: + type: string + yAxisLabel: + type: string + xPrefix: + type: string + xSuffix: + type: string + yPrefix: + type: string + ySuffix: + type: string + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + ScatterViewProperties: + type: object + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - yColumn + - fillColumns + - symbolColumns + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + properties: + timeFormat: + type: string + type: + type: string + enum: [scatter] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + type: string + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + xColumn: + type: string + yColumn: + type: string + fillColumns: + type: array + items: + type: string + symbolColumns: + type: array + items: + type: string + xDomain: + type: array + items: + type: number + maxItems: 2 + yDomain: + type: array + items: + type: number + maxItems: 2 + xAxisLabel: + type: string + yAxisLabel: + type: string + xPrefix: + type: string + xSuffix: + type: string + yPrefix: + type: string + ySuffix: + type: string + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + HeatmapViewProperties: + type: object + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - yColumn + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + - binSize + properties: + timeFormat: + type: string + type: + type: string + enum: [heatmap] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + type: string + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + xColumn: + type: string + yColumn: + type: string + xDomain: + type: array + items: + type: number + maxItems: 2 + yDomain: + type: array + items: + type: number + maxItems: 2 + xAxisLabel: + type: string + yAxisLabel: + type: string + xPrefix: + type: string + xSuffix: + type: string + yPrefix: + type: string + ySuffix: + type: string + binSize: + type: number + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + SingleStatViewProperties: + type: object + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - prefix + - tickPrefix + - suffix + - tickSuffix + - legend + - decimalPlaces + properties: + type: + type: string + enum: [single-stat] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + $ref: "#/components/schemas/DashboardColor" + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + prefix: + type: string + tickPrefix: + type: string + suffix: + type: string + tickSuffix: + type: string + legend: + $ref: "#/components/schemas/Legend" + decimalPlaces: + $ref: "#/components/schemas/DecimalPlaces" + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + HistogramViewProperties: + type: object + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - fillColumns + - xDomain + - xAxisLabel + - position + - binCount + properties: + type: + type: string + enum: [histogram] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + $ref: "#/components/schemas/DashboardColor" + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + xColumn: + type: string + fillColumns: + type: array + items: + type: string + xDomain: + type: array + items: + type: number + format: float + xAxisLabel: + type: string + position: + type: string + enum: [overlaid, stacked] + binCount: + type: integer + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + GaugeViewProperties: + type: object + required: + [ + type, + queries, + colors, + shape, + note, + showNoteWhenEmpty, + prefix, + tickPrefix, + suffix, + tickSuffix, + legend, + decimalPlaces, + ] + properties: + type: + type: string + enum: [gauge] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + $ref: "#/components/schemas/DashboardColor" + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + prefix: + type: string + tickPrefix: + type: string + suffix: + type: string + tickSuffix: + type: string + legend: + $ref: "#/components/schemas/Legend" + decimalPlaces: + $ref: "#/components/schemas/DecimalPlaces" + TableViewProperties: + type: object + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - tableOptions + - fieldOptions + - timeFormat + - decimalPlaces + properties: + type: + type: string + enum: [table] + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + $ref: "#/components/schemas/DashboardColor" + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + tableOptions: + properties: + verticalTimeAxis: + description: >- + verticalTimeAxis describes the orientation of the table by + indicating whether the time axis will be displayed vertically + type: boolean + sortBy: + $ref: "#/components/schemas/RenamableField" + wrapping: + description: Wrapping describes the text wrapping style to be used in table views + type: string + enum: + - truncate + - wrap + - single-line + fixFirstColumn: + description: >- + fixFirstColumn indicates whether the first column of the table + should be locked + type: boolean + fieldOptions: + description: >- + fieldOptions represent the fields retrieved by the query with + customization options + type: array + items: + $ref: "#/components/schemas/RenamableField" + timeFormat: + description: >- + timeFormat describes the display format for time values according to + moment.js date formatting + type: string + decimalPlaces: + $ref: "#/components/schemas/DecimalPlaces" + MarkdownViewProperties: + type: object + required: + - type + - shape + - note + properties: + type: + type: string + enum: [markdown] + shape: + type: string + enum: ["chronograf-v2"] + note: + type: string + CheckViewProperties: + type: object + required: + - type + - shape + - checkID + - queries + - colors + properties: + type: + type: string + enum: [check] + shape: + type: string + enum: ["chronograf-v2"] + checkID: + type: string + check: + $ref: "#/components/schemas/Check" + queries: + type: array + items: + $ref: "#/components/schemas/DashboardQuery" + colors: + description: Colors define color encoding of data into a visualization + type: array + items: + $ref: "#/components/schemas/DashboardColor" + legendOpacity: + type: number + format: float + legendOrientationThreshold: + type: integer + Axes: + description: The viewport for a View's visualizations + type: object + required: ["x", "y"] + properties: + x: + $ref: "#/components/schemas/Axis" + "y": # Quoted to prevent YAML parser from interpreting y as shorthand for true. + $ref: "#/components/schemas/Axis" + Legend: + description: Legend define encoding of data into a view's legend + type: object + properties: + type: + description: The style of the legend. + type: string + enum: + - static + orientation: + description: >- + orientation is the location of the legend with respect to the view + graph + type: string + enum: + - top + - bottom + - left + - right + DecimalPlaces: + description: Indicates whether decimal places should be enforced, and how many digits it should show. + type: object + properties: + isEnforced: + description: Indicates whether decimal point setting should be enforced + type: boolean + digits: + description: The number of digits after decimal to display + type: integer + format: int32 + ConstantVariableProperties: + properties: + type: + type: string + enum: [constant] + values: + type: array + items: + type: string + MapVariableProperties: + properties: + type: + type: string + enum: [map] + values: + type: object + additionalProperties: + type: string + QueryVariableProperties: + properties: + type: + type: string + enum: [query] + values: + type: object + properties: + query: + type: string + language: + type: string + Variable: + type: object + required: + - name + - orgID + - arguments + properties: + links: + type: object + readOnly: true + properties: + self: + type: string + format: uri + org: + type: string + format: uri + labels: + type: string + format: uri + id: + readOnly: true + type: string + orgID: + type: string + name: + type: string + description: + type: string + selected: + type: array + items: + type: string + labels: + $ref: "#/components/schemas/Labels" + arguments: + $ref: "#/components/schemas/VariableProperties" + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + Variables: + type: object + example: + variables: + - id: "1221432" + name: ":ok:" + selected: + - hello + arguments: + type: constant + values: + - howdy + - hello + - hi + - yo + - oy + - id: "1221432" + name: ":ok:" + selected: + - c + arguments: + type: map + values: + a: fdjaklfdjkldsfjlkjdsa + b: dfaksjfkljekfajekdljfas + c: fdjksajfdkfeawfeea + - id: "1221432" + name: ":ok:" + selected: + - host + arguments: + type: query + query: 'from(bucket: "foo") |> showMeasurements()' + language: flux + properties: + variables: + type: array + items: + $ref: "#/components/schemas/Variable" + VariableProperties: + type: object + oneOf: + - $ref: "#/components/schemas/QueryVariableProperties" + - $ref: "#/components/schemas/ConstantVariableProperties" + - $ref: "#/components/schemas/MapVariableProperties" + ViewProperties: + oneOf: + - $ref: "#/components/schemas/LinePlusSingleStatProperties" + - $ref: "#/components/schemas/XYViewProperties" + - $ref: "#/components/schemas/SingleStatViewProperties" + - $ref: "#/components/schemas/HistogramViewProperties" + - $ref: "#/components/schemas/GaugeViewProperties" + - $ref: "#/components/schemas/TableViewProperties" + - $ref: "#/components/schemas/MarkdownViewProperties" + - $ref: "#/components/schemas/CheckViewProperties" + - $ref: "#/components/schemas/ScatterViewProperties" + - $ref: "#/components/schemas/HeatmapViewProperties" + - $ref: "#/components/schemas/MosaicViewProperties" + - $ref: "#/components/schemas/BandViewProperties" + View: + required: + - name + - properties + properties: + links: + type: object + readOnly: true + properties: + self: + type: string + id: + readOnly: true + type: string + name: + type: string + properties: + $ref: "#/components/schemas/ViewProperties" + Views: + type: object + properties: + links: + type: object + properties: + self: + type: string + views: + type: array + items: + $ref: "#/components/schemas/View" + CellUpdate: + type: object + properties: + x: + type: integer + format: int32 + "y": # Quoted to prevent YAML parser from interpreting y as shorthand for true. + type: integer + format: int32 + w: + type: integer + format: int32 + h: + type: integer + format: int32 + CreateCell: + type: object + properties: + name: + type: string + x: + type: integer + format: int32 + "y": # Quoted to prevent YAML parser from interpreting y as shorthand for true. + type: integer + format: int32 + w: + type: integer + format: int32 + h: + type: integer + format: int32 + usingView: + type: string + description: Makes a copy of the provided view. + AnalyzeQueryResponse: + type: object + properties: + errors: + type: array + items: + type: object + properties: + line: + type: integer + column: + type: integer + character: + type: integer + message: + type: string + CellWithViewProperties: + type: object + allOf: + - $ref: "#/components/schemas/Cell" + - type: object + properties: + name: + type: string + properties: + $ref: "#/components/schemas/ViewProperties" + Cell: + type: object + properties: + id: + type: string + links: + type: object + properties: + self: + type: string + view: + type: string + x: + type: integer + format: int32 + "y": # Quoted to prevent YAML parser from interpreting y as shorthand for true. + type: integer + format: int32 + w: + type: integer + format: int32 + h: + type: integer + format: int32 + viewID: + type: string + description: The reference to a view from the views API. + CellsWithViewProperties: + type: array + items: + $ref: "#/components/schemas/CellWithViewProperties" + Cells: + type: array + items: + $ref: "#/components/schemas/Cell" + Secrets: + additionalProperties: + type: string + example: + apikey: abc123xyz + SecretKeys: + type: object + properties: + secrets: + type: array + items: + type: string + SecretKeysResponse: + allOf: + - $ref: "#/components/schemas/SecretKeys" + - type: object + properties: + links: + readOnly: true + type: object + properties: + self: + type: string + org: + type: string + CreateDashboardRequest: + properties: + orgID: + type: string + description: The ID of the organization that owns the dashboard. + name: + type: string + description: The user-facing name of the dashboard. + description: + type: string + description: The user-facing description of the dashboard. + required: + - orgID + - name + DashboardWithViewProperties: + type: object + allOf: + - $ref: "#/components/schemas/CreateDashboardRequest" + - type: object + properties: + links: + type: object + example: + self: "/api/v2/dashboards/1" + cells: "/api/v2/dashboards/1/cells" + owners: "/api/v2/dashboards/1/owners" + members: "/api/v2/dashboards/1/members" + labels: "/api/v2/dashboards/1/labels" + org: "/api/v2/labels/1" + properties: + self: + $ref: "#/components/schemas/Link" + cells: + $ref: "#/components/schemas/Link" + members: + $ref: "#/components/schemas/Link" + owners: + $ref: "#/components/schemas/Link" + labels: + $ref: "#/components/schemas/Link" + org: + $ref: "#/components/schemas/Link" + id: + readOnly: true + type: string + meta: + type: object + properties: + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + cells: + $ref: "#/components/schemas/CellsWithViewProperties" + labels: + $ref: "#/components/schemas/Labels" + Dashboard: + type: object + allOf: + - $ref: "#/components/schemas/CreateDashboardRequest" + - type: object + properties: + links: + type: object + example: + self: "/api/v2/dashboards/1" + cells: "/api/v2/dashboards/1/cells" + owners: "/api/v2/dashboards/1/owners" + members: "/api/v2/dashboards/1/members" + labels: "/api/v2/dashboards/1/labels" + org: "/api/v2/labels/1" + properties: + self: + $ref: "#/components/schemas/Link" + cells: + $ref: "#/components/schemas/Link" + members: + $ref: "#/components/schemas/Link" + owners: + $ref: "#/components/schemas/Link" + labels: + $ref: "#/components/schemas/Link" + org: + $ref: "#/components/schemas/Link" + id: + readOnly: true + type: string + meta: + type: object + properties: + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + cells: + $ref: "#/components/schemas/Cells" + labels: + $ref: "#/components/schemas/Labels" + Dashboards: + type: object + properties: + links: + $ref: "#/components/schemas/Links" + dashboards: + type: array + items: + $ref: "#/components/schemas/Dashboard" + Source: + type: object + properties: + links: + type: object + properties: + self: + type: string + query: + type: string + health: + type: string + buckets: + type: string + id: + type: string + orgID: + type: string + default: + type: boolean + name: + type: string + type: + type: string + enum: ["v1", "v2", "self"] + url: + type: string + format: uri + insecureSkipVerify: + type: boolean + telegraf: + type: string + token: + type: string + username: + type: string + password: + type: string + sharedSecret: + type: string + metaUrl: + type: string + format: uri + defaultRP: + type: string + languages: + type: array + readOnly: true + items: + type: string + enum: + - flux + - influxql + Sources: + type: object + properties: + links: + type: object + properties: + self: + type: string + format: uri + sources: + type: array + items: + $ref: "#/components/schemas/Source" + ScraperTargetRequest: + type: object + properties: + name: + type: string + description: The name of the scraper target. + type: + type: string + description: The type of the metrics to be parsed. + enum: [prometheus] + url: + type: string + description: The URL of the metrics endpoint. + example: http://localhost:9090/metrics + orgID: + type: string + description: The organization ID. + bucketID: + type: string + description: The ID of the bucket to write to. + ScraperTargetResponse: + type: object + allOf: + - $ref: "#/components/schemas/ScraperTargetRequest" + - type: object + properties: + id: + type: string + readOnly: true + org: + type: string + description: The organization name. + bucket: + type: string + description: The bucket name. + links: + type: object + readOnly: true + example: + self: "/api/v2/scrapers/1" + owners: "/api/v2/scrapers/1/owners" + members: "/api/v2/scrapers/1/members" + bucket: "/api/v2/buckets/1" + organization: "/api/v2/orgs/1" + properties: + self: + $ref: "#/components/schemas/Link" + members: + $ref: "#/components/schemas/Link" + owners: + $ref: "#/components/schemas/Link" + bucket: + $ref: "#/components/schemas/Link" + organization: + $ref: "#/components/schemas/Link" + ScraperTargetResponses: + type: object + properties: + configurations: + type: array + items: + $ref: "#/components/schemas/ScraperTargetResponse" + DocumentMeta: + type: object + properties: + name: + type: string + type: + type: string + templateID: + type: string + description: + type: string + version: + type: string + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + required: + - name + - version + Document: + type: object + properties: + id: + type: string + readOnly: true + meta: + $ref: "#/components/schemas/DocumentMeta" + content: + type: object + labels: + $ref: "#/components/schemas/Labels" + links: + type: object + readOnly: true + example: + self: "/api/v2/documents/templates/1" + properties: + self: + description: The document URL. + $ref: "#/components/schemas/Link" + required: + - id + - meta + - content + DocumentCreate: + type: object + properties: + meta: + $ref: "#/components/schemas/DocumentMeta" + content: + type: object + org: + type: string + description: The organization Name. Specify either `orgID` or `org`. + orgID: + type: string + description: The organization Name. Specify either `orgID` or `org`. + labels: + type: array + description: An array of label IDs to be added as labels to the document. + items: + type: string + required: + - meta + - content + DocumentUpdate: + type: object + properties: + meta: + $ref: "#/components/schemas/DocumentMeta" + content: + type: object + DocumentListEntry: + type: object + properties: + id: + type: string + readOnly: true + meta: + $ref: "#/components/schemas/DocumentMeta" + labels: + $ref: "#/components/schemas/Labels" + links: + type: object + readOnly: true + example: + self: "/api/v2/documents/templates/1" + properties: + self: + description: The document URL. + $ref: "#/components/schemas/Link" + required: + - id + - meta + Documents: + type: object + properties: + documents: + type: array + items: + $ref: "#/components/schemas/DocumentListEntry" + TelegrafRequest: + type: object + properties: + name: + type: string + description: + type: string + metadata: + type: object + properties: + buckets: + type: array + items: + type: string + config: + type: string + orgID: + type: string + TelegrafRequestPlugin: + oneOf: + - $ref: "#/components/schemas/TelegrafPluginInputCpu" + - $ref: "#/components/schemas/TelegrafPluginInputDisk" + - $ref: "#/components/schemas/TelegrafPluginInputDiskio" + - $ref: "#/components/schemas/TelegrafPluginInputDocker" + - $ref: "#/components/schemas/TelegrafPluginInputFile" + - $ref: "#/components/schemas/TelegrafPluginInputKubernetes" + - $ref: "#/components/schemas/TelegrafPluginInputLogParser" + - $ref: "#/components/schemas/TelegrafPluginInputProcstat" + - $ref: "#/components/schemas/TelegrafPluginInputPrometheus" + - $ref: "#/components/schemas/TelegrafPluginInputRedis" + - $ref: "#/components/schemas/TelegrafPluginInputSyslog" + - $ref: "#/components/schemas/TelegrafPluginOutputFile" + - $ref: "#/components/schemas/TelegrafPluginOutputInfluxDBV2" + TelegrafPluginInputCpu: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["cpu"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputDisk: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["disk"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputDiskio: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["diskio"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputDocker: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["docker"] + type: + type: string + enum: ["input"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginInputDockerConfig" + TelegrafPluginInputFile: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["file"] + type: + type: string + enum: [input] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginInputFileConfig" + TelegrafPluginInputKernel: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["kernel"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputKubernetes: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["kubernetes"] + type: + type: string + enum: ["input"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginInputKubernetesConfig" + TelegrafPluginInputLogParser: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["logparser"] + type: + type: string + enum: ["input"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginInputLogParserConfig" + TelegrafPluginInputMem: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["mem"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputNetResponse: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["net_response"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputNet: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["net"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputNginx: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["nginx"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputProcesses: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["processes"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputProcstat: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["procstat"] + type: + type: string + enum: ["input"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginInputProcstatConfig" + TelegrafPluginInputPrometheus: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["prometheus"] + type: + type: string + enum: ["input"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginInputPrometheusConfig" + TelegrafPluginInputRedis: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["redis"] + type: + type: string + enum: ["input"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginInputRedisConfig" + TelegrafPluginInputSyslog: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["syslog"] + type: + type: string + enum: ["input"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginInputSyslogConfig" + TelegrafPluginInputSwap: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["swap"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputSystem: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["system"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginInputTail: + type: object + required: + - name + - type + properties: + name: + type: string + enum: ["tail"] + type: + type: string + enum: ["input"] + comment: + type: string + TelegrafPluginOutputFile: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["file"] + type: + type: string + enum: ["output"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginOutputFileConfig" + TelegrafPluginOutputInfluxDBV2: + type: object + required: + - name + - type + - config + properties: + name: + type: string + enum: ["influxdb_v2"] + type: + type: string + enum: ["output"] + comment: + type: string + config: + $ref: "#/components/schemas/TelegrafPluginOutputInfluxDBV2Config" + Telegraf: + type: object + allOf: + - $ref: "#/components/schemas/TelegrafRequest" + - type: object + properties: + id: + type: string + readOnly: true + links: + type: object + readOnly: true + example: + self: "/api/v2/telegrafs/1" + lables: "/api/v2/telegrafs/1/labels" + owners: "/api/v2/telegrafs/1/owners" + members: "/api/v2/telegrafs/1/members" + properties: + self: + $ref: "#/components/schemas/Link" + labels: + $ref: "#/components/schemas/Link" + members: + $ref: "#/components/schemas/Link" + owners: + $ref: "#/components/schemas/Link" + labels: + readOnly: true + $ref: "#/components/schemas/Labels" + Telegrafs: + type: object + properties: + configurations: + type: array + items: + $ref: "#/components/schemas/Telegraf" + TelegrafPlugin: + type: object + properties: + type: + type: string + name: + type: string + description: + type: string + config: + type: string + TelegrafPlugins: + type: object + properties: + version: + type: string + os: + type: string + plugins: + type: array + items: + $ref: "#/components/schemas/TelegrafPlugin" + TelegrafPluginInputDockerConfig: + type: object + required: + - endpoint + properties: + endpoint: + type: string + TelegrafPluginInputFileConfig: + type: object + properties: + files: + type: array + items: + type: string + TelegrafPluginInputKubernetesConfig: + type: object + properties: + url: + type: string + format: uri + TelegrafPluginInputLogParserConfig: + type: object + properties: + files: + type: array + items: + type: string + TelegrafPluginInputProcstatConfig: + type: object + properties: + exe: + type: string + TelegrafPluginInputPrometheusConfig: + type: object + properties: + urls: + type: array + items: + type: string + format: uri + TelegrafPluginInputRedisConfig: + type: object + properties: + servers: + type: array + items: + type: string + password: + type: string + TelegrafPluginInputSyslogConfig: + type: object + properties: + server: + type: string + TelegrafPluginOutputFileConfig: + type: object + required: + - files + properties: + files: + type: array + items: + type: object + properties: + type: + type: string + enum: [stdout, path] + path: + type: string + TelegrafPluginOutputInfluxDBV2Config: + type: object + required: + - urls + - token + - organization + - bucket + properties: + urls: + type: array + items: + type: string + format: uri + token: + type: string + organization: + type: string + bucket: + type: string + IsOnboarding: + type: object + properties: + allowed: + description: True means that the influxdb instance has NOT had initial setup; false means that the database has been setup. + type: boolean + OnboardingRequest: + type: object + properties: + username: + type: string + password: + type: string + org: + type: string + bucket: + type: string + retentionPeriodHrs: + type: integer + required: + - username + - org + - bucket + OnboardingResponse: + type: object + properties: + user: + $ref: "#/components/schemas/User" + org: + $ref: "#/components/schemas/Organization" + bucket: + $ref: "#/components/schemas/Bucket" + auth: + $ref: "#/components/schemas/Authorization" + PasswordResetBody: + properties: + password: + type: string + required: + - password + AddResourceMemberRequestBody: + type: object + properties: + id: + type: string + name: + type: string + required: + - id + Ready: + type: object + properties: + status: + type: string + enum: + - ready + started: + type: string + format: date-time + example: "2019-03-13T10:09:33.891196-04:00" + up: + type: string + example: "14m45.911966424s" + HealthCheck: + type: object + required: + - name + - status + properties: + name: + type: string + message: + type: string + checks: + type: array + items: + $ref: "#/components/schemas/HealthCheck" + status: + type: string + enum: + - pass + - fail + version: + type: string + commit: + type: string + Labels: + type: array + items: + $ref: "#/components/schemas/Label" + Label: + type: object + properties: + id: + readOnly: true + type: string + orgID: + readOnly: true + type: string + name: + type: string + properties: + type: object + additionalProperties: + type: string + description: Key/Value pairs associated with this label. Keys can be removed by sending an update with an empty value. + example: { "color": "ffb3b3", "description": "this is a description" } + LabelCreateRequest: + type: object + required: [orgID, name] + properties: + orgID: + type: string + name: + type: string + properties: + type: object + additionalProperties: + type: string + description: Key/Value pairs associated with this label. Keys can be removed by sending an update with an empty value. + example: { "color": "ffb3b3", "description": "this is a description" } + LabelUpdate: + type: object + properties: + name: + type: string + properties: + type: object + additionalProperties: + type: string + description: Key/Value pairs associated with this label. Keys can be removed by sending an update with an empty value. + example: { "color": "ffb3b3", "description": "this is a description" } + LabelMapping: + type: object + properties: + labelID: + type: string + LabelsResponse: + type: object + properties: + labels: + $ref: "#/components/schemas/Labels" + links: + $ref: "#/components/schemas/Links" + LabelResponse: + type: object + properties: + label: + $ref: "#/components/schemas/Label" + links: + $ref: "#/components/schemas/Links" + ASTResponse: + description: Contains the AST for the supplied Flux query + type: object + properties: + ast: + $ref: "#/components/schemas/Package" + WritePrecision: + type: string + enum: + - ms + - s + - us + - ns + TaskCreateRequest: + type: object + properties: + orgID: + description: The ID of the organization that owns this Task. + type: string + org: + description: The name of the organization that owns this Task. + type: string + status: + $ref: "#/components/schemas/TaskStatusType" + flux: + description: The Flux script to run for this task. + type: string + description: + description: An optional description of the task. + type: string + required: [flux] + TaskUpdateRequest: + type: object + properties: + status: + $ref: "#/components/schemas/TaskStatusType" + flux: + description: The Flux script to run for this task. + type: string + name: + description: Override the 'name' option in the flux script. + type: string + every: + description: Override the 'every' option in the flux script. + type: string + cron: + description: Override the 'cron' option in the flux script. + type: string + offset: + description: Override the 'offset' option in the flux script. + type: string + description: + description: An optional description of the task. + type: string + FluxResponse: + description: Rendered flux that backs the check or notification. + properties: + flux: + type: string + CheckPatch: + type: object + properties: + name: + type: string + description: + type: string + status: + type: string + enum: + - active + - inactive + CheckDiscriminator: + oneOf: + - $ref: "#/components/schemas/DeadmanCheck" + - $ref: "#/components/schemas/ThresholdCheck" + - $ref: "#/components/schemas/CustomCheck" + discriminator: + propertyName: type + mapping: + deadman: "#/components/schemas/DeadmanCheck" + threshold: "#/components/schemas/ThresholdCheck" + custom: "#/components/schemas/CustomCheck" + Check: + allOf: + - $ref: "#/components/schemas/CheckDiscriminator" + PostCheck: + allOf: + - $ref: "#/components/schemas/CheckDiscriminator" + Checks: + properties: + checks: + type: array + items: + $ref: "#/components/schemas/Check" + links: + $ref: "#/components/schemas/Links" + CheckBase: + properties: + id: + readOnly: true + type: string + name: + type: string + orgID: + description: The ID of the organization that owns this check. + type: string + ownerID: + description: The ID of creator used to create this check. + type: string + readOnly: true + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + query: + $ref: "#/components/schemas/DashboardQuery" + status: + $ref: "#/components/schemas/TaskStatusType" + description: + description: An optional description of the check. + type: string + latestCompleted: + description: Timestamp of latest scheduled, completed run, RFC3339. + type: string + format: date-time + readOnly: true + lastRunStatus: + readOnly: true + type: string + enum: + - failed + - success + - canceled + lastRunError: + readOnly: true + type: string + labels: + $ref: "#/components/schemas/Labels" + links: + type: object + readOnly: true + example: + self: "/api/v2/checks/1" + labels: "/api/v2/checks/1/labels" + members: "/api/v2/checks/1/members" + owners: "/api/v2/checks/1/owners" + query: "/api/v2/checks/1/query" + properties: + self: + description: URL for this check + $ref: "#/components/schemas/Link" + labels: + description: URL to retrieve labels for this check + $ref: "#/components/schemas/Link" + members: + description: URL to retrieve members for this check + $ref: "#/components/schemas/Link" + owners: + description: URL to retrieve owners for this check + $ref: "#/components/schemas/Link" + query: + description: URL to retrieve flux script for this check + $ref: "#/components/schemas/Link" + required: [name, orgID, query] + ThresholdCheck: + allOf: + - $ref: "#/components/schemas/CheckBase" + - type: object + required: [type] + properties: + type: + type: string + enum: [threshold] + thresholds: + type: array + items: + $ref: "#/components/schemas/Threshold" + every: + description: Check repetition interval. + type: string + offset: + description: Duration to delay after the schedule, before executing check. + type: string + tags: + description: List of tags to write to each status. + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + statusMessageTemplate: + description: The template used to generate and write a status message. + type: string + Threshold: + oneOf: + - $ref: "#/components/schemas/GreaterThreshold" + - $ref: "#/components/schemas/LesserThreshold" + - $ref: "#/components/schemas/RangeThreshold" + discriminator: + propertyName: type + mapping: + greater: "#/components/schemas/GreaterThreshold" + lesser: "#/components/schemas/LesserThreshold" + range: "#/components/schemas/RangeThreshold" + DeadmanCheck: + allOf: + - $ref: "#/components/schemas/CheckBase" + - type: object + required: [type] + properties: + type: + type: string + enum: [deadman] + timeSince: + description: String duration before deadman triggers. + type: string + staleTime: + description: String duration for time that a series is considered stale and should not trigger deadman. + type: string + reportZero: + description: If only zero values reported since time, trigger an alert + type: boolean + level: + $ref: "#/components/schemas/CheckStatusLevel" + every: + description: Check repetition interval. + type: string + offset: + description: Duration to delay after the schedule, before executing check. + type: string + tags: + description: List of tags to write to each status. + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + statusMessageTemplate: + description: The template used to generate and write a status message. + type: string + CustomCheck: + allOf: + - $ref: "#/components/schemas/CheckBase" + - type: object + properties: + type: + type: string + enum: [custom] + required: [type] + ThresholdBase: + properties: + level: + $ref: "#/components/schemas/CheckStatusLevel" + allValues: + description: If true, only alert if all values meet threshold. + type: boolean + GreaterThreshold: + allOf: + - $ref: "#/components/schemas/ThresholdBase" + - type: object + required: [type, value] + properties: + type: + type: string + enum: [greater] + value: + type: number + format: float + LesserThreshold: + allOf: + - $ref: "#/components/schemas/ThresholdBase" + - type: object + required: [type, value] + properties: + type: + type: string + enum: [lesser] + value: + type: number + format: float + RangeThreshold: + allOf: + - $ref: "#/components/schemas/ThresholdBase" + - type: object + required: [type, min, max, within] + properties: + type: + type: string + enum: [range] + min: + type: number + format: float + max: + type: number + format: float + within: + type: boolean + CheckStatusLevel: + description: The state to record if check matches a criteria. + type: string + enum: ["UNKNOWN", "OK", "INFO", "CRIT", "WARN"] + RuleStatusLevel: + description: The state to record if check matches a criteria. + type: string + enum: ["UNKNOWN", "OK", "INFO", "CRIT", "WARN", "ANY"] + NotificationRuleUpdate: + type: object + properties: + name: + type: string + description: + type: string + status: + type: string + enum: + - active + - inactive + NotificationRuleDiscriminator: + oneOf: + - $ref: "#/components/schemas/SlackNotificationRule" + - $ref: "#/components/schemas/SMTPNotificationRule" + - $ref: "#/components/schemas/PagerDutyNotificationRule" + - $ref: "#/components/schemas/HTTPNotificationRule" + - $ref: "#/components/schemas/TelegramNotificationRule" + discriminator: + propertyName: type + mapping: + slack: "#/components/schemas/SlackNotificationRule" + smtp: "#/components/schemas/SMTPNotificationRule" + pagerduty: "#/components/schemas/PagerDutyNotificationRule" + http: "#/components/schemas/HTTPNotificationRule" + telegram: "#/components/schemas/TelegramNotificationRule" + NotificationRule: + allOf: + - $ref: "#/components/schemas/NotificationRuleDiscriminator" + PostNotificationRule: + allOf: + - $ref: "#/components/schemas/NotificationRuleDiscriminator" + NotificationRules: + properties: + notificationRules: + type: array + items: + $ref: "#/components/schemas/NotificationRule" + links: + $ref: "#/components/schemas/Links" + NotificationRuleBase: + type: object + required: + - id + - orgID + - status + - name + - tagRules + - statusRules + - endpointID + properties: + latestCompleted: + description: Timestamp of latest scheduled, completed run, RFC3339. + type: string + format: date-time + readOnly: true + lastRunStatus: + readOnly: true + type: string + enum: + - failed + - success + - canceled + lastRunError: + readOnly: true + type: string + id: + readOnly: true + type: string + endpointID: + type: string + orgID: + description: The ID of the organization that owns this notification rule. + type: string + ownerID: + description: The ID of creator used to create this notification rule. + type: string + readOnly: true + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + status: + $ref: "#/components/schemas/TaskStatusType" + name: + description: Human-readable name describing the notification rule. + type: string + sleepUntil: + type: string + every: + description: The notification repetition interval. + type: string + offset: + description: Duration to delay after the schedule, before executing check. + type: string + runbookLink: + type: string + limitEvery: + description: Don't notify me more than times every seconds. If set, limit cannot be empty. + type: integer + limit: + description: Don't notify me more than times every seconds. If set, limitEvery cannot be empty. + type: integer + tagRules: + description: List of tag rules the notification rule attempts to match. + type: array + items: + $ref: "#/components/schemas/TagRule" + description: + description: An optional description of the notification rule. + type: string + statusRules: + description: List of status rules the notification rule attempts to match. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/StatusRule" + labels: + $ref: "#/components/schemas/Labels" + links: + type: object + readOnly: true + example: + self: "/api/v2/notificationRules/1" + labels: "/api/v2/notificationRules/1/labels" + members: "/api/v2/notificationRules/1/members" + owners: "/api/v2/notificationRules/1/owners" + query: "/api/v2/notificationRules/1/query" + properties: + self: + description: URL for this endpoint. + $ref: "#/components/schemas/Link" + labels: + description: URL to retrieve labels for this notification rule. + $ref: "#/components/schemas/Link" + members: + description: URL to retrieve members for this notification rule. + $ref: "#/components/schemas/Link" + owners: + description: URL to retrieve owners for this notification rule. + $ref: "#/components/schemas/Link" + query: + description: URL to retrieve flux script for this notification rule. + $ref: "#/components/schemas/Link" + TagRule: + type: object + properties: + key: + type: string + value: + type: string + operator: + type: string + enum: ["equal", "notequal", "equalregex", "notequalregex"] + StatusRule: + type: object + properties: + currentLevel: + $ref: "#/components/schemas/RuleStatusLevel" + previousLevel: + $ref: "#/components/schemas/RuleStatusLevel" + count: + type: integer + period: + type: string + HTTPNotificationRuleBase: + type: object + required: [type] + properties: + type: + type: string + enum: [http] + url: + type: string + HTTPNotificationRule: + allOf: + - $ref: "#/components/schemas/NotificationRuleBase" + - $ref: "#/components/schemas/HTTPNotificationRuleBase" + SlackNotificationRuleBase: + type: object + required: [type, messageTemplate] + properties: + type: + type: string + enum: [slack] + channel: + type: string + messageTemplate: + type: string + SlackNotificationRule: + allOf: + - $ref: "#/components/schemas/NotificationRuleBase" + - $ref: "#/components/schemas/SlackNotificationRuleBase" + SMTPNotificationRule: + allOf: + - $ref: "#/components/schemas/NotificationRuleBase" + - $ref: "#/components/schemas/SMTPNotificationRuleBase" + SMTPNotificationRuleBase: + type: object + required: [type, subjectTemplate, to] + properties: + type: + type: string + enum: [smtp] + subjectTemplate: + type: string + bodyTemplate: + type: string + to: + type: string + PagerDutyNotificationRule: + allOf: + - $ref: "#/components/schemas/NotificationRuleBase" + - $ref: "#/components/schemas/PagerDutyNotificationRuleBase" + PagerDutyNotificationRuleBase: + type: object + required: [type, messageTemplate] + properties: + type: + type: string + enum: [pagerduty] + messageTemplate: + type: string + TelegramNotificationRule: + allOf: + - $ref: "#/components/schemas/NotificationRuleBase" + - $ref: "#/components/schemas/TelegramNotificationRuleBase" + TelegramNotificationRuleBase: + type: object + required: [type, messageTemplate, channel] + properties: + type: + description: The discriminator between other types of notification rules is "telegram". + type: string + enum: [telegram] + messageTemplate: + description: The message template as a flux interpolated string. + type: string + parseMode: + description: Parse mode of the message text per https://core.telegram.org/bots/api#formatting-options . Defaults to "MarkdownV2" . + type: string + enum: + - MarkdownV2 + - HTML + - Markdown + disableWebPagePreview: + description: Disables preview of web links in the sent messages when "true". Defaults to "false" . + type: boolean + NotificationEndpointUpdate: + type: object + + properties: + name: + type: string + description: + type: string + status: + type: string + enum: + - active + - inactive + NotificationEndpointDiscrimator: + oneOf: + - $ref: "#/components/schemas/SlackNotificationEndpoint" + - $ref: "#/components/schemas/PagerDutyNotificationEndpoint" + - $ref: "#/components/schemas/HTTPNotificationEndpoint" + - $ref: "#/components/schemas/TelegramNotificationEndpoint" + discriminator: + propertyName: type + mapping: + slack: "#/components/schemas/SlackNotificationEndpoint" + pagerduty: "#/components/schemas/PagerDutyNotificationEndpoint" + http: "#/components/schemas/HTTPNotificationEndpoint" + telegram: "#/components/schemas/TelegramNotificationEndpoint" + NotificationEndpoint: + allOf: + - $ref: "#/components/schemas/NotificationEndpointDiscrimator" + PostNotificationEndpoint: + allOf: + - $ref: "#/components/schemas/NotificationEndpointDiscrimator" + NotificationEndpoints: + properties: + notificationEndpoints: + type: array + items: + $ref: "#/components/schemas/NotificationEndpoint" + links: + $ref: "#/components/schemas/Links" + NotificationEndpointBase: + type: object + required: [type, name] + properties: + id: + type: string + orgID: + type: string + userID: + type: string + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + description: + description: An optional description of the notification endpoint. + type: string + name: + type: string + status: + description: The status of the endpoint. + default: active + type: string + enum: ["active", "inactive"] + labels: + $ref: "#/components/schemas/Labels" + links: + type: object + readOnly: true + example: + self: "/api/v2/notificationEndpoints/1" + labels: "/api/v2/notificationEndpoints/1/labels" + members: "/api/v2/notificationEndpoints/1/members" + owners: "/api/v2/notificationEndpoints/1/owners" + properties: + self: + description: URL for this endpoint. + $ref: "#/components/schemas/Link" + labels: + description: URL to retrieve labels for this endpoint. + $ref: "#/components/schemas/Link" + members: + description: URL to retrieve members for this endpoint. + $ref: "#/components/schemas/Link" + owners: + description: URL to retrieve owners for this endpoint. + $ref: "#/components/schemas/Link" + type: + $ref: "#/components/schemas/NotificationEndpointType" + SlackNotificationEndpoint: + type: object + allOf: + - $ref: "#/components/schemas/NotificationEndpointBase" + - type: object + properties: + url: + description: Specifies the URL of the Slack endpoint. Specify either `URL` or `Token`. + type: string + token: + description: Specifies the API token string. Specify either `URL` or `Token`. + type: string + PagerDutyNotificationEndpoint: + type: object + allOf: + - $ref: "#/components/schemas/NotificationEndpointBase" + - type: object + required: [routingKey] + properties: + clientURL: + type: string + routingKey: + type: string + HTTPNotificationEndpoint: + type: object + allOf: + - $ref: "#/components/schemas/NotificationEndpointBase" + - type: object + required: [url, authMethod, method] + properties: + url: + type: string + username: + type: string + password: + type: string + token: + type: string + method: + type: string + enum: ["POST", "GET", "PUT"] + authMethod: + type: string + enum: ["none", "basic", "bearer"] + contentTemplate: + type: string + headers: + type: object + description: Customized headers. + additionalProperties: + type: string + TelegramNotificationEndpoint: + type: object + allOf: + - $ref: "#/components/schemas/NotificationEndpointBase" + - type: object + required: [token, channel] + properties: + token: + description: Specifies the Telegram bot token. See https://core.telegram.org/bots#creating-a-new-bot . + type: string + channel: + description: ID of the telegram channel, a chat_id in https://core.telegram.org/bots/api#sendmessage . + type: string + NotificationEndpointType: + type: string + enum: ["slack", "pagerduty", "http", "telegram"] + DBRP: + required: + - orgID + - org + - bucketID + - database + - retention_policy + properties: + id: + type: string + description: the mapping identifier + readOnly: true + orgID: + type: string + description: the organization ID that owns this mapping. + org: + type: string + description: the organization that owns this mapping. + bucketID: + type: string + description: the bucket ID used as target for the translation. + database: + type: string + description: InfluxDB v1 database + retention_policy: + type: string + description: InfluxDB v1 retention policy + default: + type: boolean + description: Specify if this mapping represents the default retention policy for the database specificed. + links: + $ref: "#/components/schemas/Links" + DBRPs: + properties: + notificationEndpoints: + type: array + items: + $ref: "#/components/schemas/DBRP" + links: + $ref: "#/components/schemas/Links" + DBRPUpdate: + properties: + database: + type: string + description: InfluxDB v1 database + retention_policy: + type: string + description: InfluxDB v1 retention policy + default: + type: boolean + links: + $ref: "#/components/schemas/Links" + securitySchemes: + BasicAuth: + type: http + scheme: basic diff --git a/api-docs/cloud/swaggerV1Compat.yml b/api-docs/cloud/swaggerV1Compat.yml new file mode 100644 index 000000000..ba850a92c --- /dev/null +++ b/api-docs/cloud/swaggerV1Compat.yml @@ -0,0 +1,308 @@ +openapi: "3.0.0" +info: + title: InfluxDB API Service (v1 compatible endpoints) + version: 0.1.0 +servers: + - url: / + description: InfluxDB v1 compatible API endpoints. +paths: + /write: + post: # technically this functions with other methods as well + operationId: PostWriteV1 + tags: + - Write + summary: Write time series data into InfluxDB in a v1 compatible format + requestBody: + description: Line protocol body + required: true + content: + text/plain: + schema: + type: string + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/AuthUserV1" + - $ref: "#/components/parameters/AuthPassV1" + - in: query + name: db + schema: + type: string + required: true + description: The bucket to write to. If none exist a bucket will be created with a default 3 day retention policy. + - in: query + name: rp + schema: + type: string + description: The retention policy name. + - in: query + name: precision + schema: + type: string + description: Write precision. + - in: header + name: Content-Encoding + description: When present, its value indicates to the database that compression is applied to the line-protocol body. + schema: + type: string + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + responses: + "204": + description: Write data is correctly formatted and accepted for writing to the bucket. + "400": + description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. + content: + application/json: + schema: + $ref: "#/components/schemas/LineProtocolError" + "401": + description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "403": + description: No token was sent and they are required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "413": + description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. + content: + application/json: + schema: + $ref: "#/components/schemas/LineProtocolLengthError" + "429": + description: Token is temporarily over quota. The Retry-After header describes when to try the write again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + "503": + description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /query: + post: # technically this functions with other methods as well + operationId: PostQueryV1 + tags: + - Query + summary: Query InfluxDB in a v1 compatible format + requestBody: + description: InfluxQL query to execute. + content: + text/plain: # although this should be `application/vnd.influxql`, oats breaks so we define the content-type header parameter + schema: + type: string + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/AuthUserV1" + - $ref: "#/components/parameters/AuthPassV1" + - in: header + name: Accept-Encoding + description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. + schema: + type: string + description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/vnd.influxql + - in: query + name: q + description: Defines the influxql query to run. + schema: + type: string + responses: + "200": + description: Query results + headers: + Content-Encoding: + description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body + schema: + type: string + description: Specifies that the response in the body is encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: The Trace-Id header reports the request's trace ID, if one was generated. + schema: + type: string + description: Specifies the request's trace ID. + content: + text/csv: + schema: + type: string + example: > + name,tags,time,test_field,test_tag + test_measurement,,1603740794286107366,1,tag_value + test_measurement,,1603740870053205649,2,tag_value + test_measurement,,1603741221085428881,3,tag_value + text/plain: + schema: + $ref: "#/components/schemas/InfluxQLResponse" + "429": + description: Token is temporarily over quota. The Retry-After header describes when to try the read again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Error processing query + content: + application/json: + schema: + $ref: "#/components/schemas/Error" +components: + parameters: + TraceSpan: + in: header + name: Zap-Trace-Span + description: OpenTracing span context + example: + trace_id: "1" + span_id: "1" + baggage: + key: value + required: false + schema: + type: string + AuthUserV1: + in: query + name: u + required: false + schema: + type: string + description: Username. + AuthPassV1: + in: query + name: p + required: false + schema: + type: string + description: User token. + schemas: + InfluxQLResponse: + properties: + results: + type: array + items: + type: object + properties: + statement_id: + type: integer + series: + type: array + items: + type: object + properties: + name: + type: string + columns: + type: array + items: + type: integer + values: + type: array + items: + type: array + items: {} + Error: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + # This set of enumerations must remain in sync with the constants defined in errors.go + enum: + - internal error + - not found + - conflict + - invalid + - unprocessable entity + - empty value + - unavailable + - forbidden + - too many requests + - unauthorized + - method not allowed + message: + readOnly: true + description: Message is a human-readable message. + type: string + required: [code, message] + LineProtocolError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - internal error + - not found + - conflict + - invalid + - empty value + - unavailable + message: + readOnly: true + description: Message is a human-readable message. + type: string + op: + readOnly: true + description: Op describes the logical code operation during error. Useful for debugging. + type: string + err: + readOnly: true + description: Err is a stack of errors that occurred during processing of the request. Useful for debugging. + type: string + line: + readOnly: true + description: First line within sent body containing malformed data + type: integer + format: int32 + required: [code, message, op, err] + LineProtocolLengthError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - invalid + message: + readOnly: true + description: Message is a human-readable message. + type: string + maxLength: + readOnly: true + description: Max length in bytes for a body of line-protocol. + type: integer + format: int32 + required: [code, message, maxLength] \ No newline at end of file diff --git a/api-docs/generate-api-docs.sh b/api-docs/generate-api-docs.sh index 41809d5c8..b95d379e1 100644 --- a/api-docs/generate-api-docs.sh +++ b/api-docs/generate-api-docs.sh @@ -7,36 +7,70 @@ for version in $versions do # Trim the trailing slash off the directory name version="${version%/}" - menu="influxdb_$(echo $version | sed 's/\./_/g;s/[^0-9_]//g;')_ref" + menu="influxdb_$(echo $version | sed 's/\./_/g;s/v//g;')_ref" + if [ $version = "cloud" ]; then + titleVersion="Cloud" + else + titleVersion="$version" + fi # Generate the frontmatter - frontmatter="--- -title: InfluxDB $version API documentation + v2frontmatter="--- +title: InfluxDB $titleVersion API documentation description: > - The InfluxDB API provides a programmatic interface for interactions with InfluxDB $version. + The InfluxDB API provides a programmatic interface for interactions with InfluxDB $titleVersion. layout: api menu: $menu: parent: InfluxDB v2 API - name: View full API docs + name: View v2 API docs weight: 102 --- +" + v1frontmatter="--- +title: InfluxDB $titleVersion v1 compatiblity API documentation +description: > + The InfluxDB v1 compatility API provides a programmatic interface for interactions with InfluxDB $titleVersion using InfluxDB v1.x compatibly endpoints. +layout: api +menu: + $menu: + parent: 1.x compatibility + name: View v1 compatibility API docs +weight: 304 +--- " - # Use Redoc to generate the API html + # Use Redoc to generate the v2 API html redoc-cli bundle -t template.hbs \ - --title="InfluxDB $version API documentation" \ + --title="InfluxDB $titleVersion API documentation" \ --options.sortPropsAlphabetically \ --options.menuToggle \ --options.hideHostname \ --templateOptions.version="$version" \ + --templateOptions.titleVersion="$titleVersion" \ $version/swagger.yml + # Use Redoc to generate the v1 compatibility API html + redoc-cli bundle -t template.hbs \ + --title="InfluxDB $titleVersion v1 compatibility API documentation" \ + --options.sortPropsAlphabetically \ + --options.menuToggle \ + --options.hideHostname \ + --templateOptions.version="$version" \ + --templateOptions.titleVersion="$titleVersion" \ + --output=redoc-static-v1-compat.html \ + $version/swaggerV1Compat.yml + # Create temp file with frontmatter and Redoc html - echo "$frontmatter" >> $version.tmp + echo "$v2frontmatter" >> $version.tmp + echo "$v1frontmatter" >> $version-v1-compat.tmp cat redoc-static.html >> $version.tmp + cat redoc-static-v1-compat.html >> $version-v1-compat.tmp # Remove redoc file and move the tmp file to it's proper place rm -f redoc-static.html - mv $version.tmp ../content/influxdb/$version/api.html + rm -f redoc-static-v1-compat.html + mkdir -p ../content/influxdb/$version/api + mv $version.tmp ../content/influxdb/$version/api/_index.html + mv $version-v1-compat.tmp ../content/influxdb/$version/api/v1-compatibility.html done diff --git a/api-docs/template.hbs b/api-docs/template.hbs index bedacd61c..27f796721 100644 --- a/api-docs/template.hbs +++ b/api-docs/template.hbs @@ -39,7 +39,7 @@ {{{redocHTML}}} diff --git a/api-docs/v2.0/swagger.yml b/api-docs/v2.0/swagger.yml index f23ac9877..4212ce71e 100644 --- a/api-docs/v2.0/swagger.yml +++ b/api-docs/v2.0/swagger.yml @@ -1990,7 +1990,7 @@ paths: operationId: PostSources tags: - Sources - summary: Create a source + summary: Creates a source parameters: - $ref: "#/components/parameters/TraceSpan" requestBody: @@ -2814,7 +2814,7 @@ paths: operationId: GetDashboardsIDLabels tags: - Dashboards - summary: List all labels for a dashboard + summary: list all labels for a dashboard parameters: - $ref: "#/components/parameters/TraceSpan" - in: path @@ -3305,7 +3305,7 @@ paths: operationId: DeleteAuthorizationsID tags: - Authorizations - summary: Delete an authorization + summary: Delete a authorization parameters: - $ref: "#/components/parameters/TraceSpan" - in: path @@ -3681,7 +3681,7 @@ paths: operationId: DeleteBucketsIDLabelsID tags: - Buckets - summary: Delete a label from a bucket + summary: delete a label from a bucket parameters: - $ref: "#/components/parameters/TraceSpan" - in: path @@ -11704,7 +11704,12 @@ components: type: string enum: ["slack", "pagerduty", "http", "telegram"] DBRP: - type: object + required: + - orgID + - org + - bucketID + - database + - retention_policy properties: id: type: string @@ -11730,17 +11735,6 @@ components: description: Specify if this mapping represents the default retention policy for the database specificed. links: $ref: "#/components/schemas/Links" - oneOf: - - required: - - orgID - - bucketID - - database - - retention_policy - - required: - - org - - bucketID - - database - - retention_policy DBRPs: properties: notificationEndpoints: diff --git a/api-docs/v2.0/swaggerV1Compat.yml b/api-docs/v2.0/swaggerV1Compat.yml new file mode 100644 index 000000000..ba850a92c --- /dev/null +++ b/api-docs/v2.0/swaggerV1Compat.yml @@ -0,0 +1,308 @@ +openapi: "3.0.0" +info: + title: InfluxDB API Service (v1 compatible endpoints) + version: 0.1.0 +servers: + - url: / + description: InfluxDB v1 compatible API endpoints. +paths: + /write: + post: # technically this functions with other methods as well + operationId: PostWriteV1 + tags: + - Write + summary: Write time series data into InfluxDB in a v1 compatible format + requestBody: + description: Line protocol body + required: true + content: + text/plain: + schema: + type: string + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/AuthUserV1" + - $ref: "#/components/parameters/AuthPassV1" + - in: query + name: db + schema: + type: string + required: true + description: The bucket to write to. If none exist a bucket will be created with a default 3 day retention policy. + - in: query + name: rp + schema: + type: string + description: The retention policy name. + - in: query + name: precision + schema: + type: string + description: Write precision. + - in: header + name: Content-Encoding + description: When present, its value indicates to the database that compression is applied to the line-protocol body. + schema: + type: string + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + responses: + "204": + description: Write data is correctly formatted and accepted for writing to the bucket. + "400": + description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. + content: + application/json: + schema: + $ref: "#/components/schemas/LineProtocolError" + "401": + description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "403": + description: No token was sent and they are required. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "413": + description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. + content: + application/json: + schema: + $ref: "#/components/schemas/LineProtocolLengthError" + "429": + description: Token is temporarily over quota. The Retry-After header describes when to try the write again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + "503": + description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + /query: + post: # technically this functions with other methods as well + operationId: PostQueryV1 + tags: + - Query + summary: Query InfluxDB in a v1 compatible format + requestBody: + description: InfluxQL query to execute. + content: + text/plain: # although this should be `application/vnd.influxql`, oats breaks so we define the content-type header parameter + schema: + type: string + parameters: + - $ref: "#/components/parameters/TraceSpan" + - $ref: "#/components/parameters/AuthUserV1" + - $ref: "#/components/parameters/AuthPassV1" + - in: header + name: Accept-Encoding + description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. + schema: + type: string + description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/vnd.influxql + - in: query + name: q + description: Defines the influxql query to run. + schema: + type: string + responses: + "200": + description: Query results + headers: + Content-Encoding: + description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body + schema: + type: string + description: Specifies that the response in the body is encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + Trace-Id: + description: The Trace-Id header reports the request's trace ID, if one was generated. + schema: + type: string + description: Specifies the request's trace ID. + content: + text/csv: + schema: + type: string + example: > + name,tags,time,test_field,test_tag + test_measurement,,1603740794286107366,1,tag_value + test_measurement,,1603740870053205649,2,tag_value + test_measurement,,1603741221085428881,3,tag_value + text/plain: + schema: + $ref: "#/components/schemas/InfluxQLResponse" + "429": + description: Token is temporarily over quota. The Retry-After header describes when to try the read again. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Error processing query + content: + application/json: + schema: + $ref: "#/components/schemas/Error" +components: + parameters: + TraceSpan: + in: header + name: Zap-Trace-Span + description: OpenTracing span context + example: + trace_id: "1" + span_id: "1" + baggage: + key: value + required: false + schema: + type: string + AuthUserV1: + in: query + name: u + required: false + schema: + type: string + description: Username. + AuthPassV1: + in: query + name: p + required: false + schema: + type: string + description: User token. + schemas: + InfluxQLResponse: + properties: + results: + type: array + items: + type: object + properties: + statement_id: + type: integer + series: + type: array + items: + type: object + properties: + name: + type: string + columns: + type: array + items: + type: integer + values: + type: array + items: + type: array + items: {} + Error: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + # This set of enumerations must remain in sync with the constants defined in errors.go + enum: + - internal error + - not found + - conflict + - invalid + - unprocessable entity + - empty value + - unavailable + - forbidden + - too many requests + - unauthorized + - method not allowed + message: + readOnly: true + description: Message is a human-readable message. + type: string + required: [code, message] + LineProtocolError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - internal error + - not found + - conflict + - invalid + - empty value + - unavailable + message: + readOnly: true + description: Message is a human-readable message. + type: string + op: + readOnly: true + description: Op describes the logical code operation during error. Useful for debugging. + type: string + err: + readOnly: true + description: Err is a stack of errors that occurred during processing of the request. Useful for debugging. + type: string + line: + readOnly: true + description: First line within sent body containing malformed data + type: integer + format: int32 + required: [code, message, op, err] + LineProtocolLengthError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - invalid + message: + readOnly: true + description: Message is a human-readable message. + type: string + maxLength: + readOnly: true + description: Max length in bytes for a body of line-protocol. + type: integer + format: int32 + required: [code, message, maxLength] \ No newline at end of file diff --git a/assets/js/feature-callouts.js b/assets/js/feature-callouts.js new file mode 100644 index 000000000..b9b24355c --- /dev/null +++ b/assets/js/feature-callouts.js @@ -0,0 +1,12 @@ +// Show the url feature callout on page load +if ( Cookies.get('influxdb_url_selector_seen') != 'true' ) { + $('#callout-url-selector').fadeIn(300).removeClass('start-position') +} + +// Set feature cookie when the button is clicked +$('button.url-trigger, #callout-url-selector .close').click(function() { + if ( Cookies.get('influxdb_url_selector_seen') != 'true') { + Cookies.set('influxdb_url_selector_seen', 'true') + $('#callout-url-selector').fadeOut(200) + } +}) \ No newline at end of file diff --git a/assets/js/influxdb-url.js b/assets/js/influxdb-url.js index 1449f1537..a5cbb2d8b 100644 --- a/assets/js/influxdb-url.js +++ b/assets/js/influxdb-url.js @@ -1,83 +1,73 @@ -var defaultUrl = "http://localhost:8086" -var placeholderCloudUrl = "https://cloud2.influxdata.com" -var defaultCloudUrl = "https://us-west-2-1.aws.cloud2.influxdata.com" +var placeholderUrls = { + cloud: "https://cloud2.influxdata.com", + oss: "http://localhost:8086" +} + +var defaultUrls = { + cloud: "https://us-west-2-1.aws.cloud2.influxdata.com", + oss: "http://localhost:8086" +} + var elementSelector = ".article--content pre:not(.preserve)" -var isInfluxDBv1 = /influxdb\/v1/.test(window.location.href) -// Retrieve the selected URL from the influxdb_url session cookie -function getUrl() { - var currentUrl = Cookies.get('influxdb_url') - if (typeof currentUrl == 'undefined' ) { - return defaultUrl +// Return the page context (cloud, oss/enterprise, other) +function context() { + if (/\/influxdb\/cloud\//.test(window.location.pathname)) { + return "cloud" + } else if (/\/(enterprise_|influxdb).*\/v[1-2]\.[0-9]{1,2}\//.test(window.location.pathname)) { + return "oss/enterprise" } else { - return currentUrl + return "other" } } -// Retrieve the previously selected URL from the influxdb_prev_url session cookie -// This is used to update URLs whenever you switch between browser tabs -function getPrevUrl() { - var prevUrl = Cookies.get('influxdb_prev_url') - if (typeof prevUrl == 'undefined' ) { - return defaultUrl - } else { - return prevUrl - } +//////////////////////////////////////////////////////////////////////////////// +///////////////////////// Session-management functions ///////////////////////// +//////////////////////////////////////////////////////////////////////////////// + +// Retrieve the user's InfluxDB preference (cloud or oss) from the influxdb_pref session cookie +// Default is cloud. +function getPreference() { + return Cookies.get('influxdb_pref') || "cloud" } -// Iterate through code blocks and update InfluxDB urls -// Ignore URLs in InfluxDB 1.x docs -function updateUrls(currentUrl, newUrl) { - if (!isInfluxDBv1) { - if (typeof currentUrl != newUrl) { - $(elementSelector).each(function() { - $(this).html($(this).html().replace(currentUrl, newUrl)); - }); - } - } +// Set the user's selected InfluxDB preference (cloud or oss) +function setPreference(preference) { + Cookies.set('influxdb_pref', preference) } -// Append the URL selector button to each codeblock with an InfluxDB URL -// Ignore codeblocks on InfluxDB v1.x pages -function appendUrlSelector(currentUrl, selectorText) { - if (!isInfluxDBv1) { - $(elementSelector).each(function() { - var code = $(this).html() - if (code.includes(currentUrl)) { - $(this).after("
" + selectorText + "
") - $('.select-url').fadeIn(400) - } - }); - } -} - -// Toggle the URL selector modal window -function toggleModal() { - $(".modal").fadeToggle(200).toggleClass("open") -} - -// Set the selected URL radio button to :checked -function setRadioButton(currentUrl) { - $('input[name="influxdb-loc"][value="' + currentUrl + '"]').prop("checked", true) -} +// InfluxDB URL-Related Session keys +// +// influxdb_oss_url +// influxdb_cloud_url +// influxdb_prev_oss_url +// influxdb_prev_cloud_url +// influxdb_pref (cloud | oss) +// influxdb_custom_url // Store the InfluxDB URL session cookies – influxdb_url and influxdb_prev_url -function storeUrl(newUrl, prevUrl) { - Cookies.set('influxdb_prev_url', prevUrl) - Cookies.set('influxdb_url', newUrl) +function storeUrl(context, newUrl, prevUrl) { + Cookies.set('influxdb_prev_' + context + '_url', prevUrl) + Cookies.set('influxdb_' + context + '_url', newUrl) } // Store custom URL session cookie – influxdb_custom_url +// Used to populate the custom URL field function storeCustomUrl(customUrl) { Cookies.set('influxdb_custom_url', customUrl) $('input#custom[type=radio]').val(customUrl) } // Remove custom URL session cookie – influxdb_custom_url +// Used to clear the form when custom url input is left empty function removeCustomUrl() { Cookies.remove('influxdb_custom_url') } +//////////////////////////////////////////////////////////////////////////////// +//////////////////////// InfluxDB URL utility functions //////////////////////// +//////////////////////////////////////////////////////////////////////////////// + // Preserve URLs in codeblocks that come just after or are inside a div // with the class, .keep-url function addPreserve() { @@ -92,81 +82,258 @@ function addPreserve() { }) } -// Update URLs when selected in the modal -$('input[name="influxdb-loc"]').change(function() { - var newUrl = $(this).val() - updateUrls(getUrl(), newUrl) - storeUrl(newUrl, getUrl()) -}) +// Retrieve the previously selected cloud and oss URLs from the +// influxdb_cloud_url and influxdb_oss_url session cookies. +function getUrls() { + var currentCloudUrl = Cookies.get('influxdb_cloud_url') || defaultUrls.cloud + var currentOSSUrl = Cookies.get('influxdb_oss_url') || defaultUrls.oss + var urls = { + cloud: currentCloudUrl, + oss: currentOSSUrl + }; + return urls; +} + +// Retrieve the previously selected cloud and oss URLs from the +// prev_influxdb_cloud_url and prev_influxdb_oss_url session cookies. +// This is used to update URLs whenever you switch between browser tabs. +function getPrevUrls() { + var prevCloudUrl = Cookies.get('influxdb_prev_cloud_url') || defaultUrls.cloud + var prevOSSUrl = Cookies.get('influxdb_prev_oss_url') || defaultUrls.oss + var prevUrls = { + cloud: prevCloudUrl, + oss: prevOSSUrl + }; + return prevUrls; +} + +// Iterate through code blocks and update InfluxDB urls +// Requires objects with cloud and oss keys and url values +function updateUrls(prevUrls, newUrls) { + + var preference = getPreference() + + var cloudReplacements = [ + { replace: prevUrls.cloud, with: newUrls.cloud}, + { replace: prevUrls.oss, with: newUrls.cloud } + ] + var ossReplacements = [ + { replace: prevUrls.cloud, with: newUrls.cloud}, + { replace: prevUrls.oss, with: newUrls.oss } + ] + + if (context() === "cloud") { var replacements = cloudReplacements } + else if (context() === "oss/enterprise") { var replacements = ossReplacements } + else if ( preference === "cloud" ) { var replacements = cloudReplacements } + else { var replacements = ossReplacements } + + replacements.forEach(function (o) { + if (o.replace != o.with) { + $(elementSelector).each(function() { + $(this).html($(this).html().replace(o.replace, o.with)); + }); + } + }) +} + +// Append the URL selector button to each codeblock with an InfluxDB Cloud or OSS URL +function appendUrlSelector() { + + var appendToUrls = [ placeholderUrls.cloud, placeholderUrls.oss ] + + if (context() === "cloud") { + var selectorText = "InfluxDB Cloud Region" + } else if (context() === "oss/enterprise") { + var selectorText = "Change InfluxDB URL" + } else { + var selectorText = "InfluxDB Cloud or OSS?" + } + + appendToUrls.forEach(function(url){ + $(elementSelector).each(function() { + var code = $(this).html() + if (code.includes(url)) { + $(this).after("
" + selectorText + "
") + $('.select-url').fadeIn(400) + } + }); + }); +} + +//////////////////////////////////////////////////////////////////////////////// +///////////////////////////// Function executions ////////////////////////////// +//////////////////////////////////////////////////////////////////////////////// // Add the preserve tag to code blocks that shouldn't be udpated addPreserve() -// Update URLs on load -updateUrls(defaultUrl, getUrl()) - // Append URL selector buttons to code blocks -appendUrlSelector(getUrl(), "Cloud or OSS?") +appendUrlSelector() -// Append URL selector buttons to cloud-only code blocks -appendUrlSelector(placeholderCloudUrl, "InfluxDB Cloud Region") +// Update URLs on load +updateUrls(placeholderUrls, getUrls()) -// Update cloud-only URLs on load -if (cloudUrls.includes(getUrl())) { - updateUrls(placeholderCloudUrl, getUrl()) -} else { - updateUrls(placeholderCloudUrl, defaultCloudUrl) -} +// Set active radio button on page load +setRadioButtons(getUrls()) // Update URLs whenever you focus on the browser tab $(window).focus(function() { - updateUrls(getPrevUrl(), getUrl()) - setRadioButton(getUrl()) + updateUrls(getPrevUrls(), getUrls()) + setRadioButtons(getUrls()) }); +//////////////////////////////////////////////////////////////////////////////// +////////////////////////// Modal window interactions /////////////////////////// +//////////////////////////////////////////////////////////////////////////////// + +// Toggle the URL selector modal window +function toggleModal() { + $(".modal").fadeToggle(200).toggleClass("open") +} + +// Set the selected URL radio buttons to :checked +function setRadioButtons() { + currentUrls = getUrls() + $('input[name="influxdb-cloud-url"][value="' + currentUrls.cloud + '"]').prop("checked", true) + $('input[name="influxdb-oss-url"][value="' + currentUrls.oss + '"]').prop("checked", true) +} + // Toggle modal window on click $("#modal-close, .modal-overlay, .url-trigger").click(function(e) { e.preventDefault() toggleModal() }) -// Show the feature callout on page load -if ( Cookies.get('influxdb_url_selector_seen') != 'true' ) { - $('#callout-url-selector').fadeIn(300).removeClass('start-position') +// Update URLs and URL preference when selected/clicked in the modal +$('input[name="influxdb-cloud-url"]').change(function() { + var newUrl = $(this).val() + storeUrl("cloud", newUrl, getUrls().cloud) + updateUrls(getPrevUrls(), getUrls()) +}) +$('input[name="influxdb-cloud-url"]').click(function() {setPreference("cloud")}) + +$('input[name="influxdb-oss-url"]').change(function() { + var newUrl = $(this).val() + storeUrl("oss", newUrl, getUrls().oss) + updateUrls(getPrevUrls(), getUrls()) + setPreference("oss") +}) +$('input[name="influxdb-oss-url"]').click(function() {setPreference("oss")}) + +// Toggle preference tabs +function togglePrefBtns(el) { + preference = el.length ? el.attr("id").replace("pref-", "") : "cloud" + prefUrls = $("#" + preference + "-urls") + + el.addClass("active") + el.siblings().removeClass("active") + prefUrls.addClass("active").removeClass("inactive") + prefUrls.siblings().addClass("inactive").removeClass("active") + setPreference(preference) } -// Set feature cookie when the button is clicked -$('button.url-trigger, #callout-url-selector .close').click(function() { - if ( Cookies.get('influxdb_url_selector_seen') != 'true') { - Cookies.set('influxdb_url_selector_seen', 'true') - $('#callout-url-selector').fadeOut(200) - } +// Select preference tab on click +$('#pref-tabs .pref-tab').click(function() { + togglePrefBtns($(this)) }) -///////////////////////////////// CUSTOM URLs ///////////////////////////////// +// Select preference tab from cookie +function showPreference() { + var preference = Cookies.get("influxdb_pref") + prefTab = $("#pref-" + preference) + togglePrefBtns(prefTab) +} + +// Toggled preferred service on load +showPreference() + +//////////////////////////////////////////////////////////////////////////////// +///////////////////////////////// Custom URLs ////////////////////////////////// +//////////////////////////////////////////////////////////////////////////////// + +// Validate custom URLs +function validateUrl(url) { + var validProtocol = /^http(s?)/ + var invalidDomain =/[A-Z\s\!\@\#\$\%\^\&\*\(\)\_\+\=\[\]\{\}\\\|\;\'\"\,\<\>\/\?]/ + var protocol = url.match(/http(s?):\/\//) ? url.match(/http(s?):\/\//)[0] : ""; + var domain = url.replace(protocol, "") + + if (validProtocol.test(protocol) == false) { + return {valid: false, error: "Invalid protocol, use http[s]"} + } else if (domain.length == 0 || invalidDomain.test(domain) == true) { + return {valid: false, error: "Invalid domain"} + } else { + return {valid: true, error: ""} + } +} + +// Show validation errors +function showValidationMessage(validation) { + $('#custom-url').addClass("error") + $('#custom-url').attr("data-message", validation.error) +} + +// Hide validation messages and replace the message attr with empty string +function hideValidationMessage() { + $('#custom-url').removeClass("error").attr("data-message", "") +} + +// Set the custom URL cookie and apply the change +// If the custom URL field is empty, it defaults to the OSS default +function applyCustomUrl() { + var custUrl = $('#custom-url-field').val() + let urlValidation = validateUrl(custUrl) + if (custUrl.length > 0 ) { + if (urlValidation.valid) { + hideValidationMessage() + storeCustomUrl(custUrl) + storeUrl("oss", custUrl, getUrls().oss) + updateUrls(getPrevUrls(), getUrls()) + } else { + showValidationMessage(urlValidation) + } + + } else { + removeCustomUrl(); + hideValidationMessage() + $('input[name="influxdb-oss-url"][value="' + defaultUrls.oss + '"]').trigger('click') + } +} // Trigger radio button on custom URL field focus $('input#custom-url-field').focus(function(e) { $('input#custom[type="radio"]').trigger('click') }) +// Update URLs and close modal when using 'enter' to exit custom URL field $("#custom-url").submit(function(e) { + let url = $('#custom-url-field').val() ? $('#custom-url-field').val() : "" + let urlValidation = validateUrl(url) + e.preventDefault(); - $('#modal-close').trigger('click') + if (url === "" | urlValidation.valid) { + applyCustomUrl() + $('#modal-close').trigger('click') + } else { + showValidationMessage(urlValidation) + } }); // Store the custom InfluxDB URL when exiting the field $('#custom-url-field').blur(function() { - custUrl = $(this).val() - if (custUrl.length > 0 ) { - storeCustomUrl(custUrl) - updateUrls(getUrl(), custUrl) - storeUrl(custUrl, getPrevUrl()) - } else { - $('input#custom').val('http://example.com:8080') - removeCustomUrl(); - $('input[name="influxdb-loc"][value="' + defaultUrl + '"]').trigger('click') - } + applyCustomUrl() +}) + +// When in erred state, revalidate custom URL on keyup +$(document).on("keyup", ".error #custom-url-field", function() { + console.log("keyed up") + let url = $('#custom-url-field').val() + let urlValidation = validateUrl(url) + if (urlValidation.valid) { + hideValidationMessage() + } else { + showValidationMessage(urlValidation) + } }) // Populate the custom InfluxDB URL field on page load @@ -175,18 +342,20 @@ if ( Cookies.get('influxdb_custom_url') != undefined ) { $('#custom-url-field').val(Cookies.get('influxdb_custom_url')) } -// Set active radio button on page load -setRadioButton(getUrl()) - -/////////////////////////// Dynamically update URLs /////////////////////////// +//////////////////////////////////////////////////////////////////////////////// +/////////////////////////// Dynamically update URLs //////////////////////////// +//////////////////////////////////////////////////////////////////////////////// // Extract the protocol and hostname of referrer -referrerHost = document.referrer.match(/^(?:[^\/]*\/){2}[^\/]+/g)[0] +referrerMatch = document.referrer.match(/^(?:[^\/]*\/){2}[^\/]+/g) +referrerHost = referrerMatch ? referrerMatch[0] : ""; // Check if the referrerHost is one of the cloud URLs // cloudUrls is built dynamically in layouts/partials/footer/javascript.html if (cloudUrls.includes(referrerHost)) { - storeUrl(referrerHost, getUrl()) - updateUrls(getPrevUrl(), referrerHost) - setRadioButton(referrerHost) -} + storeUrl("cloud", referrerHost, getUrls().cloud) + updateUrls(getPrevUrls(), getUrls()) + setRadioButtons() + setPreference("cloud") + showPreference() +} \ No newline at end of file diff --git a/assets/styles/layouts/_homepage.scss b/assets/styles/layouts/_homepage.scss index 32aa99750..c275ebea7 100644 --- a/assets/styles/layouts/_homepage.scss +++ b/assets/styles/layouts/_homepage.scss @@ -51,10 +51,16 @@ right: 0; } + .actions { + display: flex; + margin: 1.25rem 0 .75rem 0; + } + a.btn { position: relative; display: inline-block; - margin: .5rem .25rem .75rem 0; + flex: 1 0; + margin: 0 .5rem .5rem 0; padding: 1.25rem 2.25rem; color: $article-btn-text !important; border-radius: $radius; @@ -292,6 +298,7 @@ padding-bottom: 2rem; h2 { font-size: 2rem; margin-top: .5rem; } p { font-size: 1rem; line-height: 1.5rem; } + .actions { flex-direction: column; } } &.search { order: 1; diff --git a/assets/styles/layouts/_landing.scss b/assets/styles/layouts/_landing.scss index 1f41f6db6..16aee750d 100644 --- a/assets/styles/layouts/_landing.scss +++ b/assets/styles/layouts/_landing.scss @@ -27,6 +27,7 @@ padding: 5rem 2vw 5rem 4.5vw; display: flex; justify-content: center; + align-items: center; flex-direction: column; text-align: center; @@ -102,13 +103,14 @@ } &#get-started { + .avoid-wrap { display:inline-block } + .btn { position: relative; - display: inline-block; - padding: 1.25rem; - margin: 0 20% .35rem; + display: block; + padding: 1.25rem 4rem; color: $landing-btn-text; - font-size: 1.1rem; + font-size: 1.2rem; font-weight: $medium; @include gradient($landing-btn-grad); transition: background-color .2s, color .2s; @@ -134,6 +136,19 @@ &:before { opacity: 1; } } } + + .beta:after { + content: 'beta'; + display: inline-block; + vertical-align: middle; + font-style: italic; + font-size: .45em; + margin: -8px 0 0 .5em; + padding: .1rem .6rem .12rem; + border-radius: 1rem; + border: .15rem solid rgba($landing-btn-text, .5); + transition: border-color .2s; + } } } } diff --git a/assets/styles/layouts/_url-selector.scss b/assets/styles/layouts/_url-selector.scss index 05d912f14..dc1b67b6c 100644 --- a/assets/styles/layouts/_url-selector.scss +++ b/assets/styles/layouts/_url-selector.scss @@ -28,7 +28,7 @@ display: flex; overflow: hidden; max-width: 650px; - max-height: 95vh; + max-height: 97.5vh; margin-top: 10vh; padding: .75rem 2rem 1.5rem; border-radius: $radius * 1.5; @@ -57,7 +57,7 @@ } .modal-content{ - overflow: scroll; + overflow: auto; h3 { color: $article-heading; @@ -107,14 +107,13 @@ .products { display: flex; - flex-direction: column-reverse; + flex-direction: column; flex-wrap: wrap; flex-grow: 1; justify-content: flex-start; } .product { - margin-right: .5rem; .providers{ display: flex; @@ -144,6 +143,30 @@ display: inline-block; width: 100%; padding-left: .5rem; + position: relative; + + &:after { + display: none; + content: attr(data-message); + position: absolute; + top: -1.8rem; + right: 0; + font-size: .85rem; + font-weight: $medium; + color: $r-fire; + } + + &.error { + &:after { display: block; } + input#custom-url-field { + border-color: $r-fire; + &:focus { + border-color: $r-fire; + box-shadow: 1px 1px 10px rgba($r-fire,0.5); + } + } + } + input { &#custom-url-field { font-family: $rubik; @@ -227,13 +250,61 @@ td,label,li { line-height: .75rem; border-radius: 1rem; } - + } label:after { margin-left: .15rem; } +/////////////////////////// InfluxDB Preference Tabs /////////////////////////// + +#pref-tabs { + padding: 0; + margin: 0 0 -5px; + list-style: none; + display: flex; + justify-content: space-between; + align-items: center; +} + +.pref-tab { + padding: .75rem 1.25rem; + margin-right: 5px; + text-align: center; + font-weight: bold; + width: 49%; + color: rgba($article-text, .7); + background: rgba($article-text, .05); + border-radius: $radius; + cursor: pointer; + transition: color .2s; + + &:last-child { + margin-right: 0; + } + + &:hover { + color: $article-link; + } + + &.active { + color: $g20-white; + @include gradient($article-btn-gradient); + } + + span.ephemeral { display: inline; } + span.abbr:after { + display: none; + content: "."; + } +} + +.product { + &.active { display: block; } + &.inactive { display: none; } +} + ///////////////////////////// InfluxDB URL Triggers //////////////////////////// .article--content { @@ -271,3 +342,20 @@ label:after { .select-url{margin-top: -3.25rem} } } + +///////////////////////////////// MEDIA QUERIES //////////////////////////////// + +@include media(small) { + .modal { + padding: .5rem; + overflow: scroll; + + .modal-body { + padding: .5rem 1.5rem 1.5rem; + } + } + .pref-tab { + span.ephemeral { display: none; } + span.abbr:after { display: inline; } + } +} diff --git a/config.toml b/config.toml index 01dc6f9e9..97e315fb8 100644 --- a/config.toml +++ b/config.toml @@ -19,6 +19,7 @@ smartDashes = false [taxonomies] "influxdb/v2.0/tag" = "influxdb/v2.0/tags" + "influxdb/cloud/tag" = "influxdb/cloud/tags" [markup] [markup.goldmark] diff --git a/content/enterprise_influxdb/v1.7/install-and-deploy/google-cloud-platform.md b/content/enterprise_influxdb/v1.7/install-and-deploy/google-cloud-platform.md index 513fa3cb8..61ace5229 100644 --- a/content/enterprise_influxdb/v1.7/install-and-deploy/google-cloud-platform.md +++ b/content/enterprise_influxdb/v1.7/install-and-deploy/google-cloud-platform.md @@ -18,7 +18,7 @@ Complete the following steps to deploy an InfluxDB Enterprise cluster on Google After deploying your cluster, see [Getting started with InfluxDB](/platform/introduction/getting-started) for an introduction to InfluxDB database and the InfluxData platform. ->**Note:** InfluxDB Enterprise on GCP is a self-managed product. For a fully managed InfluxDB experience, check out [InfluxDB Cloud 2.0](//influxdb/v2.0/cloud/get-started/). +>**Note:** InfluxDB Enterprise on GCP is a self-managed product. For a fully managed InfluxDB experience, check out [InfluxDB Cloud](/influxdb/cloud/get-started/). ## Verify prerequisites diff --git a/content/enterprise_influxdb/v1.8/install-and-deploy/deploying/google-cloud-platform.md b/content/enterprise_influxdb/v1.8/install-and-deploy/deploying/google-cloud-platform.md index 09887cf06..31cd1334b 100644 --- a/content/enterprise_influxdb/v1.8/install-and-deploy/deploying/google-cloud-platform.md +++ b/content/enterprise_influxdb/v1.8/install-and-deploy/deploying/google-cloud-platform.md @@ -20,7 +20,7 @@ Complete the following steps to deploy an InfluxDB Enterprise cluster on Google After deploying your cluster, see [Getting started with InfluxDB](/platform/introduction/getting-started) for an introduction to InfluxDB database and the InfluxData platform. ->**Note:** InfluxDB Enterprise on GCP is a self-managed product. For a fully managed InfluxDB experience, check out [InfluxDB Cloud 2.0](//influxdb/v2.0/cloud/get-started/). +>**Note:** InfluxDB Enterprise on GCP is a self-managed product. For a fully managed InfluxDB experience, check out [InfluxDB Cloud](/influxdb/cloud/get-started/). ## Verify prerequisites diff --git a/content/influxdb/cloud/_index.md b/content/influxdb/cloud/_index.md new file mode 100644 index 000000000..21235c021 --- /dev/null +++ b/content/influxdb/cloud/_index.md @@ -0,0 +1,19 @@ +--- +title: InfluxDB Cloud documentation +description: > + InfluxDB Cloud is an hosted and managed version of InfluxDB v2.0, the time series platform designed to handle high write and query loads. + Learn how to use and leverage InfluxDB Cloud in use cases such as monitoring metrics, IoT data, and events. +layout: landing-influxdb +menu: + influxdb_cloud: + name: InfluxDB Cloud +weight: 1 +--- + +#### Welcome +Welcome to the InfluxDB v2.0 documentation! +InfluxDB is an open source time series database designed to handle high write and query workloads. + +This documentation is meant to help you learn how to use and leverage InfluxDB to meet your needs. +Common use cases include infrastructure monitoring, IoT data collection, events handling, and more. +If your use case involves time series data, InfluxDB is purpose-built to handle it. diff --git a/content/influxdb/v2.0/account-management/_index.md b/content/influxdb/cloud/account-management/_index.md similarity index 65% rename from content/influxdb/v2.0/account-management/_index.md rename to content/influxdb/cloud/account-management/_index.md index 068d6ad4f..ce4e5efc7 100644 --- a/content/influxdb/v2.0/account-management/_index.md +++ b/content/influxdb/cloud/account-management/_index.md @@ -1,7 +1,7 @@ --- -title: Manage your InfluxDB Cloud 2.0 Account +title: Manage your InfluxDB Cloud Account description: > - View and manage information related to your InfluxDB Cloud 2.0 account such as + View and manage information related to your InfluxDB Cloud account such as pricing plans, data usage, account cancelation, etc. weight: 10 products: [cloud] @@ -9,7 +9,7 @@ aliases: - /influxdb/v2.0/cloud/account-management/ - /influxdb/v2.0/account-management menu: - influxdb_2_0: + influxdb_cloud: name: Account management products: [cloud] --- diff --git a/content/influxdb/v2.0/account-management/billing.md b/content/influxdb/cloud/account-management/billing.md similarity index 87% rename from content/influxdb/v2.0/account-management/billing.md rename to content/influxdb/cloud/account-management/billing.md index d938dcb3d..be20fd467 100644 --- a/content/influxdb/v2.0/account-management/billing.md +++ b/content/influxdb/cloud/account-management/billing.md @@ -4,12 +4,13 @@ list_title: Manage billing description: > Upgrade to the InfluxDB Cloud Usage-Based Plan and manage your billing information. aliases: + - /influxdb/v2.0/account-management/billing - /influxdb/v2.0/cloud/account-management/billing - /influxdb/v2.0/cloud/account-management/upgrade-to-payg/ - /influxdb/v2.0/cloud/account-management/upgrade-to-usage-based-plan/ weight: 103 menu: - influxdb_2_0: + influxdb_cloud: parent: Account management name: Manage billing products: [cloud] @@ -40,9 +41,9 @@ Add your payment method and view billing information in the {{< cloud-name "shor {{< nav-icon "account" >}} 2. Do one of the following: - - If you subscribed to an InfluxDB Cloud 2.0 plan through [**AWS Marketplace**](https://aws.amazon.com/marketplace/pp/B08234JZPS) or [**GCP Marketplace**](https://console.cloud.google.com/marketplace/details/influxdata-public/cloud2-gcp-marketplace-prod?pli=1), click the **AWS** or **GCP** link to access your billing and subscription information. + - If you subscribed to an InfluxDB Cloud plan through [**AWS Marketplace**](https://aws.amazon.com/marketplace/pp/B08234JZPS) or [**GCP Marketplace**](https://console.cloud.google.com/marketplace/details/influxdata-public/cloud2-gcp-marketplace-prod?pli=1), click the **AWS** or **GCP** link to access your billing and subscription information. - - If you subscribed to an InfluxDB Cloud 2.0 plan through **InfluxData**, complete the following procedures as needed: + - If you subscribed to an InfluxDB Cloud plan through **InfluxData**, complete the following procedures as needed: - [Add or update your payment method](#add-or-update-your-payment-method) - [Add or update your contact information](#add-or-update-your-contact-information) @@ -98,7 +99,7 @@ On the **Billing page**, view the total limits available for the Free Plan. ## Exceeded rate limits -If you exceed your plan's [rate limits](/influxdb/v2.0/account-management/pricing-plans/), {{< cloud-name >}} provides a notification in the {{< cloud-name "short" >}} user interface (UI) and adds a rate limit event to your **Usage** page for review. +If you exceed your plan's [rate limits](/influxdb/cloud/account-management/pricing-plans/), {{< cloud-name >}} provides a notification in the {{< cloud-name "short" >}} user interface (UI) and adds a rate limit event to your **Usage** page for review. All rate-limited requests are rejected; including both read and write requests. _Rate-limited requests are **not** queued._ diff --git a/content/influxdb/cloud/account-management/change-password.md b/content/influxdb/cloud/account-management/change-password.md new file mode 100644 index 000000000..fd7e77a76 --- /dev/null +++ b/content/influxdb/cloud/account-management/change-password.md @@ -0,0 +1,35 @@ +--- +title: Change your password +seotitle: Change your password in InfluxDB +description: Change your password in InfluxDB using the influx CLI. +menu: + influxdb_cloud: + name: Change your password + parent: Account management +weight: 105 +--- + +Use `influx` command line interface (CLI) to update your password. + +{{% note %}} +User passwords cannot be updated in the InfluxDB UI. +{{% /note %}} + +## Change your password using the influx CLI + +Use the [`influx user password` command](/influxdb/cloud/reference/cli/influx/user/password) +to update a password for a user. To update a password, you need the following: + +- Username or user ID _(provided in the output of `influx user list`)_ +- New password + +##### Update a password +```sh +# Syntax +influx user password -n + +# Example +influx user password -n johndoe +``` + +When prompted, enter and confirm the new password. diff --git a/content/influxdb/v2.0/account-management/data-usage.md b/content/influxdb/cloud/account-management/data-usage.md similarity index 83% rename from content/influxdb/v2.0/account-management/data-usage.md rename to content/influxdb/cloud/account-management/data-usage.md index 991d1510b..7b4015993 100644 --- a/content/influxdb/v2.0/account-management/data-usage.md +++ b/content/influxdb/cloud/account-management/data-usage.md @@ -2,12 +2,13 @@ title: View InfluxDB Cloud data usage list_title: View data usage description: > - View your InfluxDB Cloud 2.0 data usage and rate limit notifications. + View your InfluxDB Cloud data usage and rate limit notifications. weight: 103 aliases: - - /influxdb/v2.0/cloud/account-management/data-usage + - /influxdb/v2.0/account-management/data-usage + - /influxdb/v2.0/cloud/account-management/data-usage menu: - influxdb_2_0: + influxdb_cloud: parent: Account management name: View data usage products: [cloud] @@ -30,14 +31,14 @@ Find data usage information for the time frame specified in the drop-down at the ## Exceeded rate limits -If you exceed your plan's [rate limits](/influxdb/v2.0/account-management/pricing-plans/), {{< cloud-name >}} +If you exceed your plan's [rate limits](/influxdb/cloud/account-management/pricing-plans/), {{< cloud-name >}} will provide a notification in the {{< cloud-name "short" >}} user interface (UI) and add a rate limit event to your **Usage** page for review. All rate-limited requests are rejected; including both read and write requests. _Rate-limited requests are **not** queued._ -_To remove rate limits, [upgrade to a Usage-based Plan](/influxdb/v2.0/account-management/billing/#upgrade-to-usage-based-plan)._ +_To remove rate limits, [upgrade to a Usage-based Plan](/influxdb/cloud/account-management/billing/#upgrade-to-usage-based-plan)._ ### Rate-limited HTTP response code When a request exceeds your plan's rate limit, the InfluxDB API returns the following response: diff --git a/content/influxdb/v2.0/account-management/multi-user/_index.md b/content/influxdb/cloud/account-management/multi-user/_index.md similarity index 85% rename from content/influxdb/v2.0/account-management/multi-user/_index.md rename to content/influxdb/cloud/account-management/multi-user/_index.md index 7008d4cc9..8a88600c3 100644 --- a/content/influxdb/v2.0/account-management/multi-user/_index.md +++ b/content/influxdb/cloud/account-management/multi-user/_index.md @@ -4,9 +4,11 @@ description: > View and manage multiple users in an InfluxDB Cloud account. weight: 4 menu: - influxdb_2_0: + influxdb_cloud: parent: Account management name: Manage multiple users +aliases: + - /influxdb/v2.0/account-management/multi-user/ --- {{< cloud-name >}} accounts support multiple users in an organization. diff --git a/content/influxdb/v2.0/account-management/multi-user/invite-user.md b/content/influxdb/cloud/account-management/multi-user/invite-user.md similarity index 52% rename from content/influxdb/v2.0/account-management/multi-user/invite-user.md rename to content/influxdb/cloud/account-management/multi-user/invite-user.md index 5f69bbdc9..29140ea49 100644 --- a/content/influxdb/v2.0/account-management/multi-user/invite-user.md +++ b/content/influxdb/cloud/account-management/multi-user/invite-user.md @@ -5,12 +5,18 @@ description: > Invite a user to collaborate in InfluxDB Cloud. weight: 103 menu: - influxdb_2_0: + influxdb_cloud: parent: Manage multiple users identifier: invite_user_cloud +aliases: + - /influxdb/v2.0/account-management/multi-user/invite-user/ --- -1. Navigate to the **Users** page in the left navigation bar. +## Invite a user + +1. In the {{< cloud-name "short" >}} UI, select the user avatar in the left navigation menu, and select **Users**. + + {{< nav-icon "account" >}} 2. Under **Add a new user to your organization**, enter the email address of the user to invite. (Users must be invited one at a time.) 3. Click **Add & Invite**. @@ -20,8 +26,20 @@ The activation link expires after 72 hours. Once activated, the new user is added as an **Owner** with permissions to read and write all resources. +Accounts can have up to 50 pending invitations at one time. + +## Withdraw an invitation + +1. In the {{< cloud-name "short" >}} UI, select the user avatar in the left navigation menu, and select **Users**. + + {{< nav-icon "account" >}} +2. Click the {{< icon "delete" >}} next to the invitation you want to withdraw. +3. Confirm the withdrawl. + {{% warn %}} -Currently, Cloud 2.0 has only one permission level: Owner. +#### Permissions + +Currently, Cloud has only one permission level: Owner. With Owner permissions, a user can delete resources and other users from your organization. Take care when inviting a user. {{% /warn %}} diff --git a/content/influxdb/v2.0/account-management/multi-user/remove-user.md b/content/influxdb/cloud/account-management/multi-user/remove-user.md similarity index 81% rename from content/influxdb/v2.0/account-management/multi-user/remove-user.md rename to content/influxdb/cloud/account-management/multi-user/remove-user.md index 05e9168b8..28842f73d 100644 --- a/content/influxdb/v2.0/account-management/multi-user/remove-user.md +++ b/content/influxdb/cloud/account-management/multi-user/remove-user.md @@ -5,9 +5,11 @@ description: > Remove a user from an InfluxDB Cloud organization. weight: 103 menu: - influxdb_2_0: + influxdb_cloud: parent: Manage multiple users identifier: remove_user_cloud +aliases: + - /influxdb/v2.0/account-management/multi-user/remove-user/ --- 1. Navigate to the **Users** page in the left navigation bar. diff --git a/content/influxdb/v2.0/account-management/offboarding.md b/content/influxdb/cloud/account-management/offboarding.md similarity index 56% rename from content/influxdb/v2.0/account-management/offboarding.md rename to content/influxdb/cloud/account-management/offboarding.md index 2388661ec..15c5ca8bf 100644 --- a/content/influxdb/v2.0/account-management/offboarding.md +++ b/content/influxdb/cloud/account-management/offboarding.md @@ -1,13 +1,14 @@ --- title: Cancel your InfluxDB Cloud subscription description: > - Cancel your InfluxDB Cloud 2.0 account at any time by stopping all read and write + Cancel your InfluxDB Cloud account at any time by stopping all read and write requests, backing up data, and contacting InfluxData Support. -weight: 104 +weight: 106 aliases: - - /influxdb/v2.0/cloud/account-management/offboarding + - /influxdb/v2.0/account-management/offboarding + - /influxdb/v2.0/cloud/account-management/offboarding menu: - influxdb_2_0: + influxdb_cloud: parent: Account management name: Cancel InfluxDB Cloud products: [cloud] @@ -33,11 +34,11 @@ Exported data and artifacts can be used in an InfluxDB OSS instance. #### Export tasks -For details, see [Export a task](/influxdb/v2.0/process-data/manage-tasks/export-task/). +For details, see [Export a task](/influxdb/cloud/process-data/manage-tasks/export-task/). #### Export dashboards -For details, see [Export a dashboard](/influxdb/v2.0/visualize-data/dashboards/export-dashboard/). +For details, see [Export a dashboard](/influxdb/cloud/visualize-data/dashboards/export-dashboard/). #### Save Telegraf configurations @@ -60,6 +61,6 @@ To request a backup of data in your {{< cloud-name "short" >}} instance, contact 2. Do one of the following: - - If you subscribed to an InfluxDB Cloud 2.0 **Usage-Based Plan** through **AWS Marketplace**, click the **AWS** link, click **Unsubscribe**, and then click **Yes, cancel subscription**. - - If you subscribed to an InfluxDB Cloud 2.0 **Usage-Based Plan** through **GCP Marketplace**, click the **GCP** link, click **Unsubscribe**, and then click **Yes, cancel subscription**. - - If you subscribed to an InfluxDB Cloud 2.0 **Usage-Based Plan** through **InfluxData**, click **Cancel Service**. Select **I understand and agree to these conditions**, and then click **I understand, Cancel Service.** Click **Confirm and Cancel Service**. Your payment method is charged your final balance immediately upon cancellation of service. + - If you subscribed to an InfluxDB Cloud **Usage-Based Plan** through **AWS Marketplace**, click the **AWS** link, click **Unsubscribe**, and then click **Yes, cancel subscription**. + - If you subscribed to an InfluxDB Cloud **Usage-Based Plan** through **GCP Marketplace**, click the **GCP** link, click **Unsubscribe**, and then click **Yes, cancel subscription**. + - If you subscribed to an InfluxDB Cloud **Usage-Based Plan** through **InfluxData**, click **Cancel Service**. Select **I understand and agree to these conditions**, and then click **I understand, Cancel Service.** Click **Confirm and Cancel Service**. Your payment method is charged your final balance immediately upon cancellation of service. diff --git a/content/influxdb/v2.0/account-management/pricing-calculator.md b/content/influxdb/cloud/account-management/pricing-calculator.md similarity index 92% rename from content/influxdb/v2.0/account-management/pricing-calculator.md rename to content/influxdb/cloud/account-management/pricing-calculator.md index 379a55586..714b55d9b 100644 --- a/content/influxdb/v2.0/account-management/pricing-calculator.md +++ b/content/influxdb/cloud/account-management/pricing-calculator.md @@ -1,11 +1,11 @@ --- -title: InfluxDB Cloud 2.0 pricing calculator +title: InfluxDB Cloud pricing calculator description: > - Use the InfluxDB Cloud 2.0 pricing calculator to estimate costs by adjusting the number of devices, + Use the InfluxDB Cloud pricing calculator to estimate costs by adjusting the number of devices, plugins, metrics, and writes for the Usage-based Plan. weight: 2 menu: - influxdb_2_0: + influxdb_cloud: name: Pricing calculator products: [cloud] draft: true @@ -46,4 +46,4 @@ Guidelines used to estimate costs for default configurations: - **Professional**. For teams monitoring multiple disparate systems or use cases. - **Enterprise**. For teams monitoring multiple domains and use cases accessing a variety of dashboards. 5. Adjust the default configuration values to match your number of devices, plugins, metrics, and so on. The **Projected Usage** costs are automatically updated as you adjust your configuration. -6. Click **Get started with InfluxDB Cloud** [to get started](/influxdb/v2.0/get-started/). +6. Click **Get started with InfluxDB Cloud** [to get started](/influxdb/cloud/get-started/). diff --git a/content/influxdb/v2.0/account-management/pricing-plans.md b/content/influxdb/cloud/account-management/pricing-plans.md similarity index 82% rename from content/influxdb/v2.0/account-management/pricing-plans.md rename to content/influxdb/cloud/account-management/pricing-plans.md index bf05dfd1d..834f9b2e4 100644 --- a/content/influxdb/v2.0/account-management/pricing-plans.md +++ b/content/influxdb/cloud/account-management/pricing-plans.md @@ -1,26 +1,27 @@ --- -title: InfluxDB Cloud 2.0 pricing plans +title: InfluxDB Cloud pricing plans description: > - InfluxDB Cloud 2.0 provides two pricing plans to fit your needs – the rate-limited + InfluxDB Cloud provides two pricing plans to fit your needs – the rate-limited Free Plan and the Usage-based Plan. aliases: - /influxdb/v2.0/cloud/rate-limits/ - /influxdb/v2.0/cloud/pricing-plans/ + - /influxdb/v2.0/pricing-plans/ weight: 102 menu: - influxdb_2_0: + influxdb_cloud: parent: Account management name: Pricing plans products: [cloud] -influxdb/v2.0/tags: [VPC] +influxdb/cloud/tags: [VPC] --- -InfluxDB Cloud 2.0 offers two pricing plans: +InfluxDB Cloud offers two pricing plans: - [Free Plan](#free-plan) - [Usage-Based Plan](#usage-based-plan) - + ## Free Plan @@ -45,11 +46,11 @@ Data retention is determined by the time at which data is written to InfluxDB; n - Unlimited Slack notification endpoints -_To remove rate limits, [upgrade to a Usage-based Plan](/influxdb/v2.0/account-management/billing/#upgrade-to-usage-based-plan)._ +_To remove rate limits, [upgrade to a Usage-based Plan](/influxdb/cloud/account-management/billing/#upgrade-to-usage-based-plan)._ ## Usage-Based Plan -The Usage-based Plan offers more flexibility and ensures you only pay for what you [use](/influxdb/v2.0/account-management/data-usage/). +The Usage-based Plan offers more flexibility and ensures you only pay for what you [use](/influxdb/cloud/account-management/data-usage/). ### Pricing vectors @@ -68,7 +69,7 @@ To protect against any intentional or unintentional harm, Usage-Based Plans incl - **Ingest batch size:** 50MB - **Queries:** 3000MB every 5 minutes - **Storage:** Unlimited retention -- **Series cardinality:** 1,000,000 +- **Series cardinality:** 1,000,000 initial limit (higher limits available; [contact support](mailto:support@influxdata.com)) - **Create:** - Unlimited dashboards - Unlimited tasks diff --git a/content/influxdb/cloud/get-started.md b/content/influxdb/cloud/get-started.md new file mode 100644 index 000000000..e2d5517d6 --- /dev/null +++ b/content/influxdb/cloud/get-started.md @@ -0,0 +1,293 @@ +--- +title: Get started with InfluxDB Cloud +description: > + InfluxDB Cloud is a fully managed and hosted version of InfluxDB v2.0, the time series + platform purpose-built to collect, store, process and visualize metrics and events. +menu: + influxdb_cloud: + name: Get started +weight: 2 +influxdb/cloud/tags: [get-started, install] +aliases: + - /influxdb/v2.0/cloud/get-started +--- + +InfluxDB Cloud is a fully managed and hosted version of InfluxDB v2.0, the time series +platform purpose-built to collect, store, process and visualize metrics and events. + +_See [Differences between InfluxDB Cloud and InfluxDB OSS](#differences-between-influxdb-cloud-and-influxdb-oss)._ + +## Start for free + +Start using {{< cloud-name >}} at no cost with the [Free Plan](/influxdb/cloud/account-management/pricing-plans/#free-plan). +Use it as much and as long as you like within the plan's rate-limits. +Limits are designed to let you monitor 5-10 sensors, stacks or servers comfortably. + +## Sign up + +1. Choose one of the following: + + #### Subscribe through InfluxData + + To subscribe to an InfluxDB Cloud **Free Plan** through InfluxData, + go to [InfluxDB Cloud]({{< cloud-link >}}). + + - To use social sign-on, click **Continue with Google**. Note that Google social sign-on does not support email aliases. + - Sign up with email by entering your name, email address, and password, then click **Create Account**. + + If you originally signed up with email but want to enable social sign-on, you can do so by logging in through Google as long as you use the same email address. + + #### **Subscribe through a cloud provider** + To subscribe to an InfluxDB Cloud **Usage-Based** plan and pay through your + **Amazon Web Services (AWS)** or **Google Cloud Platform (GCP)** account: + + - **AWS** + Sign in to AWS, navigate to the [InfluxDB Cloud product on AWS Marketplace](https://aws.amazon.com/marketplace/pp/B08234JZPS), + and follow the prompts to subscribe. After you click **Set Up Your Account**, + enter your credentials, and then click **Start Now**. + All usage charges will be paid through the subscribed AWS account. + + - **GCP** + Sign in to GCP, navigate to the [InfluxDB Cloud product on GCP Marketplace](https://console.cloud.google.com/marketplace/details/influxdata-public/cloud2-gcp-marketplace-prod), + and follow the prompts to subscribe. After you click **Set Up Your Account**, + enter your credentials, and then click **Start Now**. + All usage charges will be paid through the subscribed GCP account. + + {{%note%}} +Currently, we do **not support** using an existing InfluxDB Cloud account to sign up for an InfluxDB Cloud plan through AWS or GCP Marketplaces. + {{%/note%}} + +2. If you signed up with your email address, InfluxDB Cloud requires email verification to complete the sign up process. + Verify your email address by opening the email sent to the address you provided and clicking **Verify Your Email**. +3. (If you subscribed through InfluxData) Choose your cloud provider. +4. Select a provider and region for your {{< cloud-name >}} instance. The following are available: + + {{< cloud_regions type="list" >}} + + _To suggest regions to add, click **Let us know** under Regions._ +5. (If you subscribed through InfluxData) Review the terms of the agreement, and then select **I have viewed and agree to InfluxDB Cloud Services Subscription Agreement and InfluxData Global Data Processing Agreement**. + For details on the agreements, see the [InfluxDB Cloud: Services Subscription Agreement](https://www.influxdata.com/legal/terms-of-use/) and the [InfluxData Global Data Processing Agreement](https://www.influxdata.com/legal/influxdata-global-data-processing-agreement/). + +6. Click **Finish**. {{< cloud-name >}} opens with a default organization and bucket (both created from your email address). + + _To update organization and bucket names, see [Update an organization](/influxdb/cloud/organizations/update-org/) + and [Update a bucket](/influxdb/cloud/organizations/buckets/update-bucket/#update-a-buckets-name-in-the-influxdb-ui)._ + +## (Optional) Download, install, and use the influx CLI + +To use the `influx` CLI to manage and interact with your InfluxDB Cloud instance, complete the following steps: + +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS](#) +[Linux](#) +{{% /tabs %}} + + +{{% tab-content %}} + +#### Step 1: Download influx CLI for macOS + +Click the following button to download and install `influx` CLI for macOS. + +influx CLI (macOS) + +#### Step 2: Unpackage the influx binary + +**Note:** The commands below are examples. Adjust the file names, paths, and utilities to your own needs. + +To unpackage the downloaded archive, **double click the archive file in Finder** +or run the following command in a macOS command prompt application such +**Terminal** or **[iTerm2](https://www.iterm2.com/)**: + +```sh +# Unpackage contents to the current working directory +tar zxvf ~/Downloads/influxdb_client_2.0.1_darwin_amd64.tar.gz +``` + +#### Step 3: (Optional) Place the binary in your $PATH + +If you choose, you can place `influx` in your `$PATH` or you can +prefix the executable with `./` to run in place. If the binary is on your $PATH, you can run `influx` from any directory. Otherwise, you must specify the location of the CLI (for example, `./influx`or `path/to/influx`). + +**Note:** If you have the 1.x binary on your $PATH, moving the 2.0 binary to your $PATH will overwrite the 1.x binary because they have the same name. + +```sh +# Copy the influx binary to your $PATH +sudo cp influxdb_client_2.0.1_darwin_amd64/influx /usr/local/bin/ +``` + +{{% note %}} +If you rename the binary, all references to `influx` in this documentation refer to the renamed binary. +{{% /note %}} + +#### Step 4: (macOS Catalina only) Authorize InfluxDB binaries + +If running `influx` on macOS Catalina, you must manually authorize the +`influx` binary in the **Security & Privacy** section of **System Preferences**. + +#### Step 5: Set up a configuration profile + +To avoid having to pass your InfluxDB [authentication token](/influxdb/cloud/security/tokens/) with each `influx` command, set up a configuration profile that stores your credentials. + +In a terminal, run the following command: + +```sh + # Set up a configuration profile + influx config create -n default \ + -u https://cloud2.influxdata.com \ + -o example-org \ + -t mySuP3rS3cr3tT0keN \ + -a + ``` + +This configures a new profile named `default` and makes the profile active so your `influx` CLI commands run against this instance. +For more detail, see [influx config](/influxdb/cloud/reference/cli/influx/config/). + +#### Step 6: Learn `influx` CLI commands + +To see all available `influx` commands, type `influx -h` or check out [influx - InfluxDB command line interface](/influxdb/cloud/reference/cli/influx/). + +{{% /tab-content %}} + + + +{{% tab-content %}} + +#### Step 1: Download influx CLI for Linux + +Click one of the following buttons to download and install the `influx` CLI appropriate for your chipset. + +influx CLI (amd64) +influx CLI (arm) + +#### Step 2: Unpackage the influx binary + +**Note:** The commands below are examples. Adjust the file names, paths, and utilities to your own needs. + +```sh +# Unpackage contents to the current working directory +tar xvfz influxdb_client_2.0.1_linux_amd64.tar.gz +``` + +#### Step 3: (Optional) Place the binary in your $PATH + +If you choose, you can place `influx` in your `$PATH` or you can +prefix the executable with `./` to run in place. If the binary is on your $PATH, you can run `influx` from any directory. Otherwise, you must specify the location of the CLI (for example, `./influx`or `path/to/influx`). + +**Note:** If you have the 1.x binary on your $PATH, moving the 2.0 binary to your $PATH will overwrite the 1.x binary because they have the same name. + +```sh +# Copy the influx and influxd binary to your $PATH +sudo cp influxdb_client_2.0.1_linux_amd64/influx /usr/local/bin/ +``` + +{{% note %}} +If you rename the binary, all references to `influx` in this documentation refer to the renamed binary. +{{% /note %}} + +#### Step 4: Set up a configuration profile + +To avoid having to pass your InfluxDB [authentication token](/influxdb/cloud/security/tokens/) with each `influx` command, set up a configuration profile that stores your credentials. + +In a terminal, run the following command: + +```sh + # Set up a configuration profile + influx config create -n default \ + -u https://cloud2.influxdata.com \ + -o example-org \ + -t mySuP3rS3cr3tT0keN \ + -a + ``` + +This configures a new profile named `default` and makes the profile active so your `influx` CLI commands run against this instance. +For more detail, see [influx config](/influxdb/cloud/reference/cli/influx/config/). + +#### Step 5: Learn `influx` CLI commands + +To see all available `influx` commands, type `influx -h` or check out [influx - InfluxDB command line interface](/influxdb/cloud/reference/cli/influx/). + + +{{% /tab-content %}} + + +{{< /tabs-wrapper >}} + +## Sign in + +Sign in to [InfluxDB Cloud](https://cloud2.influxdata.com) using your email address and password. + +Sign in to InfluxDB Cloud now + +## Start working with your time series data + +### Collect and write data + +Collect and write data to InfluxDB using the Telegraf plugins, the InfluxDB v2 API, the `influx` +command line interface (CLI), the InfluxDB UI (the user interface for InfluxDB Cloud), or the InfluxDB v2 API client libraries. + +#### Use Telegraf + +Use Telegraf to quickly write data to {{< cloud-name >}}. +Create new Telegraf configurations automatically in the InfluxDB UI, or manually update an +existing Telegraf configuration to send data to your {{< cloud-name "short" >}} instance. + +For details, see [Automatically configure Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/) +and [Manually update Telegraf configurations](/influxdb/cloud/write-data/no-code/use-telegraf/manual-config/). + +#### API, CLI, and client libraries + +For information about using the InfluxDB v2 API, `influx` CLI, and client libraries to write data, +see [Write data to InfluxDB](/influxdb/cloud/write-data/). + +#### Demo data + +**{{< cloud-name "short" >}}** lets you [add a demo data bucket](/influxdb/cloud/reference/sample-data/#influxdb-cloud-demo-data) +for quick, **free** access to time series data. + +### Query data + +Query data using Flux, the UI, and the `influx` command line interface. +See [Query data](/influxdb/cloud/query-data/). + +### Process data + +Use InfluxDB tasks to process and downsample data. See [Process data](/influxdb/cloud/process-data/). + +### Visualize data + +Build custom dashboards to visualize your data. +See [Visualize data](/influxdb/cloud/visualize-data/). + +### Monitor and alert + +Monitor your data and sends alerts based on specified logic. +See [Monitor and alert](/influxdb/cloud/monitor-alert/). + +## Differences between InfluxDB Cloud and InfluxDB OSS + +{{< cloud-name >}} is API-compatible and functionally compatible with InfluxDB OSS 2.0. +The primary differences between InfluxDB OSS 2.0 and InfluxDB Cloud are: + +- [InfluxDB scrapers](/influxdb/v2.0/write-data/no-code/scrape-data/) that collect data from specified + targets are not available in {{< cloud-name "short" >}}. +- {{< cloud-name "short" >}} instances are currently limited to a single organization. + +#### New features in InfluxDB Cloud + +- **Free Plan (rate-limited)**: Skip downloading and installing InfluxDB OSS 2.0 and + jump into exploring InfluxDB Cloud technology. + The Free Plan is designed for getting started with InfluxDB and for small hobby projects. +- **Flux support**: [Flux](/influxdb/cloud/query-data/get-started/) is a standalone data + scripting and query language that increases productivity and code reuse. + It is the primary language for working with data within InfluxDB Cloud. + Flux can be used with other data sources as well, letting you work with data where it resides. +- **Unified API**: Everything in InfluxDB (ingest, query, storage, and visualization) + is now accessible using a unified [InfluxDB v2 API](/influxdb/cloud/reference/api/) that + enables seamless movement between open source and cloud. +- **Integrated visualization and dashboards**: Based on the pioneering Chronograf project, + the new user interface (InfluxDB UI) offers quick and effortless onboarding, + richer user experiences, and significantly quicker results. +- **Usage-based pricing**: The [Usage-based Plan](/influxdb/cloud/account-management/pricing-plans/#usage-based-plan) + offers more flexibility and ensures that you only pay for what you use. diff --git a/content/influxdb/cloud/influxdb-templates/_index.md b/content/influxdb/cloud/influxdb-templates/_index.md new file mode 100644 index 000000000..521c0831c --- /dev/null +++ b/content/influxdb/cloud/influxdb-templates/_index.md @@ -0,0 +1,68 @@ +--- +title: InfluxDB templates +description: > + InfluxDB templates are prepackaged InfluxDB configurations that contain everything + from dashboards and Telegraf configurations to notifications and alerts. +menu: influxdb_cloud +weight: 9 +influxdb/cloud/tags: [templates] +--- + +InfluxDB templates are prepackaged InfluxDB configurations that contain everything +from dashboards and Telegraf configurations to notifications and alerts. +Use InfluxDB templates to quickly set up a fresh instance of InfluxDB, back up your +dashboard configuration, or share your configuration with the InfluxData community. + +**InfluxDB templates do the following:** + +- Reduce setup time +- Facilitate secure, portable, source-controlled InfluxDB platform states. +- Simplify sharing and using pre-built InfluxDB solutions. + +{{< youtube 2JjW4Rym9XE >}} + +## Template manifests +A template consists of a single file known as a **manifest** that defines the +InfluxDB state and associated [resources](#template-resources). +Template manifests support the following formats: + +- [YAML](https://yaml.org/) +- [JSON](https://www.json.org/) +- [Jsonnet](https://jsonnet.org/) + +{{% note %}} +Template manifests are compatible with +[Kubernetes Custom Resource Definitions (CRD)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/). +{{% /note %}} + +The `metadata.name` field in manifests uniquely identifies each resource in the template. +`metadata.name` values must be [DNS-1123](https://tools.ietf.org/html/rfc1123) compliant. +If resources in the template depend on other InfluxDB resources, all dependencies +must be included in the template. + +_See [Create an InfluxDB template](/influxdb/cloud/influxdb-templates/create/) for information about +generating template manifests._ + +### Template resources +Include the following **resources** in a template: + +- buckets +- checks +- dashboards +- dashboard variables +- labels +- notification endpoints +- notification rules +- tasks +- Telegraf configurations + +## Stacks +**InfluxDB stacks** are stateful InfluxDB templates. +When you apply a template, InfluxDB associates resources in the template with a stack. +Use stacks to add, update, or remove templated resources over time. + +For more information, see [InfluxDB Stacks](#influxdb-stacks) below. + +--- + +{{< children >}} diff --git a/content/influxdb/v2.0/influxdb-templates/cloud.md b/content/influxdb/cloud/influxdb-templates/cloud.md similarity index 67% rename from content/influxdb/v2.0/influxdb-templates/cloud.md rename to content/influxdb/cloud/influxdb-templates/cloud.md index f617f4cd1..1f50e1126 100644 --- a/content/influxdb/v2.0/influxdb-templates/cloud.md +++ b/content/influxdb/cloud/influxdb-templates/cloud.md @@ -2,15 +2,16 @@ title: InfluxDB templates in InfluxDB Cloud list_title: InfluxDB templates in Cloud description: > - Install templates directly in the UI or download the `influx` CLI to apply and manage InfluxDB templates in your InfluxDB Cloud account. + Install templates directly in the UI or download the `influx` CLI to apply + and manage InfluxDB templates in your InfluxDB Cloud account. menu: - influxdb_2_0: + influxdb_cloud: parent: InfluxDB templates name: Templates in Cloud weight: 101 aliases: - - /influxdb/v2.0/influxdb-templates/get_started_cloud/ -influxdb/v2.0/tags: [templates] + - /influxdb/cloud/influxdb-templates/get_started_cloud/ +influxdb/cloud/tags: [templates] products: [cloud] --- @@ -38,15 +39,15 @@ The Template Installer displays the template name and the number of resources in - Click **View Readme**. Complete the instructions to finalize your template. - (Optional) To customize a template, under **Installed Resources**, expand the template resources, and then click a resource to update it. Update any of the following resources included in the template: - - Buckets. [Update buckets](/influxdb/v2.0/organizations/buckets/update-bucket/) - - Dashboards. [Control dashboards](/influxdb/v2.0/visualize-data/dashboards/control-dashboard/) - - Labels. [Edit labels](/influxdb/v2.0/visualize-data/labels/#edit-a-label) - - Checks. [Update checks](/influxdb/v2.0/monitor-alert/checks/update/) - - Notification endpoints. [Update notification endpoints](/influxdb/v2.0/monitor-alert/notification-endpoints/update/) - - Notification rules. [Update notification rules](/influxdb/v2.0/monitor-alert/notification-rules/update/) - - Telegraf configurations. [Update a Telegraf configurations](/influxdb/v2.0/telegraf-configs/update/) + - Buckets. [Update buckets](/influxdb/cloud/organizations/buckets/update-bucket/) + - Dashboards. [Control dashboards](/influxdb/cloud/visualize-data/dashboards/control-dashboard/) + - Labels. [Edit labels](/influxdb/cloud/visualize-data/labels/#edit-a-label) + - Checks. [Update checks](/influxdb/cloud/monitor-alert/checks/update/) + - Notification endpoints. [Update notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/update/) + - Notification rules. [Update notification rules](/influxdb/cloud/monitor-alert/notification-rules/update/) + - Telegraf configurations. [Update a Telegraf configurations](/influxdb/cloud/telegraf-configs/update/) -7. (Optional) Add or delete resources from the template, and then use the `influx` CLI to [export resources to a new template (JSON or YAML file)](/influxdb/v2.0/influxdb-templates/create/#export-all-resources). +7. (Optional) Add or delete resources from the template, and then use the `influx` CLI to [export resources to a new template (JSON or YAML file)](/influxdb/cloud/influxdb-templates/create/#export-all-resources). {{% note %}} To install and configure the `influx` CLI, complete steps 1-2 in the procedure below. @@ -54,15 +55,15 @@ To install and configure the `influx` CLI, complete steps 1-2 in the procedure b ## Apply and manage templates using the influx CLI -Use the [`influx` CLI](/influxdb/v2.0/reference/cli/influx/) +Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to apply and manage templates in your InfluxDB Cloud account. If you haven’t already, do the following: -1. [Download and install `influx` CLI](/influxdb/v2.0/get-started/#optional-download-install-and-use-the-influx-cli). -2. [Configure the `influx` CLI](/influxdb/v2.0/get-started/#set-up-influxdb) to use your +1. [Download and install `influx` CLI](/influxdb/cloud/get-started/#optional-download-install-and-use-the-influx-cli). +2. [Configure the `influx` CLI](/influxdb/cloud/get-started/#set-up-influxdb) to use your InfluxDB Cloud instance URL, organization, and tokens. -3. [Use the `influx` CLI](/influxdb/v2.0/reference/cli/influx/) to use, manage, and create +3. [Use the `influx` CLI](/influxdb/cloud/reference/cli/influx/) to use, manage, and create InfluxDB templates: - - [Use templates](/influxdb/v2.0/influxdb-templates/use/) - - [Create templates](/influxdb/v2.0/influxdb-templates/create/) + - [Use templates](/influxdb/cloud/influxdb-templates/use/) + - [Create templates](/influxdb/cloud/influxdb-templates/create/) \ No newline at end of file diff --git a/content/influxdb/cloud/influxdb-templates/create.md b/content/influxdb/cloud/influxdb-templates/create.md new file mode 100644 index 000000000..67212129d --- /dev/null +++ b/content/influxdb/cloud/influxdb-templates/create.md @@ -0,0 +1,231 @@ +--- +title: Create an InfluxDB template +description: > + Use the InfluxDB UI and the `influx export` command to create InfluxDB templates. +menu: + influxdb_cloud: + parent: InfluxDB templates + name: Create a template + identifier: Create an InfluxDB template +weight: 103 +influxdb/cloud/tags: [templates] +related: + - /influxdb/cloud/reference/cli/influx/export/ + - /influxdb/cloud/reference/cli/influx/export/all/ +--- + +Use the InfluxDB user interface (UI) and the `influx export` command to +create InfluxDB templates. +Add resources (buckets, Telegraf configurations, tasks, and more) in the InfluxDB +UI and export the resources as a template. + +{{< youtube 714uHkxKM6U >}} + +{{% note %}} +#### InfluxDB OSS for creating templates +Templatable resources are scoped to a single organization, so the simplest way to create a +template is to create a new organization, build the template within the organization, +and then [export all resources](#export-all-resources) as a template. + +**[InfluxDB OSS](/{{< latest "influxdb" "v2" >}}/)** supports multiple organizations so you +can create new organizations for the sole purpose of building and maintaining a template. +In **InfluxDB Cloud**, your user account is an organization. +**We recommend [using InfluxDB OSS to create InfluxDB templates](/{{< latest "influxdb" "v2" >}}/influxdb-templates/create/).** +{{% /note %}} + +## Export a template +Do one of the following to export a template: + +- [Export all resources in an organization](#export-all-resources) +- [Export specific resources in an organization](#export-specific-resources) +- [Export a stack and its associated resources](#export-a-stack) + +### Export all resources +To export all templatable resources within an organization to a template manifest, +use the `influx export all` command. +Provide the following: + +- **Organization name** or **ID** +- **Authentication token** with read access to the organization +- **Destination path and filename** for the template manifest. + The filename extension determines the template format—both **YAML** (`.yml`) and + **JSON** (`.json`) are supported. + +###### Export all resources to a template +```sh +# Syntax +influx export all -o -f -t + +# Example +influx export all \ + -o my-org \ + -f ~/templates/awesome-template.yml \ + -t $INFLUX_TOKEN +``` + +#### Export resources filtered by labelName or resourceKind +The `influx export all` command has an optional `--filter` flag that exports +only resources that match specified label names or resource kinds. +Provide multiple filters for both `labelName` and `resourceKind` + +###### Export only dashboards and buckets with specific labels +The following example exports resources that match this predicate logic: + +```js +(resourceKind == "Bucket" or resourceKind == "Dashboard") +and +(labelName == "Example1" or labelName == "Example2") +``` + +```sh +influx export all \ + -o my-org \ + -f ~/templates/awesome-template.yml \ + -t $INFLUX_TOKEN \ + --filter=resourceKind=Bucket \ + --filter=resourceKind=Dashboard \ + --filter=labelName=Example1 \ + --filter=labelName=Example2 +``` + +For information about flags, see the +[`influx export all` documentation](/influxdb/cloud/reference/cli/influx/export/all/). + +### Export specific resources +To export specific resources within an organization to a template manifest, +use the `influx export` with resource flags for each resource to include. +Provide the following: + +- **Organization name** or **ID** +- **Authentication token** with read access to the organization +- **Destination path and filename** for the template manifest. + The filename extension determines the template format—both **YAML** (`.yml`) and + **JSON** (`.json`) are supported. +- **Resource flags** with corresponding lists of resource IDs to include in the template. + For information about what resource flags are available, see the + [`influx export` documentation](/influxdb/cloud/reference/cli/influx/export/). + +###### Export specific resources to a template +```sh +# Syntax +influx export all -o -f -t [resource-flags] + +# Example +influx export all \ + -o my-org \ + -f ~/templates/awesome-template.yml \ + -t $INFLUX_TOKEN \ + --buckets=00x000ooo0xx0xx,o0xx0xx00x000oo \ + --dashboards=00000xX0x0X00x000 \ + --telegraf-configs=00000x0x000X0x0X0 +``` + +### Export a stack +To export a stack and all its associated resources as a template, use the +`influx export stack` command. +Provide the following: + +- **Organization name** or **ID** +- **Authentication token** with read access to the organization +- **Destination path and filename** for the template manifest. + The filename extension determines the template format—both **YAML** (`.yml`) and + **JSON** (`.json`) are supported. +- **Stack ID** + +###### Export a stack as a template +```sh +# Syntax +influx export stack \ + -o \ + -t \ + -f \ + + +# Example +influx export stack \ + -o my-org \ + -t mYSuP3RS3CreTt0K3n + -f ~/templates/awesome-template.yml \ + 05dbb791a4324000 +``` + +## Include user-definable resource names +After exporting a template manifest, replace resource names with **environment references** +to let users customize resource names when installing your template. + +1. [Export a template](#export-a-template) +2. Select any of the following resource fields to update: + + - `metadata.name` + - `associations[].name` + - `endpointName` _(unique to `NotificationRule` resources)_ + +3. Replace the resource field value with an `envRef` object with a `key` property + that reference the key of a key-value pair the user provides when installing the template. + During installation, the `envRef` object is replaced by the value of the + referenced key-value pair. + If the user does not provide the environment reference key-value pair, InfluxDB + uses the `key` string as the default value. + + {{< code-tabs-wrapper >}} + {{% code-tabs %}} +[YAML](#) +[JSON](#) + {{% /code-tabs %}} + {{% code-tab-content %}} +```yml +apiVersion: influxdata.com/v2alpha1 +kind: Bucket +metadata: + name: + envRef: + key: bucket-name-1 +``` + {{% /code-tab-content %}} + {{% code-tab-content %}} +```json +{ + "apiVersion": "influxdata.com/v2alpha1", + "kind": "Bucket", + "metadata": { + "name": { + "envRef": { + "key": "bucket-name-1" + } + } + } +} +``` + {{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +Using the example above, users are prompted to provide a value for `bucket-name-1` +when [applying the template](/influxdb/cloud/influxdb-templates/use/#apply-templates). +Users can also include the `--env-ref` flag with the appropriate key-value pair +when installing the template. + +```sh +# Set bucket-name-1 to "myBucket" +influx apply \ + -f /path/to/template.yml \ + --env-ref=bucket-name-1=myBucket +``` + +_If sharing your template, we recommend documenting what environment references +exist in the template and what keys to use to replace them._ + +{{% note %}} +#### Resource fields that support environment references +Only the following fields support environment references: + +- `metadata.name` +- `spec.endpointName` +- `spec.associations.name` +{{% /note %}} + +## Share your InfluxDB templates +Share your InfluxDB templates with the entire InfluxData community. +**Contribute your template to the [InfluxDB Community Templates](https://github.com/influxdata/community-templates/) +repository on GitHub.** + +View InfluxDB Community Templates diff --git a/content/influxdb/cloud/influxdb-templates/stacks/_index.md b/content/influxdb/cloud/influxdb-templates/stacks/_index.md new file mode 100644 index 000000000..b52108e10 --- /dev/null +++ b/content/influxdb/cloud/influxdb-templates/stacks/_index.md @@ -0,0 +1,51 @@ +--- +title: InfluxDB stacks +description: > + InfluxDB stacks are stateful InfluxDB templates that let you add, + update, and remove templated resources over time, avoid duplicating resources + when applying the same or similar templates more than once, and apply + changes to distributed instances of InfluxDB OSS or InfluxDB Cloud. +menu: + influxdb_cloud: + parent: InfluxDB templates +weight: 105 +related: + - /influxdb/cloud/reference/cli/stacks/ +--- + +**InfluxDB stacks** are **stateful [InfluxDB templates](/influxdb/cloud/influxdb-templates)** +that let you add, update, and remove templated resources over time, avoid +duplicating resources when applying the same or similar templates more than once, +and apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud. + +## Ideal use cases for InfluxDB stacks +Stacks help save time and effort in the following use cases: + +- [Actively develop and extend templates](#actively-develop-and-extend-templates) +- [Apply updates from source-controlled templates](#apply-updates-from-source-controlled-templates) +- [Apply template updates across multiple InfluxDB instances](#apply-template-updates-across-multiple-influxdb-instances) + +### Actively develop and extend templates +InfluxDB stacks aid in developing and maintaining InfluxDB templates. +Stacks let you modify and update template manifests and apply those changes in +any stack that uses the template. + +### Apply updates from source-controlled templates +You can use a variety of InfluxDB templates from many different sources including +[Community Templates](https://github.com/influxdata/community-templates/) or +self-built custom templates. +As templates are updated over time, stacks allow template users to gracefully +apply updates without creating duplicate resources. + +### Apply template updates across multiple InfluxDB instances +In many cases, users have more than one instance of InfluxDB running and apply +the same template to each separate instance. +By using stacks, you can make changes to a stack on one instance, +[export the stack as a template](/influxdb/cloud/influxdb-templates/create/#export-a-stack) +and then apply the changes to your other InfluxDB instances. + +## Manage InfluxDB Stacks + +{{< children type="anchored-list" >}} + +{{< children readmore=true >}} diff --git a/content/influxdb/cloud/influxdb-templates/stacks/init.md b/content/influxdb/cloud/influxdb-templates/stacks/init.md new file mode 100644 index 000000000..71f7317f8 --- /dev/null +++ b/content/influxdb/cloud/influxdb-templates/stacks/init.md @@ -0,0 +1,73 @@ +--- +title: Initialize an InfluxDB stack +list_title: Initialize a stack +description: > + InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/influxdb/cloud/influxdb-templates/use/) + **without providing a stack ID**. + To manually create or initialize a new stack, use the [`influx stacks init` command](/influxdb/cloud/reference/cli/influx/stacks/init/). +menu: + influxdb_cloud: + parent: InfluxDB stacks + name: Initialize a stack +weight: 201 +related: + - /influxdb/cloud/reference/cli/influx/stacks/init/ +list_code_example: | + ```sh + influx apply \ + -o example-org \ + -f path/to/template.yml + ``` + ```sh + influx stacks init \ + -o example-org \ + -n "Example Stack" \ + -d "InfluxDB stack for monitoring some awesome stuff" \ + -u https://example.com/template-1.yml \ + -u https://example.com/template-2.yml + ``` +--- + +InfluxDB automatically creates a new stack each time you [apply an InfluxDB template](/influxdb/cloud/influxdb-templates/use/) +**without providing a stack ID**. +To manually create or initialize a new stack, use the [`influx stacks init` command](/influxdb/cloud/reference/cli/influx/stacks/init/). + +## Initialize a stack when applying a template +To automatically create a new stack when [applying an InfluxDB template](/influxdb/cloud/influxdb-templates/use/) +**don't provide a stack ID**. +InfluxDB applies the resources in the template to a new stack and provides the **stack ID** the output. + +```sh +influx apply \ + -o example-org \ + -f path/to/template.yml +``` + +## Manually initialize a new stack +Use the [`influx stacks init` command](/influxdb/cloud/reference/cli/influx/stacks/init/) +to create or initialize a new InfluxDB stack. + +**Provide the following:** + +- Organization name or ID +- Stack name +- Stack description +- InfluxDB template URLs + + +```sh +# Syntax +influx stacks init \ + -o \ + -n \ + -d + +# Example +influx stacks init \ + -o example-org \ + -n "Example Stack" \ + -d "InfluxDB stack for monitoring some awesome stuff" \ + -u https://example.com/template-1.yml \ + -u https://example.com/template-2.yml +``` diff --git a/content/influxdb/cloud/influxdb-templates/stacks/remove.md b/content/influxdb/cloud/influxdb-templates/stacks/remove.md new file mode 100644 index 000000000..2dfe162ba --- /dev/null +++ b/content/influxdb/cloud/influxdb-templates/stacks/remove.md @@ -0,0 +1,39 @@ +--- +title: Remove an InfluxDB stack +list_title: Remove a stack +description: > + Use the [`influx stacks remove` command](/influxdb/cloud/reference/cli/influx/stacks/remove/) + to remove an InfluxDB stack and all its associated resources. +menu: + influxdb_cloud: + parent: InfluxDB stacks + name: Remove a stack +weight: 204 +related: + - /influxdb/cloud/reference/cli/influx/stacks/remove/ +list_code_example: | + ```sh + influx stacks remove \ + -o example-org \ + --stack-id=12ab34cd56ef + ``` +--- + +Use the [`influx stacks remove` command](/influxdb/cloud/reference/cli/influx/stacks/remove/) +to remove an InfluxDB stack and all its associated resources. + +**Provide the following:** + +- Organization name or ID +- Stack ID + + +```sh +# Syntax +influx stacks remove -o --stack-id= + +# Example +influx stacks remove \ + -o example-org \ + --stack-id=12ab34cd56ef +``` diff --git a/content/influxdb/cloud/influxdb-templates/stacks/update.md b/content/influxdb/cloud/influxdb-templates/stacks/update.md new file mode 100644 index 000000000..02e9e424f --- /dev/null +++ b/content/influxdb/cloud/influxdb-templates/stacks/update.md @@ -0,0 +1,56 @@ +--- +title: Update an InfluxDB stack +list_title: Update a stack +description: > + Use the [`influx apply` command](/influxdb/cloud/reference/cli/influx/apply/) + to update a stack with a modified template. + When applying a template to an existing stack, InfluxDB checks to see if the + resources in the template match existing resources. + InfluxDB updates, adds, and removes resources to resolve differences between + the current state of the stack and the newly applied template. +menu: + influxdb_cloud: + parent: InfluxDB stacks + name: Update a stack +weight: 202 +related: + - /influxdb/cloud/reference/cli/influx/apply + - /influxdb/cloud/reference/cli/influx/stacks/update/ +list_code_example: | + ```sh + influx apply \ + -o example-org \ + -u http://example.com/template-1.yml \ + -u http://example.com/template-2.yml \ + --stack-id=12ab34cd56ef + ``` +--- + +Use the [`influx apply` command](/influxdb/cloud/reference/cli/influx/apply/) +to update a stack with a modified template. +When applying a template to an existing stack, InfluxDB checks to see if the +resources in the template match existing resources. +InfluxDB updates, adds, and removes resources to resolve differences between +the current state of the stack and the newly applied template. + +Each stack is uniquely identified by a **stack ID**. +For information about retrieving your stack ID, see [View stacks](/influxdb/cloud/influxdb-templates/stacks/view/). + +**Provide the following:** + +- Organization name or ID +- Stack ID +- InfluxDB template URLs to apply + + +```sh +influx apply \ + -o example-org \ + -u http://example.com/template-1.yml \ + -u http://example.com/template-2.yml \ + --stack-id=12ab34cd56ef +``` + +Template resources are uniquely identified by their `metadata.name` field. +If errors occur when applying changes to a stack, all applied changes are +reversed and the stack is returned to its previous state. diff --git a/content/influxdb/cloud/influxdb-templates/stacks/view.md b/content/influxdb/cloud/influxdb-templates/stacks/view.md new file mode 100644 index 000000000..7bc5296c7 --- /dev/null +++ b/content/influxdb/cloud/influxdb-templates/stacks/view.md @@ -0,0 +1,66 @@ +--- +title: View InfluxDB stacks +list_title: View stacks +description: > + Use the [`influx stacks` command](/influxdb/cloud/reference/cli/influx/stacks/) + to view installed InfluxDB stacks and their associated resources. +menu: + influxdb_cloud: + parent: InfluxDB stacks + name: View stacks +weight: 203 +related: + - /influxdb/cloud/reference/cli/influx/stacks/ +list_code_example: | + ```sh + influx stacks -o example-org + ``` +--- + +Use the [`influx stacks` command](/influxdb/cloud/reference/cli/influx/stacks/) +to view installed InfluxDB stacks and their associated resources. + +**Provide the following:** + +- Organization name or ID + + +```sh +# Syntax +influx stacks -o + +# Example +influx stacks -o example-org +``` + +### Filter stacks +To output information about specific stacks, use the `--stack-name` or `--stack-id` +flags to filter output by stack names or stack IDs. + +##### Filter by stack name +```sh +# Syntax +influx stacks \ + -o \ + --stack-name= + +# Example +influx stacks \ + -o example-org \ + --stack-name=stack1 \ + --stack-name=stack2 +``` + +### Filter by stack ID +```sh +# Syntax +influx stacks \ + -o \ + --stack-id= + +# Example +influx stacks \ + -o example-org \ + --stack-id=12ab34cd56ef \ + --stack-id=78gh910i11jk +``` diff --git a/content/influxdb/cloud/influxdb-templates/use.md b/content/influxdb/cloud/influxdb-templates/use.md new file mode 100644 index 000000000..0343694f1 --- /dev/null +++ b/content/influxdb/cloud/influxdb-templates/use.md @@ -0,0 +1,241 @@ +--- +title: Use InfluxDB templates +description: > + Use the `influx` command line interface (CLI) to summarize, validate, and apply + templates from your local filesystem and from URLs. +menu: + influxdb_cloud: + parent: InfluxDB templates + name: Use templates +weight: 102 +influxdb/cloud/tags: [templates] +related: + - /influxdb/cloud/reference/cli/influx/apply/ + - /influxdb/cloud/reference/cli/influx/template/ + - /influxdb/cloud/reference/cli/influx/template/validate/ +--- + +Use the `influx` command line interface (CLI) to summarize, validate, and apply +templates from your local filesystem and from URLs. + +- [Use InfluxDB community templates](#use-influxdb-community-templates) +- [View a template summary](#view-a-template-summary) +- [Validate a template](#validate-a-template) +- [Apply templates](#apply-templates) + + +## Use InfluxDB community templates +The [InfluxDB community templates repository](https://github.com/influxdata/community-templates/) +is home to a growing number of InfluxDB templates developed and maintained by +others in the InfluxData community. +Apply community templates directly from GitHub using a template's download URL +or download the template. + +{{< youtube 2JjW4Rym9XE >}} + +{{% note %}} +When attempting to access the community templates via the URL, the templates use the following +as the root of the URL: + +```sh +https://raw.githubusercontent.com/influxdata/community-templates/master/ +``` + +For example, the Docker community template can be accessed via: + +```sh +https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml +``` +{{% /note %}} + +View InfluxDB Community Templates + +## View a template summary +To view a summary of what's included in a template before applying the template, +use the [`influx template` command](/influxdb/cloud/reference/cli/influx/template/). +View a summary of a template stored in your local filesystem or from a URL. + +{{% code-tabs-wrapper %}} +{{% code-tabs %}} +[From a file](#) +[From a URL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +# Syntax +influx template -f + +# Example +influx template -f /path/to/template.yml +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +# Syntax +influx template -u + +# Example +influx template -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml +``` +{{% /code-tab-content %}} +{{% /code-tabs-wrapper %}} + +## Validate a template +To validate a template before you install it or troubleshoot a template, use +the [`influx template validate` command](/influxdb/cloud/reference/cli/influx/template/validate/). +Validate a template stored in your local filesystem or from a URL. + +{{% code-tabs-wrapper %}} +{{% code-tabs %}} +[From a file](#) +[From a URL](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +# Syntax +influx template validate -f + +# Example +influx template validate -f /path/to/template.yml +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +# Syntax +influx template validate -u + +# Example +influx template validate -u https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml +``` +{{% /code-tab-content %}} +{{% /code-tabs-wrapper %}} + +## Apply templates +Use the [`influx apply` command](/influxdb/cloud/reference/cli/influx/apply/) to install templates +from your local filesystem or from URLs. + +- [Apply a template from a file](#apply-a-template-from-a-file) +- [Apply all templates in a directory](#apply-all-templates-in-a-directory) +- [Apply a template from a URL](#apply-a-template-from-a-url) +- [Apply templates from both files and URLs](#apply-templates-from-both-files-and-urls) +- [Define environment references](#define-environment-references) +- [Include a secret when installing a template](#include-a-secret-when-installing-a-template) + +{{% note %}} +#### Apply templates to an existing stack +To apply a template to an existing stack, include the stack ID when applying the template. +Any time you apply a template without a stack ID, InfluxDB initializes a new stack +and all new resources. +For more information, see [InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/). +{{% /note %}} + +### Apply a template from a file +To install templates stored on your local machine, use the `-f` or `--file` flag +to provide the **file path** of the template manifest. + +```sh +# Syntax +influx apply -o -f + +# Examples +# Apply a single template +influx apply -o example-org -f /path/to/template.yml + +# Apply multiple templates +influx apply -o example-org \ + -f /path/to/this/template.yml \ + -f /path/to/that/template.yml +``` + +### Apply all templates in a directory +To apply all templates in a directory, use the `-f` or `--file` flag to provide +the **directory path** of the directory where template manifests are stored. +By default, this only applies templates stored in the specified directory. +To apply all templates stored in the specified directory and its subdirectories, +include the `-R`, `--recurse` flag. + +```sh +# Syntax +influx apply -o -f + +# Examples +# Apply all templates in a directory +influx apply -o example-org -f /path/to/template/dir/ + +# Apply all templates in a directory and its subdirectories +influx apply -o example-org -f /path/to/template/dir/ -R +``` + +### Apply a template from a URL +To apply templates from a URL, use the `-u` or `--template-url` flag to provide the URL +of the template manifest. + +```sh +# Syntax +influx apply -o -u + +# Examples +# Apply a single template from a URL +influx apply -o example-org -u https://example.com/templates/template.yml + +# Apply multiple templates from URLs +influx apply -o example-org \ + -u https://example.com/templates/template1.yml \ + -u https://example.com/templates/template2.yml +``` + +### Apply templates from both files and URLs +To apply templates from both files and URLs in a single command, include multiple +file or directory paths and URLs, each with the appropriate `-f` or `-u` flag. + +```sh +# Syntax +influx apply -o -u -f + +# Example +influx apply -o example-org \ + -u https://example.com/templates/template1.yml \ + -u https://example.com/templates/template2.yml \ + -f ~/templates/custom-template.yml \ + -f ~/templates/iot/home/ \ + --recurse +``` + +### Define environment references +Some templates include [environment references](/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names) that let you provide custom resource names. +The `influx apply` command prompts you to provide a value for each environment +reference in the template. +You can also provide values for environment references by including an `--env-ref` +flag with a key-value pair comprised of the environment reference key and the +value to replace it. + +```sh +influx apply -o example-org -f /path/to/template.yml \ + --env-ref=bucket-name-1=myBucket + --env-ref=label-name-1=Label1 \ + --env-ref=label-name-2=Label2 +``` + +### Include a secret when installing a template +Some templates use [secrets](/influxdb/cloud/security/secrets/) in queries. +Secret values are not included in templates. +To define secret values when installing a template, include the `--secret` flag +with the secret key-value pair. + +```sh +# Syntax +influx apply -o -f \ + --secret== + +# Examples +# Define a single secret when applying a template +influx apply -o example-org -f /path/to/template.yml \ + --secret=FOO=BAR + +# Define multiple secrets when applying a template +influx apply -o example-org -f /path/to/template.yml \ + --secret=FOO=bar \ + --secret=BAZ=quz +``` + +_To add a secret after applying a template, see [Add secrets](/influxdb/cloud/security/secrets/manage-secrets/add/)._ diff --git a/content/influxdb/cloud/monitor-alert/_index.md b/content/influxdb/cloud/monitor-alert/_index.md new file mode 100644 index 000000000..11e9b6130 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/_index.md @@ -0,0 +1,38 @@ +--- +title: Monitor data and send alerts +seotitle: Monitor data and send alerts +description: > + Monitor your time series data and send alerts by creating checks, notification + rules, and notification endpoints. Or use community templates to monitor supported environments. +menu: + influxdb_cloud: + name: Monitor & alert +weight: 6 +influxdb/cloud/tags: [monitor, alert, checks, notification, endpoints] +--- + +Monitor your time series data and send alerts by creating checks, notification +rules, and notification endpoints. Or use [community templates to monitor](/influxdb/cloud/monitor-alert/templates/) supported environments. + +## Overview + +1. A [check](/influxdb/cloud/reference/glossary/#check) in InfluxDB queries data and assigns a status with a `_level` based on specific conditions. +2. InfluxDB stores the output of a check in the `statuses` measurement in the `_monitoring` system bucket. +3. [Notification rules](/influxdb/cloud/reference/glossary/#notification-rule) check data in the `statuses` + measurement and, based on conditions set in the notification rule, send a message + to a [notification endpoint](/influxdb/cloud/reference/glossary/#notification-endpoint). +4. InfluxDB stores notifications in the `notifications` measurement in the `_monitoring` system bucket. + +## Create an alert + +To get started, do the following: + +1. [Create checks](/influxdb/cloud/monitor-alert/checks/create/) to monitor data and assign a status. +2. [Add notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/create/) + to send notifications to third parties. +3. [Create notification rules](/influxdb/cloud/monitor-alert/notification-rules/create) to check + statuses and send notifications to your notifications endpoints. + +## Manage your monitoring and alerting pipeline + +{{< children >}} diff --git a/content/influxdb/cloud/monitor-alert/checks/_index.md b/content/influxdb/cloud/monitor-alert/checks/_index.md new file mode 100644 index 000000000..0a45ce46a --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/checks/_index.md @@ -0,0 +1,19 @@ +--- +title: Manage checks +seotitle: Manage monitoring checks in InfluxDB +description: > + Checks in InfluxDB query data and apply a status or level to each data point based on specified conditions. +menu: + influxdb_cloud: + parent: Monitor & alert +weight: 101 +influxdb/cloud/tags: [monitor, checks, notifications, alert] +related: + - /influxdb/cloud/monitor-alert/notification-rules/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +Checks in InfluxDB query data and apply a status or level to each data point based on specified conditions. +Learn how to create and manage checks: + +{{< children >}} diff --git a/content/influxdb/cloud/monitor-alert/checks/create.md b/content/influxdb/cloud/monitor-alert/checks/create.md new file mode 100644 index 000000000..7b5a3842e --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/checks/create.md @@ -0,0 +1,152 @@ +--- +title: Create checks +seotitle: Create monitoring checks in InfluxDB +description: > + Create a check in the InfluxDB UI. +menu: + influxdb_cloud: + parent: Manage checks +weight: 201 +related: + - /influxdb/cloud/monitor-alert/notification-rules/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +Create a check in the InfluxDB user interface (UI). +Checks query data and apply a status to each point based on specified conditions. + +## Parts of a check +A check consists of two parts – a query and check configuration. + +#### Check query +- Specifies the dataset to monitor. +- May include tags to narrow results. + +#### Check configuration +- Defines check properties, including the check interval and status message. +- Evaluates specified conditions and applies a status (if applicable) to each data point: + - `crit` + - `warn` + - `info` + - `ok` +- Stores status in the `_level` column. + +## Check types +There are two types of checks – a threshold check and a deadman check. + +#### Threshold check +A threshold check assigns a status based on a value being above, below, +inside, or outside of defined thresholds. + +#### Deadman check +A deadman check assigns a status to data when a series or group doesn't report +in a specified amount of time. + +## Create a check in the InfluxDB UI +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Click **{{< icon "plus" >}} Create** and select the [type of check](#check-types) to create. +3. Click **Name this check** in the top left corner and provide a unique name for the check. + +#### Configure the check query +1. Select the **bucket**, **measurement**, **field** and **tag sets** to query. +2. If creating a threshold check, select an **aggregate function**. + Aggregate functions aggregate data between the specified check intervals and + return a single value for the check to process. + + In the **Aggregate functions** column, select an interval from the interval drop-down list + (for example, "Every 5 minutes") and an aggregate function from the list of functions. + +3. Click **Submit** to run the query and preview the results. + To see the raw query results, click the **{{< icon "toggle" >}} View Raw Data** toggle. + +#### Configure the check +1. Click **2. Configure Check** near the top of the window. +2. In the **Properties** column, configure the following: + + ##### Schedule Every + Select the interval to run the check (for example, "Every 5 minutes"). + This interval matches the aggregate function interval for the check query. + _Changing the interval here will update the aggregate function interval._ + + ##### Offset + Delay the execution of a task to account for any late data. + Offset queries do not change the queried time range. + + {{% note %}}Your offset must be shorter than your [check interval](#schedule-every). + {{% /note %}} + + ##### Tags + Add custom tags to the query output. + Each custom tag appends a new column to each row in the query output. + The column label is the tag key and the column value is the tag value. + + Use custom tags to associate additional metadata with the check. + Common metadata tags across different checks lets you easily group and organize checks. + You can also use custom tags in [notification rules](/influxdb/cloud/monitor-alert/notification-rules/create/). + +3. In the **Status Message Template** column, enter the status message template for the check. + Use [Flux string interpolation](/influxdb/cloud/reference/flux/language/string-interpolation/) + to populate the message with data from the query. + + {{% note %}} +#### Flux only interpolates string values +Flux currently interpolates only string values. +Use the [string() function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/string/) +to convert non-string values to strings. + +```js +count = 12 +"I currently have ${string(v: count)} cats." +``` + {{% /note %}} + + Check data is represented as a record, `r`. + Access specific column values using dot notation: `r.columnName`. + + Use data from the following columns: + + - columns included in the query output + - [custom tags](#tags) added to the query output + - `_check_id` + - `_check_name` + - `_level` + - `_source_measurement` + - `_type` + + ###### Example status message template + ``` + From ${r._check_name}: + ${r._field} is ${r._level}. + Its value is ${string(v: r.field_name)}. + ``` + + When a check generates a status, it stores the message in the `_message` column. + +4. Define check conditions that assign statuses to points. + Condition options depend on your check type. + + ##### Configure a threshold check + 1. In the **Thresholds** column, click the status name (CRIT, WARN, INFO, or OK) + to define conditions for that specific status. + 2. From the **When value** drop-down list, select a threshold: is above, is below, + is inside of, is outside of. + 3. Enter a value or values for the threshold. + You can also use the threshold sliders in the data visualization to define threshold values. + + ##### Configure a deadman check + 1. In the **Deadman** column, enter a duration for the deadman check in the **for** field. + For example, `90s`, `5m`, `2h30m`, etc. + 2. Use the **set status to** drop-down list to select a status to set on a dead series. + 3. In the **And stop checking after** field, enter the time to stop monitoring the series. + For example, `30m`, `2h`, `3h15m`, etc. + +5. Click the green **{{< icon "check" >}}** in the top right corner to save the check. + +## Clone a check +Create a new check by cloning an existing check. + +1. In the **Checks** column, hover over the check you want to clone. +2. Click the **{{< icon "clone" >}}** icon, then **Clone**. diff --git a/content/influxdb/cloud/monitor-alert/checks/delete.md b/content/influxdb/cloud/monitor-alert/checks/delete.md new file mode 100644 index 000000000..4715e1d49 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/checks/delete.md @@ -0,0 +1,34 @@ +--- +title: Delete checks +seotitle: Delete monitoring checks in InfluxDB +description: > + Delete checks in the InfluxDB UI. +menu: + influxdb_cloud: + parent: Manage checks +weight: 204 +related: + - /influxdb/cloud/monitor-alert/notification-rules/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +If you no longer need a check, use the InfluxDB user interface (UI) to delete it. + +{{% warn %}} +Deleting a check cannot be undone. +{{% /warn %}} + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Hover over the check you want to delete, click the **{{< icon "delete" >}}** + icon, and then **Delete**. + +After a check is deleted, all statuses generated by the check remain in the `_monitoring` +bucket until the retention period for the bucket expires. + +{{% note %}} +You can also [disable a check](/influxdb/cloud/monitor-alert/checks/update/#enable-or-disable-a-check) +without having to delete it. +{{% /note %}} diff --git a/content/influxdb/cloud/monitor-alert/checks/update.md b/content/influxdb/cloud/monitor-alert/checks/update.md new file mode 100644 index 000000000..68f8711a3 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/checks/update.md @@ -0,0 +1,60 @@ +--- +title: Update checks +seotitle: Update monitoring checks in InfluxDB +description: > + Update, rename, enable or disable checks in the InfluxDB UI. +menu: + influxdb_cloud: + parent: Manage checks +weight: 203 +related: + - /influxdb/cloud/monitor-alert/notification-rules/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +Update checks in the InfluxDB user interface (UI). +Common updates include: + +- [Update check queries and logic](#update-check-queries-and-logic) +- [Enable or disable a check](#enable-or-disable-a-check) +- [Rename a check](#rename-a-check) +- [Add or update a check description](#add-or-update-a-check-description) +- [Add a label to a check](#add-a-label-to-a-check) + +To update checks, select **Alerts** in the navigation menu on the left. + +{{< nav-icon "alerts" >}} + + +## Update check queries and logic +1. Click the name of the check you want to update. The check builder appears. +2. To edit the check query, click **1. Define Query** at the top of the check builder window. +3. To edit the check logic, click **2. Configure Check** at the top of the check builder window. + +_For details about using the check builder, see [Create checks](/influxdb/cloud/monitor-alert/checks/create/)._ + +## Enable or disable a check +Click the {{< icon "toggle" >}} toggle next to a check to enable or disable it. + +## Rename a check +1. Hover over the name of the check you want to update. +2. Click the **{{< icon "edit" >}}** icon that appears next to the check name. +2. Enter a new name and click out of the name field or press enter to save. + +_You can also rename a check in the [check builder](#update-check-queries-and-logic)._ + +## Add or update a check description +1. Hover over the check description you want to update. +2. Click the **{{< icon "edit" >}}** icon that appears next to the description. +2. Enter a new description and click out of the name field or press enter to save. + +## Add a label to a check +1. Click **Add a label** next to the check you want to add a label to. + The **Add Labels** box opens. +2. To add an existing label, select the label from the list. +3. To create and add a new label: + - In the search field, enter the name of the new label. The **Create Label** box opens. + - In the **Description** field, enter an optional description for the label. + - Select a color for the label. + - Click **Create Label**. +4. To remove a label, hover over the label under to a rule and click **{{< icon "x" >}}**. diff --git a/content/influxdb/cloud/monitor-alert/checks/view.md b/content/influxdb/cloud/monitor-alert/checks/view.md new file mode 100644 index 000000000..3ceaac464 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/checks/view.md @@ -0,0 +1,43 @@ +--- +title: View checks +seotitle: View monitoring checks in InfluxDB +description: > + View check details and statuses and notifications generated by checks in the InfluxDB UI. +menu: + influxdb_cloud: + parent: Manage checks +weight: 202 +related: + - /influxdb/cloud/monitor-alert/notification-rules/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +View check details and statuses and notifications generated by checks in the InfluxDB user interface (UI). + +- [View a list of all checks](#view-a-list-of-all-checks) +- [View check details](#view-check-details) +- [View statuses generated by a check](#view-statuses-generated-by-a-check) +- [View notifications triggered by a check](#view-notifications-triggered-by-a-check) + +To view checks, click **Alerts** in navigation menu on the left. + +{{< nav-icon "alerts" >}} + +## View a list of all checks +The **Checks** section of the Alerts landing page displays all existing checks. + +## View check details +Click the name of the check you want to view. +The check builder appears. +Here you can view the check query and logic. + +## View statuses generated by a check +1. Hover over the check and click the **{{< icon "view" >}}** icon. +2. Click **View History**. + The Statuses History page displays statuses generated by the selected check. + +## View notifications triggered by a check +1. Hover over the check, click the **{{< icon "view" >}}** + icon, then **View History**. +2. In the top left corner, click **Notifications**. + The Notifications History page displays notifications initiated by the selected check. diff --git a/content/influxdb/cloud/monitor-alert/custom-checks.md b/content/influxdb/cloud/monitor-alert/custom-checks.md new file mode 100644 index 000000000..4426ace55 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/custom-checks.md @@ -0,0 +1,102 @@ +--- +title: Create custom checks +seotitle: Custom checks +description: > + Create custom checks with a Flux task. +menu: + influxdb_cloud: + parent: Monitor & alert +weight: 201 +v2.0/tags: [alerts, checks, tasks, Flux] +--- + +In the UI, you can create two kinds of [checks](/influxdb/cloud/reference/glossary/#check): +[`threshold`](/influxdb/cloud/monitor-alert/checks/create/#threshold-check) and +[`deadman`](/influxdb/cloud/monitor-alert/checks/create/#deadman-check). + +Using a Flux task, you can create a custom check that provides a couple advantages: + +- Customize and transform the data you would like to use for the check. +- Set up custom criteria for your alert (other than `threshold` and `deadman`). + +## Create a task + +1. In the InfluxDB UI, select **Tasks** in the navigation menu on the left. + + {{< nav-icon "tasks" >}} + +2. Click **{{< icon "plus" >}} Create Task**, and then select **New Task**. +3. In the **Name** field, enter a descriptive name, + and then enter how often to run the task in the **Every** field (for example, `10m`). + For more detail, such as using cron syntax or including an offset, see [Task configuration options](/influxdb/cloud/process-data/task-options/). +4. Enter the Flux script for your custom check, including the [`monitor.check`](/influxdb/cloud/reference/flux/stdlib/monitor/check/) function. + +{{% note %}} +Use the the API endpoint `/checks/{checkID}/query` to see the Flux code for a check built in the UI. +This can be useful for constructing custom checks. +{{% /note %}} + +### Example: Monitor failed tasks + +The script below is fairly complex, and can be used as a framework for similar tasks. +It does the following: + +- Import the necessary `influxdata/influxdb/monitor` package, and other packages for data processing. +- Query the `_tasks` bucket to retrieve all statuses generated by your check. +- Set the `_level` to alert on, for example, `crit`, `warn`, `info`, or `ok`. +- Create a `check` object that specifies an ID, name, and type for the check. +- Define the `ok` and `crit` statuses. +- Execute the `monitor` function on the `check` using the `task_data`. + +#### Example alert task script + +```js +import "strings" +import "regexp" +import "influxdata/influxdb/monitor" +import "influxdata/influxdb/v1" + +option task = {name: "Failed Tasks Check", every: 1h, offset: 4m} + +task_data = from(bucket: "_tasks") + |> range(start: -task.every) + |> filter(fn: (r) => + (r["_measurement"] == "runs")) + |> filter(fn: (r) => + (r["_field"] == "logs")) + |> map(fn: (r) => ({ r with name: strings.split(v: regexp.findString(r: /option task = \{([^\}]+)/, v: r._value), t: "\\\\\\\"")[1] })) + |> drop(columns: ["_value", "_start", "_stop"]) + |> group(columns: ["name", "taskID", "status", "_measurement"]) + |> map(fn: (r) => + ({r with _value: if r.status == "failed" then 1 else 0})) + |> last() +check = { + _check_id: "0000000000000001", // 16 characters, alphanumeric + _check_name: "Failed Tasks Check", // string + _type: "custom", // can also use "threashold" or "deadman" + tags: {}, +} +ok = (r) => + (r["logs"] == 0) +crit = (r) => + (r["logs"] == 1) +messageFn = (r) => + ("The task: ${r.taskID} - ${r.name} has a status of ${r.status}") + +task_data + |> v1["fieldsAsCols"]() + |> monitor["check"]( + data: check, + messageFn: messageFn, + ok: ok, + crit: crit, + ) +``` + +{{% note %}} +Creating a custom check does not send a notification email. +For information on how to create notification emails, see +[Create notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/create), +[Create notification rules](/influxdb/cloud/monitor-alert/notification-rules/create), +and [Send alert email](/influxdb/cloud/monitor-alert/send-email/) +{{% /note %}} diff --git a/content/influxdb/cloud/monitor-alert/notification-endpoints/_index.md b/content/influxdb/cloud/monitor-alert/notification-endpoints/_index.md new file mode 100644 index 000000000..f8b3b2a0d --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-endpoints/_index.md @@ -0,0 +1,20 @@ +--- +title: Manage notification endpoints +list_title: Manage notification endpoints +description: > + Create, read, update, and delete endpoints in the InfluxDB UI. +influxdb/cloud/tags: [monitor, endpoints, notifications, alert] +menu: + influxdb_cloud: + parent: Monitor & alert +weight: 102 +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-rules/ +--- + +Notification endpoints store information to connect to a third party service. +If you're using the Free Plan, create a Slack endpoint. +If you're using the Usage-based Plan, create a connection to a HTTP, Slack, or PagerDuty endpoint. + +{{< children >}} diff --git a/content/influxdb/cloud/monitor-alert/notification-endpoints/create.md b/content/influxdb/cloud/monitor-alert/notification-endpoints/create.md new file mode 100644 index 000000000..9a4675a05 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-endpoints/create.md @@ -0,0 +1,45 @@ +--- +title: Create notification endpoints +description: > + Create notification endpoints to send alerts on your time series data. +menu: + influxdb_cloud: + name: Create endpoints + parent: Manage notification endpoints +weight: 201 +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-rules/ +--- + +To send notifications about changes in your data, start by creating a notification endpoint to a third party service. After creating notification endpoints, [create notification rules](/influxdb/cloud/monitor-alert/notification-rules/create) to send alerts to third party services on [check statuses](/influxdb/cloud/monitor-alert/checks/create). + +## Create a notification endpoint in the UI + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click **{{< icon "plus" >}} Create**. +4. From the **Destination** drop-down list, select a destination endpoint to send notifications. + The following endpoints are available for the InfluxDB Cloud Free Plan and Usage-based Plan: + + | Endpoint | Free Plan | Usage-based Plan | + |:-------- |:-------------------: |:----------------------------:| + | **Slack** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | + | **PagerDuty** | | **{{< icon "check" >}}** | + | **HTTP** | | **{{< icon "check" >}}** | + +5. In the **Name** and **Description** fields, enter a name and description for the endpoint. +6. Enter enter information to connect to the endpoint: + + - For HTTP, enter the **URL** to send the notification. Select the **auth method** to use: **None** for no authentication. To authenticate with a username and password, select **Basic** and then enter credentials in the **Username** and **Password** fields. To authenticate with a token, select **Bearer**, and then enter the authentication token in the **Token** field. + + - For Slack, create an [Incoming WebHook](https://api.slack.com/incoming-webhooks#posting_with_webhooks) in Slack, and then enter your webHook URL in the **Slack Incoming WebHook URL** field. + + - For PagerDuty: + - [Create a new service](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-new-service), [add an integration for your service](https://support.pagerduty.com/docs/services-and-integrations#section-add-integrations-to-an-existing-service), and then enter the PagerDuty integration key for your new service in the **Routing Key** field. + - The **Client URL** provides a useful link in your PagerDuty notification. Enter any URL that you'd like to use to investigate issues. This URL is sent as the `client_url` property in the PagerDuty trigger event. By default, the **Client URL** is set to your Monitoring & Alerting History page, and the following included in the PagerDuty trigger event: `"client_url": "https://us-west-2-1.aws.cloud2.influxdata.net/orgs//alert-history”` + +6. Click **Create Notification Endpoint**. diff --git a/content/influxdb/cloud/monitor-alert/notification-endpoints/delete.md b/content/influxdb/cloud/monitor-alert/notification-endpoints/delete.md new file mode 100644 index 000000000..1b9ca92aa --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-endpoints/delete.md @@ -0,0 +1,26 @@ +--- +title: Delete notification endpoints +description: > + Delete a notification endpoint in the InfluxDB UI. +menu: + influxdb_cloud: + name: Delete endpoints + parent: Manage notification endpoints +weight: 204 +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-rules/ +--- + +If notifications are no longer sent to an endpoint, complete the steps below to delete the endpoint, and then [update notification rules](/influxdb/cloud/monitor-alert/notification-rules/update) with a new notification endpoint as needed. + +## Delete a notification endpoint in the UI + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. + find the rule you want to delete. +3. Hover over the endpoint you want to delete and click the **{{< icon "trash" >}}** icon. +4. Click **Delete** to confirm. diff --git a/content/influxdb/cloud/monitor-alert/notification-endpoints/update.md b/content/influxdb/cloud/monitor-alert/notification-endpoints/update.md new file mode 100644 index 000000000..71b562507 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-endpoints/update.md @@ -0,0 +1,66 @@ +--- +title: Update notification endpoints +description: > + Update notification endpoints in the InfluxDB UI. +menu: + influxdb_cloud: + name: Update endpoints + parent: Manage notification endpoints +weight: 203 +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-rules/ +--- + +To update the notification endpoint details, complete the procedures below as needed. To update the notification endpoint selected for a notification rule, see [update notification rules](/influxdb/cloud/monitor-alert/notification-rules/update/). + +## Add a label to notification endpoint + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click **{{< icon "add-label" >}} Add a label** next to the endpoint you want to add a label to. + The **Add Labels** box opens. +4. To add an existing label, select the label from the list. +5. To create and add a new label: + + - In the search field, enter the name of the new label. The **Create Label** box opens. + - In the **Description** field, enter an optional description for the label. + - Select a color for the label. + - Click **Create Label**. + +6. To remove a label, hover over the label under an endpoint and click X. + + +## Disable notification endpoint + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click the {{< icon "toggle" >}} toggle to disable the notification endpoint. + +## Update the name or description for notification endpoint + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Hover over the name or description of the endpoint and click the pencil icon + (**{{< icon "edit" >}}**) to edit the field. +4. Click outside of the field to save your changes. + +## Change endpoint details + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click the endpoint to update. +4. Update details as needed, and then click **Edit Notification Endpoint**. + For details about each field, see [Create notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/create/). diff --git a/content/influxdb/cloud/monitor-alert/notification-endpoints/view.md b/content/influxdb/cloud/monitor-alert/notification-endpoints/view.md new file mode 100644 index 000000000..9196bbeed --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-endpoints/view.md @@ -0,0 +1,51 @@ +--- +title: View notification endpoint history +seotitle: View notification endpoint details and history +description: > + View notification endpoint details and history in the InfluxDB UI. +menu: + influxdb_cloud: + name: View endpoint history + parent: Manage notification endpoints +weight: 202 +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-rules/ +--- + +View notification endpoint details and history in the InfluxDB user interface (UI). + +- [View notification endpoints](#view-notification-endpoints) +- [View notification endpoint details](#view-notification-endpoint-details) +- [View history notification endpoint history](#view-notification-endpoint-history), including statues and notifications sent to the endpoint + +## View notification endpoints + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. + +## View notification endpoint details + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Click the name of the notification endpoint you want to view. +4. View the notification endpoint destination, name, and information to connect to the endpoint. + +## View notification endpoint history + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Endpoints** near to top of the page. +3. Hover over the notification endpoint, click the **{{< icon "view" >}}** icon, then **View History**. + The Check Statuses History page displays: + + - Statuses generated for the selected notification endpoint + - Notifications sent to the selected notification endpoint diff --git a/content/influxdb/cloud/monitor-alert/notification-rules/_index.md b/content/influxdb/cloud/monitor-alert/notification-rules/_index.md new file mode 100644 index 000000000..ea0f16dcd --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-rules/_index.md @@ -0,0 +1,17 @@ +--- +title: Manage notification rules +description: > + Manage notification rules in InfluxDB. +weight: 103 +influxdb/cloud/tags: [monitor, notifications, alert] +menu: + influxdb_cloud: + parent: Monitor & alert +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +The following articles provide information on managing your notification rules: + +{{< children >}} diff --git a/content/influxdb/cloud/monitor-alert/notification-rules/create.md b/content/influxdb/cloud/monitor-alert/notification-rules/create.md new file mode 100644 index 000000000..156c9f30b --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-rules/create.md @@ -0,0 +1,44 @@ +--- +title: Create notification rules +description: > + Create notification rules to send alerts on your time series data. +weight: 201 +menu: + influxdb_cloud: + parent: Manage notification rules +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +Once you've set up checks and notification endpoints, create notification rules to alert you. +_For details, see [Manage checks](/influxdb/cloud/monitor-alert/checks/) and +[Manage notification endpoints](/influxdb/cloud/monitor-alert/notification-endpoints/)._ + +## Create a new notification rule in the UI + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Click **{{< icon "plus" >}} Create**. +4. Complete the **About** section: + 1. In the **Name** field, enter a name for the notification rule. + 2. In the **Schedule Every** field, enter how frequently the rule should run. + 3. In the **Offset** field, enter an offset time. For example,if a task runs on the hour, a 10m offset delays the task to 10 minutes after the hour. Time ranges defined in the task are relative to the specified execution time. +5. In the **Conditions** section, build a condition using a combination of status and tag keys. + - Next to **When status is equal to**, select a status from the drop-down field. + - Next to **AND When**, enter one or more tag key-value pairs to filter by. +6. In the **Message** section, select an endpoint to notify. +7. Click **Create Notification Rule**. + +## Clone an existing notification rule in the UI + +1. 1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Hover over the rule you want to clone and click the **{{< icon "clone" >}}** icon and select **Clone**. + The cloned rule appears. diff --git a/content/influxdb/cloud/monitor-alert/notification-rules/delete.md b/content/influxdb/cloud/monitor-alert/notification-rules/delete.md new file mode 100644 index 000000000..163b137f1 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-rules/delete.md @@ -0,0 +1,22 @@ +--- +title: Delete notification rules +description: > + If you no longer need to receive an alert, delete the associated notification rule. +weight: 204 +menu: + influxdb_cloud: + parent: Manage notification rules +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +## Delete a notification rule in the UI + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Hover over the rule you want to delete and click the **{{< icon "trash" >}}** icon. +4. Click **Delete** to confirm. diff --git a/content/influxdb/cloud/monitor-alert/notification-rules/update.md b/content/influxdb/cloud/monitor-alert/notification-rules/update.md new file mode 100644 index 000000000..da322963b --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-rules/update.md @@ -0,0 +1,50 @@ +--- +title: Update notification rules +description: > + Update notification rules to update the notification message or change the schedule or conditions. +weight: 203 +menu: + influxdb_cloud: + parent: Manage notification rules +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +## Add a label to notification rules + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Click **{{< icon "add-label" >}} Add a label** next to the rule you want to add a label to. + The **Add Labels** box opens. +4. To add an existing label, select the label from the list. +5. To create and add a new label: + - In the search field, enter the name of the new label. The **Create Label** box opens. + - In the **Description** field, enter an optional description for the label. + - Select a color for the label. + - Click **Create Label**. +6. To remove a label, hover over the label under to a rule and click **{{< icon "x" >}}**. + + +## Disable notification rules + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Click the {{< icon "toggle" >}} toggle to disable the notification rule. + +## Update the name or description for notification rules + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. +3. Hover over the name or description of a rule and click the pencil icon + (**{{< icon "edit" >}}**) to edit the field. +4. Click outside of the field to save your changes. diff --git a/content/influxdb/cloud/monitor-alert/notification-rules/view.md b/content/influxdb/cloud/monitor-alert/notification-rules/view.md new file mode 100644 index 000000000..0dcea29ce --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/notification-rules/view.md @@ -0,0 +1,45 @@ +--- +title: View notification rules +description: > + Update notification rules to update the notification message or change the schedule or conditions. +weight: 202 +menu: + influxdb_cloud: + parent: Manage notification rules +related: + - /influxdb/cloud/monitor-alert/checks/ + - /influxdb/cloud/monitor-alert/notification-endpoints/ +--- + +View notification rule details and statuses and notifications generated by notification rules in the InfluxDB user interface (UI). + +- [View a list of all notification rules](#view-a-list-of-all-notification-rules) +- [View notification rule details](#view-notification-rule-details) +- [View statuses generated by a check](#view-statuses-generated-by-a-notification-rule) +- [View notifications triggered by a notification rule](#view-notifications-triggered-by-a-notification-rule) + +**To view notification rules:** + +1. In the navigation menu on the left, select **Alerts**. + + {{< nav-icon "alerts" >}} + +2. Select **Notification Rules** near to top of the page. + +## View a list of all notification rules +The **Notification Rules** section of the Alerts landing page displays all existing checks. + +## View notification rule details +Click the name of the check you want to view. +The check builder appears. +Here you can view the check query and logic. + +## View statuses generated by a notification rule +Hover over the check, click the **{{< icon "view" >}}** icon, and then **View History**. +The Statuses History page displays statuses generated by the selected check. + +## View notifications triggered by a notification rule +1. Hover over the notification rule, click the **{{< icon "view" >}}** + icon, and then **View History**. +2. In the top left corner, click **Notifications**. + The Notifications History page displays notifications initiated by the selected notification rule. diff --git a/content/influxdb/cloud/monitor-alert/send-email.md b/content/influxdb/cloud/monitor-alert/send-email.md new file mode 100644 index 000000000..b625706a9 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/send-email.md @@ -0,0 +1,235 @@ +--- +title: Send alert email +description: > + Send an alert email. +menu: + influxdb_cloud: + parent: Monitor & alert +weight: 104 +influxdb/cloud/tags: [alert, email, notifications, check] +related: + - /influxdb/cloud/monitor-alert/checks/ +--- + +Send an alert email using a third party service, such as [SendGrid](https://sendgrid.com/), [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/), [Mailjet](https://www.mailjet.com/), or [Mailgun](https://www.mailgun.com/). To send an alert email, complete the following steps: + +1. [Create a check](/influxdb/cloud/monitor-alert/checks/create/#create-a-check-in-the-influxdb-ui) to identify the data to monitor and the status to alert on. +2. Set up your preferred email service (sign up, retrieve API credentials, and send test email): + - **SendGrid**: See [Getting Started With the SendGrid API](https://sendgrid.com/docs/API_Reference/api_getting_started.html) + - **AWS Simple Email Service (SES)**: See [Using the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email.html). Your AWS SES request, including the `url` (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). + - **Mailjet**: See [Getting Started with Mailjet](https://dev.mailjet.com/email/guides/getting-started/) + - **Mailgun**: See [Mailgun Signup](https://signup.mailgun.com/new/signup) +3. [Create an alert email task](#create-an-alert-email-task) to call your email service and send an alert email. + + {{% note %}} + In the procedure below, we use the **Task** page in the InfluxDB UI (user interface) to create a task. Explore other ways to [create a task](/influxdb/cloud/process-data/manage-tasks/create-task/). + {{% /note %}} + +### Create an alert email task + +1. In the InfluxDB UI, select **Tasks** in the navigation menu on the left. + + {{< nav-icon "tasks" >}} + +2. Click **{{< icon "plus" >}} Create Task**, and then select **New Task**. +3. In the **Name** field, enter a descriptive name, for example, **Send alert email**, and then enter how often to run the task in the **Every** field, for example, `10m`. For more detail, such as using cron syntax or including an offset, see [Task configuration options](/influxdb/cloud/process-data/task-options/). + +4. In the right panel, enter the following detail in your **task script** (see [examples below](#examples)): + - Import the [Flux HTTP package](/influxdb/cloud/reference/flux/stdlib/http/). + - (Optional) Store your API key as a secret for reuse. First, [add your API key as a secret](/influxdb/cloud/security/secrets/manage-secrets/add/), and then import the [Flux InfluxDB Secrets package](/influxdb/cloud/reference/flux/stdlib/secrets/). + - Query the `statuses` measurement in the `_monitoring` bucket to retrieve all statuses generated by your check. + - Set the time range to monitor; use the same interval that the task is scheduled to run. For example, `range (start: -task.every)`. + - Set the `_level` to alert on, for example, `crit`, `warn`, `info`, or `ok`. + - Use the `map()` function to evaluate the criteria to send an alert using `http.post()`. + - Specify your email service `url` (endpoint), include applicable request `headers`, and verify your request `data` format follows the format specified for your email service. + +#### Examples + +{{< tabs-wrapper >}} +{{% tabs %}} +[SendGrid](#) +[AWS SES](#) +[Mailjet](#) +[Mailgun](#) +{{% /tabs %}} + + +{{% tab-content %}} + +The example below uses the SendGrid API to send an alert email when more than 3 critical statuses occur since the previous task run. + +```js +import "http" + +// Import the Secrets package if you store your API key as a secret. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secret if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +SENDGRID_APIKEY = secrets.get(key: "SENDGRID_APIKEY") + +numberOfCrits = from(bucket: "_monitoring") + |> range(start: -task.every) + |> filter(fn: (r) => r.measurement == "statuses" and r.level == "crit") + |> count() + +numberOfCrits + |> map(fn: (r) => (if r._value > 3 then { + r with _value: http.post( + url: "https://api.sendgrid.com/v3/mail/send", + headers: {"Content-Type": "application/json", Authorization: "Bearer ${SENDGRID_APIKEY}"}, + data: bytes(v: "{ + \"personalizations\": [{ + \"to\": [{ + \"email\": \”jane.doe@example.com\"}], + \"subject\": \”InfluxData critical alert\" + }], + \"from\": {\"email\": \"john.doe@example.com\"}, + \"content\": [{ + \"type\": \"text/plain\", + \"value\": \”Example alert text\" + }] + }\""))} else {r with _value: 0})) +``` + +{{% /tab-content %}} + + +{{% tab-content %}} + +The example below uses the AWS SES API v2 to send an alert email when more than 3 critical statuses occur since the last task run. + +{{% note %}} +Your AWS SES request, including the `url` (endpoint), authentication, and the structure of the request may vary. For more information, see [Amazon SES API requests](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-requests.html) and [Authenticating requests to the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-ses-api-authentication.html). We recommend signing your AWS API requests using the [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html). +{{% /note %}} + +```js +import "http" + +// Import the Secrets package if you store your API credentials as secrets. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secrets if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +AWS_AUTH_ALGORITHM = secrets.get(key: "AWS_AUTH_ALGORITHM") +AWS_CREDENTIAL = secrets.get(key: "AWS_CREDENTIAL") +AWS_SIGNED_HEADERS = secrets.get(key: "AWS_SIGNED_HEADERS") +AWS_CALCULATED_SIGNATURE = secrets.get(key: "AWS_CALCULATED_SIGNATURE") + +numberOfCrits = from(bucket: "_monitoring") + |> range(start: -task.every) + |> filter(fn: (r) => (r.measurement == "statuses" and r._level == "crit") + |> count() + +numberOfCrits + |> map(fn: (r) => (if r._value > 3 then { + r with _value: http.post( + url: "https://email.your-aws-region.amazonaws.com/sendemail/v2/email/outbound-emails", + headers: {"Content-Type": "application/json", Authorization: "Bearer ${AWS_AUTH_ALGORITHM}${AWS_CREDENTIAL}${AWS_SIGNED_HEADERS}${AWS_CALCULATED_SIGNATURE}"}, + data: bytes(v: "{ + \"personalizations\": [{ + \"to\": [{ + \"email\": \”jane.doe@example.com\"}], + \"subject\": \”InfluxData critical alert\" + }], + \"from\": {\"email\": \"john.doe@example.com\"}, + \"content\": [{ + \"type\": \"text/plain\", + \"value\": \”Example alert text\" + }] + }\""))} else {r with _value: 0})) +``` + +For details on the request syntax, see [SendEmail API v2 reference](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html). + +{{% /tab-content %}} + + +{{% tab-content %}} + +The example below uses the Mailjet Send API to send an alert email when more than 3 critical statuses occur since the last task run. + +{{% note %}} +To view your Mailjet API credentials, sign in to Mailjet and open the [API Key Management page](https://app.mailjet.com/account/api_keys). +{{% /note %}} + +```js +import "http" + +// Import the Secrets package if you store your API keys as secrets. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secrets if applicable. Otherwise, skip this line +// and add the API keys as Basic credentials in the Authorization header. +MAILJET_APIKEY = secrets.get(key: "MAILJET_APIKEY") +MAILJET_SECRET_APIKEY = secrets.get(key: "MAILJET_SECRET_APIKEY") + +numberOfCrits = from(bucket: "_monitoring") + |> range(start: -task.every) + |> filter(fn: (r) => (r.measurement == "statuses" and "r.level" == "crit") + |> count() + +numberOfCrits + |> map(fn: (r) => (if r._value > 3 then { + r with _value: http.post( + url: "https://api.mailjet.com/v3.1/send", + headers: {"Content-type": "application/json", Authorization: "Basic ${MAILJET_APIKEY}:${MAILJET_SECRET_APIKEY}"}, + data: bytes(v: "{ + \"Messages\": [{ + \"From\": {\"Email\": \”jane.doe@example.com\"}, + \"To\": [{\"Email\": \"john.doe@example.com\"]}, + \"Subject\": \”InfluxData critical alert\", + \"TextPart\": \”Example alert text\" + \"HTMLPart\": `"

Hello, to review critical alerts, review your Critical Alert Dashboard

}]}' + }\""))} else {r with _value: 0})) +``` + +{{% /tab-content %}} + + + +{{% tab-content %}} + +The example below uses the Mailgun API to send an alert email when more than 3 critical statuses occur since the last task run. + +{{% note %}} +To view your Mailgun API keys, sign in to Mailjet and open [Account Security - API security](https://app.mailgun.com/app/account/security/api_keys). Mailgun requires that a domain be specified via Mailgun. A domain is automatically created for you when you first set up your account. You must include this domain in your `url` endpoint (for example, `https://api.mailgun.net/v3/YOUR_DOMAIN` or `https://api.eu.mailgun.net/v3/YOUR_DOMAIN`. If you're using a free version of Mailgun, you can set up a maximum of five authorized recipients (to receive email alerts) for your domain. To view your Mailgun domains, sign in to Mailgun and view the [Domains page](https://app.mailgun.com/app/sending/domains). +{{% /note %}} + +```js +import "http" + +// Import the Secrets package if you store your API key as a secret. +// For detail on how to do this, see Step 4 above. +import "influxdata/influxdb/secrets" + +// Retrieve the secret if applicable. Otherwise, skip this line +// and add the API key as the Bearer token in the Authorization header. +MAILGUN_APIKEY = secrets.get(key: "MAILGUN_APIKEY") + +numberOfCrits = from(bucket: "_monitoring") + |> range(start: -task.every) + |> filter(fn: (r) => (r["_measurement"] == "statuses")) + |> filter(fn: (r) => (r["_level"] == "crit")) + |> count() + +numberOfCrits + |> map(fn: (r) => + (if r._value > 1 then {r with _value: http.post( + url: "https://api.mailgun.net/v3/YOUR_DOMAIN/messages", + headers: {"Content-type": "application/json", Authorization: "Basic api:${MAILGUN_APIKEY}"}, + data: bytes(v: "{ + \"from\": \"Username \", + \"to\"=\"YOU@YOUR_DOMAIN_NAME\", + \"to\"=\"email@example.com\", + \"subject\"=\"Critical InfluxData alert\", + \"text\"=\"You have critical alerts to review\" + }\""))} else {r with _value: 0})) +``` + +{{% /tab-content %}} + +{{< /tabs-wrapper >}} diff --git a/content/influxdb/cloud/monitor-alert/templates/_index.md b/content/influxdb/cloud/monitor-alert/templates/_index.md new file mode 100644 index 000000000..bee05930b --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/templates/_index.md @@ -0,0 +1,14 @@ +--- +title: Monitor with templates +description: > + Use community templates to monitor data in many supported environments. Monitor infrastructure, networking, IoT, software, security, TICK stack, and more. +menu: + influxdb_cloud: + parent: Monitor & alert +weight: 104 +influxdb/cloud/tags: [monitor, templates] +--- + +Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor data in supported environments. + +{{< children >}} diff --git a/content/influxdb/cloud/monitor-alert/templates/infrastructure/_index.md b/content/influxdb/cloud/monitor-alert/templates/infrastructure/_index.md new file mode 100644 index 000000000..6c5ea476b --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/templates/infrastructure/_index.md @@ -0,0 +1,14 @@ +--- +title: Monitor infrastructure +description: > + Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your infrastructure. +menu: + influxdb_cloud: + parent: Monitor with templates +weight: 104 +influxdb/cloud/tags: [monitor, templates, infrastructure] +--- + +Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your infrastructure. + +{{< children >}} diff --git a/content/influxdb/cloud/monitor-alert/templates/infrastructure/aws.md b/content/influxdb/cloud/monitor-alert/templates/infrastructure/aws.md new file mode 100644 index 000000000..840faf69c --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/templates/infrastructure/aws.md @@ -0,0 +1,57 @@ +--- +title: Monitor Amazon Web Services (AWS) +description: > + Use the AWS CloudWatch Monitoring template to monitor data from Amazon Web Services (AWS), Amazon Elastic Compute Cloud (EC2), and Amazon Elastic Load Balancing (ELB) with the AWS CloudWatch Service. +menu: + influxdb_cloud: + parent: Monitor infrastructure + name: AWS CloudWatch +weight: 201 +--- + +Use the [AWS CloudWatch Monitoring template](https://github.com/influxdata/community-templates/tree/master/aws_cloudwatch) to monitor data from [Amazon Web Services (AWS)](https://aws.amazon.com/), [Amazon Elastic Compute Cloud (EC2)](https://aws.amazon.com/ec2/), and [Amazon Elastic Load Balancing (ELB)](https://aws.amazon.com/elasticloadbalancing/) with the [AWS CloudWatch Service](https://aws.amazon.com/cloudwatch/). + +The AWS CloudWatch Monitoring template includes the following: + +- two [dashboards](/influxdb/cloud/reference/glossary/#dashboard): + - **AWS CloudWatch NLB (Network Load Balancers) Monitoring**: Displays data from the `cloudwatch_aws_network_elb measurement` + - **AWS CloudWatch Instance Monitoring**: Displays data from the `cloudwatch_aws_ec2` measurement +- two [buckets](/influxdb/cloud/reference/glossary/#bucket): `kubernetes` and `cloudwatch` +- two labels: `inputs.cloudwatch`, `AWS` +- one variable: `v.bucket` +- one [Telegraf configuration](/influxdb/cloud/telegraf-configs/): [AWS CloudWatch input plugin](/{{< latest "telegraf" >}}/plugins//#cloudwatch) + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/aws_cloudwatch/aws_cloudwatch.yml + ``` + For more information, see [influx apply](/influxdb/cloud/reference/cli/influx/apply/). +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the CloudWatch API and [InfluxDB v2 API](/influxdb/cloud/reference/api/). +3. In your Telegraf configuration file (`telegraf.conf`), find the following example `influxdb_v2` output plugins, and then **replace** the `urls` to specify the servers to monitor: + + ```sh + ## k8s + [[outputs.influxdb_v2]] + urls = ["http://influxdb.monitoring:9999"] + organization = "InfluxData" + bucket = "kubernetes" + token = "secret-token" + + ## cloudv2 sample + [[outputs.influxdb_v2]] + urls = ["$INFLUX_HOST"] + token = "$INFLUX_TOKEN" + organization = "$INFLUX_ORG" + bucket = “cloudwatch" + ``` +4. [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf). + +## View the incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open your AWS dashboards, and then set the `v.bucket` variable to specify the bucket to query data from (`kubernetes` or `cloudwatch`). diff --git a/content/influxdb/cloud/monitor-alert/templates/infrastructure/docker.md b/content/influxdb/cloud/monitor-alert/templates/infrastructure/docker.md new file mode 100644 index 000000000..98be54b9f --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/templates/infrastructure/docker.md @@ -0,0 +1,54 @@ +--- +title: Monitor Docker +description: > + Use the [Docker Monitoring template](https://github.com/influxdata/community-templates/tree/master/docker) to monitor your Docker containers. +menu: + influxdb_cloud: + parent: Monitor infrastructure + name: Docker +weight: 202 +--- + +Use the [Docker Monitoring template](https://github.com/influxdata/community-templates/tree/master/docker) to monitor your Docker containers. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). +This template uses the [Docker input plugin](/{{< latest "telegraf" >}}/plugins//#docker) to collect metrics stored in InfluxDB and display these metrics in a dashboard. + +The Docker Monitoring template includes the following: + +- one [dashboard](/influxdb/cloud/reference/glossary/#dashboard): **Docker** +- one [bucket](/influxdb/cloud/reference/glossary/#bucket): `docker, 7d retention` +- labels: Docker input plugin labels +- one [Telegraf configuration](/influxdb/cloud/telegraf-configs/): Docker input plugin +- one variable: `bucket` +- four [checks](/influxdb/cloud/reference/glossary/#check): `Container cpu`, `mem`, `disk`, `non-zero exit` +- one [notification endpoint](/influxdb/cloud/reference/glossary/#notification-endpoint): `Http Post` +- one [notification rule](/influxdb/cloud/reference/glossary/#notification-rule): `Crit Alert` + +For more information about how checks, notification endpoints, and notifications rules work together, see [monitor data and send alerts](/influxdb/cloud/monitor-alert/). + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/docker/docker.yml + ``` + For more information, see [influx apply](/influxdb/cloud/reference/cli/influx/apply/). + + > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/cloud/reference/cli/influx/config/). + +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the Docker containers and [InfluxDB v2 API](/influxdb/cloud/reference/api/). +3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/cloud/telegraf-configs/), do the following: + - Depending on how you run Docker, you may need to customize the [Docker input plugin](/{{< latest "telegraf" >}}/plugins//#docker) configuration, for example, you may need to specify the `endpoint` value. + - Set the following environment variables: + - INFLUX_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/cloud/security/tokens/view-tokens/). + - INFLUX_ORG: Name of your organization. See how to [view your organization](/influxdb/cloud/organizations/view-orgs/). + - INFLUX_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. + +4. [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf). + +## View incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open the **Docker** dashboard to start monitoring. diff --git a/content/influxdb/cloud/monitor-alert/templates/infrastructure/vshpere.md b/content/influxdb/cloud/monitor-alert/templates/infrastructure/vshpere.md new file mode 100644 index 000000000..8b00022fd --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/templates/infrastructure/vshpere.md @@ -0,0 +1,55 @@ +--- +title: Monitor vSphere +description: > + Use the [vSphere Dashboard for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/vsphere) to monitor your vSphere host. +menu: + influxdb_cloud: + parent: Monitor infrastructure + name: vSphere +weight: 206 +--- + +Use the [vSphere Dashboard for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/vsphere) to monitor your vSphere host. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). +This template uses the [Docker input plugin](/{{< latest "telegraf" >}}/plugins//#docker) to collect metrics stored in InfluxDB and display these metrics in a dashboard. + +The Docker Monitoring template includes the following: + +- one [dashboard](/influxdb/cloud/reference/glossary/#dashboard): **vsphere** +- one [bucket](/influxdb/cloud/reference/glossary/#bucket): `vsphere` +- label: vsphere +- one [Telegraf configuration](/influxdb/cloud/telegraf-configs/): InfluxDB v2 output plugin, vSphere input plugin +- one variable: `bucket` + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/vsphere/vsphere.yml + ``` + For more information, see [influx apply](/influxdb/cloud/reference/cli/influx/apply/). + + > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/cloud/reference/cli/influx/config/). + +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the vSphere host and [InfluxDB v2 API](/influxdb/cloud/reference/api/). +3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/cloud/telegraf-configs/), do the following: + - Set the following environment variables: + - INFLUX_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/cloud/security/tokens/view-tokens/). + - INFLUX_ORG: Name of your organization. See how to [view your organization](/influxdb/cloud/organizations/view-orgs/). + - INFLUX_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. + - INFLUX_BUCKET: Bucket to store data in. To use the bucket included, you must export the variable: `export INFLUX_BUCKET=vsphere` +4. - Set the host address to the vSphere and provide the `username` and `password` as variables: + ```sh + vcenters = [ "https://$VSPHERE_HOST/sdk" ] + username = "$vsphere-user" + password = "$vsphere-password" + ``` + +4. [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf). + +## View incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open the **vsphere** dashboard to start monitoring. diff --git a/content/influxdb/cloud/monitor-alert/templates/infrastructure/windows.md b/content/influxdb/cloud/monitor-alert/templates/infrastructure/windows.md new file mode 100644 index 000000000..457e57101 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/templates/infrastructure/windows.md @@ -0,0 +1,52 @@ +--- +title: Monitor Windows +description: > + Use the [Windows System Monitoring template](https://github.com/influxdata/community-templates/tree/master/windows_system) to monitor your Windows system. +menu: + influxdb_cloud: + parent: Monitor infrastructure + name: Windows +weight: 207 +--- + +Use the [Windows System Monitoring template](https://github.com/influxdata/community-templates/tree/master/windows_system) to monitor your Windows system. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). + +The Windows System Monitoring template includes the following: + +- one [dashboard](/influxdb/cloud/reference/glossary/#dashboard): **Windows System** +- one [bucket](/influxdb/cloud/reference/glossary/#bucket): `telegraf`, 7d retention +- label: `Windows System Template`, Telegraf plugin labels: `outputs.influxdb_v2` +- one [Telegraf configuration](/influxdb/cloud/telegraf-configs/): InfluxDB v2 output plugin, Windows Performance Counters input plugin +- two variables: `bucket`, `windows_host` + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/windows_system/windows_system.yml + ``` + For more information, see [influx apply](/influxdb/cloud/reference/cli/influx/apply/). + + > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/cloud/reference/cli/influx/config/). + +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the Windows system and [InfluxDB v2 API](/influxdb/cloud/reference/api/). +3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/cloud/telegraf-configs/), do the following: + - Set the following environment variables: + - INFLUX_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `telegraf` bucket. See how to [view tokens](/influxdb/cloud/security/tokens/view-tokens/). + - INFLUX_ORG: Name of your organization. See how to [view your organization](/influxdb/cloud/organizations/view-orgs/). + - INFLUX_URL: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. + +4. [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf). +5. To monitor multiple Windows systems, repeat steps 1-4 for each system. + +## View incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open the **Windows System** dashboard to start monitoring. + + {{% note %}} + If you're monitoring multiple Windows machines, switch between them using the `windows_host` filter at the top of the dashboard. + {{% /note %}} diff --git a/content/influxdb/cloud/monitor-alert/templates/networks/_index.md b/content/influxdb/cloud/monitor-alert/templates/networks/_index.md new file mode 100644 index 000000000..5a9deb68e --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/templates/networks/_index.md @@ -0,0 +1,14 @@ +--- +title: Monitor networks +description: > + Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your networks. +menu: + influxdb_cloud: + parent: Monitor with templates +weight: 104 +influxdb/cloud/tags: [monitor, templates, networks, networking] +--- + +Use one of our community templates to quickly set up InfluxDB (with a bucket and dashboard) to collect, analyze, and monitor your networks. + +{{< children >}} \ No newline at end of file diff --git a/content/influxdb/cloud/monitor-alert/templates/networks/haproxy.md b/content/influxdb/cloud/monitor-alert/templates/networks/haproxy.md new file mode 100644 index 000000000..afed4dd08 --- /dev/null +++ b/content/influxdb/cloud/monitor-alert/templates/networks/haproxy.md @@ -0,0 +1,48 @@ +--- +title: Monitor HAProxy +description: > + Use the [HAProxy for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/haproxy) to monitor your HAProxy instance. +menu: + influxdb_cloud: + parent: Monitor networks + name: HAproxy +weight: 201 +--- + +Use the [HAProxy for InfluxDB v2 template](https://github.com/influxdata/community-templates/tree/master/haproxy) to monitor your HAProxy instances. First, [apply the template](#apply-the-template), and then [view incoming data](#view-incoming-data). +This template uses the [HAProxy input plugin](/{{< latest "telegraf" >}}/plugins//#haproxy) to collect metrics stored in an HAProxy instance and display these metrics in a dashboard. + +The HAProxy for InfluxDB v2 template includes the following: + +- one [dashboard](/influxdb/cloud/reference/glossary/#dashboard): **HAProxy** +- one [bucket](/influxdb/cloud/reference/glossary/#bucket): `haproxy` +- label: `haproxy` +- one [Telegraf configuration](/influxdb/cloud/telegraf-configs/): HAProxy input plugin, InfluxDB v2 output plugin +- one variable: `bucket` + +## Apply the template + +1. Use the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) to run the following command: + + ```sh + influx apply -f https://raw.githubusercontent.com/influxdata/community-templates/master/haproxy/haproxy.yml + ``` + For more information, see [influx apply](/influxdb/cloud/reference/cli/influx/apply/). + + > **Note:** Ensure your `influx` CLI is configured with your account credentials and that configuration is active. For more information, see [influx config](/influxdb/cloud/reference/cli/influx/config/). + +2. [Install Telegraf](/{{< latest "telegraf" >}}/introduction/installation/) on a server with network access to both the HAProxy instances and [InfluxDB v2 API](/influxdb/cloud/reference/api/). +3. In your [Telegraf configuration file (`telegraf.conf`)](/influxdb/cloud/telegraf-configs/), do the following: + - Set the following environment variables: + - INFLUX_TOKEN: Token must have permissions to read Telegraf configurations and write data to the `haproxy` bucket. See how to [view tokens](/influxdb/cloud/security/tokens/view-tokens/). + - INFLUX_ORG: Name of your organization. See how to [view your organization](/influxdb/cloud/organizations/view-orgs/). + - INFLUX_HOST: Your InfluxDB host URL, for example, localhost, a remote instance, or InfluxDB Cloud. + +4. [Start Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/auto-config/#start-telegraf). + +## View incoming data + +1. In the InfluxDB user interface (UI), select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} +2. Open the **HAProxy** dashboard to start monitoring. diff --git a/content/influxdb/cloud/organizations/_index.md b/content/influxdb/cloud/organizations/_index.md new file mode 100644 index 000000000..b527e5f62 --- /dev/null +++ b/content/influxdb/cloud/organizations/_index.md @@ -0,0 +1,22 @@ +--- +title: Manage organizations +seotitle: Manage organizations in InfluxDB +description: Manage organizations in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_cloud: + name: Manage organizations +weight: 10 +influxdb/cloud/tags: [organizations] +--- + +An **organization** is a workspace for a group of users. +All dashboards, tasks, buckets, members, etc., belong to an organization. + +{{% cloud %}} +You cannot currently create additional organizations in {{< cloud-name >}}. +Only the default organization is available. +{{% /cloud %}} + +The following articles provide information about managing organizations: + +{{< children >}} diff --git a/content/influxdb/cloud/organizations/buckets/_index.md b/content/influxdb/cloud/organizations/buckets/_index.md new file mode 100644 index 000000000..c0d1dc6cc --- /dev/null +++ b/content/influxdb/cloud/organizations/buckets/_index.md @@ -0,0 +1,19 @@ +--- +title: Manage buckets +seotitle: Manage buckets in InfluxDB +description: Manage buckets in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_cloud: + name: Manage buckets + parent: Manage organizations +weight: 105 +influxdb/cloud/tags: [buckets] +--- + +A **bucket** is a named location where time series data is stored. +All buckets have a **retention policy**, a duration of time that each data point persists. +A bucket belongs to an organization. + +The following articles provide information about managing buckets: + +{{< children >}} diff --git a/content/influxdb/cloud/organizations/buckets/create-bucket.md b/content/influxdb/cloud/organizations/buckets/create-bucket.md new file mode 100644 index 000000000..d204d915e --- /dev/null +++ b/content/influxdb/cloud/organizations/buckets/create-bucket.md @@ -0,0 +1,68 @@ +--- +title: Create a bucket +seotitle: Create a bucket in InfluxDB +description: Create buckets to store time series data in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_cloud: + name: Create a bucket + parent: Manage buckets +weight: 201 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to create a bucket. + +## Create a bucket in the InfluxDB UI + +There are two places you can create a bucket in the UI. + +### Create a bucket from the Load Data menu + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **{{< icon "plus" >}} Create Bucket** in the upper right. +3. Enter a **Name** for the bucket. +4. Select when to **Delete Data**: + - **Never** to retain data forever. + - **Older than** to choose a specific retention policy. +5. Click **Create** to create the bucket. + +### Create a bucket in the Data Explorer + +1. In the navigation menu on the left, select **Explore* (**Data Explorer**). + + {{< nav-icon "data-explorer" >}} + +2. In the **From** panel in the Flux Builder, select `+ Create Bucket`. +3. Enter a **Name** for the bucket. +4. Select when to **Delete Data**: + - **Never** to retain data forever. + - **Older than** to choose a specific retention policy. +5. Click **Create** to create the bucket. + +## Create a bucket using the influx CLI + +Use the [`influx bucket create` command](/influxdb/cloud/reference/cli/influx/bucket/create) +to create a new bucket. A bucket requires the following: + +- bucket name +- organization name or ID +- retention period (duration to keep data) in one of the following units: + - nanoseconds (`ns`) + - microseconds (`us` or `µs`) + - milliseconds (`ms`) + - seconds (`s`) + - minutes (`m`) + - hours (`h`) + - days (`d`) + - weeks (`w`) + +```sh +# Syntax +influx bucket create -n -o -r + +# Example +influx bucket create -n my-bucket -o my-org -r 72h +``` diff --git a/content/influxdb/cloud/organizations/buckets/delete-bucket.md b/content/influxdb/cloud/organizations/buckets/delete-bucket.md new file mode 100644 index 000000000..b6de8c85b --- /dev/null +++ b/content/influxdb/cloud/organizations/buckets/delete-bucket.md @@ -0,0 +1,56 @@ +--- +title: Delete a bucket +seotitle: Delete a bucket from InfluxDB +description: Delete a bucket from InfluxDB using the InfluxDB UI or the influx CLI +menu: + influxdb_cloud: + name: Delete a bucket + parent: Manage buckets +weight: 203 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to delete a bucket. + +## Delete a bucket in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Hover over the bucket you would like to delete. +3. Click **{{< icon "delete" >}} Delete Bucket** and **Confirm** to delete the bucket. + +## Delete a bucket using the influx CLI + +Use the [`influx bucket delete` command](/influxdb/cloud/reference/cli/influx/bucket/delete) +to delete a bucket a bucket by name or ID. + +### Delete a bucket by name +**To delete a bucket by name, you need:** + +- Bucket name +- Bucket's organization name or ID + + +```sh +# Syntax +influx bucket delete -n -o + +# Example +influx bucket delete -n my-bucket -o my-org +``` + +### Delete a bucket by ID +**To delete a bucket by ID, you need:** + +- Bucket ID _(provided in the output of `influx bucket list`)_ + + +```sh +# Syntax +influx bucket delete -i + +# Example +influx bucket delete -i 034ad714fdd6f000 +``` diff --git a/content/influxdb/cloud/organizations/buckets/update-bucket.md b/content/influxdb/cloud/organizations/buckets/update-bucket.md new file mode 100644 index 000000000..27f3b82ba --- /dev/null +++ b/content/influxdb/cloud/organizations/buckets/update-bucket.md @@ -0,0 +1,73 @@ +--- +title: Update a bucket +seotitle: Update a bucket in InfluxDB +description: Update a bucket's name or retention policy in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_cloud: + name: Update a bucket + parent: Manage buckets +weight: 202 +--- + +Use the `influx` command line interface (CLI) or the InfluxDB user interface (UI) to update a bucket. + +Note that updating an bucket's name will affect any assets that reference the bucket by name, including the following: + + - Queries + - Dashboards + - Tasks + - Telegraf configurations + - Templates + +If you change a bucket name, be sure to update the bucket in the above places as well. + +## Update a bucket's name in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **Settings** under the bucket you want to rename. +3. Click **Rename**. +3. Review the information in the window that appears and click **I understand, let's rename my bucket**. +4. Update the bucket's name and click **Change Bucket Name**. + +## Update a bucket's retention policy in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **Settings** next to the bucket you want to update. +3. In the window that appears, edit the bucket's retention policy. +4. Click **Save Changes**. + +## Update a bucket using the influx CLI + +Use the [`influx bucket update` command](/influxdb/cloud/reference/cli/influx/bucket/update) +to update a bucket. Updating a bucket requires the following: + +- The bucket ID _(provided in the output of `influx bucket list`)_ +- The name or ID of the organization the bucket belongs to. + +##### Update the name of a bucket + +```sh +# Syntax +influx bucket update -i -o -n + +# Example +influx bucket update -i 034ad714fdd6f000 -o my-org -n my-new-bucket +``` + +##### Update a bucket's retention policy + +Valid retention policy duration units are nanoseconds (`ns`), microseconds (`us` or `µs`), milliseconds (`ms`), seconds (`s`), minutes (`m`), hours (`h`), days (`d`), or weeks (`w`). + +```sh +# Syntax +influx bucket update -i -r + +# Example +influx bucket update -i 034ad714fdd6f000 -r 1209600000000000 +``` diff --git a/content/influxdb/cloud/organizations/buckets/view-buckets.md b/content/influxdb/cloud/organizations/buckets/view-buckets.md new file mode 100644 index 000000000..a9aabb926 --- /dev/null +++ b/content/influxdb/cloud/organizations/buckets/view-buckets.md @@ -0,0 +1,34 @@ +--- +title: View buckets +seotitle: View buckets in InfluxDB +description: View a list of all the buckets for an organization in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_cloud: + name: View buckets + parent: Manage buckets +weight: 202 +--- + +## View buckets in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + + A list of buckets with their retention policies and IDs appears. + +2. Click a bucket to open it in the **Data Explorer**. +3. Click the bucket ID to copy it to the clipboard. + +## View buckets using the influx CLI + +Use the [`influx bucket list` command](/influxdb/cloud/reference/cli/influx/bucket/list) +to view a buckets in an organization. + +```sh +influx bucket list +``` + +Other filtering options such as filtering by a name or ID are available. +See the [`influx bucket list` documentation](/influxdb/cloud/reference/cli/influx/bucket/list) +for information about other available flags. diff --git a/content/influxdb/cloud/organizations/members/_index.md b/content/influxdb/cloud/organizations/members/_index.md new file mode 100644 index 000000000..42f6bf954 --- /dev/null +++ b/content/influxdb/cloud/organizations/members/_index.md @@ -0,0 +1,16 @@ +--- +title: Manage organization members +seotitle: Manage members of an organization in InfluxDB +description: Manage members of an organization in InfluxDB using the InfluxDB UI or CLI. +menu: + influxdb_cloud: + name: Manage members + parent: Manage organizations +weight: 106 +influxdb/cloud/tags: [members] +--- + +A **member** is a user that belongs to an organization. +The following articles provide information about managing users: + +{{< children >}} diff --git a/content/influxdb/cloud/organizations/members/add-member.md b/content/influxdb/cloud/organizations/members/add-member.md new file mode 100644 index 000000000..8cc6605ae --- /dev/null +++ b/content/influxdb/cloud/organizations/members/add-member.md @@ -0,0 +1,40 @@ +--- +title: Add a member +seotitle: Add a member to an organization in InfluxDB +description: Add a member to an organization. +menu: + influxdb_cloud: + name: Add a member + parent: Manage members +weight: 201 +--- + +Use the `influx` command line interface (CLI) to add a member to an organization. + +{{% cloud %}} +To manage members of an organization in {{< cloud-name >}}, see [Manage multiple users](/influxdb/cloud/account-management/multi-user/). +{{% /cloud %}} + + + +## Add a member to an organization using the influx CLI + +1. Get a list of users and their IDs by running the following: + +```sh +influx user list +``` + +2. To add a user to an organization, run the following command: + +```sh +influx org members add -n -m +``` + +For more information, see the [`influx org members add` command](/influxdb/cloud/reference/cli/influx/org/members/add). diff --git a/content/influxdb/cloud/organizations/members/remove-member.md b/content/influxdb/cloud/organizations/members/remove-member.md new file mode 100644 index 000000000..d9ad728f8 --- /dev/null +++ b/content/influxdb/cloud/organizations/members/remove-member.md @@ -0,0 +1,42 @@ +--- +title: Remove a member +seotitle: Remove a member from an organization in InfluxDB +description: Remove a member from an organization. +menu: + influxdb_cloud: + name: Remove a member + parent: Manage members +weight: 203 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to remove a member from an organization. + +{{% note %}} +Removing a member from an organization removes all permissions associated with the organization. +{{% /note %}} + +## Remove a member from an organization in the InfluxDB UI + +1. In the navigation menu on the left, select **Org (Organization)** > **Members**. + + {{< nav-icon "org" >}} + +2. Hover over the member you would like to delete and click the **{{< icon "delete" >}}** icon. +3. Click **Delete**. + +## Remove a member from an organization using the influx CLI + +Use the [`influx org members remove` command](/influxdb/cloud/reference/cli/influx/org/members/remove) +to remove a member from an organization. Removing a member requires the following: + +- The organization name or ID _(provided in the output of [`influx org list`](/influxdb/cloud/reference/cli/influx/org/list/))_ +- The member ID _(provided in the output of [`influx org members list`](/influxdb/cloud/reference/cli/influx/org/members/list/))_ + +```sh +# Syntax +influx org members remove -o -i + +# Example +influx org members remove -o 00xXx0x00xXX0000 -i x0xXXXx00x0x000X +``` diff --git a/content/influxdb/cloud/organizations/members/view-members.md b/content/influxdb/cloud/organizations/members/view-members.md new file mode 100644 index 000000000..6d5c08b01 --- /dev/null +++ b/content/influxdb/cloud/organizations/members/view-members.md @@ -0,0 +1,35 @@ +--- +title: View members +seotitle: View members of an organization in InfluxDB +description: Review a list of members for an organization. +menu: + influxdb_cloud: + name: View members + parent: Manage members +weight: 202 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to view members of an organization. + +## View members of organization in the InfluxDB UI + +In the navigation menu on the left, select **Org (Organization)** > **Members**. + +{{< nav-icon "org" >}} + + +## View members of organization using the influx CLI + +Use the [`influx org members list` command](/influxdb/cloud/reference/cli/influx/org/members/list) +to list members of an organization. Listing an organization's members requires the following: + +- The name or ID of the organization + +```sh +# Syntax +influx org members list -n + +# Example +influx org members list -n my-org +``` diff --git a/content/influxdb/cloud/organizations/update-org.md b/content/influxdb/cloud/organizations/update-org.md new file mode 100644 index 000000000..877c55078 --- /dev/null +++ b/content/influxdb/cloud/organizations/update-org.md @@ -0,0 +1,50 @@ +--- +title: Update an organization +seotitle: Update an organization in InfluxDB +description: Update an organization's name and assets in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_cloud: + name: Update an organization + parent: Manage organizations +weight: 103 +--- + +Use the `influx` command line interface (CLI) or the InfluxDB user interface (UI) to update an organization. + +Note that updating an organization's name will affect any assets that reference the organization by name, including the following: + + - Queries + - Dashboards + - Tasks + - Telegraf configurations + - Templates + +If you change an organization name, be sure to update the organization in the above places as well. + +## Update an organization in the InfluxDB UI + +1. In the navigation menu on the left, click the **Org (Organization)** > **About**. + + {{< nav-icon "org" >}} + +2. Click **{{< icon "edit" >}} Rename**. +3. In the window that appears, review the information and click **I understand, let's rename my organization**. +4. Enter a new name for your organization. +5. Click **Change organization name**. + +## Update an organization using the influx CLI + +Use the [`influx org update` command](/influxdb/cloud/reference/cli/influx/org/update) +to update an organization. Updating an organization requires the following: + +- The org ID _(provided in the output of `influx org list`)_ + +##### Update the name of a organization + +```sh +# Syntax +influx org update -i -n + +# Example +influx org update -i 034ad714fdd6f000 -n my-new-org +``` diff --git a/content/influxdb/cloud/organizations/view-orgs.md b/content/influxdb/cloud/organizations/view-orgs.md new file mode 100644 index 000000000..3134f3609 --- /dev/null +++ b/content/influxdb/cloud/organizations/view-orgs.md @@ -0,0 +1,50 @@ +--- +title: View organization +seotitle: View organization in InfluxDB +description: Review a list of organizations in InfluxDB using the InfluxDB UI or the influx CLI. +menu: + influxdb_cloud: + name: View organizations + parent: Manage organizations +weight: 102 +--- + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to view organizations. + +## View organizations using the influx CLI + +Use the [`influx org list` command](/influxdb/cloud/reference/cli/influx/org/list) +to view organizations. + +```sh +influx org list +``` + +Filtering options such as filtering by name or ID are available. +See the [`influx org list` documentation](/influxdb/cloud/reference/cli/influx/org/list) +for information about other available flags. + +## View your organization ID + +Use the InfluxDB UI or `influx` CLI to view your organization ID. + +### Organization ID in the UI + +After logging in to the InfluxDB UI, your organization ID appears in the URL. + +
+https://cloud2.influxdata.com/orgs/03a2bbf46249a000/...
+
+ +### Organization ID in the CLI + +Use [`influx org list`](#view-organizations-using-the-influx-cli) to view your organization ID. + +```sh +> influx org list + +ID Name +03a2bbf46249a000 org-1 +03ace3a859669000 org-2 +``` diff --git a/content/influxdb/cloud/process-data/_index.md b/content/influxdb/cloud/process-data/_index.md new file mode 100644 index 000000000..226e7170a --- /dev/null +++ b/content/influxdb/cloud/process-data/_index.md @@ -0,0 +1,26 @@ +--- +title: Process Data with InfluxDB tasks +seotitle: Process Data with InfluxDB tasks +description: > + InfluxDB's task engine runs scheduled Flux tasks that process and analyze data. + This collection of articles provides information about creating and managing InfluxDB tasks. +menu: + influxdb_cloud: + name: Process data +weight: 4 +influxdb/cloud/tags: [tasks] +--- + +Process and analyze your data with tasks in the InfluxDB **task engine**. Use tasks (scheduled Flux queries) +to input a data stream and then analyze, modify, and act on the data accordingly. + +Discover how to create and manage tasks using the InfluxDB user interface (UI) +and the `influx` command line interface (CLI). +Find examples of data downsampling, anomaly detection _(Coming)_, alerting +_(Coming)_, and other common tasks. + +{{% note %}} +Tasks replace InfluxDB v1.x continuous queries. +{{% /note %}} + +{{< children >}} diff --git a/content/influxdb/cloud/process-data/common-tasks/_index.md b/content/influxdb/cloud/process-data/common-tasks/_index.md new file mode 100644 index 000000000..c6c3670e7 --- /dev/null +++ b/content/influxdb/cloud/process-data/common-tasks/_index.md @@ -0,0 +1,22 @@ +--- +title: Common data processing tasks +seotitle: Common data processing tasks performed with with InfluxDB +description: > + InfluxDB Tasks process data on specified schedules. + This collection of articles walks through common use cases for InfluxDB tasks. +influxdb/cloud/tags: [tasks] +menu: + influxdb_cloud: + name: Common tasks + parent: Process data +weight: 104 +--- + +The following articles walk through common task use cases. + +{{< children >}} + +{{% note %}} +This list will continue to grow. +If you have suggestions, please [submit them to the InfluxData Community](https://community.influxdata.com/c/influxdb2). +{{% /note %}} diff --git a/content/influxdb/cloud/process-data/common-tasks/downsample-data.md b/content/influxdb/cloud/process-data/common-tasks/downsample-data.md new file mode 100644 index 000000000..7ac1da7ed --- /dev/null +++ b/content/influxdb/cloud/process-data/common-tasks/downsample-data.md @@ -0,0 +1,80 @@ +--- +title: Downsample data with InfluxDB +seotitle: Downsample data in an InfluxDB task +description: > + How to create a task that downsamples data much like continuous queries + in previous versions of InfluxDB. +menu: + influxdb_cloud: + name: Downsample data + parent: Common tasks +weight: 201 +influxdb/cloud/tags: [tasks] +--- + +One of the most common use cases for InfluxDB tasks is downsampling data to reduce +the overall disk usage as data collects over time. +In previous versions of InfluxDB, continuous queries filled this role. + +This article walks through creating a continuous-query-like task that downsamples +data by aggregating data within windows of time, then storing the aggregate value in a new bucket. + +### Requirements +To perform a downsampling task, you need to the following: + +##### A "source" bucket +The bucket from which data is queried. + +##### A "destination" bucket +A separate bucket where aggregated, downsampled data is stored. + +##### Some type of aggregation +To downsample data, it must be aggregated in some way. +What specific method of aggregation you use depends on your specific use case, +but examples include mean, median, top, bottom, etc. +View [Flux's aggregate functions](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/) +for more information and ideas. + +## Example downsampling task script +The example task script below is a very basic form of data downsampling that does the following: + +1. Defines a task named "cq-mem-data-1w" that runs once a week. +2. Defines a `data` variable that represents all data from the last 2 weeks in the + `mem` measurement of the `system-data` bucket. +3. Uses the [`aggregateWindow()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/) + to window the data into 1 hour intervals and calculate the average of each interval. +4. Stores the aggregated data in the `system-data-downsampled` bucket under the + `my-org` organization. + +```js +// Task Options +option task = { + name: "cq-mem-data-1w", + every: 1w, +} + +// Defines a data source +data = from(bucket: "system-data") + |> range(start: -duration(v: int(v: task.every) * 2)) + |> filter(fn: (r) => r._measurement == "mem") + +data + // Windows and aggregates the data in to 1h averages + |> aggregateWindow(fn: mean, every: 1h) + // Stores the aggregated data in a new bucket + |> to(bucket: "system-data-downsampled", org: "my-org") +``` + +Again, this is a very basic example, but it should provide you with a foundation +to build more complex downsampling tasks. + +## Add your task +Once your task is ready, see [Create a task](/influxdb/cloud/process-data/manage-tasks/create-task) for information about adding it to InfluxDB. + +## Things to consider +- If there is a chance that data may arrive late, specify an `offset` in your + task options long enough to account for late-data. +- If running a task against a bucket with a finite retention policy, do not schedule + tasks to run too closely to the end of the retention policy. + Always provide a "cushion" for downsampling tasks to complete before the data + is dropped by the retention policy. diff --git a/content/influxdb/cloud/process-data/get-started.md b/content/influxdb/cloud/process-data/get-started.md new file mode 100644 index 000000000..f9a8d5b35 --- /dev/null +++ b/content/influxdb/cloud/process-data/get-started.md @@ -0,0 +1,148 @@ +--- +title: Get started with InfluxDB tasks +list_title: Get started with tasks +description: > + Learn the basics of writing an InfluxDB task that processes data, and then performs an action, + such as storing the modified data in a new bucket or sending an alert. +aliases: + - /influxdb/cloud/process-data/write-a-task/ +influxdb/cloud/tags: [tasks] +menu: + influxdb_cloud: + name: Get started with tasks + parent: Process data +weight: 101 +--- + +An **InfluxDB task** is a scheduled Flux script that takes a stream of input data, modifies or analyzes +it in some way, then stores the modified data in a new bucket or performs other actions. + +This article walks through writing a basic InfluxDB task that downsamples +data and stores it in a new bucket. + +## Components of a task +Every InfluxDB task needs the following four components. +Their form and order can vary, but they are all essential parts of a task. + +- [Task options](#define-task-options) +- [A data source](#define-a-data-source) +- [Data processing or transformation](#process-or-transform-your-data) +- [A destination](#define-a-destination) + +_[Skip to the full example task script](#full-example-task-script)_ + +## Define task options +Task options define specific information about the task. +The example below illustrates how task options are defined in your Flux script: + +```js +option task = { + name: "cqinterval15m", + every: 1h, + offset: 0m, + concurrency: 1, + retry: 5 +} +``` + +_See [Task configuration options](/influxdb/cloud/process-data/task-options) for detailed information +about each option._ + +{{% note %}} +When creating a task in the InfluxDB user interface (UI), task options are defined in form fields. +{{% /note %}} + +## Define a data source +Define a data source using Flux's [`from()` function](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from/) +or any other [Flux input functions](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/). + +For convenience, consider creating a variable that includes the sourced data with +the required time range and any relevant filters. + +```js +data = from(bucket: "telegraf/default") + |> range(start: -task.every) + |> filter(fn: (r) => + r._measurement == "mem" and + r.host == "myHost" + ) +``` + +{{% note %}} +#### Using task options in your Flux script +Task options are passed as part of a `task` option record and can be referenced in your Flux script. +In the example above, the time range is defined as `-task.every`. + +`task.every` is dot notation that references the `every` property of the `task` option record. +`every` is defined as `1h`, therefore `-task.every` equates to `-1h`. + +Using task options to define values in your Flux script can make reusing your task easier. +{{% /note %}} + +## Process or transform your data +The purpose of tasks is to process or transform data in some way. +What exactly happens and what form the output data takes is up to you and your +specific use case. + +The example below illustrates a task that downsamples data by calculating the average of set intervals. +It uses the `data` variable defined [above](#define-a-data-source) as the data source. +It then windows the data into 5 minute intervals and calculates the average of each +window using the [`aggregateWindow()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/). + +```js +data + |> aggregateWindow( + every: 5m, + fn: mean + ) +``` + +_See [Common tasks](/influxdb/cloud/process-data/common-tasks) for examples of tasks commonly used with InfluxDB._ + +## Define a destination +In the vast majority of task use cases, once data is transformed, it needs to be sent and stored somewhere. +This could be a separate bucket or another measurement. + +The example below uses Flux's [`to()` function](/influxdb/cloud/reference/flux/stdlib/built-in/outputs/to) +to send the transformed data to another bucket: + +```js +// ... +|> to(bucket: "telegraf_downsampled", org: "my-org") +``` + +{{% note %}} +In order to write data into InfluxDB, you must have `_time`, `_measurement`, `_field`, and `_value` columns. +{{% /note %}} + +## Full example task script +Below is a task script that combines all of the components described above: + +```js +// Task options +option task = { + name: "cqinterval15m", + every: 1h, + offset: 0m, + concurrency: 1, + retry: 5 +} + +// Data source +data = from(bucket: "telegraf/default") + |> range(start: -task.every) + |> filter(fn: (r) => + r._measurement == "mem" and + r.host == "myHost" + ) + +data + // Data transformation + |> aggregateWindow( + every: 5m, + fn: mean + ) + // Data destination + |> to(bucket: "telegraf_downsampled") + +``` diff --git a/content/influxdb/cloud/process-data/manage-tasks/_index.md b/content/influxdb/cloud/process-data/manage-tasks/_index.md new file mode 100644 index 000000000..ccc660bb1 --- /dev/null +++ b/content/influxdb/cloud/process-data/manage-tasks/_index.md @@ -0,0 +1,20 @@ +--- +title: Manage tasks in InfluxDB +seotitle: Manage data processing tasks in InfluxDB +list_title: Manage tasks +description: > + InfluxDB provides options for creating, reading, updating, and deleting tasks + using both the `influx` CLI and the InfluxDB UI. +influxdb/cloud/tags: [tasks] +menu: + influxdb_cloud: + name: Manage tasks + parent: Process data +weight: 102 +--- + +InfluxDB provides two options for managing the creation, reading, updating, and deletion (CRUD) of tasks - +through the InfluxDB user interface (UI) or using the `influx` command line interface (CLI). +Both tools can perform all task CRUD operations. + +{{< children >}} diff --git a/content/influxdb/cloud/process-data/manage-tasks/create-task.md b/content/influxdb/cloud/process-data/manage-tasks/create-task.md new file mode 100644 index 000000000..cb402a4a4 --- /dev/null +++ b/content/influxdb/cloud/process-data/manage-tasks/create-task.md @@ -0,0 +1,113 @@ +--- +title: Create a task +seotitle: Create a task for processing data in InfluxDB +description: > + Create a data processing task in InfluxDB using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_cloud: + name: Create a task + parent: Manage tasks +weight: 201 +related: + - /influxdb/cloud/reference/cli/influx/task/create +--- + +InfluxDB provides multiple ways to create tasks both in the InfluxDB user interface (UI) +and the `influx` command line interface (CLI). + +_Before creating a task, review the [basics criteria for writing a task](/influxdb/cloud/process-data/get-started)._ + +- [InfluxDB UI](#create-a-task-in-the-influxdb-ui) +- [`influx` CLI](#create-a-task-using-the-influx-cli) + +## Create a task in the InfluxDB UI +The InfluxDB UI provides multiple ways to create a task: + +- [Create a task from the Data Explorer](#create-a-task-from-the-data-explorer) +- [Create a task in the Task UI](#create-a-task-in-the-task-ui) +- [Import a task](#import-a-task) +- [Create a task from a template](#create-a-task-from-a-template) +- [Clone a task](#clone-a-task) + +### Create a task from the Data Explorer +1. In the navigation menu on the left, select **Explore** (**Data Explorer**). + + {{< nav-icon "data-explorer" >}} + +2. Build a query and click **Save As** in the upper right. +3. Select the **Task** option. +4. Specify the task options. See [Task options](/influxdb/cloud/process-data/task-options) + for detailed information about each option. +5. Select a token to use from the **Token** dropdown. +6. Click **Save as Task**. + + +### Create a task in the Task UI +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Click **{{< icon "plus" >}} Create Task** in the upper right. +3. Select **New Task**. +4. In the left panel, specify the task options. + See [Task options](/influxdb/cloud/process-data/task-options) for detailed information about each option. +5. Select a token to use from the **Token** dropdown. +6. In the right panel, enter your task script. +7. Click **Save** in the upper right. + +### Import a task +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Click **+ Create Task** in the upper right. +3. Select **Import Task**. +4. Upload a JSON task file using one of the following options: + - Drag and drop a JSON task file in the specified area. + - Click to upload and the area to select the JSON task from from your file manager. + - Select the **JSON** option and paste in raw task JSON. +5. Click **Import JSON as Task**. + +### Create a task from a template +1. In the navigation menu on the left, select **Settings** > **Templates**. + + {{< nav-icon "Settings" >}} + +2. Select **Templates**. +3. Hover over the template to use to create the task and click **Create**. + + +### Clone a task +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Hover over the task you would like to clone and click the **{{< icon "duplicate" >}}** icon that appears. +4. Click **Clone**. + +## Create a task using the influx CLI +Use `influx task create` command to create a new task. +It accepts either a file path or raw Flux. + +###### Create a task using a file +```sh +# Syntax +influx task create --org -f + +# Example +influx task create --org my-org -f /tasks/cq-mean-1h.flux +``` + +###### Create a task using raw Flux +```sh +influx task create --org my-org - # to open stdin pipe + +options task = { + name: "task-name", + every: 6h +} + +# ... Task script ... + +# to close the pipe and submit the command +``` diff --git a/content/influxdb/cloud/process-data/manage-tasks/delete-task.md b/content/influxdb/cloud/process-data/manage-tasks/delete-task.md new file mode 100644 index 000000000..27e4d0937 --- /dev/null +++ b/content/influxdb/cloud/process-data/manage-tasks/delete-task.md @@ -0,0 +1,36 @@ +--- +title: Delete a task +seotitle: Delete a task for processing data in InfluxDB +description: > + Delete a task from InfluxDB using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_cloud: + name: Delete a task + parent: Manage tasks +weight: 206 +related: + - /influxdb/cloud/reference/cli/influx/task/delete +--- + +## Delete a task in the InfluxDB UI +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. In the list of tasks, hover over the task you would like to delete. +3. Click **Delete** on the far right. +4. Click **Confirm**. + + +## Delete a task with the influx CLI +Use the `influx task delete` command to delete a task. + +_This command requires a task ID, which is available in the output of `influx task list`._ + +```sh +# Syntax +influx task delete -i + +# Example +influx task delete -i 0343698431c35000 +``` diff --git a/content/influxdb/cloud/process-data/manage-tasks/export-task.md b/content/influxdb/cloud/process-data/manage-tasks/export-task.md new file mode 100644 index 000000000..2a4bfd0dc --- /dev/null +++ b/content/influxdb/cloud/process-data/manage-tasks/export-task.md @@ -0,0 +1,26 @@ +--- +title: Export a task +seotitle: Export an InfluxDB task +description: Export a data processing task from InfluxDB using the InfluxDB UI. +menu: + influxdb_cloud: + name: Export a task + parent: Manage tasks +weight: 205 +--- + +InfluxDB lets you export tasks from the InfluxDB user interface (UI). +Tasks are exported as downloadable JSON files. + +## Export a task in the InfluxDB UI +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. In the list of tasks, hover over the task you would like to export and click + the **{{< icon "gear" >}}** icon that appears. +3. Select **Export**. +4. Downloading or save the task export file using one of the following options: + - Click **Download JSON** to download the exported JSON file. + - Click **Save as template** to save the export file as a task template. + - Click **Copy to Clipboard** to copy the raw JSON content to your machine's clipboard. diff --git a/content/influxdb/cloud/process-data/manage-tasks/run-task.md b/content/influxdb/cloud/process-data/manage-tasks/run-task.md new file mode 100644 index 000000000..670a32211 --- /dev/null +++ b/content/influxdb/cloud/process-data/manage-tasks/run-task.md @@ -0,0 +1,44 @@ +--- +title: Run a task +seotitle: Run an InfluxDB task +description: > + Run a data processing task using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_cloud: + name: Run a task + parent: Manage tasks +weight: 203 +related: + - /influxdb/cloud/reference/cli/influx/task/run + - /influxdb/cloud/reference/cli/influx/task/retry +--- + +InfluxDB data processing tasks generally run in defined intervals or at a specific time, +however, you can manually run a task from the InfluxDB user interface (UI) or the +`influx` command line interface (CLI). + +## Run a task from the InfluxDB UI +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Hover over the task you want to run and click the **{{< icon "gear" >}}** icon. +3. Select **Run Task**. + +## Run a task with the influx CLI +Use the `influx task run retry` command to run a task. + +{{% note %}} +To run a task from the `influx` CLI, the task must have already run at least once. +{{% /note %}} + +```sh +# List all tasks to find the ID of the task to run +influx task list + +# Use the task ID to list previous runs of the task +influx task run list --task-id=0000000000000000 + +# Use the task ID and run ID to retry a run +influx task run retry --task-id=0000000000000000 --run-id=0000000000000000 +``` diff --git a/content/influxdb/cloud/process-data/manage-tasks/task-run-history.md b/content/influxdb/cloud/process-data/manage-tasks/task-run-history.md new file mode 100644 index 000000000..2d4a621f0 --- /dev/null +++ b/content/influxdb/cloud/process-data/manage-tasks/task-run-history.md @@ -0,0 +1,46 @@ +--- +title: View task run history and logs +description: > + View task run histories and logs using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_cloud: + name: View run history + parent: Manage tasks +weight: 203 +related: + - /influxdb/cloud/reference/cli/influx/task/run/find +--- + +When an InfluxDB task runs, a "run" record is created in the task's history. +Logs associated with each run provide relevant log messages, timestamps, +and the exit status of the run attempt. + +Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) +to view task run histories and associated logs. + +## View a task's run history in the InfluxDB UI + +1. In the navigation menu on the left, select **Tasks**. + + {{< nav-icon "tasks" >}} + +2. Hover over the task you want to run and click the **{{< icon "gear" >}}** icon. +3. Select **View Task Runs**. + +### View task run logs +To view logs associated with a run, click **View Logs** next to the run in the task's run history. + +## View a task's run history with the influx CLI +Use the `influx task run list` command to view a task's run history. + +```sh +# List all tasks to find the ID of the task to run +influx task list + +# Use the task ID to view the run history of a task +influx task run list --task-id=0000000000000000 +``` + +{{% note %}} +Detailed run logs are not currently available in the `influx` CLI. +{{% /note %}} diff --git a/content/influxdb/cloud/process-data/manage-tasks/update-task.md b/content/influxdb/cloud/process-data/manage-tasks/update-task.md new file mode 100644 index 000000000..1c6f13a23 --- /dev/null +++ b/content/influxdb/cloud/process-data/manage-tasks/update-task.md @@ -0,0 +1,69 @@ +--- +title: Update a task +seotitle: Update a task for processing data in InfluxDB +description: > + Update a data processing task in InfluxDB using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_cloud: + name: Update a task + parent: Manage tasks +weight: 204 +related: + - /influxdb/cloud/reference/cli/influx/task/update +--- + +## Update a task in the InfluxDB UI +Click the **Tasks** icon in the left navigation to view the lists of tasks. + +{{< nav-icon "tasks" >}} + +Click the name of a task to update it. + +#### Update a task Flux script +1. In the list of tasks, click the **Name** of the task you want to update. +2. In the left panel, modify the task options. +3. In the right panel, modify the task script. +4. Click **Save** in the upper right. + + +#### Update the status of a task +In the list of tasks, click the {{< icon "toggle" >}} toggle to the left of the +task you want to activate or inactivate. + +#### Update a task description +1. In the list of tasks, hover over the name of the task you want to update. +2. Click the pencil icon {{< icon "pencil" >}}. +3. Click outside of the field or press `RETURN` to update. + +## Update a task with the influx CLI +Use the `influx task update` command to update or change the status of an existing task. + +_This command requires a task ID, which is available in the output of `influx task list`._ + +#### Update a task Flux script +Pass the file path of your updated Flux script to the `influx task update` command +with the ID of the task you want to update. +Modified [task options](/influxdb/cloud/process-data/task-options) defined in the Flux +script are also updated. + +```sh +# Syntax +influx task update -i -f + +# Example +influx task update -i 0343698431c35000 -f /tasks/cq-mean-1h.flux +``` + +#### Update the status of a task +Pass the ID of the task you want to update to the `influx task update` +command with the `--status` flag. + +_Possible arguments of the `--status` flag are `active` or `inactive`._ + +```sh +# Syntax +influx task update -i --status < active | inactive > + +# Example +influx task update -i 0343698431c35000 --status inactive +``` diff --git a/content/influxdb/cloud/process-data/manage-tasks/view-tasks.md b/content/influxdb/cloud/process-data/manage-tasks/view-tasks.md new file mode 100644 index 000000000..429ce7226 --- /dev/null +++ b/content/influxdb/cloud/process-data/manage-tasks/view-tasks.md @@ -0,0 +1,38 @@ +--- +title: View tasks +seotitle: View created tasks that process data in InfluxDB +description: > + View existing data processing tasks using the InfluxDB UI or the `influx` CLI. +menu: + influxdb_cloud: + name: View tasks + parent: Manage tasks +weight: 202 +related: + - /influxdb/cloud/reference/cli/influx/task/list +--- + +## View tasks in the InfluxDB UI +Click the **Tasks** icon in the left navigation to view the lists of tasks. + +{{< nav-icon "tasks" >}} + +### Filter the list of tasks + +1. Click the **Show Inactive** {{< icon "toggle" >}} toggle to include or exclude + inactive tasks in the list. +2. Enter text in the **Filter tasks** field to search for tasks by name or label. +3. Click the heading of any column to sort by that field. + +## View tasks with the influx CLI +Use the `influx task list` command to return a list of created tasks. + +```sh +influx task list +``` + +#### Filter tasks using the CLI +Other filtering options such as filtering by organization or user, +or limiting the number of tasks returned, are available. +See the [`influx task list` documentation](/influxdb/cloud/reference/cli/influx/task/list) +for information about other available flags. diff --git a/content/influxdb/cloud/process-data/task-options.md b/content/influxdb/cloud/process-data/task-options.md new file mode 100644 index 000000000..ab522156d --- /dev/null +++ b/content/influxdb/cloud/process-data/task-options.md @@ -0,0 +1,112 @@ +--- +title: Task configuration options +seotitle: InfluxDB task configuration options +description: > + Task options define specific information about a task such as its name, + the schedule on which it runs, execution delays, and others. +menu: + influxdb_cloud: + name: Task options + parent: Process data +weight: 105 +influxdb/cloud/tags: [tasks, flux] +--- + +Task options define specific information about a task. +They are set in a Flux script or in the InfluxDB user interface (UI). +The following task options are available: + +- [name](#name) +- [every](#every) +- [cron](#cron) +- [offset](#offset) +- [concurrency](#concurrency) +- [retry](#retry) + +{{% note %}} +`every` and `cron` are mutually exclusive, but at least one is required. +{{% /note %}} + +## name +The name of the task. _**Required**_. + +_**Data type:** String_ + +```js +options task = { + name: "taskName", + // ... +} +``` + +## every +The interval at which the task runs. + +_**Data type:** Duration_ + +```js +options task = { + // ... + every: 1h, +} +``` + +{{% note %}} +In the InfluxDB UI, the **Interval** field sets this option. +{{% /note %}} + +## cron +The [cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that +defines the schedule on which the task runs. +Cron scheduling is based on system time. + +_**Data type:** String_ + +```js +options task = { + // ... + cron: "0 * * * *", +} +``` + +## offset +Delays the execution of the task but preserves the original time range. +For example, if a task is to run on the hour, a `10m` offset will delay it to 10 +minutes after the hour, but all time ranges defined in the task are relative to +the specified execution time. +A common use case is offsetting execution to account for data that may arrive late. + +_**Data type:** Duration_ + +```js +options task = { + // ... + offset: "0 * * * *", +} +``` + +## concurrency +The number task of executions that can run concurrently. +If the concurrency limit is reached, all subsequent executions are queued until +other running task executions complete. + +_**Data type:** Integer_ + +```js +options task = { + // ... + concurrency: 2, +} +``` + +## retry +The number of times to retry the task before it is considered as having failed. + +_**Data type:** Integer_ + +```js +options task = { + // ... + retry: 2, +} +``` diff --git a/content/influxdb/cloud/query-data/_index.md b/content/influxdb/cloud/query-data/_index.md new file mode 100644 index 000000000..954eca0ce --- /dev/null +++ b/content/influxdb/cloud/query-data/_index.md @@ -0,0 +1,17 @@ +--- +title: Query data in InfluxDB +seotitle: Query data stored in InfluxDB +description: > + Learn to query data stored in InfluxDB using Flux and tools such as the InfluxDB + user interface and the 'influx' command line interface. +menu: + influxdb_cloud: + name: Query data +weight: 3 +influxdb/cloud/tags: [query, flux] +--- + +Learn to query data stored in InfluxDB using Flux and tools such as the InfluxDB +user interface and the 'influx' command line interface. + +{{< children >}} diff --git a/content/influxdb/cloud/query-data/execute-queries/_index.md b/content/influxdb/cloud/query-data/execute-queries/_index.md new file mode 100644 index 000000000..df3bc0191 --- /dev/null +++ b/content/influxdb/cloud/query-data/execute-queries/_index.md @@ -0,0 +1,17 @@ +--- +title: Execute queries +seotitle: Different ways to query InfluxDB +description: There are multiple ways to query data from InfluxDB including the InfluxDB UI, CLI, and API. +weight: 103 +menu: + influxdb_cloud: + name: Execute queries + parent: Query data +influxdb/cloud/tags: [query] +--- + +There are multiple ways to execute queries with InfluxDB. Choose from the following options: + +{{< children >}} + + diff --git a/content/influxdb/cloud/query-data/execute-queries/data-explorer.md b/content/influxdb/cloud/query-data/execute-queries/data-explorer.md new file mode 100644 index 000000000..7c2c3c9d3 --- /dev/null +++ b/content/influxdb/cloud/query-data/execute-queries/data-explorer.md @@ -0,0 +1,13 @@ +--- +title: Query in Data Explorer +description: > + Query your data in the InfluxDB user interface (UI) Data Explorer. +weight: 201 +menu: + influxdb_cloud: + name: Query with Data Explorer + parent: Execute queries +influxdb/cloud/tags: [query] +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/execute-queries/flux-repl.md b/content/influxdb/cloud/query-data/execute-queries/flux-repl.md new file mode 100644 index 000000000..e7201c8c4 --- /dev/null +++ b/content/influxdb/cloud/query-data/execute-queries/flux-repl.md @@ -0,0 +1,12 @@ +--- +title: Query in the Flux REPL +description: Use the Flux REPL to query InfluxDB data. +weight: 203 +menu: + influxdb_cloud: + name: Query in the Flux REPL + parent: Execute queries +influxdb/cloud/tags: [query] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/query-data/execute-queries/influx-api.md b/content/influxdb/cloud/query-data/execute-queries/influx-api.md new file mode 100644 index 000000000..3973a99ca --- /dev/null +++ b/content/influxdb/cloud/query-data/execute-queries/influx-api.md @@ -0,0 +1,12 @@ +--- +title: Query with the InfluxDB API +description: Use the InfluxDB API to query InfluxDB data. +weight: 202 +menu: + influxdb_cloud: + name: Query with the InfluxDB API + parent: Execute queries +influxdb/cloud/tags: [query] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/query-data/execute-queries/influx-query.md b/content/influxdb/cloud/query-data/execute-queries/influx-query.md new file mode 100644 index 000000000..d45358957 --- /dev/null +++ b/content/influxdb/cloud/query-data/execute-queries/influx-query.md @@ -0,0 +1,12 @@ +--- +title: Use the `influx query` command +description: Use the influx CLI to query InfluxDB data. +weight: 204 +menu: + influxdb_cloud: + name: Use the influx CLI + parent: Execute queries +influxdb/cloud/tags: [query] +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/_index.md b/content/influxdb/cloud/query-data/flux/_index.md new file mode 100644 index 000000000..bc7b0aec1 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/_index.md @@ -0,0 +1,12 @@ +--- +title: Query data with Flux +description: Guides that walk through both common and complex queries and use cases for Flux. +weight: 102 +influxdb/cloud/tags: [flux, query] +menu: + influxdb_cloud: + name: Query with Flux + parent: Query data +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/query-data/flux/calculate-percentages.md b/content/influxdb/cloud/query-data/flux/calculate-percentages.md new file mode 100644 index 000000000..6b1bd38b0 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/calculate-percentages.md @@ -0,0 +1,21 @@ +--- +title: Calculate percentages with Flux +list_title: Calculate percentages +description: > + Use [`pivot()` or `join()`](/influxdb/cloud/query-data/flux/mathematic-operations/#pivot-vs-join) + and the [`map()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map/) + to align operand values into rows and calculate a percentage. +menu: + influxdb_cloud: + name: Calculate percentages + parent: Query with Flux +weight: 209 +related: + - /influxdb/cloud/query-data/flux/mathematic-operations + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/map + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/join +list_query_example: percentages +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/conditional-logic.md b/content/influxdb/cloud/query-data/flux/conditional-logic.md new file mode 100644 index 000000000..d56f4e499 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/conditional-logic.md @@ -0,0 +1,25 @@ +--- +title: Query using conditional logic +seotitle: Query using conditional logic in Flux +list_title: Conditional logic +description: > + This guide describes how to use Flux conditional expressions, such as `if`, + `else`, and `then`, to query and transform data. **Flux evaluates statements from left to right and stops evaluating once a condition matches.** +influxdb/cloud/tags: [conditionals, flux] +menu: + influxdb_cloud: + name: Conditional logic + parent: Query with Flux +weight: 220 +related: + - /influxdb/cloud/query-data/flux/query-fields/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/map/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/reduce/ +list_code_example: | + ```js + if color == "green" then "008000" else "ffffff" + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/cumulativesum.md b/content/influxdb/cloud/query-data/flux/cumulativesum.md new file mode 100644 index 000000000..7f389d827 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/cumulativesum.md @@ -0,0 +1,18 @@ +--- +title: Query cumulative sum +seotitle: Query cumulative sum in Flux +list_title: Cumulative sum +description: > + Use the `cumulativeSum()` function to calculate a running total of values. +weight: 210 +menu: + influxdb_cloud: + parent: Query with Flux + name: Cumulative sum +influxdb/cloud/tags: [query, cumulative sum] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/cumulativesum/ +list_query_example: cumulative_sum +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/custom-functions/_index.md b/content/influxdb/cloud/query-data/flux/custom-functions/_index.md new file mode 100644 index 000000000..55796dc9d --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/custom-functions/_index.md @@ -0,0 +1,22 @@ +--- +title: Create custom Flux functions +description: Create your own custom Flux functions to transform and manipulate data. +list_title: Custom functions +influxdb/cloud/tags: [functions, custom, flux] +menu: + influxdb_cloud: + name: Custom functions + parent: Query with Flux +weight: 220 +list_code_example: | + ```js + multByX = (tables=<-, x) => + tables + |> map(fn: (r) => ({ r with _value: r._value * x})) + + data + |> multByX(x: 2.0) + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/custom-functions/custom-aggregate.md b/content/influxdb/cloud/query-data/flux/custom-functions/custom-aggregate.md new file mode 100644 index 000000000..ffbc2bdd9 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/custom-functions/custom-aggregate.md @@ -0,0 +1,14 @@ +--- +title: Create custom aggregate functions +description: Create your own custom aggregate functions in Flux using the `reduce()` function. +influxdb/cloud/tags: [functions, custom, flux, aggregates] +menu: + influxdb_cloud: + name: Custom aggregate functions + parent: Custom functions +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/reduce/ +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/exists.md b/content/influxdb/cloud/query-data/flux/exists.md new file mode 100644 index 000000000..c331a3333 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/exists.md @@ -0,0 +1,25 @@ +--- +title: Check if a value exists +seotitle: Use Flux to check if a value exists +list_title: Exists +description: > + Use the Flux `exists` operator to check if a record contains a key or if that + key's value is `null`. +influxdb/cloud/tags: [exists] +menu: + influxdb_cloud: + name: Exists + parent: Query with Flux +weight: 220 +related: + - /influxdb/cloud/query-data/flux/query-fields/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/ +list_code_example: | + ##### Filter null values + ```js + data + |> filter(fn: (r) => exists r._value) + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/explore-schema.md b/content/influxdb/cloud/query-data/flux/explore-schema.md new file mode 100644 index 000000000..e592bed32 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/explore-schema.md @@ -0,0 +1,43 @@ +--- +title: Explore your data schema with Flux +list_title: Explore your schema +description: > + Flux provides functions that let you explore the structure and schema of your + data stored in InfluxDB. +influxdb/cloud/tags: [schema] +menu: + influxdb_cloud: + name: Explore your schema + parent: Query with Flux +weight: 206 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/inputs/buckets/ + - /influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurements + - /influxdb/cloud/reference/flux/stdlib/influxdb-v1/fieldkeys + - /influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementfieldkeys + - /influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagkeys + - /influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagkeys + - /influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagvalues + - /influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagvalues +list_code_example: | + ```js + import "influxdata/influxdb/v1" + + // List buckets + buckets() + + // List measurements + v1.measurements(bucket: "example-bucket") + + // List field keys + v1.fieldKeys(bucket: "example-bucket") + + // List tag keys + v1.tagKeys(bucket: "example-bucket") + + // List tag values + v1.tagValues(bucket: "example-bucket", tag: "example-tag") + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/fill.md b/content/influxdb/cloud/query-data/flux/fill.md new file mode 100644 index 000000000..8b1a8f7b5 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/fill.md @@ -0,0 +1,19 @@ +--- +title: Fill null values in data +seotitle: Fill null values in data +list_title: Fill +description: > + Use the [`fill()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/fill/) + to replace _null_ values. +weight: 210 +menu: + influxdb_cloud: + parent: Query with Flux + name: Fill +influxdb/cloud/tags: [query, fill] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/fill/ +list_query_example: fill_null +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/first-last.md b/content/influxdb/cloud/query-data/flux/first-last.md new file mode 100644 index 000000000..b3c6868e5 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/first-last.md @@ -0,0 +1,21 @@ +--- +title: Query first and last values +seotitle: Query first and last values in Flux +list_title: First and last +description: > + Use the [`first()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/first/) or + [`last()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/last/) functions + to return the first or last point in an input table. +weight: 210 +menu: + influxdb_cloud: + parent: Query with Flux + name: First & last +influxdb/cloud/tags: [query] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/first/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/last/ +list_query_example: first_last +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/geo/_index.md b/content/influxdb/cloud/query-data/flux/geo/_index.md new file mode 100644 index 000000000..803efc97e --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/geo/_index.md @@ -0,0 +1,21 @@ +--- +title: Work with geo-temporal data +list_title: Geo-temporal data +description: > + Use the Flux Geo package to filter geo-temporal data and group by geographic location or track. +menu: + influxdb_cloud: + name: Geo-temporal data + parent: Query with Flux +weight: 220 +list_code_example: | + ```js + import "experimental/geo" + + sampleGeoData + |> geo.filterRows(region: {lat: 30.04, lon: 31.23, radius: 200.0}) + |> geo.groupByArea(newColumn: "geoArea", level: 5) + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/geo/filter-by-region.md b/content/influxdb/cloud/query-data/flux/geo/filter-by-region.md new file mode 100644 index 000000000..500b5fea7 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/geo/filter-by-region.md @@ -0,0 +1,25 @@ +--- +title: Filter geo-temporal data by region +description: > + Use the `geo.filterRows` function to filter geo-temporal data by box-shaped, circular, or polygonal geographic regions. +menu: + influxdb_cloud: + name: Filter by region + parent: Geo-temporal data +weight: 302 +related: + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/filterrows/ +list_code_example: | + ```js + import "experimental/geo" + + sampleGeoData + |> geo.filterRows( + region: {lat: 30.04, lon: 31.23, radius: 200.0}, + strict: true + ) + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/geo/group-geo-data.md b/content/influxdb/cloud/query-data/flux/geo/group-geo-data.md new file mode 100644 index 000000000..4d12cf4e7 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/geo/group-geo-data.md @@ -0,0 +1,24 @@ +--- +title: Group geo-temporal data +description: > + Use the `geo.groupByArea()` to group geo-temporal data by area and `geo.asTracks()` + to group data into tracks or routes. +menu: + influxdb_cloud: + parent: Geo-temporal data +weight: 302 +related: + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/groupbyarea/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/astracks/ +list_code_example: | + ```js + import "experimental/geo" + + sampleGeoData + |> geo.groupByArea(newColumn: "geoArea", level: 5) + |> geo.asTracks(groupBy: ["id"],sortBy: ["_time"]) + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/geo/shape-geo-data.md b/content/influxdb/cloud/query-data/flux/geo/shape-geo-data.md new file mode 100644 index 000000000..d862211b9 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/geo/shape-geo-data.md @@ -0,0 +1,32 @@ +--- +title: Shape data to work with the Geo package +description: > + Functions in the Flux Geo package require **lat** and **lon** fields and an **s2_cell_id** tag. + Rename latitude and longitude fields and generate S2 cell ID tokens. +menu: + influxdb_cloud: + name: Shape geo-temporal data + parent: Geo-temporal data +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/shapedata/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/s2cellidtoken/ +list_code_example: | + ```js + import "experimental/geo" + + sampleGeoData + |> map(fn: (r) => ({ r with + _field: + if r._field == "latitude" then "lat" + else if r._field == "longitude" then "lon" + else r._field + })) + |> map(fn: (r) => ({ r with + s2_cell_id: geo.s2CellIDToken(point: {lon: r.lon, lat: r.lat}, level: 10) + })) + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/group-data.md b/content/influxdb/cloud/query-data/flux/group-data.md new file mode 100644 index 000000000..0d17e8a30 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/group-data.md @@ -0,0 +1,19 @@ +--- +title: Group data in InfluxDB with Flux +list_title: Group +description: > + Use the [`group()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group) + to group data with common values in specific columns. +influxdb/cloud/tags: [group] +menu: + influxdb_cloud: + name: Group + parent: Query with Flux +weight: 202 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/group + - /influxdb/cloud/reference/flux/stdlib/experimental/group +list_query_example: group +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/histograms.md b/content/influxdb/cloud/query-data/flux/histograms.md new file mode 100644 index 000000000..38e943d2d --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/histograms.md @@ -0,0 +1,18 @@ +--- +title: Create histograms with Flux +list_title: Histograms +description: > + Use the [`histogram()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/histogram/) + to create cumulative histograms with Flux. +influxdb/cloud/tags: [histogram] +menu: + influxdb_cloud: + name: Histograms + parent: Query with Flux +weight: 210 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/histogram +list_query_example: histogram +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/increase.md b/content/influxdb/cloud/query-data/flux/increase.md new file mode 100644 index 000000000..d63caa283 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/increase.md @@ -0,0 +1,21 @@ +--- +title: Calculate the increase +seotitle: Calculate the increase in Flux +list_title: Increase +description: > + Use the [`increase()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/increase/) + to track increases across multiple columns in a table. + This function is especially useful when tracking changes in counter values that + wrap over time or periodically reset. +weight: 210 +menu: + influxdb_cloud: + parent: Query with Flux + name: Increase +influxdb/cloud/tags: [query, increase, counters] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/increase/ +list_query_example: increase +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/join.md b/content/influxdb/cloud/query-data/flux/join.md new file mode 100644 index 000000000..e31d7b416 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/join.md @@ -0,0 +1,17 @@ +--- +title: Join data with Flux +seotitle: Join data in InfluxDB with Flux +list_title: Join +description: This guide walks through joining data with Flux and outlines how it shapes your data in the process. +influxdb/cloud/tags: [join, flux] +menu: + influxdb_cloud: + name: Join + parent: Query with Flux +weight: 210 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/join +list_query_example: join +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/manipulate-timestamps.md b/content/influxdb/cloud/query-data/flux/manipulate-timestamps.md new file mode 100644 index 000000000..173e05e95 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/manipulate-timestamps.md @@ -0,0 +1,23 @@ +--- +title: Manipulate timestamps with Flux +list_title: Manipulate timestamps +description: > + Use Flux to process and manipulate timestamps. +menu: + influxdb_cloud: + name: Manipulate timestamps + parent: Query with Flux +weight: 220 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/misc/now/ + - /influxdb/cloud/reference/flux/stdlib/system/time/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/time/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/uint/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/int/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/truncatetimecolumn/ + - /influxdb/cloud/reference/flux/stdlib/date/truncate/ + - /influxdb/cloud/reference/flux/stdlib/experimental/addduration/ + - /influxdb/cloud/reference/flux/stdlib/experimental/subduration/ +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/mathematic-operations.md b/content/influxdb/cloud/query-data/flux/mathematic-operations.md new file mode 100644 index 000000000..70d0234a7 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/mathematic-operations.md @@ -0,0 +1,23 @@ +--- +title: Transform data with mathematic operations +seotitle: Transform data with mathematic operations in Flux +list_title: Transform data with math +description: > + Use the [`map()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map) + to remap column values and apply mathematic operations. +influxdb/cloud/tags: [math, flux] +menu: + influxdb_cloud: + name: Transform data with math + parent: Query with Flux +weight: 208 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/map + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/reduce/ + - /influxdb/cloud/reference/flux/language/operators/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/ + - /influxdb/cloud/query-data/flux/calculate-percentages/ +list_query_example: map_math +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/median.md b/content/influxdb/cloud/query-data/flux/median.md new file mode 100644 index 000000000..6f3a9e552 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/median.md @@ -0,0 +1,21 @@ +--- +title: Find median values +seotitle: Find median values in Flux +list_title: Median +description: > + Use the [`median()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/median/) + to return a value representing the `0.5` quantile (50th percentile) or median of input data. +weight: 210 +menu: + influxdb_cloud: + parent: Query with Flux + name: Median +influxdb/cloud/tags: [query, median] +related: + - /influxdb/cloud/query-data/flux/percentile-quantile/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/median/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/quantile/ +list_query_example: median +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/monitor-states.md b/content/influxdb/cloud/query-data/flux/monitor-states.md new file mode 100644 index 000000000..5a3a7c9c3 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/monitor-states.md @@ -0,0 +1,16 @@ +--- +title: Monitor states +seotitle: Monitor states and state changes in your events and metrics with Flux. +description: Flux provides several functions to help monitor states and state changes in your data. +influxdb/cloud/tags: [states, monitor, flux] +menu: + influxdb_cloud: + name: Monitor states + parent: Query with Flux +weight: 220 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/stateduration/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/statecount/ +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/moving-average.md b/content/influxdb/cloud/query-data/flux/moving-average.md new file mode 100644 index 000000000..013fcd38a --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/moving-average.md @@ -0,0 +1,21 @@ +--- +title: Calculate the moving average +seotitle: Calculate the moving average in Flux +list_title: Moving Average +description: > + Use the [`movingAverage()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage/) + or [`timedMovingAverage()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage/) + functions to return the moving average of data. +weight: 210 +menu: + influxdb_cloud: + parent: Query with Flux + name: Moving Average +influxdb/cloud/tags: [query, moving average] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/timedmovingaverage/ +list_query_example: moving_average +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/percentile-quantile.md b/content/influxdb/cloud/query-data/flux/percentile-quantile.md new file mode 100644 index 000000000..0abd96647 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/percentile-quantile.md @@ -0,0 +1,20 @@ +--- +title: Find percentile and quantile values +seotitle: Query percentile and quantile values in Flux +list_title: Percentile & quantile +description: > + Use the `quantile()` function to return all values within the `q` quantile or + percentile of input data. +weight: 210 +menu: + influxdb_cloud: + parent: Query with Flux + name: Percentile & quantile +influxdb/cloud/tags: [query, percentile, quantile] +related: + - /influxdb/cloud/query-data/flux/query-median/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/quantile/ +list_query_example: quantile +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/query-fields.md b/content/influxdb/cloud/query-data/flux/query-fields.md new file mode 100644 index 000000000..d19a0b813 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/query-fields.md @@ -0,0 +1,29 @@ +--- +title: Query fields and tags +seotitle: Query fields and tags in InfluxDB using Flux +description: > + Use the [`filter()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/) to query data based on fields, tags, or any other column value. + `filter()` performs operations similar to the `SELECT` statement and the `WHERE` + clause in InfluxQL and other SQL-like query languages. +weight: 201 +menu: + influxdb_cloud: + parent: Query with Flux +influxdb/cloud/tags: [query, select, where] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/ + - /influxdb/cloud/query-data/flux/conditional-logic/ + - /influxdb/cloud/query-data/flux/regular-expressions/ +list_code_example: | + ```js + from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "example-measurement" and + r._field == "example-field" and + r.tag == "example-tag" + ) + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/rate.md b/content/influxdb/cloud/query-data/flux/rate.md new file mode 100644 index 000000000..8b3417d97 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/rate.md @@ -0,0 +1,24 @@ +--- +title: Calculate the rate of change +seotitle: Calculate the rate of change in Flux +list_title: Rate +description: > + Use the [`derivative()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/derivative/) + to calculate the rate of change between subsequent values or the + [`aggregate.rate()` function](/influxdb/cloud/reference/flux/stdlib/experimental/aggregate/rate/) + to calculate the average rate of change per window of time. + If time between points varies, these functions normalize points to a common time interval + making values easily comparable. +weight: 210 +menu: + influxdb_cloud: + parent: Query with Flux + name: Rate +influxdb/cloud/tags: [query, rate] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/derivative/ + - /influxdb/cloud/reference/flux/stdlib/experimental/aggregate/rate/ +list_query_example: rate_of_change +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/regular-expressions.md b/content/influxdb/cloud/query-data/flux/regular-expressions.md new file mode 100644 index 000000000..37100f361 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/regular-expressions.md @@ -0,0 +1,17 @@ +--- +title: Use regular expressions in Flux +list_title: Regular expressions +description: This guide walks through using regular expressions in evaluation logic in Flux functions. +influxdb/cloud/tags: [regex] +menu: + influxdb_cloud: + name: Regular expressions + parent: Query with Flux +weight: 220 +related: + - /influxdb/cloud/query-data/flux/query-fields/ + - /influxdb/cloud/reference/flux/stdlib/regexp/ +list_query_example: regular_expressions +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/scalar-values.md b/content/influxdb/cloud/query-data/flux/scalar-values.md new file mode 100644 index 000000000..d07fcb6a4 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/scalar-values.md @@ -0,0 +1,27 @@ +--- +title: Extract scalar values in Flux +list_title: Extract scalar values +description: > + Use Flux stream and table functions to extract scalar values from Flux query output. + This lets you, for example, dynamically set variables using query results. +menu: + influxdb_cloud: + name: Extract scalar values + parent: Query with Flux +weight: 220 +influxdb/cloud/tags: [scalar] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/ +list_code_example: | + ```js + scalarValue = { + _record = + data + |> tableFind(fn: key => true) + |> getRecord(idx: 0) + return _record._value + } + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/sort-limit.md b/content/influxdb/cloud/query-data/flux/sort-limit.md new file mode 100644 index 000000000..163e4c91f --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/sort-limit.md @@ -0,0 +1,22 @@ +--- +title: Sort and limit data with Flux +seotitle: Sort and limit data in InfluxDB with Flux +list_title: Sort and limit +description: > + Use the [`sort()`function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/sort) + to order records within each table by specific columns and the + [`limit()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/limit) + to limit the number of records in output tables to a fixed number, `n`. +influxdb/cloud/tags: [sort, limit] +menu: + influxdb_cloud: + name: Sort and limit + parent: Query with Flux +weight: 203 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/sort + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/limit +list_query_example: sort_limit +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/sql.md b/content/influxdb/cloud/query-data/flux/sql.md new file mode 100644 index 000000000..539bb13e5 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/sql.md @@ -0,0 +1,29 @@ +--- +title: Query SQL data sources +seotitle: Query SQL data sources with InfluxDB +list_title: Query SQL data +description: > + The Flux `sql` package provides functions for working with SQL data sources. + Use `sql.from()` to query SQL databases like PostgreSQL, MySQL, Snowflake, + SQLite, Microsoft SQL Server, Amazon Athena, and Google BigQuery. +influxdb/cloud/tags: [query, flux, sql] +menu: + influxdb_cloud: + parent: Query with Flux + list_title: SQL data +weight: 220 +related: + - /influxdb/cloud/reference/flux/stdlib/sql/ +list_code_example: | + ```js + import "sql" + + sql.from( + driverName: "postgres", + dataSourceName: "postgresql://user:password@localhost", + query: "SELECT * FROM example_table" + ) + ``` +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/flux/window-aggregate.md b/content/influxdb/cloud/query-data/flux/window-aggregate.md new file mode 100644 index 000000000..fbfd4dfb7 --- /dev/null +++ b/content/influxdb/cloud/query-data/flux/window-aggregate.md @@ -0,0 +1,22 @@ +--- +title: Window and aggregate data with Flux +seotitle: Window and aggregate data in InfluxDB with Flux +list_title: Window & aggregate +description: > + This guide walks through windowing and aggregating data with Flux and outlines + how it shapes your data in the process. +menu: + influxdb_cloud: + name: Window & aggregate + parent: Query with Flux +weight: 204 +influxdb/cloud/tags: [flux, aggregates] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/window + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors +list_query_example: aggregate_window +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/get-started/_index.md b/content/influxdb/cloud/query-data/get-started/_index.md new file mode 100644 index 000000000..8e45d79e0 --- /dev/null +++ b/content/influxdb/cloud/query-data/get-started/_index.md @@ -0,0 +1,90 @@ +--- +title: Get started with Flux +description: > + Get started with Flux, InfluxData's functional data scripting language. + This step-by-step guide through the basics of writing a Flux query. +weight: 101 +influxdb/cloud/tags: [query, flux, get-started] +menu: + influxdb_cloud: + name: Get started with Flux + parent: Query data +related: + - /influxdb/cloud/reference/flux/ + - /influxdb/cloud/reference/flux/stdlib/ +--- + +Flux is InfluxData's functional data scripting language designed for querying, +analyzing, and acting on data. + +This multi-part getting started guide walks through important concepts related to Flux. +It covers querying time series data from InfluxDB using Flux, and introduces Flux syntax and functions. + +## Flux design principles +Flux is designed to be usable, readable, flexible, composable, testable, contributable, and shareable. +Its syntax is largely inspired by [2018's most popular scripting language](https://insights.stackoverflow.com/survey/2018#technology), +Javascript, and takes a functional approach to data exploration and processing. + +The following example illustrates querying data stored from the last hour, +filtering by the `cpu` measurement and the `cpu=cpu-total` tag, windowing the data in 1 minute intervals, +and calculating the average of each window: + +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn:(r) => + r._measurement == "cpu" and + r.cpu == "cpu-total" + ) + |> aggregateWindow(every: 1m, fn: mean) +``` + +## Key concepts +Flux introduces important new concepts you should understand as you get started. + +### Pipe-forward operator +Flux uses pipe-forward operators (`|>`) extensively to chain operations together. +After each function or operation, Flux returns a table or collection of tables containing data. +The pipe-forward operator pipes those tables into the next function or operation where +they are further processed or manipulated. +This makes it easy to chain together functions to build sophisticated queries. + +### Tables +Flux structures all data in tables. +When data is streamed from data sources, Flux formats it as annotated +comma-separated values (CSV), representing tables. +Functions then manipulate or process them and output new tables. + +#### Group keys +Every table has a **group key** which describes the contents of the table. +It's a list of columns for which every row in the table will have the same value. +Columns with unique values in each row are **not** part of the group key. + +As functions process and transform data, each modifies the group keys of output tables. +Understanding how tables and group keys are modified by functions is key to properly +shaping your data for the desired output. + +###### Example group key +```js +Group key: [_start, _stop, _field] + _start:time _stop:time _field:string _time:time _value:float +------------------------------ ------------------------------ ---------------------- ------------------------------ ---------------------------- +2019-04-25T17:33:55.196959000Z 2019-04-25T17:34:55.196959000Z used_percent 2019-04-25T17:33:56.000000000Z 65.55318832397461 +2019-04-25T17:33:55.196959000Z 2019-04-25T17:34:55.196959000Z used_percent 2019-04-25T17:34:06.000000000Z 65.52391052246094 +2019-04-25T17:33:55.196959000Z 2019-04-25T17:34:55.196959000Z used_percent 2019-04-25T17:34:16.000000000Z 65.49603939056396 +2019-04-25T17:33:55.196959000Z 2019-04-25T17:34:55.196959000Z used_percent 2019-04-25T17:34:26.000000000Z 65.51754474639893 +2019-04-25T17:33:55.196959000Z 2019-04-25T17:34:55.196959000Z used_percent 2019-04-25T17:34:36.000000000Z 65.536737442016 +``` + +Note that `_time` and `_value` are excluded from the example group key because they +are unique to each row. + +## Tools for working with Flux + +The [Execute queries](/influxdb/cloud/query-data/execute-queries) guide walks through +the different tools available for querying InfluxDB with Flux. + +
+ + +
diff --git a/content/influxdb/cloud/query-data/get-started/query-influxdb.md b/content/influxdb/cloud/query-data/get-started/query-influxdb.md new file mode 100644 index 000000000..07b7b60d9 --- /dev/null +++ b/content/influxdb/cloud/query-data/get-started/query-influxdb.md @@ -0,0 +1,137 @@ +--- +title: Query InfluxDB with Flux +description: Learn the basics of using Flux to query data from InfluxDB. +influxdb/cloud/tags: [query, flux] +menu: + influxdb_cloud: + name: Query InfluxDB + parent: Get started with Flux +weight: 201 +related: + - /influxdb/cloud/query-data/flux/ + - /influxdb/cloud/reference/flux/stdlib/built-in/inputs/from + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/range + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter +--- + +This guide walks through the basics of using Flux to query data from InfluxDB. +Every Flux query needs the following: + +1. [A data source](#1-define-your-data-source) +2. [A time range](#2-specify-a-time-range) +3. [Data filters](#3-filter-your-data) + + +## 1. Define your data source +Flux's [`from()`](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from) function defines an InfluxDB data source. +It requires a [`bucket`](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from#bucket) parameter. +The following examples use `example-bucket` as the bucket name. + +```js +from(bucket:"example-bucket") +``` + +## 2. Specify a time range +Flux requires a time range when querying time series data. +"Unbounded" queries are very resource-intensive and as a protective measure, +Flux will not query the database without a specified range. + +Use the pipe-forward operator (`|>`) to pipe data from your data source into the [`range()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range) +function, which specifies a time range for your query. +It accepts two parameters: `start` and `stop`. +Ranges can be **relative** using negative [durations](/influxdb/cloud/reference/flux/language/lexical-elements#duration-literals) +or **absolute** using [timestamps](/influxdb/cloud/reference/flux/language/lexical-elements#date-and-time-literals). + +###### Example relative time ranges +```js +// Relative time range with start only. Stop defaults to now. +from(bucket:"example-bucket") + |> range(start: -1h) + +// Relative time range with start and stop +from(bucket:"example-bucket") + |> range(start: -1h, stop: -10m) +``` + +{{% note %}} +Relative ranges are relative to "now." +{{% /note %}} + +###### Example absolute time range +```js +from(bucket:"example-bucket") + |> range(start: 2018-11-05T23:30:00Z, stop: 2018-11-06T00:00:00Z) +``` + +#### Use the following: +For this guide, use the relative time range, `-15m`, to limit query results to data from the last 15 minutes: + +```js +from(bucket:"example-bucket") + |> range(start: -15m) +``` + +## 3. Filter your data +Pass your ranged data into the `filter()` function to narrow results based on data attributes or columns. +The `filter()` function has one parameter, `fn`, which expects an anonymous function +with logic that filters data based on columns or attributes. + +Flux's anonymous function syntax is similar to Javascript's. +Records or rows are passed into the `filter()` function as a record (`r`). +The anonymous function takes the record and evaluates it to see if it matches the defined filters. +Use the `and` relational operator to chain multiple filters. + +```js +// Pattern +(r) => (r.recordProperty comparisonOperator comparisonExpression) + +// Example with single filter +(r) => (r._measurement == "cpu") + +// Example with multiple filters +(r) => (r._measurement == "cpu") and (r._field != "usage_system" ) +``` + +#### Use the following: +For this example, filter by the `cpu` measurement, the `usage_system` field, and the `cpu-total` tag value: + +```js +from(bucket:"example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) +``` + +## 4. Yield your queried data +Flux's `yield()` function outputs the filtered tables as the result of the query. + +```js +from(bucket:"example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> yield() +``` + +Flux automatically assumes a `yield()` function at +the end of each script in order to output and visualize the data. +Explicitly calling `yield()` is only necessary when including multiple queries in the same Flux query. +Each set of returned data needs to be named using the `yield()` function. + +## Congratulations! +You have now queried data from InfluxDB using Flux. + +The query shown here is a barebones example. +Flux queries can be extended in many ways to form powerful scripts. + + +
+ + +
diff --git a/content/influxdb/cloud/query-data/get-started/syntax-basics.md b/content/influxdb/cloud/query-data/get-started/syntax-basics.md new file mode 100644 index 000000000..af809b203 --- /dev/null +++ b/content/influxdb/cloud/query-data/get-started/syntax-basics.md @@ -0,0 +1,236 @@ +--- +title: Flux syntax basics +description: An introduction to the basic elements of the Flux syntax with real-world application examples. +influxdb/cloud/tags: [flux, syntax] +menu: + influxdb_cloud: + name: Syntax basics + parent: Get started with Flux +weight: 203 +related: + - /influxdb/cloud/reference/flux/language/types/ +--- + + +Flux, at its core, is a scripting language designed specifically for working with data. +This guide walks through a handful of simple expressions and how they are handled in Flux. + +## Use the Flux REPL +Use the [Flux REPL](/influxdb/cloud/tools/repl/) to open the interactive Read-Eval-Print Loop (REPL). +Run the commands provided in this guide in the REPL. + +##### Start the Flux REPL +```bash +./flux repl +``` + +## Basic Flux syntax +The code blocks below provide commands that illustrate the basic syntax of Flux. +Run these commands in the REPL. + +### Simple expressions +Flux is a scripting language that supports basic expressions. +For example, simple addition: + +```js +> 1 + 1 +2 +``` + +### Variables +Assign an expression to a variable using the assignment operator, `=`. + +```js +> s = "this is a string" +> i = 1 // an integer +> f = 2.0 // a floating point number +``` + +Type the name of a variable to print its value: + +```js +> s +this is a string +> i +1 +> f +2 +``` + +### Records +Flux also supports records. Each value in a record can be a different data type. + +```js +> o = {name:"Jim", age: 42, "favorite color": "red"} +``` + +Use **dot notation** to access a properties of a record: + +```js +> o.name +Jim +> o.age +42 +``` + +Or **bracket notation**: + +```js +> o["name"] +Jim +> o["age"] +42 +> o["favorite color"] +red +``` + +{{% note %}} +Use bracket notation to reference record properties with special or +white space characters in the property key. +{{% /note %}} + +### Arrays +Flux supports arrays. All values in an array must be the same type. + +```js +> n = 4 +> l = [1,2,3,n] +> l +[1, 2, 3, 4] +``` + +### Functions +Flux uses functions for most of its heavy lifting. +Below is a simple function that squares a number, `n`. + +```js +> square = (n) => n * n +> square(n:3) +9 +``` + +{{% note %}} +Flux does not support positional arguments or parameters. +Parameters must always be named when calling a function. +{{% /note %}} + +### Pipe-forward operator +Flux uses the pipe-forward operator (`|>`) extensively to chain operations together. +After each function or operation, Flux returns a table or collection of tables containing data. +The pipe-forward operator pipes those tables into the next function where they are further processed or manipulated. + +```js +data |> someFunction() |> anotherFunction() +``` + +## Real-world application of basic syntax +This likely seems familiar if you've already been through through the other +[getting started guides](/influxdb/cloud/query-data/get-started). +Flux's syntax is inspired by Javascript and other functional scripting languages. +As you begin to apply these basic principles in real-world use cases such as creating data stream variables, +custom functions, etc., the power of Flux and its ability to query and process data will become apparent. + +The examples below provide both multi-line and single-line versions of each input command. +Carriage returns in Flux aren't necessary, but do help with readability. +Both single- and multi-line commands can be copied and pasted into the `influx` CLI running in Flux mode. + +### Define data stream variables +A common use case for variable assignments in Flux is creating variables for one +or more input data streams. + +{{< code-tabs-wrapper >}} + {{% code-tabs %}} + [Multi-line](#) + [Single-line](#) + {{% /code-tabs %}} +{{% code-tab-content %}} +```js +timeRange = -1h + +cpuUsageUser = + from(bucket:"example-bucket") + |> range(start: timeRange) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_user" and + r.cpu == "cpu-total" + ) + +memUsagePercent = + from(bucket:"example-bucket") + |> range(start: timeRange) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```js +timeRange = -1h +cpuUsageUser = from(bucket:"example-bucket") |> range(start: timeRange) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user" and r.cpu == "cpu-total") +memUsagePercent = from(bucket:"example-bucket") |> range(start: timeRange) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper>}} + +These variables can be used in other functions, such as `join()`, while keeping the syntax minimal and flexible. + +### Define custom functions +Create a function that returns the `N` number rows in the input stream with the highest `_value`s. +To do this, pass the input stream (`tables`) and the number of results to return (`n`) into a custom function. +Then using Flux's `sort()` and `limit()` functions to find the top `n` results in the data set. + +{{< code-tabs-wrapper >}} + {{% code-tabs %}} + [Multi-line](#) + [Single-line](#) + {{% /code-tabs %}} +{{% code-tab-content %}} +```js +topN = (tables=<-, n) => + tables + |> sort(desc: true) + |> limit(n: n) +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +topN = (tables=<-, n) => tables |> sort(desc: true) |> limit(n: n) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Using this new custom function `topN` and the `cpuUsageUser` data stream variable defined above, +we can find the top five data points and yield the results. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Multi-line](#) +[Single-line](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```js +cpuUsageUser + |> topN(n:5) + |> yield() +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```js +cpuUsageUser |> topN(n:5) |> yield() +``` +{{% /code-tab-content %}} + +{{< /code-tabs-wrapper>}} + +This query will return the five data points with the highest user CPU usage over the last hour. + +_More information about creating custom functions is available in the [Custom functions](/influxdb/cloud/query-data/flux/custom-functions) documentation._ + +
+ +
diff --git a/content/influxdb/cloud/query-data/get-started/transform-data.md b/content/influxdb/cloud/query-data/get-started/transform-data.md new file mode 100644 index 000000000..b458fbdc2 --- /dev/null +++ b/content/influxdb/cloud/query-data/get-started/transform-data.md @@ -0,0 +1,187 @@ +--- +title: Transform data with Flux +description: Learn the basics of using Flux to transform data queried from InfluxDB. +influxdb/cloud/tags: [flux, transform, query] +menu: + influxdb_cloud: + name: Transform data + parent: Get started with Flux +weight: 202 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/window +--- + +When [querying data from InfluxDB](/influxdb/cloud/query-data/get-started/query-influxdb), +you often need to transform that data in some way. +Common examples are aggregating data into averages, downsampling data, etc. + +This guide demonstrates using [Flux functions](/influxdb/cloud/reference/flux/stdlib) to transform your data. +It walks through creating a Flux script that partitions data into windows of time, +averages the `_value`s in each window, and outputs the averages as a new table. +(Remember, Flux structures all data in [tables](/influxdb/cloud/query-data/get-started/#tables).) + +It's important to understand how the "shape" of your data changes through each of these operations. + +## Query data +Use the query built in the previous [Query data from InfluxDB](/influxdb/cloud/query-data/get-started/query-influxdb) +guide, but update the range to pull data from the last hour: + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) +``` + +## Flux functions +Flux provides a number of functions that perform specific operations, transformations, and tasks. +You can also [create custom functions](/influxdb/cloud/query-data/flux/custom-functions) in your Flux queries. +_Functions are covered in detail in the [Flux functions](/influxdb/cloud/reference/flux/stdlib) documentation._ + +A common type of function used when transforming data queried from InfluxDB is an aggregate function. +Aggregate functions take a set of `_value`s in a table, aggregate them, and transform +them into a new value. + +This example uses the [`mean()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean) +to average values within each time window. + +{{% note %}} +The following example walks through the steps required to window and aggregate data, +but there is a [`aggregateWindow()` helper function](#helper-functions) that does it for you. +It's just good to understand the steps in the process. +{{% /note %}} + +## Window your data +Flux's [`window()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window) partitions records based on a time value. +Use the `every` parameter to define a duration of each window. + +{{% note %}} +#### Calendar months and years +`every` supports all [valid duration units](/influxdb/cloud/reference/flux/language/types/#duration-types), +including **calendar months (`1mo`)** and **years (`1y`)**. +{{% /note %}} + +For this example, window data in five minute intervals (`5m`). + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> window(every: 5m) +``` + +As data is gathered into windows of time, each window is output as its own table. +When visualized, each table is assigned a unique color. + +![Windowed data tables](/img/flux/windowed-data.png) + +## Aggregate windowed data +Flux aggregate functions take the `_value`s in each table and aggregate them in some way. +Use the [`mean()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean) to average the `_value`s of each table. + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> window(every: 5m) + |> mean() +``` + +As rows in each window are aggregated, their output table contains only a single row with the aggregate value. +Windowed tables are all still separate and, when visualized, will appear as single, unconnected points. + +![Windowed aggregate data](/img/flux/windowed-aggregates.png) + +## Add times to your aggregates +As values are aggregated, the resulting tables do not have a `_time` column because +the records used for the aggregation all have different timestamps. +Aggregate functions don't infer what time should be used for the aggregate value. +Therefore the `_time` column is dropped. + +A `_time` column is required in the [next operation](#unwindow-aggregate-tables). +To add one, use the [`duplicate()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/duplicate) +to duplicate the `_stop` column as the `_time` column for each windowed table. + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> window(every: 5m) + |> mean() + |> duplicate(column: "_stop", as: "_time") +``` + +## Unwindow aggregate tables + +Use the `window()` function with the `every: inf` parameter to gather all points +into a single, infinite window. + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> window(every: 5m) + |> mean() + |> duplicate(column: "_stop", as: "_time") + |> window(every: inf) +``` + +Once ungrouped and combined into a single table, the aggregate data points will appear connected in your visualization. + +![Unwindowed aggregate data](/img/flux/windowed-aggregates-ungrouped.png) + +## Helper functions +This may seem like a lot of coding just to build a query that aggregates data, however going through the +process helps to understand how data changes "shape" as it is passed through each function. + +Flux provides (and allows you to create) "helper" functions that abstract many of these steps. +The same operation performed in this guide can be accomplished using the +[`aggregateWindow()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow). + +```js +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> aggregateWindow(every: 5m, fn: mean) +``` + +## Congratulations! +You have now constructed a Flux query that uses Flux functions to transform your data. +There are many more ways to manipulate your data using both Flux's primitive functions +and your own custom functions, but this is a good introduction into the basic syntax and query structure. + +--- + +_For a deeper dive into windowing and aggregating data with example data output for each transformation, +view the [Window and aggregate data](/influxdb/cloud/query-data/flux/window-aggregate) guide._ + +--- + +
+ + +
diff --git a/content/influxdb/cloud/query-data/influxql.md b/content/influxdb/cloud/query-data/influxql.md new file mode 100644 index 000000000..0b54eda9f --- /dev/null +++ b/content/influxdb/cloud/query-data/influxql.md @@ -0,0 +1,18 @@ +--- +title: Query data with InfluxQL +description: > + Use the [InfluxDB 1.x `/query` compatibility endpoint](/influxdb/cloud/reference/api/influxdb-1x/query) + to query data in InfluxDB Cloud with **InfluxQL**. +weight: 102 +influxdb/cloud/tags: [influxql, query] +menu: + influxdb_cloud: + name: Query with InfluxQL + parent: Query data +related: + - /influxdb/cloud/reference/api/influxdb-1x/ + - /influxdb/cloud/reference/api/influxdb-1x/query + - /influxdb/cloud/reference/api/influxdb-1x/dbrp +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/optimize-queries.md b/content/influxdb/cloud/query-data/optimize-queries.md new file mode 100644 index 000000000..916606ffe --- /dev/null +++ b/content/influxdb/cloud/query-data/optimize-queries.md @@ -0,0 +1,78 @@ +--- +title: Optimize Flux queries +description: > + Optimize your Flux queries to reduce their memory and compute (CPU) requirements. +weight: 104 +menu: + influxdb_cloud: + name: Optimize queries + parent: Query data +influxdb/cloud/tags: [query] +--- + +Optimize your Flux queries to reduce their memory and compute (CPU) requirements. + +- [Start queries with pushdown functions](#start-queries-with-pushdown-functions) +- [Avoid short window durations](#avoid-short-window-durations) +- [Use "heavy" functions sparingly](#use-heavy-functions-sparingly) +- [Balance time range and data precision](#balance-time-range-and-data-precision) + +## Start queries with pushdown functions +Some Flux functions can push their data manipulation down to the underlying +data source rather than storing and manipulating data in memory. +These are known as "pushdown" functions and using them correctly can greatly +reduce the amount of memory necessary to run a query. + +#### Pushdown functions +- [range()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range/) +- [filter()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/) +- [group()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group/) +- [count()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/count/) +- [sum()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/sum/) +- [first()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/first/) +- [last()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/last/) + +Use pushdown functions at the beginning of your query. +Once a non-pushdown function runs, Flux pulls data into memory and runs all +subsequent operations there. + +##### Pushdown functions in use +```js +from(bucket: "example-bucket") + |> range(start: -1h) // + |> filter(fn: (r) => r.sensor == "abc123") // Pushed to the data source + |> group(columns: ["_field", "host"]) // + + |> aggregateWindow(every: 5m, fn: max) // + |> filter(fn: (r) => r._value >= 90.0) // Run in memory + |> top(n: 10) // +``` + +## Avoid short window durations +Windowing (grouping data based on time intervals) is commonly used to aggregate and downsample data. +Increase performance by avoiding short window durations. +More windows require more compute power to evaluate which window each row should be assigned to. +Reasonable window durations depend on the total time range queried. + +## Use "heavy" functions sparingly +The following functions use more memory or CPU than others. +Consider their necessity in your data processing before using them: + +- [map()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map/) +- [reduce()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/reduce/) +- [window()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window/) +- [join()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/join/) +- [union()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/union/) +- [pivot()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot/) + +{{% note %}} +We're continually optimizing Flux and this list may not represent its current state. +{{% /note %}} + +## Balance time range and data precision +To ensure queries are performant, balance the time range and the precision of your data. +For example, if you query data stored every second and request six months worth of data, +results will include a minimum of ≈15.5 million points. +Flux must store these points in memory to generate a response. + +To query data over large periods of time, create a task to [downsample data](/influxdb/cloud/process-data/common-tasks/downsample-data/), and then query the downsampled data instead. diff --git a/content/influxdb/cloud/reference/_index.md b/content/influxdb/cloud/reference/_index.md new file mode 100644 index 000000000..aceb19a09 --- /dev/null +++ b/content/influxdb/cloud/reference/_index.md @@ -0,0 +1,8 @@ +--- +title: InfluxDB reference +description: > + Reference documentation for InfluxDB Cloud including importing updates, API documentation, + tools, syntaxes, and more. +--- + +{{< children >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/api/_index.md b/content/influxdb/cloud/reference/api/_index.md new file mode 100644 index 000000000..e58c46fe6 --- /dev/null +++ b/content/influxdb/cloud/reference/api/_index.md @@ -0,0 +1,37 @@ +--- +title: InfluxDB v2 API +description: > + The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. + Access the InfluxDB API using the `/api/v2/` endpoint. +menu: influxdb_cloud_ref +weight: 3 +influxdb/cloud/tags: [api] +--- + +The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. +Access the InfluxDB API using the `/api/v2/` endpoint. + +## Authentication +InfluxDB uses [authentication tokens](/influxdb/cloud/security/tokens/) to authorize API requests. +Include your authentication token as an `Authorization` header in each request. + +```sh +curl --request POST https://cloud2.influxdata.com/api/v2/write \ + --header "Authorization: Token YOURAUTHTOKEN" \ + --data-urlencode "org=myorg" \ + --data-urlencode "bucket=example-bucket" +``` + +## InfluxDB v2 API Documentation +InfluxDB OSS 2.0 API documentation + +## InfluxDB v1 compatibility API documentation +The InfluxDB v2 API includes [InfluxDB 1.x compatibility endpoints](/influxdb/cloud/reference/api/influxdb-1x/) +that work with InfluxDB 1.x client libraries and third-party integrations like +[Grafana](https://grafana.com) and others. + +View full v1 compatibility API documentation + +## InfluxDB client libraries +InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. +For information about supported client libraries, see [InfluxDB client libraries](/influxdb/cloud/tools/client-libraries/). diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/_index.md b/content/influxdb/cloud/reference/api/influxdb-1x/_index.md new file mode 100644 index 000000000..0f718bf56 --- /dev/null +++ b/content/influxdb/cloud/reference/api/influxdb-1x/_index.md @@ -0,0 +1,17 @@ +--- +title: InfluxDB 1.x compatibility API +description: > + The InfluxDB v2 API includes InfluxDB 1.x compatibility endpoints that work with + InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. +menu: + influxdb_cloud_ref: + name: 1.x compatibility + parent: InfluxDB v2 API +weight: 104 +influxdb/cloud/tags: [influxql, query, write] +products: [cloud] +related: + - /influxdb/cloud/query-data/influxql +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/dbrp.md b/content/influxdb/cloud/reference/api/influxdb-1x/dbrp.md new file mode 100644 index 000000000..19b25cfb0 --- /dev/null +++ b/content/influxdb/cloud/reference/api/influxdb-1x/dbrp.md @@ -0,0 +1,17 @@ +--- +title: Database and retention policy mapping +description: > + The database and retention policy (DBRP) mapping service maps InfluxDB 1.x + database and retention policy combinations to InfluxDB Cloud buckets. +menu: + influxdb_cloud_ref: + name: DBRP mapping + parent: 1.x compatibility +weight: 302 +related: + - /influxdb/cloud/reference/api/influxdb-1x/query + - /influxdb/cloud/reference/api/influxdb-1x/write + - /influxdb/cloud/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/query.md b/content/influxdb/cloud/reference/api/influxdb-1x/query.md new file mode 100644 index 000000000..b14438da0 --- /dev/null +++ b/content/influxdb/cloud/reference/api/influxdb-1x/query.md @@ -0,0 +1,21 @@ +--- +title: /query 1.x compatibility API +list_title: /query +description: > + The `/query` 1.x compatibility endpoint queries InfluxDB Cloud using **InfluxQL**. +menu: + influxdb_cloud_ref: + name: /query + parent: 1.x compatibility +weight: 301 +influxdb/cloud/tags: [influxql, query] +products: [cloud] +list_code_example: | + 
+  GET https://cloud2.influxdata.com/query
+
+related: + - /influxdb/cloud/query-data/influxql +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/api/influxdb-1x/write.md b/content/influxdb/cloud/reference/api/influxdb-1x/write.md new file mode 100644 index 000000000..c726f57b8 --- /dev/null +++ b/content/influxdb/cloud/reference/api/influxdb-1x/write.md @@ -0,0 +1,22 @@ +--- +title: /write 1.x compatibility API +list_title: /write +description: > + The `/write` 1.x compatibilty endpoint writes data to InfluxDB Cloud using patterns from the + InfluxDB 1.x `/write` API endpoint. +menu: + influxdb_cloud_ref: + name: /write + parent: 1.x compatibility +weight: 301 +influxdb/cloud/tags: [write] +products: [cloud] +list_code_example: | + 
+  POST https://cloud2.influxdata.com/write
+
+related: + - /influxdb/cloud/reference/syntax/line-protocol +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/cli/_index.md b/content/influxdb/cloud/reference/cli/_index.md new file mode 100644 index 000000000..ccc82976d --- /dev/null +++ b/content/influxdb/cloud/reference/cli/_index.md @@ -0,0 +1,18 @@ +--- +title: Command line tools +seotitle: Command line tools for managing InfluxDB +description: > + InfluxDB provides command line tools designed to aid in managing and working + with InfluxDB from the command line. +influxdb/cloud/tags: [cli] +menu: + influxdb_cloud_ref: + name: Command line tools +weight: 4 +--- + +InfluxDB provides command line tools designed to aid in managing and working +with InfluxDB from the command line. +The following command line interfaces (CLIs) are available: + +{{< children >}} diff --git a/content/influxdb/cloud/reference/cli/influx/_index.md b/content/influxdb/cloud/reference/cli/influx/_index.md new file mode 100644 index 000000000..cce966151 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/_index.md @@ -0,0 +1,16 @@ +--- +title: influx - InfluxDB command line interface +seotitle: influx - InfluxDB command line interface +description: > + The `influx` CLI includes commands to manage many aspects of InfluxDB, + including buckets, organizations, users, tasks, etc. +menu: + influxdb_cloud_ref: + name: influx + parent: Command line tools +weight: 101 +influxdb/cloud/tags: [cli] +--- + +{{< duplicate-oss >}} + diff --git a/content/influxdb/cloud/reference/cli/influx/apply/_index.md b/content/influxdb/cloud/reference/cli/influx/apply/_index.md new file mode 100644 index 000000000..92e3028c9 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/apply/_index.md @@ -0,0 +1,14 @@ +--- +title: influx apply +description: The `influx apply` command applies InfluxDB templates. +menu: + influxdb_cloud_ref: + name: influx apply + parent: influx +weight: 101 +aliases: + - /influxdb/cloud/reference/cli/influx/pkg/ +influxdb/cloud/tags: [templates] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/auth/_index.md b/content/influxdb/cloud/reference/cli/influx/auth/_index.md new file mode 100644 index 000000000..e4f7f02da --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/auth/_index.md @@ -0,0 +1,12 @@ +--- +title: influx auth +description: The `influx auth` command and its subcommands manage authorizations in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx auth + parent: influx +weight: 101 +influxdb/cloud/tags: [authentication] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/auth/active.md b/content/influxdb/cloud/reference/cli/influx/auth/active.md new file mode 100644 index 000000000..0db232f82 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/auth/active.md @@ -0,0 +1,11 @@ +--- +title: influx auth active +description: The `influx auth active` command activates an authorization. +menu: + influxdb_cloud_ref: + name: influx auth active + parent: influx auth +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/auth/create.md b/content/influxdb/cloud/reference/cli/influx/auth/create.md new file mode 100644 index 000000000..b9e885547 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/auth/create.md @@ -0,0 +1,11 @@ +--- +title: influx auth create +description: The `influx auth create` creates an authorization in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx auth create + parent: influx auth +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/auth/delete.md b/content/influxdb/cloud/reference/cli/influx/auth/delete.md new file mode 100644 index 000000000..4d64a7fdd --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/auth/delete.md @@ -0,0 +1,11 @@ +--- +title: influx auth delete +description: The `influx auth delete` command deletes an authorization in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx auth delete + parent: influx auth +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/auth/inactive.md b/content/influxdb/cloud/reference/cli/influx/auth/inactive.md new file mode 100644 index 000000000..1e8ae8b55 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/auth/inactive.md @@ -0,0 +1,11 @@ +--- +title: influx auth inactive +description: The `influx auth inactive` inactivates an authorization in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx auth inactive + parent: influx auth +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/auth/list.md b/content/influxdb/cloud/reference/cli/influx/auth/list.md new file mode 100644 index 000000000..0352a7ed6 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/auth/list.md @@ -0,0 +1,11 @@ +--- +title: influx auth list +description: The `influx auth list` command lists and searches authorizations in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx auth list + parent: influx auth +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/backup/_index.md b/content/influxdb/cloud/reference/cli/influx/backup/_index.md new file mode 100644 index 000000000..ab9f4c472 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/backup/_index.md @@ -0,0 +1,14 @@ +--- +title: influx backup +description: The `influx backup` command backs up data stored in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx backup + parent: influx +weight: 101 +influxdb/cloud/tags: [backup] +related: + - /influxdb/cloud/backup-restore/backup/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket/_index.md b/content/influxdb/cloud/reference/cli/influx/bucket/_index.md new file mode 100644 index 000000000..ceb70ae92 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/bucket/_index.md @@ -0,0 +1,12 @@ +--- +title: influx bucket +description: The `influx bucket` command and its subcommands manage buckets in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx bucket + parent: influx +weight: 101 +influxdb/cloud/tags: [buckets] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket/create.md b/content/influxdb/cloud/reference/cli/influx/bucket/create.md new file mode 100644 index 000000000..0506190b6 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/bucket/create.md @@ -0,0 +1,13 @@ +--- +title: influx bucket create +description: The `influx bucket create` command creates a new bucket in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx bucket create + parent: influx bucket +weight: 201 +aliases: + - /influxdb/cloud/reference/cli/influx/bucket/create/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket/delete.md b/content/influxdb/cloud/reference/cli/influx/bucket/delete.md new file mode 100644 index 000000000..77e1f0a10 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/bucket/delete.md @@ -0,0 +1,13 @@ +--- +title: influx bucket delete +description: The `influx bucket delete` command deletes a bucket from InfluxDB and all the data it contains. +menu: + influxdb_cloud_ref: + name: influx bucket delete + parent: influx bucket +weight: 201 +related: + - /influxdb/cloud/organizations/buckets/delete-bucket/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket/list.md b/content/influxdb/cloud/reference/cli/influx/bucket/list.md new file mode 100644 index 000000000..c28714c31 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/bucket/list.md @@ -0,0 +1,11 @@ +--- +title: influx bucket list +description: The `influx bucket list` command lists and searches for buckets in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx bucket list + parent: influx bucket +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/bucket/update.md b/content/influxdb/cloud/reference/cli/influx/bucket/update.md new file mode 100644 index 000000000..e90416395 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/bucket/update.md @@ -0,0 +1,11 @@ +--- +title: influx bucket update +description: The `influx bucket update` command updates information associated with buckets in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx bucket update + parent: influx bucket +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/completion/_index.md b/content/influxdb/cloud/reference/cli/influx/completion/_index.md new file mode 100644 index 000000000..4a62d57b3 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/completion/_index.md @@ -0,0 +1,14 @@ +--- +title: influx completion +description: > + The `influx completion` command outputs `influx` shell completion scripts for a + specified shell (`bash` or `zsh`). +menu: + influxdb_cloud_ref: + name: influx completion + parent: influx +weight: 101 +influxdb/cloud/tags: [cli, tools] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/config/_index.md b/content/influxdb/cloud/reference/cli/influx/config/_index.md new file mode 100644 index 000000000..3b6ccd483 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/config/_index.md @@ -0,0 +1,12 @@ +--- +title: influx config +description: The `influx config` command and subcommands manage multiple InfluxDB connection configurations. +menu: + influxdb_cloud_ref: + name: influx config + parent: influx +weight: 101 +influxdb/cloud/tags: [config] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/config/create.md b/content/influxdb/cloud/reference/cli/influx/config/create.md new file mode 100644 index 000000000..9b44edfe6 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/config/create.md @@ -0,0 +1,11 @@ +--- +title: influx config create +description: The `influx config create` command creates a new InfluxDB connection configuration. +menu: + influxdb_cloud_ref: + name: influx config create + parent: influx config +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/config/list.md b/content/influxdb/cloud/reference/cli/influx/config/list.md new file mode 100644 index 000000000..0c771883f --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/config/list.md @@ -0,0 +1,11 @@ +--- +title: influx config list +description: The `influx config list` command lists all InfluxDB connection configurations. +menu: + influxdb_cloud_ref: + name: influx config list + parent: influx config +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/config/rm.md b/content/influxdb/cloud/reference/cli/influx/config/rm.md new file mode 100644 index 000000000..a27e549f0 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/config/rm.md @@ -0,0 +1,11 @@ +--- +title: influx config rm +description: The `influx config rm` command removes an InfluxDB connection configuration. +menu: + influxdb_cloud_ref: + name: influx config rm + parent: influx config +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/config/set.md b/content/influxdb/cloud/reference/cli/influx/config/set.md new file mode 100644 index 000000000..3d2354634 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/config/set.md @@ -0,0 +1,11 @@ +--- +title: influx config set +description: The `influx config set` command updates an InfluxDB connection configuration. +menu: + influxdb_cloud_ref: + name: influx config set + parent: influx config +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/dashboards/_index.md b/content/influxdb/cloud/reference/cli/influx/dashboards/_index.md new file mode 100644 index 000000000..fc79d16c3 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/dashboards/_index.md @@ -0,0 +1,13 @@ +--- +title: influx dashboards +description: > + The `influx dashboards` command lists existing InfluxDB dashboards. +menu: + influxdb_cloud_ref: + name: influx dashboards + parent: influx +weight: 101 +influxdb/cloud/tags: [telegraf] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/delete/_index.md b/content/influxdb/cloud/reference/cli/influx/delete/_index.md new file mode 100644 index 000000000..5b060ad6f --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/delete/_index.md @@ -0,0 +1,12 @@ +--- +title: influx delete +description: The `influx delete` command deletes points from an InfluxDB bucket. +menu: + influxdb_cloud_ref: + name: influx delete + parent: influx +weight: 101 +influxdb/cloud/tags: [delete] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/export/_index.md b/content/influxdb/cloud/reference/cli/influx/export/_index.md new file mode 100644 index 000000000..4295b9db1 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/export/_index.md @@ -0,0 +1,12 @@ +--- +title: influx export +description: The `influx export` command exports existing resources as an InfluxDB template. +menu: + influxdb_cloud_ref: + parent: influx +weight: 101 +related: + - /influxdb/cloud/influxdb-templates/create/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/export/all.md b/content/influxdb/cloud/reference/cli/influx/export/all.md new file mode 100644 index 000000000..f78352dde --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/export/all.md @@ -0,0 +1,13 @@ +--- +title: influx export all +description: > + The `influx export all` command exports all resources in an organization as an InfluxDB template. +menu: + influxdb_cloud_ref: + parent: influx export +weight: 201 +related: + - /influxdb/cloud/influxdb-templates/create/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/export/stack.md b/content/influxdb/cloud/reference/cli/influx/export/stack.md new file mode 100644 index 000000000..76ce062e5 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/export/stack.md @@ -0,0 +1,11 @@ +--- +title: influx export stack +description: > + The `influx export stack` command exports all resources associated with a stack as an InfluxDB template. +menu: + influxdb_cloud_ref: + parent: influx export +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/help/_index.md b/content/influxdb/cloud/reference/cli/influx/help/_index.md new file mode 100644 index 000000000..5c3590086 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/help/_index.md @@ -0,0 +1,11 @@ +--- +title: influx help +description: The `influx help` command provides help for any command in the `influx` command line interface. +menu: + influxdb_cloud_ref: + name: influx help + parent: influx +weight: 101 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/_index.md b/content/influxdb/cloud/reference/cli/influx/org/_index.md new file mode 100644 index 000000000..0cf96cf7b --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/_index.md @@ -0,0 +1,12 @@ +--- +title: influx org +description: The `influx org` command and its subcommands manage organization information in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org + parent: influx +weight: 101 +influxdb/cloud/tags: [organizations] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/create.md b/content/influxdb/cloud/reference/cli/influx/org/create.md new file mode 100644 index 000000000..91f919144 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/create.md @@ -0,0 +1,11 @@ +--- +title: influx org create +description: The `influx org create` creates a new organization in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org create + parent: influx org +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/delete.md b/content/influxdb/cloud/reference/cli/influx/org/delete.md new file mode 100644 index 000000000..066a77dca --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/delete.md @@ -0,0 +1,11 @@ +--- +title: influx org delete +description: The `influx org delete` command deletes an organization in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org delete + parent: influx org +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/list.md b/content/influxdb/cloud/reference/cli/influx/org/list.md new file mode 100644 index 000000000..82dbbc151 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/list.md @@ -0,0 +1,11 @@ +--- +title: influx org list +description: The `influx org list` lists and searches for organizations in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org list + parent: influx org +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/members/_index.md b/content/influxdb/cloud/reference/cli/influx/org/members/_index.md new file mode 100644 index 000000000..c16930cb0 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/members/_index.md @@ -0,0 +1,12 @@ +--- +title: influx org members +description: The `influx org members` command and its subcommands manage organization members in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org members + parent: influx org +weight: 201 +influxdb/cloud/tags: [members, organizations] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/members/add.md b/content/influxdb/cloud/reference/cli/influx/org/members/add.md new file mode 100644 index 000000000..4ed7ed78d --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/members/add.md @@ -0,0 +1,11 @@ +--- +title: influx org members add +description: The `influx org members add` command adds a new member to an organization in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org members add + parent: influx org members +weight: 301 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/members/list.md b/content/influxdb/cloud/reference/cli/influx/org/members/list.md new file mode 100644 index 000000000..fe8815a25 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/members/list.md @@ -0,0 +1,11 @@ +--- +title: influx org members list +description: The `influx org members list` command lists members within an organization in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org members list + parent: influx org members +weight: 301 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/members/remove.md b/content/influxdb/cloud/reference/cli/influx/org/members/remove.md new file mode 100644 index 000000000..e05e0aa3c --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/members/remove.md @@ -0,0 +1,11 @@ +--- +title: influx org members remove +description: The `influx org members remove` command removes a member from an organization in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org members remove + parent: influx org members +weight: 301 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/org/update.md b/content/influxdb/cloud/reference/cli/influx/org/update.md new file mode 100644 index 000000000..acd398c65 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/org/update.md @@ -0,0 +1,11 @@ +--- +title: influx org update +description: The `influx org update` command updates information related to organizations in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx org update + parent: influx org +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/ping/_index.md b/content/influxdb/cloud/reference/cli/influx/ping/_index.md new file mode 100644 index 000000000..cc8540215 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/ping/_index.md @@ -0,0 +1,14 @@ +--- +title: influx ping +description: > + The `influx ping` command checks the health of a running InfluxDB instance by + querying the `/health` endpoint. +menu: + influxdb_cloud_ref: + name: influx ping + parent: influx +weight: 101 +influxdb/cloud/tags: [ping, health] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/query/_index.md b/content/influxdb/cloud/reference/cli/influx/query/_index.md new file mode 100644 index 000000000..abc973d9d --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/query/_index.md @@ -0,0 +1,14 @@ +--- +title: influx query +description: > + The `influx query` command executes a literal Flux query provided as a string + or a literal Flux query contained in a file by specifying the file prefixed with an '@' sign. +menu: + influxdb_cloud_ref: + name: influx query + parent: influx +weight: 101 +influxdb/cloud/tags: [query] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/secret/_index.md b/content/influxdb/cloud/reference/cli/influx/secret/_index.md new file mode 100644 index 000000000..725d2bb85 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/secret/_index.md @@ -0,0 +1,12 @@ +--- +title: influx secret +description: The `influx secret` command manages secrets. +menu: + influxdb_cloud_ref: + name: influx secret + parent: influx +weight: 101 +influxdb/cloud/tags: [secrets] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/secret/delete.md b/content/influxdb/cloud/reference/cli/influx/secret/delete.md new file mode 100644 index 000000000..d869ebaff --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/secret/delete.md @@ -0,0 +1,12 @@ +--- +title: influx secret delete +description: The `influx secret delete` command deletes secrets. +menu: + influxdb_cloud_ref: + name: influx secret delete + parent: influx secret +weight: 101 +influxdb/cloud/tags: [secrets] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/secret/list.md b/content/influxdb/cloud/reference/cli/influx/secret/list.md new file mode 100644 index 000000000..3f912a143 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/secret/list.md @@ -0,0 +1,12 @@ +--- +title: influx secret list +description: The `influx secret list` command lists secret keys. +menu: + influxdb_cloud_ref: + name: influx secret list + parent: influx secret +weight: 101 +influxdb/cloud/tags: [secrets] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/secret/update.md b/content/influxdb/cloud/reference/cli/influx/secret/update.md new file mode 100644 index 000000000..05797f06d --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/secret/update.md @@ -0,0 +1,12 @@ +--- +title: influx secret update +description: The `influx secret update` command adds and updates secrets. +menu: + influxdb_cloud_ref: + name: influx secret update + parent: influx secret +weight: 101 +influxdb/cloud/tags: [secrets] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/setup/_index.md b/content/influxdb/cloud/reference/cli/influx/setup/_index.md new file mode 100644 index 000000000..7d5da342f --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/setup/_index.md @@ -0,0 +1,14 @@ +--- +title: influx setup +description: > + The `influx setup` command walks through the initial InfluxDB setup process, + creating a default user, organization, and bucket. +menu: + influxdb_cloud_ref: + name: influx setup + parent: influx +weight: 101 +influxdb/cloud/tags: [get-started] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/stacks/_index.md b/content/influxdb/cloud/reference/cli/influx/stacks/_index.md new file mode 100644 index 000000000..5c02b2b0c --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/stacks/_index.md @@ -0,0 +1,14 @@ +--- +title: influx stacks +description: > + The `influx stacks` command and its subcommands list and manage InfluxDB stacks + and associated resources. +menu: + influxdb_cloud_ref: + name: influx stacks + parent: influx +weight: 101 +influxdb/cloud/tags: [templates] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/stacks/init.md b/content/influxdb/cloud/reference/cli/influx/stacks/init.md new file mode 100644 index 000000000..e27222b2c --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/stacks/init.md @@ -0,0 +1,12 @@ +--- +title: influx stacks init +description: The `influx stacks init` command initializes an InfluxDB stack. +menu: + influxdb_cloud_ref: + name: influx stacks init + parent: influx stacks +weight: 201 +influxdb/cloud/tags: [templates] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/stacks/remove.md b/content/influxdb/cloud/reference/cli/influx/stacks/remove.md new file mode 100644 index 000000000..ed4c1c664 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/stacks/remove.md @@ -0,0 +1,14 @@ +--- +title: influx stacks remove +description: The `influx stacks remove` command removes an InfluxDB stack and all associated resources. +menu: + influxdb_cloud_ref: + name: influx stacks remove + parent: influx stacks +weight: 201 +aliases: + - /influxdb/cloud/reference/cli/influx/pkg/stack/remove/ +influxdb/cloud/tags: [templates] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/stacks/update.md b/content/influxdb/cloud/reference/cli/influx/stacks/update.md new file mode 100644 index 000000000..f09014552 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/stacks/update.md @@ -0,0 +1,12 @@ +--- +title: influx stacks update +description: The 'influx stacks update' command updates an InfluxDB stack. +menu: + influxdb_cloud_ref: + name: influx stacks update + parent: influx stacks +weight: 201 +influxdb/cloud/tags: [templates] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/_index.md b/content/influxdb/cloud/reference/cli/influx/task/_index.md new file mode 100644 index 000000000..9e90f0e2d --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/_index.md @@ -0,0 +1,12 @@ +--- +title: influx task +description: The `influx task` command and its subcommands manage tasks in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx task + parent: influx +weight: 101 +influxdb/cloud/tags: [tasks] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/create.md b/content/influxdb/cloud/reference/cli/influx/task/create.md new file mode 100644 index 000000000..150a69c4d --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/create.md @@ -0,0 +1,11 @@ +--- +title: influx task create +description: The `influx task create` command creates a new task in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx task create + parent: influx task +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/delete.md b/content/influxdb/cloud/reference/cli/influx/task/delete.md new file mode 100644 index 000000000..ce375e57f --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/delete.md @@ -0,0 +1,11 @@ +--- +title: influx task delete +description: The `influx task delete` command deletes a task in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx task delete + parent: influx task +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/list.md b/content/influxdb/cloud/reference/cli/influx/task/list.md new file mode 100644 index 000000000..c3fa3559f --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/list.md @@ -0,0 +1,11 @@ +--- +title: influx task list +description: The `influx task list` command lists and searches for tasks in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx task list + parent: influx task +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/log/_index.md b/content/influxdb/cloud/reference/cli/influx/task/log/_index.md new file mode 100644 index 000000000..7f93d414c --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/log/_index.md @@ -0,0 +1,14 @@ +--- +title: influx task log +description: > + The `influx task log` and its subcommand, `list`, output log information + related to a task. +menu: + influxdb_cloud_ref: + name: influx task log + parent: influx task +weight: 201 +influxdb/cloud/tags: [logs] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/log/list.md b/content/influxdb/cloud/reference/cli/influx/task/log/list.md new file mode 100644 index 000000000..5109ec9a7 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/log/list.md @@ -0,0 +1,13 @@ +--- +title: influx task log list +description: The `influx task log list` command outputs log information related to a task. +menu: + influxdb_cloud_ref: + name: influx task log list + parent: influx task log +weight: 301 +aliases: + - /influxdb/cloud/reference/cli/influx/task/log/list +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/run/_index.md b/content/influxdb/cloud/reference/cli/influx/task/run/_index.md new file mode 100644 index 000000000..82c758214 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/run/_index.md @@ -0,0 +1,13 @@ +--- +title: influx task run +description: > + The `influx task run` command and its subcommand, `list` output information + related to runs of a task. +menu: + influxdb_cloud_ref: + name: influx task run + parent: influx task +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/run/list.md b/content/influxdb/cloud/reference/cli/influx/task/run/list.md new file mode 100644 index 000000000..dae7967db --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/run/list.md @@ -0,0 +1,11 @@ +--- +title: influx task run list +description: The `influx task run list` command outputs information related to runs of a task. +menu: + influxdb_cloud_ref: + name: influx task run list + parent: influx task run +weight: 301 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/run/retry.md b/content/influxdb/cloud/reference/cli/influx/task/run/retry.md new file mode 100644 index 000000000..85ead4282 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/run/retry.md @@ -0,0 +1,11 @@ +--- +title: influx task run retry +description: The `influx task run retry` command retries to run a task in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx task run retry + parent: influx task run +weight: 301 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/task/update.md b/content/influxdb/cloud/reference/cli/influx/task/update.md new file mode 100644 index 000000000..24e91ec3e --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/task/update.md @@ -0,0 +1,11 @@ +--- +title: influx task update +description: The `influx task update` command updates information related to tasks in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx task update + parent: influx task +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/telegrafs/_index.md b/content/influxdb/cloud/reference/cli/influx/telegrafs/_index.md new file mode 100644 index 000000000..1f21178fe --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/telegrafs/_index.md @@ -0,0 +1,14 @@ +--- +title: influx telegrafs +description: > + The `influx telegrafs` command lists Telegraf configurations. + Subcommands manage Telegraf configurations. +menu: + influxdb_cloud_ref: + name: influx telegrafs + parent: influx +weight: 101 +influxdb/cloud/tags: [telegraf] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/telegrafs/create.md b/content/influxdb/cloud/reference/cli/influx/telegrafs/create.md new file mode 100644 index 000000000..a6f181dde --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/telegrafs/create.md @@ -0,0 +1,13 @@ +--- +title: influx telegrafs create +description: > + The `influx telegrafs create` command creates a new Telegraf configuration in InfluxDB + using a provided Telegraf configuration file. +menu: + influxdb_cloud_ref: + name: influx telegrafs create + parent: influx telegrafs +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/telegrafs/rm.md b/content/influxdb/cloud/reference/cli/influx/telegrafs/rm.md new file mode 100644 index 000000000..826b8adc3 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/telegrafs/rm.md @@ -0,0 +1,12 @@ +--- +title: influx telegrafs rm +description: > + The `influx telegrafs rm` command removes Telegraf configurations from InfluxDB. +menu: + influxdb_cloud_ref: + name: influx telegrafs rm + parent: influx telegrafs +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/telegrafs/update.md b/content/influxdb/cloud/reference/cli/influx/telegrafs/update.md new file mode 100644 index 000000000..64b1a19af --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/telegrafs/update.md @@ -0,0 +1,13 @@ +--- +title: influx telegrafs update +description: > + The `influx telegrafs update` command updates a Telegraf configuration to match the specified parameters. + If a name or description are not provided, they are set to an empty string. +menu: + influxdb_cloud_ref: + name: influx telegrafs update + parent: influx telegrafs +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/template/_index.md b/content/influxdb/cloud/reference/cli/influx/template/_index.md new file mode 100644 index 000000000..3dbebb5c8 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/template/_index.md @@ -0,0 +1,12 @@ +--- +title: influx template +description: The `influx template` command summarizes the specified InfluxDB template. +menu: + influxdb_cloud_ref: + name: influx template + parent: influx +weight: 101 +influxdb/cloud/tags: [templates] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/template/validate.md b/content/influxdb/cloud/reference/cli/influx/template/validate.md new file mode 100644 index 000000000..c3ee90ca2 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/template/validate.md @@ -0,0 +1,11 @@ +--- +title: influx template validate +description: > + The `influx template validate` command validates the provided InfluxDB template. +menu: + influxdb_cloud_ref: + parent: influx template +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/transpile/_index.md b/content/influxdb/cloud/reference/cli/influx/transpile/_index.md new file mode 100644 index 000000000..896ccfb83 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/transpile/_index.md @@ -0,0 +1,13 @@ +--- +title: influx transpile +description: > + The `influx transpile` command transpiles an InfluxQL query to Flux source code. +menu: + influxdb_cloud_ref: + name: influx transpile + parent: influx +weight: 101 +influxdb/cloud/tags: [influxql, flux] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/_index.md b/content/influxdb/cloud/reference/cli/influx/user/_index.md new file mode 100644 index 000000000..fe047d358 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/user/_index.md @@ -0,0 +1,12 @@ +--- +title: influx user +description: The `influx user` command and its subcommands manage user information in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx user + parent: influx +weight: 101 +influxdb/cloud/tags: [users] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/create.md b/content/influxdb/cloud/reference/cli/influx/user/create.md new file mode 100644 index 000000000..5a9f0ab56 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/user/create.md @@ -0,0 +1,11 @@ +--- +title: influx user create +description: The `influx user create` command creates a user in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx user create + parent: influx user +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/delete.md b/content/influxdb/cloud/reference/cli/influx/user/delete.md new file mode 100644 index 000000000..be8f76d59 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/user/delete.md @@ -0,0 +1,11 @@ +--- +title: influx user delete +description: The `influx user delete` command deletes a specified user. +menu: + influxdb_cloud_ref: + name: influx user delete + parent: influx user +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/list.md b/content/influxdb/cloud/reference/cli/influx/user/list.md new file mode 100644 index 000000000..20d0a5da9 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/user/list.md @@ -0,0 +1,13 @@ +--- +title: influx user list +description: The `influx user list` lists users in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx user list + parent: influx user +weight: 201 +aliases: + - /influxdb/cloud/reference/cli/influx/user/find +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/password.md b/content/influxdb/cloud/reference/cli/influx/user/password.md new file mode 100644 index 000000000..928be2ad4 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/user/password.md @@ -0,0 +1,13 @@ +--- +title: influx user password +description: The `influx user password` command updates the password for a user in InfluxDB. +menu: + influxdb_cloud_ref: + name: influx user password + parent: influx user +weight: 201 +related: + - /influxdb/cloud/users/change-password/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/user/update.md b/content/influxdb/cloud/reference/cli/influx/user/update.md new file mode 100644 index 000000000..48d6f02fe --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/user/update.md @@ -0,0 +1,12 @@ +--- +title: influx user update +description: > + The `influx user update` command updates information related to a user such as their user name. +menu: + influxdb_cloud_ref: + name: influx user update + parent: influx user +weight: 201 +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/version.md b/content/influxdb/cloud/reference/cli/influx/version.md new file mode 100644 index 000000000..01ad23f14 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/version.md @@ -0,0 +1,11 @@ +--- +title: influx version +description: The `influx version` command outputs the current version of the influx command line interface (CLI). +influxdb/cloud/tags: [influx, cli] +menu: + influxdb_cloud_ref: + parent: influx +weight: 202 +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/cli/influx/write/_index.md b/content/influxdb/cloud/reference/cli/influx/write/_index.md new file mode 100644 index 000000000..019e4e715 --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/write/_index.md @@ -0,0 +1,17 @@ +--- +title: influx write +description: > + The `influx write` command writes data to InfluxDB via stdin or from a specified file. + Write data using line protocol or annotated CSV. +menu: + influxdb_cloud_ref: + name: influx write + parent: influx +weight: 101 +influxdb/cloud/tags: [write] +related: + - /influxdb/cloud/write-data/ + - /influxdb/cloud/write-data/csv/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/cli/influx/write/dryrun.md b/content/influxdb/cloud/reference/cli/influx/write/dryrun.md new file mode 100644 index 000000000..4d78c48bd --- /dev/null +++ b/content/influxdb/cloud/reference/cli/influx/write/dryrun.md @@ -0,0 +1,14 @@ +--- +title: influx write dryrun +description: > + The `influx write dryrun` command prints write output to stdout instead of writing + to InfluxDB. Use this command to test writing data. +menu: + influxdb_cloud_ref: + name: influx write dryrun + parent: influx write +weight: 101 +influxdb/cloud/tags: [write] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/flux/_index.md b/content/influxdb/cloud/reference/flux/_index.md new file mode 100644 index 000000000..41086b565 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/_index.md @@ -0,0 +1,14 @@ +--- +title: Flux data scripting language +description: Reference articles for Flux functions and the Flux language specification. +influxdb/cloud/tags: [flux] +menu: + influxdb_cloud_ref: + name: Flux language +weight: 3 +--- + +The following articles are meant as a reference for the Flux standard library and +the Flux language specification. + +{{< children >}} diff --git a/content/influxdb/cloud/reference/flux/language/_index.md b/content/influxdb/cloud/reference/flux/language/_index.md new file mode 100644 index 000000000..65a0203af --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/_index.md @@ -0,0 +1,48 @@ +--- +title: Flux language specification +description: > + Covers the current and future Flux functional data scripting language, + which is designed for querying, analyzing, and acting on data. +menu: + influxdb_cloud_ref: + name: Flux specification + parent: Flux language +weight: 103 +influxdb/cloud/tags: [flux] +--- + +The following document specifies the Flux language and query execution. + +{{% note %}} +This document is a living document and may not represent the current implementation of Flux. +Any section that is not currently implemented is commented with a **[IMPL#XXX]** where +**XXX** is an issue number tracking discussion and progress towards implementation. +{{% /note %}} + +The Flux language is centered on querying and manipulating time series data. + +### Notation +The syntax of the language is specified using [Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form): + +```js +Production = production_name "=" [ Expression ] "." . +Expression = Alternative { "|" Alternative } . +Alternative = Term { Term } . +Term = production_name | token [ "…" token ] | Group | Option | Repetition . +Group = "(" Expression ")" . +Option = "[" Expression "]" . +Repetition = "{" Expression "}" . +``` + +Productions are expressions constructed from terms and the following operators, in increasing precedence: + +``` +| alternation +() grouping +[] option (0 or 1 times) +{} repetition (0 to n times) +``` + +Lower-case production names are used to identify lexical tokens. +Non-terminals are in Camel case. +Lexical tokens are enclosed in double quotes (`""`) or back quotes (``). diff --git a/content/influxdb/cloud/reference/flux/language/assignment-scope.md b/content/influxdb/cloud/reference/flux/language/assignment-scope.md new file mode 100644 index 000000000..24b64fe34 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/assignment-scope.md @@ -0,0 +1,78 @@ +--- +title: Assignment and scope +description: An assignment binds an identifier to a variable, option, or function. Every identifier in a program must be assigned. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Assignment and scope +weight: 202 +--- + +An assignment binds an identifier to a variable, option, or function. +Every identifier in a program must be assigned. + +Flux is lexically scoped using blocks: + +1. The scope of a preassigned identifier is in the universe block. +2. The scope of an identifier denoting a variable, option, or function at the top level (outside any function) is the package block. +3. The scope of the name of an imported package is the file block of the file containing the import declaration. +4. The scope of an identifier denoting a function argument is the function body. +5. The scope of an identifier assigned inside a function is the innermost containing block. + +An identifier assigned in a block may be reassigned in an inner block with the exception of option identifiers. +While the identifier of the inner assignment is in scope, it denotes the entity assigned by the inner assignment. + +Note that the package clause is not an assignment. +The package name does not appear in any scope. +Its purpose is to identify the files belonging to the same package and to specify the default package name for import declarations. + +## Variable assignment +A variable assignment creates a variable bound to an identifier and gives it a type and value. +A variable keeps the same type and value for the remainder of its lifetime. +An identifier assigned to a variable in a block cannot be reassigned in the same block. +An identifier can be reassigned or shadowed in an inner block. + +```js +VariableAssignment = identifier "=" Expression . +``` + +##### Examples of variable assignment + +{{% note %}} +In this code snippet, `n` and `m` are defined in an outer block as integers. Within the anonymous function, `n` and `m` are defined as strings, but only within that scope. So while the function will return `"ab"`, `n` and `m` in the outer scope are unchanged, remaining `n = 1` and `m = 2`. +{{% /note %}} + +```js +n = 1 +m = 2 +x = 5.4 +f = () => { + n = "a" + m = "b" + return n + m +} +``` + +## Option assignment +```js +OptionAssignment = "option" [ identifier "." ] identifier "=" Expression . +``` + +An option assignment creates an option bound to an identifier and gives it a type and a value. +Options may only be assigned in a package block. +Once declared, an option may not be redeclared in the same package block. +An option declared in one package may be reassigned a new value in another. +An option keeps the same type for the remainder of its lifetime. + +###### Examples +```js +// alert package +option severity = ["low", "moderate", "high"] +// foo package +import "alert" +option alert.severity = ["low", "critical"] // qualified option +option n = 1 +option n = 2 +f = (a, b) => a + b + n +x = f(a:1, b:1) // x = 4 +``` diff --git a/content/influxdb/cloud/reference/flux/language/blocks.md b/content/influxdb/cloud/reference/flux/language/blocks.md new file mode 100644 index 000000000..d34a98fec --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/blocks.md @@ -0,0 +1,25 @@ +--- +title: Blocks +description: A block is a possibly empty sequence of statements within matching braces ({}). +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Blocks +weight: 203 +--- + +A _block_ is a possibly empty sequence of statements within matching braces (`{}`). + +``` +Block = "{" StatementList "} . +StatementList = { Statement } . +``` + +In addition to _explicit blocks_ in the source code, there are _implicit blocks_: + +1. The _universe block_ encompasses all Flux source text. +2. Each package has a _package block_ containing all Flux source text for that package. +3. Each file has a _file block_ containing all Flux source text in that file. +4. Each function literal has its own _function block_ even if not explicitly declared. + +Blocks nest and influence scoping. diff --git a/content/influxdb/cloud/reference/flux/language/data-model.md b/content/influxdb/cloud/reference/flux/language/data-model.md new file mode 100644 index 000000000..30c901f12 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/data-model.md @@ -0,0 +1,141 @@ +--- +title: Flux data model +description: Flux employs a basic data model built from basic data types. The data model consists of tables, records, columns and streams. +menu: + influxdb_cloud_ref: + name: Data model + parent: Flux specification +weight: 201 +--- + +{{% note %}} +This document is a living document and may not represent the current implementation of Flux. +Any section that is not currently implemented is commented with a **[IMPL#XXX]** where +**XXX** is an issue number tracking discussion and progress towards implementation. +{{% /note %}} + +Flux employs a basic data model built from basic data types. +The data model consists of tables, records, columns and streams. + +## Record + +A **record** is a tuple of named values and is represented using a record type. + +## Column + +A **column** has a label and a data type. +The available data types for a column are: + +| Data type | Description | +| --------- |:----------- | +| bool | A boolean value, true or false. | +| uint | An unsigned 64-bit integer. | +| int | A signed 64-bit integer. | +| float | An IEEE-754 64-bit floating-point number. | +| string | A sequence of unicode characters. | +| bytes | A sequence of byte values. | +| time | A nanosecond precision instant in time. | +| duration | A nanosecond precision duration of time. | + +## Table + +A **table** is set of records with a common set of columns and a group key. + +The group key is a list of columns. +A table's group key denotes which subset of the entire dataset is assigned to the table. +All records within a table will have the same values for each column that is part of the group key. +These common values are referred to as the "group key value" and can be represented as a set of key value pairs. + +A tables schema consists of its group key and its columns' labels and types. + +{{% note %}} +[IMPL#463](https://github.com/influxdata/flux/issues/463) Specify the primitive types that make up stream and table types +{{% /note %}} + +## Stream of tables + +A **stream** represents a potentially unbounded set of tables. +A stream is grouped into individual tables using their respective group keys. +Tables within a stream each have a unique group key value. + +{{% note %}} +[IMPL#463](https://github.com/influxdata/flux/issues/463) Specify the primitive +types that make up stream and table types +{{% /note %}} + +## Missing values (null) + +`null` is a predeclared identifier representing a missing or unknown value. +`null` is the only value comprising the _null type_. +Any non-boolean operator that operates on basic types returns _null_ when at least one of its operands is _null_. + +Think of _null_ as an unknown value. +The following table explains how _null_ values behave in expressions: + +| Expression | Evaluates To | Because | +| ---------------- | ------------ | ----------------------------------------------------------------------------------- | +| `null + 5` | `null` | Adding 5 to an unknown value is still unknown | +| `null * 5` | `null` | Multiplying an unknown value by 5 is still unknown | +| `null == 5` | `null` | We don't know if an unknown value is equal to 5 | +| `null < 5` | `null` | We don't know if an unknown value is less than 5 | +| `null == null` | `null` | We don't know if something unknown is equal to something else that is also unknown | + +Operating on something unknown produces something that is still unknown. +The only place where this is not the case is in boolean logic. +Because boolean types are nullable, Flux implements ternary logic as a way of handling boolean operators with _null_ operands. +By interpreting a _null_ operand as an unknown value, we have the following definitions: + +- not _null_ = _null_ +- _null_ or false = _null_ +- _null_ or true = true +- _null_ or _null_ = _null_ +- _null_ and false = false +- _null_ and true = _null_ +- _null_ and _null_ = _null_ + +Because records are represented using record types, attempting to access a column +whose value is unknown or missing from a record will also return _null_. + +{{% note %}} +According to the definitions above, it is not possible to check if an expression is _null_ using the `==` and `!=` operators. +These operators will return _null_ if any of their operands are _null_. +In order to perform such a check, Flux provides a built-in `exists` operator: + +- `exists x` returns false if `x` is _null_ +- `exists x` returns true if `x` is not _null_ +{{% /note %}} + +## Transformations + +Transformations define a change to a stream. +Transformations may consume an input stream and always produce a new output stream. +The output stream group keys have a stable output order based on the input stream. +Specific ordering may change between releases, but is not considered a breaking change. + +Most transformations output one table for every table they receive from the input stream. +Transformations that modify group keys or values regroup the tables in the output stream. +A transformation produces side effects when constructed from a function that produces side effects. + +Transformations are represented using function types. + +### Match parameter names + +Some transformations (for example, `map` and `filter`) are represented using higher-order functions (functions that accept other functions). +Each argument passed into a function must match the parameter name defined for the function. + +For example, `filter` accepts `fn`, which takes one argument named `r`: + + ```js +from(bucket: "db") + |> filter(fn: (r) => ...) +``` + + If a parameter is renamed from `r` to `v`, the script fails: + +```js +from(bucket: "db") + |> filter(fn: (v) => ...) + // FAILS!: 'v' != 'r'. +``` + +Because Flux does not support positional arguments, parameter names matter. The transformation (in this case, `filter`) must know `r` is the parameter name to successfully invoke the function. diff --git a/content/influxdb/cloud/reference/flux/language/expressions.md b/content/influxdb/cloud/reference/flux/language/expressions.md new file mode 100644 index 000000000..ad37dae08 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/expressions.md @@ -0,0 +1,278 @@ +--- +title: Expressions +description: An expression specifies the computation of a value by applying the operators and functions to operands. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Expressions +weight: 204 +--- + +An _expression_ specifies the computation of a value by applying the operators and functions to operands. + +## Operands and primary expressions + +Operands denote the elementary values in an expression. + +Primary expressions are the operands for unary and binary expressions. +A primary expressions may be a literal, an identifier denoting a variable, or a parenthesized expression. + +```js +PrimaryExpression = identifier | Literal | "(" Expression ")" . +``` + +## Literals + +Literals construct a value. + +```js +Literal = int_lit + | float_lit + | string_lit + | regex_lit + | duration_lit + | date_time_lit + | pipe_receive_lit + | RecordLiteral + | ArrayLiteral + | FunctionLiteral . +``` + +### Record literals + +Record literals construct a value with the record type. + +```js +RecordLiteral = "{" RecordBody "}" . +RecordBody = WithProperties | PropertyList . +WithProperties = identifier "with" PropertyList . +PropertyList = [ Property { "," Property } ] . +Property = identifier [ ":" Expression ] + | string_lit ":" Expression . +``` + +**Examples** +```js +{a: 1, b: 2, c: 3} +{a, b, c} +{o with x: 5, y: 5} +{o with a, b} +``` + +### Array literals + +Array literals construct a value with the array type. + +```js +ArrayLiteral = "[" ExpressionList "]" . +ExpressionList = [ Expression { "," Expression } ] . +``` + +### Function literals + +A _function literal_ defines a new function with a body and parameters. +The function body may be a block or a single expression. +The function body must have a return statement if it is an explicit block, otherwise the expression is the return value. + +```js +FunctionLiteral = FunctionParameters "=>" FunctionBody . +FunctionParameters = "(" [ ParameterList [ "," ] ] ")" . +ParameterList = Parameter { "," Parameter } . +Parameter = identifier [ "=" Expression ] . +FunctionBody = Expression | Block . +``` + +##### Examples of function literals + +```js +() => 1 // function returns the value 1 +(a, b) => a + b // function returns the sum of a and b +(x=1, y=1) => x * y // function with default values +(a, b, c) => { // function with a block body + d = a + b + return d / c +} + +``` +All function literals are anonymous. +A function may be given a name using a variable assignment. + +``` +add = (a,b) => a + b +mul = (a,b) => a * b +``` + +Function literals are _closures_ and may refer to variables defined in a surrounding block. +Those variables are shared between the function literal and the surrounding block. + +## Call expressions + +A _call expression_ invokes a function with the provided arguments. +Arguments must be specified using the argument name. +Positional arguments are not supported. +Argument order does not matter. +When an argument has a default value, it is not required to be specified. + +```js +CallExpression = "(" PropertyList ")" . +``` + +##### Examples of call expressions + +```js +f(a:1, b:9.6) +float(v:1) +``` + +Use short notation in a call expression when the name of every argument matches the name of every parameter. + +##### Examples of short notation in call expressions + +```js +add(a: a, b: b) //long notation +add(a, b) // short notation equivalent + +add = (a,b) => a + b +a = 1 +b = 2 + +// Don't mix short and long notation. +add(a: a, b) +add(a, b: b) +``` + +## Pipe expressions + +A _pipe expression_ is a call expression with an implicit piped argument. +Pipe expressions simplify creating long nested call chains. + +Pipe expressions pass the result of the left hand expression as the _pipe argument_ to the right hand call expression. +Function literals specify which if any argument is the pipe argument using the _pipe literal_ as the argument's default value. +It is an error to use a pipe expression if the function does not declare a pipe argument. + +```js +pipe_receive_lit = "<-" . +``` + +##### Examples of pipe expressions + +```js +foo = () => // function body elided +bar = (x=<-) => // function body elided +baz = (y=<-) => // function body elided +foo() |> bar() |> baz() // equivalent to baz(x:bar(y:foo())) +``` + +## Index expressions +Index expressions access a value from an array based on a numeric index. + +```js +IndexExpression = "[" Expression "]" . +``` + +## Member expressions +Member expressions access a property of a record. +They are specified using an expression in one of the following forms: + +```js +rec.k +// or +rec["k"] +``` + +The property being accessed must be either an identifier or a string literal. +In either case the literal value is the name of the property being accessed, the identifier is not evaluated. +It is not possible to access a record's property using an arbitrary expression. + +If `rec` contains an entry with property `k`, both `rec.k` and `rec["k"]` return the value associated with `k`. +If `rec` does **not** contain an entry with property `k`, both `rec.k` and `rec["k"]` return _null_. + +```js +MemberExpression = DotExpression | MemberBracketExpression . +DotExpression = "." identifier . +MemberBracketExpression = "[" string_lit "]" . +``` + +## Conditional expressions +Conditional expressions evaluate a boolean-valued condition. +If the result is _true_, the expression that follows the `then` keyword is evaluated and returned. +If the result is _false_, the expression that follows the `else` keyword is evaluated and returned. +In either case, only the branch taken is evaluated and only side effects associated this branch will occur. + +```js +ConditionalExpression = "if" Expression "then" Expression "else" Expression . +``` + +##### Conditional expression example +```js +color = if code == 0 then "green" else if code == 1 then "yellow" else "red" +``` + +{{% note %}} +According to the definition above, if a condition evaluates to a _null_ or unknown value, +the _else_ branch is evaluated. +{{% /note %}} + +## Operators +Operators combine operands into expressions. +The precedence of the operators is given in the table below. +Operators with a lower number have higher precedence. + +| Precedence | Operator | Description | +|:----------:|:--------: |:-------------------------- | +| 1 | `a()` | Function call | +| | `a[]` | Member or index access | +| | `.` | Member access | +| 2 | \|> | Pipe forward | +| 3 | `^` | Exponentiation | +| 4 | `*` `/` `%` | Multiplication, division, and modulo | +| 5 | `+` `-` | Addition and subtraction | +| 6 |`==` `!=` | Comparison operators | +| | `<` `<=` | | +| | `>` `>=` | | +| |`=~` `!~` | | +| 7 | `not` | Unary logical operator | +| | `exists` | Null check operator | +| 8 | `and` | Logical AND | +| 9 | `or` | Logical OR | +| 10 | `if` `then` `else` | Conditional | + +The operator precedence is encoded directly into the grammar as the following. + +```js +Expression = ConditionalExpression . +ConditionalExpression = LogicalExpression + | "if" Expression "then" Expression "else" Expression . +LogicalExpression = UnaryLogicalExpression + | LogicalExpression LogicalOperator UnaryLogicalExpression . +LogicalOperator = "and" | "or" . +UnaryLogicalExpression = ComparisonExpression + | UnaryLogicalOperator UnaryLogicalExpression . +UnaryLogicalOperator = "not" | "exists" . +ComparisonExpression = AdditiveExpression + | ComparisonExpression ComparisonOperator AdditiveExpression . +ComparisonOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "=~" | "!~" . +AdditiveExpression = MultiplicativeExpression + | AdditiveExpression AdditiveOperator MultiplicativeExpression . +AdditiveOperator = "+" | "-" . +MultiplicativeExpression = PipeExpression + | MultiplicativeExpression MultiplicativeOperator PipeExpression . +MultiplicativeOperator = "*" | "/" | "%" | "^" . +PipeExpression = PostfixExpression + | PipeExpression PipeOperator UnaryExpression . +PipeOperator = "|>" . +UnaryExpression = PostfixExpression + | PrefixOperator UnaryExpression . +PrefixOperator = "+" | "-" . +PostfixExpression = PrimaryExpression + | PostfixExpression PostfixOperator . +PostfixOperator = MemberExpression + | CallExpression + | IndexExpression . +``` + +{{% warn %}} +Dividing by 0 or using the mod operator with a divisor of 0 will result in an error. +{{% /warn %}} + +_Also see [Flux Operators](/influxdb/cloud/reference/flux/language/operators)._ diff --git a/content/influxdb/cloud/reference/flux/language/lexical-elements.md b/content/influxdb/cloud/reference/flux/language/lexical-elements.md new file mode 100644 index 000000000..699c797c3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/lexical-elements.md @@ -0,0 +1,373 @@ +--- +title: Lexical elements +description: Descriptions of Flux comments, tokens, identifiers, keywords, and other lexical elements. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Lexical elements +weight: 205 +--- + +{{% note %}} +This document is a living document and may not represent the current implementation of Flux. +Any section that is not currently implemented is commented with a **[IMPL#XXX]** where +**XXX** is an issue number tracking discussion and progress towards implementation. +{{% /note %}} + +## Comments + +Comment serve as documentation. +Comments begin with the character sequence `//` and stop at the end of the line. + +Comments cannot start inside string or regexp literals. +Comments act like newlines. + +## Tokens + +Flux is built up from tokens. +There are four classes of tokens: + +* _identifiers_ +* _keywords_ +* _operators_ +* _literals_ + + +_White space_ formed from spaces, horizontal tabs, carriage returns, and newlines is ignored except as it separates tokens that would otherwise combine into a single token. +While breaking the input into tokens, the next token is the longest sequence of characters that form a valid token. + +## Identifiers + +Identifiers name entities within a program. +An _identifier_ is a sequence of one or more letters and digits. +An identifier must start with a letter. + +```js + identifier = letter { letter | unicode_digit } . +``` + +##### Examples of identifiers + +``` +a +_x +longIdentifierName +αβ +``` + +## Keywords + +The following keywords are reserved and may not be used as identifiers: + +``` +and import not return option test +empty in or package builtin +``` + +{{% note %}} +[IMPL#256](https://github.com/influxdata/platform/issues/256) Add in and empty operator support. +{{% /note %}} + + +## Operators + +The following character sequences represent operators: + +``` ++ == != ( ) => +- < !~ [ ] ^ +* > =~ { } +/ <= = , : +% >= <- . |> +``` + +## Numeric literals + +Numeric literals may be integers or floating point values. +Literals have arbitrary precision and are coerced to a specific type when used. + +The following coercion rules apply to numeric literals: + +* An integer literal can be coerced to an "int", "uint", or "float" type, +* A float literal can be coerced to a "float" type. +* An error will occur if the coerced type cannot represent the literal value. + +{{% note %}} +[IMPL#255](https://github.com/influxdata/platform/issues/255) Allow numeric literal coercion. +{{% /note %}} + +### Integer literals + +An integer literal is a sequence of digits representing an integer value. +Only decimal integers are supported. + +```js + int_lit = "0" | decimal_lit . + decimal_lit = ( "1" … "9" ) { decimal_digit } . +``` + +##### Examples of integer literals + +``` +0 +42 +317316873 +``` + +## Floating-point literals + +A _floating-point literal_ is a decimal representation of a floating-point value. +It has an integer part, a decimal point, and a fractional part. +The integer and fractional part comprise decimal digits. +One of the integer part or the fractional part may be elided. + +```js +float_lit = decimals "." [ decimals ] + | "." decimals . +decimals = decimal_digit { decimal_digit } . +``` + +##### Examples of floating-point literals + +```js +0. +72.40 +072.40 // == 72.40 +2.71828 +.26 +``` + +{{% note %}} +[IMPL#254](https://github.com/influxdata/platform/issues/254) Parse float literals. +{{% /note %}} + +### Duration literals + +A _duration literal_ is a representation of a length of time. +It has an integer part and a duration unit part. +Multiple durations may be specified together and the resulting duration is the sum of each smaller part. +When several durations are specified together, larger units must appear before smaller ones, and there can be no repeated units. + +```js +duration_lit = { int_lit duration_unit } . +duration_unit = "y" | "mo" | "w" | "d" | "h" | "m" | "s" | "ms" | "us" | "µs" | "ns" . +``` + +| Units | Meaning | +| ----- | ------- | +| y | year (12 months) | +| mo | month | +| w | week (7 days) | +| d | day | +| h | hour (60 minutes) | +| m | minute (60 seconds) | +| s | second | +| ms | milliseconds (1 thousandth of a second) | +| us or µs | microseconds (1 millionth of a second) | +| ns | nanoseconds (1 billionth of a second) | + +Durations represent a length of time. +Lengths of time are dependent on specific instants in time they occur and as such, +durations do not represent a fixed amount of time. +There are no amount of days equal to a month, as months vary in their number of days. +Durations are a tuple of positive integers that represent a duration and the sign +of the duration (positive or negative). +Durations are implemented this way so it is possible to determine whether a duration is positive or negative. +Since duration values depend on their context, the only way to know if a duration +is a positive or negative number is if all magnitudes have the same sign. +In the canonical implementation, this is implemented as a tuple of the months and +nanoseconds and a boolean that indicates whether it is positive or negative. +The spec does not prescribe a specific implementation and other implementations +may use a different internal representation. + +Durations cannot be combined by addition and subtraction. +All magnitudes in the tuple must be a positive integer which cannot be guaranteed +when using addition and subtraction. +Durations can be multiplied by any integer value. +The unary negative operator is the equivalent of multiplying the duration by -1. +These operations are performed on each time unit independently. + +##### Examples of duration literals + +```js +1s +10d +1h15m // 1 hour and 15 minutes +5w +1mo5d // 1 month and 5 days +-1mo5d // negative 1 month and 5 days +5w * 2 // 10 weeks +``` +Durations can be added to date times to produce a new date time. + +Addition and subtraction of durations to date times do not commute and are left associative. +Addition and subtraction of durations to date times applies months, days and seconds in that order. +When months are added to a date times and the resulting date is past the end of the month, the day is rolled back to the last day of the month. + +##### Examples of duration literals + +```js +2018-01-01T00:00:00Z + 1d // 2018-01-02T00:00:00Z +2018-01-01T00:00:00Z + 1mo // 2018-02-01T00:00:00Z +2018-01-01T00:00:00Z + 2mo // 2018-03-01T00:00:00Z +2018-01-31T00:00:00Z + 2mo // 2018-03-31T00:00:00Z +2018-02-28T00:00:00Z + 2mo // 2018-04-28T00:00:00Z +2018-01-31T00:00:00Z + 1mo // 2018-02-28T00:00:00Z, February 31th is rolled back to the last day of the month, February 28th in 2018. + +// Addition and subtraction of durations to date times does not commute +2018-02-28T00:00:00Z + 1mo + 1d // 2018-03-29T00:00:00Z +2018-02-28T00:00:00Z + 1mo + 1d // 2018-03-29T00:00:00Z +2018-02-28T00:00:00Z + 1d + 1mo // 2018-04-01T00:00:00Z +2018-01-01T00:00:00Z + 2mo - 1d // 2018-02-28T00:00:00Z +2018-01-01T00:00:00Z - 1d + 3mo // 2018-03-31T00:00:00Z +2018-01-31T00:00:00Z + 1mo + 1mo // 2018-03-28T00:00:00Z +2018-01-31T00:00:00Z + 2mo // 2018-03-31T00:00:00Z + +// Addition and subtraction of durations to date times applies months, days and seconds in that order. +2018-01-28T00:00:00Z + 1mo + 2d // 2018-03-02T00:00:00Z +2018-01-28T00:00:00Z + 1mo2d // 2018-03-02T00:00:00Z +2018-01-28T00:00:00Z + 2d + 1mo // 2018-02-28T00:00:00Z, explicit left associative add of 2d first changes the result +2018-02-01T00:00:00Z + 2mo2d // 2018-04-03T00:00:00Z +2018-01-01T00:00:00Z + 1mo30d // 2018-03-02T00:00:00Z, Months are applied first to get February 1st, then days are added resulting in March 2 in 2018. +2018-01-31T00:00:00Z + 1mo1d // 2018-03-01T00:00:00Z, Months are applied first to get February 28th, then days are added resulting in March 1 in 2018. + +// Multiplication works +2018-01-01T00:00:00Z + 1mo * 1 // 2018-02-01T00:00:00Z +2018-01-01T00:00:00Z + 1mo * 2 // 2018-03-01T00:00:00Z +2018-01-01T00:00:00Z + 1mo * 3 // 2018-04-01T00:00:00Z +2018-01-31T00:00:00Z + 1mo * 1 // 2018-02-28T00:00:00Z +2018-01-31T00:00:00Z + 1mo * 2 // 2018-03-31T00:00:00Z +2018-01-31T00:00:00Z + 1mo * 3 // 2018-04-30T00:00:00Z +``` + +{{% note %}} +[IMPL#657](https://github.com/influxdata/platform/issues/657) Implement Duration vectors. +{{% /note %}} + +## Date and time literals + +A _date and time literal_ represents a specific moment in time. +It has a date part, a time part and a time offset part. +The format follows the [RFC 3339](https://tools.ietf.org/html/rfc3339) specification. +The time is optional. +When it is omitted, the time is assumed to be midnight for the default location. +The `time_offset` is optional. +When it is omitted, the location option is used to determine the offset. + +```js +date_time_lit = date [ "T" time ] . +date = year_lit "-" month "-" day . +year = decimal_digit decimal_digit decimal_digit decimal_digit . +month = decimal_digit decimal_digit . +day = decimal_digit decimal_digit . +time = hour ":" minute ":" second [ fractional_second ] [ time_offset ] . +hour = decimal_digit decimal_digit . +minute = decimal_digit decimal_digit . +second = decimal_digit decimal_digit . +fractional_second = "." { decimal_digit } . +time_offset = "Z" | ("+" | "-" ) hour ":" minute . +``` + +##### Examples of date and time literals + +```js +1952-01-25T12:35:51Z +2018-08-15T13:36:23-07:00 +2009-10-15T09:00:00 // October 15th 2009 at 9 AM in the default location +2018-01-01 // midnight on January 1st 2018 in the default location +``` + +{{% note %}} +[IMPL#152](https://github.com/influxdata/flux/issues/152) Implement shorthand time literals. +{{% /note %}} + +### String literals + +A _string literal_ represents a sequence of characters enclosed in double quotes. +Within the quotes any character may appear except an unescaped double quote. +String literals support several escape sequences. + +``` +\n U+000A line feed or newline +\r U+000D carriage return +\t U+0009 horizontal tab +\" U+0022 double quote +\\ U+005C backslash +\${ U+0024 U+007B dollar sign and opening curly bracket +``` + +Additionally, any byte value may be specified via a hex encoding using `\x` as the prefix. + +``` +string_lit = `"` { unicode_value | byte_value | StringExpression | newline } `"` . +byte_value = `\` "x" hex_digit hex_digit . +hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . +unicode_value = unicode_char | escaped_char . +escaped_char = `\` ( "n" | "r" | "t" | `\` | `"` ) . +StringExpression = "${" Expression "}" . +``` + +##### Examples of string literals + +```js +"abc" +"string with double \" quote" +"string with backslash \\" +"日本語" +"\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 encoding of the previous line +``` + +String literals are also interpolated for embedded expressions to be evaluated as strings. +Embedded expressions are enclosed in a dollar sign and curly braces (`${}`). +The expressions are evaluated in the scope containing the string literal. +The result of an expression is formatted as a string and replaces the string content between the braces. +All types are formatted as strings according to their literal representation. +A function `printf` exists to allow more precise control over formatting of various types. +To include the literal `${` within a string, it must be escaped. + +{{% note %}} +[IMPL#248](https://github.com/influxdata/platform/issues/248) Add printf function. +{{% /note %}} + +##### Example: Interpolation + +```js +n = 42 +"the answer is ${n}" // the answer is 42 +"the answer is not ${n+1}" // the answer is not 43 +"dollar sign opening curly bracket \${" // dollar sign opening curly bracket ${ +``` + +{{% note %}} +[IMPL#1775](https://github.com/influxdata/flux/issues/1775) Interpolate arbitrary expressions in string literals +{{% /note %}} + +### Regular expression literals + +A _regular expression literal_ represents a regular expression pattern, enclosed in forward slashes. +Within the forward slashes, any unicode character may appear except for an unescaped forward slash. +The `\x` hex byte value representation from string literals may also be present. + +Regular expression literals support only the following escape sequences: + +``` +\/ U+002f forward slash +\\ U+005c backslash +``` + +``` +regexp_lit = "/" { unicode_char | byte_value | regexp_escape_char } "/" . +regexp_escape_char = `\` (`/` | `\`) +``` + +##### Examples of regular expression literals + +```js +/.*/ +/http:\/\/localhost:9999/ +/^\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e(ZZ)?$/ +/^日本語(ZZ)?$/ // the above two lines are equivalent +/\\xZZ/ // this becomes the literal pattern "\xZZ" +``` + +The regular expression syntax is defined by [RE2](https://github.com/google/re2/wiki/Syntax). diff --git a/content/influxdb/cloud/reference/flux/language/notation.md b/content/influxdb/cloud/reference/flux/language/notation.md new file mode 100644 index 000000000..e2d4d69ec --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/notation.md @@ -0,0 +1,34 @@ +--- +title: Notation +description: Notation principles for the Flux functional data scripting language. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Notation +weight: 206 +--- + +The syntax of the language is specified using [Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form): + +``` +Production = production_name "=" [ Expression ] "." . +Expression = Alternative { "|" Alternative } . +Alternative = Term { Term } . +Term = production_name | token [ "…" token ] | Group | Option | Repetition . +Group = "(" Expression ")" . +Option = "[" Expression "]" . +Repetition = "{" Expression "}" . +``` + +A _production_ is an expression constructed from terms and the following operators, in increasing precedence: + +``` +| alternation +() grouping +[] option (0 or 1 times) +{} repetition (0 to n times) +``` + +Lowercase production names are used to identify lexical tokens. +Non-terminals are in [camel case](https://en.wikipedia.org/wiki/Camel_case). +Lexical tokens are enclosed in double quotes (`""`) or back quotes (``). diff --git a/content/influxdb/cloud/reference/flux/language/operators.md b/content/influxdb/cloud/reference/flux/language/operators.md new file mode 100644 index 000000000..2e678765d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/operators.md @@ -0,0 +1,151 @@ +--- +title: Operators in the Flux language +description: Flux supports many types of operators including arithmetic operators, comparison operators, function operators, and others. +menu: + influxdb_cloud_ref: + name: Operators + parent: Flux specification +weight: 215 +influxdb/cloud/tags: [operators] +--- + +Flux includes the following types of operators: + +- [Arithmetic operators](#arithmetic-operators) +- [Comparison operators](#comparison-operators) +- [Logical operators](#logical-operators) +- [Assignment operators](#assignment-operators) +- [Function operators](#function-operators) +- [String Operators](#string-operators) +- [Literal constructors](#literal-constructors) +- [Miscellaneous operators](#miscellaneous-operators) + +_Also see:_ + +- [Operator precedence](#operator-precedence) + +## Arithmetic operators +Arithmetic operators take two numerical values (either literals or variables) and +perform a calculation that returns a single numerical value. + +| Operator | Description | Example | Result | +|:--------:|:----------- | ------- | ------ | +| `+` | Addition | `1 + 1` | `2` | +| `-` | Subtraction | `3 - 2` | `1` | +| `*` | Multiplication | `2 * 3` | `6` | +| `/` | Division | `9 / 3` | `3` | +| `^` | Exponentiation | `2 ^ 3` | `8` | +| `%` | Modulo | `10 % 5` | `0` | + +{{% note %}} +In the current version of Flux, values used in arithmetic operations must +be of the same numeric type (integer or float). +Operations with values of different numeric types will result in a type error. +{{% /note %}} + +## Comparison operators +Comparison operators compare expressions and return true or false based on the comparison. + +| Operator | Description | Example | Result | +|:--------:|:----------- | ------- | ------ | +| `==` | Equal to | `"abc" == "abc"` | `true` | +| `!=` | Not equal to | `"abc" != "def"` | `true` | +| `<` | Less than | `1 < 2` | `true` | +| `>` | Greater than | `1 > 2` | `false` | +| `<=` | Less than or equal | `1 <= 2` | `true` | +| `>=` | Greater than or equal | `1 >= 2` | `false` | +| `=~` | Equal to regular expression | `"abc" =~ /[a-z]*/` | `true` | +| `!~` | Not equal to regular expression | `"abc" !~ /[0-9]*/` | `true` | + +{{% note %}} +The `>` and `<` operators also [compare the lexicographic order of strings](#string-operators). +{{% /note %}} + +## Logical operators +| Operator | Description | +|:--------:|:----------- | +| `exists` | Returns `false` if right operand is _**null**_. Otherwise, returns `true`. | +| `and` | Returns `true` if both operands are true. Otherwise, returns `false`. | +| `or` | Returns `true` if any operand is true. Otherwise, returns `false`. | + +#### Short-circuit evaluation +Flux logical operators observe the short-circuiting behavior seen in other programming languages. +The evaluation of the left-hand (LH) operand determines if the right-hand (RH) operand is evaluated. + +- When the operator is `and` and the LH operand evaluates to `false`, the evaluation + returns `false` without evaluating the RH operand. +- When the operator is `or` and the LH operand evaluates to `true`, the evaluation + returns `true` without evaluating the RH operand. + +## Assignment operators +An assignment operator assigns a value to its left operand based on the value of its right operand. + +| Operator | Description | Example | Meaning | +|:--------:|:----------- | ------- | ------- | +| `=` | Assign value of left expression to right expression | `x = y` | x = y | + + +## Function operators +Function operators facilitate the creation of functions and control the flow of data through operations. + +| Operator | Description | Examples | Meaning | +|:--------: |:----------- | -------- | ------- | +| |> | Pipe‑forward | data |> function() | Tables contained in the "data" variable are piped into the function. | +| `<-` | Pipe‑receive | `tables=<-` | The "tables" variable or parameter is assigned to data piped into the operation. _This operator is used for any data type passed into a function; not just table data._ | +| `=>` | Arrow | `(r) => r.tag1 == "tagvalue"` | The arrow passes a record or parameters into function operations. | +| `()` | Function call | `top(n:10)` | Call the `top` function setting the `n` parameter to `10` and perform the associated operations. | + +--- + +_See [Custom functions](/influxdb/cloud/query-data/flux/custom-functions) for examples of function operators is use._ + +--- + +## String Operators +String operators concatenate or compare string values. + +| Operator | Description | Examples | Result | +|:--------:|:----------- | -------- | ------ | +| `+` | Concatenation | `"ab" + "c"` | `"abc"` | +| `<` | Less than in lexicographic order | `"ant" < "bee"` | `true` | +| `>` | Greater than in lexicographic order | `"ant" > "bee"` | `false` | + +## Literal constructors +Literal constructors define fixed values. + +| Operator | Description | +|:--------:| ----------- | +| `[ ]` | List / array | +| `{ }` | Record | +| `""` | String | + +## Miscellaneous operators +| Operator | Description | Example | +|:--------:|:----------- | ------- | +| `( )` | Logical grouping | `r._value / (r._value * 2)` | +| `,` | Sequence delimiter | `item1, item2, item3` | +| `:` | Key-value separator | `{name: "Bob"}` | +| `.` | Member access / dot reference | `r._measurement` | + +## Operator precedence +The table below outlines operator precedence. +Operators with a lower number have higher precedence. + +| Precedence | Operator | Description | +|:----------:|:--------: |:-------------------------- | +| 1 | `a()` | Function call | +| | `a[]` | Member or index access | +| | `.` | Member access | +| 2 | \|> | Pipe forward | +| 3 | `^` | Exponentiation | +| 4 | `*` `/` `%` | Multiplication, division, and modulo | +| 5 | `+` `-` | Addition and subtraction | +| 6 |`==` `!=` | Comparison operators | +| | `<` `<=` | | +| | `>` `>=` | | +| |`=~` `!~` | | +| 7 | `not` | Unary logical operator | +| | `exists` | Null check operator | +| 8 | `and` | Logical AND | +| 9 | `or` | Logical OR | +| 10 | `if` `then` `else` | Conditional | diff --git a/content/influxdb/cloud/reference/flux/language/options.md b/content/influxdb/cloud/reference/flux/language/options.md new file mode 100644 index 000000000..8e738658f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/options.md @@ -0,0 +1,62 @@ +--- +title: Options +description: > + A Flux option represents a storage location for any value of a specified type. + Options are mutable. An option can hold different values during its lifetime. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Options +weight: 212 +--- + +{{% note %}} +This document is a living document and may not represent the current implementation of Flux. +Any section that is not currently implemented is commented with a **[IMPL#XXX]** where +**XXX** is an issue number tracking discussion and progress towards implementation. +{{% /note %}} + +An option represents a storage location for any value of a specified type. +Options are mutable. +An option can hold different values during its lifetime. + +Below is a list of built-in options currently implemented in the Flux language: + +- now +- task +- location + +##### now +The `now` option is a function that returns a time value used as a proxy for the current system time. + +```js +// Query should execute as if the below time is the current system time +option now = () => 2006-01-02T15:04:05-07:00 +``` + +##### task +The `task` option schedules the execution of a Flux query. + +```js +option task = { + name: "foo", // Name is required. + every: 1h, // Task should be run at this interval. + delay: 10m, // Delay scheduling this task by this duration. + cron: "0 2 * * *", // Cron is a more sophisticated way to schedule. 'every' and 'cron' are mutually exclusive. + retry: 5, // Number of times to retry a failed query. +} +``` + +##### location +The `location` option sets the default time zone of all times in the script. +The location maps the UTC offset in use at that location for a given time. +The default value is set using the time zone of the running process. + +```js +option location = fixedZone(offset:-5h) // Set timezone to be 5 hours west of UTC. +option location = loadLocation(name:"America/Denver") // Set location to be America/Denver. +``` + +{{% note %}} +[IMPL#660](https://github.com/influxdata/platform/issues/660) Implement Location option +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/language/packages.md b/content/influxdb/cloud/reference/flux/language/packages.md new file mode 100644 index 000000000..928fa55b7 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/packages.md @@ -0,0 +1,62 @@ +--- +title: Packages +description: > + Flux source is organized into packages. + A package consists of one or more source files. + Each source file is parsed individually and composed into a single package. +aliases: + - /influxdb/cloud/reference/flux/language/programs +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Packages +weight: 207 +--- + +Flux source is organized into packages. +A package consists of one or more source files. +Each source file is parsed individually and composed into a single package. + +```js +File = [ PackageClause ] [ ImportList ] StatementList . +ImportList = { ImportDeclaration } . +``` + +## Package clause + +```js +PackageClause = "package" identifier . +``` + +A _package clause_ defines the name for the current package. +Package names must be valid Flux identifiers. +The package clause must be at the beginning of any Flux source file. +All files in the same package must declare the same package name. +When a file does not declare a package clause, all identifiers in that +file will belong to the special `main` package. + +### Package main + +The `main` package is special for a few reasons: + +1. It defines the entry point of a Flux program. +2. It cannot be imported. +3. All statements are marked as producing side effects. + +## Package initialization + +Packages are initialized in the following order: + +1. All imported packages are initialized and assigned to their package identifier. +2. All option declarations are evaluated and assigned regardless of order. + An option cannot have a dependency on another option assigned in the same package block. +3. All variable declarations are evaluated and assigned regardless of order. A variable cannot have a direct or indirect dependency on itself. +4. Any package side effects are evaluated. + +A package will only be initialized once across all file blocks and across all packages blocks regardless of how many times it is imported. + +Initializing imported packages must be deterministic. +Specifically after all imported packages are initialized, each option must be assigned the same value. +Packages imported in the same file block are initialized in declaration order. +Packages imported across different file blocks have no known order. +When a set of imports modify the same option, they must be ordered by placing them in the same file block. diff --git a/content/influxdb/cloud/reference/flux/language/representation.md b/content/influxdb/cloud/reference/flux/language/representation.md new file mode 100644 index 000000000..14199147f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/representation.md @@ -0,0 +1,37 @@ +--- +title: Representation +description: Source code is encoded in UTF-8. The text need not be canonicalized. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Representation +weight: 209 +--- + +Source code is encoded in UTF-8. +The text need not be canonicalized. + +## Characters + +This document will use the term _character_ to refer to a Unicode code point. + +The following terms are used to denote specific Unicode character classes: + +``` +newline = /* the Unicode code point U+000A */ . +unicode_char = /* an arbitrary Unicode code point except newline */ . +unicode_letter = /* a Unicode code point classified as "Letter" */ . +unicode_digit = /* a Unicode code point classified as "Number, decimal digit" */ . +``` + +In The Unicode Standard 8.0, Section 4.5, "General Category" defines a set of character categories. +Flux treats all characters in any of the Letter categories (Lu, Ll, Lt, Lm, or Lo) as Unicode letters, and those in the Number category (Nd) as Unicode digits. + +### Letters and digits + +The underscore character `_` (`U+005F`) is considered a letter. + +``` +letter = unicode_letter | "_" . +decimal_digit = "0" … "9" . +``` diff --git a/content/influxdb/cloud/reference/flux/language/side-effects.md b/content/influxdb/cloud/reference/flux/language/side-effects.md new file mode 100644 index 000000000..1b4bfdf04 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/side-effects.md @@ -0,0 +1,16 @@ +--- +title: Side effects +description: A summary of side effects in the Flux functional data scripting language. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Side effects +weight: 210 +--- + +Side effects can occur in one of two ways. + +1. By reassigning built-in options +2. By calling a function that produces side effects + +A function produces side effects when it is explicitly declared to have side effects or when it calls a function that itself produces side effects. diff --git a/content/influxdb/cloud/reference/flux/language/statements.md b/content/influxdb/cloud/reference/flux/language/statements.md new file mode 100644 index 000000000..c5830e478 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/statements.md @@ -0,0 +1,81 @@ +--- +title: Statements +description: Statements control execution in the Flux functional data scripting language. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Statements +weight: 211 +--- + +{{% note %}} +This document is a living document and may not represent the current implementation of Flux. +Any section that is not currently implemented is commented with a **[IMPL#XXX]** where +**XXX** is an issue number tracking discussion and progress towards implementation. +{{% /note %}} + +A _statement_ controls execution. + +```js +Statement = OptionAssignment + | BuiltinStatement + | VariableAssignment + | ReturnStatement + | ExpressionStatement . +``` + +## Import declaration + +```js +ImportDeclaration = "import" [identifier] string_lit . +``` + +A package name and an import path is associated with every package. +The import statement takes a package's import path and brings all of the identifiers +defined in that package into the current scope under a namespace. +The import statement defines the namespace through which to access the imported identifiers. +By default the identifier of this namespace is the package name unless otherwise specified. +For example, given a variable `x` declared in package `foo`, importing `foo` and referencing `x` would look like this: + +```js +import "import/path/to/package/foo" + +foo.x +``` + +Or this: + +```js +import bar "import/path/to/package/foo" + +bar.x +``` + +A package's import path is always absolute. +A package may reassign a new value to an option identifier declared in one of its imported packages. +A package cannot access nor modify the identifiers belonging to the imported packages of its imported packages. +Every statement contained in an imported package is evaluated. + +## Return statements + +A terminating statement prevents execution of all statements that appear after it in the same block. +A return statement is a terminating statement. + +``` +ReturnStatement = "return" Expression . +``` +## Expression statements + +An _expression statement_ is an expression where the computed value is discarded. + +``` +ExpressionStatement = Expression . +``` + +##### Examples of expression statements + +```js +1 + 1 +f() +a +``` diff --git a/content/influxdb/cloud/reference/flux/language/string-interpolation.md b/content/influxdb/cloud/reference/flux/language/string-interpolation.md new file mode 100644 index 000000000..f5552123f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/string-interpolation.md @@ -0,0 +1,96 @@ +--- +title: String interpolation +description: > + Flux string interpolation evaluates string literals containing one or more placeholders + and returns a result with placeholders replaced with their corresponding values. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: String interpolation +weight: 211 +--- + +Flux string interpolation evaluates string literals containing one or more placeholders +and returns a result with placeholders replaced with their corresponding values. + +## String interpolation syntax +To use Flux string interpolation, enclose embedded [expressions](/influxdb/cloud/reference/flux/language/expressions/) +in a dollar sign and curly braces `${}`. +Flux replaces the content between the braces with the result of the expression and +returns a string literal. + +```js +name = "John" + +"My name is ${name}." + +// My name is John. +``` + +{{% note %}} +#### Flux only interpolates string values +Flux currently interpolates only string values ([IMP#1775](https://github.com/influxdata/flux/issues/1775)). +Use the [string() function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/string/) +to convert non-string values to strings. + +```js +count = 12 + +"I currently have ${string(v: count)} cats." +``` +{{% /note %}} + + +## Use dot notation to interpolate record values +[Records](/influxdb/cloud/reference/flux/language/expressions/#record-literals) consist of key-value pairs. +Use [dot notation](/influxdb/cloud/reference/flux/language/expressions/#member-expressions) +to interpolate values from a record. + +```js +person = { + name: "John", + age: 42 +} + +"My name is ${person.name} and I'm ${string(v: person.age)} years old." + +// My name is John and I'm 42 years old. +``` + +Flux returns each record in query results as a record. +In Flux row functions, each row record is represented by `r`. +Use dot notation to interpolate specific column values from the `r` record. + +##### Use string interpolation to add a human-readable message +```js +from(bucket: "example-bucket") + |> range(start: -30m) + |> map(fn: (r) => ({ + r with + human-readable: "${r._field} is ${r._value} at ${string(v: r._time)}." + })) +``` + +## String interpolation versus concatenation +Flux supports both string interpolation and string concatenation. +String interpolation is a more concise method for achieving the same result. + +```js +person = { + name: "John", + age: 42 +} + +// String interpolation +"My name is ${person.name} and I'm ${string(v: person.age)} years old." + +// String concatenation +"My name is " + person.name + " and I'm " + string(v: person.age) + " years old." + +// Both return: My name is John and I'm 42 years old. +``` + +{{% note %}} +Check and notification message templates configured in the InfluxDB user interface +**do not** support string concatenation. +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/language/system-built-ins.md b/content/influxdb/cloud/reference/flux/language/system-built-ins.md new file mode 100644 index 000000000..ce9b0fefa --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/system-built-ins.md @@ -0,0 +1,46 @@ +--- +title: System built-ins +description: > + When a built-in value is not expressible in Flux, its value may be defined by the hosting environment. + All such values must have a corresponding builtin statement to declare the existence and type of the built-in value. +aliases: + - /influxdb/cloud/reference/flux/language/built-ins/system-built-ins/ +menu: + influxdb_cloud_ref: + name: System built-ins + parent: Flux specification +weight: 206 +--- + +Flux contains many preassigned values. These preassigned values are defined in the source files for the various built-in packages. + +When a built-in value is not expressible in Flux, its value may be defined by the hosting environment. +All such values must have a corresponding builtin statement to declare the existence and type of the built-in value. + +```js +BuiltinStatement = "builtin" identifer ":" TypeExpression . +TypeExpression = MonoType ["where" Constraints] . + +MonoType = Tvar | Basic | Array | Record | Function . +Tvar = "A" … "Z" . +Basic = "int" | "uint" | "float" | "string" | "bool" | "time" | "duration" | "bytes" | "regexp" . +Array = "[" MonoType "]" . +Record = ( "{" [Properties] "}" ) | ( "{" Tvar "with" Properties "}" ) . +Function = "(" [Parameters] ")" "=>" MonoType . + +Properties = Property { "," Property } . +Property = identifier ":" MonoType . + +Parameters = Parameter { "," Parameter } . +Parameter = [ "<-" | "?" ] identifier ":" MonoType . + +Constraints = Constraint { "," Constraint } . +Constraint = Tvar ":" Kinds . +Kinds = identifier { "+" identifier } . +``` + +##### Example + +```js +builtin filter : (<-tables: [T], fn: (r: T) => bool) => [T] +``` diff --git a/content/influxdb/cloud/reference/flux/language/types.md b/content/influxdb/cloud/reference/flux/language/types.md new file mode 100644 index 000000000..d492eaf80 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/types.md @@ -0,0 +1,279 @@ +--- +title: Types +description: A type defines the set of values and operations on those values. Types are never explicitly declared as part of the syntax. Types are always inferred from the usage of the value. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Types +weight: 213 +--- + +{{% note %}} +This document is a living document and may not represent the current implementation of Flux. +Any section that is not currently implemented is commented with a **[IMPL#XXX]** where +**XXX** is an issue number tracking discussion and progress towards implementation. +{{% /note %}} + +A **type** defines the set of values and operations on those values. +Types are never explicitly declared as part of the syntax except as part of a [builtin statement](/influxdb/cloud/reference/flux/language/system-built-ins/). +Types are always inferred from the usage of the value. +Type inference follows a Hindley-Milner style inference system. + +## Union types +A union type defines a set of types. +In the examples below, a union type is specified as follows: + +```js +T = t1 | t2 | ... | tn +``` + +where `t1`, `t2`, ..., and `tn` are types. + +In the example above a value of type `T` is either of type `t1`, type `t2`, ..., or type `tn`. + +## Basic types +All Flux data types are constructed from the following types: + +### Null types +The **null type** represents a missing or unknown value. +The **null type** name is `null`. +There is only one value that comprises the _null type_ and that is the _null_ value. +A type `t` is nullable if it can be expressed as follows: + +```js +t = {s} | null +``` + +where `{s}` defines a set of values. + +### Boolean types +A _boolean type_ represents a truth value, corresponding to the preassigned variables `true` and `false`. +The boolean type name is `bool`. +The boolean type is nullable and can be formally specified as follows: + +```js +bool = {true, false} | null +``` + +### Numeric types +A _numeric type_ represents sets of integer or floating-point values. + +The following numeric types exist: + +``` +uint the set of all unsigned 64-bit integers | null +int the set of all signed 64-bit integers | null +float the set of all IEEE-754 64-bit floating-point numbers | null +``` + +{{% note %}} +All numeric types are nullable. +{{% /note %}} + +### Time types +A _time type_ represents a single point in time with nanosecond precision. +The time type name is `time`. +The time type is nullable. + +#### Timestamp format +Flux supports [RFC3339 timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp): + +- `YYYY-MM-DD` +- `YYYY-MM-DDT00:00:00Z` +- `YYYY-MM-DDT00:00:00.000Z` + +### Duration types +A _duration type_ represents a length of time with nanosecond precision. +The duration type name is `duration`. +The duration type is nullable + +Durations can be added to times to produce a new time. + +##### Examples of duration types +```js +1ns // 1 nanosecond +1us // 1 microsecond +1ms // 1 millisecond +1s // 1 second +1m // 1 minute +1h // 1 hour +1d // 1 day +1w // 1 week +1mo // 1 calendar month +1y // 1 calendar year + +3d12h4m25s // 3 days, 12 hours, 4 minutes, and 25 seconds +``` + +### String types +A _string type_ represents a possibly empty sequence of characters. +Strings are immutable and cannot be modified once created. +The string type name is `string`. +The string type is nullable. + +{{% note %}} +An empty string is **not** a _null_ value. +{{% /note %}} + +The length of a string is its size in bytes, not the number of characters, +since a single character may be multiple bytes. + +### Bytes types +A _bytes type_ represents a sequence of byte values. +The bytes type name is `bytes`. + +## Regular expression types +A _regular expression type_ represents the set of all patterns for regular expressions. +The regular expression type name is `regexp`. +The regular expression type is **not** nullable. + +## Composite types +These are types constructed from basic types. +Composite types are not nullable. + +### Array types +An _array type_ represents a sequence of values of any other type. +All values in the array must be of the same type. +The length of an array is the number of elements in the array. + +### Record types +A _record type_ represents a set of unordered key and value pairs. +The key must always be a string. +The value may be any other type, and need not be the same as other values within the record. + +Keys in a record may only be referenced statically. + +Type inference determines the properties that are present in a record. +If type inference determines all the properties in a record, it is said to be "bounded." +Not all keys may be known in the type of a record, in which case the record is said to be "unbounded." +An unbounded record may contain any property in addition to the properties it is known to contain. + +### Function types +A _function type_ represents a set of all functions with the same argument and result types. + +{{% note %}} +[IMPL#249](https://github.com/influxdata/platform/issues/249) Specify type inference rules. +{{% /note %}} + +### Generator types +A _generator type_ represents a value that produces an unknown number of other values. +The generated values may be of any other type, but must all be the same type. + +{{% note %}} +[IMPL#658](https://github.com/influxdata/platform/query/issues/658) Implement Generators types. +{{% /note %}} + +## Polymorphism +Flux functions can be polymorphic, meaning a function can be applied to arguments of different types. +Flux supports parametric, record, and ad hoc polymorphism. + +### Parametric polymorphism +Parametric polymorphism is the notion that a function can be applied uniformly to arguments of any type. +For example: + +```js +f = (x) => x +f(x: 1) +f(x: 1.1) +f(x: "1") +f(x: true) +f(x: f) +``` + +The identifiers, `a` and `b`, in the body of the `add` function are used as both `int` and `float` types. + +### Record polymorphism +Record polymorphism is the notion that a function can be applied to different types of records. +For example: + +```js +john = {name:"John", lastName:"Smith"} +jane = {name:"Jane", age:44} + +// John and Jane are records with different types. +// We can still define a function that can operate on both records safely. + +// name returns the name of a person +name = (person) => person.name + +name(person:john) // John +name(person:jane) // Jane + +device = {id: 125325, lat: 15.6163, lon: 62.6623} + +name(person:device) // Type error, "device" does not have a property name. +``` + +Records of differing types can be passed to the same function as long as they contain the necessary properties. +The necessary properties are determined by the use of the record. + +### Ad hoc polymorphism +Ad hoc polymorphism is the notion that a function can be applied to arguments of +different types with different behavior depending on the type. + +```js +add = (a, b) => a + b + +// Integer addition +add(a: 1, b: 1) + +// String concatenation +add(a: "str", b: "ing") + +// Addition not defined for boolean data types +add(a: true, b: false) +``` + +## Type constraints +Type constraints are to implement static ad hoc polymorphism. +For example, the following function is defined only for `Addable` types: + +```js +add = (a, b) => a + b +``` + +Passing a record to `add()` results in compile-time type error because records are not addable. + +```js +// Records are not Addable and will result in an error. +add(a: {}, b: {}) +``` + +Constraints are never explicitly declared but rather inferred from the context. + +### Addable constraint +Addable types are those the binary arithmetic operator `+` accepts. +Integer, Uinteger, Float, and String types are `Addable`. + +### Subtractable constraint +Subtractable types are those the binary arithmetic operator `-` accepts. +Integer, Uinteger, and Float types are `Subtractable`. + +### Divisible constraint +Divisible types are those the binary arithmetic operator `\` accepts. +Integer, Uinteger, and Float types are `Divisible`. + +### Numeric Constraint +Integer, Uinteger, and Float types are `Numeric`. + +### Comparable Constraint +Comparable types are those the binary comparison operators `<`, `<=`, `>`, or `>=` accept. +Integer, Uinteger, Float, String, Duration, and Time types are `Comparable`. + +### Equatable Constraint +Equatable types are those that can be compared for equality using the `==` or `!=` operators. +Boolean, Integer, Uinteger, Float, String, Duration, Time, Bytes, Array, and Record types are `Equatable`. + +### Nullable Constraint +Nullable types are those that can be _null_. +Boolean, Integer, Uinteger, Float, String, Duration, and Time types are `Nullable`. + +### Record Constraint +Records are the only types that fall under this constraint. + +### Negatable Constraint +Negatable types ore those the unary arithmetic operator `-` accepts. +Integer, Uinteger, Float, and Duration types are `Negatable`. + +### Timeable Constraint +Duration and Time types are `Timeable`. diff --git a/content/influxdb/cloud/reference/flux/language/variables.md b/content/influxdb/cloud/reference/flux/language/variables.md new file mode 100644 index 000000000..98f97f9b5 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/language/variables.md @@ -0,0 +1,13 @@ +--- +title: Variables +description: Flux variables hold values. A variable can only hold values defined by its type. +menu: + influxdb_cloud_ref: + parent: Flux specification + name: Variables +weight: 214 +--- + +A **variable** represents a storage location for a single value. +Variables are immutable. +Once a variable is given a value, it holds that value for the remainder of its lifetime. diff --git a/content/influxdb/cloud/reference/flux/stdlib/_index.md b/content/influxdb/cloud/reference/flux/stdlib/_index.md new file mode 100644 index 000000000..a93bdccf9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/_index.md @@ -0,0 +1,18 @@ +--- +title: Flux standard library +description: > + The Flux standard library includes built-in functions and importable packages + that retrieve, transform, process, and output data. +aliases: + - /influxdb/cloud/reference/flux/functions/ +influxdb/v2.0/tags: [flux, functions, package] +menu: + influxdb_cloud_ref: + parent: Flux language +weight: 102 +--- + +The Flux standard library includes built-in functions and importable packages +that retrieve, transform, process, and output data. + +{{< children >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/all-functions.md b/content/influxdb/cloud/reference/flux/stdlib/all-functions.md new file mode 100644 index 000000000..e4cbec6d9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/all-functions.md @@ -0,0 +1,15 @@ +--- +title: Complete list of Flux functions +description: View the full library of documented Flux functions. +aliases: + - /influxdb/cloud/reference/flux/functions/all-functions/ +menu: + influxdb_cloud_ref: + name: View all functions + parent: Flux standard library +weight: 299 +--- + +This list below contains all documented Flux functions: + +{{< list-all-functions >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/_index.md new file mode 100644 index 000000000..6e55b367d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/_index.md @@ -0,0 +1,22 @@ +--- +title: Flux built-in functions +list_title: Built-in functions +description: > + Built-in functions provide a foundation for working with data using Flux. + They do not require an import statement and are usable without any extra setup. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/ +menu: + influxdb_cloud_ref: + name: Built-in + parent: Flux standard library +weight: 201 +influxdb/v2.0/tags: [built-in, functions, package] +--- + +Built-in functions provide a foundation for working with data using Flux. +Because these functions are "built-in," they do not require an `import` statement and are usable without any extra setup. + +Built-in functions are grouped into the following categories: + +{{< children >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/_index.md new file mode 100644 index 000000000..72ec0dac1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/_index.md @@ -0,0 +1,20 @@ +--- +title: Flux built-in input functions +list_title: Built-in input functions +description: Flux's built-in input functions define sources of data or or display information about data sources. +aliases: + - /influxdb/cloud/reference/flux/functions/inputs + - /influxdb/cloud/reference/flux/functions/built-in/inputs/ +menu: + influxdb_cloud_ref: + parent: Built-in + name: Inputs + identifier: built-in-inputs +weight: 301 +influxdb/v2.0/tags: [inputs, built-in, functions] +--- + +Flux's built-in input functions define sources of data or display information about data sources. +The following input functions are available: + +{{< children type="functions" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/buckets.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/buckets.md new file mode 100644 index 000000000..a568cf3f5 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/buckets.md @@ -0,0 +1,22 @@ +--- +title: buckets() function +description: The `buckets()` function returns a list of buckets in the organization. +aliases: + - /influxdb/cloud/reference/flux/functions/inputs/buckets + - /influxdb/cloud/reference/flux/functions/built-in/inputs/buckets/ +menu: + influxdb_cloud_ref: + name: buckets + parent: built-in-inputs +weight: 401 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-databases, InfluxQL - SHOW DATABASES]() +--- + +The `buckets()` function returns a list of buckets in the organization. + +_**Function type:** Input_ + +```js +buckets() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from.md new file mode 100644 index 000000000..6e439774d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from.md @@ -0,0 +1,105 @@ +--- +title: from() function +description: The `from()` function retrieves data from an InfluxDB data source. +aliases: + - /influxdb/cloud/reference/flux/functions/inputs/from + - /influxdb/cloud/reference/flux/functions/built-in/inputs/from/ +menu: + influxdb_cloud_ref: + name: from + parent: built-in-inputs +weight: 401 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#from-clause, InfluxQL - FROM +--- + +The `from()` function retrieves data from an InfluxDB data source. +It returns a stream of tables from the specified [bucket](#parameters). +Each unique series is contained within its own table. +Each record in the table represents a single point in the series. + +_**Function type:** Input_ +_**Output data type:** Record_ + +```js +from( + bucket: "example-bucket", + host: "https://example.com", + org: "example-org", + token: "MySuP3rSecr3Tt0k3n" +) + +// OR + +from( + bucketID: "0261d8287f4d6000", + host: "https://example.com", + orgID: "example-org", + token: "MySuP3rSecr3Tt0k3n" +) +``` + +## Parameters + +{{% note %}} +[host](#host), [org](#org) or [orgID](#orgid), and [token](#token) parameters +are only required when querying data from a **different organization** or a +**remote InfluxDB instance**. +{{% /note %}} + +### bucket +Name of the bucket to query. + +_**Data type:** String_ + +### bucketID +String-encoded bucket ID to query. + +_**Data type:** String_ + +### host +URL of the InfluxDB instance to query. +_See [InfluxDB URLs](/influxdb/cloud/reference/urls/)._ + +_**Data type:** String_ + +### org +Organization name. + +_**Data type:** String_ + +### orgID +String-encoded [organization ID](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id) to query. + +_**Data type:** String_ + +### token +InfluxDB [authentication token](/influxdb/cloud/security/tokens/). + +_**Data type:** String_ + +## Examples + +##### Query using the bucket name +```js +from(bucket: "example-bucket") +``` + +##### Query using the bucket ID +```js +from(bucketID: "0261d8287f4d6000") +``` + +##### Query a remote InfluxDB Cloud instance +```js +import "influxdata/influxdb/secrets" + +token = secrets.get(key: "INFLUXDB_CLOUD_TOKEN") + +from( + bucket: "example-bucket", + host: "https://cloud2.influxdata.com", + org: "example-org", + token: token +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/_index.md new file mode 100644 index 000000000..440775a83 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/_index.md @@ -0,0 +1,23 @@ +--- +title: Flux built-in miscellaneous functions +list_title: Built-in miscellaneous functions +description: > + Flux provides built-in miscellaneous functions that serve purposes other than + retrieving, transforming, or outputting data. +aliases: + - /influxdb/cloud/reference/flux/functions/misc + - /influxdb/cloud/reference/flux/functions/built-in/misc/ +menu: + influxdb_cloud_ref: + parent: Built-in + name: Miscellaneous + identifier: built-in-misc +weight: 305 +influxdb/v2.0/tags: [built-in, functions] +--- + +Flux's built-in functions primarily retrieve, shape and transform, then output data, however +there are functions available that serve other purposes. +The following functions are are available but don't fit within other function categories: + +{{< children type="functions" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/intervals.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/intervals.md new file mode 100644 index 000000000..85b37755f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/intervals.md @@ -0,0 +1,163 @@ +--- +title: intervals() function +description: The `intervals()` function generates a set of time intervals over a range of time. +aliases: + - /influxdb/cloud/reference/flux/functions/misc/intervals + - /influxdb/cloud/reference/flux/functions/built-in/misc/intervals/ + - /influxdb/cloud/reference/flux/stdlib/built-in/misc/intervals +menu: + influxdb_cloud_ref: + name: intervals + parent: built-in-misc +weight: 401 +draft: true +--- + +The `intervals()` function generates a set of time intervals over a range of time. + +An interval is a record with `start` and `stop` properties that correspond to the inclusive start and exclusive stop times of the time interval. +The return value of intervals is another function that accepts start and stop time parameters and returns an interval generator. +The generator is then used to produce the set of intervals. +The set of intervals includes all intervals that intersect with the initial range of time. + +{{% note %}} +The `intervals()` function is designed to be used with the intervals parameter +of the [`window()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window). +{{% /note %}} + +By default the end boundary of an interval will align with the Unix epoch (zero time) +modified by the offset of the `location` option. + +_**Function type:** Miscellaneous_ +_**Output data type:** Record_ + +```js +intervals() +``` + +## Parameters + +### every +The duration between starts of each of the intervals. +The Nth interval start time is the initial start time plus the offset plus an Nth multiple of the every parameter. +Defaults to the value of the `period` duration. + +_**Data type:** Duration_ + +### period +The length of each interval. +Each interval's stop time is equal to the interval start time plus the period duration. +It can be negative, indicating the start and stop boundaries are reversed. +Defaults to the value of the `every` duration. + +_**Data type:** Duration_ + +### offset +The duration by which to shift the window boundaries. +It can be negative, indicating that the offset goes backwards in time. +Defaults to `0`, which will align window end boundaries with the `every` duration. + +_**Data type:** Duration_ + +### filter +A function that accepts an interval record and returns a boolean value. +Each potential interval is passed to the filter function. +When the function returns false, that interval is excluded from the set of intervals. +Defaults to include all intervals. + +_**Data type:** Function_ + +## Examples + +##### Basic intervals +```js +// 1 hour intervals +intervals(every:1h) + +// 2 hour long intervals every 1 hour +intervals(every:1h, period:2h) + +// 2 hour long intervals every 1 hour starting at 30m past the hour +intervals(every:1h, period:2h, offset:30m) + +// 1 week intervals starting on Monday (by default weeks start on Sunday) +intervals(every:1w, offset:1d) + +// the hour from 11PM - 12AM every night +intervals(every:1d, period:-1h) + +// the last day of each month +intervals(every:1mo, period:-1d) +``` + +##### Using a predicate +```js +// 1 day intervals excluding weekends +intervals( + every:1d, + filter: (interval) => !(weekday(time: interval.start) in [Sunday, Saturday]), +) + +// Work hours from 9AM - 5PM on work days. +intervals( + every:1d, + period:8h, + offset:9h, + filter:(interval) => !(weekday(time: interval.start) in [Sunday, Saturday]), +) +``` + +##### Using known start and stop dates +```js +// Every hour for six hours on Sep 5th. +intervals(every:1h)(start:2018-09-05T00:00:00-07:00, stop: 2018-09-05T06:00:00-07:00) + +// Generates +// [2018-09-05T00:00:00-07:00, 2018-09-05T01:00:00-07:00) +// [2018-09-05T01:00:00-07:00, 2018-09-05T02:00:00-07:00) +// [2018-09-05T02:00:00-07:00, 2018-09-05T03:00:00-07:00) +// [2018-09-05T03:00:00-07:00, 2018-09-05T04:00:00-07:00) +// [2018-09-05T04:00:00-07:00, 2018-09-05T05:00:00-07:00) +// [2018-09-05T05:00:00-07:00, 2018-09-05T06:00:00-07:00) + +// Every hour for six hours with 1h30m periods on Sep 5th +intervals(every:1h, period:1h30m)(start:2018-09-05T00:00:00-07:00, stop: 2018-09-05T06:00:00-07:00) + +// Generates +// [2018-09-05T00:00:00-07:00, 2018-09-05T01:30:00-07:00) +// [2018-09-05T01:00:00-07:00, 2018-09-05T02:30:00-07:00) +// [2018-09-05T02:00:00-07:00, 2018-09-05T03:30:00-07:00) +// [2018-09-05T03:00:00-07:00, 2018-09-05T04:30:00-07:00) +// [2018-09-05T04:00:00-07:00, 2018-09-05T05:30:00-07:00) +// [2018-09-05T05:00:00-07:00, 2018-09-05T06:30:00-07:00) + +// Every hour for six hours using the previous hour on Sep 5th +intervals(every:1h, period:-1h)(start:2018-09-05T12:00:00-07:00, stop: 2018-09-05T18:00:00-07:00) + +// Generates +// [2018-09-05T11:00:00-07:00, 2018-09-05T12:00:00-07:00) +// [2018-09-05T12:00:00-07:00, 2018-09-05T13:00:00-07:00) +// [2018-09-05T13:00:00-07:00, 2018-09-05T14:00:00-07:00) +// [2018-09-05T14:00:00-07:00, 2018-09-05T15:00:00-07:00) +// [2018-09-05T15:00:00-07:00, 2018-09-05T16:00:00-07:00) +// [2018-09-05T16:00:00-07:00, 2018-09-05T17:00:00-07:00) +// [2018-09-05T17:00:00-07:00, 2018-09-05T18:00:00-07:00) + +// Every month for 4 months starting on Jan 1st +intervals(every:1mo)(start:2018-01-01, stop: 2018-05-01) + +// Generates +// [2018-01-01, 2018-02-01) +// [2018-02-01, 2018-03-01) +// [2018-03-01, 2018-04-01) +// [2018-04-01, 2018-05-01) + +// Every month for 4 months starting on Jan 15th +intervals(every:1mo)(start:2018-01-15, stop: 2018-05-15) + +// Generates +// [2018-01-15, 2018-02-15) +// [2018-02-15, 2018-03-15) +// [2018-03-15, 2018-04-15) +// [2018-04-15, 2018-05-15) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/length.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/length.md new file mode 100644 index 000000000..56965b36e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/length.md @@ -0,0 +1,31 @@ +--- +title: length() function +description: The `length()` function returns the number of items in an array. +menu: + influxdb_cloud_ref: + name: length + parent: built-in-misc +weight: 401 +--- + +The `length()` function returns the number of items in an array. + +_**Function type:** Miscellaneous_ + +```js +length(arr: []) +``` + +## Parameters + +### arr +The array to evaluate. + +## Examples +```js +people = ["John", "Jane", "Abed"] + +length(arr: people) + +// Returns 3 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/linearbins.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/linearbins.md new file mode 100644 index 000000000..c55e00e4b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/linearbins.md @@ -0,0 +1,54 @@ +--- +title: linearBins() function +description: The `linearBins()` function generates a list of linearly separated floats. +aliases: + - /influxdb/cloud/reference/flux/functions/misc/linearbins + - /influxdb/cloud/reference/flux/functions/built-in/misc/linearbins/ +menu: + influxdb_cloud_ref: + name: linearBins + parent: built-in-misc +weight: 401 +--- + +The `linearBins()` function generates a list of linearly separated floats. +It is a helper function meant to generate bin bounds for the +[`histogram()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/histogram). + +_**Function type:** Miscellaneous_ +_**Output data type:** Array of floats_ + +```js +linearBins(start: 0.0, width: 5.0, count: 20, infinity: true) +``` + +## Parameters + +### start +The first value in the returned list. + +_**Data type:** Float_ + +### width +The distance between subsequent bin values. + +_**Data type:** Float_ + +### count +The number of bins to create. + +_**Data type:** Integer_ + +### infinity +When `true`, adds an additional bin with a value of positive infinity. +Defaults to `true`. + +_**Data type:** Boolean_ + +## Examples + +```js +linearBins(start: 0.0, width: 10.0, count: 10) + +// Generated list: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, +Inf] +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/logarithmicbins.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/logarithmicbins.md new file mode 100644 index 000000000..07d91f8d3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/logarithmicbins.md @@ -0,0 +1,53 @@ +--- +title: logarithmicBins() function +description: The `logarithmicBins()` function generates a list of exponentially separated floats. +aliases: + - /influxdb/cloud/reference/flux/functions/misc/logarithmicbins + - /influxdb/cloud/reference/flux/functions/built-in/misc/logarithmicbins/ +menu: + influxdb_cloud_ref: + name: logarithmicBins + parent: built-in-misc +weight: 401 +--- + +The `logarithmicBins()` function generates a list of exponentially separated floats. +It is a helper function meant to generate bin bounds for the +[`histogram()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/histogram). + +_**Function type:** Miscellaneous_ +_**Output data type:** Array of floats_ + +```js +logarithmicBins(start:1.0, factor: 2.0, count: 10, infinity: true) +``` + +## Parameters + +### start +The first value in the returned bin list. + +_**Data type:** Float_ + +### factor +The multiplier applied to each subsequent bin. + +_**Data type:** Float_ + +### count +The number of bins to create. + +_**Data type:** Integer_ + +### infinity +When `true`, adds an additional bin with a value of positive infinity. +Defaults to `true`. + +_**Data type:** Boolean_ + +## Examples +```js +logarithmicBins(start: 1.0, factor: 2.0, count: 10, infinity: true) + +// Generated list: [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, +Inf] +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/now.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/now.md new file mode 100644 index 000000000..12ff0d88c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/now.md @@ -0,0 +1,50 @@ +--- +title: now() function +description: The `now()` function returns the current time (UTC). +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/misc/now/ +menu: + influxdb_cloud_ref: + name: now + parent: built-in-misc +weight: 401 +related: + - /influxdb/cloud/reference/flux/stdlib/system/time/ +--- + +The `now()` function returns the current time (UTC) or the time defined in the `now` option. + +_**Function type:** Date/Time_ +_**Output data type:** Time_ + +```js +now() +``` + +## Examples + +##### Use the current UTC time as a query boundary +```js +data + |> range(start: -10h, stop: now()) +``` + +##### Return the now option time +```js +option now = () => 2020-01-01T00:00:00Z + +now() +// Returns 2020-01-01T00:00:00.000000000Z +``` + +{{% note %}} +#### now() vs system.time() +`now()` returns the current UTC time. +`now()` is cached at runtime, so all instances of `now()` in a Flux script +return the same value. + +[`system.time()`](/influxdb/cloud/reference/flux/stdlib/system/time/) returns the current +system time of the host machine, which typically accounts for the local time zone. +This time represents the time at which `system.time()` it is executed, so each +instance of `system.time()` in a Flux script returns a unique value. +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/sleep.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/sleep.md new file mode 100644 index 000000000..173ba5bc9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/misc/sleep.md @@ -0,0 +1,55 @@ +--- +title: sleep() function +description: The `sleep()` function delays execution by a specified duration. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/misc/sleep/ +menu: + influxdb_cloud_ref: + name: sleep + parent: built-in-misc +weight: 401 +--- + +The `sleep()` function delays execution by a specified duration. + +_**Function type:** Miscellaneous_ + +```js +sleep( + v: x, + duration: 10s +) +``` + +## Parameters + +### v +Defines input tables. +`sleep()` accepts piped-forward data and passes it on unmodified after the +specified [duration](#duration). +If data is not piped-forward into `sleep()`, set `v` to specify a stream of tables. +The examples [below](#examples) illustrate how. + +_**Data type:** Record_ + +### duration +The length of time to delay execution. + +_**Data type:** Duration_ + +## Examples + +### Delay execution in a chained query +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> sleep(duration: 10s) +``` + +### Delay execution using a stream variable +```js +x = from(bucket: "example-bucket") + |> range(start: -1h) + +sleep(v: x, duration: 10s) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/_index.md new file mode 100644 index 000000000..b181a23b3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/_index.md @@ -0,0 +1,20 @@ +--- +title: Flux built-in output functions +list_title: Built-in output functions +description: Flux's built-in output functions yield results or send data to a specified output destination. +aliases: + - /influxdb/cloud/reference/flux/functions/outputs + - /influxdb/cloud/reference/flux/functions/built-in/outputs/ +menu: + influxdb_cloud_ref: + parent: Built-in + name: Outputs + identifier: built-in-outputs +weight: 302 +influxdb/v2.0/tags: [outputs, built-in, functions] +--- + +Flux's built-in output functions yield results or send data to a specified output destination. +The following output functions are are available: + +{{< children type="functions" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/to.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/to.md new file mode 100644 index 000000000..ac69c2c3f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/to.md @@ -0,0 +1,179 @@ +--- +title: to() function +description: The `to()` function writes data to an InfluxDB v2.0 bucket. +aliases: + - /influxdb/cloud/reference/flux/functions/outputs/to + - /influxdb/cloud/reference/flux/functions/built-in/outputs/to/ +menu: + influxdb_cloud_ref: + name: to + parent: built-in-outputs +weight: 401 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#the-into-clause, InfluxQL – SELECT INTO +--- + +The `to()` function writes data to an **InfluxDB v2.0** bucket. + +_**Function type:** Output_ + +```js +to( + bucket: "my-bucket", + org: "my-org", + timeColumn: "_time", + tagColumns: ["tag1", "tag2", "tag3"], + fieldFn: (r) => ({ [r._field]: r._value }) +) + +// OR + +to( + bucketID: "1234567890", + orgID: "0987654321", + timeColumn: "_time", + tagColumns: ["tag1", "tag2", "tag3"], + fieldFn: (r) => ({ [r._field]: r._value }) +) +``` + +### Output data requirements +The `to()` function converts output data into line protocol and writes it to InfluxDB. +Line protocol requires each record to have a timestamp, a measurement, a field, and a value. +All output data must include the following columns: + +- `_time` +- `_measurement` +- `_field` +- `_value` + +{{% note %}} +The `to()` function ignores rows with a null `_time` value and does not write +them to InfluxDB. +{{% /note %}} + +## Parameters + +{{% note %}} +You must provide a `bucket` or `bucketID` and an `org` or `orgID`. +{{% /note %}} + +### bucket +The bucket to write data to. +`bucket` and `bucketID` are mutually exclusive. + +_**Data type:** String_ + +### bucketID +The ID of the bucket to write data to. +`bucketID` and `bucket` are mutually exclusive. + +_**Data type:** String_ + +### org +The organization name of the specified [`bucket`](#bucket). +`org` and `orgID` are mutually exclusive. + +_**Data type:** String_ + +### orgID +The organization ID of the specified [`bucket`](#bucket). +`orgID` and `org` are mutually exclusive. + +_**Data type:** String_ + + + +### timeColumn +Time column of the output. +Default is `"_time"`. + +_**Data type:** String_ + +### tagColumns +Tag columns in the output. +Defaults to all columns with type `string`, excluding all value columns and columns +identified by [`fieldFn`](#fieldfn). + +_**Data type:** Array of strings_ + +### fieldFn +Function that takes a record from the input table and returns a record. +For each record from the input table, `fieldFn` returns a record that maps the +output field key to the output value. +Default is `(r) => ({ [r._field]: r._value })` + +_**Data type:** Function_ +_**Output data type:** Record_ + +{{% note %}} +Make sure `fieldFn` parameter names match each specified parameter. +To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +## Examples + +### Default to() operation + +Given the following table: + +| _time | _start | _stop | _measurement | _field | _value | +| ----- | ------ | ----- | ------------ | ------ | ------ | +| 0005 | 0000 | 0009 | "a" | "temp" | 100.1 | +| 0006 | 0000 | 0009 | "a" | "temp" | 99.3 | +| 0007 | 0000 | 0009 | "a" | "temp" | 99.9 | + +The default `to` operation: + +```js +// ... +|> to(bucket:"my-bucket", org:"my-org") +``` + +is equivalent to writing the above data using the following line protocol: + +``` +_measurement=a temp=100.1 0005 +_measurement=a temp=99.3 0006 +_measurement=a temp=99.9 0007 +``` + +### Custom to() operation + +The `to()` functions default operation can be overridden. For example, given the following table: + +| _time | _start | _stop | tag1 | tag2 | hum | temp | +| ----- | ------ | ----- | ---- | ---- | ---- | ----- | +| 0005 | 0000 | 0009 | "a" | "b" | 55.3 | 100.1 | +| 0006 | 0000 | 0009 | "a" | "b" | 55.4 | 99.3 | +| 0007 | 0000 | 0009 | "a" | "b" | 55.5 | 99.9 | + +The operation: + +```js +// ... +|> to( + bucket:"my-bucket", + org:"my-org", + tagColumns:["tag1"], + fieldFn: (r) => ({"hum": r.hum, "temp": r.temp}) +) +``` + +is equivalent to writing the above data using the following line protocol: + +``` +_tag1=a hum=55.3,temp=100.1 0005 +_tag1=a hum=55.4,temp=99.3 0006 +_tag1=a hum=55.5,temp=99.9 0007 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/yield.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/yield.md new file mode 100644 index 000000000..b70ba5bab --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/outputs/yield.md @@ -0,0 +1,45 @@ +--- +title: yield() function +description: The `yield()` function indicates the input tables received should be delivered as a result of the query. +aliases: + - /influxdb/cloud/reference/flux/functions/outputs/yield + - /influxdb/cloud/reference/flux/functions/built-in/outputs/yield/ +menu: + influxdb_cloud_ref: + name: yield + parent: built-in-outputs +weight: 401 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#the-basic-select-statement, InfluxQL – SELECT AS +--- + +The `yield()` function indicates the input tables received should be delivered as a result of the query. +Yield outputs the input stream unmodified. +A query may have multiple results, each identified by the name provided to the `yield()` function. + +_**Function type:** Output_ +_**Output data type:** Record_ + +```js +yield(name: "custom-name") +``` + +{{% note %}} +`yield()` is implicit for queries that do only one thing and are only needed when using multiple sources in a query. +With multiple sources, `yield()` is required to specify what is returned, and what name to give it. +{{% /note %}} + +## Parameters + +### name +A unique name for the yielded results. +Defaults to `"_results"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> yield(name: "1") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/tests/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/tests/_index.md new file mode 100644 index 000000000..345ffd7f2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/tests/_index.md @@ -0,0 +1,19 @@ +--- +title: Flux built-in testing functions +list_title: Built-in testing functions +description: Flux's built-in testing functions test various aspects of piped-forward data. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/tests/ +menu: + influxdb_cloud_ref: + name: Tests + identifier: built-in-tests + parent: Built-in +weight: 305 +influxdb/v2.0/tags: [testing, built-in, functions] +--- + +Flux's built-in testing functions test various aspects of piped-forward data. +The following built-in testing functions are available: + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/tests/contains.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/tests/contains.md new file mode 100644 index 000000000..5aaff9eba --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/tests/contains.md @@ -0,0 +1,48 @@ +--- +title: contains() function +description: The `contains()` function tests whether a value is a member of a set. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/tests/contains/ +menu: + influxdb_cloud_ref: + name: contains + parent: built-in-tests +weight: 401 +--- + +The `contains()` function tests whether a value is a member of a set. +If the value is a member of the set, the function returns `true`. +If the value is not a member of the set, the functions returns `false`. + +```js +contains( + value: 1, + set: [1,2,3] +) +``` + +## Parameters + +### value +The value for which to search. + +_**Data type:** Boolean | Integer | UInteger | Float | String | Time_ + +### set +The set of values in which to search. + +_**Data type:** Array of Booleans | Integers | UIntegers | Floats | Strings | Times_ + +## Examples + +###### Filter on a set of specific fields +```js +fields = ["load1", "load5", "load15"] + +from(bucket: "example-bucket") + |> range(start:start, stop: stop) + |> filter(fn: (r) => + r._measurement == "system" and + contains(value: r._field, set: fields) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/_index.md new file mode 100644 index 000000000..98b522661 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux built-in transformation functions +list_title: Built-in transformation functions +description: Flux's built-in transformation functions transform and shape your data in specific ways. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations + - /influxdb/cloud/reference/flux/functions/built-in/transformations/ +menu: + influxdb_cloud_ref: + parent: Built-in + name: Transformations + identifier: built-in-transformations +weight: 303 +influxdb/v2.0/tags: [transformations, built-in, functions] +--- + +Flux's built-in transformation functions transform or shape your data in specific ways. +There are different types of transformations categorized below: + +{{< children show="sections" >}} + +## Generic transformations + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/_index.md new file mode 100644 index 000000000..c50089103 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/_index.md @@ -0,0 +1,56 @@ +--- +title: Flux built-in aggregate transformations +list_title: Built-in aggregate transformations +description: > + Flux's aggregate transformations take values from an input table and aggregate them in some way. + Output tables contain a single row with the aggregated value. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/ +menu: + influxdb_cloud_ref: + parent: built-in-transformations + name: Aggregates + identifier: built-in-aggregates +weight: 401 +influxdb/v2.0/tags: [aggregates, built-in, functions] +related: + - /influxdb/cloud/query-data/flux/window-aggregate/ +--- + +Flux's built-in aggregate transformations take values from an input table and aggregate them in some way. +Output tables contain a single row with the aggregated value. + +Aggregate operations output a table for every input table they receive. +You must provide a column to aggregate. +Any output table will have the following properties: + +- It always contains a single record. +- It will have the same group key as the input table. +- It will contain a column for the provided aggregate column. + The column label will be the same as the input table. + The type of the column depends on the specific aggregate operation. + The value of the column will be `null` if the input table is empty or the input column has only `null` values. +- It will not have a `_time` column. + +### aggregateWindow helper function +The [`aggregateWindow()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow) +does most of the work needed when aggregating data. +It windows and aggregates the data, then combines windowed tables into a single output table. + +### Aggregate functions +The following aggregate functions are available: + +{{< children type="functions" >}} + +### Aggregate selectors +The following functions are both aggregates and selectors. +Each returns `n` values after performing an aggregate operation. +They are categorized as selector functions in this documentation: + +- [highestAverage](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestaverage) +- [highestCurrent](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestcurrent) +- [highestMax](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestmax) +- [lowestAverage](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestaverage) +- [lowestCurrent](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestcurrent) +- [lowestMin](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestmin) diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow.md new file mode 100644 index 000000000..9659192ef --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow.md @@ -0,0 +1,151 @@ +--- +title: aggregateWindow() function +description: The `aggregateWindow()` function applies an aggregate function to fixed windows of time. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/aggregatewindow + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/aggregatewindow/ +menu: + influxdb_cloud_ref: + name: aggregateWindow + parent: built-in-aggregates +weight: 501 +related: + - /influxdb/cloud/query-data/flux/window-aggregate/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#aggregations, InfluxQL – Aggregate functions + - /{{< latest "influxdb" "v1" >}}/query_language/explore-data/#the-group-by-clause, InfluxQL – GROUP BY time() +--- + +The `aggregateWindow()` function applies an aggregate or selector function +(any function with a `column` parameter) to fixed windows of time. + +_**Function type:** Aggregate_ + +```js +aggregateWindow( + every: 1m, + fn: mean, + column: "_value", + timeSrc: "_stop", + timeDst: "_time", + createEmpty: true +) +``` + +As data is windowed into separate tables and processed, the `_time` column is dropped from each group key. +This function copies the timestamp from a remaining column into the `_time` column. +View the [function definition](#function-definition). + +`aggregateWindow()` restores the original `_start` and `_stop` values of input data +and, by default, uses `_stop` to set the `_time` value for each aggregated window. +Each row in the output of `aggregateWindow` represents an aggregated window ending at `_time`. + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### every + +The duration of windows. + +{{% note %}} +#### Calendar months and years +`every` supports all [valid duration units](/influxdb/cloud/reference/flux/language/types/#duration-types), +including **calendar months (`1mo`)** and **years (`1y`)**. +{{% /note %}} + +_**Data type:** Duration_ + +### fn + +The [aggregate function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates) used in the operation. + +_**Data type:** Function_ + +{{% note %}} +Only aggregate and selector functions with a `column` parameter (singular) work with `aggregateWindow()`. +{{% /note %}} + +### column + +The column on which to operate. +Defaults to `"_value"`. + +_**Data type:** String_ + +### timeSrc + +The time column from which time is copied for the aggregate record. +Defaults to `"_stop"`. + +_**Data type:** String_ + +### timeDst + +The "time destination" column to which time is copied for the aggregate record. +Defaults to `"_time"`. + +_**Data type:** String_ + +### createEmpty + +For windows without data, this will create an empty window and fill +it with a `null` aggregate value. +Defaults to `true`. + +_**Data type:** Boolean_ + +## Examples +The examples below use a `data` variable to represent a filtered data set. + +```js +data = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent") +``` + +##### Use an aggregate function with default parameters +The following example uses the default parameters of the +[`mean()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean/) +to aggregate time-based windows: + +```js +data + |> aggregateWindow( + every: 5m, + fn: mean + ) +``` +##### Specify parameters of the aggregate function +To use functions that don't provide defaults for required parameters with `aggregateWindow()`, +define an anonymous function with `column` and `tables` parameters that pipes-forward +tables into the aggregate or selector function with all required parameters defined: + +```js +data + |> aggregateWindow( + column: "_value", + every: 5m, + fn: (column, tables=<-) => tables |> quantile(q: 0.99, column:column) + ) +``` + +##### Window and aggregate by calendar month +```js +data + |> aggregateWindow(every: 1mo, fn: mean) +``` + +## Function definition + +```js +aggregateWindow = (every, fn, column="_value", timeSrc="_stop", timeDst="_time", tables=<-) => + tables + |> window(every:every) + |> fn(column:column) + |> duplicate(column:timeSrc, as:timeDst) + |> window(every:inf, timeColumn:timeDst) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/count.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/count.md new file mode 100644 index 000000000..3b1e30e48 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/count.md @@ -0,0 +1,57 @@ +--- +title: count() function +description: The `count()` function outputs the number of non-null records in a column. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/count + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/count/ +menu: + influxdb_cloud_ref: + name: count + parent: built-in-aggregates +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#count, InfluxQL – COUNT() +--- + +The `count()` function outputs the number of records in a column. +It counts both null and non-null records. + +_**Function type:** Aggregate_ +_**Output data type:** Integer_ + +```js +count(column: "_value") +``` + +{{% note %}} +#### Empty tables +`count()` returns `0` for empty tables. +To keep empty tables in your data, set the following parameters for the following functions: + +| Function | Parameter | +|:-------- |:--------- | +| [filter()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/) | `onEmpty: "keep"` | +| [window()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window/) | `createEmpty: true` | +| [aggregateWindow()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/) | `createEmpty: true` | +{{% /note %}} + +## Parameters + +### column +The column on which to operate. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> count() +``` + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> count(column: "_value") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/histogramquantile.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/histogramquantile.md new file mode 100644 index 000000000..dd13f1a0f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/histogramquantile.md @@ -0,0 +1,94 @@ +--- +title: histogramQuantile() function +description: > + The `histogramQuantile()` function approximates a quantile given a histogram + that approximates the cumulative distribution of the dataset. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/histogramquantile + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/histogramquantile/ +menu: + influxdb_cloud_ref: + name: histogramQuantile + parent: built-in-aggregates +weight: 501 +--- + +The `histogramQuantile()` function approximates a quantile given a histogram that +approximates the cumulative distribution of the dataset. +Each input table represents a single histogram. +The histogram tables must have two columns – a count column and an upper bound column. + +The count is the number of values that are less than or equal to the upper bound value. +The table can have any number of records, each representing an entry in the histogram. +The counts must be monotonically increasing when sorted by upper bound. +If any values in the count column or upper bound column are `null`, it returns an error. + +Linear interpolation between the two closest bounds is used to compute the quantile. +If the either of the bounds used in interpolation are infinite, +then the other finite bound is used and no interpolation is performed. + +The output table has the same group key as the input table. +Columns not part of the group key are removed and a single value column of type float is added. +The count and upper bound columns must not be part of the group key. +The value column represents the value of the desired quantile from the histogram. + +_**Function type:** Aggregate_ +_**Output data type:** Float_ + +```js +histogramQuantile( + quantile: 0.5, + countColumn: "_value", + upperBoundColumn: "le", + valueColumn: "_value", + minValue: 0.0 +) +``` + +## Parameters + +### quantile +A value between 0 and 1 indicating the desired quantile to compute. + +_**Data type:** Float_ + +### countColumn +The name of the column containing the histogram counts. +The count column type must be float. +Defaults to `"_value"`. + +_**Data type:** String_ + +### upperBoundColumn +The name of the column containing the histogram upper bounds. +The upper bound column type must be float. +Defaults to `"le"`. + +_**Data type:** String_ + +### valueColumn +The name of the output column which will contain the computed quantile. +Defaults to `"_value"`. + +_**Data type:** String_ + +### minValue +The assumed minimum value of the dataset. +When the quantile falls below the lowest upper bound, interpolation is performed between `minValue` and the lowest upper bound. +When `minValue` is equal to negative infinity, the lowest upper bound is used. +Defaults to `0.0`. + +_**Data type:** Float_ + +{{% note %}} +When the quantile falls below the lowest upper bound, +interpolation is performed between `minValue` and the lowest upper bound. +When `minValue` is equal to negative infinity, the lowest upper bound is used. +{{% /note %}} + +## Examples + +##### Compute the 90th quantile +```js +histogramQuantile(quantile: 0.9) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/integral.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/integral.md new file mode 100644 index 000000000..67666fcca --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/integral.md @@ -0,0 +1,83 @@ +--- +title: integral() function +description: The `integral()` function computes the area under the curve per unit of time of subsequent non-null records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/integral + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/integral/ +menu: + influxdb_cloud_ref: + name: integral + parent: built-in-aggregates +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#integral, InfluxQL – INTEGRAL() +--- + +The `integral()` function computes the area under the curve per [`unit`](#unit) of time of subsequent non-null records. +The curve is defined using `_time` as the domain and record values as the range. + +_**Function type:** Aggregate_ +_**Output data type:** Float_ + +```js +integral( + unit: 10s, + column: "_value", + timeColumn: "_time", + interpolation: "" +) +``` + +## Parameters + +### unit +Time duration used when computing the integral. + +_**Data type:** Duration_ + +### column +Column on which to operate. +Defaults to `"_value"`. + +_**Data type:** String_ + +### timeColumn +Column that contains time values to use in the operation. +Defaults to `"_time"`. + +_**Data type:** String_ + +### interpolate +Type of interpolation to use. +Defaults to `""`. + +Use one of the following interpolation options: + +- _empty sting for no interpolation_ +- linear + +_**Data type:** String_ + +## Examples + +##### Calculate the integral +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> integral(unit:10s) +``` + +##### Calculate the integral with linear interpolation +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> integral(unit:10s, interpolate: "linear") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean.md new file mode 100644 index 000000000..6064a7c7f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean.md @@ -0,0 +1,42 @@ +--- +title: mean() function +description: The `mean()` function computes the mean or average of non-null records in the input table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/mean + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/mean/ +menu: + influxdb_cloud_ref: + name: mean + parent: built-in-aggregates +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#mean, InfluxQL – MEAN() +--- + +The `mean()` function computes the mean or average of non-null records in the input table. + +_**Function type:** Aggregate_ +_**Output data type:** Float_ + +```js +mean(column: "_value") +``` + +## Parameters + +### column +The column to use to compute the mean. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket:"example-bucket") + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent") + |> range(start:-12h) + |> window(every:10m) + |> mean() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/median.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/median.md new file mode 100644 index 000000000..87438f636 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/median.md @@ -0,0 +1,115 @@ +--- +title: median() function +description: > + The `median()` function returns the median `_value` of an input table or all non-null records + in the input table with values that fall within the `0.5` quantile or 50th percentile. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/median + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/median/ +menu: + influxdb_cloud_ref: + name: median + parent: built-in-aggregates +weight: 501 +related: + - /influxdb/cloud/query-data/flux/median/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#median, InfluxQL – MEDIAN() +--- + +The `median()` function is a special application of the [`quantile()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/quantile) +that returns the median `_value` of an input table or all non-null records in the input table +with values that fall within the `0.5` quantile (50th percentile) depending on the [method](#method) used. + +_**Function type:** Selector or Aggregate_ +_**Output data type:** Record_ + + +```js +median( + column: "_value", + method: "estimate_tdigest", + compression: 0.0 +) +``` + +When using the `estimate_tdigest` or `exact_mean` methods, it outputs non-null +records with values that fall within the `0.5` quantile. + +When using the `exact_selector` method, it outputs the non-null record with the +value that represents the `0.5` quantile. + +{{% note %}} +The `median()` function can only be used with float value types. +It is a special application of the [`quantile()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/quantile) +which uses an approximation implementation that requires floats. +You can convert your value column to a float column using the [`toFloat()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tofloat). +{{% /note %}} + +## Parameters + +### column +The column to use to compute the median. +Defaults to `"_value"`. + +_**Data type:** String_ + +### method +Defines the method of computation. +Defaults to `"estimate_tdigest"`. + +_**Data type:** String_ + +The available options are: + +##### estimate_tdigest +An aggregate method that uses a [t-digest data structure](https://github.com/tdunning/t-digest) +to compute an accurate quantile estimate on large data sources. + +##### exact_mean +An aggregate method that takes the average of the two points closest to the quantile value. + +##### exact_selector +A selector method that returns the data point for which at least `q` points are less than. + +### compression +Indicates how many centroids to use when compressing the dataset. +A larger number produces a more accurate result at the cost of increased memory requirements. +Defaults to `1000.0`. + +_**Data type:** Float_ + +## Examples + +###### Median as an aggregate +```js +from(bucket: "example-bucket") + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> range(start:-12h) + |> window(every:10m) + |> median() +``` + +###### Median as a selector +```js +from(bucket: "example-bucket") + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> range(start:-12h) + |> window(every:10m) + |> median(method: "exact_selector") +``` + +## Function definition +```js +median = (method="estimate_tdigest", compression=0.0, tables=<-) => + quantile( + q:0.5, + method:method, + compression:compression + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mode.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mode.md new file mode 100644 index 000000000..9c492074c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mode.md @@ -0,0 +1,64 @@ +--- +title: mode() function +description: > + The `mode()` function computes the mode or value that occurs most often in a + specified column in the input table. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/mode/ +menu: + influxdb_cloud_ref: + name: mode + parent: built-in-aggregates +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#mode, InfluxQL – MODE() +--- + +The `mode()` function computes the mode or value that occurs most often in a +specified column in the input table. + +_**Function type:** Aggregate_ + +```js +mode(column: "_value") +``` + +If there are multiple modes, it returns all of them in a sorted table. +Mode only considers non-null values. +If there is no mode, `mode()` returns `null`. + +{{% warn %}} +#### Empty tables +`mode()` drops empty tables. +{{% /warn %}} + +##### Supported data types + +- String +- Float +- Integer +- UInteger +- Boolean +- Time + +## Parameters + +### column +The column to use to compute the mode. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples + +###### Return the mode of windowed data +```js +from(bucket: "example-bucket") + |> filter(fn: (r) => + r._measurement == "errors" and + r._field == "count_per_minute" + ) + |> range(start:-12h) + |> window(every:10m) + |> mode() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/quantile.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/quantile.md new file mode 100644 index 000000000..afc1f026c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/quantile.md @@ -0,0 +1,105 @@ +--- +title: quantile() function +description: The `quantile()` function outputs non-null records with values that fall within the specified quantile or the non-null record with the value that represents the specified quantile. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/percentile + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/percentile + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/quantile/ +menu: + influxdb_cloud_ref: + name: quantile + parent: built-in-aggregates +weight: 501 +related: + - /influxdb/cloud/query-data/flux/percentile-quantile/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#percentile, InfluxQL – PERCENTILE() +--- + +The `quantile()` function returns records from an input table with `_value`s that fall within +a specified quantile or it returns the record with the `_value` that represents the specified quantile. +Which it returns depends on the [method](#method) used. +`quantile()` supports columns with float values. + +_**Function type:** Aggregate or Selector_ +_**Output data type:** Float | Record_ + +```js +quantile( + column: "_value", + q: 0.99, + method: "estimate_tdigest", + compression: 1000.0 +) +``` + +When using the `estimate_tdigest` or `exact_mean` methods, it outputs non-null +records with values that fall within the specified quantile. + +When using the `exact_selector` method, it outputs the non-null record with the +value that represents the specified quantile. + +## Parameters + +### column +The column to use to compute the quantile. +Defaults to `"_value"`. + +_**Data type:** String_ + +### q +A value between 0 and 1 indicating the desired quantile. + +_**Data type:** Float_ + +### method +Defines the method of computation. + +_**Data type:** String_ + +The available options are: + +##### estimate_tdigest +An aggregate method that uses a [t-digest data structure](https://github.com/tdunning/t-digest) +to compute an accurate quantile estimate on large data sources. + +##### exact_mean +An aggregate method that takes the average of the two points closest to the quantile value. + +##### exact_selector +A selector method that returns the data point for which at least `q` points are less than. + +### compression +Indicates how many centroids to use when compressing the dataset. +A larger number produces a more accurate result at the cost of increased memory requirements. +Defaults to `1000.0`. + +_**Data type:** Float_ + +## Examples + +###### Quantile as an aggregate +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system") + |> quantile( + q: 0.99, + method: "estimate_tdigest", + compression: 1000.0 + ) +``` + +###### Quantile as a selector +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system") + |> quantile( + q: 0.99, + method: "exact_selector" + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/reduce.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/reduce.md new file mode 100644 index 000000000..cf440d33a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/reduce.md @@ -0,0 +1,161 @@ +--- +title: reduce() function +description: > + The `reduce()` function aggregates records in each table according to the reducer, + `fn`, providing a way to create custom table aggregations. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/reduce/ +menu: + influxdb_cloud_ref: + name: reduce + parent: built-in-aggregates +weight: 501 +influxdb/v2.0/tags: [exists] +related: + - /influxdb/cloud/query-data/flux/custom-functions/custom-aggregate/ + - /influxdb/cloud/query-data/flux/conditional-logic/ +--- + +The `reduce()` function aggregates records in each table according to the reducer, +`fn`, providing a way to create custom aggregations. +The output for each table is the group key of the table with columns corresponding +to each field in the reducer record. + +_**Function type:** Transformation_ + +```js +reduce( + fn: (r, accumulator) => ({ sum: r._value + accumulator.sum }), + identity: {sum: 0.0} +) +``` + +If the reducer record contains a column with the same name as a group key column, +the group key column's value is overwritten, and the outgoing group key is changed. +However, if two reduced tables write to the same destination group key, the function will error. + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### fn +Function to apply to each record with a reducer record ([`identity`](#identity)). + +_**Data type:** Function_ + +###### fn syntax +```js +// Pattern +fn: (r, accumulator) => ({ identityKey: r.column + accumulator.identityKey }) + +// Example +fn: (r, accumulator) => ({ sum: r._value + accumulator.sum }) +``` + +{{% note %}} +#### Matching output record keys and types +The output record from `fn` must have the same key names and value types as the [`identity`](#identity). +After operating on a record, the output record is given back to `fn` as the input accumulator. +If the output record keys and value types do not match the `identity` keys and value types, +it will return a type error. +{{% /note %}} + +#### r +Record representing each row or record. + +#### accumulator +Reducer record defined by [`identity`](#identity). + +### identity +Defines the reducer record and provides initial values to use when creating a reducer. +May be used more than once in asynchronous processing use cases. +_The data type of values in the `identity` record determine the data type of output values._ + +_**Data type:** Record_ + +###### identity record syntax +```js +// Pattern +identity: {identityKey1: value1, identityKey2: value2} + +// Example +identity: {sum: 0.0, count: 0.0} +``` + +## Important notes + +#### Dropped columns +By default, `reduce()` drops any columns that: + +1. Are not part of the input table's [group key](/influxdb/cloud/reference/glossary/#group-key). +2. Are not explicitly mapped in the `reduce()` function. + +## Examples + +##### Compute the sum of the value column +```js +from(bucket:"example-bucket") + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.service == "app-server" + ) + |> range(start:-12h) + |> reduce( + fn: (r, accumulator) => ({ + sum: r._value + accumulator.sum + }), + identity: {sum: 0.0} + ) +``` + +##### Compute the sum and count in a single reducer +```js +from(bucket:"example-bucket") + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.service == "app-server" + ) + |> range(start:-12h) + |> reduce( + fn: (r, accumulator) => ({ + sum: r._value + accumulator.sum, + count: accumulator.count + 1.0 + }), + identity: {sum: 0.0, count: 0.0} + ) +``` + +##### Compute the product of all values +```js +from(bucket:"example-bucket") + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.service == "app-server") + |> range(start:-12h) + |> reduce( + fn: (r, accumulator) => ({ + prod: r._value * accumulator.prod + }), + identity: {prod: 1.0} + ) +``` + +##### Calculate the average +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") + |> window(every: 5m) + |> reduce(fn: (r, accumulator) => ({ + count: accumulator.count + 1, + total: accumulator.total + r._value, + avg: (accumulator.total + r._value) / float(v: accumulator.count) + }), + identity: {count: 1, total: 0.0, avg: 0.0} + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/skew.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/skew.md new file mode 100644 index 000000000..7d890c838 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/skew.md @@ -0,0 +1,40 @@ +--- +title: skew() function +description: The `skew()` function outputs the skew of non-null records as a float. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/skew + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/skew/ +menu: + influxdb_cloud_ref: + name: skew + parent: built-in-aggregates +weight: 501 +--- + +The `skew()` function outputs the skew of non-null records as a float. + +_**Function type:** Aggregate_ +_**Output data type:** Float_ + +```js +skew(column: "_value") +``` + +## Parameters + +### column +The column on which to operate. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> skew() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/spread.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/spread.md new file mode 100644 index 000000000..e0b00b371 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/spread.md @@ -0,0 +1,46 @@ +--- +title: spread() function +description: The `spread()` function outputs the difference between the minimum and maximum values in a specified column. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/spread + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/spread/ +menu: + influxdb_cloud_ref: + name: spread + parent: built-in-aggregates +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#spread, InfluxQL – SPREAD() +--- + +The `spread()` function outputs the difference between the minimum and maximum values in a specified column. +Only `uint`, `int`, and `float` column types can be used. +The type of the output column depends on the type of input column: + +- For columns with type `uint` or `int`, the output is an `int` +- For columns with type `float`, the output is a float. + +_**Function type:** Aggregate_ +_**Output data type:** Integer or Float (inherited from input column type)_ + +```js +spread(column: "_value") +``` + +## Parameters + +### column +The column on which to operate. Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> spread() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/stddev.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/stddev.md new file mode 100644 index 000000000..9d6ec1ae2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/stddev.md @@ -0,0 +1,59 @@ +--- +title: stddev() function +description: The `stddev()` function computes the standard deviation of non-null records in a specified column. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/stddev + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/stddev/ +menu: + influxdb_cloud_ref: + name: stddev + parent: built-in-aggregates +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#stddev, InfluxQL – STDDEV() +--- + +The `stddev()` function computes the standard deviation of non-null records in a specified column. + +_**Function type:** Aggregate_ +_**Output data type:** Float_ + +```js +stddev( + column: "_value", + mode: "sample" +) +``` + +## Parameters + +### column +The column on which to operate. +Defaults to `"_value"`. + +_**Data type:** String_ + +### mode +The standard deviation mode or type of standard deviation to calculate. +Defaults to `"sample"`. + +_**Data type:** String_ + +The available options are: + +##### sample +Calculates the sample standard deviation where the data is considered to be part of a larger population. + +##### population +Calculates the population standard deviation where the data is considered a population of its own. + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> stddev() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/sum.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/sum.md new file mode 100644 index 000000000..62fdb6be5 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/sum.md @@ -0,0 +1,42 @@ +--- +title: sum() function +description: The `sum()` function computes the sum of non-null records in a specified column. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/sum + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/sum/ +menu: + influxdb_cloud_ref: + name: sum + parent: built-in-aggregates +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#sum, InfluxQL – SUM() +--- + +The `sum()` function computes the sum of non-null records in a specified column. + +_**Function type:** Aggregate_ +_**Output data type:** Integer, UInteger, or Float (inherited from column type)_ + +```js +sum(column: "_value") +``` + +## Parameters + +### column +The column on which to operate. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> sum() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/timeweightedavg.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/timeweightedavg.md new file mode 100644 index 000000000..a588cd97b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/timeweightedavg.md @@ -0,0 +1,53 @@ +--- +title: timeWeightedAvg() function +description: The `timeWeightedAvg()` function outputs the timeWeightedAvg of non-null records as a float. +menu: + influxdb_cloud_ref: + name: timeWeightedAvg + parent: built-in-aggregates +weight: 501 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/integral/ +--- + +The `timeWeightedAvg()` function outputs the time-weighted average of non-null records +in a table as a float. +Time is weighted using the linearly interpolated integral of values in the table. + +_**Function type:** Aggregate_ +_**Output data type:** Float_ + +```js +timeWeightedAvg(unit: "_value") +``` + +## Parameters + +### unit +Time duration used when computing the time-weighted average. + +_**Data type:** Duration_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> timeWeightedAvg(unit: 1m) +``` + +## Function definition +```js +timeWeightedAvg = (tables=<-, unit) => tables + |> integral( + unit: unit, + interpolate: "linear" + ) + |> map(fn: (r) => ({ + r with + _value: (r._value * float(v: uint(v: unit))) / float(v: int(v: r._stop) - int(v: r._start)) + })) +``` \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/chandemomentumoscillator.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/chandemomentumoscillator.md new file mode 100644 index 000000000..6d0aa5ef6 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/chandemomentumoscillator.md @@ -0,0 +1,123 @@ +--- +title: chandeMomentumOscillator() function +description: > + The `chandeMomentumOscillator()` function applies the technical momentum indicator + developed by Tushar Chande. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/chandemomentumoscillator/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/chandemomentumoscillator/ +menu: + influxdb_cloud_ref: + name: chandeMomentumOscillator + parent: built-in-transformations +weight: 402 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#triple-exponential-moving-average, InfluxQL CHANDE_MOMENTUM_OSCILLATOR() +--- + +The `chandeMomentumOscillator()` function applies the technical momentum indicator +developed by Tushar Chande. + +_**Function type:** Transformation_ + +```js +chandeMomentumOscillator( + n: 10, + columns: ["_value"] +) +``` + +The Chande Momentum Oscillator (CMO) indicator calculates the difference between +the sum of all recent data points with values greater than the median value of the data set +and the sum of all recent data points with values lower than the median value of the data set, +then divides the result by the sum of all data movement over a given time period. +It then multiplies the result by 100 and returns a value between -100 and +100. + +## Parameters + +### n +The period or number of points to use in the calculation. + +_**Data type:** Integer_ + +### columns +The columns to operate on. +Defaults to `["_value"]`. + +_**Data type: Array of Strings**_ + +## Output tables +For each input table with `x` rows, `chandeMomentumOscillator()` outputs a table +with `x - n` rows. + +## Examples + +#### Table transformation with a ten point Chande Momentum Oscillator + +{{< flex >}} +{{% flex-content %}} +###### Input table +| _time | _value | +|:-----:|:------:| +| 0001 | 1 | +| 0002 | 2 | +| 0003 | 3 | +| 0004 | 4 | +| 0005 | 5 | +| 0006 | 6 | +| 0007 | 7 | +| 0008 | 8 | +| 0009 | 9 | +| 0010 | 10 | +| 0011 | 11 | +| 0012 | 12 | +| 0013 | 13 | +| 0014 | 14 | +| 0015 | 15 | +| 0016 | 14 | +| 0017 | 13 | +| 0018 | 12 | +| 0019 | 11 | +| 0020 | 10 | +| 0021 | 9 | +| 0022 | 8 | +| 0023 | 7 | +| 0024 | 6 | +| 0025 | 5 | +| 0026 | 4 | +| 0027 | 3 | +| 0028 | 2 | +| 0029 | 1 | +{{% /flex-content %}} + +{{% flex-content %}} +###### Query +```js +// ... + |> chandeMomentumOscillator(n: 10) +``` + +###### Output table +| _time | _value | +|:-----:|:------:| +| 0011 | 100 | +| 0012 | 100 | +| 0013 | 100 | +| 0014 | 100 | +| 0015 | 100 | +| 0016 | 80 | +| 0017 | 60 | +| 0018 | 40 | +| 0019 | 20 | +| 0020 | 0 | +| 0021 | -20 | +| 0022 | -40 | +| 0023 | -60 | +| 0024 | -80 | +| 0025 | -100 | +| 0026 | -100 | +| 0027 | -100 | +| 0028 | -100 | +| 0029 | -100 | +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/columns.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/columns.md new file mode 100644 index 000000000..cc92b74f2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/columns.md @@ -0,0 +1,57 @@ +--- +title: columns() function +description: > + The `columns()` function lists the column labels of input tables. + For each input table, it outputs a table with the same group key columns, + plus a new column containing the labels of the input table's columns. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/columns + - /influxdb/cloud/reference/flux/functions/built-in/transformations/columns/ +menu: + influxdb_cloud_ref: + name: columns + parent: built-in-transformations +weight: 402 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-measurements, InfluxQL – SHOW MEASUREMENTS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-field-keys, InfluxQL – SHOW FIELD KEYS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-tag-keys, InfluxQL – SHOW TAG KEYS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-tag-keys, InfluxQL – SHOW SERIES +--- + +The `columns()` function lists the column labels of input tables. +For each input table, it outputs a table with the same group key columns, +plus a new column containing the labels of the input table's columns. +Each row in an output table contains the group key value and the label of one column of the input table. +Each output table has the same number of rows as the number of columns of the input table. + +_**Function type:** Transformation_ + +```js +columns(column: "_value") +``` + +## Parameters + +### column +The name of the output column in which to store the column labels. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -30m) + |> columns(column: "labels") +``` + +##### Get every possible column label in a single table +```js +from(bucket: "example-bucket") + |> range(start: -30m) + |> columns() + |> keep(columns: ["_value"]) + |> group() + |> distinct() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/cov.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/cov.md new file mode 100644 index 000000000..1f3edf9bf --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/cov.md @@ -0,0 +1,71 @@ +--- +title: cov() function +description: The `cov()` function computes the covariance between two streams by first joining the streams, then performing the covariance operation. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/cov + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/cov/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/cov/ +menu: + influxdb_cloud_ref: + name: cov + parent: built-in-transformations +weight: 402 +--- + +The `cov()` function computes the covariance between two streams by first joining the streams, +then performing the covariance operation. + +_**Function type:** Transformation_ +_**Output data type:** Float_ + +```js +cov(x: table1, y: table2, on: ["_time", "_field"], pearsonr: false) +``` + +## Parameters + +### x +One input stream used to calculate the covariance. + +_**Data type:** Record_ + +### y +The other input table used to calculate the covariance. + +_**Data type:** Record_ + +### on +The list of columns on which to join. + +_**Data type:** Array of strings_ + +### pearsonr +Indicates whether the result should be normalized to be the Pearson R coefficient. + +_**Data type:** Boolean_ + + +## Examples + +```js +table1 = from(bucket: "example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "measurement_1" + ) + +table2 = from(bucket: "example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => + r._measurement == "measurement_2" + ) + +cov(x: table1, y: table2, on: ["_time", "_field"]) +``` + +## Function definition +```js +cov = (x,y,on,pearsonr=false) => + join( tables:{x:x, y:y}, on:on ) + |> covariance(pearsonr:pearsonr, columns:["_value_x","_value_y"]) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/covariance.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/covariance.md new file mode 100644 index 000000000..582aa5008 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/covariance.md @@ -0,0 +1,47 @@ +--- +title: covariance() function +description: The `covariance()` function computes the covariance between two columns. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/covariance + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/covariance/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/covariance/ +menu: + influxdb_cloud_ref: + name: covariance + parent: built-in-transformations +weight: 402 +--- + +The `covariance()` function computes the covariance between two columns. + +_**Function type:** Transformation_ +_**Output data type:** Float_ + +```js +covariance(columns: ["column_x", "column_y"], pearsonr: false, valueDst: "_value") +``` + +## Parameters + +### columns +A list of **two columns** on which to operate. Required + +_**Data type:** Array of strings_ + +### pearsonr +Indicates whether the result should be normalized to be the Pearson R coefficient. + +_**Data type:** Boolean_ + +### valueDst +The column into which the result will be placed. Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start:-5m) + |> map(fn: (r) => ({r with x: r._value, y: r._value * r._value / 2})) + |> covariance(columns: ["x", "y"]) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/cumulativesum.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/cumulativesum.md new file mode 100644 index 000000000..e9e464ff8 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/cumulativesum.md @@ -0,0 +1,44 @@ +--- +title: cumulativeSum() function +description: The `cumulativeSum()` function computes a running sum for non-null records in the table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/cumulativesum + - /influxdb/cloud/reference/flux/functions/built-in/transformations/cumulativesum/ +menu: + influxdb_cloud_ref: + name: cumulativeSum + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/cumulativesum/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#cumulative-sum, InfluxQL – CUMULATIVE_SUM() +--- + +The `cumulativeSum()` function computes a running sum for non-null records in the table. +The output table schema will be the same as the input table. + +_**Function type:** Transformation +_**Output data type:** Float_ + +```js +cumulativeSum(columns: ["_value"]) +``` + +## Parameters + +### columns +A list of columns on which to operate. +Defaults to `["_value"]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => + r._measurement == "disk" and + r._field == "used_percent" + ) + |> cumulativeSum(columns: ["_value"]) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/derivative.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/derivative.md new file mode 100644 index 000000000..98c7e5382 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/derivative.md @@ -0,0 +1,68 @@ +--- +title: derivative() function +description: The `derivative()` function computes the rate of change per unit of time between subsequent non-null records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/derivative + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/derivative/ +menu: + influxdb_cloud_ref: + name: derivative + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/rate/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#derivative, InfluxQL – DERIVATIVE() +--- + +The `derivative()` function computes the rate of change per [`unit`](#unit) of time between subsequent non-null records. +It assumes rows are ordered by the `_time` column. +The output table schema is the same as the input table. + +_**Function type:** Transformation_ +_**Output data type:** Float_ + +```js +derivative( + unit: 1s, + nonNegative: true, + columns: ["_value"], + timeSrc: "_time" +) +``` + +## Parameters + +### unit +The time duration used when creating the derivative. +Defaults to `1s`. + +_**Data type:** Duration_ + +### nonNegative +Indicates if the derivative is allowed to be negative. Default is `true`. +When `true`, if a value is less than the previous value, it is assumed the +previous value should have been a zero. + +_**Data type:** Boolean_ + +### columns +The columns to use to compute the derivative. +Defaults to `["_value"]`. + +_**Data type:** String_ + +### timeSrc +The column containing time values. +Defaults to `"_time"`. + +_**Data type:** String_ + +## Output tables +For each input table with `n` rows, `derivative()` outputs a table with `n - 1` rows. + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> derivative(unit: 1s, nonNegative: true) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/difference.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/difference.md new file mode 100644 index 000000000..0db49558a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/difference.md @@ -0,0 +1,121 @@ +--- +title: difference() function +description: The `difference()` function computes the difference between subsequent non-null records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/difference + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/difference/ +menu: + influxdb_cloud_ref: + name: difference + parent: built-in-transformations +weight: 402 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#difference, InfluxQL – DIFFERENCE() +--- + +The `difference()` function computes the difference between subsequent records. +The user-specified columns of numeric type are subtracted while others are kept intact. + +_**Function type:** Transformation_ +_**Output data type:** Float_ + +```js +difference( + nonNegative: false, + columns: ["_value"], + keepFirst: false +) +``` + +## Parameters + +### nonNegative +Indicates if the difference is allowed to be negative. +When set to `true`, if a value is less than the previous value, it is assumed the previous value should have been a zero. + +_**Data type:** Boolean_ + +### columns +The columns to use to compute the difference. +Defaults to `["_value"]`. + +_**Data type:** Array of Strings_ + +### keepFirst +Indicates the first row should be kept. +If `true`, the difference will be `null`. +Defaults to `false`. + +_**Data type:** Boolean_ + +## Subtraction rules for numeric types +- The difference between two non-null values is their algebraic difference; + or `null`, if the result is negative and `nonNegative: true`; +- `null` minus some value is always `null`; +- Some value `v` minus `null` is `v` minus the last non-null value seen before `v`; + or `null` if `v` is the first non-null value seen. + +## Output tables +For each input table with `n` rows, `difference()` outputs a table with `n - 1` rows. + +## Examples + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> difference() +``` +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> difference(nonNegative: true) +``` + +### Example data transformation + +###### Input table +| _time | _value | tag | +|:-----:|:------:|:---:| +| 0001 | null | tv | +| 0002 | 6 | tv | +| 0003 | 4 | tv | +| 0004 | 10 | tv | +| 0005 | null | tv | + +#### With nonNegative set to false +```js +|> difference(nonNegative: false) +``` +###### Output table +| _time | _value | tag | +|:-----:|:------:|:---:| +| 0002 | null | tv | +| 0003 | -2 | tv | +| 0004 | 6 | tv | +| 0005 | null | tv | + +#### With nonNegative set to true +```js +|> difference(nonNegative: true): +``` +###### Output table +| _time | _value | tag | +|:-----:|:------:|:---:| +| 0002 | null | tv | +| 0003 | null | tv | +| 0004 | 6 | tv | +| 0005 | null | tv | + + +#### With keepFirst set to true +```js +|> difference(nonNegative: false, keepFirst: true): +``` +###### Output table +| _time | _value | tag | +|:-----:|:------:|:---:| +| 0001 | null | tv | +| 0002 | null | tv | +| 0003 | -2 | tv | +| 0004 | 6 | tv | +| 0005 | null | tv | diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema.md new file mode 100644 index 000000000..e60169d76 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema.md @@ -0,0 +1,66 @@ +--- +title: doubleEMA() function +description: > + The `doubleEMA()` function calculates the exponential moving average of values + grouped into `n` number of points, giving more weight to recent data at double + the rate of `exponentialMovingAverage()`. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/doubleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/doubleema/ +menu: + influxdb_cloud_ref: + name: doubleEMA + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#double-exponential-moving-average, InfluxQL DOUBLE_EXPONENTIAL_MOVING_AVERAGE() +--- + +The `doubleEMA()` function calculates the exponential moving average of values in +the `_value` column grouped into `n` number of points, giving more weight to recent +data at double the rate of [`exponentialMovingAverage()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/). + +_**Function type:** Transformation_ + +```js +doubleEMA(n: 5) +``` + +##### Double exponential moving average rules +- A double exponential moving average is defined as `doubleEMA = 2 * EMA_N - EMA of EMA_N`. + - `EMA` is an exponential moving average. + - `N = n` is the period used to calculate the EMA. +- A true double exponential moving average requires at least `2 * n - 1` values. + If not enough values exist to calculate the double EMA, it returns a `NaN` value. +- `doubleEMA()` inherits all [exponential moving average rules](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/#exponential-moving-average-rules). + +## Parameters + +### n +The number of points to average. + +_**Data type:** Integer_ + +## Examples + +#### Calculate a five point double exponential moving average +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> doubleEMA(n: 5) +``` + +## Function definition +```js +doubleEMA = (n, tables=<-) => + tables + |> exponentialMovingAverage(n:n) + |> duplicate(column:"_value", as:"ema") + |> exponentialMovingAverage(n:n) + |> map(fn: (r) => ({r with _value: 2.0 * r.ema - r._value})) + |> drop(columns: ["ema"]) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/drop.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/drop.md new file mode 100644 index 000000000..ee9e165cb --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/drop.md @@ -0,0 +1,67 @@ +--- +title: drop() function +description: The `drop()` function removes specified columns from a table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/drop + - /influxdb/cloud/reference/flux/functions/built-in/transformations/drop/ +menu: + influxdb_cloud_ref: + name: drop + parent: built-in-transformations +weight: 402 +--- + +The `drop()` function removes specified columns from a table. +Columns are specified either through a list or a predicate function. +When a dropped column is part of the group key, it will be removed from the key. +If a specified column is not present in a table, it will return an error. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +drop(columns: ["col1", "col2"]) + +// OR + +drop(fn: (column) => column =~ /usage*/) +``` + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### columns + +Columns to be removed from the table. +Cannot be used with `fn`. + +_**Data type:** Array of strings_ + +### fn + +A predicate function which takes a column name as a parameter (`column`) and returns +a boolean indicating whether or not the column should be removed from the table. +Cannot be used with `columns`. + +_**Data type:** Function_ + +## Examples + +##### Drop a list of columns + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> drop(columns: ["host", "_measurement"]) +``` + +##### Drop columns matching a predicate + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> drop(fn: (column) => column =~ /usage*/) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/duplicate.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/duplicate.md new file mode 100644 index 000000000..90d1b583b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/duplicate.md @@ -0,0 +1,47 @@ +--- +title: duplicate() function +description: The `duplicate()` function duplicates a specified column in a table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/duplicate + - /influxdb/cloud/reference/flux/functions/built-in/transformations/duplicate/ +menu: + influxdb_cloud_ref: + name: duplicate + parent: built-in-transformations +weight: 402 +--- + +The `duplicate()` function duplicates a specified column in a table. +If the specified column is part of the group key, it will be duplicated, but will +not be part of the output table's group key. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +duplicate(column: "column-name", as: "duplicate-name") +``` + +## Parameters + +### column +The column to duplicate. + +_**Data type:** String_ + +### as +The name assigned to the duplicate column. + +_**Data type:** String_ + +{{% note %}} +If the `as` column already exists, this function will overwrite the existing values. +{{% /note %}} + +## Examples +```js +from(bucket: "example-bucket") + |> range(start:-5m) + |> filter(fn: (r) => r._measurement == "cpu") + |> duplicate(column: "host", as: "server") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/elapsed.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/elapsed.md new file mode 100644 index 000000000..79b9b5f54 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/elapsed.md @@ -0,0 +1,58 @@ +--- +title: elapsed() function +description: The `elapsed()` function returns the time between subsequent records. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/elapsed/ +menu: + influxdb_cloud_ref: + name: elapsed + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/contrib/events/duration/ +--- + +The `elapsed()` function returns the time between subsequent records. +Given an input table, `elapsed()` returns the same table without the first record +(as elapsed time is not defined) and an additional column containing the elapsed time. + +_**Function type:** Transformation_ + +```js +elapsed( + unit: 1s, + timeColumn: "_time", + columnName: "elapsed" +) +``` + +_`elapsed()` returns an errors if the `timeColumn` is not present in the input table._ + +## Parameters + +### unit +The unit time to returned. +_Defaults to `1s`._ + +_**Data type:** Duration_ + +### timeColumn +The column to use to compute the elapsed time. +_Defaults to `"_time"`._ + +_**Data type:** String_ + +### columnName +The column to store elapsed times. +_Defaults to `"elapsed"`._ + +_**Data type:** String_ + +## Examples + +##### Calculate the time between points in seconds +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> elapsed(unit: 1s) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage.md new file mode 100644 index 000000000..d2a3d0019 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage.md @@ -0,0 +1,76 @@ +--- +title: exponentialMovingAverage() function +description: > + The `exponentialMovingAverage()` function calculates the exponential moving average of values + in the `_value` column grouped into `n` number of points, giving more weight to recent data. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/exponentialmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/exponentialmovingaverage/ +menu: + influxdb_cloud_ref: + name: exponentialMovingAverage + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleema/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#exponential-moving-average, InfluxQL EXPONENTIAL_MOVING_AVERAGE() +--- + +The `exponentialMovingAverage()` function calculates the exponential moving average of values +in the `_value` column grouped into `n` number of points, giving more weight to recent data. + +_**Function type:** Aggregate_ + +```js +exponentialMovingAverage(n: 5) +``` + +##### Exponential moving average rules +- The first value of an exponential moving average over `n` values is the + algebraic mean of `n` values. +- Subsequent values are calculated as `y(t) = x(t) * k + y(t-1) * (1 - k)`, where: + - `y(t)` is the exponential moving average at time `t`. + - `x(t)` is the value at time `t`. + - `k = 2 / (1 + n)`. +- The average over a period populated by only `null` values is `null`. +- Exponential moving averages skip `null` values. + +## Parameters + +### n +The number of points to average. + +_**Data type:** Integer_ + +## Examples + +#### Calculate a five point exponential moving average +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> exponentialMovingAverage(n: 5) +``` + +#### Table transformation with a two point exponential moving average + +###### Input table: +| _time | tag | _value | +|:-----:|:---:|:------:| +| 0001 | tv | null | +| 0002 | tv | 10 | +| 0003 | tv | 20 | + +###### Query: +```js +// ... + |> exponentialMovingAverage(n: 2) +``` + +###### Output table: +| _time | tag | _value | +|:-----:|:---:|:------:| +| 0002 | tv | 10 | +| 0003 | tv | 16.67 | diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/fill.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/fill.md new file mode 100644 index 000000000..4537185e3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/fill.md @@ -0,0 +1,75 @@ +--- +title: fill() function +description: The `fill()` function replaces all null values in an input stream and replace them with a non-null value. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/fill + - /influxdb/cloud/reference/flux/functions/built-in/transformations/fill/ +menu: + influxdb_cloud_ref: + name: fill + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/fill/ + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#group-by-time-intervals-and-fill, InfluxQL – FILL +--- + +The `fill()` function replaces all null values in an input stream with a non-null value. +The output stream is the same as the input stream with all null values replaced in the specified column. + +_**Function type:** Transformation_ + +```js +fill(column: "_value", value: 0.0) + +// OR + +fill(column: "_value", usePrevious: true) +``` + +## Parameters + +### column +The column in which to replace null values. Defaults to `"_value"`. + +_**Data type:** String_ + +### value +The constant value to use in place of nulls. +The value type must match the value type of the `column`. + +_**Data type:** Boolean | Integer | UInteger | Float | String | Time | Duration_ + +### usePrevious +When `true`, assigns the value set in the previous non-null row. + +{{% note %}} +Cannot be used with `value`. +{{% /note %}} + +_**Data type:** Boolean_ + + +## Examples + +##### Fill null values with a specified non-null value +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r.cpu == "cpu-total" + ) + |> fill(value: 0.0) +``` + +##### Fill null values with the previous non-null value +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r.cpu == "cpu-total" + ) + |> fill(usePrevious: true) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter.md new file mode 100644 index 000000000..4bd911414 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter.md @@ -0,0 +1,106 @@ +--- +title: filter() function +description: The `filter()` function filters data based on conditions defined in a predicate function (fn). +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/filter + - /influxdb/cloud/reference/flux/functions/built-in/transformations/filter/ +menu: + influxdb_cloud_ref: + name: filter + parent: built-in-transformations +weight: 402 +influxdb/v2.0/tags: [exists] +related: + - /influxdb/cloud/query-data/flux/query-fields/ + - /influxdb/cloud/query-data/flux/conditional-logic/ + - /influxdb/cloud/query-data/flux/exists/ + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#the-basic-select-statement, InfluxQL – SELECT +--- + +The `filter()` function filters data based on conditions defined in a predicate function ([`fn`](#fn)). +The output tables have the same schema as the corresponding input tables. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +filter( + fn: (r) => r._measurement == "cpu", + onEmpty: "drop" +) +``` + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### fn + +A single argument predicate function that evaluates true or false. +Records are passed to the function. +Those that evaluate to true are included in the output tables. +Records that evaluate to _null_ or false are not included in the output tables. + +_**Data type:** Function_ + +{{% note %}} +Records evaluated in `fn` functions are represented by `r`, short for "record" or "row". +{{% /note %}} + +### onEmpty +Defines the behavior for empty tables. +Potential values are `keep` and `drop`. +Defaults to `drop`. + +_**Data type:** String_ + +##### drop +Tables without rows are dropped. + +##### keep +Tables without rows are output to the next transformation. + +{{% warn %}} +Keeping empty tables with your first `filter()` function can have severe performance +costs since it retains empty tables from your entire data set. +For higher performance, use your first `filter()` function to do basic filtering, +then keep empty tables on subsequent `filter()` calls with smaller data sets. +_[See the example below](#keep-empty-tables-when-filtering)._ +{{% /warn %}} + +## Examples + +##### Filter based on measurement, field, and tag +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) +``` + +##### Filter out null values +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => exists r._value ) +``` + +##### Filter values based on thresholds +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => r._value > 50.0 and r._value < 65.0 ) +``` + +##### Keep empty tables when filtering +```js +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "events" and r._field == "open") + |> filter(fn: (r) => r.doorId =~ /^2.*/, onEmpty: "keep") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group.md new file mode 100644 index 000000000..0422bed58 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group.md @@ -0,0 +1,96 @@ +--- +title: group() function +description: The `group()` function groups records based on their values for specific columns. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/group + - /influxdb/cloud/reference/flux/functions/built-in/transformations/group/ +menu: + influxdb_cloud_ref: + name: group + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/group-data/ + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#the-group-by-clause, InfluxQL – GROUP BY +--- + +The `group()` function groups records based on their values for specific columns. +It produces tables with new group keys based on provided properties. +Specify an empty array of columns to ungroup data or merge all input tables into a single output table. + +_**Function type:** Transformation_ + +```js +group(columns: ["host", "_measurement"], mode:"by") + +// OR + +group(columns: ["_time"], mode:"except") + +// OR + +group() +``` + +{{% warn %}} +#### Group does not guarantee sort order +`group()` does not guarantee the sort order of output records. +To ensure data is sorted correctly, use [`sort()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/sort/) +after `group()`. + +```js +data + |> group() + |> sort(columns: ["_time"]) +``` +{{% /warn %}} + +## Parameters + +### columns +List of columns to use in the grouping operation. +Defaults to `[]`. + +_**Data type:** Array of strings_ + +### mode +The mode used to group columns. + +_**Data type:** String_ + +The following options are available: + +- by +- except + +Defaults to `"by"`. + +#### by +Groups records by columns defined in the [`columns`](#columns) parameter. + +#### except +Groups records by all columns **except** those defined in the [`columns`](#columns) parameter. + +## Examples + +###### Group by host and measurement +```js +from(bucket: "example-bucket") + |> range(start: -30m) + |> group(columns: ["host", "_measurement"]) +``` + +###### Group by everything except time +```js +from(bucket: "example-bucket") + |> range(start: -30m) + |> group(columns: ["_time"], mode: "except") +``` + +###### Ungroup data +```js +// Merge all tables into a single table +from(bucket: "example-bucket") + |> range(start: -30m) + |> group() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/histogram.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/histogram.md new file mode 100644 index 000000000..ba1a44059 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/histogram.md @@ -0,0 +1,83 @@ +--- +title: histogram() function +description: The `histogram()` function approximates the cumulative distribution of a dataset by counting data frequencies for a list of bins. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/histogram + - /influxdb/cloud/reference/flux/functions/built-in/transformations/histogram/ +menu: + influxdb_cloud_ref: + name: histogram + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/histograms/ +--- + +The `histogram()` function approximates the cumulative distribution of a dataset by counting data frequencies for a list of bins. +A bin is defined by an upper bound where all data points that are less than or equal to the bound are counted in the bin. +The bin counts are cumulative. + +Each input table is converted into a single output table representing a single histogram. +The output table has the same group key as the input table. +Columns not part of the group key are removed and an upper bound column and a count column are added. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +histogram(column: "_value", upperBoundColumn: "le", countColumn: "_value", bins: [50.0, 75.0, 90.0], normalize: false) +``` + +## Parameters + +### column +The name of a column containing input data values. +The column type must be float. +Defaults to `"_value"`. + +_**Data type:** String_ + +### upperBoundColumn +The name of the column in which to store the histogram's upper bounds. +Defaults to `"le"`. + +_**Data type:** String_ + +### countColumn +The name of the column in which to store the histogram counts. +Defaults to `"_value"`. + +_**Data type:** String_ + +### bins +A list of upper bounds to use when computing the histogram frequencies. +Bins should contain a bin whose bound is the maximum value of the data set. +This value can be set to positive infinity if no maximum is known. + +_**Data type:** Array of floats_ + +#### Bin helper functions +The following helper functions can be used to generated bins. + +[linearBins()](/influxdb/cloud/reference/flux/stdlib/built-in/misc/linearbins) +[logarithmicBins()](/influxdb/cloud/reference/flux/stdlib/built-in/misc/logarithmicbins) + +### normalize +When `true`, will convert the counts into frequency values between 0 and 1. +Defaults to `false`. + +_**Data type:** Boolean_ + +{{% note %}} +Normalized histograms cannot be aggregated by summing their counts. +{{% /note %}} + +## Examples + +##### Histogram with dynamically generated bins +```js +// Dynamically generate 10 bins from 0,10,20,...,100 +histogram( + bins: linearBins(start:0.0, width:10.0, count:10) +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/holtwinters.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/holtwinters.md new file mode 100644 index 000000000..c09128876 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/holtwinters.md @@ -0,0 +1,115 @@ +--- +title: holtWinters() function +description: > + The `holtWinters()` function applies the Holt-Winters forecasting method to input tables. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/holtwinters + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/holtwinters/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/holtwinters/ +menu: + influxdb_cloud_ref: + name: holtWinters + parent: built-in-transformations +weight: 402 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#holt-winters, InfluxQL HOLT_WINTERS() +--- + +The `holtWinters()` function applies the Holt-Winters forecasting method to input tables. + +_**Function type:** Transformation_ +_**Output data type:** Float_ + +```js +holtWinters( + n: 10, + seasonality: 4, + interval: 30d, + withFit: false, + timeColumn: "_time", + column: "_value", +) +``` + +The Holt-Winters method predicts [`n`](#n) seasonally-adjusted values for the +specified [`column`](#column) at the specified [`interval`](#interval). +For example, if `interval` is six minutes (`6m`) and `n` is `3`, results include three predicted +values six minutes apart. + +#### Seasonality +[`seasonality`](#seasonality) delimits the length of a seasonal pattern according to `interval`. +If your `interval` is two minutes (`2m`) and `seasonality` is `4`, then the seasonal pattern occurs every eight minutes or every four data points. Likewise, if your `interval` is two months (`2mo`) and `seasonality` is `4`, then the seasonal pattern occurs every eight months or every four data points. +If data doesn't have a seasonal pattern, set `seasonality` to `0`. + +#### Space values evenly in time +`holtWinters()` expects values evenly spaced in time. +To ensure `holtWinters()` values are spaced evenly in time, the following rules apply: + +- Data is grouped into time-based "buckets" determined by the `interval`. +- If a bucket includes many values, the first value is used. +- If a bucket includes no values, a missing value (`null`) is added for that bucket. + +By default, `holtWinters()` uses the first value in each time bucket to run the Holt-Winters calculation. +To specify other values to use in the calculation, use: + +- [`window()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window/) + with [selectors](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/) + or [aggregates](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/) +- [`aggregateWindow()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow) + +#### Fitted model +The `holtWinters()` function applies the [Nelder-Mead optimization](https://en.wikipedia.org/wiki/Nelder%E2%80%93Mead_method) +to include "fitted" data points in results when [`withFit`](#withfit) is set to `true`. + +#### Null timestamps +`holtWinters()` discards rows with `null` timestamps before running the Holt-Winters calculation. + +#### Null values +`holtWinters()` treats `null` values as missing data points and includes them in the Holt-Winters calculation. + +## Parameters + +### n +The number of values to predict. + +_**Data type:** Integer_ + +### seasonality +The number of points in a season. +Defaults to `0`. + +_**Data type:** Integer_ + +### interval +The interval between two data points. + +_**Data type:** Duration_ + +### withFit +Return [fitted data](#fitted-model) in results. +Defaults to `false`. + +_**Data type:** Boolean_ + +### timeColumn +The time column to use. +Defaults to `"_time"`. + +_**Data type:** String_ + +### column +The column to operate on. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples + +##### Use aggregateWindow to prepare data for holtWinters +```js +from(bucket: "example-bucket") + |> range(start: -7y) + |> filter(fn: (r) => r._field == "water_level") + |> aggregateWindow(every: 379m, fn: first). + |> holtWinters(n: 10, seasonality: 4, interval: 379m) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/hourselection.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/hourselection.md new file mode 100644 index 000000000..c1e429969 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/hourselection.md @@ -0,0 +1,56 @@ +--- +title: hourSelection() function +description: > + The `hourSelection()` function retains all rows with time values in a specified hour range. + Hours are specified in military time. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/hourselection + - /influxdb/cloud/reference/flux/functions/built-in/transformations/hourselection/ +menu: + influxdb_cloud_ref: + name: hourSelection + parent: built-in-transformations +weight: 402 +--- + +The `hourSelection()` function retains all rows with time values in a specified hour range. + +_**Function type:** Transformation_ + +```js +hourSelection( + start: 9, + stop: 17, + timeColumn: "_time" +) +``` + +## Parameters + +### start +The first hour of the hour range (inclusive). +Hours range from `[0-23]`. + +_**Data type:** Integer_ + +### stop +The last hour of the hour range (inclusive). +Hours range from `[0-23]`. + +_**Data type:** Integer_ + +### timeColumn +The column that contains the time value. +Default is `"_time"`. + +_**Data type:** String_ + +## Examples + +##### Use only data from 9am to 5pm +```js +from(bucket:"example-bucket") + |> range(start:-90d) + |> filter(fn: (r) => r._measurement == "foot-traffic" ) + |> hourSelection(start: 9, stop: 17) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/increase.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/increase.md new file mode 100644 index 000000000..f7a580910 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/increase.md @@ -0,0 +1,83 @@ +--- +title: increase() function +description: > + The `increase()` function calculates the cumulative sum of **non-negative** differences + between subsequent values. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/increase + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/increase/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/increase/ +menu: + influxdb_cloud_ref: + name: increase + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/increase/ +--- + +The `increase()` function calculates the cumulative sum of **non-negative** differences +between subsequent values. +A main use case is tracking changes in counter values which may wrap over time +when they hit a threshold or are reset. +In the case of a wrap/reset, we can assume that the absolute delta between two +points will be at least their non-negative difference. + +_**Function type:** Transformation_ +_**Output data type:** Float_ + +```js +increase(columns: ["_value"]) +``` + +## Parameters + +### columns +The columns to use in the operation. +Defaults to `["_value"]`. + +_**Data type:** Array of strings_ + +## Output tables +For each input table with `n` rows, `derivative()` outputs a table with `n - 1` rows. + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -24h) + |> filter(fn: (r) => + r._measurement == "system" and + r._field == "n_users" + ) + |> increase() +``` + +{{< flex >}} +{{% flex-content %}} +Given the following input table: + +| _time | _value | +| ----- | ------ | +| 00001 | 1 | +| 00002 | 5 | +| 00003 | 3 | +| 00004 | 4 | +{{% /flex-content %}} +{{% flex-content %}} +`increase()` produces the following table: + +| _time | _value | +| ----- | ------ | +| 00002 | 4 | +| 00003 | 4 | +| 00004 | 5 | +{{% /flex-content %}} +{{< /flex >}} + +## Function definition +```js +increase = (tables=<-, column="_value") => + tables + |> difference(nonNegative: true, column:column) + |> cumulativeSum() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/join.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/join.md new file mode 100644 index 000000000..c9d3966df --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/join.md @@ -0,0 +1,156 @@ +--- +title: join() function +description: The `join()` function merges two or more input streams whose values are equal on a set of common columns into a single output stream. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/join + - /influxdb/cloud/reference/flux/functions/built-in/transformations/join/ +menu: + influxdb_cloud_ref: + name: join + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/join/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/union/ +--- + +The `join()` function merges two or more input streams whose values are equal on +a set of common columns into a single output stream. +Null values are not considered equal when comparing column values. +The resulting schema is the union of the input schemas. +The resulting group key is the union of the input group keys. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +join(tables: {key1: table1, key2: table2}, on: ["_time", "_field"], method: "inner") +``` + +#### Output schema +The column schema of the output stream is the union of the input schemas. +It is also the same for the output group key. +Columns are renamed using the pattern `_` to prevent ambiguity in joined tables. + +##### Example: +If you have two streams of data, **data_1** and **data_2**, with the following group keys: + +**data_1**: `[_time, _field]` +**data_2**: `[_time, _field]` + +And join them with: + +```js +join(tables: {d1: data_1, d2: data_2}, on: ["_time"]) +``` + +The resulting group keys for all tables will be: `[_time, _field_d1, _field_d2]` + + +## Parameters + +### tables +The map of streams to be joined. Required + +_**Data type:** Record_ + +{{% note %}} +`join()` currently only supports two input streams. +{{% /note %}} + +### on +The list of columns on which to join. Required + +_**Data type:** Array of strings_ + +### method +The method used to join. Defaults to `"inner"`. + +_**Data type:** String_ + +###### Possible Values: +- `inner` + + + +## Examples + +#### Example join with sample data + +Given the following two streams of data: + +##### SF_Temp** + +| _time | _field | _value | +| ------ |:------:| -------:| +| 0001 | "temp" | 70 | +| 0002 | "temp" | 75 | +| 0003 | "temp" | 72 | + +##### NY_Temp** + +| _time | _field | _value | +| ------ |:------:| -------:| +| 0001 | "temp" | 55 | +| 0002 | "temp" | 56 | +| 0003 | "temp" | 55 | + +And the following join query: + +```js +join( + tables: {sf: SF_Temp, ny: NY_Temp}, + on: ["_time", "_field"] +) +``` + +The output will be: + +| _time | _field | _value_ny | _value_sf | +| ----- | ------ | ---------:| ---------:| +| 0001 | "temp" | 55 | 70 | +| 0002 | "temp" | 56 | 75 | +| 0003 | "temp" | 55 | 72 | + +#### Cross-measurement join +```js +data_1 = from(bucket:"example-bucket") + |> range(start:-15m) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + +data_2 = from(bucket:"example-bucket") + |> range(start:-15m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + +join( + tables: {d1: data_1, d2: data_2}, + on: ["_time", "host"] +) +``` + +## join() versus union() +`join()` creates new rows based on common values in one or more specified columns. +Output rows also contain the differing values from each of the joined streams. +`union()` does not modify data in rows, but unifies separate streams of tables +into a single stream of tables and groups rows of data based on existing +[group keys](/influxdb/cloud/reference/glossary/#group-key). + +Given two streams of tables, `t1` and `t2`, the results of `join()` and `union()` +are illustrated below: + +{{< svg "/static/svgs/join-vs-union.svg" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/kaufmansama.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/kaufmansama.md new file mode 100644 index 000000000..7954092cd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/kaufmansama.md @@ -0,0 +1,55 @@ +--- +title: kaufmansAMA() function +description: > + The `kaufmansAMA()` function calculates the Kaufman's Adaptive Moving Average (KAMA) + using values in an input table. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/kaufmansama/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/kaufmansama/ +menu: + influxdb_cloud_ref: + name: kaufmansAMA + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/kaufmanser/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#kaufmans-adaptive-moving-average, InfluxQL KAUFMANS_ADAPTIVE_MOVING_AVERAGE() +--- + +The `kaufmansAMA()` function calculates the Kaufman's Adaptive Moving Average (KAMA) +using values in an input table. + +_**Function type:** Transformation_ + +```js +kaufmansAMA( + n: 10, + column: "_value" +) +``` + +Kaufman's Adaptive Moving Average is a trend-following indicator designed to account +for market noise or volatility. + +## Parameters + +### n +The period or number of points to use in the calculation. + +_**Data type:** Integer_ + +### column +The column to operate on. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "telegraf/autogen"): + |> range(start: -7d) + |> kaufmansAMA( + n: 10, + column: "_value" + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/kaufmanser.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/kaufmanser.md new file mode 100644 index 000000000..a82d65016 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/kaufmanser.md @@ -0,0 +1,45 @@ +--- +title: kaufmansER() function +description: > + The `kaufmansER()` function calculates the Kaufman's Efficiency Ratio (KER) using + values in an input table. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/kaufmanser/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/kaufmanser/ +menu: + influxdb_cloud_ref: + name: kaufmansER + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/kaufmansama/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#kaufmans-efficiency-ratio, InfluxQL KAUFMANS_EFFICIENCY_RATIO() +--- + +The `kaufmansER()` function calculates the Kaufman's Efficiency Ratio (KER) using +values in an input table. +The function operates on the `_value` column. + +_**Function type:** Transformation_ + +```js +kaufmansER(n: 10) +``` + +Kaufman's Efficiency Ratio indicator divides the absolute value of the +Chande Momentum Oscillator by 100 to return a value between 0 and 1. +Higher values represent a more efficient or trending market. + +## Parameters + +### n +The period or number of points to use in the calculation. + +_**Data type:** Integer_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -7d) + |> kaufmansER(n: 10) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keep.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keep.md new file mode 100644 index 000000000..87feec4d2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keep.md @@ -0,0 +1,66 @@ +--- +title: keep() function +description: The `keep()` function returns a table containing only the specified columns. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/keep + - /influxdb/cloud/reference/flux/functions/built-in/transformations/keep/ +menu: + influxdb_cloud_ref: + name: keep + parent: built-in-transformations +weight: 402 +--- + +The `keep()` function returns a table containing only the specified columns, ignoring all others. +Only columns in the group key that are also specified in the `keep()` function will be kept in the resulting group key. +_It is the inverse of [`drop`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/drop)._ + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +keep(columns: ["col1", "col2"]) + +// OR + +keep(fn: (column) => column =~ /inodes*/) +``` + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### columns + +Columns that should be included in the resulting table. +Cannot be used with `fn`. + +_**Data type:** Array of strings_ + +### fn + +A predicate function which takes a column name as a parameter (`column`) and returns +a boolean indicating whether or not the column should be included in the resulting table. +Cannot be used with `columns`. + +_**Data type:** Function_ + +## Examples + +##### Keep a list of columns + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> keep(columns: ["_time", "_value"]) +``` + +##### Keep all columns matching a predicate + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> keep(fn: (column) => column =~ /inodes*/) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keys.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keys.md new file mode 100644 index 000000000..343174253 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keys.md @@ -0,0 +1,57 @@ +--- +title: keys() function +description: > + The `keys()` function outputs the group key of input tables. + For each input table, it outputs a table with the same group key columns, plus a + _value column containing the labels of the input table's group key. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/keys + - /influxdb/cloud/reference/flux/functions/built-in/transformations/keys/ +menu: + influxdb_cloud_ref: + name: keys + parent: built-in-transformations +weight: 402 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-measurements, InfluxQL – SHOW MEASUREMENTS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-field-keys, InfluxQL – SHOW FIELD KEYS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-tag-keys, InfluxQL – SHOW TAG KEYS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-tag-keys, InfluxQL – SHOW SERIES +--- + +The `keys()` function outputs the group key of input tables. +For each input table, it outputs a table with the same group key columns, plus a +`_value` column containing the labels of the input table's group key. +Each row in an output table contains the group key value and the label of one column in the group key of the input table. +Each output table has the same number of rows as the size of the group key of the input table. + +_**Function type:** Transformation_ + +```js +keys(column: "_value") +``` + +## Parameters + +### column +The name of the output column in which to store the group key labels. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -30m) + |> keys(column: "keys") +``` + +##### Return every possible key in a single table +```js +from(bucket: "example-bucket") + |> range(start: -30m) + |> keys() + |> keep(columns: ["_value"]) + |> group() + |> distinct() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keyvalues.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keyvalues.md new file mode 100644 index 000000000..620ad3531 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keyvalues.md @@ -0,0 +1,91 @@ +--- +title: keyValues() function +description: The `keyValues()` function returns a table with the input table's group key plus two columns, _key and _value, that correspond to unique column + value pairs from the input table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/keyvalues + - /influxdb/cloud/reference/flux/functions/built-in/transformations/keyvalues/ +menu: + influxdb_cloud_ref: + name: keyValues + parent: built-in-transformations +weight: 402 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-measurements, InfluxQL – SHOW MEASUREMENTS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-field-keys, InfluxQL – SHOW FIELD KEYS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-tag-keys, InfluxQL – SHOW TAG KEYS + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-tag-values, InfluxQL – SHOW TAG VALUES + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration/#show-serie, InfluxQL – SHOW SERIES +--- + +The `keyValues()` function returns a table with the input table's group key plus two columns, +`_key` and `_value`, that correspond to unique column + value pairs from the input table. + +_**Function type:** Transformation_ + +```js +keyValues(keyColumns: ["usage_idle", "usage_user"]) +``` + + + +## Parameters + + + +### keyColumns + +A list of columns from which values are extracted. +All columns indicated must be of the same type. +Each input table must have all of the columns listed by the `keyColumns` parameter. + +_**Data type:** Array of strings_ + + + +## Examples + +##### Get key values from explicitly defined columns + +```js +from(bucket: "example-bucket") + |> range(start: -30m) + |> filter(fn: (r) => r._measurement == "cpu") + |> keyValues(keyColumns: ["usage_idle", "usage_user"]) +``` + + diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/limit.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/limit.md new file mode 100644 index 000000000..54705b560 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/limit.md @@ -0,0 +1,52 @@ +--- +title: limit() function +description: The `limit()` function limits each output table to the first `n` records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/limit + - /influxdb/cloud/reference/flux/functions/built-in/transformations/limit/ +menu: + influxdb_cloud_ref: + name: limit + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/sort-limit/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/tail/ + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#the-limit-and-slimit-clauses, InfluxQL LIMIT +--- + +The `limit()` function limits each output table to the first [`n`](#n) records. +The function produces one output table for each input table. +Each output table contains the first `n` records after the [`offset`](#offset). +If the input table has less than `offset + n` records, `limit()` outputs all records after the `offset`. + +_**Function type:** Filter_ + +```js +limit( + n:10, + offset: 0 +) +``` + +## Parameters + +### n +The maximum number of records to output. + +_**Data type:** Integer_ + +### offset +The number of records to skip per table before limiting to `n`. +Defaults to `0`. + +_**Data type:** Integer_ + +## Examples + +##### Output the first ten records in each table +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> limit(n:10) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map.md new file mode 100644 index 000000000..fd485b581 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map.md @@ -0,0 +1,114 @@ +--- +title: map() function +description: The `map()` function applies a function to each record in the input tables. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/map + - /influxdb/cloud/reference/flux/functions/built-in/transformations/map/ +menu: + influxdb_cloud_ref: + name: map + parent: built-in-transformations +weight: 402 +influxdb/v2.0/tags: [exists] +related: + - /influxdb/cloud/query-data/flux/conditional-logic/ + - /influxdb/cloud/query-data/flux/mathematic-operations/ + - /influxdb/cloud/reference/flux/stdlib/contrib/rows/map/ +--- + +The `map()` function applies a function to each record in the input tables. +The modified records are assigned to new tables based on the group key of the input table. +The output tables are the result of applying the map function to each record of the input tables. + +When the output record contains a different value for the group key, the record is regrouped into the appropriate table. +When the output record drops a column that was part of the group key, that column is removed from the group key. + +_**Function type:** Transformation_ + +```js +map(fn: (r) => ({ _value: r._value * r._value })) +``` + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### fn + +A single argument function to apply to each record. +The return value must be a record. + +_**Data type:** Function_ + +{{% note %}} +Records evaluated in `fn` functions are represented by `r`, short for "record" or "row". +{{% /note %}} + +## Important notes + +#### Preserve columns + +By default, `map()` drops any columns that: + +1. Are not part of the input table's group key. +2. Are not explicitly mapped in the `map()` function. + +This often results in the `_time` column being dropped. +To preserve the `_time` column and other columns that do not meet the criteria above, +use the `with` operator to map values in the `r` record. +The `with` operator updates a column if it already exists, +creates a new column if it doesn't exist, and includes all existing columns in +the output table. + +```js +map(fn: (r) => ({ r with newColumn: r._value * 2 })) +``` + +## Examples + +###### Square the value of each record + +```js +from(bucket:"example-bucket") + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + |> range(start:-12h) + |> map(fn: (r) => ({ r with _value: r._value * r._value})) +``` + +###### Create a new table with new format + +```js +from(bucket:"example-bucket") + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> range(start:-12h) + // create a new table by copying each row into a new format + |> map(fn: (r) => ({ + time: r._time, + app_server: r.host + })) +``` + +###### Add new columns and preserve existing columns +```js +from(bucket:"example-bucket") + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> range(start:-12h) + // create a new table by copying each row into a new format + |> map(fn: (r) => ({ + r with + app_server: r.host, + valueInt: int(v: r._value) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage.md new file mode 100644 index 000000000..1c09d1051 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage.md @@ -0,0 +1,73 @@ +--- +title: movingAverage() function +description: > + The `movingAverage()` function calculates the mean of values grouped into `n` number of points. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/movingaverage/ + - /influxdb/cloud/reference/flux/functions/built-in/transformations/movingaverage/ +menu: + influxdb_cloud_ref: + name: movingAverage + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/moving-average/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleema/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#moving-average, InfluxQL MOVING_AVERAGE() +--- + +The `movingAverage()` function calculates the mean of values in the `_values` column +grouped into `n` number of points. + +_**Function type:** Transformation_ + +```js +movingAverage(n: 5) +``` + +##### Moving average rules +- The average over a period populated by `n` values is equal to their algebraic mean. +- The average over a period populated by only `null` values is `null`. +- Moving averages skip `null` values. +- If `n` is less than the number of records in a table, `movingAverage` returns + the average of the available values. + +## Parameters + +### n +The number of points to average. + +_**Data type:** Integer_ + +## Examples + +#### Calculate a five point moving average +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> movingAverage(n: 5) +``` + +#### Table transformation with a two point moving average + +###### Input table: +| _time | tag | _value | +|:-----:|:---:|:------:| +| 0001 | tv | null | +| 0002 | tv | 6 | +| 0003 | tv | 4 | + +###### Query: +```js +// ... + |> movingAverage(n: 2 ) +``` + +###### Output table: +| _time | tag | _value | +|:-----:|:---:|:------:| +| 0002 | tv | 6 | +| 0003 | tv | 5 | diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pearsonr.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pearsonr.md new file mode 100644 index 000000000..971b47131 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pearsonr.md @@ -0,0 +1,65 @@ +--- +title: pearsonr() function +description: The `pearsonr()` function computes the Pearson R correlation coefficient between two streams by first joining the streams, then performing the covariance operation normalized to compute R. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/aggregates/pearsonr + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/pearsonr/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/pearsonr/ +menu: + influxdb_cloud_ref: + name: pearsonr + parent: built-in-transformations +weight: 402 +--- + +The `pearsonr()` function computes the Pearson R correlation coefficient between two streams +by first joining the streams, then performing the covariance operation normalized to compute R. + +_**Function type:** Transformation_ +_**Output data type:** Float_ + +```js +pearsonr(x: stream1, y: stream2, on: ["_time", "_field"]) +``` + +## Parameters + +### x +First input stream used in the operation. + +_**Data type:** Record_ + +### y +Second input stream used in the operation. + +_**Data type:** Record_ + +### on +The list of columns on which to join. + +_**Data type:** Array of strings_ + +## Examples +```js +stream1 = from(bucket:"example-bucket") + |> range(start:-15m) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used" + ) + +stream2 = from(bucket:"example-bucket") + |> range(start:-15m) + |> filter(fn: (r) => r + ._measurement == "mem" and + r._field == "available" + ) + +pearsonr(x: stream1, y: stream2, on: ["_time"]) +``` + +## Function definition +```js +pearsonr = (x,y,on) => + cov(x:x, y:y, on:on, pearsonr:true) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot.md new file mode 100644 index 000000000..8ded835e0 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot.md @@ -0,0 +1,146 @@ +--- +title: pivot() function +description: The `pivot()` function collects values stored vertically (column-wise) in a table and aligns them horizontally (row-wise) into logical sets. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/pivot + - /influxdb/cloud/reference/flux/functions/built-in/transformations/pivot/ +menu: + influxdb_cloud_ref: + name: pivot + parent: built-in-transformations +weight: 402 +--- + +The `pivot()` function collects values stored vertically (column-wise) in a table +and aligns them horizontally (row-wise) into logical sets. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") +``` + +The group key of the resulting table is the same as the input tables, excluding columns found in the [`columnKey`](#columnkey) and [`valueColumn`](#valuecolumn) parameters. +This is because these columns are not part of the resulting output table. + +Every input row should have a 1:1 mapping to a particular row + column in the output table, determined by its values for the [`rowKey`](#rowkey) and [`columnKey`](#columnkey) parameters. +In cases where more than one value is identified for the same row + column pair, the last value +encountered in the set of table rows is used as the result. + +The output is constructed as follows: + +- The set of columns for the new table is the `rowKey` unioned with the group key, + but excluding the columns indicated by the `columnKey` and the `valueColumn`. +- A new column is added to the set of columns for each unique value identified + in the input by the `columnKey` parameter. +- The label of a new column is the concatenation of the values of `columnKey` using `_` as a separator. + If the value is `null`, `"null"` is used. +- A new row is created for each unique value identified in the input by the `rowKey` parameter. +- For each new row, values for group key columns stay the same, while values for new columns are + determined from the input tables by the value in `valueColumn` at the row identified by the + `rowKey` values and the new column's label. + If no value is found, the value is set to `null`. + + +## Parameters + +### rowKey +List of columns used to uniquely identify a row for the output. + +_**Data type:** Array of strings_ + +### columnKey +List of columns used to pivot values onto each row identified by the rowKey. + +_**Data type:** Array of strings_ + +### valueColumn +The single column that contains the value to be moved around the pivot. + +_**Data type:** String_ + +## Examples + +### Align fields within each measurement that have the same timestamp + +```js +from(bucket:"test") + |> range(start: 1970-01-01T00:00:00.000000000Z) + |> pivot( + rowKey:["_time"], + columnKey: ["_field"], + valueColumn: "_value" + ) +``` + +###### Input +| _time | _value | _measurement | _field | +|:------------------------------:|:------:|:------------:|:------:| +| 1970-01-01T00:00:00.000000001Z | 1.0 | "m1" | "f1" | +| 1970-01-01T00:00:00.000000001Z | 2.0 | "m1" | "f2" | +| 1970-01-01T00:00:00.000000001Z | null | "m1" | "f3" | +| 1970-01-01T00:00:00.000000001Z | 3.0 | "m1" | null | +| 1970-01-01T00:00:00.000000002Z | 4.0 | "m1" | "f1" | +| 1970-01-01T00:00:00.000000002Z | 5.0 | "m1" | "f2" | +| null | 6.0 | "m1" | "f2" | +| 1970-01-01T00:00:00.000000002Z | null | "m1" | "f3" | +| 1970-01-01T00:00:00.000000003Z | null | "m1" | "f1" | +| 1970-01-01T00:00:00.000000003Z | 7.0 | "m1" | null | +| 1970-01-01T00:00:00.000000004Z | 8.0 | "m1" | "f3" | + +###### Output +| _time | _measurement | f1 | f2 | f3 | null | +|:------------------------------:|:------------:|:----:|:----:|:----:|:----:| +| 1970-01-01T00:00:00.000000001Z | "m1" | 1.0 | 2.0 | null | 3.0 | +| 1970-01-01T00:00:00.000000002Z | "m1" | 4.0 | 5.0 | null | null | +| null | "m1" | null | 6.0 | null | null | +| 1970-01-01T00:00:00.000000003Z | "m1" | null | null | null | 7.0 | +| 1970-01-01T00:00:00.000000004Z | "m1" | null | null | 8.0 | null | + +### Align fields and measurements that have the same timestamp + +{{% note %}} +Note the effects of: + +- Having null values in some `columnKey` value; +- Having more values for the same `rowKey` and `columnKey` value + (the 11th row overrides the 10th, and so does the 15th with the 14th). +{{% /note %}} + +```js +from(bucket:"test") + |> range(start: 1970-01-01T00:00:00.000000000Z) + |> pivot( + rowKey:["_time"], + columnKey: ["_measurement", "_field"], + valueColumn: "_value" + ) +``` + +###### Input +| _time | _value | _measurement | _field | +|:------------------------------:|:------:|:------------:|:------:| +| 1970-01-01T00:00:00.000000001Z | 1.0 | "m1" | "f1" | +| 1970-01-01T00:00:00.000000001Z | 2.0 | "m1" | "f2" | +| 1970-01-01T00:00:00.000000001Z | 3.0 | null | "f3" | +| 1970-01-01T00:00:00.000000001Z | 4.0 | null | null | +| 1970-01-01T00:00:00.000000002Z | 5.0 | "m1" | "f1" | +| 1970-01-01T00:00:00.000000002Z | 6.0 | "m1" | "f2" | +| 1970-01-01T00:00:00.000000002Z | 7.0 | "m1" | "f3" | +| 1970-01-01T00:00:00.000000002Z | 8.0 | null | null | +| null | 9.0 | "m1" | "f3" | +| 1970-01-01T00:00:00.000000003Z | 10.0 | "m1" | null | +| 1970-01-01T00:00:00.000000003Z | 11.0 | "m1" | null | +| 1970-01-01T00:00:00.000000003Z | 12.0 | "m1" | "f3" | +| 1970-01-01T00:00:00.000000003Z | 13.0 | null | null | +| null | 14.0 | "m1" | null | +| null | 15.0 | "m1" | null | + +###### Output +| _time | m1_f1 | m1_f2 | null_f3 | null_null | m1_f3 | m1_null | +|:------------------------------:|:-----:|:-----:|:---------:|:---------:|:-----:|:-------:| +| 1970-01-01T00:00:00.000000001Z | 1.0 | 2.0 | 3.0 | 4.0 | null | null | +| 1970-01-01T00:00:00.000000002Z | 5.0 | 6.0 | null | 8.0 | 7.0 | null | +| null | null | null | null | null | 9.0 | 15.0 | +| 1970-01-01T00:00:00.000000003Z | null | null | null | 13.0 | 12.0 | 11.0 | diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range.md new file mode 100644 index 000000000..b38188145 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range.md @@ -0,0 +1,82 @@ +--- +title: range() function +description: The `range()` function filters records based on time bounds. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/range + - /influxdb/cloud/reference/flux/functions/built-in/transformations/range/ +menu: + influxdb_cloud_ref: + name: range + parent: built-in-transformations +weight: 402 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#the-where-clause, InfluxQL – WHERE +--- + +The `range()` function filters records based on time bounds. +Each input table's records are filtered to contain only records that exist within the time bounds. +Records with a `null` value for their time are filtered. +Each input table's group key value is modified to fit within the time bounds. +Tables where all records exists outside the time bounds are filtered entirely. + +_**Function type:** Transformation_ +_**Output data type:* Record_ + +```js +range(start: -15m, stop: now()) +``` + +## Parameters + +### start +The earliest time to include in results. +Results **include** points that match the specified start time. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. + +_**Data type:** Duration | Time | Integer_ + +### stop +The latest time to include in results. +Results **exclude** points that match the specified stop time. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. +Defaults to `now()`. + +_**Data type:** Duration | Time | Integer_ + +{{% note %}} +Time values in Flux must be in [RFC3339 format](/influxdb/cloud/reference/flux/language/types#timestamp-format). +{{% /note %}} + +## Examples + +###### Time range relative to now +```js +from(bucket:"example-bucket") + |> range(start: -12h) + // ... +``` + +###### Relative time range +```js +from(bucket:"example-bucket") + |> range(start: -12h, stop: -15m) + // ... +``` + +###### Absolute time range +```js +from(bucket:"example-bucket") + |> range(start: 2018-05-22T23:30:00Z, stop: 2018-05-23T00:00:00Z) + // ... +``` + +###### Absolute time range with Unix timestamps +```js +from(bucket:"example-bucket") + |> range(start: 1527031800, stop: 1527033600) + // ... +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/relativestrengthindex.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/relativestrengthindex.md new file mode 100644 index 000000000..0801f7d3a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/relativestrengthindex.md @@ -0,0 +1,115 @@ +--- +title: relativeStrengthIndex() function +description: > + The `relativeStrengthIndex()` function measures the relative speed and change of + values in an input table. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/relativestrengthindex/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/relativestrengthindex/ +menu: + influxdb_cloud_ref: + name: relativeStrengthIndex + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#relative-strength-index, InfluxQL RELATIVE_STRENGTH_INDEX() +--- + +The `relativeStrengthIndex()` function measures the relative speed and change of +values in an input table. + +_**Function type:** Transformation_ + +```js +relativeStrengthIndex( + n: 5, + columns: ["_value"] +) +``` + +##### Relative strength index rules +- The general equation for calculating a relative strength index (RSI) is + `RSI = 100 - (100 / (1 + (AVG GAIN / AVG LOSS)))`. +- For the first value of the RSI, `AVG GAIN` and `AVG LOSS` are averages of the `n` period. +- For subsequent calculations: + - `AVG GAIN` = `((PREVIOUS AVG GAIN) * (n - 1)) / n` + - `AVG LOSS` = `((PREVIOUS AVG LOSS) * (n - 1)) / n` +- `relativeStrengthIndex()` ignores `null` values. + +## Parameters + +### n +The number of values to use to calculate the RSI. + +_**Data type:** Integer_ + +### columns +Columns to operate on. _Defaults to `["_value"]`_. + +_**Data type:** Array of Strings_ + +## Output tables +For each input table with `x` rows, `relativeStrengthIndex()` outputs a table +with `x - n` rows. + +## Examples + +#### Calculate a five point relative strength index +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> relativeStrengthIndex(n: 5) +``` + +#### Table transformation with a ten point RSI + +{{< flex >}} +{{% flex-content %}} +###### Input table: +| _time | A | B | tag | +|:-----:|:----:|:----:|:---:| +| 0001 | 1 | 1 | tv | +| 0002 | 2 | 2 | tv | +| 0003 | 3 | 3 | tv | +| 0004 | 4 | 4 | tv | +| 0005 | 5 | 5 | tv | +| 0006 | 6 | 6 | tv | +| 0007 | 7 | 7 | tv | +| 0008 | 8 | 8 | tv | +| 0009 | 9 | 9 | tv | +| 0010 | 10 | 10 | tv | +| 0011 | 11 | 11 | tv | +| 0012 | 12 | 12 | tv | +| 0013 | 13 | 13 | tv | +| 0014 | 14 | 14 | tv | +| 0015 | 15 | 15 | tv | +| 0016 | 16 | 16 | tv | +| 0017 | 17 | null | tv | +| 0018 | 18 | 17 | tv | +{{% /flex-content %}} +{{% flex-content %}} +###### Query: +```js +// ... + |> relativeStrengthIndex( + n: 10, + columns: ["A", "B"] + ) +``` + +###### Output table: +| _time | A | B | tag | +|:-----:|:----:|:----:|:---:| +| 0011 | 100 | 100 | tv | +| 0012 | 100 | 100 | tv | +| 0013 | 100 | 100 | tv | +| 0014 | 100 | 100 | tv | +| 0015 | 100 | 100 | tv | +| 0016 | 90 | 90 | tv | +| 0017 | 81 | 90 | tv | +| 0018 | 72.9 | 81 | tv | +{{% flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/rename.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/rename.md new file mode 100644 index 000000000..f7050f575 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/rename.md @@ -0,0 +1,68 @@ +--- +title: rename() function +description: The `rename()` function renames specified columns in a table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/rename + - /influxdb/cloud/reference/flux/functions/built-in/transformations/rename/ +menu: + influxdb_cloud_ref: + name: rename + parent: built-in-transformations +weight: 402 +--- + +The `rename()` function renames specified columns in a table. +If a column is renamed and is part of the group key, the column name in the group key will be updated. + +There are two variants: + +- one which maps old column names to new column names +- one which takes a mapping function. + +_**Function type:** Transformation_ + +```js +rename(columns: {host: "server", facility: "datacenter"}) + +// OR + +rename(fn: (column) => "{column}_new") +``` + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### columns + +A map of columns to rename and their corresponding new names. +Cannot be used with `fn`. + +_**Data type:** Record_ + +### fn + +A function mapping between old and new column names. +Cannot be used with `columns`. + +_**Data type:** Function_ + +## Examples + +##### Rename a single column + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> rename(columns: {host: "server"}) +``` + +##### Rename all columns using a function + +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> rename(fn: (column) => column + "_new") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/_index.md new file mode 100644 index 000000000..ca215a5cb --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/_index.md @@ -0,0 +1,32 @@ +--- +title: Flux built-in selector functions +list_title: Built-in selector functions +description: Flux's built-in selector functions return one or more records based on function logic. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/ +menu: + influxdb_cloud_ref: + parent: built-in-transformations + name: Selectors + identifier: built-in-selectors +weight: 401 +influxdb/v2.0/tags: [selectors, built-in, functions] +related: + - /influxdb/cloud/query-data/flux/window-aggregate/ +--- + +Flux's built-in selector functions return one or more records based on function logic. +The output table is different than the input table, but individual row values are not. + +The following selector functions are available: + +{{< children type="functions" >}} + + +### Selectors and aggregates +The following functions can be used as both selectors or aggregates, but they are +categorized as aggregate functions in this documentation: + +- [median](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/median) +- [quantile](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/quantile) diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/bottom.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/bottom.md new file mode 100644 index 000000000..345f110b2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/bottom.md @@ -0,0 +1,65 @@ +--- +title: bottom() function +description: The `bottom()` function sorts a table by columns and keeps only the bottom n records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/bottom + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/bottom/ +menu: + influxdb_cloud_ref: + name: bottom + parent: built-in-selectors +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#bottom, InfluxQL – BOTTOM() +--- + +The `bottom()` function sorts a table by columns and keeps only the bottom `n` records. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +bottom(n:10, columns: ["_value"]) +``` + +{{% warn %}} +#### Empty tables +`bottom()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Number of records to return. + +_**Data type:** Integer_ + +### columns +List of columns by which to sort. +Sort precedence is determined by list order (left to right). +Default is `["_value"]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> bottom(n:10) +``` + +## Function definition +```js +// _sortLimit is a helper function, which sorts and limits a table. +_sortLimit = (n, desc, columns=["_value"], tables=<-) => + tables + |> sort(columns:columns, desc:desc) + |> limit(n:n) + +bottom = (n, columns=["_value"], tables=<-) => + _sortLimit(n:n, columns:columns, desc:false) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/distinct.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/distinct.md new file mode 100644 index 000000000..0245ee460 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/distinct.md @@ -0,0 +1,45 @@ +--- +title: distinct() function +description: The `distinct()` function returns the unique values for a given column. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/distinct + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/distinct/ +menu: + influxdb_cloud_ref: + name: distinct + parent: built-in-selectors +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#distinct, InfluxQL – DISTINCT() +--- + +The `distinct()` function returns the unique values for a given column. +The `_value` of each output record is set to the distinct value in the specified column. +`null` is considered its own distinct value if it is present. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +distinct(column: "host") +``` + +{{% warn %}} +#### Empty tables +`distinct()` drops empty tables. +{{% /warn %}} + +## Parameters + +### column +Column on which to track unique values. + +_**Data type:** string_ + +## Examples +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "cpu") + |> distinct(column: "host") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/first.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/first.md new file mode 100644 index 000000000..1b2c52258 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/first.md @@ -0,0 +1,40 @@ +--- +title: first() function +description: The `first()` function selects the first non-null record from an input table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/first + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/first/ +menu: + influxdb_cloud_ref: + name: first + parent: built-in-selectors +weight: 501 +related: + - /influxdb/cloud/query-data/flux/first-last/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#first, InfluxQL – FIRST() +--- + +The `first()` function selects the first non-null record from an input table. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +first() +``` + +{{% warn %}} +#### Empty tables +`first()` drops empty tables. +{{% /warn %}} + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> first() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestaverage.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestaverage.md new file mode 100644 index 000000000..ddaa01b8b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestaverage.md @@ -0,0 +1,90 @@ +--- +title: highestAverage() function +description: The `highestAverage()` function calculates the average of each table in the input stream returns the top `n` records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/highestaverage + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/highestaverage/ +menu: + influxdb_cloud_ref: + name: highestAverage + parent: built-in-selectors +weight: 501 +--- + +The `highestAverage()` function calculates the average of each table in the input stream returns the top `n` records. +It outputs a single aggregated table containing `n` records. + +_**Function type:** Selector, Aggregate_ + +```js +highestAverage( + n:10, + column: "_value", + groupColumns: [] +) +``` + +{{% warn %}} +#### Empty tables +`highestAverage()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Number of records to return. + +_**Data type:** Integer_ + +### column +Column by which to sort. +Default is `"_value"`. + +_**Data type:** String_ + +### groupColumns +The columns on which to group before performing the aggregation. +Default is `[]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> highestAverage(n:10, groupColumns: ["host"]) +``` + +## Function definition +```js +// _sortLimit is a helper function, which sorts and limits a table. +_sortLimit = (n, desc, columns=["_value"], tables=<-) => + tables + |> sort(columns:columns, desc:desc) + |> limit(n:n) + +// _highestOrLowest is a helper function which reduces all groups into a single +// group by specific tags and a reducer function. It then selects the highest or +// lowest records based on the column and the _sortLimit function. +// The default reducer assumes no reducing needs to be performed. +_highestOrLowest = (n, _sortLimit, reducer, column="_value", groupColumns=[], tables=<-) => + tables + |> group(columns:groupColumns) + |> reducer() + |> group(columns:[]) + |> _sortLimit(n:n, columns:[column]) + +highestAverage = (n, column="_value", groupColumns=[], tables=<-) => + tables + |> _highestOrLowest( + n:n, + columns:columns, + groupColumns:groupColumns, + reducer: (tables=<-) => tables |> mean(column:column), + _sortLimit: top, + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestcurrent.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestcurrent.md new file mode 100644 index 000000000..c5a894642 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestcurrent.md @@ -0,0 +1,90 @@ +--- +title: highestCurrent() function +description: The `highestCurrent()` function selects the last record of each table in the input stream and returns the top `n` records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/highestcurrent + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/highestcurrent/ +menu: + influxdb_cloud_ref: + name: highestCurrent + parent: built-in-selectors +weight: 501 +--- + +The `highestCurrent()` function selects the last record of each table in the input stream and returns the top `n` records. +It outputs a single aggregated table containing `n` records. + +_**Function type:** Selector, Aggregate_ + +```js +highestCurrent( + n:10, + column: "_value", + groupColumns: [] +) +``` + +{{% warn %}} +#### Empty tables +`highestCurrent()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Number of records to return. + +_**Data type:** Integer_ + +### column +Column by which to sort. +Default is `"_value"`. + +_**Data type:** String_ + +### groupColumns +The columns on which to group before performing the aggregation. +Default is `[]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> highestCurrent(n:10, groupColumns: ["host"]) +``` + +## Function definition +```js +// _sortLimit is a helper function, which sorts and limits a table. +_sortLimit = (n, desc, columns=["_value"], tables=<-) => + tables + |> sort(columns:columns, desc:desc) + |> limit(n:n) + +// _highestOrLowest is a helper function which reduces all groups into a single +// group by specific tags and a reducer function. It then selects the highest or +// lowest records based on the column and the _sortLimit function. +// The default reducer assumes no reducing needs to be performed. +_highestOrLowest = (n, _sortLimit, reducer, column="_value", groupColumns=[], tables=<-) => + tables + |> group(columns:groupColumns) + |> reducer() + |> group(columns:[]) + |> _sortLimit(n:n, columns:[column]) + +highestCurrent = (n, column="_value", groupColumns=[], tables=<-) => + tables + |> _highestOrLowest( + n:n, + column:column, + groupColumns:groupColumns, + reducer: (tables=<-) => tables |> last(column:column), + _sortLimit: top, + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestmax.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestmax.md new file mode 100644 index 000000000..aed18eec1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/highestmax.md @@ -0,0 +1,90 @@ +--- +title: highestMax() function +description: The `highestMax()` function selects the maximum record from each table in the input stream and returns the top `n` records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/highestmax + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/highestmax/ +menu: + influxdb_cloud_ref: + name: highestMax + parent: built-in-selectors +weight: 501 +--- + +The `highestMax()` function selects the maximum record from each table in the input stream and returns the top `n` records. +It outputs a single aggregated table containing `n` records. + +_**Function type:** Selector, Aggregate_ + +```js +highestMax( + n:10, + column: "_value", + groupColumns: [] +) +``` + +{{% warn %}} +#### Empty tables +`highestMax()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Number of records to return. + +_**Data type:** Integer_ + +### column +Column by which to sort. +Default is `"_value"`. + +_**Data type:** String_ + +### groupColumns +The columns on which to group before performing the aggregation. +Default is `[]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> highestMax(n:10, groupColumns: ["host"]) +``` + +## Function definition +```js +// _sortLimit is a helper function, which sorts and limits a table. +_sortLimit = (n, desc, columns=["_value"], tables=<-) => + tables + |> sort(columns:columns, desc:desc) + |> limit(n:n) + +// _highestOrLowest is a helper function which reduces all groups into a single +// group by specific tags and a reducer function. It then selects the highest or +// lowest records based on the column and the _sortLimit function. +// The default reducer assumes no reducing needs to be performed. +_highestOrLowest = (n, _sortLimit, reducer, column="_value", groupColumns=[], tables=<-) => + tables + |> group(columns:groupColumns) + |> reducer() + |> group(columns:[]) + |> _sortLimit(n:n, columns:[column]) + +highestMax = (n, column="_value", groupColumns=[], tables=<-) => + tables + |> _highestOrLowest( + n:n, + column:column, + groupColumns:groupColumns, + reducer: (tables=<-) => tables |> max(column:column), + _sortLimit: top + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/last.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/last.md new file mode 100644 index 000000000..f03e63ebf --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/last.md @@ -0,0 +1,40 @@ +--- +title: last() function +description: The `last()` function selects the last non-null record from an input table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/last + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/last/ +menu: + influxdb_cloud_ref: + name: last + parent: built-in-selectors +weight: 501 +related: + - /influxdb/cloud/query-data/flux/first-last/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#last, InfluxQL – LAST() +--- + +The `last()` function selects the last non-null record from an input table. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +last() +``` + +{{% warn %}} +#### Empty tables +`last()` drops empty tables. +{{% /warn %}} + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> last() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestaverage.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestaverage.md new file mode 100644 index 000000000..95ced0b87 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestaverage.md @@ -0,0 +1,91 @@ +--- +title: lowestAverage() function +description: The `lowestAverage()` function calculates the average of each table in the input stream returns the lowest `n` records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/lowestaverage + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/lowestaverage/ +menu: + influxdb_cloud_ref: + name: lowestAverage + parent: built-in-selectors +weight: 501 +--- + +The `lowestAverage()` function calculates the average of each table in the input stream returns the lowest `n` records. +It outputs a single aggregated table containing `n` records. + +_**Function type:** Selector, Aggregate_ + +```js +lowestAverage( + n:10, + column: "_value", + groupColumns: [] +) +``` + +{{% warn %}} +#### Empty tables +`lowestAverage()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Number of records to return. + +_**Data type:** Integer_ + +### column +Column by which to sort. +Default is `"_value"`. + +_**Data type:** String_ + +### groupColumns +The columns on which to group before performing the aggregation. +Default is `[]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> lowestAverage(n:10, groupColumns: ["host"]) +``` + +## Function definition +```js +// _sortLimit is a helper function, which sorts and limits a table. +_sortLimit = (n, desc, columns=["_value"], tables=<-) => + tables + |> sort(columns:columns, desc:desc) + |> limit(n:n) + +// _highestOrLowest is a helper function which reduces all groups into a single +// group by specific tags and a reducer function. It then selects the highest or +// lowest records based on the column and the _sortLimit function. +// The default reducer assumes no reducing needs to be performed. +_highestOrLowest = (n, _sortLimit, reducer, column="_value", groupColumns=[], tables=<-) => + tables + |> group(columns:groupColumns) + |> reducer() + |> group(columns:[]) + |> _sortLimit(n:n, columns:[column]) + +lowestAverage = (n, column="_value", groupColumns=[], tables=<-) => + tables + |> _highestOrLowest( + n:n, + column:column, + groupColumns:groupColumns, + reducer: (tables=<-) => tables |> mean(column:column]), + _sortLimit: bottom, + ) + +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestcurrent.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestcurrent.md new file mode 100644 index 000000000..393e7b504 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestcurrent.md @@ -0,0 +1,90 @@ +--- +title: lowestCurrent() function +description: The `lowestCurrent()` function selects the last record of each table in the input stream and returns the lowest `n` records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/lowestcurrent + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/lowestcurrent/ +menu: + influxdb_cloud_ref: + name: lowestCurrent + parent: built-in-selectors +weight: 501 +--- + +The `lowestCurrent()` function selects the last record of each table in the input stream and returns the lowest `n` records. +It outputs a single aggregated table containing `n` records. + +_**Function type:** Selector, Aggregate_ + +```js +lowestCurrent( + n:10, + column: "_value", + groupColumns: [] +) +``` + +{{% warn %}} +#### Empty tables +`lowestCurrent()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Number of records to return. + +_**Data type:** Integer_ + +### column +Column by which to sort. +Default is `"_value"`. + +_**Data type:** String_ + +### groupColumns +The columns on which to group before performing the aggregation. +Default is `[]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> lowestCurrent(n:10, groupColumns: ["host"]) +``` + +## Function definition +```js +// _sortLimit is a helper function, which sorts and limits a table. +_sortLimit = (n, desc, columns=["_value"], tables=<-) => + tables + |> sort(columns:columns, desc:desc) + |> limit(n:n) + +// _highestOrLowest is a helper function which reduces all groups into a single +// group by specific tags and a reducer function. It then selects the highest or +// lowest records based on the column and the _sortLimit function. +// The default reducer assumes no reducing needs to be performed. +_highestOrLowest = (n, _sortLimit, reducer, column="_value", groupColumns=[], tables=<-) => + tables + |> group(columns:groupColumns) + |> reducer() + |> group(columns:[]) + |> _sortLimit(n:n, columns:[column]) + +lowestCurrent = (n, column="_value", groupColumns=[], tables=<-) => + tables + |> _highestOrLowest( + n:n, + column:column, + groupColumns:groupColumns, + reducer: (tables=<-) => tables |> last(column:column), + _sortLimit: bottom, + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestmin.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestmin.md new file mode 100644 index 000000000..33e45e72f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/lowestmin.md @@ -0,0 +1,90 @@ +--- +title: lowestMin() function +description: The `lowestMin()` function selects the minimum record from each table in the input stream and returns the lowest `n` records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/lowestmin + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/lowestmin/ +menu: + influxdb_cloud_ref: + name: lowestMin + parent: built-in-selectors +weight: 501 +--- + +The `lowestMin()` function selects the minimum record from each table in the input stream and returns the lowest `n` records. +It outputs a single aggregated table containing `n` records. + +_**Function type:** Selector, Aggregate_ + +```js +lowestMin( + n:10, + column: "_value", + groupColumns: [] +) +``` + +{{% warn %}} +#### Empty tables +`lowestMin()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Number of records to return. + +_**Data type:** Integer_ + +### column +Column by which to sort. +Default is `"_value"`. + +_**Data type:** String_ + +### groupColumns +The columns on which to group before performing the aggregation. +Default is `[]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> lowestMin(n:10, groupColumns: ["host"]) +``` + +## Function definition +```js +// _sortLimit is a helper function, which sorts and limits a table. +_sortLimit = (n, desc, columns=["_value"], tables=<-) => + tables + |> sort(columns:columns, desc:desc) + |> limit(n:n) + +// _highestOrLowest is a helper function which reduces all groups into a single +// group by specific tags and a reducer function. It then selects the highest or +// lowest records based on the column and the _sortLimit function. +// The default reducer assumes no reducing needs to be performed. +_highestOrLowest = (n, _sortLimit, reducer, column="_value", groupColumns=[], tables=<-) => + tables + |> group(columns:groupColumns) + |> reducer() + |> group(columns:[]) + |> _sortLimit(n:n, columns:[column]) + +lowestMin = (n, column="_value", groupColumns=[], tables=<-) => + tables + |> _highestOrLowest( + n:n, + column:column, + groupColumns:groupColumns, + reducer: (tables=<-) => tables |> min(column:column), + _sortLimit: bottom, + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/max.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/max.md new file mode 100644 index 000000000..47d5f834e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/max.md @@ -0,0 +1,47 @@ +--- +title: max() function +description: The `max()` function selects record with the highest _value from the input table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/max + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/max/ +menu: + influxdb_cloud_ref: + name: max + parent: built-in-selectors +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#max, InfluxQL – MAX() +--- + +The `max()` function selects record with the highest `_value` from the input table. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +max(column: "_value") +``` + +{{% warn %}} +#### Empty tables +`max()` drops empty tables. +{{% /warn %}} + +## Parameters + +### column +The column to use to calculate the maximum value. +Default is `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> max() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/min.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/min.md new file mode 100644 index 000000000..a21a6c9e9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/min.md @@ -0,0 +1,47 @@ +--- +title: min() function +description: The `min()` function selects record with the lowest _value from the input table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/min + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/min/ +menu: + influxdb_cloud_ref: + name: min + parent: built-in-selectors +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#min, InfluxQL – MIN() +--- + +The `min()` function selects record with the lowest `_value` from the input table. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +min(column: "_value") +``` + +{{% warn %}} +#### Empty tables +`min()` drops empty tables. +{{% /warn %}} + +## Parameters + +### column +The column to use to calculate the minimum value. +Default is `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> min() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/sample.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/sample.md new file mode 100644 index 000000000..06ceb1e27 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/sample.md @@ -0,0 +1,54 @@ +--- +title: sample() function +description: The `sample()` function selects a subset of the records from the input table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/sample + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/sample/ +menu: + influxdb_cloud_ref: + name: sample + parent: built-in-selectors +weight: 501 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#sample, InfluxQL – SAMPLE() +--- + +The `sample()` function selects a subset of the records from the input table. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +sample(n:5, pos: -1) +``` + +{{% warn %}} +#### Empty tables +`sample()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Sample every Nth element. + +_**Data type:** Integer_ + +### pos +The position offset from the start of results where sampling begins. +`pos` must be less than `n`. +If `pos` is less than 0, a random offset is used. +Defaults to `-1` (random offset). + +_**Data type:** Integer_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1d) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" + ) + |> sample(n: 5, pos: 1) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/top.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/top.md new file mode 100644 index 000000000..b602988d4 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/top.md @@ -0,0 +1,62 @@ +--- +title: top() function +description: The `top()` function sorts a table by columns and keeps only the top n records. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/top + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/top/ +menu: + influxdb_cloud_ref: + name: top + parent: built-in-selectors +weight: 501 +--- + +The `top()` function sorts a table by columns and keeps only the top `n` records. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +top(n:10, columns: ["_value"]) +``` + +{{% warn %}} +#### Empty tables +`top()` drops empty tables. +{{% /warn %}} + +## Parameters + +### n +Number of records to return. + +_**Data type:** Integer_ + +### columns +List of columns by which to sort. +Sort precedence is determined by list order (left to right). +Default is `["_value"]`. + +_**Data type:** Array of strings_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> top(n:10) +``` + +## Function definition +```js +// _sortLimit is a helper function, which sorts and limits a table. +_sortLimit = (n, desc, columns=["_value"], tables=<-) => + tables + |> sort(columns:columns, desc:desc) + |> limit(n:n) + +top = (n, columns=["_value"], tables=<-) => _sortLimit(n:n, columns:columns, desc:true) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/unique.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/unique.md new file mode 100644 index 000000000..ebdcb1466 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/unique.md @@ -0,0 +1,43 @@ +--- +title: unique() function +description: The `unique()` function returns all records containing unique values in a specified column. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/selectors/unique + - /influxdb/cloud/reference/flux/functions/built-in/transformations/selectors/unique/ +menu: + influxdb_cloud_ref: + name: unique + parent: built-in-selectors +weight: 501 +--- + +The `unique()` function returns all records containing unique values in a specified column. +Group keys, record columns, and values are **not** modified. + +_**Function type:** Selector_ +_**Output data type:** Record_ + +```js +unique(column: "_value") +``` + +{{% warn %}} +#### Empty tables +`unique()` drops empty tables. +{{% /warn %}} + +## Parameters + +### column +The column searched for unique values. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples +```js +from("example-bucket") + |> range(start: -15m) + |> filter(fn: (r) => r._measurement == "syslog") + |> unique(column: "message") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/set.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/set.md new file mode 100644 index 000000000..6276ec446 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/set.md @@ -0,0 +1,41 @@ +--- +title: set() function +description: The `set()` function assigns a static value to each record in the input table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/set + - /influxdb/cloud/reference/flux/functions/built-in/transformations/set/ +menu: + influxdb_cloud_ref: + name: set + parent: built-in-transformations +weight: 402 +--- + +The `set()` function assigns a static value to each record in the input table. +The key may modify an existing column or add a new column to the tables. +If the modified column is part of the group key, the output tables are regrouped as needed. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +set(key: "myKey",value: "myValue") +``` + +## Parameters + +### key +The label of the column to modify or set. + +_**Data type:** String_ + +### value +The string value to set. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "example-bucket") + |> set(key: "host", value: "prod-node-1") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/sort.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/sort.md new file mode 100644 index 000000000..6580eac0c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/sort.md @@ -0,0 +1,56 @@ +--- +title: sort() function +description: The `sort()` function orders the records within each table. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/sort + - /influxdb/cloud/reference/flux/functions/built-in/transformations/sort/ +menu: + influxdb_cloud_ref: + name: sort + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/sort-limit/ +--- + +The `sort()` function orders the records within each table. +One output table is produced for each input table. +The output tables will have the same schema as their corresponding input tables. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +#### Sorting with null values +When sorting, `null` values will always be first. +When `desc: false`, nulls are less than every other value. +When `desc: true`, nulls are greater than every value. + +```js +sort(columns: ["_value"], desc: false) +``` + +## Parameters + +### columns +List of columns by which to sort. +Sort precedence is determined by list order (left to right). +Default is `["_value"]`. + +_**Data type:** Array of strings_ + +### desc +Sort results in descending order. +Default is `false`. + +_**Data type:** Boolean_ + +## Examples +```js +from(bucket:"example-bucket") + |> range(start:-12h) + |> filter(fn: (r) => + r._measurement == "system" and + r._field == "uptime" + ) + |> sort(columns:["region", "host", "_value"]) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/statecount.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/statecount.md new file mode 100644 index 000000000..53e584153 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/statecount.md @@ -0,0 +1,63 @@ +--- +title: stateCount() function +description: The `stateCount()` function computes the number of consecutive records in a given state. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/statecount + - /influxdb/cloud/reference/flux/functions/built-in/transformations/statecount/ +menu: + influxdb_cloud_ref: + name: stateCount + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/monitor-states/ +--- + +The `stateCount()` function computes the number of consecutive records in a given state. +The state is defined via the function `fn`. +For each consecutive point that evaluates as `true`, the state count is incremented. +When a point evaluates as `false`, the state count is reset. +The state count is added as an additional column to each record. + +_**Function type:** Transformation_ +_**Output data type:** Integer_ + +```js +stateCount(fn: (r) => r._field == "state", column: "stateCount") +``` + +_If the expression generates an error during evaluation, the point is discarded +and does not affect the state count._ + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### fn + +A single argument function that evaluates true or false to identify the state of the record. +Records are passed to the function. +Those that evaluate to `true` increment the state count. +Those that evaluate to `false` reset the state count. + +_**Data type:** Function_ + +### column + +The name of the column added to each record that contains the incremented state count. + +_**Data type:** String_ + +## Examples + +```js +from("monitor/autogen") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "http") + |> stateCount( + fn: (r) => r.http_response_code == "500", + column: "server_error_count" + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stateduration.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stateduration.md new file mode 100644 index 000000000..911c8425e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stateduration.md @@ -0,0 +1,78 @@ +--- +title: stateDuration() function +description: The `stateDuration()` function computes the duration of a given state. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/stateduration + - /influxdb/cloud/reference/flux/functions/built-in/transformations/stateduration/ +menu: + influxdb_cloud_ref: + name: stateDuration + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/monitor-states/ + - /influxdb/cloud/reference/flux/stdlib/contrib/events/duration/ +--- + +The `stateDuration()` function computes the duration of a given state. +The state is defined via the function `fn`. +For each consecutive point for that evaluates as `true`, the state duration will be +incremented by the duration between points. +When a point evaluates as `false`, the state duration is reset. +The state duration is added as an additional column to each record. + +_**Function type:** Transformation_ +_**Output data type:** Duration_ + +{{% note %}} +As the first point in the given state has no previous point, its +state duration will be 0. +{{% /note %}} + +```js +stateDuration(fn: (r) => r._measurement == "state", column: "stateDuration", unit: 1s) +``` + +_If the expression generates an error during evaluation, the point is discarded, +and does not affect the state duration._ + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### fn + +A single argument function that evaluates true or false to identify the state of the record. +Records are passed to the function. +Those that evaluate to `true` increment the state duration. +Those that evaluate to `false` reset the state duration. + +_**Data type:** Function_ + +### column + +The name of the column added to each record that contains the state duration. + +_**Data type:** String_ + +### unit + +The unit of time in which the state duration is incremented. +For example: `1s`, `1m`, `1h`, etc. +The default unit is one second (`1s`). + +_**Data type:** Duration_ + +## Examples + +```js +from("monitor/autogen") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "http") + |> stateDuration( + fn: (r) => r.http_response_code == "500", + column: "server_error_duration" + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/_index.md new file mode 100644 index 000000000..3cd22a890 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/_index.md @@ -0,0 +1,57 @@ +--- +title: Flux stream and table functions +list_title: Stream and table functions +seotitle: Flux built-in stream and table functions +description: > + Use stream and table functions to extract a table from a stream of tables and access its + columns and records. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/stream-table/ +weight: 401 +menu: + influxdb_cloud_ref: + name: Stream & table + parent: built-in-transformations +influxdb/v2.0/tags: [transformations, built-in, functions, stream, table] +related: + - /influxdb/cloud/query-data/flux/scalar-values/ +--- + +Use stream and table functions to extract a table from a stream of tables and access its +columns and records. + +{{< children type="functions" >}} + +### Example stream and table functions + +##### Recommended usage +```js +data = from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn:(r) => r._measurement == "cpu") + +// Extract the "_value" column from the table +data + |> findColumn(fn: (key) => key._field == "usage_idle", column: "_value") + +// Extract the first record from the table +data + |> findRecord(fn: (key) => key._field == "usage_idle", idx: 0) + +``` + +##### Alternate usage +```js +data = from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn:(r) => r._measurement == "cpu") + +// Extract the first available table for which "_field" is equal to "usage_idle" +t = data |> tableFind(fn: (key) => key._field == "usage_idle") + +// Extract the "_value" column from the table +values = t |> getColumn(column: "_value") + +// Extract the first record from the table +r0 = t |> getRecord(idx: 0) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/findcolumn.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/findcolumn.md new file mode 100644 index 000000000..33c5f7738 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/findcolumn.md @@ -0,0 +1,54 @@ +--- +title: findColumn() function +description: > + The `findColumn()` function returns an array of values in a specified column from the + first table in a stream of tables where group key values match the specified predicate. +menu: + influxdb_cloud_ref: + name: findColumn + parent: Stream & table +weight: 501 +related: + - /influxdb/cloud/query-data/flux/scalar-values/ +--- + +The `findColumn()` function returns an array of values in a specified column from the +first table in a stream of tables where the group key values match the specified predicate. +The function returns an empty array if no table is found or if the column label +is not present in the set of columns. + +_**Function type:** Stream and table_ + +```js +findColumn( + fn: (key) => key._field == "fieldName") + column: "_value" +) +``` + +## Parameters + +### fn +A predicate function for matching keys in a table's group key. +Expects a `key` argument that represents a group key in the input stream. + +_**Data type:** Function_ + +### column +Name of the column to extract. + +_**Data type:** String_ + +## Example +```js +vs = from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn:(r) => r._measurement == "cpu") + |> findColumn( + fn: (key) => key._field == "usage_idle", + column: "_value" + ) + +// Use column values +x = vs[0] + vs[1] +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/findrecord.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/findrecord.md new file mode 100644 index 000000000..86794c9e3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/findrecord.md @@ -0,0 +1,54 @@ +--- +title: findRecord() function +description: > + The `findRecord()` function returns a record at a specified index from the first + table in a stream of tables where the group key values match the specified predicate. +menu: + influxdb_cloud_ref: + name: findRecord + parent: Stream & table +weight: 501 +related: + - /influxdb/cloud/query-data/flux/scalar-values/ +--- + +The `findRecord()` function returns a record at a specified index from the first +table in a stream of tables where the group key values match the specified predicate. +The function returns an empty record if no table is found or if the index is out of bounds. + +_**Function type:** Stream and table_ + +```js +findRecord( + fn: (key) => key._field == "fieldName", + idx: 0 +) +``` + +## Parameters + +### fn +A predicate function for matching keys in a table's group key. +Expects a `key` argument that represents a group key in the input stream. + +_**Data type:** Function_ + +### idx +Index of the record to extract. + +_**Data type:** Integer_ + +## Example +```js +r0 = from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn:(r) => r._measurement == "cpu") + |> tableFind() + |> findRecord( + fn: (key) => key._field == "usage_idle", + idx: 0 + ) + +// Use record values +x = r0._field + "--" + r0._measurement +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/getcolumn.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/getcolumn.md new file mode 100644 index 000000000..8bbfd2785 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/getcolumn.md @@ -0,0 +1,50 @@ +--- +title: getColumn() function +description: > + The `getColumn()` function extracts a column from a table given its label. + If the label is not present in the set of columns, the function errors. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/stream-table/getcolumn/ +menu: + influxdb_cloud_ref: + name: getColumn + parent: Stream & table +weight: 501 +related: + - /influxdb/cloud/query-data/flux/scalar-values/ +--- + +The `getColumn()` function extracts a column from a table given its label. +If the label is not present in the set of columns, the function errors. + +_**Function type:** Stream and table_ + +```js +getColumn(column: "_value") +``` + +{{% note %}} +#### Use tableFind() to extract a single table +`getColumn()` requires a single table as input. +Use [`tableFind()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/tablefind/) +to extract a single table from a stream of tables. +{{% /note %}} + +## Parameters + +### column +Name of the column to extract. + +_**Data type:** String_ + +## Example +```js +vs = from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn:(r) => r._measurement == "cpu") + |> tableFind(fn: (key) => key._field == "usage_idle") + |> getColumn(column: "_value") + +// Use column values +x = vs[0] + vs[1] +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/getrecord.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/getrecord.md new file mode 100644 index 000000000..10bdd9be5 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/getrecord.md @@ -0,0 +1,50 @@ +--- +title: getRecord() function +description: > + The `getRecord()` function extracts a record from a table given its index. + If the index is out of bounds, the function errors. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/stream-table/getrecord/ +menu: + influxdb_cloud_ref: + name: getRecord + parent: Stream & table +weight: 501 +related: + - /influxdb/cloud/query-data/flux/scalar-values/ +--- + +The `getRecord()` function extracts a record from a table given the record's index. +If the index is out of bounds, the function errors. + +_**Function type:** Stream and table_ + +```js +getRecord(idx: 0) +``` + +{{% note %}} +#### Use tableFind() to extract a single table +`getRecord()` requires a single table as input. +Use [`tableFind()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/tablefind/) +to extract a single table from a stream of tables. +{{% /note %}} + +## Parameters + +### idx +Index of the record to extract. + +_**Data type:** Integer_ + +## Example +```js +r0 = from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn:(r) => r._measurement == "cpu") + |> tableFind(fn: (key) => key._field == "usage_idle") + |> getRecord(idx: 0) + +// Use record values +x = r0._field + "--" + r0._measurement +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/tablefind.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/tablefind.md new file mode 100644 index 000000000..56eb08a7e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/tablefind.md @@ -0,0 +1,62 @@ +--- +title: tableFind() function +description: > + The `tableFind()` function extracts the first table in a stream of tables whose + group key values match a predicate. If no table is found, the function errors. +aliases: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/tablefind/ +menu: + influxdb_cloud_ref: + name: tableFind + parent: Stream & table +weight: 501 +related: + - /influxdb/cloud/query-data/flux/scalar-values/ +--- + +The `tableFind()` function extracts the first table in a stream of tables whose +group key values match a predicate. If no table is found, the function errors. + +_**Function type:** Stream and table_ + +```js +tableFind(fn: (key) => key._field == "fieldName") +``` + +## Parameters + +{{% note %}} +Make sure `fn` parameter names match each specified parameter. +To learn why, see [Match parameter names](/influxdb/cloud/reference/flux/language/data-model/#match-parameter-names). +{{% /note %}} + +### fn + +A predicate function for matching keys in a table's group key. +`tableFind` returns the first table that resolves as `true`. +Expects a `key` argument that represents a group key in the input stream. + +_**Data type:** Function_ + +##### Example fn function + +```js +(key) => key._field == "fieldName" +``` + +## Example + +```js +t = from(bucket:"example-bucket") + |> range(start: -5m) + |> filter(fn:(r) => r._measurement == "cpu") + |> tableFind(fn: (key) => key._field == "usage_idle") + +// t represents the first table in a stream whose group key +// contains "_field" with a value of "usage_idle". +``` + +{{% note %}} +You can use `t` from the example above as input for [`getColumn()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/getcolumn/) +and [`getRecord()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/stream-table/getrecord/). +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tail.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tail.md new file mode 100644 index 000000000..299655327 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tail.md @@ -0,0 +1,49 @@ +--- +title: tail() function +description: The `tail()` function limits each output table to the last `n` records. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/tail/ +menu: + influxdb_cloud_ref: + name: tail + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/limit/ +--- + +The `tail()` function limits each output table to the last [`n`](#n) records. +The function produces one output table for each input table. +Each output table contains the last `n` records before the [`offset`](#offset). +If the input table has less than `offset + n` records, `tail()` outputs all records before the `offset`. + +_**Function type:** Filter_ + +```js +tail( + n:10, + offset: 0 +) +``` + +## Parameters + +### n +The maximum number of records to output. + +_**Data type:** Integer_ + +### offset +The number of records to skip at the end of a table table before limiting to `n`. +Defaults to `0`. + +_**Data type:** Integer_ + +## Examples + +##### Output the last ten records in each table +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> tail(n:10) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage.md new file mode 100644 index 000000000..a7eb31cf8 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage.md @@ -0,0 +1,86 @@ +--- +title: timedMovingAverage() function +description: > + The `timedMovingAverage()` function calculates the mean of values in a defined time + range at a specified frequency. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/timedmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/timedmovingaverage/ +menu: + influxdb_cloud_ref: + name: timedMovingAverage + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleema/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#moving-average, InfluxQL MOVING_AVERAGE() +--- + +The `timedMovingAverage()` function calculates the mean of values in a defined time +range at a specified frequency. + +_**Function type:** Transformation_ + +```js +timedMovingAverage( + every: 1d, + period: 5d, + column="_value" +) +``` + +## Parameters + +### every +The frequency of time windows. + +_**Data type:** Duration_ + +### period +The length of each averaged time window. +_A negative duration indicates start and stop boundaries are reversed._ + +_**Data type:** Duration_ + +### column +The column used to compute the moving average. +Defaults to `"_value"`. + +_**Data type:** String_ + +## Examples + +###### Calculate a seven day moving average every day +```js +from(bucket: "example-bucket"): + |> range(start: -7y) + |> filter(fn: (r) => + r._measurement == "financial" and + r._field == "closing_price" + ) + |> timedMovingAverage(every: 1y, period: 5y) +``` + +###### Calculate a five year moving average every year +```js +from(bucket: "example-bucket"): + |> range(start: -50d) + |> filter(fn: (r) => + r._measurement == "financial" and + r._field == "closing_price" + ) + |> timedMovingAverage(every: 1d, period: 7d) +``` + +## Function definition +```js +timedMovingAverage = (every, period, column="_value", tables=<-) => + tables + |> window(every: every, period: period) + |> mean(column:column) + |> duplicate(column: "_stop", as: "_time") + |> window(every: inf) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/timeshift.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/timeshift.md new file mode 100644 index 000000000..ce9dd3390 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/timeshift.md @@ -0,0 +1,53 @@ +--- +title: timeShift() function +description: The `timeShift()` function adds a fixed duration to time columns. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/shift + - /influxdb/cloud/reference/flux/functions/built-in/transformations/shift + - /influxdb/cloud/reference/flux/functions/built-in/transformations/timeshift/ +menu: + influxdb_cloud_ref: + name: timeShift + parent: built-in-transformations +weight: 402 +--- + +The `timeShift()` function adds a fixed duration to time columns. +The output table schema is the same as the input table. +If the time is `null`, the time will continue to be `null`. + +_**Function type:** Transformation_ + +```js +timeShift(duration: 10h, columns: ["_start", "_stop", "_time"]) +``` + +## Parameters + +### duration +The amount of time to add to each time value. +May be a negative duration. + +_**Data type:** Duration_ + +### columns +The list of all columns to be shifted. +Defaults to `["_start", "_stop", "_time"]`. + +_**Data type:** Array of strings_ + +## Examples + +###### Shift forward in time +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> timeShift(duration: 12h) +``` + +###### Shift backward in time +```js +from(bucket: "example-bucket") + |> range(start: -5m) + |> timeShift(duration: -12h) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleema.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleema.md new file mode 100644 index 000000000..a28a8254e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleema.md @@ -0,0 +1,71 @@ +--- +title: tripleEMA() function +description: > + The `tripleEMA()` function calculates the exponential moving average of values + grouped into `n` number of points, giving more weight to recent data with less lag + than `exponentialMovingAverage()` and `doubleEMA()`. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/tripleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/tripleema/ +menu: + influxdb_cloud_ref: + name: tripleEMA + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#triple-exponential-moving-average, InfluxQL TRIPLE_EXPONENTIAL_MOVING_AVERAGE() +--- + +The `tripleEMA()` function calculates the exponential moving average of values in +the `_value` column grouped into `n` number of points, giving more weight to recent +data with less lag than +[`exponentialMovingAverage()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/) +and [`doubleEMA()`](http://localhost:1313/influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema/). + +_**Function type:** Transformation_ + +```js +tripleEMA(n: 5) +``` + +##### Triple exponential moving average rules +- A triple exponential moving average is defined as `tripleEMA = (3 * EMA_1) - (3 * EMA_2) + EMA_3`. + - `EMA_1` is the exponential moving average of the original data. + - `EMA_2` is the exponential moving average of `EMA_1`. + - `EMA_3` is the exponential moving average of `EMA_2`. +- A true triple exponential moving average requires at least requires at least `3 * n - 2` values. + If not enough values exist to calculate the triple EMA, it returns a `NaN` value. +- `tripleEMA()` inherits all [exponential moving average rules](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/#exponential-moving-average-rules). + +## Parameters + +### n +The number of points to average. + +_**Data type:** Integer_ + +## Examples + +#### Calculate a five point triple exponential moving average +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> tripleEMA(n: 5) +``` + +## Function definition +```js +tripleEMA = (n, tables=<-) => + tables + |> exponentialMovingAverage(n:n) + |> duplicate(column:"_value", as:"ema1") + |> exponentialMovingAverage(n:n) + |> duplicate(column:"_value", as:"ema2") + |> exponentialMovingAverage(n:n) + |> map(fn: (r) => ({r with _value: 3.0 * r.ema1 - 3.0 * r.ema2 + r._value})) + |> drop(columns: ["ema1", "ema2"]) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleexponentialderivative.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleexponentialderivative.md new file mode 100644 index 000000000..edd1c247d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleexponentialderivative.md @@ -0,0 +1,70 @@ +--- +title: tripleExponentialDerivative() function +description: > + The `tripleExponentialDerivative()` function calculates a triple exponential + derivative (TRIX) of input tables using `n` points. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/aggregates/tripleexponentialderivative/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/tripleexponentialderivative/ +menu: + influxdb_cloud_ref: + name: tripleExponentialDerivative + parent: built-in-transformations +weight: 402 +influxdb/v2.0/tags: [technical analysis] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/movingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/doubleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/tripleema/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/timedmovingaverage/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/ + - /{{< latest "influxdb" "v1" >}}/query_language/functions/#triple-exponential-derivative, InfluxQL TRIPLE_EXPONENTIAL_DERIVATIVE() +--- + +The `tripleExponentialDerivative()` function calculates a triple exponential +derivative ([TRIX](https://en.wikipedia.org/wiki/Trix_(technical_analysis))) of +input tables using `n` points. + +_**Function type:** Transformation_ + +```js +tripleExponentialDerivative(n: 5) +``` + +Triple exponential derivative, commonly referred to as “TRIX,” is a momentum indicator and oscillator. +A triple exponential derivative uses the natural logarithm (log) of input data to +calculate a triple exponential moving average over the period of time. +The calculation prevents cycles shorter than the defined period from being considered by the indicator. +`tripleExponentialDerivative()` uses the time between `n` points to define the period. + +Triple exponential derivative oscillates around a zero line. +A positive momentum **oscillator** value indicates an overbought market; +a negative value indicates an oversold market. +A positive momentum **indicator** value indicates increasing momentum; +a negative value indicates decreasing momentum. + +##### Triple exponential moving average rules +- A triple exponential derivative is defined as: + - `TRIX[i] = ((EMA3[i] / EMA3[i - 1]) - 1) * 100`: + - `EMA_3 = EMA(EMA(EMA(data)))` +- If there are not enough values to calculate a triple exponential derivative, + the output `_value` is `NaN`; all other columns are the same as the _last_ record of the input table. +- The function behaves the same way as the [`exponentialMovingAverage()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/exponentialmovingaverage/) function: + - The function does not include `null` values in the calculation. + - The function acts only on the `_value` column. + +## Parameters + +### n +The number of points to use in the calculation. + +_**Data type:** Integer_ + +## Examples + +#### Calculate a five point triple exponential derivative +```js +from(bucket: "example-bucket"): + |> range(start: -12h) + |> tripleExponentialDerivative(n: 5) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/truncatetimecolumn.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/truncatetimecolumn.md new file mode 100644 index 000000000..1567377e6 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/truncatetimecolumn.md @@ -0,0 +1,55 @@ +--- +title: truncateTimeColumn() function +description: > + The `truncateTimeColumn()` function truncates all input table `_time` values to a specified unit. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/truncatetimecolumn/ +menu: + influxdb_cloud_ref: + name: truncateTimeColumn + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/date/truncate/ +--- + +The `truncateTimeColumn()` function truncates all input table `_time` values to a specified unit. + +_**Function type:** Transformation_ + +```js +truncateTimeColumn(unit: 1s) +``` + +## Parameters + +### unit +The unit of time to truncate to. + +_**Data type:** Duration_ + +{{% note %}} +Only use `1` and the unit of time to specify the `unit`. +For example: `1s`, `1m`, `1h`. +{{% /note %}} + +## Examples + +##### Truncate all time values to seconds +```js +from(bucket:"example-bucket") + |> range(start:-1h) + |> truncateTimeColumn(unit: 1s) +``` + +## Function definition +```js +import "date" + +truncateTimeColumn = (unit, tables=<-) => + tables + |> map(fn: (r) => ({ + r with _time: date.truncate(t: r._time, unit:unit) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/_index.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/_index.md new file mode 100644 index 000000000..ff3786c3e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/_index.md @@ -0,0 +1,20 @@ +--- +title: Flux built-in type conversion functions +list_title: Built-in type conversion functions +description: Flux's built-in built-in type conversion functions convert columns of the input table into a specific data type. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/type-conversions + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/ +menu: + influxdb_cloud_ref: + parent: built-in-transformations + name: Type conversions + identifier: built-in-type-conversions +weight: 401 +influxdb/v2.0/tags: [type-conversions, built-in, functions] +--- + +Flux's built-in type conversion functions convert columns of the input table into a specific data type. +The following type conversion functions are available: + +{{< children type="functions" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/bool.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/bool.md new file mode 100644 index 000000000..e00b4751d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/bool.md @@ -0,0 +1,35 @@ +--- +title: bool() function +description: The `bool()` function converts a single value to a boolean. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/bool/ +menu: + influxdb_cloud_ref: + name: bool + parent: built-in-type-conversions +weight: 502 +--- + +The `bool()` function converts a single value to a boolean. + +_**Function type:** Type conversion_ +_**Output data type:** Boolean_ + +```js +bool(v: "true") +``` + +## Parameters + +### v +The value to convert. + +_**Data type:** Float | Integer | String | Uinteger_ + +## Examples +```js +from(bucket: "sensor-data") + |> range(start: -1m) + |> filter(fn:(r) => r._measurement == "system" ) + |> map(fn:(r) => ({ r with responsive: bool(v: r.responsive) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/bytes.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/bytes.md new file mode 100644 index 000000000..e5f5d8913 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/bytes.md @@ -0,0 +1,34 @@ +--- +title: bytes() function +description: The `bytes()` function converts a single value to bytes. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/bytes/ +menu: + influxdb_cloud_ref: + name: bytes + parent: built-in-type-conversions +weight: 502 +--- + +The `bytes()` function converts a single value to bytes. + +_**Function type:** Type conversion_ +_**Output data type:** Bytes_ + +```js +bytes(v: "1m") +``` + +## Parameters + +### v +The value to convert. + +_**Data type:** String_ + +## Examples +```js +from(bucket: "sensor-data") + |> range(start: -1m) + |> map(fn:(r) => ({ r with _value: bytes(v: r._value) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/duration.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/duration.md new file mode 100644 index 000000000..28ed2c89f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/duration.md @@ -0,0 +1,46 @@ +--- +title: duration() function +description: The `duration()` function converts a single value to a duration. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/duration/ +menu: + influxdb_cloud_ref: + name: duration + parent: built-in-type-conversions +weight: 502 +--- + +The `duration()` function converts a single value to a duration. + +_**Function type:** Type conversion_ +_**Output data type:** Duration_ + +```js +duration(v: "1m") +``` + +## Parameters + +### v +The value to convert. + +_**Data type:** Integer | String | Uinteger_ + +{{% note %}} +`duration()` assumes **numeric** input values are **nanoseconds**. +**String** input values must use [duration literal representation](/influxdb/cloud/reference/flux/language/lexical-elements/#duration-literals). +{{% /note %}} + +## Examples + +{{% note %}} +Flux does not support duration column types. +The example below converts an integer to a duration and stores the value as a string. +{{% /note %}} + +```js +from(bucket: "sensor-data") + |> range(start: -1m) + |> filter(fn:(r) => r._measurement == "system" ) + |> map(fn:(r) => ({ r with uptime: string(v: duration(v: r.uptime)) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/float.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/float.md new file mode 100644 index 000000000..f4f3edd95 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/float.md @@ -0,0 +1,35 @@ +--- +title: float() function +description: The `float()` function converts a single value to a float. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/float/ +menu: + influxdb_cloud_ref: + name: float + parent: built-in-type-conversions +weight: 502 +--- + +The `float()` function converts a single value to a float. + +_**Function type:** Type conversion_ +_**Output data type:** Float_ + +```js +float(v: "3.14") +``` + +## Parameters + +### v +The value to convert. + +_**Data type:** Boolean | Integer | Numeric String | Uinteger_ + +## Examples +```js +from(bucket: "sensor-data") + |> range(start: -1m) + |> filter(fn:(r) => r._measurement == "camera" ) + |> map(fn:(r) => ({ r with aperature: float(v: r.aperature) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/int.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/int.md new file mode 100644 index 000000000..57c4c9f98 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/int.md @@ -0,0 +1,42 @@ +--- +title: int() function +description: The `int()` function converts a single value to an integer. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/int/ +menu: + influxdb_cloud_ref: + name: int + parent: built-in-type-conversions +weight: 502 +--- + +The `int()` function converts a single value to an integer. + +_**Function type:** Type conversion_ +_**Output data type:** Integer_ + +```js +int(v: "4") +``` + +## Parameters + +### v +The value to convert. + +_**Data type:** Boolean | Duration | Float | Numeric String | Time | Uinteger_ + +For duration and time values, `int()` returns the following: + +| Input type | Returned value | +|:---------- |:-------------- | +| Duration | The number of nanoseconds in the specified duration | +| Time | A nanosecond epoch timestamp | + +## Examples +```js +from(bucket: "sensor-data") + |> range(start: -1m) + |> filter(fn:(r) => r._measurement == "camera" ) + |> map(fn:(r) => ({ r with exposures: int(v: r.exposures) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/string.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/string.md new file mode 100644 index 000000000..def69382e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/string.md @@ -0,0 +1,35 @@ +--- +title: string() function +description: The `string()` function converts a single value to a string. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/string/ +menu: + influxdb_cloud_ref: + name: string + parent: built-in-type-conversions +weight: 502 +--- + +The `string()` function converts a single value to a string. + +_**Function type:** Type conversion_ +_**Output data type:** String_ + +```js +string(v: 123456789) +``` + +## Parameters + +### v +The value to convert. + +_**Data type:** Boolean | Bytes | Duration | Float | Integer | Time | Uinteger_ + +## Examples +```js +from(bucket: "sensor-data") + |> range(start: -1m) + |> filter(fn:(r) => r._measurement == "system" ) + |> map(fn:(r) => ({ r with model_number: string(v: r.model_number) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/time.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/time.md new file mode 100644 index 000000000..d9759ab38 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/time.md @@ -0,0 +1,39 @@ +--- +title: time() function +description: The `time()` function converts a single value to a time. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/time/ +menu: + influxdb_cloud_ref: + name: time + parent: built-in-type-conversions +weight: 502 +--- + +The `time()` function converts a single value to a time. + +_**Function type:** Type conversion_ +_**Output data type:** Time_ + +```js +time(v: "2016-06-13T17:43:50.1004002Z") +``` + +## Parameters + +### v +The value to convert. + +_**Data type:** Integer | String | Uinteger_ + +{{% note %}} +`time()` assumes all numeric input values are nanosecond epoch timestamps. +{{% /note %}} + +## Examples +```js +from(bucket: "sensor-data") + |> range(start: -1m) + |> filter(fn:(r) => r._measurement == "system" ) + |> map(fn:(r) => ({ r with timestamp: time(v: r.timestamp) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tobool.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tobool.md new file mode 100644 index 000000000..41fb3e756 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tobool.md @@ -0,0 +1,49 @@ +--- +title: toBool() function +description: The `toBool()` function converts all values in the `_value` column to booleans. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/type-conversions/tobool + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/tobool/ +menu: + influxdb_cloud_ref: + name: toBool + parent: built-in-type-conversions +weight: 501 +--- + +The `toBool()` function converts all values in the `_value` column to booleans. + +_**Function type:** Type conversion_ + +```js +toBool() +``` + +_**Supported data types:** Float | Integer | String | Uinteger_ + +{{% note %}} +To convert values in a column other than `_value`, define a custom function +patterned after the [function definition](#function-definition), +but replace `_value` with your desired column. +{{% /note %}} + +## Examples +```js +from(bucket: "telegraf") + |> filter(fn:(r) => + r._measurement == "mem" and + r._field == "used" + ) + |> toBool() +``` + +## Function definition +```js +toBool = (tables=<-) => + tables + |> map(fn:(r) => ({ r with _value: bool(v: r._value) })) +``` + +_**Used functions:** +[map()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map), +[bool()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/bool)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/toduration.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/toduration.md new file mode 100644 index 000000000..8df3626aa --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/toduration.md @@ -0,0 +1,58 @@ +--- +title: toDuration() function +description: The `toDuration()` function converts all values in the `_value` column to durations. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/type-conversions/toduration + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/toduration/ +menu: + influxdb_cloud_ref: + name: toDuration + parent: built-in-type-conversions +weight: 501 +--- + +{{% warn %}} +**`toDuration()` was removed in Flux 0.37.** +{{% /warn %}} + +The `toDuration()` function converts all values in the `_value` column to durations. + +_**Function type:** Type conversion_ + +```js +toDuration() +``` + +_**Supported data types:** Integer | String | Uinteger_ + +{{% note %}} +`duration()` assumes **numeric** input values are **nanoseconds**. +**String** input values must use [duration literal representation](#/v2.0/reference/flux/language/lexical-elements/#duration-literals). +{{% /note %}} + +{{% note %}} +To convert values in a column other than `_value`, define a custom function +patterned after the [function definition](#function-definition), +but replace `_value` with your desired column. +{{% /note %}} + +## Examples +```js +from(bucket: "telegraf") + |> filter(fn:(r) => + r._measurement == "mem" and + r._field == "used" + ) + |> toDuration() +``` + +## Function definition +```js +toDuration = (tables=<-) => + tables + |> map(fn:(r) => ({ r with _value: duration(v: r._value) })) +``` + +_**Used functions:** +[map()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map), +[duration()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/duration)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tofloat.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tofloat.md new file mode 100644 index 000000000..506118450 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tofloat.md @@ -0,0 +1,49 @@ +--- +title: toFloat() function +description: The `toFloat()` function converts all values in the `_value` column to floats. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/type-conversions/tofloat + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/tofloat/ +menu: + influxdb_cloud_ref: + name: toFloat + parent: built-in-type-conversions +weight: 501 +--- + +The `toFloat()` function converts all values in the `_value` column to floats. + +_**Function type:** Type conversion_ + +```js +toFloat() +``` + +_**Supported data types:** Boolean | Integer | Numeric String | Uinteger_ + +{{% note %}} +To convert values in a column other than `_value`, define a custom function +patterned after the [function definition](#function-definition), +but replace `_value` with your desired column. +{{% /note %}} + +## Examples +```js +from(bucket: "telegraf") + |> filter(fn:(r) => + r._measurement == "mem" and + r._field == "used" + ) + |> toFloat() +``` + +## Function definition +```js +toFloat = (tables=<-) => + tables + |> map(fn:(r) => ({ r with _value: float(v: r._value) })) +``` + +_**Used functions:** +[map()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map), +[float()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/float)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/toint.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/toint.md new file mode 100644 index 000000000..a8ab2b200 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/toint.md @@ -0,0 +1,56 @@ +--- +title: toInt() function +description: The `toInt()` function converts all values in the `_value` column to integers. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/type-conversions/toint + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/toint/ +menu: + influxdb_cloud_ref: + name: toInt + parent: built-in-type-conversions +weight: 501 +--- + +The `toInt()` function converts all values in the `_value` column to integers. + +_**Function type:** Type conversion_ + +```js +toInt() +``` + +_**Supported data types:** Boolean | Duration | Float | Numeric String | Time | Uinteger_ + +For duration and time values, `toInt()` returns the following: + +| Input type | Returned value | +|:---------- |:-------------- | +| Duration | The number of nanoseconds in the specified duration | +| Time | A nanosecond epoch timestamp | + +{{% note %}} +To convert values in a column other than `_value`, define a custom function +patterned after the [function definition](#function-definition), +but replace `_value` with your desired column. +{{% /note %}} + +## Examples +```js +from(bucket: "telegraf") + |> filter(fn:(r) => + r._measurement == "mem" and + r._field == "used" + ) + |> toInt() +``` + +## Function definition +```js +toInt = (tables=<-) => + tables + |> map(fn:(r) => ({ r with _value: int(v: r._value) })) +``` + +_**Used functions:** +[map()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map), +[int()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/int)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tostring.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tostring.md new file mode 100644 index 000000000..5a89ba565 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/tostring.md @@ -0,0 +1,49 @@ +--- +title: toString() function +description: The `toString()` function converts all values in the `_value` column to strings. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/type-conversions/tostring + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/tostring/ +menu: + influxdb_cloud_ref: + name: toString + parent: built-in-type-conversions +weight: 501 +--- + +The `toString()` function converts all values in the `_value` column to strings. + +_**Function type:** Type conversion_ + +```js +toString() +``` + +_**Supported data types:** Boolean | Bytes | Duration | Float | Integer | Time | Uinteger_ + +{{% note %}} +To convert values in a column other than `_value`, define a custom function +patterned after the [function definition](#function-definition), +but replace `_value` with your desired column. +{{% /note %}} + +## Examples +```js +from(bucket: "telegraf") + |> filter(fn:(r) => + r._measurement == "mem" and + r._field == "used" + ) + |> toString() +``` + +## Function definition +```js +toString = (tables=<-) => + tables + |> map(fn:(r) => ({ r with _value: string(v: r._value) })) +``` + +_**Used functions:** +[map()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map), +[string()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/string)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/totime.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/totime.md new file mode 100644 index 000000000..3e6325e55 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/totime.md @@ -0,0 +1,53 @@ +--- +title: toTime() function +description: The `toTime()` function converts all values in the `_value` column to times. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/type-conversions/totime + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/totime/ +menu: + influxdb_cloud_ref: + name: toTime + parent: built-in-type-conversions +weight: 501 +--- + +The `toTime()` function converts all values in the `_value` column to times. + +_**Function type:** Type conversion_ + +```js +toTime() +``` + +_**Supported data types:** Integer | String | Uinteger_ + +{{% note %}} +`toTime()` assumes all numeric input values are nanosecond epoch timestamps. +{{% /note %}} + +{{% note %}} +To convert values in a column other than `_value`, define a custom function +patterned after the [function definition](#function-definition), +but replace `_value` with your desired column. +{{% /note %}} + +## Examples +```js +from(bucket: "telegraf") + |> filter(fn:(r) => + r._measurement == "mem" and + r._field == "used" + ) + |> toTime() +``` + +## Function definition +```js +toTime = (tables=<-) => + tables + |> map(fn:(r) => ({ r with _value: time(v:r._value) })) +``` + +_**Used functions:** +[map()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map), +[time()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/time)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/touint.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/touint.md new file mode 100644 index 000000000..47c7f18bd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/touint.md @@ -0,0 +1,56 @@ +--- +title: toUInt() function +description: The `toUInt()` function converts all values in the `_value` column to UIntegers. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/type-conversions/touint + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/touint/ +menu: + influxdb_cloud_ref: + name: toUInt + parent: built-in-type-conversions +weight: 501 +--- + +The `toUInt()` function converts all values in the `_value` column to UIntegers. + +_**Function type:** Type conversion_ + +```js +toUInt() +``` + +_**Supported data types:** Boolean | Duration | Float | Integer | Numeric String | Time_ + +For duration and time values, `toUint()` returns the following: + +| Input type | Returned value | +|:---------- |:-------------- | +| Duration | The number of nanoseconds in the specified duration | +| Time | A nanosecond epoch timestamp | + +{{% note %}} +To convert values in a column other than `_value`, define a custom function +patterned after the [function definition](#function-definition), +but replace `_value` with your desired column. +{{% /note %}} + +## Examples +```js +from(bucket: "telegraf") + |> filter(fn:(r) => + r._measurement == "mem" and + r._field == "used" + ) + |> toUInt() +``` + +## Function definition +```js +toUInt = (tables=<-) => + tables + |> map(fn:(r) => ({ r with _value: uint(v:r._value) })) +``` + +_**Used functions:** +[map()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map), +[uint()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/uint)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/uint.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/uint.md new file mode 100644 index 000000000..48409de8a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/type-conversions/uint.md @@ -0,0 +1,42 @@ +--- +title: uint() function +description: The `uint()` function converts a single value to a UInteger. +aliases: + - /influxdb/cloud/reference/flux/functions/built-in/transformations/type-conversions/uint/ +menu: + influxdb_cloud_ref: + name: uint + parent: built-in-type-conversions +weight: 502 +--- + +The `uint()` function converts a single value to a UInteger. + +_**Function type:** Type conversion_ +_**Output data type:** UInteger_ + +```js +uint(v: "4") +``` + +## Parameters + +### v +The value to convert. + +_**Data type:** Boolean | Duration | Float | Integer | Numeric String | Time_ + +For duration and time values, `uint()` returns the following: + +| Input type | Returned value | +|:---------- |:-------------- | +| Duration | The number of nanoseconds in the specified duration | +| Time | A nanosecond epoch timestamp | + +## Examples +```js +from(bucket: "sensor-data") + |> range(start: -1m) + |> filter(fn:(r) => r._measurement == "camera" ) + |> map(fn:(r) => ({ r with exposures: uint(v: r.exposures) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/union.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/union.md new file mode 100644 index 000000000..16ab4ebc3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/union.md @@ -0,0 +1,61 @@ +--- +title: union() function +description: The `union()` function concatenates two or more input streams into a single output stream. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/union + - /influxdb/cloud/reference/flux/functions/built-in/transformations/union/ +menu: + influxdb_cloud_ref: + name: union + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/join/ +--- + +The `union()` function concatenates two or more input streams into a single output stream. +In tables that have identical schemas and group keys, contents of the tables will be concatenated in the output stream. +The output schemas of the `union()` function is the union of all input schemas. + +`union()` does not preserve the sort order of the rows within tables. +A sort operation may be added if a specific sort order is needed. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +union(tables: [table1, table2]) +``` + +## Parameters + +### tables +Specifies the streams to union together. +There must be at least two streams. + +_**Data type:** Array of streams_ + +## Examples +```js +bucket1 = from(bucket: "example-bucket-1") + |> range(start: -5m) + |> filter(fn: (r) => r._field == "usage_guest" or r._field == "usage_guest_nice") + +bucket2 = from(bucket: "example-bucket-2") + |> range(start: -5m) + |> filter(fn: (r) => r._field == "usage_guest" or r._field == "usage_idle") + +union(tables: [bucket1, bucket2]) +``` + +## union() versus join() +`union()` merges separate streams of tables into a single stream of tables and +groups rows of data based on existing [group keys](/influxdb/cloud/reference/glossary/#group-key). +`union()` does not modify individual rows of data. +`join()` creates new rows based on common values in one or more specified columns. +Output rows also contain the differing values from each of the joined streams. + +Given two streams of tables, `t1` and `t2`, the results of `join()` and `union()` +are illustrated below: + +{{< svg "/static/svgs/join-vs-union.svg" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window.md b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window.md new file mode 100644 index 000000000..9e766c819 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window.md @@ -0,0 +1,111 @@ +--- +title: window() function +description: The `window()` function groups records based on a time value. +aliases: + - /influxdb/cloud/reference/flux/functions/transformations/window + - /influxdb/cloud/reference/flux/functions/built-in/transformations/window/ +menu: + influxdb_cloud_ref: + name: window + parent: built-in-transformations +weight: 402 +related: + - /influxdb/cloud/query-data/flux/window-aggregate/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/ + - /{{< latest "influxdb" "v1" >}}/query_language/data_exploration/#the-group-by-clause, InfluxQL – GROUP BY time() +--- + +The `window()` function groups records based on a time value. +New columns are added to uniquely identify each window. +Those columns are added to the group key of the output tables. + +A single input record will be placed into zero or more output tables, depending on the specific windowing function. + +By default the start boundary of a window will align with the Unix epoch (zero time) +modified by the offset of the `location` option. + +_**Function type:** Transformation_ +_**Output data type:** Record_ + +```js +window( + every: 5m, + period: 5m, + offset: 12h, + timeColumn: "_time", + startColumn: "_start", + stopColumn: "_stop", + createEmpty: false +) +``` + +## Parameters + +{{% note %}} +#### Calendar months and years +`every`, `period`, and `offset` support all [valid duration units](/influxdb/cloud/reference/flux/language/types/#duration-types), +including **calendar months (`1mo`)** and **years (`1y`)**. +{{% /note %}} + +### every +Duration of time between windows. +Defaults to `period` value. + +_**Data type:** Duration_ + +### period +Duration of the window. +Period is the length of each interval. +It can be negative, indicating the start and stop boundaries are reversed. +Defaults to `every` value. + +_**Data type:** Duration_ + +### offset +Offset is the duration by which to shift the window boundaries. +It can be negative, indicating that the offset goes backwards in time. +Defaults to 0, which will align window end boundaries with the `every` duration. + +_**Data type:** Duration_ + +### timeColumn +The column containing time. +Defaults to `"_time"`. + +_**Data type:** String_ + +### startColumn +The column containing the window start time. +Defaults to `"_start"`. + +_**Data type:** String_ + +### stopColumn +The column containing the window stop time. +Defaults to `"_stop"`. + +_**Data type:** String_ + +### createEmpty +Specifies whether empty tables should be created. +Defaults to `false`. + +_**Data type:** Boolean_ + +## Examples + +#### Window data into 10 minute intervals +```js +from(bucket:"example-bucket") + |> range(start: -12h) + |> window(every: 10m) + // ... +``` + +#### Window by calendar month +```js +from(bucket:"example-bucket") + |> range(start: -1y) + |> window(every: 1mo) + // ... +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/_index.md new file mode 100644 index 000000000..2d5513cfe --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/_index.md @@ -0,0 +1,16 @@ +--- +title: Flux user-contributed functions +list_title: User-contributed functions +description: > + User-contributed packages and functions are contributed and maintained by members of the InfluxDB and Flux communities. +menu: + influxdb_cloud_ref: + name: Contributed + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [contributed, functions, package] +--- + +User-contributed packages and functions are contributed and maintained by members of the InfluxDB and Flux communities. + +{{< children >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/_index.md new file mode 100644 index 000000000..6cc0dfab7 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/_index.md @@ -0,0 +1,28 @@ +--- +title: Flux Discord package +list_title: Discord package +description: > + The Flux Discord package provides functions for sending messages to Discord. + Import the `contrib/chobbs/discord` package. +menu: + influxdb_cloud_ref: + name: Discord + parent: Contributed +weight: 202 +influxdb/v2.0/tags: [functions, discord, package] +--- + +The Flux Discord package provides functions for sending messages to Discord. +Import the `contrib/chobbs/discord` package: + +```js +import "contrib/chobbs/discord" +``` + +{{< children type="functions" show="pages" >}} + +{{% note %}} +#### Package author and maintainer +**Github:** [@chobbs](https://github.com/chobbs) +**InfluxDB Slack:** [@craig](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/endpoint.md new file mode 100644 index 000000000..516362a36 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/endpoint.md @@ -0,0 +1,99 @@ +--- +title: discord.endpoint() function +description: > + The `discord.endpoint()` function sends a single message to a Discord channel using + a [Discord webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks&?page=3) + and data from table rows. +menu: + influxdb_cloud_ref: + name: discord.endpoint + parent: Discord +weight: 202 +--- + +The `discord.endpoint()` function sends a single message to a Discord channel using +a [Discord webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks&?page=3) +and data from table rows. + +_**Function type:** Output_ + +```js +import "contrib/chobbs/discord" + +discord.endpoint( + webhookToken: "mySuPerSecRetTokEn", + webhookID: "123456789", + username: "username", + avatar_url: "https://example.com/avatar_pic.jpg" +) +``` + +## Parameters + +### webhookToken +Discord [webhook token](https://discord.com/developers/docs/resources/webhook). + +_**Data type:** String_ + +### webhookID +Discord [webhook ID](https://discord.com/developers/docs/resources/webhook). + +_**Data type:** String_ + +### username +Override the Discord webhook's default username. + +_**Data type:** String_ + +### avatar_url +Override the Discord webhook's default avatar. + +_**Data type:** String_ + +## Usage +`discord.endpoint` is a factory function that outputs another function. +The output function requires a `mapFn` parameter. + +### mapFn +A function that builds the record used to generate the Discord webhook request. +Requires an `r` parameter. + +_**Data type:** Function_ + +`mapFn` accepts a table row (`r`) and returns a record that must include the +following field: + +- `content` + +_For more information, see the [`discord.send() content` parameter](/influxdb/cloud/reference/flux/stdlib/contrib/discord/send/#content)._ + +## Examples + +##### Send critical statuses to a Discord channel +```js +import "influxdata/influxdb/secrets" +import "contrib/chobbs/discord" + +discordToken = secrets.get(key: "DISCORD_TOKEN") +endpoint = telegram.endpoint( + webhookToken: discordToken, + webhookID: "123456789", + username: "critBot" +) + +crit_statuses = from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses" and status == "crit") + +crit_statuses + |> endpoint(mapFn: (r) => ({ + content: "The status is critical!", + }) + )() +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@chobbs](https://github.com/chobbs) +**InfluxDB Slack:** [@craig](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/send.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/send.md new file mode 100644 index 000000000..7d134a0cd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/discord/send.md @@ -0,0 +1,86 @@ +--- +title: discord.send() function +description: > + The `discord.send()` function sends a single message to a Discord channel using + a [Discord webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks&?page=3). +menu: + influxdb_cloud_ref: + name: discord.send + parent: Discord +weight: 202 +--- + +The `discord.send()` function sends a single message to a Discord channel using +a [Discord webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks&?page=3). + +_**Function type:** Output_ + +```js +import "contrib/chobbs/discord" + +discord.send( + webhookToken: "mySuPerSecRetTokEn", + webhookID: "123456789", + username: "username", + content: "This is an example message", + avatar_url: "https://example.com/avatar_pic.jpg" +) +``` + +## Parameters + +### webhookToken +Discord [webhook token](https://discord.com/developers/docs/resources/webhook). + +_**Data type:** String_ + +### webhookID +Discord [webhook ID](https://discord.com/developers/docs/resources/webhook). + +_**Data type:** String_ + +### username +Override the Discord webhook's default username. + +_**Data type:** String_ + +### content +Message to send to Discord (2000 character limit). + +_**Data type:** String_ + +### avatar_url +Override the Discord webhook's default avatar. + +_**Data type:** String_ + +## Examples + +##### Send the last reported status to Discord +```js +import "contrib/chobbs/discord" +import "influxdata/influxdb/secrets" + +token = secrets.get(key: "DISCORD_TOKEN") + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> findRecord(fn: (key) => true, idx: 0) + +discord.send( + webhookToken:token, + webhookID: "1234567890", + username: "chobbs", + content: "The current status is \"${lastReported.status}\".", + avatar_url: "https://staff-photos.net/pic.jpg" +) +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@chobbs](https://github.com/chobbs) +**InfluxDB Slack:** [@craig](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/events/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/events/_index.md new file mode 100644 index 000000000..1cf9bb4a9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/events/_index.md @@ -0,0 +1,29 @@ +--- +title: Flux Events package +list_title: Events package +description: > + The Flux Events package provides tools for analyzing event-based data. + Import the `contrib/tomhollingworth/events` package. +menu: + influxdb_cloud_ref: + name: Events + parent: Contributed + identifier: contrib-events +weight: 202 +influxdb/v2.0/tags: [functions, events, package] +--- + +The Flux Events package provides tools for analyzing event-based data. +Import the `contrib/tomhollingworth/events` package: + +```js +import "contrib/tomhollingworth/events" +``` + +{{< children type="functions" show="pages" >}} + +{{% note %}} +#### Package author and maintainer +**Github:** [@tomhollingworth](https://github.com/tomhollingworth) +**InfluxDB Slack:** [@Tom Hollingworth](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/events/duration.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/events/duration.md new file mode 100644 index 000000000..9aef2b81b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/events/duration.md @@ -0,0 +1,171 @@ +--- +title: events.duration() function +description: > + The `events.duration()` function calculates the duration of events. + The function determines the time between a record and the subsequent record and + associates the duration with the first record (start of the event). +menu: + influxdb_cloud_ref: + name: events.duration + parent: contrib-events +weight: 301 +influxdb/v2.0/tags: [functions, events, package] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/elapsed/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/stateduration/ +--- + +The `events.duration()` function calculates the duration of events. +The function determines the time between a record and the subsequent record and +associates the duration with the first record (start of the event). +To calculate the duration of the last event, the function compares the timestamp +of the final record to the timestamp in the [`stopColumn`](#stopcolumn) or the +specified [`stop`](#stop) time. + +```js +import "contrib/tomhollingworth/events" + +events.duration( + unit: 1ns, + columnName: "duration", + timeColumn: "_time", + stopColumn: "_stop", + stop: 2020-01-01T00:00:00Z +) +``` + +{{% note %}} +#### Similar functions +`events.duration()` is similar to `elapsed()` and `stateDuration()`, but differs +in important ways: + +- `elapsed()` drops the first record. `events.duration()` does not. +- `stateDuration()` calculates the total time spent in a state (determined by a + [predicate function](/influxdb/cloud/reference/glossary/#predicate-function)). + `events.duration()` returns the duration between all records and their subsequent records. + +For examples, see [below](#compared-to-similar-functions). +{{% /note %}} + +## Parameters + +### unit +Duration unit of the calculated state duration. +Default is `1ns` + +_**Data type:** Duration_ + +### columnName +Name of the result column. +Default is `"duration"`. + +_**Data type:** String_ + +### timeColumn +Name of the time column. +Default is `"_time"`. + +_**Data type:** String_ + +### stopColumn +Name of the stop column. +Default is `"_stop"`. + +_**Data type:** String_ + +### stop +The latest time to use when calculating results. +If provided, `stop` overrides the time value in the [`stopColumn`](#stopcolumn). + +_**Data type:** Time_ + +## Examples + +##### Calculate the duration of states +```js +import "contrib/tomhollingworth/events" + +data + |> events.duration( + unit: 1m, + stop: 2020-01-02T00:00:00Z + ) +``` + +{{< flex >}} +{{% flex-content %}} +##### Input +| _time | state | +|:----- | -----:| +| 2020-01-01T00:00:00Z | ok | +| 2020-01-01T00:12:34Z | warn | +| 2020-01-01T00:25:01Z | ok | +| 2020-01-01T16:07:55Z | crit | +| 2020-01-01T16:54:21Z | warn | +| 2020-01-01T18:20:45Z | ok | +{{% /flex-content %}} +{{% flex-content %}} +##### Output +| _time | state | duration | +|:----- |:-----:| --------:| +| 2020-01-01T00:00:00Z | ok | 12 | +| 2020-01-01T00:12:34Z | warn | 12 | +| 2020-01-01T00:25:01Z | ok | 942 | +| 2020-01-01T16:07:55Z | crit | 46 | +| 2020-01-01T16:54:21Z | warn | 86 | +| 2020-01-01T18:20:45Z | ok | 339 | +{{% /flex-content %}} +{{< /flex >}} + +## Compared to similar functions +The example below includes output values of `events.duration()`, `elapsed()`, and +`stateDuration()` related to the `_time` and `state` values of input data. + +{{< flex >}} +{{% flex-content %}} +##### Input +| _time | state | +|:----- | -----:| +| 2020-01-01T00:00:00Z | ok | +| 2020-01-01T00:12:34Z | warn | +| 2020-01-01T00:25:01Z | ok | +| 2020-01-01T16:07:55Z | crit | +| 2020-01-01T16:54:21Z | warn | +| 2020-01-01T18:20:45Z | ok | +{{% /flex-content %}} +{{% flex-content %}} +##### Functions +```js +data |> events.duration( + unit: 1m, + stop: 2020-01-02T00:00:00Z +) + +data |> elapsed( + unit: 1m +) + +data |> stateDuration( + unit: 1m, + fn: (r) => true +) +``` +{{% /flex-content %}} +{{< /flex >}} + +##### Output values +| _time | state | events.duration() | elapsed() | stateDuration() | +|:----- |:-----:| -----------------:| ---------: | ---------------:| +| 2020-01-01T00:00:00Z | ok | 12 | N/A | 0 | +| 2020-01-01T00:12:34Z | warn | 12 | 12 | 12 | +| 2020-01-01T00:25:01Z | ok | 942 | 12 | 25 | +| 2020-01-01T16:07:55Z | crit | 46 | 942 | 967 | +| 2020-01-01T16:54:21Z | warn | 86 | 46 | 1014 | +| 2020-01-01T18:20:45Z | ok | 339 | 86 | 1100 | + + +{{% note %}} +#### Package author and maintainer +**Github:** [@tomhollingworth](https://github.com/tomhollingworth) +**InfluxDB Slack:** [@Tom Hollingworth](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/influxdb/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/influxdb/_index.md new file mode 100644 index 000000000..2792eb195 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/influxdb/_index.md @@ -0,0 +1,29 @@ +--- +title: Flux InfluxDB package +list_title: InfluxDB package +description: > + The Flux InfluxDB package provides additional functions for querying data from InfluxDB. + Import the `contrib/jsternberg/influxdb` package. +menu: + influxdb_cloud_ref: + name: InfluxDB + identifier: contrib_influxdb + parent: Contributed +weight: 202 +influxdb/v2.0/tags: [functions, package, query] +--- + +The Flux InfluxDB package provides additional functions for querying data from InfluxDB. +Import the `contrib/jsternberg/influxdb` package: + +```js +import "contrib/jsternberg/influxdb" +``` + +{{< children type="functions" show="pages" >}} + +{{% note %}} +#### Package author and maintainer +**Github:** [@jsternberg](https://github.com/jsternberg) +**InfluxDB Slack:** [@Jonathan Sternberg](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/influxdb/select.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/influxdb/select.md new file mode 100644 index 000000000..da1ddd1bf --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/influxdb/select.md @@ -0,0 +1,184 @@ +--- +title: influxdb.select() function +description: > + The `influxdb.select()` function is an alternate implementation of `from()`, `range()`, `filter()` + and `pivot()` that returns pivoted query results and masks the `_start` and `_stop` column + Results are similar to those returned by InfluxQL `SELECT` statements. +menu: + influxdb_cloud_ref: + name: influxdb.select + parent: contrib_influxdb +weight: 202 +influxdb/v2.0/tags: [functions, package, query] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/inputs/from/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/range/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/ + - /influxdb/cloud/reference/flux/stdlib/influxdb-v1/fieldsascols/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot/ +--- + +The `influxdb.select()` function is an alternate implementation of `from()`, `range()`, `filter()` +and `pivot()` that returns pivoted query results and masks the `_measurement`, `_start`, and `_stop` columns. +Results are similar to those returned by InfluxQL `SELECT` statements. + +_**Function type:** Input_ + +```js +import "contrib/jsternberg/influxdb" + +influxdb.select( + from: "example-bucket", + start: -1d, + stop: now(), + m: "example-measurement", + fields: [], + where: (r) => true, + host: "https://example.com", + org: "example-org", + token: "MySuP3rSecr3Tt0k3n" +) +``` + +## Parameters + +{{% note %}} +[host](#host), [org](#org), and [token](#token) parameters are only required when +querying data from a **different organization** or a **remote InfluxDB instance**. +{{% /note %}} + +### from +Required Name of the bucket to query. + +_**Data type:** String_ + +### start +Required Earliest time to include in results. +Results **include** points that match the specified start time. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. + +_**Data type:** Duration | Time | Integer_ + +### stop +Latest time to include in results. +Results **exclude** points that match the specified stop time. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. + +Defaults to `now()`. + +_**Data type:** Duration | Time | Integer_ + +### m +Required Name of the measurement to query. + +_**Data type:** String_ + +### fields +List of fields to query. +Returns all fields when list is empty or unspecified. +Defaults to `[]`. + +_**Data type:** Array of Strings_ + +### where +A single argument predicate function that evaluates true or false and filters results based on tag values. +Records are passed to the function **before fields are pivoted into columns**. +Records that evaluate to true are included in the output tables. +Records that evaluate to _null_ or false are not included in the output tables. +Defaults to `(r) => true`. + +_**Data type:** Function_ + +{{% note %}} +Records evaluated in `fn` functions are represented by `r`, short for "record" or "row". +{{% /note %}} + +### host +URL of the InfluxDB instance to query. +_See [InfluxDB URLs](/influxdb/cloud/reference/urls/)._ + +_**Data type:** String_ + +### org +Organization name. + +_**Data type:** String_ + +### token +InfluxDB [authentication token](/influxdb/cloud/security/tokens/). + +_**Data type:** String_ + + +## Examples + +- [Query a single field](#query-a-single-field) +- [Query multiple fields](#query-multiple-fields) +- [Query all fields and filter by tags](#query-all-fields-and-filter-by-tags) +- [Query data from a remote InfluxDB Cloud instance](#query-data-from-a-remote-influxdb-cloud-instance) + +##### Query a single field +```js +import "contrib/jsternberg/influxdb" + +influxdb.select( + from: "example-bucket", + start: -1d, + m: "example-measurement", + fields: ["field1"] +) +``` + +##### Query multiple fields +```js +import "contrib/jsternberg/influxdb" + +influxdb.select( + from: "example-bucket", + start: -1d, + m: "example-measurement", + fields: ["field1", "field2", "field3"] +) +``` + +##### Query all fields and filter by tags +```js +import "contrib/jsternberg/influxdb" + +influxdb.select( + from: "example-bucket", + start: -1d, + m: "example-measurement", + where: (r) => r.host == "host1" and r.region == "us-west" +) +``` + +##### Query data from a remote InfluxDB Cloud instance +```js +import "contrib/jsternberg/influxdb" +import "influxdata/influxdb/secrets" + +token = secrets.get(key: "INFLUXDB_CLOUD_TOKEN") + +influxdb.select( + from: "example-bucket", + start: -1d, + m: "example-measurement", + fields: ["field1", "field2"], + host: "https://cloud2.influxdata.com", + org: "example-org", + token: token +) +``` + +--- + +{{% note %}} +#### Package author and maintainer +**Github:** [@jsternberg](https://github.com/jsternberg) +**InfluxDB Slack:** [@Jonathan Sternberg](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/_index.md new file mode 100644 index 000000000..ab9c4f629 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/_index.md @@ -0,0 +1,32 @@ +--- +title: Flux Opsgenie package +list_title: Opsgenie package +description: > + The Flux Opsgenie package provides functions that send alerts to + [Atlassian Opsgenie](https://www.atlassian.com/software/opsgenie) using the + [Opsgenie v2 API](https://docs.opsgenie.com/docs/alert-api#create-alert). + Import the `contrib/sranka/opsgenie` package. +menu: + influxdb_cloud_ref: + name: Opsgenie + parent: Contributed +weight: 202 +influxdb/v2.0/tags: [functions, opsgenie, package] +--- + +The Flux Opsgenie package provides functions that send alerts to +[Atlassian Opsgenie](https://www.atlassian.com/software/opsgenie) using the +[Opsgenie v2 API](https://docs.opsgenie.com/docs/alert-api#create-alert). +Import the `contrib/sranka/opsgenie` package: + +```js +import "contrib/sranka/opsgenie" +``` + +{{< children type="functions" show="pages" >}} + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/endpoint.md new file mode 100644 index 000000000..d38cff516 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/endpoint.md @@ -0,0 +1,104 @@ +--- +title: opsgenie.endpoint() function +description: > + The `opsgenie.endpoint()` function sends an alert message to Opsgenie using data from table rows. +menu: + influxdb_cloud_ref: + name: opsgenie.endpoint + parent: Opsgenie +weight: 202 +--- + +The `opsgenie.endpoint()` function sends an alert message to Opsgenie using data from table rows. + +_**Function type:** Output_ + +```js +import "contrib/sranka/opsgenie" + +opsgenie.endpoint( + url: "https://api.opsgenie.com/v2/alerts", + apiKey: "YoUrSup3R5ecR37AuThK3y", + entity: "example-entity" +) +``` + +## Parameters + +### url +Opsgenie API URL. +Defaults to `https://api.opsgenie.com/v2/alerts`. + +_**Data type:** String_ + +### apiKey +Required +Opsgenie API authorization key. + +_**Data type:** String_ + +### entity +Alert entity used to specify the alert domain. + +_**Data type:** String_ + +## Usage +`opsgenie.endpoint` is a factory function that outputs another function. +The output function requires a `mapFn` parameter. + +### mapFn +A function that builds the record used to generate the POST request. +Requires an `r` parameter. + +_**Data type:** Function_ + +`mapFn` accepts a table row (`r`) and returns a record that must include the +following fields: + +- `message` +- `alias` +- `description` +- `priority` +- `responders` +- `tags` +- `actions` +- `details` +- `visibleTo` + +_For more information, see [`opsgenie.sendAlert()`](/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/sendalert/)._ + +## Examples + +##### Send critical statuses to Opsgenie +```js +import "influxdata/influxdb/secrets" +import "contrib/sranka/opsgenie" + +apiKey = secrets.get(key: "OPSGENIE_APIKEY") +endpoint = opsgenie.endpoint(apiKey: apiKey) + +crit_statuses = from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses" and status == "crit") + +crit_statuses + |> endpoint(mapFn: (r) => ({ + message: "Great Scott!- Disk usage is: ${r.status}.", + alias: "disk-usage-${r.status}", + description: "", + priority: "P3", + responders: ["user:john@example.com", "team:itcrowd"], + tags: [], + entity: "my-lab", + actions: [], + details: "{}", + visibleTo: [] + }) + )() +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/sendalert.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/sendalert.md new file mode 100644 index 000000000..342fbb21d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/opsgenie/sendalert.md @@ -0,0 +1,142 @@ +--- +title: opsgenie.sendAlert() function +description: > + The `opsgenie.sendAlert()` function sends an alert message to Opsgenie. +menu: + influxdb_cloud_ref: + name: opsgenie.sendAlert + parent: Opsgenie +weight: 202 +--- + +The `opsgenie.sendAlert()` function sends an alert message to Opsgenie. + +_**Function type:** Output_ + +```js +import "contrib/sranka/opsgenie" + +opsgenie.sendAlert( + url: "https://api.opsgenie.com/v2/alerts", + apiKey: "YoUrSup3R5ecR37AuThK3y", + message: "Example message", + alias: "Example alias", + description: "Example description", + priority: "P3", + responders: ["user:john@example.com", "team:itcrowd"], + tags: ["tag1", "tag2"], + entity: "example-entity", + actions: ["action1", "action2"], + details: "{}", + visibleTo: [] +) +``` + +## Parameters + +### url +Opsgenie API URL. +Defaults to `https://api.opsgenie.com/v2/alerts`. + +_**Data type:** String_ + +### apiKey +Required +Opsgenie API authorization key. + +_**Data type:** String_ + +### message +Required +Alert message text. +130 characters or less. + +_**Data type:** String_ + +### alias +Opsgenie alias usee to de-deduplicate alerts. +250 characters or less. +Defaults to [message](#message). + +_**Data type:** String_ + +### description +Alert description. +15000 characters or less. + +_**Data type:** String_ + +### priority +Opsgenie [alert priority](https://docs.opsgenie.com/docs/alert-priority-settings). +Valid values include: + +- `P1` +- `P2` +- `P3` _(default)_ +- `P4` +- `P5` + +_**Data type:** String_ + +### responders +List of responder teams or users. +Use the `user:` prefix for users and `teams:` prefix for teams. + +_**Data type:** Array of strings_ + +### tags +Alert tags. + +_**Data type:** Array of strings_ + +### entity +Alert entity used to specify the alert domain. + +_**Data type:** String_ + +### actions +List of actions available for the alert. + +_**Data type:** Array of strings_ + +### details +Additional alert details. +Must be a JSON-encoded map of key-value string pairs. + +_**Data type:** String_ + +### visibleTo +List of teams and users the alert will be visible to without sending notifications. +Use the `user:` prefix for users and `teams:` prefix for teams. + +_**Data type:** Array of strings_ + +## Examples + +##### Send the last reported status to a Opsgenie +```js +import "influxdata/influxdb/secrets" +import "contrib/sranka/opsgenie" + +apiKey = secrets.get(key: "OPSGENIE_APIKEY") + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> findRecord(fn: (key) => true, idx: 0) + + opsgenie.sendAlert( + apiKey: apiKey, + message: "Disk usage is: ${lastReported.status}.", + alias: "example-disk-usage", + responders: ["user:john@example.com", "team:itcrowd"] + ) +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/rows/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/rows/_index.md new file mode 100644 index 000000000..88143581a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/rows/_index.md @@ -0,0 +1,28 @@ +--- +title: Flux Rows package +list_title: Rows package +description: > + The Flux Rows package provides additional functions for remapping values in rows. + Import the `contrib/jsternberg/rows` package. +menu: + influxdb_cloud_ref: + name: Rows + parent: Contributed +weight: 202 +influxdb/v2.0/tags: [functions, package] +--- + +The Flux Rows package provides additional functions for remapping values in rows. +Import the `contrib/jsternberg/rows` package: + +```js +import "contrib/jsternberg/rows" +``` + +{{< children type="functions" show="pages" >}} + +{{% note %}} +#### Package author and maintainer +**Github:** [@jsternberg](https://github.com/jsternberg) +**InfluxDB Slack:** [@Jonathan Sternberg](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/rows/map.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/rows/map.md new file mode 100644 index 000000000..2c80d170d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/rows/map.md @@ -0,0 +1,227 @@ +--- +title: rows.map() function +description: > + The `rows.map()` function is an alternate implementation of [`map()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map/) + that is faster, but more limited than `map()`. +menu: + influxdb_cloud_ref: + name: rows.map + parent: Rows +weight: 202 +influxdb/v2.0/tags: [functions, package, map] +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/map/ +--- + +The `rows.map()` function is an alternate implementation of [`map()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map/) +that is faster, but more limited than `map()`. +`rows.map()` cannot modify [groups keys](/influxdb/cloud/reference/glossary/#group-key) and, +therefore, does not need to regroup tables. +**Attempts to change columns in the group key are ignored.** + +_**Function type:** Transformation_ + +```js +import "contrib/jsternberg/rows" + +rows.map( fn: (r) => ({_value: r._value * 100.0})) +``` + +## Parameters + +### fn + +A single argument function to apply to each record. +The return value must be a record. + +_**Data type:** Function_ + +{{% note %}} +Use the `with` operator to preserve columns **not** in the group and **not** +explicitly mapped in the operation. +{{% /note %}} + +## Examples + +- [Perform mathemtical operations on column values](#perform-mathemtical-operations-on-column-values) +- [Preserve all columns in the operation](#preserve-all-columns-in-the-operation) +- [Attempt to remap columns in the group key](#attempt-to-remap-columns-in-the-group-key) + +--- + +### Perform mathemtical operations on column values +The following example returns the square of each value in the `_value` column: + +```js +import "contrib/jsternberg/rows" + +data + |> rows.map(fn: (r) ({ _value: r._value * r._value })) +``` + +{{% note %}} +#### Important notes +The `_time` column is dropped because: + +- It's not in the group key. +- It's not explicitly mapped in the operation. +- The `with` operator was not used to include existing columns. +{{% /note %}} + +{{< flex >}} +{{% flex-content %}} +#### Input tables + +**Group key:** `tag,_field` + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag1 | foo | 0001 | 1.9 | +| tag1 | foo | 0002 | 2.4 | +| tag1 | foo | 0003 | 2.1 | + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag2 | bar | 0001 | 3.1 | +| tag2 | bar | 0002 | 3.8 | +| tag2 | bar | 0003 | 1.7 | +{{% /flex-content %}} + +{{% flex-content %}} +#### Output tables + +**Group key:** `tag,_field` + +| tag | _field | _value | +|:--- |:------ | ------:| +| tag1 | foo | 3.61 | +| tag1 | foo | 5.76 | +| tag1 | foo | 4.41 | + +| tag | _field | _value | +|:--- |:------ | ------:| +| tag2 | bar | 9.61 | +| tag2 | bar | 14.44 | +| tag2 | bar | 2.89 | +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Preserve all columns in the operation +Use the `with` operator in your mapping operation to preserve all columns, +including those not in the group key, without explicitly remapping them. + +```js +import "contrib/jsternberg/rows" + +data + |> rows.map(fn: (r) ({ r with _value: r._value * r._value })) +``` + +{{% note %}} +#### Important notes +- The mapping operation remaps the `_value` column. +- The `with` operator preserves all other columns not in the group key (`_time`). +{{% /note %}} + +{{< flex >}} +{{% flex-content %}} +#### Input tables + +**Group key:** `tag,_field` + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag1 | foo | 0001 | 1.9 | +| tag1 | foo | 0002 | 2.4 | +| tag1 | foo | 0003 | 2.1 | + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag2 | bar | 0001 | 3.1 | +| tag2 | bar | 0002 | 3.8 | +| tag2 | bar | 0003 | 1.7 | +{{% /flex-content %}} + +{{% flex-content %}} +#### Output tables + +**Group key:** `tag,_field` + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag1 | foo | 0001 | 3.61 | +| tag1 | foo | 0002 | 5.76 | +| tag1 | foo | 0003 | 4.41 | + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag2 | bar | 0001 | 9.61 | +| tag2 | bar | 0002 | 14.44 | +| tag2 | bar | 0003 | 2.89 | +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Attempt to remap columns in the group key + +```js +import "contrib/jsternberg/rows" + +data + |> rows.map(fn: (r) ({ r with tag: "tag3" })) +``` + +{{% note %}} +#### Important notes +- Remapping the `tag` column to `"tag3"` is ignored because `tag` is part of the group key. +- The `with` operator preserves columns not in the group key (`_time` and `_value`). +{{% /note %}} + +{{< flex >}} +{{% flex-content %}} +#### Input tables + +**Group key:** `tag,_field` + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag1 | foo | 0001 | 1.9 | +| tag1 | foo | 0002 | 2.4 | +| tag1 | foo | 0003 | 2.1 | + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag2 | bar | 0001 | 3.1 | +| tag2 | bar | 0002 | 3.8 | +| tag2 | bar | 0003 | 1.7 | +{{% /flex-content %}} + +{{% flex-content %}} +#### Output tables + +**Group key:** `tag,_field` + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag1 | foo | 0001 | 1.9 | +| tag1 | foo | 0002 | 2.4 | +| tag1 | foo | 0003 | 2.1 | + +| tag | _field | _time | _value | +|:--- |:------ |:----- | ------:| +| tag2 | bar | 0001 | 3.1 | +| tag2 | bar | 0002 | 3.8 | +| tag2 | bar | 0003 | 1.7 | +{{% /flex-content %}} +{{< /flex >}} + +--- + +{{% note %}} +#### Package author and maintainer +**Github:** [@jsternberg](https://github.com/jsternberg) +**InfluxDB Slack:** [@Jonathan Sternberg](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/_index.md new file mode 100644 index 000000000..cb91dba4a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/_index.md @@ -0,0 +1,37 @@ +--- +title: Flux Sensu package +list_title: Sensu package +description: > + The Flux Sensu package provides functions for sending events to + [Sensu Go](https://docs.sensu.io/sensu-go/latest/). + Import the `contrib/sranka/sensu` package. +menu: + influxdb_cloud_ref: + name: Sensu + parent: Contributed +weight: 202 +v2.0/tags: [functions, teams, sensu, package] +--- + +The Flux Sensu package provides functions for sending events to +[Sensu Go](https://docs.sensu.io/sensu-go/latest/). +Import the `contrib/sranka/sensu` package: + +```js +import "contrib/sranka/sensu" +``` + +{{< children type="functions" show="pages" >}} + +## Sensu API Key authentication +The Flux Sensu package only supports [Sensu API key authentication](https://docs.sensu.io/sensu-go/latest/api/#authenticate-with-an-api-key). +All `sensu` functions require an `apiKey` parameter to successfully authenticate +with your Sensu service. +For information about managing Sensu API keys, see the +[Sensu APIKeys API documentation](https://docs.sensu.io/sensu-go/latest/api/apikeys/). + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/endpoint.md new file mode 100644 index 000000000..aa1230b36 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/endpoint.md @@ -0,0 +1,120 @@ +--- +title: sensu.endpoint() function +description: > + The `sensu.endpoint()` function sends an event to the + [Sensu Events API](https://docs.sensu.io/sensu-go/latest/api/events/#create-a-new-event) + using data from table rows. +menu: + influxdb_cloud_ref: + name: sensu.endpoint + parent: Sensu +weight: 202 +related: + - https://docs.sensu.io/sensu-go/latest/api/events/, Sensu Events API + - https://docs.sensu.io/sensu-go/latest/api/apikeys/, Sensu APIKeys API + - https://docs.sensu.io/sensu-go/latest/reference/handlers/, Sensu handlers +--- + +The `sensu.endpoint()` function sends an event to the +[Sensu Events API](https://docs.sensu.io/sensu-go/latest/api/events/#create-a-new-event) +using data from table rows. + +_**Function type:** Output_ + +```js +import "contrib/sranka/sensu" + +sensu.endpoint( + url: "http://localhost:8080", + apiKey: "mYSuP3rs3cREtApIK3Y", + handlers: [], + namespace: "default", + entityName: "influxdb" +) +``` + +## Parameters + +### url +Required +Base URL of [Sensu API](https://docs.sensu.io/sensu-go/latest/migrate/#architecture) +**without a trailing slash**. Example: `http://localhost:8080`. + +_**Data type:** String_ + +### apiKey +Required +Sensu [API Key](https://docs.sensu.io/sensu-go/latest/operations/control-access/). + +_**Data type:** String_ + +### handlers +[Sensu handlers](https://docs.sensu.io/sensu-go/latest/reference/handlers/) to execute. +Default is `[]`. + +_**Data type:** Array of strings_ + +### namespace +[Sensu namespace](https://docs.sensu.io/sensu-go/latest/reference/rbac/). +Default is `default`. + +_**Data type:** String_ + +### entityName +Event source. +Use alphanumeric characters, underscores (`_`), periods (`.`), and hyphens (`-`). +All other characters are replaced with an underscore. +Default is `influxdb`. + +_**Data type:** String_ + +## Usage +`sensu.endpoint` is a factory function that outputs another function. +The output function requires a `mapFn` parameter. + +### mapFn +A function that builds the object used to generate the POST request. +Requires an `r` parameter. + +_**Data type:** Function_ + +`mapFn` accepts a table row (`r`) and returns an object that must include the +following fields: + +- `checkName` +- `text` +- `status` + +_For more information, see [`sensu.event()` parameters](/v2.0/reference/flux/stdlib/contrib/sensu/event/#parameters)._ + +## Examples + +##### Send critical status events to Sensu +```js +import "influxdata/influxdb/secrets" +import "contrib/sranka/sensu" + +token = secrets.get(key: "TELEGRAM_TOKEN") +endpoint = sensu.endpoint( + url: "http://localhost:8080", + apiKey: apiKey +) + +crit_statuses = from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses" and status == "crit") + +crit_statuses + |> endpoint(mapFn: (r) => ({ + checkName: "critStatus", + text: "Status is critical", + status: 2 + }) + )() +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/event.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/event.md new file mode 100644 index 000000000..38ea53bca --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/sensu/event.md @@ -0,0 +1,141 @@ +--- +title: sensu.event() function +description: > + The `sensu.event()` function sends a single event to the + [Sensu Events API](https://docs.sensu.io/sensu-go/latest/api/events/#create-a-new-event). +menu: + influxdb_cloud_ref: + name: sensu.event + parent: Sensu +weight: 202 +related: + - https://docs.sensu.io/sensu-go/latest/api/events/, Sensu Events API + - https://docs.sensu.io/sensu-go/latest/api/apikeys/, Sensu APIKeys API + - https://docs.sensu.io/sensu-go/latest/reference/handlers/, Sensu handlers +--- + +The `sensu.event()` function sends a single event to the +[Sensu Events API](https://docs.sensu.io/sensu-go/latest/api/events/#create-a-new-event). + +_**Function type:** Output_ + +```js +import "contrib/sranka/sensu" + +sensu.event( + url: "http://localhost:8080", + apiKey: "mYSuP3rs3cREtApIK3Y", + checkName: "checkName", + text: "Event output text", + handlers: [], + status: 0, + state: "passing", + namespace: "default", + entityName: "influxdb" +) +``` + +## Parameters + +### url +Required +Base URL of [Sensu API](https://docs.sensu.io/sensu-go/latest/migrate/#architecture) +**without a trailing slash**. Example: `http://localhost:8080`. + +_**Data type:** String_ + +### apiKey +Required +Sensu [API Key](https://docs.sensu.io/sensu-go/latest/operations/control-access/). + +_**Data type:** String_ + +### checkName +Required +Check name. +Use alphanumeric characters, underscores (`_`), periods (`.`), and hyphens (`-`). +All other characters are replaced with an underscore. + +_**Data type:** String_ + +### text +Required +Event text. +Mapped to `output` in the Sensu Events API request. + +_**Data type:** String_ + +### handlers +[Sensu handlers](https://docs.sensu.io/sensu-go/latest/reference/handlers/) to execute. +Default is `[]`. + +_**Data type:** Array of strings_ + +### status +Event status code that indicates [state](#state). +Default is `0`. + +_**Data type:** Integer_ + +| Status code | State | +|:----------- |:----- | +| `0` | OK | +| `1` | WARNING | +| `2` | CRITICAL | +| Any other value | UNKNOWN or custom state | + +### state +Event state. +Default is `"passing"` for `0` [status](#status) and `"failing"` for other statuses. + +_**Data type:** string_ + +The following values are accepted: + +- `"failing"` +- `"passing"` +- `"flapping"` + +### namespace +[Sensu namespace](https://docs.sensu.io/sensu-go/latest/reference/rbac/). +Default is `"default"`. + +_**Data type:** String_ + +### entityName +Event source. +Use alphanumeric characters, underscores (`_`), periods (`.`), and hyphens (`-`). +All other characters are replaced with an underscore. +Default is `influxdb`. + +_**Data type:** String_ + +## Examples + +##### Send the last reported status to Sensu +```js +import "influxdata/influxdb/secrets" +import "contrib/sranka/sensu" + +apiKey = secrets.get(key: "SENSU_API_KEY") + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> findRecord(fn: (key) => true, idx: 0) + + sensu.event( + url: "http://localhost:8080", + apiKey: apiKey, + checkName: "diskUsage", + text: "Disk usage is **${lastReported.status}**.", + ) +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/_index.md new file mode 100644 index 000000000..23eb88202 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/_index.md @@ -0,0 +1,32 @@ +--- +title: Flux Microsoft Teams package +list_title: Microsoft Teams package +description: > + The Flux Microsoft Teams package provides functions for sending messages to a + [Microsoft Teams](https://www.microsoft.com/microsoft-365/microsoft-teams/group-chat-software) + channel using an [incoming webhook](https://docs.microsoft.com/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). + Import the `contrib/sranka/teams` package. +menu: + influxdb_cloud_ref: + name: Teams + parent: Contributed +weight: 202 +influxdb/v2.0/tags: [functions, teams, microsoft, package] +--- + +The Flux Microsoft Teams package provides functions for sending messages to a +[Microsoft Teams](https://www.microsoft.com/microsoft-365/microsoft-teams/group-chat-software) +channel using an [incoming webhook](https://docs.microsoft.com/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). +Import the `contrib/sranka/teams` package: + +```js +import "contrib/sranka/teams" +``` + +{{< children type="functions" show="pages" >}} + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/endpoint.md new file mode 100644 index 000000000..bc7ad5dfd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/endpoint.md @@ -0,0 +1,78 @@ +--- +title: teams.endpoint() function +description: > + The `teams.endpoint()` function sends a message to a Microsoft Teams channel + using data from table rows. +menu: + influxdb_cloud_ref: + name: teams.endpoint + parent: Teams +weight: 202 +--- + +The `teams.endpoint()` function sends a message to a Microsoft Teams channel +using data from table rows. + +_**Function type:** Output_ + +```js +import "contrib/sranka/teams" + +teams.endpoint( + url: "https://outlook.office.com/webhook/example-webhook" +) +``` + +## Parameters + +### url +Incoming webhook URL. + +_**Data type:** String_ + +## Usage +`teams.endpoint` is a factory function that outputs another function. +The output function requires a `mapFn` parameter. + +### mapFn +A function that builds the object used to generate the POST request. +Requires an `r` parameter. + +_**Data type:** Function_ + +`mapFn` accepts a table row (`r`) and returns an object that must include the +following fields: + +- `title` +- `text` +- `summary` + +_For more information, see [`teams.message()` parameters](/v2.0/reference/flux/stdlib/contrib/teams/message/#parameters)._ + +## Examples + +##### Send critical statuses to a Microsoft Teams channel +```js +import "contrib/sranka/teams" + +url = "https://outlook.office.com/webhook/example-webhook" +endpoint = teams.endpoint(url: url) + +crit_statuses = from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses" and status == "crit") + +crit_statuses + |> endpoint(mapFn: (r) => ({ + title: "Disk Usage" + text: "Disk usage is: **${r.status}**.", + summary: "Disk usage is ${r.status}" + }) + )() +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/message.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/message.md new file mode 100644 index 000000000..7dc5061fb --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/teams/message.md @@ -0,0 +1,78 @@ +--- +title: teams.message() function +description: > + The `teams.message()` function sends a single message to a Microsoft Teams channel using + an [incoming webhook](https://docs.microsoft.com/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). +menu: + influxdb_cloud_ref: + name: teams.message + parent: Teams +weight: 202 +--- + +The `teams.message()` function sends a single message to a Microsoft Teams channel using +an [incoming webhook](https://docs.microsoft.com/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). + +_**Function type:** Output_ + +```js +import "contrib/sranka/teams" + +teams.message( + url: "https://outlook.office.com/webhook/example-webhook", + title: "Example message title", + text: "Example message text", + summary: "", +) +``` + +## Parameters + +### url +Incoming webhook URL. + +_**Data type:** String_ + +### title +Message card title. + +_**Data type:** String_ + +### text +Message card text. + +_**Data type:** String_ + +### summary +Message card summary. +Default is `""`. +If no summary is provided, Flux generates the summary from the message text. + +_**Data type:** String_ + +## Examples + +##### Send the last reported status to a Microsoft Teams channel +```js +import "contrib/sranka/teams" + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> findRecord(fn: (key) => true, idx: 0) + +teams.message( + url: "https://outlook.office.com/webhook/example-webhook", + title: "Disk Usage" + text: "Disk usage is: *${lastReported.status}*.", + summary: "Disk usage is ${lastReported.status}" +) +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/_index.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/_index.md new file mode 100644 index 000000000..85f20ac63 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/_index.md @@ -0,0 +1,50 @@ +--- +title: Flux Telegram package +list_title: Telegram package +description: > + The Flux Telegram package provides functions for sending messages to + [Telegram](https://telegram.org/) using the [Telegram Bot API](https://core.telegram.org/bots/api). + Import the `contrib/sranka/telegram` package. +menu: + influxdb_cloud_ref: + name: Telegram + parent: Contributed +weight: 202 +v2.0/tags: [functions, teams, telegram, package] +--- + +The Flux Telegram package provides functions for sending messages to +[Telegram](https://telegram.org/) using the [Telegram Bot API](https://core.telegram.org/bots/api). +Import the `contrib/sranka/telegram` package: + +```js +import "contrib/sranka/telegram" +``` + +{{< children type="functions" show="pages" >}} + +## Set up a Telegram bot +The **Telegram Bot API** requires a **bot token** and a **channel ID**. +To set up a Telegram bot and obtain the required bot token and channel ID: + +1. [Create a new Telegram account](https://telegram.org/) or use an existing account. +2. [Create a Telegram bot](https://core.telegram.org/bots#creating-a-new-bot). + Telegram provides a **bot token** for the newly created bot. +3. Use the **Telegram application** to create a new channel. +4. [Add the new bot to the channel](https://stackoverflow.com/questions/33126743/how-do-i-add-my-bot-to-a-channel) as an **Administrator**. + Ensure the bot has permissions necessary to **post messages**. +5. Send a message to bot in the channel. +6. Send a request to `https://api.telegram.org/bot$token/getUpdates`. + + ```sh + curl https://api.telegram.org/bot$token/getUpdates + ``` + + Find your **channel ID** in the `id` field of the response. + + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/endpoint.md new file mode 100644 index 000000000..0e1cec3ec --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/endpoint.md @@ -0,0 +1,106 @@ +--- +title: telegram.endpoint() function +description: > + The `telegram.endpoint()` function sends a message to a Telegram channel + using data from table rows. +menu: + influxdb_cloud_ref: + name: telegram.endpoint + parent: Telegram +weight: 202 +--- + +The `telegram.endpoint()` function sends a message to a Telegram channel +using data from table rows. + +_**Function type:** Output_ + +```js +import "contrib/sranka/telegram" + +telegram.endpoint( + url: "https://api.telegram.org/bot", + token: "S3crEtTel3gRamT0k3n", + parseMode: "MarkdownV2", + disableWebPagePreview: false, +) +``` + +{{% note %}} +For information about retrieving your Telegram **bot token** and **channel ID**, +see [Set up a Telegram bot](/v2.0/reference/flux/stdlib/contrib/telegram/#set-up-a-telegram-bot). +{{% /note %}} + +## Parameters + +### url +URL of the Telegram bot endpoint. +Default is `https://api.telegram.org/bot`. + +_**Data type:** String_ + +### token +Required +Telegram bot token. + +_**Data type:** String_ + +### parseMode +[Parse mode](https://core.telegram.org/bots/api#formatting-options) of the message text. +Default is `"MarkdownV2"`. + +_**Data type:** String_ + +### disableWebPagePreview +Disable preview of web links in the sent message. +Default is `false`. + +_**Data type:** Boolean_ + +## Usage +`telegram.endpoint` is a factory function that outputs another function. +The output function requires a `mapFn` parameter. + +### mapFn +A function that builds the object used to generate the POST request. +Requires an `r` parameter. + +_**Data type:** Function_ + +`mapFn` accepts a table row (`r`) and returns an object that must include the +following fields: + +- `channel` +- `text` +- `silent` + +_For more information, see [`telegram.message()` parameters](/v2.0/reference/flux/stdlib/contrib/telegram/message/#parameters)._ + +## Examples + +##### Send critical statuses to a Telegram channel +```js +import "influxdata/influxdb/secrets" +import "contrib/sranka/telegram" + +token = secrets.get(key: "TELEGRAM_TOKEN") +endpoint = telegram.endpoint(token: token) + +crit_statuses = from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses" and status == "crit") + +crit_statuses + |> endpoint(mapFn: (r) => ({ + channel: "-12345", + text: "Disk usage is **${r.status}**.", + silent: true + }) + )() +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/message.md b/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/message.md new file mode 100644 index 000000000..0c416a038 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/contrib/telegram/message.md @@ -0,0 +1,107 @@ +--- +title: telegram.message() function +description: > + The `telegram.message()` function sends a single message to a Telegram channel using + the [`sendMessage` method of the Telegram Bot API](https://core.telegram.org/bots/api#sendmessage). +menu: + influxdb_cloud_ref: + name: telegram.message + parent: Telegram +weight: 202 +--- + +The `telegram.message()` function sends a single message to a Telegram channel using +the [`sendMessage` method of the Telegram Bot API](https://core.telegram.org/bots/api#sendmessage). + +_**Function type:** Output_ + +```js +import "contrib/sranka/telegram" + +telegram.message( + url: "https://api.telegram.org/bot", + token: "S3crEtTel3gRamT0k3n", + channel: "-12345", + text: "Example message text", + parseMode: "MarkdownV2", + disableWebPagePreview: false, + silent: true +) +``` + +{{% note %}} +For information about retrieving your Telegram **bot token** and **channel ID**, +see [Set up a Telegram bot](/v2.0/reference/flux/stdlib/contrib/telegram/#set-up-a-telegram-bot). +{{% /note %}} + +## Parameters + +### url +URL of the Telegram bot endpoint. +Default is `https://api.telegram.org/bot`. + +_**Data type:** String_ + +### token +Required +Telegram bot token. + +_**Data type:** String_ + +### channel +Required +Telegram channel ID. + +_**Data type:** String_ + +### text +Message text. + +_**Data type:** String_ + +### parseMode +[Parse mode](https://core.telegram.org/bots/api#formatting-options) of the message text. +Default is `"MarkdownV2"`. + +_**Data type:** String_ + +### disableWebPagePreview +Disable preview of web links in the sent message. +Default is `false`. + +_**Data type:** Boolean_ + +### silent +Send message [silently](https://telegram.org/blog/channels-2-0#silent-messages). +Default is `true`. + +_**Data type:** Boolean_ + +## Examples + +##### Send the last reported status to Telegram +```js +import "influxdata/influxdb/secrets" +import "contrib/sranka/telegram" + +token = secrets.get(key: "TELEGRAM_TOKEN") + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> findRecord(fn: (key) => true, idx: 0) + + telegram.message( + token: token, + channel: "-12345" + text: "Disk usage is **${lastReported.status}**.", + ) +``` + +{{% note %}} +#### Package author and maintainer +**Github:** [@sranka](https://github.com/sranka) +**InfluxDB Slack:** [@sranka](https://influxdata.com/slack) +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/csv/_index.md b/content/influxdb/cloud/reference/flux/stdlib/csv/_index.md new file mode 100644 index 000000000..44957b7ca --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/csv/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux CSV package +list_title: CSV package +description: > + The Flux CSV package provides functions for working with data in annotated CSV format. + Import the `csv` package. +aliases: + - /influxdb/cloud/reference/flux/functions/csv/ +menu: + influxdb_cloud_ref: + name: CSV + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, csv, package] +--- + +CSV Flux functions provide tools for working with data in [annotated CSV format](https://github.com/influxdata/flux/blob/master/docs/SPEC.md#csv). +Import the `csv` package: + +```js +import "csv" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/csv/from.md b/content/influxdb/cloud/reference/flux/stdlib/csv/from.md new file mode 100644 index 000000000..c15369239 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/csv/from.md @@ -0,0 +1,83 @@ +--- +title: csv.from() function +description: The `csv.from()` function retrieves data from a CSV data source. +aliases: + - /influxdb/cloud/reference/flux/functions/inputs/fromcsv + - /influxdb/cloud/reference/flux/functions/built-in/inputs/fromcsv + - /influxdb/cloud/reference/flux/functions/csv/from/ +menu: + influxdb_cloud_ref: + name: csv.from + parent: CSV +weight: 202 +--- + +The `csv.from()` function retrieves data from a comma-separated value (CSV) data source. +It returns a stream of tables. +Each unique series is contained within its own table. +Each record in the table represents a single point in the series. + +_**Function type:** Input_ + +```js +import "csv" + +csv.from(csv: csvData) + +// OR + +csv.from(file: "/path/to/data-file.csv") +``` + +## Parameters + +### csv +Annotated CSV text. + +{{% note %}} +CSV data must use Annotated CSV syntax and include all +[annotation rows](/influxdb/cloud/reference/syntax/annotated-csv/#annotations). +For more information, see [Annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/). +{{% /note %}} + +_**Data type:** String_ + +### file +The file path of the CSV file to query. +The path can be absolute or relative. +If relative, it is relative to the working directory of the `fluxd` process. +_The CSV file must exist in the same file system running the `fluxd` process._ + +{{% warn %}} +**InfluxDB OSS** and **{{< cloud-name "short" >}}** user interfaces do _**not**_ support the `file` parameter. +Neither allow access to the underlying filesystem. +However, the [Flux REPL](/influxdb/cloud/tools/repl/) does support the `file` parameter. +{{% /warn %}} + +_**Data type:** String_ + +## Examples + +### Query CSV data from a file +```js +import "csv" + +csv.from(file: "/path/to/data-file.csv") +``` + +### Query raw CSV-formatted text +```js +import "csv" + +csvData = " +#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,string,string,double +#group,false,false,false,false,false,false,false,false +#default,,,,,,,, +,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 +" + +csv.from(csv: csvData) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/_index.md b/content/influxdb/cloud/reference/flux/stdlib/date/_index.md new file mode 100644 index 000000000..9d94d7e7b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/_index.md @@ -0,0 +1,60 @@ +--- +title: Flux date package +list_title: Date package +description: > + The Flux date package provides date and time constants and functions. + Import the `date` package. +aliases: + - /influxdb/cloud/reference/flux/language/built-ins/time-constants/ + - /influxdb/cloud/reference/flux/functions/date/ +menu: + influxdb_cloud_ref: + name: Date + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [date, time, functions] +--- + +The Flux date package provides date and time constants and functions. +Import the `date` package. + +```js +import "date" +``` + +## Date and time constants +That `date` package includes the following date and time constants. + +### Days of the week +Days of the week are represented as integers in the range `[0-6]`. + +```js +date.Sunday = 0 +date.Monday = 1 +date.Tuesday = 2 +date.Wednesday = 3 +date.Thursday = 4 +date.Friday = 5 +date.Saturday = 6 +``` + +### Months of the year +Months are represented as integers in the range `[1-12]`. + +```js +date.January = 1 +date.February = 2 +date.March = 3 +date.April = 4 +date.May = 5 +date.June = 6 +date.July = 7 +date.August = 8 +date.September = 9 +date.October = 10 +date.November = 11 +date.December = 12 +``` + +## Date and time functions +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/hour.md b/content/influxdb/cloud/reference/flux/stdlib/date/hour.md new file mode 100644 index 000000000..5ff7b9333 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/hour.md @@ -0,0 +1,57 @@ +--- +title: date.hour() function +description: > + The `date.hour()` function returns the hour of a specified time. + Results range from `[0-23]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/hour/ +menu: + influxdb_cloud_ref: + name: date.hour + parent: Date +weight: 301 +--- + +The `date.hour()` function returns the hour of a specified time. +Results range from `[0-23]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.hour(t: 2019-07-17T12:05:21.012Z) + +// Returns 12 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the hour of a time value +```js +import "date" + +date.hour(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 12 +``` + +##### Return the hour of a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.hour(t: -8h) + +// Returns 4 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/microsecond.md b/content/influxdb/cloud/reference/flux/stdlib/date/microsecond.md new file mode 100644 index 000000000..da0977cb0 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/microsecond.md @@ -0,0 +1,57 @@ +--- +title: date.microsecond() function +description: > + The `date.microsecond()` function returns the microsecond of a specified time. + Results range from `[0-999999]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/microsecond/ +menu: + influxdb_cloud_ref: + name: date.microsecond + parent: Date +weight: 301 +--- + +The `date.microsecond()` function returns the microsecond of a specified time. +Results range from `[0-999999]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.microsecond(t: 2019-07-17T12:05:21.012934584Z) + +// Returns 12934 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the microsecond of a time value +```js +import "date" + +date.microsecond(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 293534 +``` + +##### Return the microsecond of a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.microsecond(t: -1890us) + +// Returns 291644 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/millisecond.md b/content/influxdb/cloud/reference/flux/stdlib/date/millisecond.md new file mode 100644 index 000000000..5895b951d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/millisecond.md @@ -0,0 +1,57 @@ +--- +title: date.millisecond() function +description: > + The `date.millisecond()` function returns the millisecond of a specified time. + Results range from `[0-999999]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/millisecond/ +menu: + influxdb_cloud_ref: + name: date.millisecond + parent: Date +weight: 301 +--- + +The `date.millisecond()` function returns the millisecond of a specified time. +Results range from `[0-999]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.millisecond(t: 2019-07-17T12:05:21.012934584Z) + +// Returns 12 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the millisecond of a time value +```js +import "date" + +date.millisecond(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 293 +``` + +##### Return the millisecond of a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.millisecond(t: -150ms) + +// Returns 143 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/minute.md b/content/influxdb/cloud/reference/flux/stdlib/date/minute.md new file mode 100644 index 000000000..1ab0c4757 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/minute.md @@ -0,0 +1,57 @@ +--- +title: date.minute() function +description: > + The `date.minute()` function returns the minute of a specified time. + Results range from `[0-59]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/minute/ +menu: + influxdb_cloud_ref: + name: date.minute + parent: Date +weight: 301 +--- + +The `date.minute()` function returns the minute of a specified time. +Results range from `[0-59]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.minute(t: 2019-07-17T12:05:21.012Z) + +// Returns 5 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the minute of a time value +```js +import "date" + +date.minute(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 21 +``` + +##### Return the minute of a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.minute(t: -45m) + +// Returns 36 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/month.md b/content/influxdb/cloud/reference/flux/stdlib/date/month.md new file mode 100644 index 000000000..c109e8de7 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/month.md @@ -0,0 +1,57 @@ +--- +title: date.month() function +description: > + The `date.month()` function returns the month of a specified time. + Results range from `[1-12]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/month/ +menu: + influxdb_cloud_ref: + name: date.month + parent: Date +weight: 301 +--- + +The `date.month()` function returns the month of a specified time. +Results range from `[1-12]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.month(t: 2019-07-17T12:05:21.012Z) + +// Returns 7 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the month of a time value +```js +import "date" + +date.month(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 2 +``` + +##### Return the month of a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.month(t: -3mo) + +// Returns 11 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/monthday.md b/content/influxdb/cloud/reference/flux/stdlib/date/monthday.md new file mode 100644 index 000000000..e55b20f97 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/monthday.md @@ -0,0 +1,57 @@ +--- +title: date.monthDay() function +description: > + The `date.monthDay()` function returns the day of the month for a specified time. + Results range from `[1-31]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/monthday/ +menu: + influxdb_cloud_ref: + name: date.monthDay + parent: Date +weight: 301 +--- + +The `date.monthDay()` function returns the day of the month for a specified time. +Results range from `[1-31]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.monthDay(t: 2019-07-17T12:05:21.012Z) + +// Returns 17 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the day of the month for a time value +```js +import "date" + +date.monthDay(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 11 +``` + +##### Return the day of the month for a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.monthDay(t: -8d) + +// Returns 3 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/nanosecond.md b/content/influxdb/cloud/reference/flux/stdlib/date/nanosecond.md new file mode 100644 index 000000000..64ca14155 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/nanosecond.md @@ -0,0 +1,57 @@ +--- +title: date.nanosecond() function +description: > + The `date.nanosecond()` function returns the nanosecond of a specified time. + Results range from `[0-999999999]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/nanosecond/ +menu: + influxdb_cloud_ref: + name: date.nanosecond + parent: Date +weight: 301 +--- + +The `date.nanosecond()` function returns the nanosecond of a specified time. +Results range from `[0-999999999]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.nanosecond(t: 2019-07-17T12:05:21.012934584Z) + +// Returns 12934584 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the nanosecond for a time value +```js +import "date" + +date.nanosecond(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 293534940Z +``` + +##### Return the nanosecond for a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.nanosecond(t: -2111984ns) + +// Returns 291422956 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/quarter.md b/content/influxdb/cloud/reference/flux/stdlib/date/quarter.md new file mode 100644 index 000000000..e7c8a31f9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/quarter.md @@ -0,0 +1,57 @@ +--- +title: date.quarter() function +description: > + The `date.quarter()` function returns the quarter of the year for a specified time. + Results range from `[1-4]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/quarter/ +menu: + influxdb_cloud_ref: + name: date.quarter + parent: Date +weight: 301 +--- + +The `date.quarter()` function returns the quarter of the year for a specified time. +Results range from `[1-4]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.quarter(t: 2019-07-17T12:05:21.012Z) + +// Returns 3 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the quarter for a time value +```js +import "date" + +date.quarter(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 1 +``` + +##### Return the quarter for a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.quarter(t: -7mo) + +// Returns 3 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/second.md b/content/influxdb/cloud/reference/flux/stdlib/date/second.md new file mode 100644 index 000000000..c4b0fd5b0 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/second.md @@ -0,0 +1,57 @@ +--- +title: date.second() function +description: > + The `date.second()` function returns the second of a specified time. + Results range from `[0-59]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/second/ +menu: + influxdb_cloud_ref: + name: date.second + parent: Date +weight: 301 +--- + +The `date.second()` function returns the second of a specified time. +Results range from `[0-59]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.second(t: 2019-07-17T12:05:21.012Z) + +// Returns 21 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the second of a time value +```js +import "date" + +date.second(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 3 +``` + +##### Return the second of a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.second(t: -50s) + +// Returns 13 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/truncate.md b/content/influxdb/cloud/reference/flux/stdlib/date/truncate.md new file mode 100644 index 000000000..06815100e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/truncate.md @@ -0,0 +1,78 @@ +--- +title: date.truncate() function +description: > + The `date.truncate()` function truncates a time to a specified unit. +aliases: + - /influxdb/cloud/reference/flux/functions/date/truncate/ +menu: + influxdb_cloud_ref: + name: date.truncate + parent: Date +weight: 301 +--- + +The `date.truncate()` function truncates a time to a specified unit. + +_**Function type:** Transformation_ + +```js +import "date" + +date.truncate( + t: 2019-07-17T12:05:21.012Z + unit: 1s +) + +// Returns 2019-07-17T12:05:21.000000000Z +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +### unit +The unit of time to truncate to. + +_**Data type:** Duration_ + +{{% note %}} +Only use `1` and the unit of time to specify the `unit`. +For example: `1s`, `1m`, `1h`. +{{% /note %}} + +## Examples + +##### Truncate time values +```js +import "date" + +date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1s) +// Returns 2019-06-03T13:59:01.000000000Z + +date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1m) +// Returns 2019-06-03T13:59:00.000000000Z + +date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1h) +// Returns 2019-06-03T13:00:00.000000000Z +``` + +##### Truncate time values using durations +```js +import "date" + +option now = () => 2020-01-01T00:00:30.500000000Z + +date.truncate(t: -30s, unit: 1s) +// Returns 2019-12-31T23:59:30.000000000Z + +date.truncate(t: -1m, unit: 1m) +// Returns 2019-12-31T23:59:00.000000000Z + +date.truncate(t: -1h, unit: 1h) +// Returns 2019-12-31T23:00:00.000000000Z +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/week.md b/content/influxdb/cloud/reference/flux/stdlib/date/week.md new file mode 100644 index 000000000..e8289ec81 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/week.md @@ -0,0 +1,57 @@ +--- +title: date.week() function +description: > + The `date.week()` function returns the ISO week of the year for a specified time. + Results range from `[1-53]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/week/ +menu: + influxdb_cloud_ref: + name: date.week + parent: Date +weight: 301 +--- + +The `date.week()` function returns the ISO week of the year for a specified time. +Results range from `[1-53]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.week(t: 2019-07-17T12:05:21.012Z) + +// Returns 29 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the week of the year +```js +import "date" + +date.week(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 7 +``` + +##### Return the week of the year using a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.week(t: -12d) + +// Returns 5 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/weekday.md b/content/influxdb/cloud/reference/flux/stdlib/date/weekday.md new file mode 100644 index 000000000..64346945c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/weekday.md @@ -0,0 +1,57 @@ +--- +title: date.weekDay() function +description: > + The `date.weekDay()` function returns the day of the week for a specified time. + Results range from `[0-6]`. +aliases: + - /influxdb/cloud/reference/flux/functions/date/weekday/ +menu: + influxdb_cloud_ref: + name: date.weekDay + parent: Date +weight: 301 +--- + +The `date.weekDay()` function returns the day of the week for a specified time. +Results range from `[0-6]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.weekDay(t: 2019-07-17T12:05:21.012Z) + +// Returns 3 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the day of the week for a time value +```js +import "date" + +date.weekDay(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 2 +``` + +##### Return the day of the week for a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.weekDay(t: -84h) + +// Returns 6 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/year.md b/content/influxdb/cloud/reference/flux/stdlib/date/year.md new file mode 100644 index 000000000..87e32d69f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/year.md @@ -0,0 +1,55 @@ +--- +title: date.year() function +description: > + The `date.year()` function returns the year of a specified time. +aliases: + - /influxdb/cloud/reference/flux/functions/date/year/ +menu: + influxdb_cloud_ref: + name: date.year + parent: Date +weight: 301 +--- + +The `date.year()` function returns the year of a specified time. + +_**Function type:** Transformation_ + +```js +import "date" + +date.year(t: 2019-07-17T12:05:21.012Z) + +// Returns 2019 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the year for a time value +```js +import "date" + +date.year(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 2020 +``` + +##### Return the year for a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.year(t: -14y) + +// Returns 2006 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/date/yearday.md b/content/influxdb/cloud/reference/flux/stdlib/date/yearday.md new file mode 100644 index 000000000..d46102678 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/date/yearday.md @@ -0,0 +1,57 @@ +--- +title: date.yearDay() function +description: > + The `date.yearDay()` function returns the day of the year for a specified time. + Results range from `[1-365]` for non-leap years, and `[1-366]` in leap years. +aliases: + - /influxdb/cloud/reference/flux/functions/date/yearday/ +menu: + influxdb_cloud_ref: + name: date.yearDay + parent: Date +weight: 301 +--- + +The `date.yearDay()` function returns the day of the year for a specified time. +Results include leap days and range from `[1-366]`. + +_**Function type:** Transformation_ + +```js +import "date" + +date.yearDay(t: 2019-07-17T12:05:21.012Z) + +// Returns 198 +``` + +## Parameters + +### t +The time to operate on. +Use an absolute time, relative duration, or integer. +Durations are relative to `now()`. + +_**Data type:** Time | Duration_ + +## Examples + +##### Return the day of the year for a time value +```js +import "date" + +date.yearDay(t: 2020-02-11T12:21:03.293534940Z) + +// Returns 42 +``` + +##### Return the day of the year for a relative duration +```js +import "date" + +option now = () => 2020-02-11T12:21:03.293534940Z + +date.yearDay(t: -1mo) + +// Returns 11 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/_index.md new file mode 100644 index 000000000..9d6451f44 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/_index.md @@ -0,0 +1,43 @@ +--- +title: Flux Experimental package +list_title: Experimental package +description: > + The Flux Experimental package includes experimental functions that perform various tasks. + Experimental functions are subject to change at any time and are not recommended for production use. +menu: + influxdb_cloud_ref: + name: Experimental + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, experimental, package] +--- + +The Flux Experimental package includes experimental functions that perform various tasks. + +{{% warn %}} +### Use experimental functions at your own risk +Experimental functions are subject to change and are **not recommended for production use**. +At any time, experimental functions and packages may: + +- be moved or promoted to a permanent location +- undergo API changes +- stop working with no planned fixes +- be removed without warning nor published explanation + +**By using experimental functions and packages, you agree to these risks.** +{{% /warn %}} + +## Experimental functions +The following functions are part of the base experimental package. +To use them, import the `experimental` package. + +```js +import "experimental" +``` + +{{< children type="functions" show="pages" >}} + +## Experimental packages +Experimental packages require different import paths than base experimental functions. + +{{< children show="sections" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/addduration.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/addduration.md new file mode 100644 index 000000000..6c99c708a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/addduration.md @@ -0,0 +1,58 @@ +--- +title: experimental.addDuration() function +description: > + The `experimental.addDuration()` function adds a duration to a time value and + returns the resulting time. +menu: + influxdb_cloud_ref: + name: experimental.addDuration + parent: Experimental +weight: 302 +related: + - /influxdb/cloud/reference/flux/stdlib/experimental/subduration/ +--- + +The `experimental.addDuration()` function adds a duration to a time value and +returns the resulting time value. + +_**Function type:** Transformation_ + +{{% warn %}} +This function will be removed once duration vectors are implemented. +See [influxdata/flux#413](https://github.com/influxdata/flux/issues/413). +{{% /warn %}} + +```js +import "experimental" + +experimental.addDuration( + d: 12h, + to: now(), +) +``` + +## Parameters + +### d +The duration to add. + +_**Data type:** Duration_ + +### to +The time to add the [duration](#d) to. + +_**Data type:** Time_ + +## Examples + +### Add six hours to a timestamp +```js +import "experimental" + +experimental.addDuration( + d: 6h, + to: 2019-09-16T12:00:00Z, +) + +// Returns 2019-09-16T18:00:00.000000000Z +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/aggregate/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/aggregate/_index.md new file mode 100644 index 000000000..8d3b3631d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/aggregate/_index.md @@ -0,0 +1,22 @@ +--- +title: Flux Aggregate package +list_title: Aggregate package +description: > + The Flux Aggregate package provides functions to simplify common aggregate operations. + Import the `experimental/aggregate` package. +menu: + influxdb_cloud_ref: + name: Aggregate + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [package] +--- + +The Flux Aggregate package provides functions to simplify common aggregate operations. +Import the `experimental/aggregate` package: + +```js +import "experimental/aggregate" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/aggregate/rate.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/aggregate/rate.md new file mode 100644 index 000000000..511da0e45 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/aggregate/rate.md @@ -0,0 +1,79 @@ +--- +title: aggregate.rate() function +description: > + The `aggregate.rate()` function calculates the rate of change per windows of time. +menu: + influxdb_cloud_ref: + name: aggregate.rate + parent: Aggregate +weight: 301 +related: + - /influxdb/cloud/query-data/flux/rate/ +--- + +The `aggregate.rate()` function calculates the rate of change per windows of time. + +_**Function type:** Transformation_ + +```js +import "experimental/aggregate" + +aggregate.rate( + every: 1m, + groupColumns: ["column1", "column2"], + unit: 1s +) +``` + +## Parameters + +### every +Duration of time windows. + +_**Data type:** Duration_ + +### groupColumns +List of columns to group by. Defaults to `[]`. + +_**Data type:** Array of strings_ + +### unit +The time duration to use when calculating the rate. Defaults to `1s`. + +_**Data type:** Duration_ + +## Examples + +```js +import "experimental/aggregate" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> aggregate.rate(every: 5m, unit: 1m) +``` + +## Function definition +```js +package aggregate + +import "experimental" + +rate = (tables=<-, every, groupColumns=[], unit=1s) => + tables + |> derivative(nonNegative:true, unit:unit) + |> aggregateWindow(every: every, fn : (tables=<-, column) => + tables + |> mean(column: column) + |> group(columns: groupColumns) + |> experimental.group(columns: ["_start", "_stop"], mode:"extend") + |> sum() + ) +``` + +_**Used functions:**_ +[aggregateWindow()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/) +[derivative()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/derivative/) +[experimental.group()](/influxdb/cloud/reference/flux/stdlib/experimental/group/) +[group()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group/) +[mean()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean/) +[sum()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/sum/) diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/aligntime.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/aligntime.md new file mode 100644 index 000000000..57ff58f3c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/aligntime.md @@ -0,0 +1,92 @@ +--- +title: experimental.alignTime() function +description: > + The `experimental.alignTime()` function aligns input tables to a common start time. +menu: + influxdb_cloud_ref: + name: experimental.alignTime + parent: Experimental +weight: 302 +--- + +The `experimental.alignTime()` function aligns input tables to a common start time. + +_**Function type:** Transformation_ + +```js +import "experimental" + +experimental.alignTime( + alignTo: 1970-01-01T00:00:00.000000000Z +) +``` + +## Parameters + +### alignTo +The **UTC time** to align tables to. +Default is `1970-01-01T00:00:00Z`. + +_**Data type:** Time_ + +## Examples + +### Compare values month-over-month +```js +import "experimental" + +from(bucket: "example-bucket") + |> range(start: -12mo) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> window(every: 1mo) + |> experimental.alignTime() +``` + +**Given the following input:** + +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 32.1 | +| 2020-01-02T00:00:00Z | 32.9 | +| 2020-01-03T00:00:00Z | 33.2 | +| 2020-01-04T00:00:00Z | 34.0 | +| 2020-02-01T00:00:00Z | 38.3 | +| 2020-02-02T00:00:00Z | 38.4 | +| 2020-02-03T00:00:00Z | 37.8 | +| 2020-02-04T00:00:00Z | 37.5 | + +**The following functions:** + +1. Window data by calendar month creating two separate tables (one for January and one for February). +2. Align tables to `2020-01-01T00:00:00Z`. + +```js +//... + |> window(every: 1mo) + |> alignTime(alignTo: 2020-01-01T00:00:00Z) +``` + +**And output:** + +{{< flex >}} +{{% flex-content %}} +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 32.1 | +| 2020-01-02T00:00:00Z | 32.9 | +| 2020-01-03T00:00:00Z | 33.2 | +| 2020-01-04T00:00:00Z | 34.0 | +{{% /flex-content %}} +{{% flex-content %}} +| _time | _value | +|:----- | ------:| +| 2020-01-01T00:00:00Z | 38.3 | +| 2020-01-02T00:00:00Z | 38.4 | +| 2020-01-03T00:00:00Z | 37.8 | +| 2020-01-04T00:00:00Z | 37.5 | +{{% /flex-content %}} +{{< /flex >}} + +Each output table represents data from a calendar month. +When visualized, data is still grouped by month, but timestamps are aligned to a +common start time and values can be compared by time. diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/array/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/array/_index.md new file mode 100644 index 000000000..c81d4907b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/array/_index.md @@ -0,0 +1,22 @@ +--- +title: Flux Array package +list_title: Array package +description: > + The Flux Array package provides functions for building tables from Flux arrays. + Import the `experimental/array` package. +menu: + influxdb_cloud_ref: + name: Array + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [functions, array, package, table] +--- + +Flux Array functions provide tools for building tables from Flux arrays. +Import the `experimental/array` package: + +```js +import "experimental/array" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/array/from.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/array/from.md new file mode 100644 index 000000000..c5aaac88d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/array/from.md @@ -0,0 +1,63 @@ +--- +title: array.from() function +description: > + The experimental `array.from()` function constructs a table from an array of records. +menu: + influxdb_cloud_ref: + name: array.from + parent: Array +weight: 401 +--- + +The experimental `array.from()` function constructs a table from an array of records. +Each record in the array is converted into an output row or record. +All records must have the same keys and data types. + +_**Function type:** Input_ + +{{< keep-url >}} +```js +import "experimental/array" + +array.from(rows: [ + {_time: 2020-01-01T00:00:00Z, _field: "exampleField", _value: 3, foo: "bar"}, + {_time: 2020-01-01T00:01:00Z, _field: "exampleField", _value: 4, foo: "bar"}, + {_time: 2020-01-01T00:02:00Z, _field: "exampleField", _value: 1, foo: "bar"} +]) +``` + +## Parameters + +### rows +Array of records to construct a table with. + +_**Data type:** Array of records_ + +## Examples + +##### Build an arbitrary table +```js +import "experimental/array" + +rows = [ + {foo: "bar", baz: 21.2} + {foo: "bar", baz: 23.8} +] + +array.from(rows: rows) +``` + +##### Union custom rows with query results +```js +import "influxdata/influxdb/v1" +import "experimental/array" + +tags = v1.tagValues( + bucket: "example-bucket", + tag: "host" +) + +wildcard_tag = array.from(rows: [{_value: "*"}]) + +union(tables: [tags, wildcard_tag]) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/bigtable/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/bigtable/_index.md new file mode 100644 index 000000000..01d2aa17f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/bigtable/_index.md @@ -0,0 +1,23 @@ +--- +title: Flux Bigtable package +list_title: Bigtable package +description: > + The Flux Bigtable package provides tools for working with data in Google Cloud Bigtable databases. + Import the `experimental/bigtable` package. +menu: + influxdb_cloud_ref: + name: Bigtable + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [functions, bigtable, package, google] +--- + +The Flux Bigtable package provides tools for working with data in +[Google Cloud Bigtable](https://cloud.google.com/bigtable/) databases. +Import the `experimental/bigtable` package: + +```js +import "experimental/bigtable" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/bigtable/from.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/bigtable/from.md new file mode 100644 index 000000000..c511b92eb --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/bigtable/from.md @@ -0,0 +1,77 @@ +--- +title: bigtable.from() function +description: > + The `bigtable.from()` function retrieves data from a Google Cloud Bigtable data source. +menu: + influxdb_cloud_ref: + name: bigtable.from + parent: Bigtable +weight: 401 +--- + +The `bigtable.from()` function retrieves data from a [Google Cloud Bigtable](https://cloud.google.com/bigtable/) +data source. + +_**Function type:** Input_ + +```js +import "experimental/bigtable" + +bigtable.from( + token: "mySuPeRseCretTokEn", + project: "exampleProjectID", + instance: "exampleInstanceID", + table: "example-table" +) +``` + +## Parameters + +### token +The Google Cloud IAM token to use to access the Cloud Bigtable database. + +_For more information, see the following:_ + +- [Cloud Bigtable Access Control](https://cloud.google.com/bigtable/docs/access-control) +- [Google Cloud IAM How-to guides](https://cloud.google.com/iam/docs/how-to) +- [Setting Up Authentication for Server to Server Production Applications on Google Cloud](https://cloud.google.com/docs/authentication/production) + +_**Data type:** String_ + +### project +The project ID of the Cloud Bigtable project to retrieve data from. + +_**Data type:** String_ + +### instance +The instance ID of the Cloud Bigtable instance to retrieve data from. + +_**Data type:** String_ + +### table +The name of the Cloud Bigtable table to retrieve data from. + +_**Data type:** String_ + +## Examples + +{{% note %}} +The example below uses [InfluxDB secrets](/influxdb/cloud/security/secrets/) to populate +sensitive connection credentials. +{{% /note %}} + +```js +import "experimental/bigtable" +import "influxdata/influxdb/secrets" + +bigtable_token = secrets.get(key: "BIGTABLE_TOKEN") +bigtable_project = secrets.get(key: "BIGTABLE_PROJECT_ID") +bigtable_instance = secrets.get(key: "BIGTABLE_INSTANCE_ID") + +bigtable.from( + token: bigtable_token, + project: bigtable_project, + instance: bigtable_instance, + table: "example-table" +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/chain.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/chain.md new file mode 100644 index 000000000..945393c94 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/chain.md @@ -0,0 +1,68 @@ +--- +title: experimental.chain() function +description: > + The `experimental.chain()` function runs two queries in a single Flux script + sequentially and outputs the results of the second query. +menu: + influxdb_cloud_ref: + name: experimental.chain + parent: Experimental +weight: 302 +--- + +The `experimental.chain()` function runs two queries in a single Flux script +sequentially and outputs the results of the second query. +Flux typically executes multiple queries in a single script in parallel. +Running the queries sequentially ensures any dependencies the second query has on +the results of the first query are met. + +##### Applicable use cases +- Writing to a bucket and querying the written data in a single Flux script or + [InfluxDB task](/influxdb/cloud/process-data/get-started/). +- Execute queries sequentially in testing scenarios. + +_**Function type:** Miscellaneous_ + +```js +import "experimental" + +experimental.chain( + first: query1, + second: query2 +) +``` + +## Parameters + +### first +The first query to execute. + +_**Data type:** Stream of tables_ + +### second +The second query to execute. + +_**Data type:** Stream of tables_ + +## Examples + +### Write to a bucket and query the written data +```js +import "experimental" + +downsampled_max = from(bucket: "example-bucket-1") + |> range(start: -1d) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> aggregateWindow(every: 1h, fn: max) + |> to(bucket: "downsample-1h-max", org: "example-org") + +average_max = from(bucket: "downsample-1h-max") + |> range(start: -1d) + |> filter(fn: (r) => r.measurement == "example-measurement") + |> mean() + +experimental.chain( + first: downsampled_max, + second: average_max +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/csv/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/csv/_index.md new file mode 100644 index 000000000..8278f4df1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/csv/_index.md @@ -0,0 +1,23 @@ +--- +title: Flux CSV package +list_title: CSV package +description: > + The Flux Experimental CSV package provides functions for retrieving annotated CSV. + Import the `experimental/csv` package. +menu: + influxdb_cloud_ref: + name: CSV + identifier: CSV-exp + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [functions, csv, package] +--- + +The Flux Experimental CSV package provides functions for retrieving annotated CSV. +Import the `experimental/csv` package: + +```js +import "experimental/csv" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/csv/from.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/csv/from.md new file mode 100644 index 000000000..c2e517602 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/csv/from.md @@ -0,0 +1,54 @@ +--- +title: csv.from() function +description: > + The experimental `csv.from()` function retrieves annotated CSV from a URL. +menu: + influxdb_cloud_ref: + name: csv.from * + parent: CSV-exp +weight: 401 +--- + +The experimental `csv.from()` function retrieves [annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/) **from a URL**. + +{{% note %}} +The experimental `csv.from()` function is an alternative to the standard +[`csv.from()` function](/influxdb/cloud/reference/flux/stdlib/csv/from/). +{{% /note %}} + +_**Function type:** Input_ + +{{< keep-url >}} +```js +import "experimental/csv" + +csv.from(url: "http://localhost:8086/") +``` + +## Parameters + +### url +The URL to retrieve annotated CSV from. + +_**Data type:** String_ + + +## Examples + +##### Query annotated CSV data from a remote URL +```js +import "experimental/csv" + +csv.from(url: "http://example.com/csv/example.csv") + |> filter(fn: (r) => r._measurement == "example-measurement") +``` + +## Function definition +```js +package csv + +import c "csv" +import "experimental/http" + +from = (url) => c.from(csv: string(v: http.get(url: url).body)) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/_index.md new file mode 100644 index 000000000..e04b3987c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/_index.md @@ -0,0 +1,196 @@ +--- +title: Flux Geo package +list_title: Geo package +description: > + The Flux Geo package provides tools for working with geo-temporal data, + such as filtering and grouping by geographic location. + Import the `experimental/geo` package. +menu: + influxdb_cloud_ref: + name: Geo + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [functions, package, geo] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The Flux Geo package provides tools for working with geo-temporal data, +such as filtering and grouping by geographic location. +Import the `experimental/geo` package: + +```js +import "experimental/geo" +``` + +{{< children type="functions" show="pages" >}} + +## Geo schema requirements +The Geo package uses the Go implementation of the [S2 Geometry Library](https://s2geometry.io/). +Functions in the Geo package require the following: + +- a **`s2_cell_id` tag** containing an **S2 cell ID as a token** (more information [below](#s2-cell-ids)) +- a **`lat` field** containing the **latitude in decimal degrees** (WGS 84) +- a **`lon` field** containing the **longitude in decimal degrees** (WGS 84) + +#### Schema recommendations +- a tag that identifies the data source +- a tag that identifies the point type (for example: `start`, `stop`, `via`) +- a field that identifies the track or route (for example: `id`, `tid`) + +##### Examples of geo-temporal line protocol +``` +taxi,pt=start,s2_cell_id=89c2594 tip=3.75,dist=14.3,lat=40.744614,lon=-73.979424,tid=1572566401123234345i 1572566401947779410 +bike,id=biker-007,pt=via,s2_cell_id=89c25dc lat=40.753944,lon=-73.992035,tid=1572588100i 1572567115 +``` + +## S2 Cell IDs +Use **latitude** and **longitude** with the `s2.CellID.ToToken` endpoint of the S2 +Geometry Library to generate `s2_cell_id` tags. +Specify your [S2 Cell ID level](https://s2geometry.io/resources/s2cell_statistics.html). + +{{% note %}} +To filter more quickly, use higher S2 Cell ID levels, +but know that that higher levels increase [series cardinality](/influxdb/cloud/reference/glossary/#series-cardinality). +{{% /note %}} + +Language-specific implementations of the S2 Geometry Library provide methods for +generating S2 Cell ID tokens. For example: + +- **Go:** [`s2.CellID.ToToken()`](https://godoc.org/github.com/golang/geo/s2#CellID.ToToken) +- **Python:** [`s2sphere.CellId.to_token()`](https://s2sphere.readthedocs.io/en/latest/api.html#s2sphere.CellId) +- **Javascript:** [`s2.cellid.toToken()`](https://github.com/mapbox/node-s2/blob/master/API.md#cellidtotoken---string) + +### Add S2 Cell IDs to existing geo-temporal data +Use the [`geo.shapeData()` function](/influxdb/cloud/reference/flux/stdlib/experimental/geo/shapedata/) +to add `s2_cell_id` tags to data that includes fields with latitude and longitude values. + +```js +//... + |> shapeData( + latField: "latitude", + lonField: "longitude", + level: 10 + ) +``` + +## Latitude and longitude values +Flux supports latitude and longitude values in **decimal degrees** (WGS 84). + +| Coordinate | Minimum | Maximum | +|:---------- | -------:| -------:| +| Latitude | -90.0 | 90.0 | +| Longitude | -180.0 | 180.0 | + +## Region definitions +Many functions in the Geo package filter data based on geographic region. +Define geographic regions using the following shapes: + +- [box](#box) +- [circle](#circle) +- [point](#point) +- [polygon](#polygon) + +### box +Define a box-shaped region by specifying a record containing the following properties: + +- **minLat:** minimum latitude in decimal degrees (WGS 84) _(Float)_ +- **maxLat:** maximum latitude in decimal degrees (WGS 84) _(Float)_ +- **minLon:** minimum longitude in decimal degrees (WGS 84) _(Float)_ +- **maxLon:** maximum longitude in decimal degrees (WGS 84) _(Float)_ + +##### Example box-shaped region +```js +{ + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} +``` + +### circle +Define a circular region by specifying a record containing the following properties: + +- **lat**: latitude of the circle center in decimal degrees (WGS 84) _(Float)_ +- **lon**: longitude of the circle center in decimal degrees (WGS 84) _(Float)_ +- **radius**: radius of the circle in kilometers (km) _(Float)_ + +##### Example circular region +```js +{ + lat: 40.69335938, + lon: -73.30078125, + radius: 20.0 +} +``` + +### point +Define a point region by specifying a record containing the following properties: + +- **lat**: latitude in decimal degrees (WGS 84) _(Float)_ +- **lon**: longitude in decimal degrees (WGS 84) _(Float)_ + +##### Example point region +```js +{ + lat: 40.671659, + lon: -73.936631 +} +``` + +### polygon +Define a custom polygon region using a record containing the following properties: + +- **points**: points that define the custom polygon _(Array of records)_ + + Define each point with a record containing the following properties: + + - **lat**: latitude in decimal degrees (WGS 84) _(Float)_ + - **lon**: longitude in decimal degrees (WGS 84) _(Float)_ + +##### Example polygonal region +```js +{ + points: [ + {lat: 40.671659, lon: -73.936631}, + {lat: 40.706543, lon: -73.749177}, + {lat: 40.791333, lon: -73.880327} + ] +} +``` + +## GIS geometry definitions +Many functions in the Geo package manipulate data based on geographic information system (GIS) data. +Define GIS geometry using the following: + +- Any [region type](#region-definitions) _(typically [point](#point))_ +- [linestring](#linestring) + +### linestring +Define a geographic linestring path using a record containing the following properties: + +- **linestring**: string containing comma-separated longitude and latitude + coordinate pairs (`lon lat,`): + +```js +{ + linestring: "39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433" +} +``` + +## Distance units +The Geo package supports the following units of measurement for distance: + +- `m` - meters +- `km` - kilometers _(default)_ +- `mile` - miles + +### Define distance units +Use the Geo package `units` option to define custom units of measurement: + +```js +import "experimental/geo" + +option geo.units = {distance: "mile"} +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/astracks.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/astracks.md new file mode 100644 index 000000000..56ed0df15 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/astracks.md @@ -0,0 +1,70 @@ +--- +title: geo.asTracks() function +description: > + The geo.asTracks() function groups rows into tracks (sequential, related data points). +menu: + influxdb_cloud_ref: + name: geo.asTracks + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.asTracks()` function groups rows into tracks (sequential, related data points). + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.asTracks( + groupBy: ["id","tid"], + orderBy: ["_time"] +) +``` + +## Parameters + +### groupBy +Columns to group by. +These columns should uniquely identify each track. +Default is `["id","tid"]`. + +_**Data type:** Array of strings_ + +### orderBy +Column to order results by. +Default is `["_time"]` + +_**Data type:** Array of strings_ + +## Examples + +##### Group tracks in a box-shaped region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.gridFilter(region: region) + |> geo.toRows(correlationKey: ["_time", "id"]) + |> geo.asTracks() +``` + +## Function definition +```js +asTracks = (tables=<-, groupBy=["id","tid"], orderBy=["_time"]) => + tables + |> group(columns: groupBy) + |> sort(columns: orderBy) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/filterrows.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/filterrows.md new file mode 100644 index 000000000..2168a02f4 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/filterrows.md @@ -0,0 +1,232 @@ +--- +title: geo.filterRows() function +description: > + The geo.filterRows() function filters data by a specified geographic region with + the option of strict filtering. +menu: + influxdb_cloud_ref: + name: geo.filterRows + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/gridfilter/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/strictfilter/ + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.filterRows()` function filters data by a specified geographic region with +the option of strict filtering. +This function is a combination of [`geo.gridFilter()`](/influxdb/cloud/reference/flux/stdlib/experimental/geo/gridfilter/) +and [`geo.strictFilter()`](/influxdb/cloud/reference/flux/stdlib/experimental/geo/strictfilter/). + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.filterRows( + region: {lat: 40.69335938, lon: -73.30078125, radius: 20.0}, + minSize: 24, + maxSize: -1, + level: -1, + s2cellIDLevel: -1, + correlationKey: ["_time"], + strict: true +) +``` + +{{% note %}} +#### s2_cell_id must be part of the group key +To filter geo-temporal data with `geo.filterRows()`, `s2_cell_id` must be part +of the [group key](/influxdb/cloud/reference/glossary/#group-key). +To add `s2_cell_id` to the group key, use [`experimental.group`](/influxdb/cloud/reference/flux/stdlib/experimental/group): + +```js +import "experimental" + +// ... + |> experimental.group(columns: ["s2_cell_id"], mode: "extend") +``` +{{% /note %}} + +### Strict and non-strict filtering +In most cases, the specified geographic region does not perfectly align with S2 grid cells. + +- **Non-strict filtering** returns points that may be outside of the specified region but + inside S2 grid cells partially covered by the region. +- **Strict filtering** returns only points inside the specified region. + + S2 grid cell + Filter region + Returned point + +{{< flex >}} +{{% flex-content %}} +**Strict filtering** +{{< svg "/static/svgs/geo-strict.svg" >}} +{{% /flex-content %}} +{{% flex-content %}} +**Non-strict filtering** +{{< svg "/static/svgs/geo-non-strict.svg" >}} +{{% /flex-content %}} +{{< /flex >}} + +## Parameters + +### region +The region containing the desired data points. +Specify record properties for the shape. +_See [Region definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Record_ + +### minSize +Minimum number of cells that cover the specified region. +Default is `24`. + +_**Data type:** Integer_ + +### maxSize +Maximum number of cells that cover the specified region. +Default is `-1`. + +_**Data type:** Integer_ + +### level +[S2 cell level](https://s2geometry.io/resources/s2cell_statistics.html) of grid cells. +Default is `-1`. + +_**Data type:** Integer_ + +{{% warn %}} +`level` is mutually exclusive with `minSize` and `maxSize` and must be less than +or equal to `s2cellIDLevel`. +{{% /warn %}} + +### s2cellIDLevel +[S2 Cell level](https://s2geometry.io/resources/s2cell_statistics.html) used in `s2_cell_id` tag. +Default is `-1`. + +_**Data type:** Integer_ + +{{% note %}} +When set to `-1`, `geo.filterRows()` attempts to automatically detect the S2 Cell ID level. +{{% /note %}} + +### correlationKey +List of columns used to uniquely identify a row for output. +Default is `["_time"]`. + +_**Data type:** Array of strings_ + +### strict +Enable strict geographic data filtering which filters points by longitude (`lon`) and latitude (`lat`). +For S2 grid cells that are partially covered by the defined region, only points +with coordinates in the defined region are returned. +Default is `true`. +_See [Strict and non-strict filtering](#strict-and-non-strict-filtering) above._ + +_**Data type:** Boolean_ + +## Examples + +##### Strictly filter data in a box-shaped region +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.filterRows( + region: { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 + } + ) +``` + +##### Approximately filter data in a circular region +The following example returns points with coordinates located in S2 grid cells partially +covered by the defined region even though some points my be located outside of the region. + +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.filterRows( + region: { + lat: 40.69335938, + lon: -73.30078125, + radius: 20.0 + } + strict: false + ) +``` + +##### Filter data in a polygonal region +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.filterRows( + region: { + points: [ + {lat: 40.671659, lon: -73.936631}, + {lat: 40.706543, lon: -73.749177}, + {lat: 40.791333, lon: -73.880327} + ] + } + ) +``` + +## Function definition +{{% truncate %}} +```js +filterRows = ( + tables=<-, + region, + minSize=24, + maxSize=-1, + level=-1, + s2cellIDLevel=-1, + strict=true +) => { + _columns = + |> columns(column: "_value") + |> tableFind(fn: (key) => true ) + |> getColumn(column: "_value") + _rows = + if contains(value: "lat", set: _columns) then + tables + |> gridFilter( + region: region, + minSize: minSize, + maxSize: maxSize, + level: level, + s2cellIDLevel: s2cellIDLevel) + else + tables + |> gridFilter( + region: region, + minSize: minSize, + maxSize: maxSize, + level: level, + s2cellIDLevel: s2cellIDLevel) + |> toRows() + _result = + if strict then + _rows + |> strictFilter(region) + else + _rows + return _result +} +``` +{{% /truncate %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/gridfilter.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/gridfilter.md new file mode 100644 index 000000000..de0ad599a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/gridfilter.md @@ -0,0 +1,172 @@ +--- +title: geo.gridFilter() function +description: > + The geo.gridFilter() function filters data by a specified geographic region. +menu: + influxdb_cloud_ref: + name: geo.gridFilter + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/strictfilter/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/filterRows/ + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.gridFilter()` function filters data by a specified geographic region. +It compares input data to a set of S2 Cell ID tokens located in the specified [region](#region). + +{{% note %}} +S2 Grid cells may not perfectly align with the defined region, so results may include +data with coordinates outside the region, but inside S2 grid cells partially covered by the region. +Use [`toRows()`](/influxdb/cloud/reference/flux/stdlib/experimental/geo/torows/) and +[`geo.strictFilter()`](/influxdb/cloud/reference/flux/stdlib/experimental/geo/strictfilter/) +after `geo.gridFilter()` to precisely filter points. +_See [Non-strict and strict filtering](#non-strict-and-strict-filtering) below._ +{{% /note %}} + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.gridFilter( + region: {lat: 40.69335938, lon: -73.30078125, radius: 20.0} + minSize: 24, + maxSize: -1, + level: -1, + s2cellIDLevel: -1 +) +``` + +{{% note %}} +#### s2_cell_id must be part of the group key +To filter geo-temporal data with `geo.gridFilter()`, `s2_cell_id` must be part +of the [group key](/influxdb/cloud/reference/glossary/#group-key). +To add `s2_cell_id` to the group key, use [`experimental.group`](/influxdb/cloud/reference/flux/stdlib/experimental/group): + +```js +import "experimental" + +// ... + |> experimental.group(columns: ["s2_cell_id"], mode: "extend") +``` +{{% /note %}} + +### Non-strict and strict filtering +In most cases, the specified geographic region does not perfectly align with S2 grid cells. + +- **Non-strict filtering** returns points that may be outside of the specified region but + inside S2 grid cells partially covered by the region. +- **Strict filtering** returns only points inside the specified region. + + S2 grid cell + Filter region + Returned point + +{{< flex >}} +{{% flex-content %}} +**Non-strict filtering** +{{< svg "/static/svgs/geo-non-strict.svg" >}} +{{% /flex-content %}} +{{% flex-content %}} +**Strict filtering** +{{< svg "/static/svgs/geo-strict.svg" >}} +{{% /flex-content %}} +{{< /flex >}} + +## Parameters + +### region +The region containing the desired data points. +Specify record properties for the shape. +_See [Region definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Record_ + +### minSize +Minimum number of cells that cover the specified region. +Default is `24`. + +_**Data type:** Integer_ + +### maxSize +Maximum number of cells that cover the specified region. +Default is `-1`. + +_**Data type:** Integer_ + +### level +[S2 cell level](https://s2geometry.io/resources/s2cell_statistics.html) of grid cells. +Default is `-1`. + +_**Data type:** Integer_ + +{{% warn %}} +`level` is mutually exclusive with `minSize` and `maxSize` and must be less than +or equal to `s2cellIDLevel`. +{{% /warn %}} + +### s2cellIDLevel +[S2 Cell level](https://s2geometry.io/resources/s2cell_statistics.html) used in `s2_cell_id` tag. +Default is `-1`. + +_**Data type:** Integer_ + +{{% note %}} +When set to `-1`, `gridFilter()` attempts to automatically detect the S2 Cell ID level. +{{% /note %}} + +## Examples + +##### Filter data in a box-shaped region +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.gridFilter( + region: { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 + } + ) +``` + +##### Filter data in a circular region +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.gridFilter( + region: { + lat: 40.69335938, + lon: -73.30078125, + radius: 20.0 + } + ) +``` + +##### Filter data in a custom polygon region +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.gridFilter( + region: { + points: [ + {lat: 40.671659, lon: -73.936631}, + {lat: 40.706543, lon: -73.749177}, + {lat: 40.791333, lon: -73.880327} + ] + } + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/groupbyarea.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/groupbyarea.md new file mode 100644 index 000000000..33df6a130 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/groupbyarea.md @@ -0,0 +1,72 @@ +--- +title: geo.groupByArea() function +description: > + The geo.groupByArea() function groups rows by geographic area. +menu: + influxdb_cloud_ref: + name: geo.groupByArea + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.groupByArea()` function groups rows by geographic area. +Area sizes are determined by the specified [`level`](#level). +Each geographic area is assigned a unique identifier which is stored in the [`newColumn`](#newcolumn). +Results are grouped by `newColumn`. + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.groupByArea( + newColumn: "geoArea", + level: 3, + s2cellIDLevel: -1 +) +``` + +## Parameters + +### newColumn +Name of the new column that stores the unique identifier for a geographic area. + +_**Data type:** String_ + +### level +[S2 Cell level](https://s2geometry.io/resources/s2cell_statistics.html) used +to determine the size of each geographic area. + +_**Data type:** Integer_ + +### s2cellIDLevel +[S2 Cell level](https://s2geometry.io/resources/s2cell_statistics.html) used in `s2_cell_id` tag. +Default is `-1`. + +_**Data type:** Integer_ + +{{% note %}} +When set to `-1`, `geo.groupByArea()` attempts to automatically detect the S2 Cell ID level. +{{% /note %}} + +## Examples +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.gridFilter(region: region) + |> geo.toRows() + |> geo.groupByArea(newColumn: "geoArea", level: 3) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/s2cellidtoken.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/s2cellidtoken.md new file mode 100644 index 000000000..613a8addd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/s2cellidtoken.md @@ -0,0 +1,85 @@ +--- +title: geo.s2CellIDToken() function +description: > + The `geo.s2CellIDToken()` function returns an S2 cell ID token. +menu: + influxdb_cloud_ref: + name: geo.s2CellIDToken + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.s2CellIDToken()` function returns an S2 cell ID token. + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.s2CellIDToken( + point: {lat: 37.7858229, lon: -122.4058124}, + level: 10 +) +``` + +## Parameters + +### point +Longitude and latitude in **decimal degrees** (WGS 84) to use when generating +the S2 cell ID token. +Record must contain `lat` and `lon` properties. + +_**Data type:** Record_ + +### token +S2 cell ID token to update. +Useful for changing the S2 cell level of an existing S2 cell ID token. + +_**Data type:** String_ + +{{% note %}} +`point` and `token` are mutually exclusive. +{{% /note %}} + +### level +[S2 cell level](https://s2geometry.io/resources/s2cell_statistics.html) to use +when generating the S2 cell ID token. + +_**Data type:** Integer_ + +## Examples + +##### Use latitude and longitude values to generate S2 cell ID tokens +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> map(fn: (r) => ({ + r with + s2_cell_id: geo.s2CellIDToken( + point: {lat: r.lat, lon: r.lon}, + level: 10 + )}) + ) +``` + +##### Update S2 cell ID token level +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> map(fn: (r) => ({ + r with + s2_cell_id: geo.s2CellIDToken( + token: r.s2_cell_id, + level: 10 + )}) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/s2celllatlon.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/s2celllatlon.md new file mode 100644 index 000000000..62af28e5a --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/s2celllatlon.md @@ -0,0 +1,36 @@ +--- +title: geo.s2CellLatLon() function +description: > + The `geo.s2CellLatLon()` function returns the latitude and longitude of the + center of an S2 cell. +menu: + influxdb_cloud_ref: + name: geo.s2CellLatLon + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.s2CellLatLon()` function returns the latitude and longitude of the +center of an S2 cell. + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.s2CellLatLon( + token: "89c284" +) + +// Returns {lat: 40.812535546624574, lon: -73.55941282728273} +``` + +## Parameters + +### token +S2 cell ID token. + +_**Data type:** String_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/shapedata.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/shapedata.md new file mode 100644 index 000000000..29cbe6ad3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/shapedata.md @@ -0,0 +1,112 @@ +--- +title: geo.shapeData() function +description: > + The `geo.shapeData()` function renames existing latitude and longitude fields to + **lat** and **lon** and adds an **s2_cell_id** tag. + Use `geo.shapeData()` to ensure geo-temporal data meets the requirements of the Geo package. +menu: + influxdb_cloud_ref: + name: geo.shapeData + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.shapeData()` function renames existing latitude and longitude fields to +**lat** and **lon** and adds an **s2_cell_id** tag. +Use `geo.shapeData()` to ensure geo-temporal data meets the +[requirements of the Geo package](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#geo-schema-requirements): + +1. Rename existing latitude and longitude fields to `lat` and `lon`. +2. Pivot data into row-wise sets based on `_time`. +3. Generate `s2_cell_id` tags using `lat` and `lon` values and a specified + [S2 cell level](https://s2geometry.io/resources/s2cell_statistics.html). + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.shapeData( + latField: "latitude", + lonField: "longitude", + level: 10 +) +``` + +## Parameters + +### latField +Name of the existing field that contains the latitude value in **decimal degrees** (WGS 84). +Field is renamed to `lat`. + +_**Data type:** String_ + +### lonField +Name of the existing field that contains the longitude value in **decimal degrees** (WGS 84). +Field is renamed to `lon`. + +_**Data type:** String_ + +### level +[S2 cell level](https://s2geometry.io/resources/s2cell_statistics.html) to use +when generating the S2 cell ID token. + +_**Data type:** Integer_ + +## Examples + +##### Shape data to meet the requirements of the Geo package +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.shapeData( + latField: "latitude", + lonField: "longitude", + level: 10 + ) +``` + +### geo.shapeData input and output + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _field | _value | +|:----- |:------: | ------:| +| 0001 | latitude | 30.0 | +| 0002 | latitude | 30.5 | +| 0003 | latitude | 30.7 | +| 0004 | latitude | 31.1 | +| • • • | • • • | • • • | +| 0001 | longitude | 20.0 | +| 0002 | longitude | 19.8 | +| 0003 | longitude | 19.2 | +| 0004 | longitude | 19.5 | +{{% /flex-content %}} +{{% flex-content %}} + +**The following function would output:** + +```js +|> geo.shapeData( + latField: "latitude", + lonField: "longitude", + level: 5 +) +``` + +| _time | lat | lon | s2_cell_id | +|:----- |:--------:|:---------:| ----------:| +| 0001 | 30.0 | 20.0 | 138c | +| 0002 | 30.5 | 19.8 | 1384 | +| 0003 | 30.7 | 19.2 | 139c | +| 0004 | 31.1 | 19.5 | 139c | +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_contains.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_contains.md new file mode 100644 index 000000000..0c700cf30 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_contains.md @@ -0,0 +1,86 @@ +--- +title: geo.ST_Contains() function +description: > + The `geo.ST_Contains()` function tests if the specified region contains the specified + GIS geometry and returns `true` or `false`. +menu: + influxdb_cloud_ref: + name: geo.ST_Contains + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo, GIS] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.ST_Contains()` function tests if the specified region contains the specified +geographic information system (GIS) geometry and returns `true` or `false`. + +_**Function type:** Test_ + +```js +import "experimental/geo" + +geo.ST_Contains( + region: {lat: 40.7, lon: -73.3, radius: 20.0}, + geometry: {lon: 39.7515, lat: 15.08433} +) + +// Returns false +``` + +## Parameters + +### region +The region to test. +Specify record properties for the shape. +_See [Region definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Record_ + +### geometry +The GIS geometry to test. +Can be either point or linestring geometry. +_See [GIS geometry definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Record_ + +## Examples + +##### Test if geographic points are inside of a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_contains: geo.ST_Contains(region: region, geometry: {lat: r.lat, lon: r.lon}) + })) +``` + +##### Test if tracks are inside of a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> geo.asTracks() + |> geo.ST_LineString() + |> map(fn: (r) => ({ + r with st_contains: geo.ST_Contains(region: region, geometry: {linestring: r.st_linestring}) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_distance.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_distance.md new file mode 100644 index 000000000..8cad5cb0e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_distance.md @@ -0,0 +1,85 @@ +--- +title: geo.ST_Distance() function +description: > + The `geo.ST_Distance()` function returns the distance between the specified region + and specified GIS geometry. +menu: + influxdb_cloud_ref: + name: geo.ST_Distance + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo, GIS] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.ST_Distance()` function returns the distance between the specified region +and specified geographic information system (GIS) geometry. +Define distance units with the [`geo.units` option](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#define-distance-units). + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.ST_Distance( + region: {lat: 40.7, lon: -73.3, radius: 20.0}, + geometry: {lon: 39.7515, lat: 15.08433} +) + +// Returns 10734.184618677662 (km) +``` + +## Parameters + +### region +The region to test. +Specify record properties for the shape. +_See [Region definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Record_ + +### geometry +The GIS geometry to test. +Can be either point or linestring geometry. +_See [GIS geometry definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Record_ + +## Examples + +##### Test if geographic points are inside of a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_contains: ST_Distance(region: region, geometry: {lat: r.lat, lon: r.lon}) + })) +``` + +##### Calculate the distance between geographic points and a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_distance: ST_Distance(region: region, geometry: {lat: r.lat, lon: r.lon}) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_dwithin.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_dwithin.md new file mode 100644 index 000000000..538ad8b85 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_dwithin.md @@ -0,0 +1,75 @@ +--- +title: geo.ST_DWithin() function +description: > + The `geo.ST_DWithin()` function tests if the specified region is within a defined + distance from the specified geographic information system (GIS) geometry and + returns `true` or `false`. +menu: + influxdb_cloud_ref: + name: geo.ST_DWithin + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo, GIS] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.ST_DWithin()` function tests if the specified region is within a defined +distance from the specified geographic information system (GIS) geometry and +returns `true` or `false`. + +_**Function type:** Test_ + +```js +import "experimental/geo" + +geo.ST_DWithin( + region: {lat: 40.7, lon: -73.3, radius: 20.0}, + geometry: {lon: 39.7515, lat: 15.08433}, + distance: 1000.0 +) + +// Returns false +``` + +## Parameters + +### region +The region to test. +Specify record properties for the shape. +_See [Region definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Record_ + +### geometry +The GIS geometry to test. +Can be either point or linestring geometry. +_See [GIS geometry definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Record_ + +### distance +Maximum distance allowed between the region and geometry. +_Define distance units with the [`geo.units` option](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#define-distance-units)._ + +_**Data type:** Float_ + +## Examples + +##### Test if geographic points are within a distance from a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_within: geo.ST_DWithin(region: box, geometry: {lat: r.lat, lon: r.lon}, distance: 15.0) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_intersects.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_intersects.md new file mode 100644 index 000000000..3f08f5ad6 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_intersects.md @@ -0,0 +1,66 @@ +--- +title: geo.ST_Intersects() function +description: > + The `geo.ST_Intersects()` function tests if the specified geographic information + system (GIS) geometry intersects with the specified region and returns `true` or `false`. +menu: + influxdb_cloud_ref: + name: geo.ST_Intersects + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo, GIS] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.ST_Intersects()` function tests if the specified geographic information +system (GIS) geometry intersects with the specified region and returns `true` or `false`. + +_**Function type:** Test_ + +```js +import "experimental/geo" + +geo.ST_Intersects( + region: {lat: 40.7, lon: -73.3, radius: 20.0}, + geometry: {linestring: "39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433"} +) + +// Returns false +``` + +## Parameters + +### region +The region to test. +Specify record properties for the shape. +_See [Region definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Record_ + +### geometry +The GIS geometry to test. +Can be either point or linestring geometry. +_See [GIS geometry definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Record_ + +## Examples + +##### Test if geographic points intersect with a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_within: geo.ST_Intersects(region: box, geometry: {lat: r.lat, lon: r.lon}) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_length.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_length.md new file mode 100644 index 000000000..aa00927f3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_length.md @@ -0,0 +1,62 @@ +--- +title: geo.ST_Length() function +description: > + The `geo.ST_Length()` function returns the [spherical length or distance](https://mathworld.wolfram.com/SphericalDistance.html) + of the specified geographic information system (GIS) geometry. +menu: + influxdb_cloud_ref: + name: geo.ST_Length + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo, GIS] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.ST_Length()` function returns the [spherical length or distance](https://mathworld.wolfram.com/SphericalDistance.html) +of the specified geographic information system (GIS) geometry. +Define distance units with the [`geo.units` option](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#define-distance-units). + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.ST_Length( + geometry: {linestring: "39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433"} +) + +// Returns 346.1023974652474 (km) +``` + +## Parameters + +### geometry +The GIS geometry to measure. +Can be either point or linestring geometry. +Points will always return `0.0`. +_See [GIS geometry definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Record_ + +## Examples + +##### Calculate the length of geographic paths +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> geo.asTracks() + |> geo.ST_LineString() + |> map(fn: (r) => ({ + r with st_length: geo.ST_Length(geometry: {linestring: r.st_linestring}) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_linestring.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_linestring.md new file mode 100644 index 000000000..1c849de53 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/st_linestring.md @@ -0,0 +1,69 @@ +--- +title: geo.ST_LineString() function +description: > + The `geo.ST_LineString()` function converts a series of geographic points into + [linestring](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#linestring). +menu: + influxdb_cloud_ref: + name: geo.ST_LineString + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo, GIS] +related: + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.ST_LineString()` function converts a series of geographic points into +[linestring](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#linestring). +Group data into meaningful, ordered paths to before converting to linestring. +Rows in each table must have `lat` and `lon` columns. +Output tables contain a single row with a `st_linestring` column containing the resulting linestring. + +_**Function type:** Aggregate_ + +```js +import "experimental/geo" + +geo.ST_LineString() +``` + +## Examples + +### Convert a series of geographic points into linestring + +##### Input data + +| _time | id | lon | lat | +|:----- |:--: | ---: | ---: | +| 2020-01-01T00:00:00Z | a213b | 39.7515 | 14.01433 | +| 2020-01-02T00:00:00Z | a213b | 38.3527 | 13.9228 | +| 2020-01-03T00:00:00Z | a213b | 36.9978 | 15.08433 | + + +```js +import "experimental/geo" + +data + |> geo.ST_LineString() +``` + +##### Output data + +| id | st_linestring | +|:-- |:------------- | +| a213b | 39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433 | + +## Function definition +```js +ST_LineString = (tables=<-) => + tables + |> reduce(fn: (r, accumulator) => ({ + __linestring: accumulator.__linestring + (if accumulator.__count > 0 then ", " else "") + string(v: r.lat) + " " + string(v: r.lon), + __count: accumulator.__count + 1 + }), identity: { + __linestring: "", + __count: 0 + } + ) + |> rename(columns: {__linestring: "st_linestring"}) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/strictfilter.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/strictfilter.md new file mode 100644 index 000000000..8bff9e5dd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/strictfilter.md @@ -0,0 +1,124 @@ +--- +title: geo.strictFilter() function +description: > + The geo.strictFilter() function filters data by latitude and longitude. +menu: + influxdb_cloud_ref: + name: geo.strictFilter + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/gridfilter/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/filterRows/ + - /influxdb/cloud/reference/flux/stdlib/experimental/geo/toRows/ + - /influxdb/cloud/query-data/flux/geo/ +--- + +The `geo.strictFilter()` function filters data by latitude and longitude in a specified region. +This filter is more strict than [`geo.gridFilter()`](/influxdb/cloud/reference/flux/stdlib/experimental/geo/gridfilter/), +but for the best performance, use `geo.strictFilter()` **after** `geo.gridFilter()`. +_See [Strict and non-strict filtering](#strict-and-non-strict-filtering) below._ + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.strictFilter( + region: {lat: 40.69335938, lon: -73.30078125, radius: 20.0} +) +``` + +{{% note %}} +`geo.strictFilter()` requires `lat` and `lon` columns in each row. +Use [`geo.toRows()`](/influxdb/cloud/reference/flux/stdlib/experimental/geo/gridfilter/) +to pivot `lat` and `lon` fields into each row **before** using `geo.strictFilter()`. +{{% /note %}} + +### Strict and non-strict filtering +In most cases, the specified geographic region does not perfectly align with S2 grid cells. + +- **Strict filtering** returns only points inside the specified region. +- **Non-strict filtering** returns points that may be outside of the specified region but + inside S2 grid cells partially covered by the region. + + S2 grid cell + Filter region + Returned point + +{{< flex >}} +{{% flex-content %}} +**Strict filtering** +{{< svg "/static/svgs/geo-strict.svg" >}} +{{% /flex-content %}} +{{% flex-content %}} +**Non-strict filtering** +{{< svg "/static/svgs/geo-non-strict.svg" >}} +{{% /flex-content %}} +{{< /flex >}} + +## Parameters + +### region +The region containing the desired data points. +Specify record properties for the shape. +_See [Region definitions](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Record_ + +## Examples + +##### Filter data in a box-shaped region +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.toRows() + |> geo.strictFilter( + region: { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 + } + ) +``` + +##### Filter data in a circular region +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.toRows() + |> geo.strictFilter( + region: { + lat: 40.69335938, + lon: -73.30078125, + radius: 20.0 + } + ) +``` + +##### Filter data in a custom polygon region +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.toRows() + |> geo.strictFilter( + region: { + points: [ + {lat: 40.671659, lon: -73.936631}, + {lat: 40.706543, lon: -73.749177}, + {lat: 40.791333, lon: -73.880327} + ] + } + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/torows.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/torows.md new file mode 100644 index 000000000..2df5ed151 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/geo/torows.md @@ -0,0 +1,43 @@ +--- +title: geo.toRows() function +description: > + The geo.toRows() function pivots data into row-wise sets base on time. +menu: + influxdb_cloud_ref: + name: geo.toRows + parent: Geo +weight: 401 +influxdb/v2.0/tags: [functions, geo] +related: + - /influxdb/cloud/query-data/flux/geo/ + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot/ +--- + +The `geo.toRows()` function pivots data into row-wise sets base on time. +For geo-temporal datasets, output rows include `lat` and `lon` columns required by +many Geo package functions. + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.toRows() +``` + +## Examples +```js +import "experimental/geo" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "example-measurement") + |> geo.toRows() +``` + +## Function definition +```js +toRows = (tables=<-, correlationKey=["_time"]) => + tables + |> v1.fieldsAsCols() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/group.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/group.md new file mode 100644 index 000000000..ee2403327 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/group.md @@ -0,0 +1,60 @@ +--- +title: experimental.group() function +description: > + The `experimental.group()` function introduces an `extend` mode to the existing + `group()` function. +menu: + influxdb_cloud_ref: + name: experimental.group + parent: Experimental +weight: 302 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/group/ +--- + +The `experimental.group()` function introduces an `extend` mode to the existing +[`group()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group/) function. + +_**Function type:** Transformation_ + +{{% warn %}} +This function will be removed once the proposed `extend` mode is sufficiently vetted. +{{% /warn %}} + +```js +import "experimental" + +experimental.group(columns: ["host", "_measurement"], mode:"extend") +``` + +## Parameters + +### columns +List of columns to use in the grouping operation. +Defaults to `[]`. + +_**Data type:** Array of strings_ + +### mode +The mode used to group columns. + +_**Data type:** String_ + +{{% note %}} +`extend` is the only mode available to `experimental.group()`. +{{% /note %}} + +#### extend +Appends columns defined in the [`columns` parameter](#columns) to all existing +[group keys](/influxdb/cloud/query-data/get-started/#group-keys). + +## Examples + +###### Include the value column in each groups' group key +```js +import "experimental" + +from(bucket: "example-bucket") + |> range(start: -1m) + |> experimental.group(columns: ["_value"], mode: "extend") +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/http/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/http/_index.md new file mode 100644 index 000000000..67aa7d64b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/http/_index.md @@ -0,0 +1,25 @@ +--- +title: Flux HTTP package +list_title: HTTP package +description: > + The Flux Experimental HTTP package provides functions for transferring data + using HTTP protocol. + Import the `experimental/http` package. +menu: + influxdb_cloud_ref: + name: HTTP + identifier: HTTP-exp + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [functions, http, package] +--- + +The Flux Experimental HTTP package provides functions for transferring data +using HTTP protocol. +Import the `experimental/http` package: + +```js +import "experimental/http" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/http/get.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/http/get.md new file mode 100644 index 000000000..60289a41b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/http/get.md @@ -0,0 +1,107 @@ +--- +title: http.get() function +description: > + The `http.get()` function submits an HTTP GET request to the specified URL and + returns the HTTP status code, response body, and response headers. +menu: + influxdb_cloud_ref: + name: http.get + parent: HTTP-exp +weight: 401 +--- + +The `http.get()` function submits an HTTP GET request to the specified URL and +returns the HTTP status code, response body, and response headers. + +_**Function type:** Miscellaneous_ + +```js +import "experimental/http" + +http.get( + url: "http://localhost:8086/", + headers: {x:"a", y:"b", z:"c"}, + timeout: 30s +) +``` + +## Parameters + +### url +The URL to send the GET request to. + +_**Data type:** String_ + +### headers +Headers to include with the GET request. + +_**Data type:** Record_ + +### timeout +Timeout for the GET request. +Default is `30s`. + +_**Data type:** Duration_ + +## Response format +`http.get` returns a record that contains the following: + +- [statusCode](#statuscode) +- [body](#body) +- [headers](#headers) + +### statusCode +The HTTP status code returned by the GET request. + +_**Data type:** Integer_ + +### body +The response body. + +_**Data type:** Byte Array_ + +### headers +Headers included with the response. + +_**Data type:** Record_ + +## Examples + +##### Get the status of InfluxDB OSS +```js +import "influxdata/influxdb/secrets" +import "experimental/http" +import "csv" + +token = secrets.get(key: "READONLY_TOKEN") + +response = http.get( + url: "http://localhost:8086/health", + headers: {Authorization: "Token ${token}"} + ) + +httpStatus = response.statusCode +responseBody = string(v: response.body) +responseHeaders = response.headers + +// Response header data +date = responseHeaders.Date +contentLenth = responseHeaders["Content-Length"] +contentType = responseHeaders["Content-Type"] + +// Use the returned data in a stream of tables +csvData = "#datatype,string,long,string +#group,false,false,false +#default,,, +,result,table,column +,,0,* +" +csv.from(csv: csvData) + |> map(fn: (r) => ({ + httpStatus: httpStatus, + responseBody: responseBody, + date: date, + contentLenth: contentLenth, + contentType: contentType, + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/join.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/join.md new file mode 100644 index 000000000..584382ca8 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/join.md @@ -0,0 +1,160 @@ +--- +title: experimental.join() function +description: > + The `experimental.join()` function joins two streams of tables on the + group key with the addition of the `_time` column. +menu: + influxdb_cloud_ref: + name: experimental.join + parent: Experimental +weight: 302 +--- + +The `experimental.join()` function joins two streams of tables on the +[group key](/influxdb/cloud/reference/glossary/#group-key) and `_time` column. +Use the [`fn` parameter](#fn) to map new output tables using values from input tables. + +{{% note %}} +To join streams of tables with different fields or measurements, use [`group()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group/) +or [`drop()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/drop/) to remove +`_field` and `_measurement` from the group key before joining. +_See an example [below](#join-two-streams-of-tables-with-different-fields-and-measurements)._ +{{% /note %}} + +_**Function type:** Transformation_ + +```js +import "experimental" + +// ... + +experimental.join( + left: left, + right: right, + fn: (left, right) => ({left with lv: left._value, rv: right._value }) +) +``` + +{{% note %}} +This function will likely replace the [`join` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/join/) +when sufficiently vetted. +{{% /note %}} + +## Parameters + +### left +First of two streams of tables to join. + +_**Data type:** Stream of tables_ + +### right +Second of two streams of tables to join. + +_**Data type:** Stream of tables_ + +### fn +A function with `left` and `right` arguments that maps a new output record +using values from the `left` and `right` input records. +The return value must be a record. + +_**Data type:** Function_ + +## Examples + +### Input and output tables + +**Given the following input tables:** +{{< flex >}} +{{% flex-content %}} +##### left +| _time | _field | _value | +|:----- |:------:| ------:| +| 0001 | temp | 80.1 | +| 0002 | temp | 80.2 | +| 0003 | temp | 79.9 | +| 0004 | temp | 80.0 | +{{% /flex-content %}} +{{% flex-content %}} +##### right +| _time | _field | _value | +|:----- |:------:| ------:| +| 0001 | temp | 72.1 | +| 0002 | temp | 72.2 | +| 0003 | temp | 71.9 | +| 0004 | temp | 72.0 | +{{% /flex-content %}} +{{< /flex >}} + +**The following `experimental.join()` function would output:** + +```js +import "experimental" + +experimental.join( + left: left, + right: right, + fn: (left, right) => ({ + left with + lv: left._value, + rv: right._value, + diff: left._value - right._value + }) +) +``` + +| _time | _field | lv | rv | diff | +|:----- |:------:|:--: |:--: | ----:| +| 0001 | temp | 80.1 | 72.1 | 8.0 | +| 0002 | temp | 80.2 | 72.2 | 8.0 | +| 0003 | temp | 79.9 | 71.9 | 8.0 | +| 0004 | temp | 80.0 | 72.0 | 8.0 | + +--- + +###### Join two streams of tables +```js +import "experimental" + +s1 = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "foo") + +s2 = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "bar") + +experimental.join( + left: s1, + right: s2, + fn: (left, right) => ({ + left with + s1_value: left._value, + s2_value: right._value + }) +) +``` + +###### Join two streams of tables with different fields and measurements +```js +import "experimental" + +s1 = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "foo" and r._field == "bar") + |> group(columns: ["_time", "_measurement", "_field", "_value"], mode: "except") + +s2 = from(bucket: "example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "baz" and r._field == "quz") + |> group(columns: ["_time", "_measurement", "_field", "_value"], mode: "except") + +experimental.join( + left: s1, + right: s2, + fn: (left, right) => ({ + left with + bar_value: left._value, + quz_value: right._value + }) +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/json/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/json/_index.md new file mode 100644 index 000000000..f89318b41 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/json/_index.md @@ -0,0 +1,23 @@ +--- +title: Flux Experimental JSON package +list_title: JSON package +description: > + The Flux experimental JSON package provides functions for working with JSON. + Import the `experimental/json` package. +menu: + influxdb_cloud_ref: + name: JSON + identifier: JSON-exp + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [functions, json, package] +--- + +Flux experimental JSON functions provide tools for working with JSON. +Import the `experimental/json` package: + +```js +import "experimental/json" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/json/parse.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/json/parse.md new file mode 100644 index 000000000..99b5579fb --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/json/parse.md @@ -0,0 +1,52 @@ +--- +title: json.parse() function +description: > + The `json.parse()` function takes JSON data as bytes and returns a value. +menu: + influxdb_cloud_ref: + name: json.parse + parent: JSON-exp +weight: 401 +--- + +The `json.parse()` function takes JSON data as bytes and returns a value. +The function can return lists, records, strings, booleans, and float values. +All numeric values are returned as floats. + +_**Function type:** Type conversion_ + +```js +import "experimental/json" + +json.parse( + data: bytes(v: "{\"a\":1,\"b\":2,\"c\":3}") +) +``` + +## Parameters + +### data +JSON data to parse. + +_**Data type:** Bytes_ + + +## Examples + +##### Parse and use JSON data to restructure a table +```js +import "experimental/json" + +data + |> map(fn: (r) => { + jsonData = json.parse(data: bytes(v: r._value)) + + return { + _time: r._time, + _field: r._field, + a: jsonData.a, + b: jsonData.b, + c: jsonData.c, + } + }) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/mqtt/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/mqtt/_index.md new file mode 100644 index 000000000..e1981c23c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/mqtt/_index.md @@ -0,0 +1,22 @@ +--- +title: Flux MQTT package +list_title: MQTT package +description: > + The Flux MQTT package provides functions for working with MQTT protocol. + Import the `experimental/mqtt` package. +menu: + influxdb_cloud_ref: + name: MQTT + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [functions, mqtt, package] +--- + +Flux MQTT functions provide tools for working with Message Queuing Telemetry Transport (MQTT) protocol. +Import the `experimental/mqtt` package: + +```js +import "experimental/mqtt" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/mqtt/to.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/mqtt/to.md new file mode 100644 index 000000000..7c768ba97 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/mqtt/to.md @@ -0,0 +1,129 @@ +--- +title: mqtt.to() function +description: > + The `mqtt.to()` function outputs data to an MQTT broker using MQTT protocol. +menu: + influxdb_cloud_ref: + name: mqtt.to + parent: MQTT +weight: 401 +--- + +The `mqtt.to()` function outputs data to an MQTT broker using MQTT protocol. + +_**Function type:** Output_ + +```js +import "experimental/mqtt" + +mqtt.to( + broker: "tcp://localhost:8883", + topic: "example-topic", + message: "Example message", + qos: 0, + clientid: "flux-mqtt", + username: "username", + password: "password", + name: "name-example", + timeout: 1s, + timeColumn: "_time", + tagColumns: ["tag1", "tag2"], + valueColumns: ["_value"] +) +``` + +## Parameters + +### broker +The MQTT broker connection string. + +_**Data type:** String_ + +### topic +The MQTT topic to send data to. + +_**Data type:** String_ + +### message +The message or payload to send to the MQTT broker. +The default payload is an output table. +If there are multiple output tables, it sends each table as a separate MQTT message. + +{{% note %}} +When you specify a message, the function sends the message string only (no output table). +{{% /note %}} + +_**Data type:** String_ + +### qos +The [MQTT Quality of Service (QoS)](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901103) level. +Values range from `[0-2]`. +Default is `0`. + +_**Data type:** Integer_ + +### clientid +The MQTT client ID. + +_**Data type:** String_ + +### username +The username to send to the MQTT broker. +Username is only required if the broker requires authentication. +If you provide a username, you must provide a [password](#password). + +_**Data type:** String_ + +### password +The password to send to the MQTT broker. +Password is only required if the broker requires authentication. +If you provide a password, you must provide a [username](#username). + +_**Data type:** String_ + +### name +_(Optional)_ The name for the MQTT message. + +_**Data type:** String_ + +### timeout +The MQTT connection timeout. +Default is `1s`. + +_**Data type:** Duration_ + +### timeColumn +The column to use as time values in the output line protocol. +Default is `"_time"`. + +_**Data type:** String_ + +### tagColumns +The columns to use as tag sets in the output line protocol. +Default is `[]`. + +_**Data type: Array of strings**_ + +### valueColumns +The columns to use as field values in the output line protocol. +Default is `["_value"]`. + +_**Data type: Array of strings**_ + +## Examples + +### Send data to an MQTT endpoint +```js +import "experimental/mqtt" + +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "airSensor") + |> mqtt.to( + broker: "tcp://localhost:8883", + topic: "air-sensors", + clientid: "sensor-12a4", + tagColumns: ["sensorID"], + valueColumns: ["_value"] + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/objectkeys.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/objectkeys.md new file mode 100644 index 000000000..9efe94e34 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/objectkeys.md @@ -0,0 +1,48 @@ +--- +title: experimental.objectKeys() function +description: > + The `experimental.objectKeys()` function returns an array of keys in a specified record. +menu: + influxdb_cloud_ref: + name: experimental.objectKeys + parent: Experimental +weight: 302 +--- + +The `experimental.objectKeys()` function returns an array of keys in a specified record. + +_**Function type:** Transformation_ + +```js +import "experimental" + +experimental.objectKeys( + o: {key1: "value1", key2: "value2"} +) + +// Returns [key1, key2] +``` + +## Parameters + +### o +The record to return keys from. + +_**Data type:** Record_ + +## Examples + +### Return all keys in a record +```js +import "experimental" + +user = { + firstName: "John", + lastName: "Doe", + age: 42 +} + +experimental.objectKeys(o: user) + +// Returns [firstName, lastName, age] +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/_index.md new file mode 100644 index 000000000..28b73c725 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/_index.md @@ -0,0 +1,23 @@ +--- +title: Flux Prometheus package +list_title: Prometheus package +description: > + The Flux Prometheus package provides functions for working with Prometheus-formatted metrics. + Import the `experimental/prometheus` package. +menu: + influxdb_cloud_ref: + name: Prometheus + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [functions, prometheus, package] +--- + +Flux Prometheus functions provide tools for working with +[Prometheus-formatted metrics](https://prometheus.io/docs/instrumenting/exposition_formats/). +Import the `experimental/prometheus` package: + +```js +import "experimental/prometheus" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/histogramquantile.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/histogramquantile.md new file mode 100644 index 000000000..755cb6ca3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/histogramquantile.md @@ -0,0 +1,41 @@ +--- +title: prometheus.histogramQuantile() function +description: > + The `prometheus.histogramQuantile()` function calculates quantiles on a set of values + assuming the given histogram data is scraped or read from a Prometheus data source. +menu: + influxdb_cloud_ref: + name: prometheus.histogramQuantile + parent: Prometheus +weight: 401 +--- + +The `prometheus.histogramQuantile()` function calculates quantiles on a set of values +assuming the given histogram data is scraped or read from a Prometheus data source. + +_**Function type:** Aggregate_ + +```js +import "experimental/prometheus" + +prometheus.histogramQuantile( + quantile: 0.99 +) +``` + +## Parameters + +### quantile +A value between 0.0 and 1.0 indicating the desired quantile. + +_**Data type:** Float_ + +## Examples + +### Calculate the 99th quantile in Prometheus data +```js +import "experimental/prometheus" + +prometheus.scrape(url: "https://example-url.com/metrics") + |> prometheus.histogramQuantile(quantile: 0.99) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/scrape.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/scrape.md new file mode 100644 index 000000000..2fefb3d5f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/prometheus/scrape.md @@ -0,0 +1,47 @@ +--- +title: prometheus.scrape() function +description: > + The `prometheus.scrape()` function retrieves Prometheus-formatted metrics + from a specified URL. +menu: + influxdb_cloud_ref: + name: prometheus.scrape + parent: Prometheus +weight: 401 +related: + - /influxdb/cloud/write-data/no-code/scrape-data//scrapable-endpoints/ +--- + +The `prometheus.scrape()` function retrieves [Prometheus-formatted metrics](https://prometheus.io/docs/instrumenting/exposition_formats/) +from a specified URL. +The function groups metrics (including histogram and summary values) into individual tables. + +_**Function type:** Input_ + +```js +import "experimental/prometheus" + +prometheus.scrape( + url: "http://localhost:8086/metrics" +) +``` + +## Parameters + +### url +The URL to scrape Prometheus-formatted metrics from. + +_**Data type:** String_ + +## Examples + +### Scrape Prometheus metrics and write them to InfluxDB +```js +import "experimental/prometheus" + +prometheus.scrape(url: "https://example-url.com/metrics") + |> to( + org: "example-org", + bucket: "example-bucket" + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/query/_index.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/_index.md new file mode 100644 index 000000000..fc7d35f79 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/_index.md @@ -0,0 +1,39 @@ +--- +title: Flux Query package +list_title: Query package +description: > + The Flux Query package provides functions meant to simplify common InfluxDB queries. + Import the `experimental/query` package. +menu: + influxdb_cloud_ref: + name: Query + parent: Experimental +weight: 301 +influxdb/v2.0/tags: [package] +--- + +Flux Query functions provide functions meant to simplify common InfluxDB queries. +Import the `experimental/query` package: + +```js +import "experimental/query" +``` + +{{< children type="functions" show="pages" >}} + +## inBucket() +The primary function in this package is [`query.inBucket()`](/influxdb/cloud/reference/flux/stdlib/experimental/query/inbucket/), +which uses all other functions in this package. + +```js +import "experimental/query" + +query.inBucket( + bucket: "example-bucket", + start: -1h, + stop: now(), + measurement: "example-measurement", + fields: ["exampleField1", "exampleField2"], + predicate: (r) => r.tagA == "foo" and r.tagB != "bar" +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/query/filterfields.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/filterfields.md new file mode 100644 index 000000000..16e2edfca --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/filterfields.md @@ -0,0 +1,58 @@ +--- +title: query.filterFields() function +description: > + The `query.filterFields()` function filters input data by field. +menu: + influxdb_cloud_ref: + name: query.filterFields + parent: Query +weight: 401 +--- + +The `query.filterFields()` function filters input data by field. + +_**Function type:** Transformation_ + +```js +import "experimental/query" + +query.filterFields( + fields: ["exampleField1", "exampleField2"] +) +``` + +## Parameters + +### fields +Fields to filter by. +Must be exact string matches. + +_**Data type:** Array of strings_ + +## Examples + +```js +import "experimental/query" + +query.fromRange(bucket: "telegraf", start: -1h) + |> query.filterFields( + fields: ["used_percent", "available_percent"] + ) +``` + +## Function definition +```js +package query + +filterFields = (tables=<-, fields=[]) => + if length(arr: fields) == 0 then + tables + else + tables + |> filter(fn: (r) => contains(value: r._field, set: fields)) +``` + +_**Used functions:**_ +[contains()](/influxdb/cloud/reference/flux/stdlib/built-in/tests/contains/) +[filter()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/) +[length()](/influxdb/cloud/reference/flux/stdlib/built-in/misc/length/) diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/query/filtermeasurement.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/filtermeasurement.md new file mode 100644 index 000000000..441202867 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/filtermeasurement.md @@ -0,0 +1,53 @@ +--- +title: query.filterMeasurement() function +description: > + The `query.filterMeasurement()` function filters input data by measurement. +menu: + influxdb_cloud_ref: + name: query.filterMeasurement + parent: Query +weight: 401 +--- + +The `query.filterMeasurement()` function filters input data by measurement. + +_**Function type:** Transformation_ + +```js +import "experimental/query" + +query.filterMeasurement( + measurement: "example-measurement" +) +``` + +## Parameters + +### measurement +The name of the measurement to filter by. +Must be an exact string match. + +_**Data type:** String_ + +## Examples + +```js +import "experimental/query" + +query.fromRange(bucket: "example-bucket", start: -1h) + |> query.filterMeasurement( + measurement: "example-measurement" + ) +``` + +## Function definition +```js +package query + +filterMeasurement = (tables=<-, measurement) => + tables + |> filter(fn: (r) => r._measurement == measurement) +``` + +_**Used functions:**_ +[filter()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/) diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/query/fromrange.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/fromrange.md new file mode 100644 index 000000000..92f3ac2dd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/fromrange.md @@ -0,0 +1,76 @@ +--- +title: query.fromRange() function +description: > + The `query.fromRange()` function returns all data from a specified bucket within + given time bounds. +menu: + influxdb_cloud_ref: + name: query.fromRange + parent: Query +weight: 401 +--- + +The `query.fromRange()` function returns all data from a specified bucket within +given time bounds. + +_**Function type:** Input_ + +```js +import "experimental/query" + +query.fromRange( + bucket: "example-bucket", + start: -1h, + stop: now() +) +``` + +## Parameters + +### bucket +The name of the bucket to query. + +_**Data type:** String_ + +### start +The earliest time to include in results. +Results **include** points that match the specified start time. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`.. +Durations are relative to `now()`. + +_**Data type:** Duration | Time | Integer_ + +### stop +The latest time to include in results. +Results **exclude** points that match the specified stop time. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. +Defaults to `now()`. + +_**Data type:** Duration | Time | Integer_ + +## Examples + +```js +import "experimental/query" + +query.fromRange( + bucket: "example-bucket", + start: 2020-01-01T00:00:00Z +) +``` + +## Function definition +```js +package query + +fromRange = (bucket, start, stop=now()) => + from(bucket: bucket) + |> range(start: start, stop: stop) +``` + +_**Used functions:**_ +[from()](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from/) +[range()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range/) diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/query/inbucket.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/inbucket.md new file mode 100644 index 000000000..8fd1ad167 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/query/inbucket.md @@ -0,0 +1,115 @@ +--- +title: query.inBucket() function +description: > + The `query.inBucket()` function queries data from a specified bucket within given + time bounds, filters data by measurement, field, and optional predicate expressions. +menu: + influxdb_cloud_ref: + name: query.inBucket + parent: Query +weight: 401 +--- + +The `query.inBucket()` function queries data from a specified bucket within given +time bounds, filters data by measurement, field, and optional predicate expressions. + +_**Function type:** Input_ + +```js +import "experimental/query" + +query.inBucket( + bucket: "example-bucket", + start: -1h, + stop: now(), + measurement: "example-measurement", + fields: ["exampleField1", "exampleField2"], + predicate: (r) => true +) +``` + +## Parameters + +### bucket +The name of the bucket to query. + +_**Data type:** String_ + +### start +The earliest time to include in results. +Results **include** points that match the specified start time. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. + +_**Data type:** Duration | Time | Integer_ + +### stop +The latest time to include in results. +Results **exclude** points that match the specified stop time. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. +Defaults to `now()`. + +_**Data type:** Duration | Time | Integer_ + +### measurement +The name of the measurement to filter by. +Must be an exact string match. + +_**Data type:** String_ + +### fields +Fields to filter by. +Must be exact string matches. + +_**Data type:** Array of strings_ + +### predicate +A single argument function that evaluates true or false. +Records are passed to the function. +Those that evaluate to `true` are included in the output tables. +Records that evaluate to `null` or `false` are not included in the output tables. +Default is `(r) => true`. + +_**Data type:** Function_ + +## Examples + +##### Query memory data from host1 +```js +import "experimental/query" + +query.inBucket( + bucket: "telegraf", + start: -1h, + measurement: "mem", + fields: ["used_percent", "available_percent"], + predicate: (r) => r.host == "host1" +) +``` + +## Function definition +```js +package query + +inBucket = ( + bucket, + start, + stop=now(), + measurement, + fields=[], + predicate=(r) => true +) => + fromRange(bucket: bucket, start: start, stop: stop) + |> filterMeasurement(measurement) + |> filter(fn: predicate) + |> filterFields(fields) +``` + +_**Used functions:**_ +[filter()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/) +[query.filterFields()](/influxdb/cloud/reference/flux/stdlib/experimental/query/filterfields/) +[query.filterMeasurement()](/influxdb/cloud/reference/flux/stdlib/experimental/query/filtermeasurement/) +[query.fromRange()](/influxdb/cloud/reference/flux/stdlib/experimental/query/fromrange/) diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/set.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/set.md new file mode 100644 index 000000000..88d774612 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/set.md @@ -0,0 +1,70 @@ +--- +title: experimental.set() function +description: > + The `experimental.set()` function sets multiple static column values on all records. +menu: + influxdb_cloud_ref: + name: experimental.set + parent: Experimental +weight: 302 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/set/ +--- + +The `experimental.set()` function sets multiple static column values on all records. +If a column already exists, the function updates the existing value. +If a column does not exist, the function adds it with the specified value. + +_Once sufficiently vetted, `experimental.set()` will replace the existing +[`set()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/set/)._ + +_**Function type:** Transformation_ + +```js +import "experimental" + +experimental.set( + o: {column1: "value1", column2: "value2"} +) +``` + +## Parameters + +### o +A record that defines the columns and values to set. +The key of each key-value pair defines the column name. +The value of each key-value pair defines the column value. + +_**Data type:** Record_ + +## Examples + +### Set values for multiple columns + +##### Example input table +| _time | _field | _value | +|:----- |:------ | ------:| +| 2019-09-16T12:00:00Z | temp | 71.2 | +| 2019-09-17T12:00:00Z | temp | 68.4 | +| 2019-09-18T12:00:00Z | temp | 70.8 | + +##### Example query +```js +import "experimental" + +data + |> experimental.set( + o: { + _field: "temperature", + unit: "°F", + location: "San Francisco" + } + ) +``` + +##### Example output table +| _time | _field | _value | unit | location | +|:----- |:------ | ------:|:----:| -------- | +| 2019-09-16T12:00:00Z | temperature | 71.2 | °F | San Francisco | +| 2019-09-17T12:00:00Z | temperature | 68.4 | °F | San Francisco | +| 2019-09-18T12:00:00Z | temperature | 70.8 | °F | San Francisco | diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/subduration.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/subduration.md new file mode 100644 index 000000000..009869184 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/subduration.md @@ -0,0 +1,58 @@ +--- +title: experimental.subDuration() function +description: > + The `experimental.subDuration()` function subtracts a duration from a time value and + returns a the resulting time value. +menu: + influxdb_cloud_ref: + name: experimental.subDuration + parent: Experimental +weight: 302 +related: + - /influxdb/cloud/reference/flux/stdlib/experimental/addduration/ +--- + +The `experimental.subDuration()` function subtracts a duration from a time value and +returns the resulting time value. + +_**Function type:** Transformation_ + +{{% warn %}} +This function will be removed once duration vectors are implemented. +See [influxdata/flux#413](https://github.com/influxdata/flux/issues/413). +{{% /warn %}} + +```js +import "experimental" + +experimental.subDuration( + d: 12h, + from: now(), +) +``` + +## Parameters + +### d +The duration to subtract. + +_**Data type:** Duration_ + +### from +The time to subtract the [duration](#d) from. + +_**Data type:** Time_ + +## Examples + +### Subtract six hours from a timestamp +```js +import "experimental" + +experimental.subDuration( + d: 6h, + from: 2019-09-16T12:00:00Z, +) + +// Returns 2019-09-16T06:00:00.000000000Z +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/experimental/to.md b/content/influxdb/cloud/reference/flux/stdlib/experimental/to.md new file mode 100644 index 000000000..13f0ce7d1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/experimental/to.md @@ -0,0 +1,105 @@ +--- +title: experimental.to() function +description: > + The `experimental.to()` function writes data to an InfluxDB v2.0 bucket. + The function structures data differently than the built-in `to()` function. +menu: + influxdb_cloud_ref: + name: experimental.to + parent: Experimental +weight: 302 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/outputs/to/ +--- + +The `experimental.to()` function writes data to an InfluxDB v2.0 bucket, but in +a [different structure](#expected-data-structure) than the +[built-in `to()` function](/influxdb/cloud/reference/flux/stdlib/built-in/outputs/to/). + +_**Function type:** Output_ + +```js +import "experimental" + +experimental.to( + bucket: "my-bucket", + org: "my-org" +) + +// OR + +experimental.to( + bucketID: "1234567890", + orgID: "0987654321" +) +``` + +### Expected data structure + +#### Data structure expected by built-in to() +The built-in `to()` function requires `_time`, `_measurement`, `_field`, and `_value` columns. +The `_field` column stores the **field key** and the `_value` column stores the **field value**. + +| _time | _measurement | _field | _value | +| ----- | ------------ | ------ | ------ | +| timestamp | measurement-name | field key | field value | + +#### Data structure expected by experimental to() +`experimental.to()` requires `_time` and `measurement` columns, but field keys +and values are stored in single columns with the **field key** as the **column name** and +the **field value** as the **column value**. + +| _time | _measurement | field_key | +| ----- | ------------ | --------- | +| timestamp | measurement-name | field value | + +If using the built-in `from()` function, use [`pivot()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot/) +to transform data into the structure `experimetnal.to()` expects. +_[See the example below](#use-pivot-to-shape-data-for-experimentalto)._ + +## Parameters + +### bucket +The bucket to write data to. +`bucket` and `bucketID` are mutually exclusive. + +_**Data type:** String_ + +### bucketID +The ID of the bucket to write data to. +`bucketID` and `bucket` are mutually exclusive. + +_**Data type:** String_ + +### org +The organization name of the specified [`bucket`](#bucket). +Only required when writing to a different organization or a remote host. +`org` and `orgID` are mutually exclusive. + +_**Data type:** String_ + +### orgID +The organization ID of the specified [`bucket`](#bucket). +Only required when writing to a different organization or a remote host. +`orgID` and `org` are mutually exclusive. + +_**Data type:** String_ + + +## Examples + +##### Use pivot() to shape data for experimental.to() +```js +import "experimental" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> pivot( + rowKey:["_time"], + columnKey: ["_field"], + valueColumn: "_value") + |> experimental.to( + bucket: "bucket-name", + org: "org-name" + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/http/_index.md b/content/influxdb/cloud/reference/flux/stdlib/http/_index.md new file mode 100644 index 000000000..83a68b7f6 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/http/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux HTTP package +list_title: HTTP package +description: > + The Flux HTTP package provides functions for transferring data using the HTTP protocol. + Import the `http` package. +aliases: + - /influxdb/cloud/reference/flux/functions/http/ +menu: + influxdb_cloud_ref: + name: HTTP + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, http, package] +--- + +The Flux HTTP package provides functions for transferring data using the HTTP protocol. +Import the `http` package: + +```js +import "http" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/http/basicauth.md b/content/influxdb/cloud/reference/flux/stdlib/http/basicauth.md new file mode 100644 index 000000000..ce80b0f04 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/http/basicauth.md @@ -0,0 +1,58 @@ +--- +title: http.basicAuth() function +description: > + The `http.basicAuth()` function returns a Base64-encoded basic authentication + header using a specified username and password combination. +aliases: + - /influxdb/cloud/reference/flux/functions/http/basicauth/ +menu: + influxdb_cloud_ref: + name: http.basicAuth + parent: HTTP +weight: 202 +--- + +The `http.basicAuth()` function returns a Base64-encoded basic authentication +header using a specified username and password combination. + +_**Function type:** Miscellaneous_ + +```js +import "http" + +http.basicAuth( + u: "username", + p: "passw0rd" +) + +// Returns "Basic dXNlcm5hbWU6cGFzc3cwcmQ=" +``` + +## Parameters + +### u +The username to use in the basic authentication header. + +_**Data type:** String_ + +### p +The password to use in the basic authentication header. + +_**Data type:** String_ + +## Examples + +##### Set a basic authentication header in an HTTP POST request +```js +import "monitor" +import "http" + +username = "myawesomeuser" +password = "mySupErSecRetPasSW0rD" + +http.post( + url: "http://myawesomesite.com/api/", + headers: {Authorization: http.basicAuth(u:username, p:password)}, + data: bytes(v: "something I want to send.") +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/http/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/http/endpoint.md new file mode 100644 index 000000000..bdeaf91fc --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/http/endpoint.md @@ -0,0 +1,50 @@ +--- +title: http.endpoint() function +description: > + The `http.endpoint()` function sends output data to an HTTP URL using the POST request method. +aliases: + - /influxdb/cloud/reference/flux/functions/http/endpoint/ +menu: + influxdb_cloud_ref: + name: http.endpoint + parent: HTTP +weight: 202 +influxdb/v2.0/tags: [endpoints] +--- + +The `http.endpoint()` function sends output data to an HTTP URL using the POST request method. + +_**Function type:** Output_ + +```js +import "http" + +http.endpoint( + url: "http://localhost:1234/" +) +``` + +## Parameters + +### url +The URL to POST to. + +_**Data type:** String_ + +### mapFn +A function that builds the record used to generate the POST request. + +{{% note %}} +_You should rarely need to override the default `mapFn` parameter. +To see the default `mapFn` value or for insight into possible overrides, view the +[`http.endpoint()` source code](https://github.com/influxdata/flux/blob/master/stdlib/http/http.flux)._ +{{% /note %}} + +_**Data type:** Function_ + +The returned record must include the following fields: + +- `headers` +- `data` + +_For more information, see [`http.post()`](/influxdb/cloud/reference/flux/stdlib/http/post/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/http/pathescape.md b/content/influxdb/cloud/reference/flux/stdlib/http/pathescape.md new file mode 100644 index 000000000..224af18f5 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/http/pathescape.md @@ -0,0 +1,45 @@ +--- +title: http.pathEscape() function +description: > + The `http.pathEscape()` function escapes special characters in a string (including `/`) + and replaces non-ASCII characters with hexadecimal representations (`%XX`). +menu: + influxdb_cloud_ref: + name: http.pathEscape + parent: HTTP +weight: 202 +--- + +The `http.pathEscape()` function escapes special characters in a string (including `/`) +and replaces non-ASCII characters with hexadecimal representations (`%XX`). + +_**Function type:** Transformation_ + +```js +import "http" + +http.pathEscape( + inputString: "/this/is/an/example-path.html" +) + +// Returns %2Fthis%2Fis%2Fan%2Fexample-path.html +``` + +## Parameters + +### inputString +The string to escape. + +_**Data type:** String_ + +## Examples + +##### URL-encode strings in a stream of tables +```js +import "http" + +data + |> map(fn: (r) => ({ r with + path: http.pathEscape(inputString: r.path) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/http/post.md b/content/influxdb/cloud/reference/flux/stdlib/http/post.md new file mode 100644 index 000000000..53b4dc43d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/http/post.md @@ -0,0 +1,78 @@ +--- +title: http.post() function +description: > + The `http.post()` function submits an HTTP POST request to the specified URL with headers and data. + The HTTP status code is returned. +aliases: + - /influxdb/cloud/reference/flux/functions/http/post/ +menu: + influxdb_cloud_ref: + name: http.post + parent: HTTP +weight: 202 +--- + +The `http.post()` function submits an HTTP POST request to the specified URL with +headers and data and returns the HTTP status code. + +_**Function type:** Output_ + +```js +import "http" + +http.post( + url: "http://localhost:8086/", + headers: {x:"a", y:"b", z:"c"}, + data: bytes(v: "body") +) +``` + +## Parameters + +### url +The URL to POST to. + +_**Data type:** String_ + +### headers +Headers to include with the POST request. + +_**Data type:** Record_ + +{{% note %}} +##### Header keys with special characters +Wrap header keys that contain special characters in double quotes (`""`). + +```js +{"key-1": "value 1", "key#2": "value 2" } +``` +{{% /note %}} + +### data +The data body to include with the POST request. + +_**Data type:** Bytes_ + +## Examples + +##### Send the last reported status to a URL +```js +import "json" +import "http" + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> findColumn(fn: (key) => true, column: "_level") + +http.post( + url: "http://myawsomeurl.com/api/notify", + headers: { + Authorization: "Bearer mySuPerSecRetTokEn", + "Content-type": "application/json" + }, + data: json.encode(v: lastReported[0]) +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/_index.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/_index.md new file mode 100644 index 000000000..1b8ce4287 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/_index.md @@ -0,0 +1,26 @@ +--- +title: Flux InfluxDB schema package +list_title: InfluxDB schema package +description: > + The Flux InfluxDB schema package provides functions for exploring your InfluxDB data schema. + Import the `influxdata/influxdb/schema` package. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/ +menu: + influxdb_cloud_ref: + name: InfluxDB Schema + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, schema, package] +introduced: 0.88.0 +--- + +The Flux InfluxDB schema package provides functions for exploring your InfluxDB data schema. + +Import the `influxdata/influxdb/schema` package: + +```js +import "influxdata/influxdb/schema" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldkeys.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldkeys.md new file mode 100644 index 000000000..1a2bc2831 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldkeys.md @@ -0,0 +1,70 @@ +--- +title: schema.fieldKeys() function +description: The `schema.fieldKeys()` function returns field keys in a bucket. +menu: + influxdb_cloud_ref: + name: schema.fieldKeys + parent: InfluxDB Schema +weight: 301 +influxdb/v2.0/tags: [fields] +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/fieldkeys +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-field-keys, SHOW FIELD KEYS in InfluxQL +introduced: 0.88.0 +--- + +The `schema.fieldKeys()` function returns [field keys](/influxdb/cloud/reference/glossary/#field-key) in a bucket. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/schema" + +schema.fieldKeys( + bucket: "example-bucket", + predicate: (r) => true, + start: -30d +) +``` + +## Parameters + +### bucket +The bucket to list field keys from. + +_**Data type:** String_ + +### predicate +The predicate function that filters field keys. +_Defaults to `(r) => true`._ + +_**Data type:** Function_ + +### start +The oldest time to include in results. +_Defaults to `-30d`._ + +Relative start times are defined using negative durations. +Negative durations are relative to now. +Absolute start times are defined using [time values](/influxdb/cloud/reference/flux/language/types/#time-types). + +_**Data type:** Duration_ + +## Examples +```js +import "influxdata/influxdb/schema" + +schema.fieldKeys(bucket: "my-bucket") +``` + +## Function definition +```js +package schema + +fieldKeys = (bucket, predicate=(r) => true, start=-30d) => + tagValues(bucket: bucket, tag: "_field", predicate: predicate, start: start) +``` + +_**Used functions:** +[schema.tagValues](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldsascols.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldsascols.md new file mode 100644 index 000000000..d54defdbf --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldsascols.md @@ -0,0 +1,55 @@ +--- +title: schema.fieldsAsCols() function +description: The schema.fieldsAsCols() function pivots a table to automatically align fields within each input table that have the same timestamp. +aliases: + - /influxdb/cloud/reference/flux/functions/inputs/fromrows + - /influxdb/cloud/reference/flux/functions/transformations/influxfieldsascols + - /influxdb/cloud/reference/flux/functions/influxdb-v1/fieldsascols/ + - /influxdb/cloud/reference/flux/functions/influxdb-schema/fieldsascols/ +menu: + influxdb_cloud_ref: + name: schema.fieldsAsCols + parent: InfluxDB Schema +weight: 301 +introduced: 0.88.0 +--- + +The `schema.fieldsAsCols()` function is a special application of the +[`pivot()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot/) +function that pivots on `_field` and `_time` columns to aligns fields within each +input table that have the same timestamp. + +_**Function type:** Transformation_ + +```js +import "influxdata/influxdb/schema" + +schema.fieldsAsCols() +``` + +## Examples +```js +import "influxdata/influxdb/schema" + +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "cpu") + |> schema.fieldsAsCols() + |> keep(columns: ["_time", "cpu", "usage_idle", "usage_user"]) +``` + +## Function definition +```js +package schema + +fieldsAsCols = (tables=<-) => + tables + |> pivot( + rowKey:["_time"], + columnKey: ["_field"], + valueColumn: "_value" + ) +``` + +_**Used functions:** +[pivot()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementfieldkeys.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementfieldkeys.md new file mode 100644 index 000000000..ae95248ff --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementfieldkeys.md @@ -0,0 +1,72 @@ +--- +title: schema.measurementFieldKeys() function +description: The `schema.measurementFieldKeys()` function returns a list of fields in a measurement. +menu: + influxdb_cloud_ref: + name: schema.measurementFieldKeys + parent: InfluxDB Schema +weight: 301 +influxdb/v2.0/tags: [fields] +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/measurementfieldkeys/ +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-field-keys, SHOW FIELD KEYS in InfluxQL +introduced: 0.88.0 +--- + +The `schema.measurementFieldKeys()` function returns a list of fields in a measurement. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/schema" + +schema.measurementFieldKeys( + bucket: "example-bucket", + measurement: "example-measurement", + start: -30d +) +``` + +## Parameters + +### bucket +Bucket to retrieve field keys from. + +_**Data type:** String_ + +### measurement +Measurement to list field keys from. + +_**Data type:** String_ + +### start +Oldest time to include in results. +_Defaults to `-30d`._ + +Relative start times are defined using negative durations. +Negative durations are relative to now. +Absolute start times are defined using [time values](/influxdb/cloud/reference/flux/language/types/#time-types). + +_**Data type:** Duration_ + +## Examples +```js +import "influxdata/influxdb/schema" + +schema.measurementFieldKeys( + bucket: "telegraf", + measurement: "cpu", +) +``` + +## Function definition +```js +package schema + +measurementFieldKeys = (bucket, measurement, start=-30d) => + fieldKeys(bucket: bucket, predicate: (r) => r._measurement == measurement, start: start) +``` + +_**Used functions:** +[schema.fieldKeys](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldkeys/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurements.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurements.md new file mode 100644 index 000000000..a5b7323ae --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurements.md @@ -0,0 +1,43 @@ +--- +title: schema.measurements() function +description: The schema.measurements() function returns a list of measurements in a specific bucket. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/measurements/ +menu: + influxdb_cloud_ref: + name: schema.measurements + parent: InfluxDB Schema +weight: 301 +influxdb/v2.0/tags: [measurements] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-measurements, SHOW MEASUREMENTS in InfluxQL +introduced: 0.88.0 +--- + +The `schema.measurements()` function returns a list of measurements in a specific bucket. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/schema" + +schema.measurements(bucket: "example-bucket") +``` + +## Parameters + +### bucket +Bucket to retrieve measurements from. + +_**Data type:** String_ + +## Function definition +```js +package schema + +measurements = (bucket) => + tagValues(bucket: bucket, tag: "_measurement") +``` + +_**Used functions:** +[schema.tagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagkeys.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagkeys.md new file mode 100644 index 000000000..c99d88940 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagkeys.md @@ -0,0 +1,54 @@ +--- +title: schema.measurementTagKeys() function +description: The schema.measurementTagKeys() function returns a list of tag keys for a specific measurement. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/measurementtagkeys/ +menu: + influxdb_cloud_ref: + name: schema.measurementTagKeys + parent: InfluxDB Schema +weight: 301 +influxdb/v2.0/tags: [tags] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-tag-keys, SHOW TAG KEYS in InfluxQL +introduced: 0.88.0 +--- + +The `schema.measurementTagKeys()` function returns a list of tag keys for a specific measurement. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/schema" + +schema.measurementTagKeys( + bucket: "example-bucket", + measurement: "cpu" +) +``` + +## Parameters + +### bucket +Bucket to return tag keys from for a specific measurement. + +_**Data type:** String_ + +### measurement +Measurement to return tag keys from. + +_**Data type:** String_ + +## Function definition +```js +package schema + +measurementTagKeys = (bucket, measurement) => + tagKeys( + bucket: bucket, + predicate: (r) => r._measurement == measurement + ) +``` + +_**Used functions:** +[schema.tagKeys()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagkeys)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagvalues.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagvalues.md new file mode 100644 index 000000000..753a26115 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagvalues.md @@ -0,0 +1,64 @@ +--- +title: schema.measurementTagValues() function +description: The schema.measurementTagValues() function returns a list of tag values for a specific measurement. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/measurementtagvalues/ +menu: + influxdb_cloud_ref: + name: schema.measurementTagValues + parent: InfluxDB Schema +weight: 301 +influxdb/v2.0/tags: [tags] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-tag-values, SHOW TAG VALUES in InfluxQL +introduced: 0.88.0 +--- + +The `schema.measurementTagValues()` function returns a list of tag values for a specific measurement. +The return value is always a single table with a single column, `_value`. + + + +```js +import "influxdata/influxdb/schema" + +schema.measurementTagValues( + bucket: "example-bucket", + measurement: "cpu", + tag: "host" +) +``` + +## Parameters + +### bucket +Bucket to return tag values from for a specific measurement. + +_**Data type:** String_ + +### measurement +Measurement to return tag values from. + +_**Data type:** String_ + +### tag +Tag to return all unique values from. + +_**Data type:** String_ + + +## Function definition +```js +package schema + +measurementTagValues = (bucket, measurement, tag) => + tagValues( + bucket: bucket, + tag: tag, + predicate: (r) => r._measurement == measurement + ) +``` + +_**Used functions:** +[schema.tagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagkeys.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagkeys.md new file mode 100644 index 000000000..ed497b195 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagkeys.md @@ -0,0 +1,81 @@ +--- +title: schema.tagKeys() function +description: The schema.tagKeys() function returns a list of tag keys for all series that match the predicate. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/tagkeys/ +menu: + influxdb_cloud_ref: + name: schema.tagKeys + parent: InfluxDB Schema +weight: 301 +influxdb/v2.0/tags: [tags] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-tag-keys, SHOW TAG KEYS in InfluxQL +introduced: 0.88.0 +--- + +The `schema.tagKeys()` function returns a list of tag keys for all series that match the [`predicate`](#predicate). +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/schema" + +schema.tagKeys( + bucket: "example-bucket", + predicate: (r) => true, + start: -30d +) +``` + +## Parameters + +### bucket +Bucket to return tag keys from. + +_**Data type:** String_ + +### predicate +Predicate function that filters tag keys. +_Defaults to `(r) => true`._ + +_**Data type:** Function_ + +### start +Oldest time to include in results. +_Defaults to `-30d`._ + +Relative start times are defined using negative durations. +Negative durations are relative to now. +Absolute start times are defined using [time values](/influxdb/cloud/reference/flux/language/types/#time-types). + +_**Data type:** Duration_ + +## Examples +```js +import "influxdata/influxdb/schema" + +schema.tagKeys(bucket: "my-bucket") +``` + + +## Function definition +```js +package schema + +tagKeys = (bucket, predicate=(r) => true, start=-30d) => + from(bucket: bucket) + |> range(start: start) + |> filter(fn: predicate) + |> keys() + |> keep(columns: ["_value"]) + |> distinct() +``` + +_**Used functions:** +[from](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from/), +[range](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range/), +[filter](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/), +[keys](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keys/), +[keep](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keep/), +[distinct](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/distinct/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues.md new file mode 100644 index 000000000..418b106ad --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues.md @@ -0,0 +1,89 @@ +--- +title: schema.tagValues() function +description: The `schema.tagValues()` function returns a list unique values for a given tag. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/tagvalues/ +menu: + influxdb_cloud_ref: + name: schema.tagValues + parent: InfluxDB Schema +weight: 301 +influxdb/v2.0/tags: [tags] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-tag-values, SHOW TAG VALUES in InfluxQL +introduced: 0.88.0 +--- + +The `schema.tagValues()` function returns a list of unique values for a given tag. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/schema" + +schema.tagValues( + bucket: "example-bucket", + tag: "host", + predicate: (r) => true, + start: -30d +) +``` + +## Parameters + +### bucket +Bucket to return unique tag values from. + +_**Data type:** String_ + +### tag +Tag to return unique values from. + +_**Data type:** String_ + +### predicate +Predicate function that filters tag values. +_Defaults to `(r) => true`._ + +_**Data type:** Function_ + +### start +Oldest time to include in results. +_Defaults to `-30d`._ + +Relative start times are defined using negative durations. +Negative durations are relative to now. +Absolute start times are defined using [time values](/influxdb/cloud/reference/flux/language/types/#time-types). + +_**Data type:** Duration_ + +## Examples +```js +import "influxdata/influxdb/schema" + +schema.tagValues( + bucket: "my-bucket", + tag: "host", +) +``` + +## Function definition +```js +package schema + +tagValues = (bucket, tag, predicate=(r) => true, start=-30d) => + from(bucket: bucket) + |> range(start: start) + |> filter(fn: predicate) + |> group(columns: [tag]) + |> distinct(column: tag) + |> keep(columns: ["_value"]) +``` + +_**Used functions:** +[from](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from/), +[range](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range/), +[filter](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/), +[group](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group/), +[distinct](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/distinct/), +[keep](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keep/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-tasks/_index.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-tasks/_index.md new file mode 100644 index 000000000..5261b948f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-tasks/_index.md @@ -0,0 +1,44 @@ +--- +title: Flux InfluxDB Tasks package +list_title: InfluxDB Tasks package +description: > + The Flux InfluxDB Tasks package provides options and functions for working with + [InfluxDB tasks](/influxdb/cloud/process-data/get-started/). + Import the `influxdata/influxdb/tasks` package. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/ +menu: + influxdb_cloud_ref: + name: InfluxDB Tasks + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, tasks, package] +related: + - /influxdb/cloud/process-data/get-started/ +--- + +The Flux InfluxDB Tasks package provides options and functions for working with +[InfluxDB tasks](/influxdb/cloud/process-data/get-started/). +Import the `influxdata/influxdb/tasks` package: + +```js +import "influxdata/influxdb/tasks" +``` + +## Options +The InfluxDB Tasks package provides the following options: + +#### lastSuccessTime +Define the time of the last successful task run. +_Only use this option to override the time of the last successful run provided by +the InfluxDB task engine._ + +```js +import "influxdata/influxdb/tasks" + +option tasks.lastSuccessTime = 0000-01-01T00:00:00Z +``` + +## Functions + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-tasks/lastsuccess.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-tasks/lastsuccess.md new file mode 100644 index 000000000..551da8c58 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-tasks/lastsuccess.md @@ -0,0 +1,41 @@ +--- +title: tasks.lastSuccess() function +description: The `tasks.lastSuccess()` function returns ... +menu: + influxdb_cloud_ref: + name: tasks.lastSuccess + parent: InfluxDB Tasks +weight: 301 +--- + +The `tasks.lastSuccess()` function returns the time of last successful run of the +InfluxDB task or the value of the `orTime` parameter if the task has never successfully run. + +```js +import "influxdata/influxdb/tasks" + +tasks.lastSuccess(orTime: 2020-01-01T00:00:00Z) +``` + +## Parameters + +### orTime +The default time value returned if the task has never successfully run. + +_**Data type:** Time | Duration_ + +## Examples + +##### Query data since the last successful task run +```js +import "influxdata/influxdb/tasks" + +options task = { + name: "Example task", + every: 30m +} + +from(bucket: "example-bucket") + |> range(start: tasks.lastSuccess(orTime: -task.every)) + // ... +``` \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/_index.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/_index.md new file mode 100644 index 000000000..c7b72fa20 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/_index.md @@ -0,0 +1,46 @@ +--- +title: Flux InfluxDB v1 package +list_title: InfluxDB v1 package +description: > + The Flux InfluxDB v1 package provides functions for managing data from an InfluxDB v1.x + database or structured using the InfluxDB v1 data structure. + Import the `influxdata/influxdb/v1` package. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/ +menu: + influxdb_cloud_ref: + name: InfluxDB v1 + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, influxdb-v1, package] +introduced: 0.16.0 +--- + +InfluxDB v1 Flux functions provide tools for managing data from an InfluxDB v1.x +database or structured using the InfluxDB v1 data structure. +Import the `influxdata/influxdb/v1` package: + +```js +import "influxdata/influxdb/v1" +``` + +{{< children type="functions" show="pages" >}} + +{{% warn %}} +#### Deprecated functions +In **Flux 0.88.0**, the following InfluxDB v1 package functions moved to the +[InfluxDB schema package](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/). +These functions are still available in the `v1` package for backwards compatibility, +but are deprecated in favor of `schema`. + +| Deprecated v1 function | → | Corresponding schema function | +|:------------------- |:-:|:------------------------ | +| **v1.fieldKeys()** | → | [schema.fieldKeys()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldkeys/) | +| **v1.fieldsAsCols()** | → | [schema.fieldsAsCols()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldsascols/) | +| **v1.measurementFieldKeys()** | → | [schema.measurementFieldKeys()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementfieldkeys/) | +| **v1.measurements()** | → | [schema.measurements()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurements/) | +| **v1.measurementTagKeys()** | → | [schema.measurementTagKeys()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagkeys/) | +| **v1.measurementTagValues()** | → | [schema.measurementTagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagvalues/) | +| **v1.tagKeys()** | → | [schema.tagKeys()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagkeys/) | +| **v1.tagValues()** | → | [schema.tagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues/) | +{{% /warn %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/databases.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/databases.md new file mode 100644 index 000000000..7fd74ea5e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/databases.md @@ -0,0 +1,26 @@ +--- +title: v1.databases() function +description: The `v1.databases()` function returns a list of databases in an InfluxDB 1.7+ instance. +menu: + influxdb_cloud_ref: + name: v1.databases + parent: InfluxDB v1 +weight: 301 +related: + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-databases, SHOW DATABASES in InfluxQL +--- + +The `v1.databases()` function returns a list of databases in an **InfluxDB 1.7+ instance**. + +```js +import "influxdata/influxdb/v1" + +v1.databases() +``` + +Output includes the following columns: + +- **databaseName:** Database name _(string)_ +- **retentionPolicy:** Retention policy name _(string)_ +- **retentionPeriod:** Retention period in nanoseconds _(integer)_ +- **default:** Default retention policy for database _(boolean)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/fieldkeys.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/fieldkeys.md new file mode 100644 index 000000000..7cc87120e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/fieldkeys.md @@ -0,0 +1,76 @@ +--- +title: v1.fieldKeys() function +description: The `v1.fieldKeys()` function returns field keys in a bucket. +menu: + influxdb_cloud_ref: + name: v1.fieldKeys + parent: InfluxDB v1 +weight: 301 +influxdb/v2.0/tags: [fields] +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/fieldkeys +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-field-keys, SHOW FIELD KEYS in InfluxQL +introduced: 0.68.0 +deprecated: 0.88.0 +--- + +{{% warn %}} +`v1.fieldKeys()` was deprecated in **Flux v0.88.0** in favor of +[`schema.fieldKeys()`](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldkeys/). +{{% /warn %}} + +The `v1.fieldKeys()` function returns [field keys](/influxdb/cloud/reference/glossary/#field-key) in a bucket. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/v1" + +v1.fieldKeys( + bucket: "example-bucket", + predicate: (r) => true, + start: -30d +) +``` + +## Parameters + +### bucket +The bucket to list field keys from. + +_**Data type:** String_ + +### predicate +The predicate function that filters field keys. +_Defaults to `(r) => true`._ + +_**Data type:** Function_ + +### start +The oldest time to include in results. +_Defaults to `-30d`._ + +Relative start times are defined using negative durations. +Negative durations are relative to now. +Absolute start times are defined using [time values](/influxdb/cloud/reference/flux/language/types/#time-types). + +_**Data type:** Duration_ + +## Examples +```js +import "influxdata/influxdb/v1" + +v1.fieldKeys(bucket: "my-bucket") +``` + +## Function definition +```js +package v1 + +fieldKeys = (bucket, predicate=(r) => true, start=-30d) => + tagValues(bucket: bucket, tag: "_field", predicate: predicate, start: start) +``` + +_**Used functions:** +[v1.tagValues](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/fieldsascols.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/fieldsascols.md new file mode 100644 index 000000000..34d5a76a5 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/fieldsascols.md @@ -0,0 +1,61 @@ +--- +title: v1.fieldsAsCols() function +description: The v1.fieldsAsCols() function pivots a table to automatically align fields within each input table that have the same timestamp. +aliases: + - /influxdb/cloud/reference/flux/functions/inputs/fromrows + - /influxdb/cloud/reference/flux/functions/transformations/influxfieldsascols + - /influxdb/cloud/reference/flux/functions/influxdb-v1/fieldsascols/ + - /influxdb/cloud/reference/flux/functions/influxdb-schema/fieldsascols/ +menu: + influxdb_cloud_ref: + name: v1.fieldsAsCols + parent: InfluxDB v1 +weight: 301 +introduced: 0.16.0 +deprecated: 0.88.0 +--- + +{{% warn %}} +`v1.fieldsAsCols()` was deprecated in **Flux v0.88.0** in favor of +[`schema.fieldsAsCols()`](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldsascols/). +{{% /warn %}} + +The `v1.fieldsAsCols()` function is a special application of the +[`pivot()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot/) +function that pivots on `_field` and `_time` columns to aligns fields within each +input table that have the same timestamp. and resemble InfluxDB 1.x query output. + +_**Function type:** Transformation_ + +```js +import "influxdata/influxdb/v1" + +v1.fieldsAsCols() +``` + +## Examples +```js +import "influxdata/influxdb/v1" + +from(bucket:"example-bucket") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "cpu") + |> v1.fieldsAsCols() + |> keep(columns: ["_time", "cpu", "usage_idle", "usage_user"]) +``` + +## Function definition +```js +package v1 + +fieldsAsCols = (tables=<-) => + tables + |> pivot( + rowKey:["_time"], + columnKey: ["_field"], + valueColumn: "_value" + ) +``` + +_**Used functions:** +[pivot()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/pivot)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementfieldkeys.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementfieldkeys.md new file mode 100644 index 000000000..bd5e17321 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementfieldkeys.md @@ -0,0 +1,78 @@ +--- +title: v1.measurementFieldKeys() function +description: The `v1.measurementFieldKeys()` function returns a list of fields in a measurement. +menu: + influxdb_cloud_ref: + name: v1.measurementFieldKeys + parent: InfluxDB v1 +weight: 301 +influxdb/v2.0/tags: [fields] +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/measurementfieldkeys/ +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-field-keys, SHOW FIELD KEYS in InfluxQL +introduced: 0.68.0 +deprecated: 0.88.0 +--- + +{{% warn %}} +`v1.measurementFieldKeys()` was deprecated in **Flux v0.88.0** in favor of +[`schema.measurementFieldKeys()`](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementfieldkeys/). +{{% /warn %}} + +The `v1.measurementFieldKeys()` function returns a list of fields in a measurement. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/v1" + +v1.measurementFieldKeys( + bucket: "example-bucket", + measurement: "example-measurement", + start: -30d +) +``` + +## Parameters + +### bucket +Bucket to retrieve field keys from. + +_**Data type:** String_ + +### measurement +Measurement to list field keys from. + +_**Data type:** String_ + +### start +Oldest time to include in results. +_Defaults to `-30d`._ + +Relative start times are defined using negative durations. +Negative durations are relative to now. +Absolute start times are defined using [time values](/influxdb/cloud/reference/flux/language/types/#time-types). + +_**Data type:** Duration_ + +## Examples +```js +import "influxdata/influxdb/v1" + +v1.measurementFieldKeys( + bucket: "telegraf", + measurement: "cpu", +) +``` + +## Function definition +```js +package v1 + +measurementFieldKeys = (bucket, measurement, start=-30d) => + fieldKeys(bucket: bucket, predicate: (r) => r._measurement == measurement, start: start) +``` + +_**Used functions:** +[v1.fieldKeys](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/fieldkeys/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurements.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurements.md new file mode 100644 index 000000000..33317b30f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurements.md @@ -0,0 +1,49 @@ +--- +title: v1.measurements() function +description: The v1.measurements() function returns a list of measurements in a specific bucket. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/measurements/ +menu: + influxdb_cloud_ref: + name: v1.measurements + parent: InfluxDB v1 +weight: 301 +influxdb/v2.0/tags: [measurements] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-measurements, SHOW MEASUREMENTS in InfluxQL +introduced: 0.16.0 +deprecated: 0.88.0 +--- + +{{% warn %}} +`v1.measurements()` was deprecated in **Flux v0.88.0** in favor of +[`schema.measurements()`](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurements/). +{{% /warn %}} + +The `v1.measurements()` function returns a list of measurements in a specific bucket. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/v1" + +v1.measurements(bucket: "example-bucket") +``` + +## Parameters + +### bucket +Bucket to retrieve measurements from. + +_**Data type:** String_ + +## Function definition +```js +package v1 + +measurements = (bucket) => + tagValues(bucket: bucket, tag: "_measurement") +``` + +_**Used functions:** +[v1.tagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagkeys.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagkeys.md new file mode 100644 index 000000000..abb6ee87f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagkeys.md @@ -0,0 +1,60 @@ +--- +title: v1.measurementTagKeys() function +description: The v1.measurementTagKeys() function returns a list of tag keys for a specific measurement. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/measurementtagkeys/ +menu: + influxdb_cloud_ref: + name: v1.measurementTagKeys + parent: InfluxDB v1 +weight: 301 +influxdb/v2.0/tags: [tags] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-tag-keys, SHOW TAG KEYS in InfluxQL +introduced: 0.16.0 +deprecated: 0.88.0 +--- + +{{% warn %}} +`v1.measurementTagKeys()` was deprecated in **Flux v0.88.0** in favor of +[`schema.measurementTagKeys()`](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagkeys/). +{{% /warn %}} + +The `v1.measurementTagKeys()` function returns a list of tag keys for a specific measurement. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/v1" + +v1.measurementTagKeys( + bucket: "example-bucket", + measurement: "cpu" +) +``` + +## Parameters + +### bucket +Bucket to return tag keys from for a specific measurement. + +_**Data type:** String_ + +### measurement +Measurement to return tag keys from. + +_**Data type:** String_ + +## Function definition +```js +package v1 + +measurementTagKeys = (bucket, measurement) => + tagKeys( + bucket: bucket, + predicate: (r) => r._measurement == measurement + ) +``` + +_**Used functions:** +[v1.tagKeys()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagkeys)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagvalues.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagvalues.md new file mode 100644 index 000000000..4c2ee7974 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagvalues.md @@ -0,0 +1,68 @@ +--- +title: v1.measurementTagValues() function +description: The v1.measurementTagValues() function returns a list of tag values for a specific measurement. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/measurementtagvalues/ +menu: + influxdb_cloud_ref: + name: v1.measurementTagValues + parent: InfluxDB v1 +weight: 301 +influxdb/v2.0/tags: [tags] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-tag-values, SHOW TAG VALUES in InfluxQL +introduced: 0.16.0 +deprecated: 0.88.0 +--- + +{{% warn %}} +`v1.measurementTagValues()` was deprecated in **Flux v0.88.0** in favor of +[`schema.measurementTagValues()`](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/measurementtagvalues/). +{{% /warn %}} + +The `v1.measurementTagValues()` function returns a list of tag values for a specific measurement. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/v1" + +v1.measurementTagValues( + bucket: "example-bucket", + measurement: "cpu", + tag: "host" +) +``` + +## Parameters + +## bucket +Bucket to return tag values from for a specific measurement. + +_**Data type:** String_ + +### measurement +Measurement to return tag values from. + +_**Data type:** String_ + +### tag +Tag to return all unique values from. + +_**Data type:** String_ + + +## Function definition +```js +package v1 + +measurementTagValues = (bucket, measurement, tag) => + tagValues( + bucket: bucket, + tag: tag, + predicate: (r) => r._measurement == measurement + ) +``` + +_**Used functions:** +[v1.tagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagkeys.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagkeys.md new file mode 100644 index 000000000..77ec0c5dd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagkeys.md @@ -0,0 +1,87 @@ +--- +title: v1.tagKeys() function +description: The v1.tagKeys() function returns a list of tag keys for all series that match the predicate. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/tagkeys/ +menu: + influxdb_cloud_ref: + name: v1.tagKeys + parent: InfluxDB v1 +weight: 301 +influxdb/v2.0/tags: [tags] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-tag-keys, SHOW TAG KEYS in InfluxQL +introduced: 0.16.0 +deprecated: 0.88.0 +--- + +{{% warn %}} +`v1.tagkeys()` was deprecated in **Flux v0.88.0** in favor of +[`schema.tagkeys()`](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagkeys/). +{{% /warn %}} + +The `v1.tagKeys()` function returns a list of tag keys for all series that match the [`predicate`](#predicate). +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/v1" + +v1.tagKeys( + bucket: "example-bucket", + predicate: (r) => true, + start: -30d +) +``` + +## Parameters + +### bucket +Bucket to return tag keys from. + +_**Data type:** String_ + +### predicate +Predicate function that filters tag keys. +_Defaults to `(r) => true`._ + +_**Data type:** Function_ + +### start +Oldest time to include in results. +_Defaults to `-30d`._ + +Relative start times are defined using negative durations. +Negative durations are relative to now. +Absolute start times are defined using [time values](/influxdb/cloud/reference/flux/language/types/#time-types). + +_**Data type:** Duration_ + +## Examples +```js +import "influxdata/influxdb/v1" + +v1.tagKeys(bucket: "my-bucket") +``` + + +## Function definition +```js +package v1 + +tagKeys = (bucket, predicate=(r) => true, start=-30d) => + from(bucket: bucket) + |> range(start: start) + |> filter(fn: predicate) + |> keys() + |> keep(columns: ["_value"]) + |> distinct() +``` + +_**Used functions:** +[from](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from/), +[range](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range/), +[filter](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/), +[keys](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keys/), +[keep](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keep/), +[distinct](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/distinct/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagvalues.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagvalues.md new file mode 100644 index 000000000..7688520bc --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagvalues.md @@ -0,0 +1,95 @@ +--- +title: v1.tagValues() function +description: The `v1.tagValues()` function returns a list unique values for a given tag. +aliases: + - /influxdb/cloud/reference/flux/functions/influxdb-v1/tagvalues/ +menu: + influxdb_cloud_ref: + name: v1.tagValues + parent: InfluxDB v1 +weight: 301 +influxdb/v2.0/tags: [tags] +related: + - /influxdb/cloud/query-data/flux/explore-schema/ + - /{{< latest "influxdb" "v1" >}}/query_language/schema_exploration#show-tag-values, SHOW TAG VALUES in InfluxQL +introduced: 0.16.0 +deprecated: 0.88.0 +--- + +{{% warn %}} +`v1.tagValues()` was deprecated in **Flux v0.88.0** in favor of +[`schema.tagValues()`](/influxdb/cloud/reference/flux/stdlib/influxdb-schema/tagvalues/). +{{% /warn %}} + +The `v1.tagValues()` function returns a list of unique values for a given tag. +The return value is always a single table with a single column, `_value`. + +```js +import "influxdata/influxdb/v1" + +v1.tagValues( + bucket: "example-bucket", + tag: "host", + predicate: (r) => true, + start: -30d +) +``` + +## Parameters + +### bucket +Bucket to return unique tag values from. + +_**Data type:** String_ + +### tag +Tag to return unique values from. + +_**Data type:** String_ + +### predicate +Predicate function that filters tag values. +_Defaults to `(r) => true`._ + +_**Data type:** Function_ + +### start +Oldest time to include in results. +_Defaults to `-30d`._ + +Relative start times are defined using negative durations. +Negative durations are relative to now. +Absolute start times are defined using [time values](/influxdb/cloud/reference/flux/language/types/#time-types). + +_**Data type:** Duration_ + +## Examples +```js +import "influxdata/influxdb/v1" + +v1.tagValues( + bucket: "my-bucket", + tag: "host", +) +``` + +## Function definition +```js +package v1 + +tagValues = (bucket, tag, predicate=(r) => true, start=-30d) => + from(bucket: bucket) + |> range(start: start) + |> filter(fn: predicate) + |> group(columns: [tag]) + |> distinct(column: tag) + |> keep(columns: ["_value"]) +``` + +_**Used functions:** +[from](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from/), +[range](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range/), +[filter](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter/), +[group](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group/), +[distinct](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/selectors/distinct/), +[keep](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keep/)_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb/_index.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb/_index.md new file mode 100644 index 000000000..3c746a5fd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux InfluxDB package +list_title: InfluxDB package +description: > + The Flux InfluxDB package provides functions for analyzing InfluxDB metadata. + Import the `influxdata/influxdb` package. +menu: + influxdb_cloud_ref: + name: InfluxDB + identifier: influxdb-pkg + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, package] +introduced: 0.92.0 +--- + +The Flux InfluxDB package provides functions for analyzing InfluxDB metadata. +Import the `influxdata/influxdb` package: + +```js +import "influxdata/influxdb" +``` + +{{< children type="functions" show="pages" >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/influxdb/cardinality.md b/content/influxdb/cloud/reference/flux/stdlib/influxdb/cardinality.md new file mode 100644 index 000000000..4da065c1d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/influxdb/cardinality.md @@ -0,0 +1,137 @@ +--- +title: influxdb.cardinality() function +description: The `influxdb.cardinality()` function returns the series cardinality of data stored in InfluxDB Cloud. +menu: + influxdb_cloud_ref: + name: influxdb.cardinality + parent: influxdb-pkg +weight: 301 +influxdb/v2.0/tags: [cardinality] +related: + - /{{< latest "influxdb" "v1" >}}/query_language/spec/#show-cardinality, SHOW CARDINALITY in InfluxQL +introduced: 0.92.0 +--- + +The `influxdb.cardinality()` function returns the [series cardinality](/{{< latest "influxdb" "v2" >}}/reference/glossary#series-cardinality) of data stored in InfluxDB Cloud. + +{{% cloud %}} +**InfluxDB Cloud** supports the `influxdb.cardinality()` function, but **InfluxDB OSS does not**. +{{% /cloud %}} + +```js +import "influxdata/influxdb" + +influxdb.cardinality( + bucket: "example-bucket", + org: "example-org", + host: "https://cloud2.influxdata.com", + token: "MySuP3rSecr3Tt0k3n", + start: -30d, + stop: now(), + predicate: (r) => true +) + +// OR + +influxdb.cardinality( + bucketID: "00xXx0x00xXX0000", + orgID: "00xXx0x00xXX0000", + host: "https://cloud2.influxdata.com", + token: "MySuP3rSecr3Tt0k3n", + start: -30d, + stop: now(), + predicate: (r) => true +) +``` + +## Parameters + +### bucket +Bucket to query cardinality from. + +_**Data type:** String_ + +### bucketID +String-encoded bucket ID to query cardinality from. + +_**Data type:** String_ + +### org +Organization name. + +_**Data type:** String_ + +### orgID +String-encoded [organization ID](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id) to query cardinality from. + +_**Data type:** String_ + +### host +URL of the InfluxDB instance to query. +_See [InfluxDB URLs](/influxdb/cloud/reference/urls/)._ + +_**Data type:** String_ + +### token +InfluxDB [authentication token](/{{< latest "influxdb" "v2" >}}/security/tokens/). + +_**Data type:** String_ + +### start +The earliest time to include when calculating cardinality. +The cardinality calculation **includes** points that match the specified start time. +Use a relative duration or absolute time. +For example, `-1h` or `2019-08-28T22:00:00Z`. +Durations are relative to [`now()`](/influxdb/cloud/reference/flux/stdlib/built-in/misc/now/). + +_**Data type:** Duration | Time_ + +### stop +The latest time to include when calculating cardinality. +The cardinality calculation **excludes** points that match the specified start time. +Use a relative duration or absolute time. +For example, `-1h` or `2019-08-28T22:00:00Z`. +Durations are relative to [`now()`](/influxdb/cloud/reference/flux/stdlib/built-in/misc/now/). +Defaults to `now()`. + +_**Data type:** Duration | Time_ + +### predicate +Predicate function that filters records. +_Defaults to `(r) => true`._ + +_**Data type:** Function_ + +## Examples + +##### Query series cardinality in a bucket +```js +import "influxdata/influxdb" + +influxdb.cardinality( + bucket: "example-bucket" + start: -1y, +) +``` + +##### Query series cardinality in a measurement +```js +import "influxdata/influxdb" + +influxdb.cardinality( + bucket: "example-bucket" + start: -1y, + predicate: (r) => r._measurement == "example-measurement" +) +``` + +##### Query series cardinality for a specific tag +```js +import "influxdata/influxdb" + +influxdb.cardinality( + bucket: "example-bucket" + start: -1y, + predicate: (r) => r.exampleTag == "foo" +) +``` \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/json/_index.md b/content/influxdb/cloud/reference/flux/stdlib/json/_index.md new file mode 100644 index 000000000..461e0cabb --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/json/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux JSON package +list_title: JSON package +description: > + The Flux JSON package provides functions for working with JSON. + Import the `json` package. +aliases: + - /influxdb/cloud/reference/flux/functions/json/ +menu: + influxdb_cloud_ref: + name: JSON + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, json, package] +--- + +JSON Flux functions provide tools for working with JSON. +Import the `json` package: + +```js +import "json" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/json/encode.md b/content/influxdb/cloud/reference/flux/stdlib/json/encode.md new file mode 100644 index 000000000..0b85be8f3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/json/encode.md @@ -0,0 +1,49 @@ +--- +title: json.encode() function +description: The `json.encode()` function converts a value into JSON bytes. +aliases: + - /influxdb/cloud/reference/flux/functions/json/encode/ +menu: + influxdb_cloud_ref: + name: json.encode + parent: JSON +weight: 202 +--- + +The `json.encode()` function converts a value into JSON bytes. + +_**Function type:** Type conversion_ + +```js +import "json" + +json.encode(v: "some value") +``` + +This function encodes [Flux types](/influxdb/cloud/reference/flux/language/types/) as follows: + +- `time` values in [RFC3339](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) format +- `duration` values in number of milliseconds since the epoch +- `regexp` values as their string representation +- `bytes` values as base64-encoded strings +- `function` values are not encoded and produce an error + +## Parameters + +### v +The value to convert. + +_**Data type:** Record | Array | Boolean | Duration | Float | Integer | String | Time | UInteger_ + +## Examples + +### Encode all values in a column in JSON bytes +```js +import "json" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> map(fn: (r) => ({ + r with _value: json.encode(v: r._value) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/_index.md b/content/influxdb/cloud/reference/flux/stdlib/math/_index.md new file mode 100644 index 000000000..f7ada2b9b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/_index.md @@ -0,0 +1,51 @@ +--- +title: Flux math package +list_title: Math package +description: > + The Flux math package provides basic constants and mathematical functions. + Import the `math` package. +aliases: + - /influxdb/cloud/reference/flux/functions/math/ +menu: + influxdb_cloud_ref: + name: Math + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [math, functions] +related: + - /influxdb/cloud/query-data/flux/mathematic-operations/ +--- + +The Flux math package provides basic constants and mathematical functions. +Import the `math` package. + +```js +import "math" +``` + +## Mathematical constants +That `math` package includes the following mathematical constants. + +```js +math.e = 2.71828182845904523536028747135266249775724709369995957496696763 // https ://oeis.org/A001113 +math.pi = 3.14159265358979323846264338327950288419716939937510582097494459 // https ://oeis.org/A000796 +math.phi = 1.61803398874989484820458683436563811772030917980576286213544862 // https ://oeis.org/A001622 + +math.sqrt2 = 1.41421356237309504880168872420969807856967187537694807317667974 // https ://oeis.org/A002193 +math.sqrte = 1.64872127070012814684865078781416357165377610071014801157507931 // https ://oeis.org/A019774 +math.sqrtpi = 1.77245385090551602729816748334114518279754945612238712821380779 // https ://oeis.org/A002161 +math.sqrtphi = 1.27201964951406896425242246173749149171560804184009624861664038 // https ://oeis.org/A139339 + +math.ln2 = 0.693147180559945309417232121458176568075500134360255254120680009 // https://oeis.org/A002162 +math.log2e = 1 ÷ math.ln2 +math.ln10 = 2.30258509299404568401799145468436420760110148862877297603332790 // https ://oeis.org/A002392 +math.log10e = 1 ÷ math.ln10 + +math.maxfloat = 1.797693134862315708145274237317043567981e+308 // 2**1023 * (2**53 - 1) / 2**52 +math.maxint = 1<<63 - 1 +math.minint = -1 << 63 +math.maxuint = 1<<64 - 1 +``` + +## Mathematical functions +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/abs.md b/content/influxdb/cloud/reference/flux/stdlib/math/abs.md new file mode 100644 index 000000000..0d25bf38c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/abs.md @@ -0,0 +1,36 @@ +--- +title: math.abs() function +description: The math.abs() function returns the absolute value of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/abs/ +menu: + influxdb_cloud_ref: + name: math.abs + parent: Math +weight: 301 +--- + +The `math.abs()` function returns the absolute value of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.abs(x: -1.22) + +// Returns 1.22 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.abs(x: ±Inf) // Returns +Inf +math.abs(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/acos.md b/content/influxdb/cloud/reference/flux/stdlib/math/acos.md new file mode 100644 index 000000000..653a77f7d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/acos.md @@ -0,0 +1,37 @@ +--- +title: math.acos() function +description: The math.acos() function returns the arccosine of `x` in radians. +aliases: + - /influxdb/cloud/reference/flux/functions/math/acos/ +menu: + influxdb_cloud_ref: + name: math.acos + parent: Math +weight: 301 +--- + +The `math.acos()` function returns the arccosine of `x` in radians. + +_**Output data type:** Float_ + +```js +import "math" + +math.acos(x: 0.22) + +// Returns 1.3489818562981022 +``` + +## Parameters + +### x +`x` should be greater than -1 and less than 1. +Otherwise, the operation will return `NaN`. + +_**Data type:** Float_ + +## Special cases +```js +math.acos(x: <-1) // Returns NaN +math.acos(x: >1) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/acosh.md b/content/influxdb/cloud/reference/flux/stdlib/math/acosh.md new file mode 100644 index 000000000..c86e0555f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/acosh.md @@ -0,0 +1,38 @@ +--- +title: math.acosh() function +description: The math.acosh() function returns the inverse hyperbolic cosine of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/acosh/ +menu: + influxdb_cloud_ref: + name: math.acosh + parent: Math +weight: 301 +--- + +The `math.acosh()` function returns the inverse hyperbolic cosine of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.acosh(x: 1.22) + +// Returns 0.6517292837263385 +``` + +## Parameters + +### x +`x` should be greater than 1. +If less than 1, the operation will return `NaN`. + +_**Data type:** Float_ + +## Special cases +```js +math.acosh(x: +Inf) // Returns +Inf +math.acosh(x: <1) // Returns NaN +math.acosh(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/asin.md b/content/influxdb/cloud/reference/flux/stdlib/math/asin.md new file mode 100644 index 000000000..c9b3cdfd7 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/asin.md @@ -0,0 +1,39 @@ +--- +title: math.asin() function +description: The math.asin() function returns the arcsine of `x` in radians. +aliases: + - /influxdb/cloud/reference/flux/functions/math/asin/ +menu: + influxdb_cloud_ref: + name: math.asin + parent: Math +weight: 301 +--- + +The `math.asin()` function returns the arcsine of `x` in radians. + +_**Output data type:** Float_ + +```js +import "math" + +math.asin(x: 0.22) + +// Returns 0.22181447049679442 +``` + +## Parameters + +### x +The value used in the operation. +`x` should be greater than -1 and less than 1. +Otherwise, the function will return `NaN`. + +_**Data type:** Float_ + +## Special cases +```js +math.asin(x: ±0) // Returns ±0 +math.asin(x: <-1) // Returns NaN +math.asin(x: >1) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/asinh.md b/content/influxdb/cloud/reference/flux/stdlib/math/asinh.md new file mode 100644 index 000000000..941ff85c9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/asinh.md @@ -0,0 +1,37 @@ +--- +title: math.asinh() function +description: The math.asinh() function returns the inverse hyperbolic sine of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/asinh/ +menu: + influxdb_cloud_ref: + name: math.asinh + parent: Math +weight: 301 +--- + +The `math.asinh()` function returns the inverse hyperbolic sine of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.asinh(x: 3.14) + +// Returns 1.8618125572133835 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.asinh(x: ±0) // Returns ±0 +math.asinh(x: ±Inf) // Returns ±Inf +math.asinh(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/atan.md b/content/influxdb/cloud/reference/flux/stdlib/math/atan.md new file mode 100644 index 000000000..5ca0f407b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/atan.md @@ -0,0 +1,36 @@ +--- +title: math.atan() function +description: The math.atan() function returns the arctangent of `x` in radians. +aliases: + - /influxdb/cloud/reference/flux/functions/math/atan/ +menu: + influxdb_cloud_ref: + name: math.atan + parent: Math +weight: 301 +--- + +The `math.atan()` function returns the arctangent of `x` in radians. + +_**Output data type:** Float_ + +```js +import "math" + +math.atan(x: 3.14) + +// Returns 1.262480664599468 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.atan(x: ±0) // Returns ±0 +math.atan(x: ±Inf) // Returns ±Pi/2 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/atan2.md b/content/influxdb/cloud/reference/flux/stdlib/math/atan2.md new file mode 100644 index 000000000..ab0e6c1af --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/atan2.md @@ -0,0 +1,59 @@ +--- +title: math.atan2() function +description: > + The math.atan2() function returns the arc tangent of `y`/`x`, using the signs of + the parameters to determine the quadrant of the return value. +aliases: + - /influxdb/cloud/reference/flux/functions/math/atan2/ +menu: + influxdb_cloud_ref: + name: math.atan2 + parent: Math +weight: 301 +--- + +The `math.atan2()` function returns the arc tangent of `y`/`x`, using the signs +of the two to determine the quadrant of the return value. + +_**Output data type:** Float_ + +```js +import "math" + +math.atan2(y: 1.22, x: 3.14) + +// Returns 0.3705838802763881 +``` + +## Parameters + +### y +The y coordinate used in the operation. + +_**Data type:** Float_ + +### x +The x coordinate used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.atan2(y:y, x:NaN) // Returns NaN +math.atan2(y: NaN, x:x) // Returns NaN +math.atan2(y: +0, x: >=0) // Returns +0 +math.atan2(y: -0, x: >=0) // Returns -0 +math.atan2(y: +0, x: <=-0) // Returns +Pi +math.atan2(y: -0, x: <=-0) // Returns -Pi +math.atan2(y: >0, x: 0) // Returns +Pi/2 +math.atan2(y: <0, x: 0) // Returns -Pi/2 +math.atan2(y: +Inf, x: +Inf) // Returns +Pi/4 +math.atan2(y: -Inf, x: +Inf) // Returns -Pi/4 +math.atan2(y: +Inf, x: -Inf) // Returns 3Pi/4 +math.atan2(y: -Inf, x: -Inf) // Returns -3Pi/4 +math.atan2(y:y, x: +Inf) // Returns 0 +math.atan2(y: >0, x: -Inf) // Returns +Pi +math.atan2(y: <0, x: -Inf) // Returns -Pi +math.atan2(y: +Inf, x:x) // Returns +Pi/2 +math.atan2(y: -Inf, x:x) // Returns -Pi/2 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/atanh.md b/content/influxdb/cloud/reference/flux/stdlib/math/atanh.md new file mode 100644 index 000000000..39d4fc08f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/atanh.md @@ -0,0 +1,42 @@ +--- +title: math.atanh() function +description: The math.atanh() function returns the inverse hyperbolic tangent of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/atanh/ +menu: + influxdb_cloud_ref: + name: math.atanh + parent: Math +weight: 301 +--- + +The `math.atanh()` function returns the inverse hyperbolic tangent of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.atanh(x: 0.22) + +// Returns 0.22365610902183242 +``` + +## Parameters + +### x +The value used in the operation. +`x` should be greater than -1 and less than 1. +Otherwise, the operation will return `NaN`. + +_**Data type:** Float_ + +## Special cases +```js +math.atanh(x: 1) // Returns +Inf +math.atanh(x: ±0) // Returns ±0 +math.atanh(x: -1) // Returns -Inf +math.atanh(x: <-1) // Returns NaN +math.atanh(x: >1) // Returns NaN +math.atanh(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/cbrt.md b/content/influxdb/cloud/reference/flux/stdlib/math/cbrt.md new file mode 100644 index 000000000..609b5c634 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/cbrt.md @@ -0,0 +1,37 @@ +--- +title: math.cbrt() function +description: The math.cbrt() function returns the cube root of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/cbrt/ +menu: + influxdb_cloud_ref: + name: math.cbrt + parent: Math +weight: 301 +--- + +The `math.cbrt()` function returns the cube root of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.cbrt(x: 1728.0) + +// Returns 12.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.cbrt(±0) // Returns ±0 +math.cbrt(±Inf) // Returns ±Inf +math.cbrt(NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/ceil.md b/content/influxdb/cloud/reference/flux/stdlib/math/ceil.md new file mode 100644 index 000000000..b527a8087 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/ceil.md @@ -0,0 +1,37 @@ +--- +title: math.ceil() function +description: The math.ceil() function returns the least integer value greater than or equal to `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/ceil/ +menu: + influxdb_cloud_ref: + name: math.ceil + parent: Math +weight: 301 +--- + +The `math.ceil()` function returns the least integer value greater than or equal to `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.ceil(x: 3.14) + +// Returns 4.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.ceil(±0) // Returns ±0 +math.ceil(±Inf) // Returns ±Inf +math.ceil(NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/copysign.md b/content/influxdb/cloud/reference/flux/stdlib/math/copysign.md new file mode 100644 index 000000000..d75dfae99 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/copysign.md @@ -0,0 +1,35 @@ +--- +title: math.copysign() function +description: The math.copysign() function returns a value with the magnitude of `x` and the sign of `y`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/copysign/ +menu: + influxdb_cloud_ref: + name: math.copysign + parent: Math +weight: 301 +--- + +The `math.copysign()` function returns a value with the magnitude of `x` and the sign of `y`. + +_**Output data type:** Float_ + +```js +import "math" + +math.copysign(x: 1.0, y: 2.0) + +// Returns 1.0 +``` + +## Parameters + +### x +The magnitude used in the operation. + +_**Data type:** Float_ + +### y +The sign used in the operation. + +_**Data type:** Float_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/cos.md b/content/influxdb/cloud/reference/flux/stdlib/math/cos.md new file mode 100644 index 000000000..fa08acbde --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/cos.md @@ -0,0 +1,36 @@ +--- +title: math.cos() function +description: The math.cos() function returns the cosine of the radian argument `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/cos/ +menu: + influxdb_cloud_ref: + name: math.cos + parent: Math +weight: 301 +--- + +The `math.cos()` function returns the cosine of the radian argument `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.cos(x: 3.14) + +// Returns -0.9999987317275396 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.cos(±Inf) // Returns NaN +math.cos(NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/cosh.md b/content/influxdb/cloud/reference/flux/stdlib/math/cosh.md new file mode 100644 index 000000000..790e20e0c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/cosh.md @@ -0,0 +1,37 @@ +--- +title: math.cosh() function +description: The math.cosh() function returns the hyperbolic cosine of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/cosh/ +menu: + influxdb_cloud_ref: + name: math.cosh + parent: Math +weight: 301 +--- + +The `math.cosh()` function returns the hyperbolic cosine of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.cosh(x: 1.22) + +// Returns 1.8412089502726743 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.cosh(±0) // Returns 1 +math.cosh(±Inf) // Returns +Inf +math.cosh(NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/dim.md b/content/influxdb/cloud/reference/flux/stdlib/math/dim.md new file mode 100644 index 000000000..a4e0838b1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/dim.md @@ -0,0 +1,43 @@ +--- +title: math.dim() function +description: The math.dim() function returns the maximum of `x`-`y` or 0. +aliases: + - /influxdb/cloud/reference/flux/functions/math/dim/ +menu: + influxdb_cloud_ref: + name: math.dim + parent: Math +weight: 301 +--- + +The `math.dim()` function returns the maximum of `x - y` or 0. + +_**Output data type:** Float_ + +```js +import "math" + +math.dim(x: 12.2, y: 8.1) + +// Returns 4.1 +``` + +## Parameters + +### x +The X value used in the operation. + +_**Data type:** Float_ + +### y +The Y value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.dim(x: +Inf, y: +Inf) // Returns NaN +math.dim(x: -Inf, y: -Inf) // Returns NaN +math.dim(x:x, y : NaN) // Returns NaN +math.dim(x: NaN, y :y) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/erf.md b/content/influxdb/cloud/reference/flux/stdlib/math/erf.md new file mode 100644 index 000000000..80563aa2c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/erf.md @@ -0,0 +1,37 @@ +--- +title: math.erf() function +description: The math.erf() function returns the error function of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/erf/ +menu: + influxdb_cloud_ref: + name: math.erf + parent: Math +weight: 301 +--- + +The `math.erf()` function returns the error function of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.erf(x: 22.6) + +// Returns 1.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.erf(+Inf) // Returns 1 +math.erf(-Inf) // Returns -1 +math.erf(NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/erfc.md b/content/influxdb/cloud/reference/flux/stdlib/math/erfc.md new file mode 100644 index 000000000..7eeaa8cce --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/erfc.md @@ -0,0 +1,37 @@ +--- +title: math.erfc() function +description: The math.erfc() function returns the complementary error function of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/erfc/ +menu: + influxdb_cloud_ref: + name: math.erfc + parent: Math +weight: 301 +--- + +The `math.erfc()` function returns the complementary error function of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.erfc(x: 22.6) + +// Returns 3.7726189138490583e-224 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.erfc(+Inf) // Returns 0 +math.erfc(-Inf) // Returns 2 +math.erfc(NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/erfcinv.md b/content/influxdb/cloud/reference/flux/stdlib/math/erfcinv.md new file mode 100644 index 000000000..bf1c18868 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/erfcinv.md @@ -0,0 +1,41 @@ +--- +title: math.erfcinv() function +description: The math.erfcinv() function returns the inverse of `math.erfc()`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/erfcinv/ +menu: + influxdb_cloud_ref: + name: math.erfcinv + parent: Math +weight: 301 +--- + +The `math.erfcinv()` function returns the inverse of `math.erfc()`. + +_**Output data type:** Float_ + +```js +import "math" + +math.erfcinv(x: 0.42345) + +// Returns 0.5660037715858239 +``` + +## Parameters + +### x +The value used in the operation. +`x` should be greater than 0 and less than 2. +Otherwise, the operation will return `NaN`. + +_**Data type:** Float_ + +## Special cases +```js +math.erfcinv(x: 0) // Returns +Inf +math.erfcinv(x: 2) // Returns -Inf +math.erfcinv(x: <0) // Returns NaN +math.erfcinv(x: >2) // Returns NaN +math.erfcinv(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/erfinv.md b/content/influxdb/cloud/reference/flux/stdlib/math/erfinv.md new file mode 100644 index 000000000..9bad32d05 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/erfinv.md @@ -0,0 +1,41 @@ +--- +title: math.erfinv() function +description: The math.erfinv() function returns the inverse error function of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/erfinv/ +menu: + influxdb_cloud_ref: + name: math.erfinv + parent: Math +weight: 301 +--- + +The `math.erfinv()` function returns the inverse error function of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.erfinv(x: 0.22) + +// Returns 0.19750838337227364 +``` + +## Parameters + +### x +The value used in the operation. +`x` should be greater than -1 and less than 1. +Otherwise, the operation will return `NaN`. + +_**Data type:** Float_ + +## Special cases +```js +math.erfinv(x: 1) // Returns +Inf +math.erfinv(x: -1) // Returns -Inf +math.erfinv(x: <-1) // Returns NaN +math.erfinv(x: > 1) // Returns NaN +math.erfinv(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/exp.md b/content/influxdb/cloud/reference/flux/stdlib/math/exp.md new file mode 100644 index 000000000..39e95f5f5 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/exp.md @@ -0,0 +1,38 @@ +--- +title: math.exp() function +description: The math.exp() function returns `e**x`, the base-e exponential of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/exp/ +menu: + influxdb_cloud_ref: + name: math.exp + parent: Math +weight: 301 +--- + +The `math.exp()` function returns `e**x`, the base-e exponential of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.exp(x: 21.0) + +// Returns 1.3188157344832146e+09 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.exp(x: +Inf) // Returns +Inf +math.exp(x: NaN) // Returns NaN +``` + +Very large values overflow to 0 or +Inf. Very small values underflow to 1. diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/exp2.md b/content/influxdb/cloud/reference/flux/stdlib/math/exp2.md new file mode 100644 index 000000000..cc44379c2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/exp2.md @@ -0,0 +1,38 @@ +--- +title: math.exp2() function +description: The math.exp2() function returns `2**x`, the base-2 exponential of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/exp2/ +menu: + influxdb_cloud_ref: + name: math.exp2 + parent: Math +weight: 301 +--- + +The `math.exp2()` function returns `2**x`, the base-2 exponential of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.exp2(x: 21.0) + +// Returns 2.097152e+06 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.exp2(x: +Inf) // Returns +Inf +math.exp2(x: NaN) // Returns NaN +``` + +Very large values overflow to 0 or +Inf. Very small values underflow to 1. diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/expm1.md b/content/influxdb/cloud/reference/flux/stdlib/math/expm1.md new file mode 100644 index 000000000..09cf3cfaf --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/expm1.md @@ -0,0 +1,42 @@ +--- +title: math.expm1() function +description: > + The math.expm1() function returns `e**x - 1`, the base-e exponential of `x` minus 1. + It is more accurate than `math.exp(x:x) - 1` when `x` is near zero. +aliases: + - /influxdb/cloud/reference/flux/functions/math/expm1/ +menu: + influxdb_cloud_ref: + name: math.expm1 + parent: Math +weight: 301 +--- + +The `math.expm1()` function returns `e**x - 1`, the base-e exponential of `x` minus 1. +It is more accurate than `math.exp(x:x) - 1` when `x` is near zero. + +_**Output data type:** Float_ + +```js +import "math" + +math.expm1(x: 1.22) + +// Returns 2.3871877336213343 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.expm1(+Inf) // Returns +Inf +math.expm1(-Inf) // Returns -1 +math.expm1(NaN) // Returns NaN +``` + +Very large values overflow to -1 or +Inf. diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/float64bits.md b/content/influxdb/cloud/reference/flux/stdlib/math/float64bits.md new file mode 100644 index 000000000..c4e3407fd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/float64bits.md @@ -0,0 +1,30 @@ +--- +title: math.float64bits() function +description: The math.float64bits() function returns the IEEE 754 binary representation of `f`, with the sign bit of `f` and the result in the same bit position. +aliases: + - /influxdb/cloud/reference/flux/functions/math/float64bits/ +menu: + influxdb_cloud_ref: + name: math.float64bits + parent: Math +weight: 301 +--- + +The `math.float64bits()` function returns the IEEE 754 binary representation of `f`, with the sign bit of `f` and the result in the same bit position. + +_**Output data type:** UInteger_ + +```js +import "math" + +math.float64bits(f: 1234.56) + +// Returns 4653144467747100426 +``` + +## Parameters + +### f +The value used in the operation. + +_**Data type:** Float_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/floor.md b/content/influxdb/cloud/reference/flux/stdlib/math/floor.md new file mode 100644 index 000000000..605f67a3c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/floor.md @@ -0,0 +1,37 @@ +--- +title: math.floor() function +description: The math.floor() function returns the greatest integer value less than or equal to `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/floor/ +menu: + influxdb_cloud_ref: + name: math.floor + parent: Math +weight: 301 +--- + +The `math.floor()` function returns the greatest integer value less than or equal to `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.floor(x: 1.22) + +// Returns 1.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.floor(±0) // Returns ±0 +math.floor(±Inf) // Returns ±Inf +math.floor(NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/frexp.md b/content/influxdb/cloud/reference/flux/stdlib/math/frexp.md new file mode 100644 index 000000000..8719e6e3f --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/frexp.md @@ -0,0 +1,42 @@ +--- +title: math.frexp() function +description: > + The math.frexp() function breaks `f` into a normalized fraction and an integral power of two. + It returns `frac` and `exp` satisfying `f == frac × 2**exp`, with the absolute + value of `frac` in the interval [½, 1). +aliases: + - /influxdb/cloud/reference/flux/functions/math/frexp/ +menu: + influxdb_cloud_ref: + name: math.frexp + parent: Math +weight: 301 +--- + +The `math.frexp()` function breaks `f` into a normalized fraction and an integral power of two. +It returns `frac` and `exp` satisfying `f == frac × 2**exp`, with the absolute value +of `frac` in the interval `[½, 1)`. + +_**Output data type:** Record_ + +```js +import "math" + +math.frexp(f: 22.0) + +// Returns {frac: 0.6875, exp: 5} +``` + +## Parameters + +### f +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.frexp(f: ±0) // Returns {frac: ±0, exp: 0} +math.frexp(f: ±Inf) // Returns {frac: ±Inf, exp: 0} +math.frexp(f: NaN) // Returns {frac: NaN, exp: 0} +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/gamma.md b/content/influxdb/cloud/reference/flux/stdlib/math/gamma.md new file mode 100644 index 000000000..53923b583 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/gamma.md @@ -0,0 +1,40 @@ +--- +title: math.gamma() function +description: The math.gamma() function returns the Gamma function of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/gamma/ +menu: + influxdb_cloud_ref: + name: math.gamma + parent: Math +weight: 301 +--- + +The `math.gamma()` function returns the Gamma function of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.gamma(x: 2.12) + +// Returns 1.056821007887572 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.gamma(x: +Inf) = +Inf +math.gamma(x: +0) = +Inf +math.gamma(x: -0) = -Inf +math.gamma(x: <0) = NaN for integer x < 0 +math.gamma(x: -Inf) = NaN +math.gamma(x: NaN) = NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/hypot.md b/content/influxdb/cloud/reference/flux/stdlib/math/hypot.md new file mode 100644 index 000000000..e193b2dc0 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/hypot.md @@ -0,0 +1,46 @@ +--- +title: math.hypot() function +description: > + The math.hypot() function returns the square root of `p*p + q*q`, + taking care to avoid unnecessary overflow and underflow. +aliases: + - /influxdb/cloud/reference/flux/functions/math/hypot/ +menu: + influxdb_cloud_ref: + name: math.hypot + parent: Math +weight: 301 +--- + +The `math.hypot()` function returns the square root of `p*p + q*q`, +taking care to avoid overflow and underflow. + +_**Output data type:** Float_ + +```js +import "math" + +math.hypot(p: 2.0, q: 5.0) + +// Returns 5.385164807134505 +``` + +## Parameters + +### p +The p value used in the operation. + +_**Data type:** Float_ + +### q +The q value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.hypot(p: ±Inf, q:q) // Returns +Inf +math.hypot(p:p, q: ±Inf) // Returns +Inf +math.hypot(p: NaN, q:q) // Returns NaN +math.hypot(p:p, q: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/ilogb.md b/content/influxdb/cloud/reference/flux/stdlib/math/ilogb.md new file mode 100644 index 000000000..bd86cd5b5 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/ilogb.md @@ -0,0 +1,37 @@ +--- +title: math.ilogb() function +description: The math.ilogb() function returns the binary exponent of `x` as an integer. +aliases: + - /influxdb/cloud/reference/flux/functions/math/ilogb/ +menu: + influxdb_cloud_ref: + name: math.ilogb + parent: Math +weight: 301 +--- + +The `math.ilogb()` function returns the binary exponent of `x` as an integer. + +_**Output data type:** Integer_ + +```js +import "math" + +math.ilogb(x: 123.45) + +// Returns 6.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.ilogb(x: ±Inf) // Returns MaxInt32 +math.ilogb(x: 0) // Returns MinInt32 +math.ilogb(x: NaN) // Returns MaxInt32 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/isinf.md b/content/influxdb/cloud/reference/flux/stdlib/math/isinf.md new file mode 100644 index 000000000..c5dab2690 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/isinf.md @@ -0,0 +1,39 @@ +--- +title: math.isInf() function +description: The math.isInf() function reports whether `f` is an infinity, according to `sign`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/isinf/ +menu: + influxdb_cloud_ref: + name: math.isInf + parent: Math +weight: 301 +--- + +The `math.isInf()` function reports whether `f` is an infinity, according to sign. + +_**Output data type:** Boolean_ + +- If `sign > 0`, `math.isInf` reports whether `f` is positive infinity. +- If `sign < 0`, `math.isInf` reports whether `f` is negative infinity. +- If `sign == 0`, `math.isInf` reports whether `f` is either infinity. + +```js +import "math" + +math.isInf(f: 2.12, sign: 3) + +// Returns false +``` + +## Parameters + +### f +The value used in the evaluation. + +_**Data type:** Float_ + +### sign +The sign used in the evaluation. + +_**Data type:** Integer_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/isnan.md b/content/influxdb/cloud/reference/flux/stdlib/math/isnan.md new file mode 100644 index 000000000..df53b81ff --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/isnan.md @@ -0,0 +1,30 @@ +--- +title: math.isNaN() function +description: The math.isNaN() function reports whether `f` is an IEEE 754 “not-a-number” value. +aliases: + - /influxdb/cloud/reference/flux/functions/math/isnan/ +menu: + influxdb_cloud_ref: + name: math.isNaN + parent: Math +weight: 301 +--- + +The `math.isNaN()` function reports whether `f` is an IEEE 754 “not-a-number” value. + +_**Output data type:** Boolean_ + +```js +import "math" + +math.isNaN(f: 12.345) + +// Returns false +``` + +## Parameters + +### f +The value used in the evaluation. + +_**Data type:** Float_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/j0.md b/content/influxdb/cloud/reference/flux/stdlib/math/j0.md new file mode 100644 index 000000000..8b0c82361 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/j0.md @@ -0,0 +1,37 @@ +--- +title: math.j0() function +description: The math.j0() function returns the order-zero Bessel function of the first kind. +aliases: + - /influxdb/cloud/reference/flux/functions/math/j0/ +menu: + influxdb_cloud_ref: + name: math.j0 + parent: Math +weight: 301 +--- + +The `math.j0()` function returns the order-zero Bessel function of the first kind. + +_**Output data type:** Float_ + +```js +import "math" + +math.j0(x: 1.23) + +// Returns 0.656070571706025 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.j0(x: ±Inf) // Returns 0 +math.j0(x: 0) // Returns 1 +math.j0(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/j1.md b/content/influxdb/cloud/reference/flux/stdlib/math/j1.md new file mode 100644 index 000000000..6729047dc --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/j1.md @@ -0,0 +1,36 @@ +--- +title: math.j1() function +description: The math.j1() function returns the order-one Bessel function of the first kind. +aliases: + - /influxdb/cloud/reference/flux/functions/math/j1/ +menu: + influxdb_cloud_ref: + name: math.j1 + parent: Math +weight: 301 +--- + +The `math.j1()` function returns the order-one Bessel function of the first kind. + +_**Output data type:** Float_ + +```js +import "math" + +math.j1(x: 1.23) + +// Returns 0.5058005726280961 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.j1(±Inf) // Returns 0 +math.j1(NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/jn.md b/content/influxdb/cloud/reference/flux/stdlib/math/jn.md new file mode 100644 index 000000000..82f5e9e92 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/jn.md @@ -0,0 +1,41 @@ +--- +title: math.jn() function +description: The math.jn() function returns the order-n Bessel function of the first kind. +aliases: + - /influxdb/cloud/reference/flux/functions/math/jn/ +menu: + influxdb_cloud_ref: + name: math.jn + parent: Math +weight: 301 +--- + +The `math.jn()` function returns the order-n Bessel function of the first kind. + +_**Output data type:** Float_ + +```js +import "math" + +math.jn(n: 2, x: 1.23) + +// Returns 0.16636938378681407 +``` + +## Parameters + +### n +The order number. + +_**Data type:** Integer_ + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.jn(n:n, x: ±Inf) // Returns 0 +math.jn(n:n, x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/ldexp.md b/content/influxdb/cloud/reference/flux/stdlib/math/ldexp.md new file mode 100644 index 000000000..789fcdb21 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/ldexp.md @@ -0,0 +1,43 @@ +--- +title: math.ldexp() function +description: The math.ldexp() function is the inverse of `math.frexp()`. It returns `frac × 2**exp`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/ldexp/ +menu: + influxdb_cloud_ref: + name: math.ldexp + parent: Math +weight: 301 +--- + +The `math.ldexp()` function is the inverse of [`math.frexp()`](/influxdb/cloud/reference/flux/stdlib/math/frexp). +It returns `frac × 2**exp`. + +_**Output data type:** Float_ + +```js +import "math" + +math.ldexp(frac: 0.5, exp: 6) + +// Returns 32.0 +``` + +## Parameters + +### frac +The fraction used in the operation. + +_**Data type:** Float_ + +### exp +The exponent used in the operation. + +_**Data type:** Integer_ + +## Special cases +```js +math.ldexp(frac: ±0, exp:exp) // Returns ±0 +math.ldexp(frac: ±Inf, exp:exp) // Returns ±Inf +math.ldexp(frac: NaN, exp:exp) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/lgamma.md b/content/influxdb/cloud/reference/flux/stdlib/math/lgamma.md new file mode 100644 index 000000000..e9248b1be --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/lgamma.md @@ -0,0 +1,39 @@ +--- +title: math.lgamma() function +description: The math.lgamma() function returns the natural logarithm and sign (-1 or +1) of `math.gamma(x:x)`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/lgamma/ +menu: + influxdb_cloud_ref: + name: math.lgamma + parent: Math +weight: 301 +--- + +The `math.lgamma()` function returns the natural logarithm and sign (-1 or +1) of `math.gamma(x:x)`. + +_**Output data format:** Record_ + +```js +import "math" + +math.lgamma(x: 3.14) + +// Returns {lgamma: 0.8261387047770286, sign: 1} +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.lgamma(x: +Inf) // Returns +Inf +math.lgamma(x: 0) // Returns +Inf +math.lgamma(x: -integer) // Returns +Inf +math.lgamma(x: -Inf) // Returns -Inf +math.lgamma(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/log.md b/content/influxdb/cloud/reference/flux/stdlib/math/log.md new file mode 100644 index 000000000..58173d531 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/log.md @@ -0,0 +1,38 @@ +--- +title: math.log() function +description: The math.log() function returns the natural logarithm of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/log/ +menu: + influxdb_cloud_ref: + name: math.log + parent: Math +weight: 301 +--- + +The `math.log()` function returns the natural logarithm of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.log(x: 3.14) + +// Returns 1.144222799920162 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.log(x: +Inf) // Returns +Inf +math.log(x: 0) // Returns -Inf +math.log(x: <0) // Returns NaN +math.log(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/log10.md b/content/influxdb/cloud/reference/flux/stdlib/math/log10.md new file mode 100644 index 000000000..707912673 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/log10.md @@ -0,0 +1,38 @@ +--- +title: math.log10() function +description: The math.log10() function returns the decimal logarithm of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/log10/ +menu: + influxdb_cloud_ref: + name: math.log10 + parent: Math +weight: 301 +--- + +The `math.log10()` function returns the decimal logarithm of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.log10(x: 3.14) + +// Returns 0.4969296480732149 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.log10(x: +Inf) // Returns +Inf +math.log10(x: 0) // Returns -Inf +math.log10(x: <0) // Returns NaN +math.log10(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/log1p.md b/content/influxdb/cloud/reference/flux/stdlib/math/log1p.md new file mode 100644 index 000000000..66c13d7c9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/log1p.md @@ -0,0 +1,42 @@ +--- +title: math.log1p() function +description: > + The math.log1p() function returns the natural logarithm of 1 plus its argument `x`. + It is more accurate than `math.log(x: 1 + x)` when `x` is near zero. +aliases: + - /influxdb/cloud/reference/flux/functions/math/log1p/ +menu: + influxdb_cloud_ref: + name: math.log1p + parent: Math +weight: 301 +--- + +The `math.log1p()` function returns the natural logarithm of 1 plus its argument `x`. +It is more accurate than `math.log(x: 1 + x)` when `x` is near zero. + +_**Output data type:** Float_ + +```js +import "math" + +math.log1p(x: 0.56) + +// Returns 0.44468582126144574 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.log1p(x: +Inf) // Returns +Inf +math.log1p(x: ±0) // Returns ±0 +math.log1p(x: -1) // Returns -Inf +math.log1p(x: <-1) // Returns NaN +math.log1p(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/log2.md b/content/influxdb/cloud/reference/flux/stdlib/math/log2.md new file mode 100644 index 000000000..e062b48b9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/log2.md @@ -0,0 +1,38 @@ +--- +title: math.log2() function +description: The math.log2() function returns the binary logarithm of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/log2/ +menu: + influxdb_cloud_ref: + name: math.log2 + parent: Math +weight: 301 +--- + +The `math.log2()` function returns the binary logarithm of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.log2(x: 3.14) + +// Returns 1.6507645591169022 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.log2(x: +Inf) // Returns +Inf +math.log2(x: 0) // Returns -Inf +math.log2(x: <0) // Returns NaN +math.log2(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/logb.md b/content/influxdb/cloud/reference/flux/stdlib/math/logb.md new file mode 100644 index 000000000..309c58215 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/logb.md @@ -0,0 +1,37 @@ +--- +title: math.logb() function +description: The math.logb() function returns the binary exponent of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/logb/ +menu: + influxdb_cloud_ref: + name: math.logb + parent: Math +weight: 301 +--- + +The `math.logb()` function returns the binary exponent of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.logb(x: 3.14) + +// Returns 1.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.logb(x: ±Inf) // Returns +Inf +math.logb(x: 0) // Returns -Inf +math.logb(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/minf.md b/content/influxdb/cloud/reference/flux/stdlib/math/minf.md new file mode 100644 index 000000000..f63b7e5c3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/minf.md @@ -0,0 +1,31 @@ +--- +title: math.mInf() function +description: The math.mInf() function returns positive infinity if `sign >= 0`, negative infinity if `sign < 0`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/m_inf/ + - /influxdb/cloud/reference/flux/stdlib/math/m_inf/ +menu: + influxdb_cloud_ref: + name: math.mInf + parent: Math +weight: 301 +--- + +The `math.mInf()` function returns positive infinity if `sign >= 0`, negative infinity if `sign < 0`. + +_**Output data type:** Float_ + +```js +import "math" + +math.mInf(sign: 1) + +// Returns +Inf +``` + +## Parameters + +### sign +The sign value used in the operation. + +_**Data type:** Integer_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/mmax.md b/content/influxdb/cloud/reference/flux/stdlib/math/mmax.md new file mode 100644 index 000000000..e42e31f1b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/mmax.md @@ -0,0 +1,47 @@ +--- +title: math.mMax() function +description: The math.mMax() function returns the larger of `x` or `y`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/m_max/ + - /influxdb/cloud/reference/flux/stdlib/math/m_max/ +menu: + influxdb_cloud_ref: + name: math.mMax + parent: Math +weight: 301 +--- + +The `math.mMax()` function returns the larger of `x` or `y`. + +_**Output data type:** Float_ + +```js +import "math" + +math.mMax(x: 1.23, y: 4.56) + +// Returns 4.56 +``` + +## Parameters + +### x +The X value used in the operation. + +_**Data type:** Float_ + +### y +The Y value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.mMax(x:x, y:+Inf) // Returns +Inf +math.mMax(x: +Inf, y:y) // Returns +Inf +math.mMax(x:x, y: NaN) // Returns NaN +math.mMax(x: NaN, y:y) // Returns NaN +math.mMax(x: +0, y: ±0) // Returns +0 +math.mMax(x: ±0, y: +0) // Returns +0 +math.mMax(x: -0, y: -0) // Returns -0 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/mmin.md b/content/influxdb/cloud/reference/flux/stdlib/math/mmin.md new file mode 100644 index 000000000..65cd63f43 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/mmin.md @@ -0,0 +1,46 @@ +--- +title: math.mMin() function +description: The math.mMin() function returns the smaller of `x` or `y`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/m_min/ + - /influxdb/cloud/reference/flux/stdlib/math/m_min/ +menu: + influxdb_cloud_ref: + name: math.mMin + parent: Math +weight: 301 +--- + +The `math.mMin()` function returns the smaller of `x` or `y`. + +_**Output data type:** Float_ + +```js +import "math" + +math.mMin(x: 1.23, y: 4.56) + +// Returns 1.23 +``` + +## Parameters + +### x +The X value used in the operation. + +_**Data type:** Float_ + +### y +The Y value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.mMin(x:x, y: -Inf) // Returns -Inf +math.mMin(x: -Inf, y:y) // Returns -Inf +math.mMin(x:x, y: NaN) // Returns NaN +math.mMin(x: NaN, y:y) // Returns NaN +math.mMin(x: -0, y: ±0) // Returns -0 +math.mMin(x: ±0, y: -0) // Returns -0 +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/mod.md b/content/influxdb/cloud/reference/flux/stdlib/math/mod.md new file mode 100644 index 000000000..1c12d0486 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/mod.md @@ -0,0 +1,47 @@ +--- +title: math.mod() function +description: > + The math.mod() function returns the floating-point remainder of `x`/`y`. + The magnitude of the result is less than `y` and its sign agrees with that of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/mod/ +menu: + influxdb_cloud_ref: + name: math.mod + parent: Math +weight: 301 +--- + +The `math.mod()` function returns the floating-point remainder of `x`/`y`. +The magnitude of the result is less than `y` and its sign agrees with that of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.mod(x: 1.23, y: 4.56) + +// Returns 1.23 +``` + +## Parameters + +### x +The X value used in the operation. + +_**Data type:** Float_ + +### y +The Y value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.mod(x: ±Inf, y:y) // Returns NaN +math.mod(x: NaN, y:y) // Returns NaN +math.mod(x:x, y: 0) // Returns NaN +math.mod(x:x, y: ±Inf) // Returns x +math.mod(x:x, y: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/modf.md b/content/influxdb/cloud/reference/flux/stdlib/math/modf.md new file mode 100644 index 000000000..8c97b05fb --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/modf.md @@ -0,0 +1,39 @@ +--- +title: math.modf() function +description: > + The math.modf() function returns integer and fractional floating-point numbers that sum to `f`. + Both values have the same sign as `f`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/modf/ +menu: + influxdb_cloud_ref: + name: math.modf + parent: Math +weight: 301 +--- + +The `math.modf()` function returns integer and fractional floating-point numbers that sum to `f`. +Both values have the same sign as `f`. + +_**Output data format:** Record_ + +```js +import "math" + +math.modf(f: 3.14) + +// Returns {int: 3, frac: 0.14000000000000012} +``` + +## Parameters + +### f +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.modf(f: ±Inf) // Returns {int: ±Inf, frac: NaN} +math.modf(f: NaN) // Returns {int: NaN, frac: NaN} +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/nan.md b/content/influxdb/cloud/reference/flux/stdlib/math/nan.md new file mode 100644 index 000000000..59e36faa8 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/nan.md @@ -0,0 +1,21 @@ +--- +title: math.NaN() function +description: The math.NaN() function returns an IEEE 754 “not-a-number” value. +aliases: + - /influxdb/cloud/reference/flux/functions/math/nan/ +menu: + influxdb_cloud_ref: + name: math.NaN + parent: Math +weight: 301 +--- + +The `math.NaN()` function returns an IEEE 754 “not-a-number” value. + +```js +import "math" + +math.NaN() + +// Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/nextafter.md b/content/influxdb/cloud/reference/flux/stdlib/math/nextafter.md new file mode 100644 index 000000000..193770082 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/nextafter.md @@ -0,0 +1,42 @@ +--- +title: math.nextafter() function +description: The math.nextafter() function returns the next representable float value after `x` towards `y`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/nextafter/ +menu: + influxdb_cloud_ref: + name: math.nextafter + parent: Math +weight: 301 +--- + +The `math.nextafter()` function returns the next representable float value after `x` towards `y`. + +_**Output data type:** Float_ + +```js +import "math" + +math.nextafter(x: 1.23, y: 4.56) + +// Returns 1.2300000000000002 +``` + +## Parameters + +### x +The X value used in the operation. + +_**Data type:** Float_ + +### y +The Y value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.nextafter(x:x, y:x) // Returns x +math.nextafter(x: NaN, y:y) // Returns NaN +math.nextafter(x:x, y:NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/pow.md b/content/influxdb/cloud/reference/flux/stdlib/math/pow.md new file mode 100644 index 000000000..6c11ff354 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/pow.md @@ -0,0 +1,60 @@ +--- +title: math.pow() function +description: The math.pow() function returns `x**y`, the base-x exponential of y. +aliases: + - /influxdb/cloud/reference/flux/functions/math/pow/ +menu: + influxdb_cloud_ref: + name: math.pow + parent: Math +weight: 301 +--- + +The `math.pow()` function returns `x**y`, the base-x exponential of y. + +_**Output data type:** Float_ + +```js +import "math" + +math.pow(x: 2.0, y: 3.0) + +// Returns 8.0 +``` + +## Parameters + +### x +The X value used in the operation. + +_**Data type:** Float_ + +### y +The Y value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +// In order of priority +math.pow(x:x, y:±0) // Returns 1 for any x +math.pow(x:1, y:y) // Returns 1 for any y +math.pow(x:X, y:1) // Returns x for any x +math.pow(x:NaN, y:y) // Returns NaN +math.pow(x:x, y:NaN) // Returns NaN +math.pow(x:±0, y:y) // Returns ±Inf for y an odd integer < 0 +math.pow(x:±0, y:-Inf) // Returns +Inf +math.pow(x:±0, y:+Inf) // Returns +0 +math.pow(x:±0, y:y) // Returns +Inf for finite y < 0 and not an odd integer +math.pow(x:±0, y:y) // Returns ±0 for y an odd integer > 0 +math.pow(x:±0, y:y) // Returns +0 for finite y > 0 and not an odd integer +math.pow(x:-1, y:±Inf) // Returns 1 +math.pow(x:x, y:+Inf) // Returns +Inf for |x| > 1 +math.pow(x:x, y:-Inf) // Returns +0 for |x| > 1 +math.pow(x:x, y:+Inf) // Returns +0 for |x| < 1 +math.pow(x:x, y:-Inf) // Returns +Inf for |x| < 1 +math.pow(x:+Inf, y:y) // Returns +Inf for y > 0 +math.pow(x:+Inf, y:y) // Returns +0 for y < 0 +math.pow(x:-Inf, y:y) // Returns math.pow(-0, -y) +math.pow(x:x, y:y) // Returns NaN for finite x < 0 and finite non-integer y +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/pow10.md b/content/influxdb/cloud/reference/flux/stdlib/math/pow10.md new file mode 100644 index 000000000..4dcdf3776 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/pow10.md @@ -0,0 +1,36 @@ +--- +title: math.pow10() function +description: The math.pow10() function returns `10**n`, the base-10 exponential of `n`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/pow10/ +menu: + influxdb_cloud_ref: + name: math.pow10 + parent: Math +weight: 301 +--- + +The `math.pow10()` function returns `10**n`, the base-10 exponential of `n`. + +_**Output data type:** Float_ + +```js +import "math" + +math.pow10(n: 3) + +// Returns 1000 +``` + +## Parameters + +### n +The value used in the operation. + +_**Data type:** Integer_ + +## Special cases +```js +math.pow10(n: <-323) // Returns 0 +math.pow10(n: >308) // Returns +Inf +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/remainder.md b/content/influxdb/cloud/reference/flux/stdlib/math/remainder.md new file mode 100644 index 000000000..2bad503cd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/remainder.md @@ -0,0 +1,44 @@ +--- +title: math.remainder() function +description: The math.remainder() function returns the IEEE 754 floating-point remainder of `x / y`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/remainder/ +menu: + influxdb_cloud_ref: + name: math.remainder + parent: Math +weight: 301 +--- + +The `math.remainder()` function returns the IEEE 754 floating-point remainder of `x / y`. + +_**Output data type:** Float_ + +```js +import "math" + +math.remainder(x: 21.0, y: 4.0) + +// Returns 1.0 +``` + +## Parameters + +### x +The numerator used in the operation. + +_**Data type:** Float_ + +### y +The denominator used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.remainder(x: ±Inf, y:y) // Returns NaN +math.remainder(x: NaN, y:y) // Returns NaN +math.remainder(x:x, y: 0) // Returns NaN +math.remainder(x:x, y: ±Inf) // Returns x +math.remainder(x:x, y: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/round.md b/content/influxdb/cloud/reference/flux/stdlib/math/round.md new file mode 100644 index 000000000..6bba8db29 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/round.md @@ -0,0 +1,37 @@ +--- +title: math.round() function +description: The math.round() function returns the nearest integer, rounding half away from zero. +aliases: + - /influxdb/cloud/reference/flux/functions/math/round/ +menu: + influxdb_cloud_ref: + name: math.round + parent: Math +weight: 301 +--- + +The `math.round()` function returns the nearest integer, rounding half away from zero. + +_**Output data type:** Float_ + +```js +import "math" + +math.round(x: 2.12) + +// Returns 2.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.round(x: ±0) // Returns ±0 +math.round(x: ±Inf) // Returns ±Inf +math.round(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/roundtoeven.md b/content/influxdb/cloud/reference/flux/stdlib/math/roundtoeven.md new file mode 100644 index 000000000..e6ce74ea7 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/roundtoeven.md @@ -0,0 +1,39 @@ +--- +title: math.roundtoeven() function +description: The math.roundtoeven() function returns the nearest integer, rounding ties to even. +aliases: + - /influxdb/cloud/reference/flux/functions/math/roundtoeven/ +menu: + influxdb_cloud_ref: + name: math.roundtoeven + parent: Math +weight: 301 +--- + +The `math.roundtoeven()` function returns the nearest integer, rounding ties to even. + +_**Output data type:** Float_ + +```js +import "math" + +math.roundtoeven(x: 3.14) +// Returns 3.0 + +math.roundtoeven(x: 3.5) +// Returns 4.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.roundtoeven(x: ±0) // Returns ±0 +math.roundtoeven(x: ±Inf) // Returns ±Inf +math.roundtoeven(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/signbit.md b/content/influxdb/cloud/reference/flux/stdlib/math/signbit.md new file mode 100644 index 000000000..27ef9b3ff --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/signbit.md @@ -0,0 +1,30 @@ +--- +title: math.signbit() function +description: The math.signbit() function reports whether `x` is negative or negative zero. +aliases: + - /influxdb/cloud/reference/flux/functions/math/signbit/ +menu: + influxdb_cloud_ref: + name: math.signbit + parent: Math +weight: 301 +--- + +The `math.signbit()` function reports whether `x` is negative or negative zero. + +_**Output data type:** Boolean_ + +```js +import "math" + +math.signbit(x: -1.2) + +// Returns true +``` + +## Parameters + +### x +The value used in the evaluation. + +_**Data type:** Float_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/sin.md b/content/influxdb/cloud/reference/flux/stdlib/math/sin.md new file mode 100644 index 000000000..1497a5026 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/sin.md @@ -0,0 +1,37 @@ +--- +title: math.sin() function +description: The math.sin() function returns the sine of the radian argument `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/sin/ +menu: + influxdb_cloud_ref: + name: math.sin + parent: Math +weight: 301 +--- + +The `math.sin()` function returns the sine of the radian argument `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.sin(x: 3.14) + +// Returns 0.0015926529164868282 +``` + +## Parameters + +### x +The radian value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.sin(x: ±0) // Returns ±0 +math.sin(x: ±Inf) // Returns NaN +math.sin(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/sincos.md b/content/influxdb/cloud/reference/flux/stdlib/math/sincos.md new file mode 100644 index 000000000..6d2880d36 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/sincos.md @@ -0,0 +1,37 @@ +--- +title: math.sincos() function +description: The math.sincos() function returns the values of `math.sin(x:x)` and `math.cos(x:x)`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/sincos/ +menu: + influxdb_cloud_ref: + name: math.sincos + parent: Math +weight: 301 +--- + +The `math.sincos()` function returns the values of `math.sin(x:x)` and `math.cos(x:x)`. + +_**Output data format:** Record_ + +```js +import "math" + +math.sincos(x: 1.23) + +// Returns {sin: 0.9424888019316975, cos: 0.3342377271245026} +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.sincos(x: ±0) // Returns {sin: ±0, cos: 1} +math.sincos(x: ±Inf) // Returns {sin: NaN, cos: NaN} +math.sincos(x: NaN) // Returns {sin: NaN, cos: NaN} +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/sinh.md b/content/influxdb/cloud/reference/flux/stdlib/math/sinh.md new file mode 100644 index 000000000..d9418b14c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/sinh.md @@ -0,0 +1,37 @@ +--- +title: math.sinh() function +description: The math.sinh() function returns the hyperbolic sine of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/sinh/ +menu: + influxdb_cloud_ref: + name: math.sinh + parent: Math +weight: 301 +--- + +The `math.sinh()` function returns the hyperbolic sine of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.sinh(x: 1.23) + +// Returns 1.564468479304407 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.sinh(x: ±0) // Returns ±0 +math.sinh(x: ±Inf) // Returns ±Inf +math.sinh(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/sqrt.md b/content/influxdb/cloud/reference/flux/stdlib/math/sqrt.md new file mode 100644 index 000000000..6433d7f89 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/sqrt.md @@ -0,0 +1,38 @@ +--- +title: math.sqrt() function +description: The math.sqrt() function returns the square root of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/sqrt/ +menu: + influxdb_cloud_ref: + name: math.sqrt + parent: Math +weight: 301 +--- + +The `math.sqrt()` function returns the square root of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.sqrt(x: 4.0) + +// Returns 2.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.sqrt(x: +Inf) // Returns +Inf +math.sqrt(x: ±0) // Returns ±0 +math.sqrt(x: <0) // Returns NaN +math.sqrt(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/tan.md b/content/influxdb/cloud/reference/flux/stdlib/math/tan.md new file mode 100644 index 000000000..09e4ec7fe --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/tan.md @@ -0,0 +1,37 @@ +--- +title: math.tan() function +description: The math.tan() function returns the tangent of the radian argument `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/tan/ +menu: + influxdb_cloud_ref: + name: math.tan + parent: Math +weight: 301 +--- + +The `math.tan()` function returns the tangent of the radian argument `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.tan(x: 3.14) + +// Returns -0.001592654936407223 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.tan(x: ±0) // Returns ±0 +math.tan(x: ±Inf) // Returns NaN +math.tan(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/tanh.md b/content/influxdb/cloud/reference/flux/stdlib/math/tanh.md new file mode 100644 index 000000000..1f1c0ee60 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/tanh.md @@ -0,0 +1,37 @@ +--- +title: math.tanh() function +description: The math.tanh() function returns the hyperbolic tangent of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/tanh/ +menu: + influxdb_cloud_ref: + name: math.tanh + parent: Math +weight: 301 +--- + +The `math.tanh()` function returns the hyperbolic tangent of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.tanh(x: 1.23) + +// Returns 0.8425793256589296 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.tanh(x: ±0) // Returns ±0 +math.tanh(x: ±Inf) // Returns ±1 +math.tanh(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/trunc.md b/content/influxdb/cloud/reference/flux/stdlib/math/trunc.md new file mode 100644 index 000000000..395922fc4 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/trunc.md @@ -0,0 +1,37 @@ +--- +title: math.trunc() function +description: The math.trunc() function returns the integer value of `x`. +aliases: + - /influxdb/cloud/reference/flux/functions/math/trunc/ +menu: + influxdb_cloud_ref: + name: math.trunc + parent: Math +weight: 301 +--- + +The `math.trunc()` function returns the integer value of `x`. + +_**Output data type:** Float_ + +```js +import "math" + +math.trunc(x: 3.14) + +// Returns 3.0 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.trunc(x: ±0) // Returns ±0 +math.trunc(x: ±Inf) // Returns ±Inf +math.trunc(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/y0.md b/content/influxdb/cloud/reference/flux/stdlib/math/y0.md new file mode 100644 index 000000000..689422f16 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/y0.md @@ -0,0 +1,38 @@ +--- +title: math.y0() function +description: The math.y0() function returns the order-zero Bessel function of the second kind. +aliases: + - /influxdb/cloud/reference/flux/functions/math/y0/ +menu: + influxdb_cloud_ref: + name: math.y0 + parent: Math +weight: 301 +--- + +The `math.y0()` function returns the order-zero Bessel function of the second kind. + +_**Output data type:** Float_ + +```js +import "math" + +math.y0(x: 3.14) + +// Returns 0.3289375969127807 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.y0(x: +Inf) // Returns 0 +math.y0(x: 0) // Returns -Inf +math.y0(x: <0) // Returns NaN +math.y0(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/y1.md b/content/influxdb/cloud/reference/flux/stdlib/math/y1.md new file mode 100644 index 000000000..efe401669 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/y1.md @@ -0,0 +1,38 @@ +--- +title: math.y1() function +description: The math.y1() function returns the order-one Bessel function of the second kind. +aliases: + - /influxdb/cloud/reference/flux/functions/math/y1/ +menu: + influxdb_cloud_ref: + name: math.y1 + parent: Math +weight: 301 +--- + +The `math.y1()` function returns the order-one Bessel function of the second kind. + +_**Output data type:** Float_ + +```js +import "math" + +math.y1(x: 3.14) + +// Returns 0.35853138083924085 +``` + +## Parameters + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.y1(x: +Inf) // Returns 0 +math.y1(x: 0) // Returns -Inf +math.y1(x: <0) // Returns NaN +math.y1(x: NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/math/yn.md b/content/influxdb/cloud/reference/flux/stdlib/math/yn.md new file mode 100644 index 000000000..25c3c4e24 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/math/yn.md @@ -0,0 +1,44 @@ +--- +title: math.yn() function +description: The math.yn() function returns the order-n Bessel function of the second kind. +aliases: + - /influxdb/cloud/reference/flux/functions/math/yn/ +menu: + influxdb_cloud_ref: + name: math.yn + parent: Math +weight: 301 +--- + +The `math.yn()` function returns the order-n Bessel function of the second kind. + +_**Output data type:** Float_ + +```js +import "math" + +math.yn(n: 3, x: 3.14) + +// Returns -0.4866506930335083 +``` + +## Parameters + +### n +The order number used in the operation. + +_**Data type:** Integer_ + +### x +The value used in the operation. + +_**Data type:** Float_ + +## Special cases +```js +math.yn(n:n, x: +Inf) // Returns 0 +math.yn(n: ≥0, x: 0) // Returns -Inf +math.yn(n: <0, x: 0) // Returns +Inf if n is odd, -Inf if n is even +math.yn(n:n, x: <0) // Returns NaN +math.yn(n:n, x:NaN) // Returns NaN +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/_index.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/_index.md new file mode 100644 index 000000000..6dbee264c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux InfluxDB Monitor package +list_title: InfluxDB Monitor package +description: > + The Flux Monitor package provides tools for monitoring and alerting with InfluxDB. + Import the `influxdata/influxdb/monitor` package. +aliases: + - /influxdb/cloud/reference/flux/functions/monitor/ +menu: + influxdb_cloud_ref: + name: InfluxDB Monitor + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, monitor, alerts, package] +--- + +The Flux monitor package provides tools for monitoring and alerting with InfluxDB. +Import the `influxdata/influxdb/monitor` package: + +```js +import "influxdata/influxdb/monitor" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md new file mode 100644 index 000000000..b4a31b4bd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md @@ -0,0 +1,105 @@ +--- +title: monitor.check() function +description: > + The `monitor.check()` function checks input data and assigns a level + (`ok`, `info`, `warn`, or `crit`) to each row based on predicate functions. +aliases: + - /influxdb/cloud/reference/flux/functions/monitor/check/ +menu: + influxdb_cloud_ref: + name: monitor.check + parent: InfluxDB Monitor +weight: 202 +--- + +The `monitor.check()` function checks input data and assigns a level +(`ok`, `info`, `warn`, or `crit`) to each row based on predicate functions. + +_**Function type:** Transformation_ + +```js +import "influxdata/influxdb/monitor" + +monitor.check( + crit: (r) => r._value > 90.0, + warn: (r) => r._value > 80.0, + info: (r) => r._value > 60.0, + ok: (r) => r._value <= 20.0, + messageFn: (r) => "The current level is ${r._level}", + data: {} +) +``` + +`monitor.check()` stores statuses in the `_level` column and writes results +to the `statuses` measurement in the `_monitoring` bucket. + +## Parameters + +### crit +Predicate function that determines `crit` status. +Default is `(r) => false`. + +_**Data type:** Function_ + +### warn +Predicate function that determines `warn` status. +Default is `(r) => false`. + +_**Data type:** Function_ + +### info +Predicate function that determines `info` status. +Default is `(r) => false`. + +_**Data type:** Function_ + +### ok +Predicate function that determines `ok` status. +Default is `(r) => true`. + +_**Data type:** Function_ + +### messageFn +A function that constructs a message to append to each row. +The message is stored in the `_message` column. + +_**Data type:** Function_ + +### data +Meta data used to identify this check. + +**InfluxDB populates check data.** + +_**Data type:** Record_ + +## Examples + +### Monitor disk usage +```js +import "influxdata/influxdb/monitor" + +from(bucket: "telegraf") + |> range(start: -1h) + |> filter(fn: (r) => + r._measurement == "disk" and + r._field = "used_percent" + ) + |> group(columns: ["_measurement"]) + |> monitor.check( + crit: (r) => r._value > 90.0, + warn: (r) => r._value > 80.0, + info: (r) => r._value > 70.0, + ok: (r) => r._value <= 60.0, + messageFn: (r) => + if r._level == "crit" then "Critical alert!! Disk usage is at ${r._value}%!" + else if r._level == "warn" then "Warning! Disk usage is at ${r._value}%." + else if r._level == "info" then "Disk usage is at ${r._value}%." + else "Things are looking good.", + data: { + _check_name: "Disk Utilization (Used Percentage)", + _check_id: "disk_used_percent", + _type: "threshold", + tags: {} + } + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/deadman.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/deadman.md new file mode 100644 index 000000000..f62329958 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/deadman.md @@ -0,0 +1,48 @@ +--- +title: monitor.deadman() function +description: > + The `monitor.deadman()` function detects when a group stops reporting data. +aliases: + - /influxdb/cloud/reference/flux/functions/monitor/deadman/ +menu: + influxdb_cloud_ref: + name: monitor.deadman + parent: InfluxDB Monitor +weight: 202 +cloud_all: true +--- + +The `monitor.deadman()` function detects when a group stops reporting data. +It takes a stream of tables and reports if groups have been observed since time `t`. + +_**Function type:** Transformation_ + +```js +import "influxdata/influxdb/monitor" + +monitor.deadman(t: 2019-08-30T12:30:00Z) +``` + +`monitor.deadman()` retains the most recent row from each input table and adds a `dead` column. +If a record appears **after** time `t`, `monitor.deadman()` sets `dead` to `false`. +Otherwise, `dead` is set to `true`. + +## Parameters + +### t +The time threshold for the deadman check. + +_**Data type:** Time_ + +## Examples + +### Detect if a host hasn't reported in the last five minutes +```js +import "influxdata/influxdb/monitor" +import "experimental" + +from(bucket: "example-bucket") + |> range(start: -10m) + |> group(columns: ["host"]) + |> monitor.deadman(t: experimental.subDuration(d: 5m, from: now() )) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/from.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/from.md new file mode 100644 index 000000000..9ead72910 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/from.md @@ -0,0 +1,71 @@ +--- +title: monitor.from() function +description: > + The `monitor.from()` function retrieves check statuses stored in the `statuses` + measurement in the `_monitoring` bucket. +aliases: + - /influxdb/cloud/reference/flux/functions/monitor/from/ +menu: + influxdb_cloud_ref: + name: monitor.from + parent: InfluxDB Monitor +weight: 202 +--- + +The `monitor.from()` function retrieves check statuses stored in the `statuses` +measurement in the `_monitoring` bucket. + +_**Function type:** Input_ + +```js +import "influxdata/influxdb/monitor" + +monitor.from( + start: -1h, + stop: now(), + fn: (r) => true +) +``` + + +## Parameters + +### start +The earliest time to include in results. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. + +_**Data type:** Duration | Time | Integer_ + +### stop +The latest time to include in results. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. +Defaults to `now()`. + +_**Data type:** Duration | Time | Integer_ + +{{% note %}} +Time values in Flux must be in [RFC3339 format](/influxdb/cloud/reference/flux/language/types#timestamp-format). +{{% /note %}} + +### fn +A single argument predicate function that evaluates `true` or `false`. +Records or rows (`r`) that evaluate to `true` are included in output tables. +Records that evaluate to _null_ or `false` are not included in output tables. + +_**Data type:** Function_ + +## Examples + +### View critical check statuses from the last hour +```js +import "influxdata/influxdb/monitor" + +monitor.from( + start: -1h, + fn: (r) => r._level == "crit" +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/logs.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/logs.md new file mode 100644 index 000000000..1f26266ca --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/logs.md @@ -0,0 +1,67 @@ +--- +title: monitor.logs() function +description: > + The `monitor.logs()` function retrieves notification events stored in the `notifications` + measurement in the `_monitoring` bucket. +aliases: + - /influxdb/cloud/reference/flux/functions/monitor/logs/ +menu: + influxdb_cloud_ref: + name: monitor.logs + parent: InfluxDB Monitor +weight: 202 +--- + +The `monitor.logs()` function retrieves notification events stored in the `notifications` +measurement in the `_monitoring` bucket. + +_**Function type:** Input_ + +```js +import "influxdata/influxdb/monitor" + +monitor.logs( + start: -1h, + stop: now(), + fn: (r) => true +) +``` + +## Parameters + +### start +The earliest time to include in results. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. + +_**Data type:** Duration | Time | Integer_ + +### stop +The latest time to include in results. +Use a relative duration, absolute time, or integer (Unix timestamp in seconds). +For example, `-1h`, `2019-08-28T22:00:00Z`, or `1567029600`. +Durations are relative to `now()`. +Defaults to `now()`. + +_**Data type:** Duration | Time | Integer_ + +{{% note %}} +Time values in Flux must be in [RFC3339 format](/influxdb/cloud/reference/flux/language/types#timestamp-format). +{{% /note %}} + +### fn +A single argument predicate function that evaluates `true` or `false`. +Records or rows (`r`) that evaluate to `true` are included in output tables. +Records that evaluate to _null_ or `false` are not included in output tables. + +_**Data type:** Function_ + +## Examples + +### Query notification events from the last hour +```js +import "influxdata/influxdb/monitor" + +monitor.logs(start: -1h) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/notify.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/notify.md new file mode 100644 index 000000000..c53224230 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/notify.md @@ -0,0 +1,54 @@ +--- +title: monitor.notify() function +description: > + The `monitor.notify()` function sends a notification to an endpoint and logs it + in the `notifications` measurement in the `_monitoring` bucket. +aliases: + - /influxdb/cloud/reference/flux/functions/monitor/notify/ +menu: + influxdb_cloud_ref: + name: monitor.notify + parent: InfluxDB Monitor +weight: 202 +--- + +The `monitor.notify()` function sends a notification to an endpoint and logs it +in the `notifications` measurement in the `_monitoring` bucket. + +_**Function type:** Output_ + +```js +import "influxdata/influxdb/monitor" + +monitor.notify( + endpoint: endpoint, + data: {} +) +``` + +## Parameters + +### endpoint +A function that constructs and sends the notification to an endpoint. + +_**Data type:** Function_ + +### data +Data to append to the output. +**InfluxDB populates notification data.** + +_**Data type:** Record_ + +## Examples + +### Send a notification to Slack +```js +import "influxdata/influxdb/monitor" +import "slack" + +endpoint = slack.endpoint(name: "slack", channel: "#flux") + +from(bucket: "system") + |> range(start: -5m) + |> monitor.notify(endpoint: endpoint) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/statechanges.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/statechanges.md new file mode 100644 index 000000000..458eac0a0 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/statechanges.md @@ -0,0 +1,87 @@ +--- +title: monitor.stateChanges() function +description: > + The `monitor.stateChanges()` function detects state changes in a stream of tables and + outputs records that change from `fromLevel` to `toLevel`. +aliases: + - /influxdb/cloud/reference/flux/functions/monitor/statechanges/ +menu: + influxdb_cloud_ref: + name: monitor.stateChanges + parent: InfluxDB Monitor +weight: 202 +--- + +The `monitor.stateChanges()` function detects state changes in a stream of data with +a `_level` column and outputs records that change from `fromLevel` to `toLevel`. + +_**Function type:** Transformation_ + +```js +import "influxdata/influxdb/monitor" + +monitor.stateChanges( + fromLevel: "any", + toLevel: "any" +) +``` + +## Parameters + +### fromLevel +The level to detect a change from. +Defaults to `"any"`. + +_**Data type:** String_ + +### toLevel +The level to detect a change to. +The function output records that change to this level. +Defaults to `"any"`. + +_**Data type:** String_ + +## Examples + +##### Detect when the state changes to critical +```js +import "influxdata/influxdb/monitor" + +monitor.from(start: -1h) + |> monitor.stateChanges(toLevel: "crit") +``` + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _level | +|:----- |:------:| +| 0001 | ok | +| 0002 | ok | +| 0003 | warn | +| 0004 | crit | +{{% /flex-content %}} +{{% flex-content %}} +**The following function outputs:** + +```js +monitor.stateChanges( + toLevel: "crit" +) +``` + +| _time | _level | +|:----- |:------:| +| 0004 | crit | +{{% /flex-content %}} +{{< /flex >}} + +## Function definition +```js +stateChanges = (fromLevel="any", toLevel="any", tables=<-) => { + return + if fromLevel == "any" and toLevel == "any" then tables |> stateChangesOnly() + else tables |> _stateChanges(fromLevel: fromLevel, toLevel: toLevel) +} +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/statechangesonly.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/statechangesonly.md new file mode 100644 index 000000000..63cc3b592 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/statechangesonly.md @@ -0,0 +1,55 @@ +--- +title: monitor.stateChangesOnly() function +description: > + The `monitor.stateChangesOnly()` function takes a stream of tables that contains a `_level` + column and returns a stream of tables where each record represents a state change. +menu: + influxdb_cloud_ref: + name: monitor.stateChangesOnly + parent: InfluxDB Monitor +weight: 202 +--- + +The `monitor.stateChangesOnly()` function takes a stream of tables that contains a `_level` +column and returns a stream of tables where each record represents a state change. + +_**Function type:** Transformation_ + +```js +import "influxdata/influxdb/monitor" + +monitor.stateChangesOnly() +``` + +## Examples + +##### Return records representing state changes +```js +import "influxdata/influxdb/monitor" + + +monitor.from(start: -1h) + |> monitor.stateChangesOnly() +``` + +{{< flex >}} +{{% flex-content %}} +**Given the following input:** + +| _time | _level | +|:----- |:------:| +| 0001 | ok | +| 0002 | ok | +| 0003 | warn | +| 0004 | crit | +{{% /flex-content %}} +{{% flex-content %}} +**`monitor.stateChangesOnly()` outputs:** + +| _time | _level | +|:----- |:------:| +| 0002 | ok | +| 0003 | warn | +| 0004 | crit | +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/pagerduty/_index.md b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/_index.md new file mode 100644 index 000000000..f012d23dd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux PagerDuty package +list_title: PagerDuty package +description: > + The Flux PagerDuty package provides functions for sending data to PagerDuty. + Import the `pagerduty` package. +aliases: + - /influxdb/cloud/reference/flux/functions/pagerduty/ +menu: + influxdb_cloud_ref: + name: PagerDuty + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, pagerduty, package] +--- + +The Flux PagerDuty package provides functions for sending data to PagerDuty. +Import the `pagerduty` package: + +```js +import "pagerduty" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/pagerduty/actionfromseverity.md b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/actionfromseverity.md new file mode 100644 index 000000000..144256c26 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/actionfromseverity.md @@ -0,0 +1,44 @@ +--- +title: pagerduty.actionFromSeverity() function +description: > + The `pagerduty.actionFromSeverity()` function converts a severity to a PagerDuty action. +aliases: + - /influxdb/cloud/reference/flux/functions/pagerduty/actionfromseverity/ +menu: + influxdb_cloud_ref: + name: pagerduty.actionFromSeverity + parent: PagerDuty +weight: 202 +--- + +The `pagerduty.actionFromSeverity()` function converts a severity to a PagerDuty action. +`ok` converts to `resolve`. +All other severities convert to `trigger`. + +_**Function type:** Transformation_ + +```js +import "pagerduty" + +pagerduty.actionFromSeverity( + severity: "ok" +) + +// Returns "resolve" +``` + +## Parameters + +### severity +The severity to convert to a PagerDuty action. + +_**Data type:** String_ + +## Function definition +```js +import "strings" + +actionFromSeverity = (severity) => + if strings.toLower(v: severity) == "ok" then "resolve" + else "trigger" +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/pagerduty/dedupkey.md b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/dedupkey.md new file mode 100644 index 000000000..bb895956d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/dedupkey.md @@ -0,0 +1,38 @@ +--- +title: pagerduty.dedupKey() function +description: > + The `pagerduty.dedupKey()` function uses the group key of an input table to + generate and store a deduplication key in the `_pagerdutyDedupKey` column. +aliases: + - /influxdb/cloud/reference/flux/functions/pagerduty/dedupkey/ +menu: + influxdb_cloud_ref: + name: pagerduty.dedupKey + parent: PagerDuty +weight: 202 +--- + +The `pagerduty.dedupKey()` function uses the group key of an input table to +generate and store a deduplication key in the `_pagerdutyDedupKey` column. +The function sorts, newline-concatenates, SHA256-hashes, and hex-encodes +the group key to create a unique deduplication key for each input table. + +_**Function type:** Transformation_ + +```js +import "pagerduty" + +pagerduty.dedupKey() +``` + +## Examples + +##### Add a PagerDuty deduplication key to output data +```js +import "pagerduty" + +from(bucket: "default") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "mem") + |> pagerduty.dedupKey() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/pagerduty/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/endpoint.md new file mode 100644 index 000000000..9ad432569 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/endpoint.md @@ -0,0 +1,90 @@ +--- +title: pagerduty.endpoint() function +description: > + The `pagerduty.endpoint()` function sends a message to PagerDuty that includes output data. +aliases: + - /influxdb/cloud/reference/flux/functions/pagerduty/endpoint/ +menu: + influxdb_cloud_ref: + name: pagerduty.endpoint + parent: PagerDuty +weight: 202 +influxdb/v2.0/tags: [endpoints] +--- + +The `pagerduty.endpoint()` function sends a message to PagerDuty that includes output data. + +_**Function type:** Output_ + +```js +import "pagerduty" + +pagerduty.endpoint( + url: "https://events.pagerduty.com/v2/enqueue" +) +``` + +## Parameters + +### pagerdutyURL +The PagerDuty API URL. +Defaults to `https://events.pagerduty.com/v2/enqueue`. + +_**Data type:** String_ + +## Usage +`pagerduty.endpoint` is a factory function that outputs another function. +The output function requires a `mapFn` parameter. + +### mapFn +A function that builds the record used to generate the POST request. +Requires an `r` parameter. + +_**Data type:** Function_ + +The returned record must include the following fields: + +- `routingKey` +- `client` +- `client_url` +- `class` +- `eventAction` +- `group` +- `severity` +- `component` +- `source` +- `summary` +- `timestamp` + +_For more information, see [`pagerduty.sendEvent()`](/influxdb/cloud/reference/flux/stdlib/pagerduty/sendevent/)_ + +## Examples + +##### Send critical statuses to a PagerDuty endpoint +```js +import "pagerduty" +import "influxdata/influxdb/secrets" + +token = secrets.get(key: "PAGERDUTY_TOKEN") +e = pagerduty.endpoint(token: token) + +crit_statuses = from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses" and status == "crit") + +crit_statuses + |> e(mapFn: (r) => ({ r with + routingKey: r.routingKey, + client: r.client, + clientURL: r.clientURL, + class: r.class, + eventAction: r.eventAction, + group: r.group, + severity: r.severity, + component: r.component, + source: r.source, + summary: r.summary, + timestamp: r._time, + }) + )() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/pagerduty/sendevent.md b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/sendevent.md new file mode 100644 index 000000000..84fb20a1b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/sendevent.md @@ -0,0 +1,124 @@ +--- +title: pagerduty.sendEvent() function +description: > + The `pagerduty.sendEvent()` function sends an event to PagerDuty. +aliases: + - /influxdb/cloud/reference/flux/functions/pagerduty/sendevent/ +menu: + influxdb_cloud_ref: + name: pagerduty.sendEvent + parent: PagerDuty +weight: 202 +--- + +The `pagerduty.sendEvent()` function sends an event to PagerDuty. + +_**Function type:** Output_ + +```js +import "pagerduty" + +pagerduty.sendEvent( + pagerdutyURL: "https://events.pagerduty.com/v2/enqueue", + routingKey: "ExampleRoutingKey", + client: "ExampleClient", + clientURL: "http://examplepagerdutyclient.com", + dedupkey: "ExampleDedupKey", + class: "cpu usage", + group: "app-stack", + severity: "ok", + eventAction: "trigger", + source: "monitoringtool:vendor:region", + summary: "This is an example summary.", + timestamp: "2016-07-17T08:42:58.315+0000" +) +``` + +## Parameters + +### pagerdutyURL +The URL of the PagerDuty endpoint. +Defaults to `https://events.pagerduty.com/v2/enqueue`. + +_**Data type:** String_ + +### routingKey +The routing key generated from your PagerDuty integration. + +_**Data type:** String_ + +### client +The name of the client sending the alert. + +_**Data type:** String_ + +### clientURL +The URL of the client sending the alert. + +_**Data type:** String_ + +### dedupkey +A per-alert ID that acts as deduplication key and allows you to acknowledge or +change the severity of previous messages. +Supports a maximum of 255 characters. + +{{% note %}} +When using [`pagerduty.endpoint()`](/influxdb/cloud/reference/flux/stdlib/pagerduty/endpoint/) +to send data to PagerDuty, the function uses the [`pagerduty.dedupKey()` function](/influxdb/cloud/reference/flux/stdlib/pagerduty/dedupkey/) to populate the `dedupkey` parameter. +{{% /note %}} + +_**Data type:** String_ + +### class +The class or type of the event. +Classes are user-defined. +For example, `ping failure` or `cpu load`. + +_**Data type:** String_ + +### group +A logical grouping used by PagerDuty. +Groups are user-defined. +For example, `app-stack`. + +_**Data type:** String_ + +### severity +The severity of the event. + +**Valid values include:** + +- `critical` +- `error` +- `warning` +- `info` + +_**Data type:** String_ + +### eventAction +[Event type](https://developer.pagerduty.com/docs/events-api-v1/overview/#event-types) to send to PagerDuty. + +**Valid values include:** + +- `trigger` +- `resolve` +- `acknowledge` + +_**Data type:** String_ + +### source +The unique location of the affected system. +For example, the hostname or fully qualified domain name (FQDN). + +_**Data type:** String_ + +### summary +A brief text summary of the event used as the summaries or titles of associated alerts. +The maximum permitted length is 1024 characters. + +_**Data type:** String_ + +### timestamp +The time the detected event occurred in [RFC3339nano format](https://golang.org/pkg/time/#RFC3339Nano). + +_**Data type:** String_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/pagerduty/severityfromlevel.md b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/severityfromlevel.md new file mode 100644 index 000000000..c96ed48b1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pagerduty/severityfromlevel.md @@ -0,0 +1,57 @@ +--- +title: pagerduty.severityFromLevel() function +description: > + The `pagerduty.severityFromLevel()` function converts an InfluxDB status level to + a PagerDuty severity. +aliases: + - /influxdb/cloud/reference/flux/functions/pagerduty/severityfromlevel/ +menu: + influxdb_cloud_ref: + name: pagerduty.severityFromLevel + parent: PagerDuty +weight: 202 +--- + +The `pagerduty.severityFromLevel()` function converts an InfluxDB status level to +a PagerDuty severity. + +_**Function type:** Transformation_ + +```js +import "pagerduty" + +pagerduty.severityFromLevel( + level: "crit" +) + +// Returns "critical" +``` + +| Status level | PagerDuty severity | +|:------------:|:------------------:| +| `crit` | `critical` | +| `warn` | `warning` | +| `info` | `info` | +| `ok` | `info` | + +## Parameters + +### level +The InfluxDB status level to convert to a PagerDuty severity. + +_**Data type:** String_ + +## Function definition +```js +import "strings" + +severityFromLevel = (level) => { + lvl = strings.toLower(v:level) + sev = if lvl == "warn" then "warning" + else if lvl == "crit" then "critical" + else if lvl == "info" then "info" + else if lvl == "ok" then "info" + else "error" + return sev +} +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/profiler/_index.md b/content/influxdb/cloud/reference/flux/stdlib/profiler/_index.md new file mode 100644 index 000000000..b58084e43 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/profiler/_index.md @@ -0,0 +1,69 @@ +--- +title: Flux Profiler package +list_title: Profiler package +description: > + The Flux Profiler package provides performance profiling tools for Flux queries and operations. + Import the `profiler` package. +menu: + influxdb_cloud_ref: + name: Profiler + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, optimize, package] +related: + - /influxdb/cloud/query-data/optimize-queries/ +--- + +The Flux Profiler package provides performance profiling tools for Flux queries and operations. +Import the `profiler` package: + +```js +import "profiler" +``` + +## Options +The Profiler package includes the following options: + +### enabledProfilers +Enable Flux profilers. + +_**Data type:** Array of strings_ + +```js +import "profiler" + +option profiler.enabledProfilers = [""] +``` + +#### Available profilers + +##### query +The `query` profiler provides statistics about the execution of an entire Flux script. +When enabled, results returned by [`yield()`](/influxdb/cloud/reference/flux/stdlib/built-in/outputs/yield/) +include a table with the following columns: + +- **TotalDuration**: total query duration in nanoseconds. +- **CompileDuration**: number of nanoseconds spent compiling the query. +- **QueueDuration**: number of nanoseconds spent queueing. +- **RequeueDuration**: number fo nanoseconds spent requeueing. +- **PlanDuration**: number of nanoseconds spent planning the query. +- **ExecuteDuration**: number of nanoseconds spent executing the query. +- **Concurrency**: number of goroutines allocated to process the query. +- **MaxAllocated**: maximum number of bytes the query allocated. +- **TotalAllocated**: total number of bytes the query allocated (includes memory that was freed and then used again). +- **RuntimeErrors**: error messages returned during query execution. +- **flux/query-plan**: Flux query plan. +- **influxdb/scanned-values**: value scanned by InfluxDB. +- **influxdb/scanned-bytes**: number of bytes scanned by InfluxDB. + +#### Use the query profiler + +Use the query profiler to output statistics about query execution. + +```js +import "profiler" + +option profiler.enabledProfilers = ["query"] + +// ... Query to profile +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/pushbullet/_index.md b/content/influxdb/cloud/reference/flux/stdlib/pushbullet/_index.md new file mode 100644 index 000000000..48ae60494 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pushbullet/_index.md @@ -0,0 +1,23 @@ +--- +title: Flux Pushbullet package +list_title: Pushbullet package +description: > + The Flux Pushbullet package provides functions for sending data to Pushbullet. + Import the `pushbullet` package. +menu: + influxdb_cloud_ref: + name: Pushbullet + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, pushbullet, package] +--- + +The Flux Pushbullet package provides functions for sending data to +[Pushbullet](https://www.pushbullet.com/). +Import the `pushbullet` package: + +```js +import "pushbullet" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/pushbullet/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/pushbullet/endpoint.md new file mode 100644 index 000000000..b5664c84e --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pushbullet/endpoint.md @@ -0,0 +1,82 @@ +--- +title: pushbullet.endpoint() function +description: > + The `pushbullet.endpoint()` function creates the endpoint for the Pushbullet API + and sends a notification of type `note`. +menu: + influxdb_cloud_ref: + name: pushbullet.endpoint + parent: Pushbullet +weight: 202 +--- + +The `pushbullet.endpoint()` function creates the endpoint for the Pushbullet API +and sends a notification of type `note`. + +_**Function type:** Output_ + +```js +import "pushbullet" + +pushbullet.endpoint( + url: "https://api.pushbullet.com/v2/pushes", + token: "" +) +``` + +## Parameters + +### url +Pushbullet API URL. +Defaults to `https://api.pushbullet.com/v2/pushes`. + +_**Data type:** String_ + +### token +[Pushbullet API token](https://get.pushbullet.help/hc/en-us/articles/215770388-Create-and-regenerate-API-tokens) +to use when interacting with Pushbullet. +Defaults to `""`. + +_**Data type:** String_ + + +## Usage +`pushbullet.endpoint` is a factory function that outputs another function. +The output function requires a `mapFn` parameter. + +### mapFn +A function that builds the record used to generate the API request. +Requires an `r` parameter. + +_**Data type:** Function_ + +The returned record must include the following fields (as defined in +[`pushbullet.pushNote()`](/influxdb/cloud/reference/flux/stdlib/pushbullet/pushnote/#title)): + +- `title` +- `text` + +## Examples + +##### Send the last reported status to Pushbullet +```js +import "pushbullet" +import "influxdata/influxdb/secrets" + +token = secrets.get(key: "PUSHBULLET_TOKEN") +e = pushbullet.endpoint(token: token) + +lastReported = + from(bucket: "example-bucket") + |> range(start: -10m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + +lastReported + |> e(mapFn: (r) => ({ + r with + title: r.title, + text: "${string(v: r._time)}: ${r.status}." + }) + )() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/pushbullet/pushdata.md b/content/influxdb/cloud/reference/flux/stdlib/pushbullet/pushdata.md new file mode 100644 index 000000000..c631d5b03 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pushbullet/pushdata.md @@ -0,0 +1,82 @@ +--- +title: pushbullet.pushData() function +description: > + The `pushbullet.pushData()` function sends a push notification to the Pushbullet API. +menu: + influxdb_cloud_ref: + name: pushbullet.pushData + parent: Pushbullet +weight: 202 +--- + +The `pushbullet.pushData()` function sends a push notification to the +[Pushbullet API](https://docs.pushbullet.com/). + +_**Function type:** Output_ + +```js +import "pushbullet" + +pushbullet.pushData( + url: "https://api.pushbullet.com/v2/pushes", + token: "", + data: { + "type": "link", + "title": "This is a notification!", + "body": "This notification came from Flux.", + "url": "http://example.com" + } +) +``` + +## Parameters + +### url +Pushbullet API URL. +Defaults to `https://api.pushbullet.com/v2/pushes`. + +_**Data type:** String_ + +### token +[Pushbullet API token](https://get.pushbullet.help/hc/en-us/articles/215770388-Create-and-regenerate-API-tokens) +to use when interacting with Pushbullet. +Defaults to `""`. + +_**Data type:** String_ + +### data +Required +Data to send to the Pushbullet API. +The function JSON-encodes data before sending it to Pushbullet. + +_**Data type:** Record_ + + + +## Examples + +##### Send the last reported status to Pushbullet +```js +import "pushbullet" +import "influxdata/influxdb/secrets" + +token = secrets.get(key: "PUSHBULLET_TOKEN") + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> tableFind(fn: (key) => true) + |> getRecord(idx: 0) + +pushbullet.pushData( + token: token, + data: { + "type": "link", + "title": "Last reported status", + "body": "${lastReported._time}: ${lastReported.status}." + "url": "${lastReported.statusURL}" + } +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/pushbullet/pushnote.md b/content/influxdb/cloud/reference/flux/stdlib/pushbullet/pushnote.md new file mode 100644 index 000000000..73d96655d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/pushbullet/pushnote.md @@ -0,0 +1,78 @@ +--- +title: pushbullet.pushNote() function +description: > + The `pushbullet.pushNote()` function sends a push notification of type `note` + to the Pushbullet API. +menu: + influxdb_cloud_ref: + name: pushbullet.pushNote + parent: Pushbullet +weight: 202 +--- + +The `pushbullet.pushNote()` function sends a push notification of type `note` +to the Pushbullet API. + +_**Function type:** Output_ + +```js +import "pushbullet" + +pushbullet.pushNote( + url: "https://api.pushbullet.com/v2/pushes", + token: "", + title: "This is a push notification!", + text: "This push notification came from Flux." +) +``` + +## Parameters + +### url +Pushbullet API URL. +Defaults to `https://api.pushbullet.com/v2/pushes`. + +_**Data type:** String_ + +### token +[Pushbullet API token](https://get.pushbullet.help/hc/en-us/articles/215770388-Create-and-regenerate-API-tokens) +to use when interacting with Pushbullet. +Defaults to `""`. + +_**Data type:** String_ + +### title +Required +Title of the notification. + +_**Data type:** String_ + +### text +Required +Text to display in the notification. + +_**Data type:** String_ + +## Examples + +##### Send the last reported status to Pushbullet +```js +import "pushbullet" +import "influxdata/influxdb/secrets" + +token = secrets.get(key: "PUSHBULLET_TOKEN") + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> tableFind(fn: (key) => true) + |> getRecord(idx: 0) + +pushbullet.pushNote( + token: token, + title: "Last reported status", + text: "${lastReported._time}: ${lastReported.status}." +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/_index.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/_index.md new file mode 100644 index 000000000..1cc9ddae6 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux regular expressions package +list_title: Regular expressions package +description: > + The Flux regular expressions package includes functions that provide enhanced + regular expression functionality. Import the `regexp` package. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/ +menu: + influxdb_cloud_ref: + name: Regular expressions + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [regex, functions] +--- + +The Flux regular expressions package includes functions that provide enhanced +regular expression functionality. Import the `regexp` package. + +```js +import "regexp" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/compile.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/compile.md new file mode 100644 index 000000000..dffb3dcf1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/compile.md @@ -0,0 +1,52 @@ +--- +title: regexp.compile() function +description: > + The `regexp.compile()` function parses a regular expression and, if successful, + returns a Regexp object that can be used to match against text. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/compile/ +menu: + influxdb_cloud_ref: + name: regexp.compile + parent: Regular expressions +weight: 301 +--- + +The `regexp.compile()` function parses a regular expression and, if successful, +returns a Regexp object that can be used to match against text. + +_**Output data type:** Regexp_ + +```js +import "regexp" + +regexp.compile(v: "abcd") + +// Returns the regexp object `abcd` +``` + +## Parameters + +### v +The string value to parse into a regular expression. + +_**Data type:** String_ + +## Examples + +###### Use a string value as a regular expression +```js +import "regexp" + +data + |> map(fn: (r) => ({ + r with + regexStr: r.regexStr, + _value: r._value, + firstRegexMatch: findString( + r: regexp.compile(v: regexStr), + v: r._value + ) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/findstring.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/findstring.md new file mode 100644 index 000000000..cf37b79b2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/findstring.md @@ -0,0 +1,53 @@ +--- +title: regexp.findString() function +description: The `regexp.findString()` function returns the left-most regular expression match in a string. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/findstring/ +menu: + influxdb_cloud_ref: + name: regexp.findString + parent: Regular expressions +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/regexp/splitregexp +--- + +The `regexp.findString()` function returns the left-most regular expression match in a string. + +_**Output data type:** String_ + +```js +import "regexp" + +findString(r: /foo.?/, v: "seafood fool") + +// Returns "food" +``` + +## Parameters + +### r +The regular expression used to search `v`. + +_**Data type:** Regexp_ + +### v +The string value to search. + +_**Data type:** String_ + +## Examples + +###### Find the first regular expression match in each row +```js +import "regexp" + +data + |> map(fn: (r) => ({ + r with + message: r.message, + regexp: r.regexp, + match: regexp.findString(r: r.regexp, v: r.message) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/findstringindex.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/findstringindex.md new file mode 100644 index 000000000..65e1f39a6 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/findstringindex.md @@ -0,0 +1,59 @@ +--- +title: regexp.findStringIndex() function +description: > + The `regexp.findStringIndex()` function returns a two-element array of integers defining + the beginning and ending indexes of the left-most regular expression match in a string. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/findstringindex/ +menu: + influxdb_cloud_ref: + name: regexp.findStringIndex + parent: Regular expressions +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/regexp/compile +--- + +The `regexp.findStringIndex()` function returns a two-element array of integers defining +the beginning and ending indexes of the left-most regular expression match in a string. + +_**Output data type:** Array of Integers_ + +```js +import "regexp" + +regexp.findStringIndex(r: /ab?/, v: "tablet") + +// Returns [1, 3] +``` + +## Parameters + +### r +The regular expression used to search `v`. + +_**Data type:** Regexp_ + +### v +The string value to search. + +_**Data type:** String_ + +## Examples + +###### Index the bounds of first regular expression match in each row +```js +import "regexp" + +data + |> map(fn: (r) => ({ + r with + regexStr: r.regexStr, + _value: r._value, + matchIndex: regexp.findStringIndex( + r: regexp.compile(r.regexStr), + v: r._value + ) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/getstring.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/getstring.md new file mode 100644 index 000000000..1919e66bf --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/getstring.md @@ -0,0 +1,47 @@ +--- +title: regexp.getString() function +description: The `regexp.getString()` function returns the source string used to compile a regular expression. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/getstring/ +menu: + influxdb_cloud_ref: + name: regexp.getString + parent: Regular expressions +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/regexp/compile +--- + +The `regexp.getString()` function returns the source string used to compile a regular expression. + +_**Output data type:** String_ + +```js +import "regexp" + +regexp.getString(r: /[a-zA-Z]/) + +// Returns "[a-zA-Z]" +``` + +## Parameters + +### r +The regular expression object to convert to a string. + +_**Data type:** Regexp_ + +## Examples + +###### Convert regular expressions into strings in each row +```js +import "regexp" + +data + |> map(fn: (r) => ({ + r with + regex: r.regex, + regexStr: regexp.getString(r: r.regex) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/matchregexpstring.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/matchregexpstring.md new file mode 100644 index 000000000..f1175f8d9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/matchregexpstring.md @@ -0,0 +1,53 @@ +--- +title: regexp.matchRegexpString() function +description: > + The `regexp.matchRegexpString()` function tests if a string contains any match + to a regular expression. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/matchregexpstring/ +menu: + influxdb_cloud_ref: + name: regexp.matchRegexpString + parent: Regular expressions +weight: 301 +--- + +The `regexp.matchRegexpString()` function tests if a string contains any match +to a regular expression. + +_**Output data type:** Boolean_ + +```js +import "regexp" + +regexp.matchRegexpString(r: /(gopher){2}/, v: "gophergophergopher") + +// Returns true +``` + +## Parameters + +### r +The regular expression used to search `v`. + +_**Data type:** Regexp_ + +### v +The string value to search. + +_**Data type:** String_ + +## Examples + +###### Filter by columns that contain matches to a regular expression +```js +import "regexp" + +data + |> filter(fn: (r) => + regexp.matchRegexpString( + r: /Alert\:/, + v: r.message + ) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/quotemeta.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/quotemeta.md new file mode 100644 index 000000000..73af6b435 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/quotemeta.md @@ -0,0 +1,46 @@ +--- +title: regexp.quoteMeta() function +description: > + The `regexp.quoteMeta()` function escapes all regular expression metacharacters inside of a string. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/quotemeta/ +menu: + influxdb_cloud_ref: + name: regexp.quoteMeta + parent: Regular expressions +weight: 301 +--- + +The `regexp.quoteMeta()` function escapes all regular expression metacharacters inside of a string. + +_**Output data type:** String_ + +```js +import "regexp" + +regexp.quoteMeta(v: ".+*?()|[]{}^$") + +// Returns "\.\+\*\?\(\)\|\[\]\{\}\^\$" +``` + +## Parameters + +### v +The string that contains regular expression metacharacters to escape. + +_**Data type:** String_ + +## Examples + +###### Escape regular expression meta characters in column values +```js +import "regexp" + +data + |> map(fn: (r) => ({ + r with + notes: r.notes, + notes_escaped: regexp.quoteMeta(v: r.notes) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/replaceallstring.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/replaceallstring.md new file mode 100644 index 000000000..a1cb6e52d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/replaceallstring.md @@ -0,0 +1,61 @@ +--- +title: regexp.replaceAllString() function +description: > + The `regexp.replaceAllString()` function replaces all regular expression matches + in a string with a specified replacement. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/replaceallstring/ +menu: + influxdb_cloud_ref: + name: regexp.replaceAllString + parent: Regular expressions +weight: 301 +--- + +The `regexp.replaceAllString()` function replaces all regular expression matches +in a string with a specified replacement. + +_**Output data type:** String_ + +```js +import "regexp" + +regexp.replaceAllString(r: /a(x*)b/, v: "-ab-axxb-", t: "T") + +// Returns "-T-T-" +``` + +## Parameters + +### r +The regular expression used to search `v`. + +_**Data type:** Regexp_ + +### v +The string value to search. + +_**Data type:** String_ + +### t +The replacement for matches to `r`. + +_**Data type:** String_ + +## Examples + +###### Replace regular expression matches in string column values +```js +import "regexp" + +data + |> map(fn: (r) => ({ + r with + message: r.message, + updated_message: regexp.replaceAllString( + r: /cat|bird|ferret/, + v: r.message, + t: "dog" + ) + })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/regexp/splitregexp.md b/content/influxdb/cloud/reference/flux/stdlib/regexp/splitregexp.md new file mode 100644 index 000000000..0d2410453 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/regexp/splitregexp.md @@ -0,0 +1,44 @@ +--- +title: regexp.splitRegexp() function +description: > + The `regexp.splitRegexp()` function splits a string into substrings separated by + regular expression matches and returns an array of `i` substrings between matches. +aliases: + - /influxdb/cloud/reference/flux/functions/regexp/splitregexp/ +menu: + influxdb_cloud_ref: + name: regexp.splitRegexp + parent: Regular expressions +weight: 301 +--- + +The `regexp.splitRegexp()` function splits a string into substrings separated by +regular expression matches and returns an array of `i` substrings between matches. + +_**Output data type:** Array of Strings_ + +```js +import "regexp" + +regexp.splitRegexp(r: /a*/, v: "abaabaccadaaae", i: 5) + +// Returns ["", "b", "b", "c", "cadaaae"] +``` + +## Parameters + +### r +The regular expression used to search `v`. + +_**Data type:** Regexp_ + +### v +The string value to search. + +_**Data type:** String_ + +### i +The maximum number of substrings to return. +`-1` returns all matching substrings. + +_**Data type:** Integer_ diff --git a/content/influxdb/cloud/reference/flux/stdlib/runtime/_index.md b/content/influxdb/cloud/reference/flux/stdlib/runtime/_index.md new file mode 100644 index 000000000..fa441dcb1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/runtime/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux runtime package +list_title: Runtime package +description: > + The Flux runtime package includes functions that provide information about the + current Flux runtime. Import the `runtime` package. +aliases: + - /influxdb/cloud/reference/flux/functions/runtime/ +menu: + influxdb_cloud_ref: + name: Runtime + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [runtime, functions, package] +--- + +The Flux runtime package includes functions that provide information about the +current Flux runtime. Import the `runtime` package: + +```js +import "runtime" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/runtime/version.md b/content/influxdb/cloud/reference/flux/stdlib/runtime/version.md new file mode 100644 index 000000000..1d4d965ab --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/runtime/version.md @@ -0,0 +1,22 @@ +--- +title: runtime.version() function +description: The `runtime.version()` function returns the current Flux version. +aliases: + - /influxdb/cloud/reference/flux/functions/runtime/version/ +menu: + influxdb_cloud_ref: + name: runtime.version + parent: Runtime +weight: 401 +--- + +The `runtime.version()` function returns the current Flux version. + +_**Function type:** Miscellaneous_ +_**Output data type:** String_ + +```js +import "runtime" + +runtime.version() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/secrets/_index.md b/content/influxdb/cloud/reference/flux/stdlib/secrets/_index.md new file mode 100644 index 000000000..9690a0ee3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/secrets/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux InfluxDB Secrets package +list_title: InfluxDB Secrets package +description: > + The Flux InfluxDB Secrets package provides functions for working with sensitive secrets managed by InfluxDB. + Import the `influxdata/influxdb/secrets` package. +aliases: + - /influxdb/cloud/reference/flux/functions/secrets/ +menu: + influxdb_cloud_ref: + name: InfluxDB Secrets + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, secrets, package] +--- + +InfluxDB Secrets Flux functions provide tools for working with sensitive secrets managed by InfluxDB. +Import the `influxdata/influxdb/secrets` package: + +```js +import "influxdata/influxdb/secrets" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/secrets/get.md b/content/influxdb/cloud/reference/flux/stdlib/secrets/get.md new file mode 100644 index 000000000..31b9034bc --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/secrets/get.md @@ -0,0 +1,47 @@ +--- +title: secrets.get() function +description: > + The `secrets.get()` function retrieves a secret from the InfluxDB secret store. +aliases: + - /influxdb/cloud/reference/flux/functions/secrets/get/ +menu: + influxdb_cloud_ref: + name: secrets.get + parent: InfluxDB Secrets +weight: 202 +--- + +The `secrets.get()` function retrieves a secret from the +[InfluxDB secret store](/influxdb/cloud/security/secrets/). + +_**Function type:** Miscellaneous_ + +```js +import "influxdata/influxdb/secrets" + +secrets.get(key: "KEY_NAME") +``` + +## Parameters + +### key +The secret key to retrieve. + +_**Data type:** String_ + +## Examples + +### Populate sensitive credentials with secrets +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "POSTGRES_USERNAME") +password = secrets.get(key: "POSTGRES_PASSWORD") + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost", + query:"SELECT * FROM example-table" +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/slack/_index.md b/content/influxdb/cloud/reference/flux/stdlib/slack/_index.md new file mode 100644 index 000000000..72f730c45 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/slack/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux Slack package +list_title: Slack package +description: > + The Flux Slack package provides functions for sending data to Slack. + Import the `slack` package. +aliases: + - /influxdb/cloud/reference/flux/functions/slack/ +menu: + influxdb_cloud_ref: + name: Slack + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, slack, package] +--- + +The Flux Slack package provides functions for sending data to Slack. +Import the `slack` package: + +```js +import "slack" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/slack/endpoint.md b/content/influxdb/cloud/reference/flux/stdlib/slack/endpoint.md new file mode 100644 index 000000000..2f70b1a0d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/slack/endpoint.md @@ -0,0 +1,97 @@ +--- +title: slack.endpoint() function +description: > + The `slack.endpoint()` function sends a message to Slack that includes output data. +aliases: + - /influxdb/cloud/reference/flux/functions/slack/endpoint/ +menu: + influxdb_cloud_ref: + name: slack.endpoint + parent: Slack +weight: 202 +influxdb/v2.0/tags: [endpoints] +--- + +The `slack.endpoint()` function sends a message to Slack that includes output data. + +_**Function type:** Output_ + +```js +import "slack" + +slack.endpoint( + url: "https://slack.com/api/chat.postMessage", + token: "mySuPerSecRetTokEn" +) +``` + +## Parameters + +### url +The Slack API URL. +Defaults to `https://slack.com/api/chat.postMessage`. + +{{% note %}} +If using a Slack webhook, you'll receive a Slack webhook URL when you +[create an incoming webhook](https://api.slack.com/incoming-webhooks#create_a_webhook). +{{% /note %}} + +_**Data type:** String_ + +### token +The [Slack API token](https://get.slack.help/hc/en-us/articles/215770388-Create-and-regenerate-API-tokens) +used to interact with Slack. +Defaults to `""`. + +{{% note %}} +A token is only required if using the Slack chat.postMessage API. +{{% /note %}} + +_**Data type:** String_ + +## Usage +`slack.endpoint` is a factory function that outputs another function. +The output function requires a `mapFn` parameter. + +### mapFn +A function that builds the record used to generate the POST request. +Requires an `r` parameter. + +{{% note %}} +_You should rarely need to override the default `mapFn` parameter. +To see the default `mapFn` value or for insight into possible overrides, view the +[`slack.endpoint()` source code](https://github.com/influxdata/flux/blob/master/stdlib/slack/slack.flux)._ +{{% /note %}} + +_**Data type:** Function_ + +The returned record must include the following fields: + +- `channel` +- `text` +- `color` + +_For more information, see [`slack.message()`](/influxdb/cloud/reference/flux/stdlib/slack/message/)_ + +## Examples + +##### Send critical statuses to a Slack endpoint +```js +import "slack" +import "influxdata/influxdb/secrets" + +token = secrets.get(key: "SLACK_TOKEN") +e = slack.endpoint(token: token) + +crit_statuses = from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses" and status == "crit") + +crit_statuses + |> e(mapFn: (r) => ({ + channel: r.channel, + text: r.text, + color: r.color, + }) + )() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/slack/message.md b/content/influxdb/cloud/reference/flux/stdlib/slack/message.md new file mode 100644 index 000000000..52e7bc0a0 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/slack/message.md @@ -0,0 +1,100 @@ +--- +title: slack.message() function +description: > + The `slack.message()` function sends a single message to a Slack channel. + The function works with either with the chat.postMessage API or with a Slack webhook. +aliases: + - /influxdb/cloud/reference/flux/functions/slack/message/ +menu: + influxdb_cloud_ref: + name: slack.message + parent: Slack +weight: 202 +--- + +The `slack.message()` function sends a single message to a Slack channel. +The function works with either with the [chat.postMessage API](https://api.slack.com/methods/chat.postMessage) +or with a [Slack webhook](https://api.slack.com/incoming-webhooks). + +_**Function type:** Output_ + +```js +import "slack" + +slack.message( + url: "https://slack.com/api/chat.postMessage", + token: "mySuPerSecRetTokEn", + channel: "#flux",, + text: "This is a message from the Flux slack.message() function.", + color: "good" +) +``` + +## Parameters + +### url +The Slack API URL. +Defaults to `https://slack.com/api/chat.postMessage`. + +{{% note %}} +If using a Slack webhook, you'll receive a Slack webhook URL when you +[create an incoming webhook](https://api.slack.com/incoming-webhooks#create_a_webhook). +{{% /note %}} + +_**Data type:** String_ + +### token +The [Slack API token](https://get.slack.help/hc/en-us/articles/215770388-Create-and-regenerate-API-tokens) +used to interact with Slack. +Defaults to `""`. + +{{% note %}} +A token is only required if using the Slack chat.postMessage API. +{{% /note %}} + +_**Data type:** String_ + +### channel +The name of channel to post the message to. Required + +_**Data type:** String_ + +### text +The text to display in the Slack message. Required + +_**Data type:** String_ + +### color +The color to include with the message. +Required + +**Valid values include:** + +- `good` +- `warning` +- `danger` +- Any valid RGB hex color code. For example, `#439FE0`. + +_**Data type:** String_ + +## Examples + +##### Send the last reported status to Slack +```js +import "slack" + +lastReported = + from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => r._measurement == "statuses") + |> last() + |> tableFind(fn: (key) => true) + |> getRecord(idx: 0) + +slack.message( + url: "https://slack.com/api/chat.postMessage", + token: "mySuPerSecRetTokEn", + channel: "#system-status", + text: "The last reported status was \"${lastReported.status}\"." +) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/sql/_index.md b/content/influxdb/cloud/reference/flux/stdlib/sql/_index.md new file mode 100644 index 000000000..de86adcd8 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/sql/_index.md @@ -0,0 +1,37 @@ +--- +title: Flux SQL package +list_title: SQL package +description: > + The Flux SQL package provides tools for working with data in SQL databases such + as MySQL, PostgreSQL, Snowflake, SQLite, Microsoft SQL Server, Amazon Athena, + and Google BigQuery. + Import the `sql` package. +aliases: + - /influxdb/cloud/reference/flux/functions/sql/ +menu: + influxdb_cloud_ref: + name: SQL + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [functions, sql, package, mysql, postgres] +related: + - /influxdb/cloud/query-data/flux/sql/ +--- + +SQL Flux functions provide tools for working with data in SQL databases such as: + +- Amazon Athena +- Google BigQuery +- Microsoft SQL Server +- MySQL +- PostgreSQL +- Snowflake +- SQLite + +Import the `sql` package: + +```js +import "sql" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/sql/from.md b/content/influxdb/cloud/reference/flux/stdlib/sql/from.md new file mode 100644 index 000000000..247a517d3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/sql/from.md @@ -0,0 +1,295 @@ +--- +title: sql.from() function +description: The `sql.from()` function retrieves data from a SQL data source. +aliases: + - /influxdb/cloud/reference/flux/functions/sql/from/ +menu: + influxdb_cloud_ref: + name: sql.from + parent: SQL +weight: 202 +related: + - /influxdb/cloud/query-data/flux/sql/ +--- + +The `sql.from()` function retrieves data from a SQL data source. + +_**Function type:** Input_ + +```js +import "sql" + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://user:password@localhost", + query:"SELECT * FROM TestTable" +) +``` + +## Parameters + +### driverName +The driver used to connect to the SQL database. + +_**Data type:** String_ + +The following drivers are available: + +- awsathena +- bigquery +- mysql +- postgres +- snowflake +- sqlite3 – _Does not work with InfluxDB OSS or InfluxDB Cloud. More information [below](#query-an-sqlite-database)._ +- sqlserver, mssql + +### dataSourceName +The data source name (DSN) or connection string used to connect to the SQL database. +The string's form and structure depend on the [driver](#drivername) used. + +_**Data type:** String_ + +##### Driver dataSourceName examples +```sh +# Amazon Athena Driver DSN +s3://myorgqueryresults/?accessID=AKIAJLO3F...®ion=us-west-1&secretAccessKey=NnQ7MUMp9PYZsmD47c%2BSsXGOFsd%2F... +s3://myorgqueryresults/?accessID=AKIAJLO3F...&db=dbname&missingAsDefault=false&missingAsEmptyString=false®ion=us-west-1&secretAccessKey=NnQ7MUMp9PYZsmD47c%2BSsXGOFsd%2F...&WGRemoteCreation=false + +# MySQL Driver DSN +username:password@tcp(localhost:3306)/dbname?param=value + +# Postgres Driver DSN +postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full + +# Snowflake Driver DSNs +username[:password]@accountname/dbname/schemaname?param1=value1¶mN=valueN +username[:password]@accountname/dbname?param1=value1¶mN=valueN +username[:password]@hostname:port/dbname/schemaname?account=¶m1=value1¶mN=valueN + +# SQLite Driver DSN +file:/path/to/test.db?cache=shared&mode=ro + +# Microsoft SQL Server Driver DSNs +sqlserver://username:password@localhost:1234?database=examplebdb +server=localhost;user id=username;database=examplebdb; +server=localhost;user id=username;database=examplebdb;azure auth=ENV +server=localhost;user id=username;database=examplebdbr;azure tenant id=77e7d537;azure client id=58879ce8;azure client secret=0123456789 + +# Google BigQuery DSNs +bigquery://projectid/?param1=value¶m2=value +bigquery://projectid/location?param1=value¶m2=value +``` + +### query +The query to run against the SQL database. + +_**Data type:** String_ + +## Examples + +- [MySQL](#query-a-mysql-database) +- [Postgres](#query-a-postgres-database) +- [Snowflake](#query-a-snowflake-database) +- [SQLite](#query-an-sqlite-database) +- [Amazon Athena](#query-an-amazon-athena-database) +- [SQL Server](#query-a-sql-server-database) +- [Google BigQuery](#query-a-bigquery-database) + +{{% note %}} +The examples below use [InfluxDB secrets](/influxdb/cloud/security/secrets/) to populate +sensitive connection credentials. +{{% /note %}} + +### Query a MySQL database +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "MYSQL_USER") +password = secrets.get(key: "MYSQL_PASS") + +sql.from( + driverName: "mysql", + dataSourceName: "${username}:${password}@tcp(localhost:3306)/db", + query:"SELECT * FROM example_table" +) +``` + +### Query a Postgres database +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "POSTGRES_USER") +password = secrets.get(key: "POSTGRES_PASS") + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost", + query:"SELECT * FROM example_table" +) +``` + +### Query a Snowflake database +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "SNOWFLAKE_USER") +password = secrets.get(key: "SNOWFLAKE_PASS") +account = secrets.get(key: "SNOWFLAKE_ACCT") + +sql.from( + driverName: "snowflake", + dataSourceName: "${username}:${password}@${account}/db/exampleschema?warehouse=wh", + query: "SELECT * FROM example_table" +) +``` + +### Query an SQLite database + +{{% warn %}} +**InfluxDB OSS** and **InfluxDB Cloud** do not have direct access to the local filesystem +and cannot query SQLite data sources. +Use the [Flux REPL](/influxdb/cloud/tools/repl/) to query a SQLite data source +on your local filesystem. +{{% /warn %}} + +```js +import "sql" + +sql.from( + driverName: "sqlite3", + dataSourceName: "file:/path/to/test.db?cache=shared&mode=ro", + query: "SELECT * FROM example_table" +) +``` + +### Query an Amazon Athena database +```js +import "sql" +import "influxdata/influxdb/secrets" + +region = us-west-1 +accessID = secrets.get(key: "ATHENA_ACCESS_ID") +secretKey = secrets.get(key: "ATHENA_SECRET_KEY") + +sql.from( + driverName: "awsathena", + dataSourceName: "s3://myorgqueryresults/?accessID=${accessID}®ion=${region}&secretAccessKey=${secretKey}", + query:"SELECT * FROM example_table" +) +``` + +##### Athena connection string +To query an Amazon Athena database, use the following query parameters in your Athena +S3 connection string (DSN): + +\* Required + +- **region** - AWS region \* +- **accessID** - AWS IAM access ID \* +- **secretAccessKey** - AWS IAM secret key \* +- **db** - database name +- **WGRemoteCreation** - controls workgroup and tag creation +- **missingAsDefault** - replace missing data with default values +- **missingAsEmptyString** - replace missing data with empty strings + + +### Query a SQL Server database +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "SQLSERVER_USER") +password = secrets.get(key: "SQLSERVER_PASS") + +sql.from( + driverName: "sqlserver", + dataSourceName: "sqlserver://${username}:${password}@localhost:1234?database=examplebdb", + query: "GO SELECT * FROM Example.Table" +) +``` + +#### SQL Server ADO authentication +Use one of the following methods to provide SQL Server authentication credentials as +[ActiveX Data Objects (ADO)](https://docs.microsoft.com/en-us/sql/ado/guide/ado-introduction?view=sql-server-ver15) +connection string parameters: + +- [Retrieve authentication credentials from environment variables](#retrieve-authentication-credentials-from-environment-variables) +- [Retrieve authentication credentials from a file](#retrieve-authentication-credentials-from-a-file) +- [Specify authentication credentials in the connection string](#specify-authentication-credentials-in-the-connection-string) +- [Use a Managed identity in an Azure VM](#use-a-managed-identity-in-an-azure-vm) + +##### Retrieve authentication credentials from environment variables +``` +azure auth=ENV +``` + +##### Retrieve authentication credentials from a file +{{% warn %}} +**InfluxDB OSS** and **{{< cloud-name "short" >}}** user interfaces do _**not**_ provide +access to the underlying file system and do not support reading credentials from a file. +To retrieve SQL Server credentials from a file, execute the query in the +[Flux REPL](/influxdb/cloud/tools/repl/) on your local machine. +{{% /warn %}} + +```powershel +azure auth=C:\secure\azure.auth +``` + +##### Specify authentication credentials in the connection string +```powershell +# Example of providing tenant ID, client ID, and client secret token +azure tenant id=77...;azure client id=58...;azure client secret=0cf123.. + +# Example of providing tenant ID, client ID, certificate path and certificate password +azure tenant id=77...;azure client id=58...;azure certificate path=C:\secure\...;azure certificate password=xY... + +# Example of providing tenant ID, client ID, and Azure username and password +azure tenant id=77...;azure client id=58...;azure username=some@myorg;azure password=a1... +``` + +##### Use a managed identity in an Azure VM +_For information about managed identities, see [Microsoft managed identities](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview)._ + +``` +azure auth=MSI +``` + +### Query a BigQuery database +```js +import "sql" +import "influxdata/influxdb/secrets" +projectID = secrets.get(key: "BIGQUERY_PROJECT_ID") +apiKey = secrets.get(key: "BIGQUERY_APIKEY") +sql.from( + driverName: "bigquery", + dataSourceName: "bigquery://${projectID}/?apiKey=${apiKey}", + query:"SELECT * FROM exampleTable" +) +``` + +#### Common BigQuery URL parameters +- **dataset** - BigQuery dataset ID. When set, you can use unqualified table names in queries. + +#### BigQuery authentication parameters +The Flux BigQuery implementation uses the Google Cloud Go SDK. +Provide your authentication credentials using one of the following methods: + +- The `GOOGLE_APPLICATION_CREDENTIALS` environment variable that identifies the + location of your credential JSON file. +- Provide your BigQuery API key using the **apiKey** URL parameter in your BigQuery DSN. + + ###### Example apiKey URL parameter + ``` + bigquery://projectid/?apiKey=AIzaSyB6XK8IO5AzKZXoioQOVNTFYzbDBjY5hy4 + ``` + +- Provide your base-64 encoded service account, refresh token, or JSON credentials + using the **credentials** URL parameter in your BigQuery DSN. + + ###### Example credentials URL parameter + ``` + bigquery://projectid/?credentials=eyJ0eXBlIjoiYXV0... + ``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/sql/to.md b/content/influxdb/cloud/reference/flux/stdlib/sql/to.md new file mode 100644 index 000000000..6f9c994b7 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/sql/to.md @@ -0,0 +1,272 @@ +--- +title: sql.to() function +description: The `sql.to()` function writes data to a SQL database. +aliases: + - /influxdb/cloud/reference/flux/functions/sql/to/ +menu: + influxdb_cloud_ref: + name: sql.to + parent: SQL +weight: 202 +--- + +The `sql.to()` function writes data to a SQL database. + +_**Function type:** Output_ + +```js +import "sql" + +sql.to( + driverName: "mysql", + dataSourceName: "username:password@tcp(localhost:3306)/dbname?param=value", + table: "example_table", + batchSize: 10000 +) +``` + +## Parameters + +### driverName +The driver used to connect to the SQL database. + +_**Data type:** String_ + +The following drivers are available: + +- bigquery +- mysql +- postgres +- snowflake +- sqlite3 – _Does not work with InfluxDB OSS or InfluxDB Cloud. More information [below](#write-data-to-an-sqlite-database)._ +- sqlserver, mssql + +{{% warn %}} +#### sql.to does not support Amazon Athena +The `sql.to` function does not support writing data to [Amazon Athena](https://aws.amazon.com/athena/). +{{% /warn %}} + +### dataSourceName +The data source name (DSN) or connection string used to connect to the SQL database. +The string's form and structure depend on the [driver](#drivername) used. + +_**Data type:** String_ + +##### Driver dataSourceName examples +```sh +# Postgres Driver DSN +postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full + +# MySQL Driver DSN +username:password@tcp(localhost:3306)/dbname?param=value + +# Snowflake Driver DSNs +username[:password]@accountname/dbname/schemaname?param1=value1¶mN=valueN +username[:password]@accountname/dbname?param1=value1¶mN=valueN +username[:password]@hostname:port/dbname/schemaname?account=¶m1=value1¶mN=valueN + +# SQLite Driver DSN +file:/path/to/test.db?cache=shared&mode=rw + +# Microsoft SQL Server Driver DSNs +sqlserver://username:password@localhost:1234?database=examplebdb +server=localhost;user id=username;database=examplebdb; +server=localhost;user id=username;database=examplebdb;azure auth=ENV +server=localhost;user id=username;database=examplebdbr;azure tenant id=77e7d537;azure client id=58879ce8;azure client secret=0123456789 + +# Google BigQuery DSNs +bigquery://projectid/?param1=value¶m2=value +bigquery://projectid/location?param1=value¶m2=value +``` + +### table +The destination table. + +_**Data type:** String_ + +### batchSize +The number of parameters or columns that can be queued within each call to `Exec`. +Defaults to `10000`. + +_**Data type:** Integer_ + +{{% note %}} +If writing to a **SQLite** database, set `batchSize` to `999` or less. +{{% /note %}} + +## Examples + +- [MySQL](#write-data-to-a-mysql-database) +- [Postgres](#write-data-to-a-postgres-database) +- [Snowflake](#write-data-to-a-snowflake-database) +- [SQLite](#write-data-to-an-sqlite-database) +- [SQL Server](#write-data-to-a-sql-server-database) +- [Google BigQuery](#write-data-to-a-sql-server-database) + +{{% note %}} +The examples below use [InfluxDB secrets](/influxdb/cloud/security/secrets/) to populate +sensitive connection credentials. +{{% /note %}} + +### Write data to a MySQL database +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "MYSQL_USER") +password = secrets.get(key: "MYSQL_PASS") + +sql.to( + driverName: "mysql", + dataSourceName: "${username}:${password}@tcp(localhost:3306)/db", + table: "example_table" +) +``` + +### Write data to a Postgres database +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "POSTGRES_USER") +password = secrets.get(key: "POSTGRES_PASS") + +sql.to( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost", + table: "example_table" +) +``` + +### Write data to a Snowflake database +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "SNOWFLAKE_USER") +password = secrets.get(key: "SNOWFLAKE_PASS") +account = secrets.get(key: "SNOWFLAKE_ACCT") + +sql.to( + driverName: "snowflake", + dataSourceName: "${username}:${password}@${account}/db/exampleschema?warehouse=wh", + table: "example_table" +) +``` + +### Write data to an SQLite database + +{{% warn %}} +**InfluxDB OSS** and **InfluxDB Cloud** do not have direct access to the local filesystem +and cannot write to SQLite data sources. +Use the [Flux REPL](/influxdb/cloud/tools/repl/) to write to an SQLite data +source on your local filesystem. +{{% /warn %}} + +```js +import "sql" + +sql.to( + driverName: "sqlite3", + dataSourceName: "file:/path/to/test.db?cache=shared&mode=rw", + table: "example_table" +) +``` + +### Write data to a SQL Server database +```js +import "sql" +import "influxdata/influxdb/secrets" + +username = secrets.get(key: "SQLSERVER_USER") +password = secrets.get(key: "SQLSERVER_PASS") + +sql.to( + driverName: "sqlserver", + dataSourceName: "sqlserver://${username}:${password}@localhost:1234?database=examplebdb", + table: "Example.Table" +) +``` + +#### SQL Server ADO authentication +Use one of the following methods to provide SQL Server authentication credentials as +[ActiveX Data Objects (ADO)](https://docs.microsoft.com/en-us/sql/ado/guide/ado-introduction?view=sql-server-ver15) +connection string parameters: + +- [Retrieve authentication credentials from environment variables](#retrieve-authentication-credentials-from-environment-variables) +- [Retrieve authentication credentials from a file](#retrieve-authentication-credentials-from-a-file) +- [Specify authentication credentials in the connection string](#specify-authentication-credentials-in-the-connection-string) +- [Use a Managed identity in an Azure VM](#use-a-managed-identity-in-an-azure-vm) + +##### Retrieve authentication credentials from environment variables +``` +azure auth=ENV +``` + +##### Retrieve authentication credentials from a file +{{% warn %}} +**InfluxDB OSS** and **{{< cloud-name "short" >}}** user interfaces do _**not**_ provide +access to the underlying file system and do not support reading credentials from a file. +To retrieve SQL Server credentials from a file, execute the query in the +[Flux REPL](/influxdb/cloud/tools/repl/) on your local machine. +{{% /warn %}} + +```powershell +azure auth=C:\secure\azure.auth +``` + +##### Specify authentication credentials in the connection string +```powershell +# Example of providing tenant ID, client ID, and client secret token +azure tenant id=77...;azure client id=58...;azure client secret=0cf123.. + +# Example of providing tenant ID, client ID, certificate path and certificate password +azure tenant id=77...;azure client id=58...;azure certificate path=C:\secure\...;azure certificate password=xY... + +# Example of providing tenant ID, client ID, and Azure username and password +azure tenant id=77...;azure client id=58...;azure username=some@myorg;azure password=a1... +``` + +##### Use a managed identity in an Azure VM +_For information about managed identities, see [Microsoft managed identities](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview)._ + +``` +azure auth=MSI +``` + +### Write to a BigQuery database +```js +import "sql" +import "influxdata/influxdb/secrets" +projectID = secrets.get(key: "BIGQUERY_PROJECT_ID") +apiKey = secrets.get(key: "BIGQUERY_APIKEY") +sql.to( + driverName: "bigquery", + dataSourceName: "bigquery://${projectID}/?apiKey=${apiKey}", + table:"exampleTable" +) +``` + +#### Common BigQuery URL parameters +- **dataset** - BigQuery dataset ID. When set, you can use unqualified table names in queries. + +#### BigQuery authentication parameters +The Flux BigQuery implementation uses the Google Cloud Go SDK. +Provide your authentication credentials using one of the following methods: + +- The `GOOGLE_APPLICATION_CREDENTIALS` environment variable that identifies the + location of your credential JSON file. +- Provide your BigQuery API key using the **apiKey** URL parameter in your BigQuery DSN. + + ###### Example apiKey URL parameter + ``` + bigquery://projectid/?apiKey=AIzaSyB6XK8IO5AzKZXoioQOVNTFYzbDBjY5hy4 + ``` + +- Provide your base-64 encoded service account, refresh token, or JSON credentials + using the **credentials** URL parameter in your BigQuery DSN. + + ###### Example credentials URL parameter + ``` + bigquery://projectid/?credentials=eyJ0eXBlIjoiYXV0... + ``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/_index.md b/content/influxdb/cloud/reference/flux/stdlib/strings/_index.md new file mode 100644 index 000000000..ef5a9c6e1 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux strings package +list_title: Strings package +description: > + The Flux strings package provides functions to manipulate UTF-8 encoded strings. + Import the `strings` package. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/ +menu: + influxdb_cloud_ref: + name: Strings + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [strings, functions, package] +--- + +The Flux string package provides functions to manipulate UTF-8 encoded strings. +Import the `strings` package: + +```js +import "strings" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/compare.md b/content/influxdb/cloud/reference/flux/stdlib/strings/compare.md new file mode 100644 index 000000000..1b55e3949 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/compare.md @@ -0,0 +1,56 @@ +--- +title: strings.compare() function +description: The strings.compare() function compares the lexicographical order of two strings. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/compare/ +menu: + influxdb_cloud_ref: + name: strings.compare + parent: Strings +weight: 301 +--- + +The `strings.compare()` function compares the lexicographical order of two strings. + +_**Output data type:** Integer_ + +```js +import "strings" + +strings.compare(v: "a", t: "b") + +// returns -1 +``` + +#### Return values +| Comparison | Return value | +|:----------:|:------------:| +| `v < t` | `-1` | +| `v == t` | `0` | +| `v > t` | `1` | + +## Parameters + +### v +The string value to compare. + +_**Data type:** String_ + +### t +The string value to compare against. + +_**Data type:** String_ + +## Examples + +###### Compare the lexicographical order of column values +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + _value: strings.compare(v: r.tag1, t: r.tag2) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/containsany.md b/content/influxdb/cloud/reference/flux/stdlib/strings/containsany.md new file mode 100644 index 000000000..997dd4506 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/containsany.md @@ -0,0 +1,54 @@ +--- +title: strings.containsAny() function +description: > + The strings.containsAny() function reports whether a specified string contains + any characters from from another string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/containsany/ +menu: + influxdb_cloud_ref: + name: strings.containsAny + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/containsstr +--- + +The `strings.containsAny()` function reports whether a specified string contains +characters from another string. + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.containsAny(v: "abc", chars: "and") + +// returns true +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### chars +Characters to search for. + +_**Data type:** String_ + +## Examples + +###### Report if a string contains specific characters +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + _value: strings.containsAny(v: r.price, chars: "£$¢") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/containsstr.md b/content/influxdb/cloud/reference/flux/stdlib/strings/containsstr.md new file mode 100644 index 000000000..1493e01d2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/containsstr.md @@ -0,0 +1,51 @@ +--- +title: strings.containsStr() function +description: The strings.containsStr() function reports whether a string contains a specified substring. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/containsstr/ +menu: + influxdb_cloud_ref: + name: strings.containsStr + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/containsany +--- + +The `strings.containsStr()` function reports whether a string contains a specified substring. + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.containsStr(v: "This and that", substr: "and") + +// returns true +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### substr +The substring value to search for. + +_**Data type:** String_ + +## Examples + +###### Report if a string contains a specific substring +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + _value: strings.containsStr(v: r.author, substr: "John") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/countstr.md b/content/influxdb/cloud/reference/flux/stdlib/strings/countstr.md new file mode 100644 index 000000000..699cc6200 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/countstr.md @@ -0,0 +1,63 @@ +--- +title: strings.countStr() function +description: > + The strings.countStr() function counts the number of non-overlapping instances + of a substring appears in a string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/countstr/ +menu: + influxdb_cloud_ref: + name: strings.countStr + parent: Strings +weight: 301 +--- + +The `strings.countStr()` function counts the number of non-overlapping instances +of a substring appears in a string. + +_**Output data type:** Integer_ + +```js +import "strings" + +strings.countStr(v: "Hello mellow fellow", substr: "ello") + +// returns 3 +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### substr +The substring to count. + +_**Data type:** String_ + +{{% note %}} +The function counts only non-overlapping instances of `substr`. +For example: + +```js +strings.coutnStr(v: "ooooo", substr: "oo") + +// Returns 2 -- (oo)(oo)o +``` +{{% /note %}} + +## Examples + +###### Count instances of a substring within a string +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + _value: strings.countStr(v: r.message, substr: "uh") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/equalfold.md b/content/influxdb/cloud/reference/flux/stdlib/strings/equalfold.md new file mode 100644 index 000000000..d1c1ead4d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/equalfold.md @@ -0,0 +1,54 @@ +--- +title: strings.equalFold() function +description: > + The strings.equalFold() function reports whether two UTF-8 strings are equal + under Unicode case-folding. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/equalfold/ +menu: + influxdb_cloud_ref: + name: strings.equalFold + parent: Strings +weight: 301 +--- + +The `strings.equalFold()` function reports whether two UTF-8 strings are equal +under Unicode case-folding. + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.equalFold(v: "Go", t: "go") + +// returns true +``` + +## Parameters + +### v +The string value to compare. + +_**Data type:** String_ + +### t +The string value to compare against. + +_**Data type:** String_ + +## Examples + +###### Ignore case when testing if two strings are the same +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + string1: r.string1, + string2: r.string2, + same: strings.equalFold(v: r.string1, t: r.string2) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/hasprefix.md b/content/influxdb/cloud/reference/flux/stdlib/strings/hasprefix.md new file mode 100644 index 000000000..3b7e56aa8 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/hasprefix.md @@ -0,0 +1,45 @@ +--- +title: strings.hasPrefix() function +description: The strings.hasPrefix() function indicates if a string begins with a specific prefix. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/hasprefix/ +menu: + influxdb_cloud_ref: + name: strings.hasPrefix + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/hassuffix +--- + +The `strings.hasPrefix()` function indicates if a string begins with a specified prefix. + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.hasPrefix(v: "go gopher", prefix: "go") + +// returns true +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### prefix +The prefix to search for. + +_**Data type:** String_ + +###### Filter based on the presence of a prefix in a column value +```js +import "strings" + +data + |> filter(fn:(r) => strings.hasPrefix(v: r.metric, prefix: "int_" )) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/hassuffix.md b/content/influxdb/cloud/reference/flux/stdlib/strings/hassuffix.md new file mode 100644 index 000000000..62f566fb7 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/hassuffix.md @@ -0,0 +1,45 @@ +--- +title: strings.hasSuffix() function +description: The strings.hasSuffix() function indicates if a string ends with a specified suffix. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/hassuffix/ +menu: + influxdb_cloud_ref: + name: strings.hasSuffix + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/hasprefix +--- + +The `strings.hasSuffix()` function indicates if a string ends with a specified suffix. + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.hasSuffix(v: "go gopher", suffix: "go") + +// returns false +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### suffix +The suffix to search for. + +_**Data type:** String_ + +###### Filter based on the presence of a suffix in a column value +```js +import "strings" + +data + |> filter(fn:(r) => strings.hasSuffix(v: r.metric, suffix: "_count" )) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/index-func.md b/content/influxdb/cloud/reference/flux/stdlib/strings/index-func.md new file mode 100644 index 000000000..6072496ab --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/index-func.md @@ -0,0 +1,56 @@ +--- +title: strings.index() function +description: > + The strings.index() function returns the index of the first instance of a substring + in another string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/index-func/ +menu: + influxdb_cloud_ref: + name: strings.index + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/indexany/ + - /influxdb/cloud/reference/flux/stdlib/strings/lastindex/ + - /influxdb/cloud/reference/flux/stdlib/strings/lastindexany/ +--- + +The `strings.index()` function returns the index of the first instance of a substring +in a string. If the substring is not present, it returns `-1`. + +_**Output data type:** Integer_ + +```js +import "strings" + +strings.index(v: "go gopher", substr: "go") + +// returns 0 +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### substr +The substring to search for. + +_**Data type:** String_ + +## Examples + +###### Find the first occurrence of a substring +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + the_index: strings.index(v: r.pageTitle, substr: "the") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/indexany.md b/content/influxdb/cloud/reference/flux/stdlib/strings/indexany.md new file mode 100644 index 000000000..8f2f37985 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/indexany.md @@ -0,0 +1,55 @@ +--- +title: strings.indexAny() function +description: > + The strings.indexAny() function returns the index of the first instance of specified characters in a string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/indexany/ +menu: + influxdb_cloud_ref: + name: strings.indexAny + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/index-func/ + - /influxdb/cloud/reference/flux/stdlib/strings/lastindex/ + - /influxdb/cloud/reference/flux/stdlib/strings/lastindexany/ +--- + +The `strings.indexAny()` function returns the index of the first instance of specified characters in a string. +If none of the specified characters are present, it returns `-1`. + +_**Output data type:** Integer_ + +```js +import "strings" + +strings.indexAny(v: "chicken", chars: "aeiouy") + +// returns 2 +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### chars +Characters to search for. + +_**Data type:** String_ + +## Examples + +###### Find the first occurrence of characters from a string +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + charIndex: strings.indexAny(v: r._field, chars: "_-") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/isdigit.md b/content/influxdb/cloud/reference/flux/stdlib/strings/isdigit.md new file mode 100644 index 000000000..717658518 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/isdigit.md @@ -0,0 +1,42 @@ +--- +title: strings.isDigit() function +description: The strings.isDigit() function tests if a single character string is a digit (0-9). +aliases: + - /influxdb/cloud/reference/flux/functions/strings/isdigit/ +menu: + influxdb_cloud_ref: + name: strings.isDigit + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/isletter/ +--- + +The `strings.isDigit()` function tests if a single-character string is a digit (0-9). + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.isDigit(v: "A") + +// returns false +``` + +## Parameters + +### v +The single-character string to test. + +_**Data type:** String_ + +## Examples + +###### Filter by columns with digits as values +```js +import "strings" + +data + |> filter(fn: (r) => strings.isDigit(v: r.serverRef)) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/isletter.md b/content/influxdb/cloud/reference/flux/stdlib/strings/isletter.md new file mode 100644 index 000000000..7a6e3de83 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/isletter.md @@ -0,0 +1,42 @@ +--- +title: strings.isLetter() function +description: The strings.isLetter() function tests if a single character string is a letter (a-z, A-Z). +aliases: + - /influxdb/cloud/reference/flux/functions/strings/isletter/ +menu: + influxdb_cloud_ref: + name: strings.isLetter + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/isdigit/ +--- + +The `strings.isLetter()` function tests if a single character string is a letter (a-z, A-Z). + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.isLetter(v: "A") + +// returns true +``` + +## Parameters + +### v +The single character string to test. + +_**Data type:** String_ + +## Examples + +###### Filter by columns with single-letter values +```js +import "strings" + +data + |> filter(fn: (r) => strings.isLetter(v: r.serverRef)) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/islower.md b/content/influxdb/cloud/reference/flux/stdlib/strings/islower.md new file mode 100644 index 000000000..c82742e75 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/islower.md @@ -0,0 +1,42 @@ +--- +title: strings.isLower() function +description: The strings.isLower() function tests if a single-character string is lowercase. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/islower/ +menu: + influxdb_cloud_ref: + name: strings.isLower + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/isupper +--- + +The `strings.isLower()` function tests if a single-character string is lowercase. + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.isLower(v: "a") + +// returns true +``` + +## Parameters + +### v +The single-character string value to test. + +_**Data type:** String_ + +## Examples + +###### Filter by columns with single-letter lowercase values +```js +import "strings" + +data + |> filter(fn: (r) => strings.isLower(v: r.host)) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/isupper.md b/content/influxdb/cloud/reference/flux/stdlib/strings/isupper.md new file mode 100644 index 000000000..a0b1ba372 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/isupper.md @@ -0,0 +1,42 @@ +--- +title: strings.isUpper() function +description: The strings.isUpper() function tests if a single character string is uppercase. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/isupper/ +menu: + influxdb_cloud_ref: + name: strings.isUpper + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/islower +--- + +The `strings.isUpper()` function tests if a single character string is uppercase. + +_**Output data type:** Boolean_ + +```js +import "strings" + +strings.isUpper(v: "A") + +// returns true +``` + +## Parameters + +### v +The single-character string value to test. + +_**Data type:** String_ + +## Examples + +###### Filter by columns with single-letter uppercase values +```js +import "strings" + +data + |> filter(fn: (r) => strings.isUpper(v: r.host)) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/joinstr.md b/content/influxdb/cloud/reference/flux/stdlib/strings/joinstr.md new file mode 100644 index 000000000..c5aac4669 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/joinstr.md @@ -0,0 +1,49 @@ +--- +title: strings.joinStr() function +description: > + The strings.joinStr() function concatenates the elements of a string array into + a single string using a specified separator. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/joinstr/ +menu: + influxdb_cloud_ref: + name: strings.joinStr + parent: Strings +weight: 301 +--- + +The `strings.joinStr()` function concatenates elements of a string array into +a single string using a specified separator. + +_**Output data type:** String_ + +```js +import "strings" + +strings.joinStr(arr: ["a", "b", "c"], v: ",") + +// returns "a,b,c" +``` + +## Parameters + +### arr +The array of strings to concatenate. + +_**Data type:** Array of strings_ + +### v +The separator to use in the concatenated value. + +_**Data type:** String_ + +## Examples + +###### Join a list of strings into a single string +```js +import "strings" + +searchTags = ["tag1", "tag2", "tag3"] + +strings.joinStr(arr: searchTags, v: ",")) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/lastindex.md b/content/influxdb/cloud/reference/flux/stdlib/strings/lastindex.md new file mode 100644 index 000000000..d410618d9 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/lastindex.md @@ -0,0 +1,56 @@ +--- +title: strings.lastIndex() function +description: > + The strings.lastIndex() function returns the index of the last instance of a substring + in a string or `-1` if substring is not present. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/lastindex/ +menu: + influxdb_cloud_ref: + name: strings.lastIndex + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/index/ + - /influxdb/cloud/reference/flux/stdlib/strings/indexany/ + - /influxdb/cloud/reference/flux/stdlib/strings/lastindexany/ +--- + +The `strings.lastIndex()` function returns the index of the last instance of a substring +in a string. If the substring is not present, the function returns `-1`. + +_**Output data type:** Integer_ + +```js +import "strings" + +strings.lastIndex(v: "go gopher", substr: "go") + +// returns 3 +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### substr +The substring to search for. + +_**Data type:** String_ + +## Examples + +###### Find the last occurrence of a substring +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + the_index: strings.lastIndex(v: r.pageTitle, substr: "the") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/lastindexany.md b/content/influxdb/cloud/reference/flux/stdlib/strings/lastindexany.md new file mode 100644 index 000000000..568d05519 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/lastindexany.md @@ -0,0 +1,54 @@ +--- +title: strings.lastIndexAny() function +description: The `strings.lastIndexAny()` function returns the index of the last instance of any specified characters in a string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/lastindexany/ +menu: + influxdb_cloud_ref: + name: strings.lastIndexAny + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/index/ + - /influxdb/cloud/reference/flux/stdlib/strings/indexany/ + - /influxdb/cloud/reference/flux/stdlib/strings/lastindex/ +--- + +The `strings.lastIndexAny()` function returns the index of the last instance of any specified characters in a string. +If none of the specified characters are present, the function returns `-1`. + +_**Output data type:** Integer_ + +```js +import "strings" + +strings.lastIndexAny(v: "chicken", chars: "aeiouy") + +// returns 5 +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### chars +Characters to search for. + +_**Data type:** String_ + +## Examples + +###### Find the last occurrence of characters from a string +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + charLastIndex: strings.lastIndexAny(v: r._field, chars: "_-") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/repeat.md b/content/influxdb/cloud/reference/flux/stdlib/strings/repeat.md new file mode 100644 index 000000000..c8f94ed77 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/repeat.md @@ -0,0 +1,50 @@ +--- +title: strings.repeat() function +description: The strings.repeat() function returns a string consisting of `i` copies of a specified string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/repeat/ +menu: + influxdb_cloud_ref: + name: strings.repeat + parent: Strings +weight: 301 +--- + +The `strings.repeat()` function returns a string consisting of `i` copies of a specified string. + +_**Output data type:** String_ + +```js +import "strings" + +strings.repeat(v: "ha", i: 3) + +// returns "hahaha" +``` + +## Parameters + +### v +The string value to repeat. + +_**Data type:** String_ + +### i +The number of times to repeat `v`. + +_**Data type:** Integer_ + +## Examples + +###### Repeat a string based on existing columns +```js +import "strings" + +data + |> map(fn: (r) => ({ + laugh: r.laugh + intensity: r.intensity + laughter: strings.repeat(v: r.laugh, i: r.intensity) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/replace.md b/content/influxdb/cloud/reference/flux/stdlib/strings/replace.md new file mode 100644 index 000000000..92e6cd7b3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/replace.md @@ -0,0 +1,64 @@ +--- +title: strings.replace() function +description: > + The strings.replace() function replaces the first `i` non-overlapping instances + of a substring with a specified replacement. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/replace/ +menu: + influxdb_cloud_ref: + name: strings.replace + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/replaceall +--- + +The `strings.replace()` function replaces the first `i` non-overlapping instances +of a substring with a specified replacement. + +_**Output data type:** String_ + +```js +import "strings" + +strings.replace(v: "oink oink oink", t: "oink", u: "moo", i: 2) + +// returns "moo moo oink" +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### t +The substring value to replace. + +_**Data type:** String_ + +### u +The replacement for `i` instances of `t`. + +_**Data type:** String_ + +### i +The number of non-overlapping `t` matches to replace. + +_**Data type:** Integer_ + +## Examples + +###### Replace a specific number of string matches +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + content: strings.replace(v: r.content, t: "he", u: "her", i: 3) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/replaceall.md b/content/influxdb/cloud/reference/flux/stdlib/strings/replaceall.md new file mode 100644 index 000000000..735dfc8d6 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/replaceall.md @@ -0,0 +1,59 @@ +--- +title: strings.replaceAll() function +description: > + The strings.replaceAll() function replaces all non-overlapping instances of a + substring with a specified replacement. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/replaceall/ +menu: + influxdb_cloud_ref: + name: strings.replaceAll + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/replace +--- + +The `strings.replaceAll()` function replaces all non-overlapping instances of a +substring with a specified replacement. + +_**Output data type:** String_ + +```js +import "strings" + +strings.replaceAll(v: "oink oink oink", t: "oink", u: "moo") + +// returns "moo moo moo" +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### t +The substring to replace. + +_**Data type:** String_ + +### u +The replacement for all instances of `t`. + +_**Data type:** String_ + +## Examples + +###### Replace string matches +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + content: strings.replaceAll(v: r.content, t: "he", u: "her") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/split.md b/content/influxdb/cloud/reference/flux/stdlib/strings/split.md new file mode 100644 index 000000000..d521ed54d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/split.md @@ -0,0 +1,52 @@ +--- +title: strings.split() function +description: > + The strings.split() function splits a string on a specified separator and returns + an array of substrings. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/split/ +menu: + influxdb_cloud_ref: + name: strings.split + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/splitafter + - /influxdb/cloud/reference/flux/stdlib/strings/splitaftern + - /influxdb/cloud/reference/flux/stdlib/strings/splitn +--- + +The `strings.split()` function splits a string on a specified separator and returns +an array of substrings. + +_**Output data type:** Array of strings_ + +```js +import "strings" + +strings.split(v: "a flux of foxes", t: " ") + +// returns ["a", "flux", "of", "foxes"] +``` + +## Parameters + +### v +The string value to split. + +_**Data type:** String_ + +### t +The string value that acts as the separator. + +_**Data type:** String_ + +## Examples + +###### Split a string into an array of substrings +```js +import "strings" + +data + |> map (fn:(r) => strings.split(v: r.searchTags, t: ",")) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/splitafter.md b/content/influxdb/cloud/reference/flux/stdlib/strings/splitafter.md new file mode 100644 index 000000000..cbe5c985b --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/splitafter.md @@ -0,0 +1,53 @@ +--- +title: strings.splitAfter() function +description: > + The strings.splitAfter() function splits a string after a specified separator and returns + an array of substrings. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/splitafter/ +menu: + influxdb_cloud_ref: + name: strings.splitAfter + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/split + - /influxdb/cloud/reference/flux/stdlib/strings/splitaftern + - /influxdb/cloud/reference/flux/stdlib/strings/splitn +--- + +The `strings.splitAfter()` function splits a string after a specified separator and returns +an array of substrings. +Split substrings include the separator, `t`. + +_**Output data type:** Array of strings_ + +```js +import "strings" + +strings.splitAfter(v: "a flux of foxes", t: " ") + +// returns ["a ", "flux ", "of ", "foxes"] +``` + +## Parameters + +### v +The string value to split. + +_**Data type:** String_ + +### t +The string value that acts as the separator. + +_**Data type:** String_ + +## Examples + +###### Split a string into an array of substrings +```js +import "strings" + +data + |> map (fn:(r) => strings.splitAfter(v: r.searchTags, t: ",")) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/splitaftern.md b/content/influxdb/cloud/reference/flux/stdlib/strings/splitaftern.md new file mode 100644 index 000000000..2b9674d11 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/splitaftern.md @@ -0,0 +1,60 @@ +--- +title: strings.splitAfterN() function +description: > + The strings.splitAfterN() function splits a string after a specified separator and returns + an array of `i` substrings. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/splitaftern/ +menu: + influxdb_cloud_ref: + name: strings.splitAfterN + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/split + - /influxdb/cloud/reference/flux/stdlib/strings/splitafter + - /influxdb/cloud/reference/flux/stdlib/strings/splitn +--- + +The `strings.splitAfterN()` function splits a string after a specified separator and returns +an array of `i` substrings. +Split substrings include the separator `t`. + +_**Output data type:** Array of strings_ + +```js +import "strings" + +strings.splitAfterN(v: "a flux of foxes", t: " ", i: 3) + +// returns ["a ", "flux ", "of foxes"] +``` + +## Parameters + +### v +The string value to split. + +_**Data type:** String_ + +### t +The string value that acts as the separator. + +_**Data type:** String_ + +### i +The maximum number of split substrings to return. +`-1` returns all matching substrings. +The last substring is the unsplit remainder. + +_**Data type:** Integer_ + +## Examples + +###### Split a string into an array of substrings +```js +import "strings" + +data + |> map (fn:(r) => strings.splitAfterN(v: r.searchTags, t: ",")) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/splitn.md b/content/influxdb/cloud/reference/flux/stdlib/strings/splitn.md new file mode 100644 index 000000000..430ba86ec --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/splitn.md @@ -0,0 +1,59 @@ +--- +title: strings.splitN() function +description: > + The strings.splitN() function splits a string on a specified separator and returns + an array of `i` substrings. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/splitn/ +menu: + influxdb_cloud_ref: + name: strings.splitN + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/split + - /influxdb/cloud/reference/flux/stdlib/strings/splitafter + - /influxdb/cloud/reference/flux/stdlib/strings/splitaftern +--- + +The `strings.splitN()` function splits a string on a specified separator and returns +an array of `i` substrings. + +_**Output data type:** Array of strings_ + +```js +import "strings" + +strings.splitN(v: "a flux of foxes", t: " ", i: 3) + +// returns ["a", "flux", "of foxes"] +``` + +## Parameters + +### v +The string value to split. + +_**Data type:** String_ + +### t +The string value that acts as the separator. + +_**Data type:** String_ + +### i +The maximum number of split substrings to return. +`-1` returns all matching substrings. +The last substring is the unsplit remainder. + +_**Data type:** Integer_ + +## Examples + +###### Split a string into an array of substrings +```js +import "strings" + +data + |> map (fn:(r) => strings.splitN(v: r.searchTags, t: ",")) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/strlen.md b/content/influxdb/cloud/reference/flux/stdlib/strings/strlen.md new file mode 100644 index 000000000..7cdf177da --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/strlen.md @@ -0,0 +1,55 @@ +--- +title: strings.strlen() function +description: > + The strings.strlen() function returns the length of a string. + String length is determined by the number of UTF code points a string contains. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/strlen/ +menu: + influxdb_cloud_ref: + name: strings.strlen + parent: Strings +weight: 301 +--- + +The `strings.strlen()` function returns the length of a string. +String length is determined by the number of UTF code points a string contains. + +_**Output data type:** Integer_ + +```js +import "strings" + +strings.strlen(v: "apple") + +// returns 5 +``` + +## Parameters + +### v +The string value to measure. + +_**Data type:** String_ + +## Examples + +###### Filter based on string value length +```js +import "strings" + +data + |> filter(fn: (r) => strings.strlen(v: r._measurement) <= 4) +``` + +###### Store the length of string values +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + length: strings.strlen(v: r._value) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/substring.md b/content/influxdb/cloud/reference/flux/stdlib/strings/substring.md new file mode 100644 index 000000000..c132a0ae8 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/substring.md @@ -0,0 +1,57 @@ +--- +title: strings.substring() function +description: > + The strings.substring() function returns a substring based on `start` and `end` parameters. + Indices are based on UTF code points. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/substring/ +menu: + influxdb_cloud_ref: + name: strings.substring + parent: Strings +weight: 301 +--- + +The `strings.substring()` function returns a substring based on `start` and `end` parameters. +These parameters are represent indices of UTF code points in the string. + +_**Output data type:** String_ + +```js +import "strings" + +strings.substring(v: "influx", start: 0, end: 3) + +// returns "infl" +``` + +## Parameters + +### v +The string value to search. + +_**Data type:** String_ + +### start +The starting index of the substring. + +_**Data type:** Integer_ + +### end +The ending index of the substring. + +_**Data type:** Integer_ + +## Examples + +###### Store the first four characters of a string +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + abbr: strings.substring(v: r.name, start: 0, end: 3) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/title.md b/content/influxdb/cloud/reference/flux/stdlib/strings/title.md new file mode 100644 index 000000000..78ef462e3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/title.md @@ -0,0 +1,44 @@ +--- +title: strings.title() function +description: The strings.title() function converts a string to title case. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/title/ +menu: + influxdb_cloud_ref: + name: strings.title + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/tolower + - /influxdb/cloud/reference/flux/stdlib/strings/totitle + - /influxdb/cloud/reference/flux/stdlib/strings/toupper +--- + +The `strings.title()` function converts a string to title case. + +_**Output data type:** String_ + +```js +import "strings" + +strings.title(v: "a flux of foxes") + +// returns "A Flux Of Foxes" +``` + +## Parameters + +### v +The string value to convert. + +_**Data type:** String_ + +## Examples + +###### Convert all values of a column to title case +```js +import "strings" + +data + |> map(fn: (r) => ({ r with pageTitle: strings.title(v: r.pageTitle) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/tolower.md b/content/influxdb/cloud/reference/flux/stdlib/strings/tolower.md new file mode 100644 index 000000000..02386eedd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/tolower.md @@ -0,0 +1,47 @@ +--- +title: strings.toLower() function +description: The strings.toLower() function converts a string to lowercase. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/tolower/ +menu: + influxdb_cloud_ref: + name: strings.toLower + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/totitle + - /influxdb/cloud/reference/flux/stdlib/strings/toupper + - /influxdb/cloud/reference/flux/stdlib/strings/title +--- + +The `strings.toLower()` function converts a string to lowercase. + +_**Output data type:** String_ + +```js +import "strings" + +strings.toLower(v: "KOALA") + +// returns "koala" +``` + +## Parameters + +### v +The string value to convert. + +_**Data type:** String_ + +## Examples + +###### Convert all values of a column to lower case +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with exclamation: strings.toLower(v: r.exclamation) + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/totitle.md b/content/influxdb/cloud/reference/flux/stdlib/strings/totitle.md new file mode 100644 index 000000000..d5ea08b80 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/totitle.md @@ -0,0 +1,57 @@ +--- +title: strings.toTitle() function +description: The strings.toTitle() function converts all characters in a string to title case. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/totitle/ +menu: + influxdb_cloud_ref: + name: strings.toTitle + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/toupper + - /influxdb/cloud/reference/flux/stdlib/strings/tolower + - /influxdb/cloud/reference/flux/stdlib/strings/title +--- + +The `strings.toTitle()` function converts all characters in a string to title case. + +_**Output data type:** String_ + +```js +import "strings" + +strings.toTitle(v: "a flux of foxes") + +// returns "A FLUX OF FOXES" +``` + +## Parameters + +### v +The string value to convert. + +_**Data type:** String_ + +## Examples + +###### Covert characters in a string to title case +```js +import "strings" + +data + |> map(fn: (r) => ({ r with pageTitle: strings.toTitle(v: r.pageTitle) })) +``` + +{{% note %}} +#### The difference between toTitle and toUpper +The results of `toTitle()` and `toUpper` are often the same, however the difference +is visible with special characters: + +```js +str = "dz" + +strings.toTitle(v: str) // Returns Dz +strings.toUpper(v: str) // Returns DZ +``` +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/toupper.md b/content/influxdb/cloud/reference/flux/stdlib/strings/toupper.md new file mode 100644 index 000000000..572128564 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/toupper.md @@ -0,0 +1,57 @@ +--- +title: strings.toUpper() function +description: The strings.toUpper() function converts a string to uppercase. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/toupper/ +menu: + influxdb_cloud_ref: + name: strings.toUpper + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/totitle + - /influxdb/cloud/reference/flux/stdlib/strings/tolower + - /influxdb/cloud/reference/flux/stdlib/strings/title +--- + +The `strings.toUpper()` function converts a string to uppercase. + +_**Output data type:** String_ + +```js +import "strings" + +strings.toUpper(v: "koala") + +// returns "KOALA" +``` + +## Parameters + +### v +The string value to convert. + +_**Data type:** String_ + +## Examples + +###### Convert all values of a column to upper case +```js +import "strings" + +data + |> map(fn: (r) => ({ r with envVars: strings.toUpper(v: r.envVars) })) +``` + +{{% note %}} +#### The difference between toTitle and toUpper +The results of `toUpper()` and `toTitle` are often the same, however the difference +is visible when using special characters: + +```js +str = "dz" + +strings.toUpper(v: str) // Returns DZ +strings.toTitle(v: str) // Returns Dz +``` +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/trim.md b/content/influxdb/cloud/reference/flux/stdlib/strings/trim.md new file mode 100644 index 000000000..16abf73cc --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/trim.md @@ -0,0 +1,59 @@ +--- +title: strings.trim() function +description: > + The strings.trim() function removes leading and trailing characters specified + in the cutset from a string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/trim/ +menu: + influxdb_cloud_ref: + name: strings.trim + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/trimleft + - /influxdb/cloud/reference/flux/stdlib/strings/trimright + - /influxdb/cloud/reference/flux/stdlib/strings/trimprefix + - /influxdb/cloud/reference/flux/stdlib/strings/trimsuffix + - /influxdb/cloud/reference/flux/stdlib/strings/trimspace +--- + +The `strings.trim()` function removes leading and trailing characters specified +in the [`cutset`](#cutset) from a string. + +_**Output data type:** String_ + +```js +import "strings" + +strings.trim(v: ".abc.", cutset: ".") + +// returns "abc" +``` + +## Parameters + +### v +String to remove characters from. + +_**Data type:** String_ + +### cutset +The leading and trailing characters to remove from the string. +Only characters that match the `cutset` string exactly are trimmed. + +_**Data type:** String_ + +## Examples + +###### Trim leading and trailing periods from all values in a column +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + variables: strings.trim(v: r.variables, cutset: ".") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/trimleft.md b/content/influxdb/cloud/reference/flux/stdlib/strings/trimleft.md new file mode 100644 index 000000000..3959bf2cd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/trimleft.md @@ -0,0 +1,57 @@ +--- +title: strings.trimLeft() function +description: > + The strings.trimLeft() function removes specified leading characters from a string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/trimleft/ +menu: + influxdb_cloud_ref: + name: strings.trimLeft + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/trim + - /influxdb/cloud/reference/flux/stdlib/strings/trimright + - /influxdb/cloud/reference/flux/stdlib/strings/trimprefix + - /influxdb/cloud/reference/flux/stdlib/strings/trimsuffix + - /influxdb/cloud/reference/flux/stdlib/strings/trimspace +--- + +The `strings.trimLeft()` function removes specified leading characters from a string. + +_**Output data type:** String_ + +```js +import "strings" + +strings.trimLeft(v: ".abc.", cutset: ".") + +// returns "abc." +``` + +## Parameters + +### v +String to remove characters from. + +_**Data type:** String_ + +### cutset +The leading characters to remove from the string. +Only characters that match the `cutset` string exactly are removed. + +_**Data type:** String_ + +## Examples + +###### Trim leading periods from all values in a column +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + variables: strings.trimLeft(v: r.variables, cutset: ".") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/trimprefix.md b/content/influxdb/cloud/reference/flux/stdlib/strings/trimprefix.md new file mode 100644 index 000000000..5e62cfe09 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/trimprefix.md @@ -0,0 +1,58 @@ +--- +title: strings.trimPrefix() function +description: > + The `strings.trimPrefix()` function removes a prefix from a string. + Strings that do not start with the prefix are returned unchanged. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/trimprefix/ +menu: + influxdb_cloud_ref: + name: strings.trimPrefix + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/trim + - /influxdb/cloud/reference/flux/stdlib/strings/trimleft + - /influxdb/cloud/reference/flux/stdlib/strings/trimright + - /influxdb/cloud/reference/flux/stdlib/strings/trimsuffix + - /influxdb/cloud/reference/flux/stdlib/strings/trimspace +--- + +The `strings.trimPrefix()` function removes a prefix from a string. +Strings that do not start with the prefix are returned unchanged. + +_**Output data type:** String_ + +```js +import "strings" + +strings.trimPrefix(v: "123_abc", prefix: "123") + +// returns "_abc" +``` + +## Parameters + +### v +The string value to trim. + +_**Data type:** String_ + +### prefix +The prefix to remove. + +_**Data type:** String_ + +## Examples + +###### Remove a prefix from all values in a column +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + sensorID: strings.trimPrefix(v: r.sensorId, prefix: "s12_") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/trimright.md b/content/influxdb/cloud/reference/flux/stdlib/strings/trimright.md new file mode 100644 index 000000000..b9ca1dd62 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/trimright.md @@ -0,0 +1,58 @@ +--- +title: strings.trimRight() function +description: > + The strings.trimRight() function removes trailing characters specified in the cutset from a string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/trimright/ +menu: + influxdb_cloud_ref: + name: strings.trimRight + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/trim + - /influxdb/cloud/reference/flux/stdlib/strings/trimleft + - /influxdb/cloud/reference/flux/stdlib/strings/trimprefix + - /influxdb/cloud/reference/flux/stdlib/strings/trimsuffix + - /influxdb/cloud/reference/flux/stdlib/strings/trimspace +--- + +The `strings.trimRight()` function removes trailing characters specified in the +[`cutset`](#cutset) from a string. + +_**Output data type:** String_ + +```js +import "strings" + +strings.trimRight(v: ".abc.", cutset: ".") + +// returns ".abc" +``` + +## Parameters + +### v +String to remove characters from. + +_**Data type:** String_ + +### cutset +The trailing characters to trim from the string. +Only characters that match the `cutset` string exactly are trimmed. + +_**Data type:** String_ + +## Examples + +###### Trim trailing periods from all values in a column +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + variables: strings.trimRight(v: r.variables, cutset: ".") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/trimspace.md b/content/influxdb/cloud/reference/flux/stdlib/strings/trimspace.md new file mode 100644 index 000000000..6a5926ae0 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/trimspace.md @@ -0,0 +1,46 @@ +--- +title: strings.trimSpace() function +description: The strings.trimSpace() function removes leading and trailing spaces from a string. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/trimspace/ +menu: + influxdb_cloud_ref: + name: strings.trimSpace + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/trim + - /influxdb/cloud/reference/flux/stdlib/strings/trimleft + - /influxdb/cloud/reference/flux/stdlib/strings/trimright + - /influxdb/cloud/reference/flux/stdlib/strings/trimprefix + - /influxdb/cloud/reference/flux/stdlib/strings/trimsuffix +--- + +The `strings.trimSpace()` function removes leading and trailing spaces from a string. + +_**Output data type:** String_ + +```js +import "strings" + +strings.trimSpace(v: " abc ") + +// returns "abc" +``` + +## Parameters + +### v +String to remove spaces from. + +_**Data type:** String_ + +## Examples + +###### Trim leading and trailing spaces from all values in a column +```js +import "strings" + +data + |> map(fn: (r) => ({ r with userInput: strings.trimSpace(v: r.userInput) })) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/strings/trimsuffix.md b/content/influxdb/cloud/reference/flux/stdlib/strings/trimsuffix.md new file mode 100644 index 000000000..6af104235 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/strings/trimsuffix.md @@ -0,0 +1,58 @@ +--- +title: strings.trimSuffix() function +description: > + The `strings.trimSuffix()` function removes a suffix from a string. + Strings that do not end with the suffix are returned unchanged. +aliases: + - /influxdb/cloud/reference/flux/functions/strings/trimsuffix/ +menu: + influxdb_cloud_ref: + name: strings.trimSuffix + parent: Strings +weight: 301 +related: + - /influxdb/cloud/reference/flux/stdlib/strings/trim + - /influxdb/cloud/reference/flux/stdlib/strings/trimleft + - /influxdb/cloud/reference/flux/stdlib/strings/trimright + - /influxdb/cloud/reference/flux/stdlib/strings/trimprefix + - /influxdb/cloud/reference/flux/stdlib/strings/trimspace +--- + +The `strings.trimSuffix()` function removes a suffix from a string. +Strings that do not end with the suffix are returned unchanged. + +_**Output data type:** String_ + +```js +import "strings" + +strings.trimSuffix(v: "123_abc", suffix: "abc") + +// returns "123_" +``` + +## Parameters + +### v +The string value to trim. + +_**Data type:** String_ + +### suffix +The suffix to remove. + +_**Data type:** String_ + +## Examples + +###### Remove a suffix from all values in a column +```js +import "strings" + +data + |> map(fn: (r) => ({ + r with + sensorID: strings.trimSuffix(v: r.sensorId, suffix: "_s12") + }) + ) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/system/_index.md b/content/influxdb/cloud/reference/flux/stdlib/system/_index.md new file mode 100644 index 000000000..ee08c624c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/system/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux system package +list_title: System package +description: > + The Flux system package provides functions for reading values from the system. + Import the `system` package. +aliases: + - /influxdb/cloud/reference/flux/functions/system/ +menu: + influxdb_cloud_ref: + name: System + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [system, functions, package] +--- + +The Flux system package provides functions for reading values from the system. +Import the `system` package: + +```js +import "system" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/system/time.md b/content/influxdb/cloud/reference/flux/stdlib/system/time.md new file mode 100644 index 000000000..3ff7698b2 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/system/time.md @@ -0,0 +1,46 @@ +--- +title: system.time() function +description: The `system.time()` function returns the current system time. +aliases: + - /influxdb/cloud/reference/flux/functions/misc/systemtime + - /influxdb/cloud/reference/flux/functions/built-in/misc/systemtime + - /influxdb/cloud/reference/flux/functions/system/time/ +menu: + influxdb_cloud_ref: + name: system.time + parent: System +weight: 401 +related: + - /influxdb/cloud/reference/flux/stdlib/built-in/misc/now/ +--- + +The `system.time()` function returns the current system time. + +_**Function type:** Date/Time_ +_**Output data type:** Timestamp_ + +```js +import "system" + +system.time() +``` + +## Examples +```js +import "system" + +data + |> set(key: "processed_at", value: string(v: system.time() )) +``` + +{{% note %}} +#### system.time() vs now() +`system.time()` returns the current system time of the host machine, which +typically accounts for the local time zone. +This time represents the time at which `system.time()` it is executed, so each +instance of `system.time()` in a Flux script returns a unique value. + +[`now()`](/influxdb/cloud/reference/flux/stdlib/built-in/misc/now/) returns the current UTC time. +`now()` is cached at runtime, so all instances of `now()` in a Flux script +return the same value. +{{% /note %}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/testing/_index.md b/content/influxdb/cloud/reference/flux/stdlib/testing/_index.md new file mode 100644 index 000000000..9f094be1d --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/testing/_index.md @@ -0,0 +1,24 @@ +--- +title: Flux testing package +list_title: Testing package +description: > + The Flux testing package provides functions that test piped-forward data in specific ways. + Import the `testing` package. +aliases: + - /influxdb/cloud/reference/flux/functions/testing/ +menu: + influxdb_cloud_ref: + name: Testing + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [testing, functions, package] +--- + +Flux testing functions test piped-forward data in specific ways and return errors if the tests fail. +Import the `testing` package: + +```js +import "testing" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/cloud/reference/flux/stdlib/testing/assertempty.md b/content/influxdb/cloud/reference/flux/stdlib/testing/assertempty.md new file mode 100644 index 000000000..cd1fd3ec4 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/testing/assertempty.md @@ -0,0 +1,43 @@ +--- +title: testing.assertEmpty() function +description: The testing.assertEmpty() function tests if an input stream is empty. +aliases: + - /influxdb/cloud/reference/flux/functions/testing/assertempty/ +menu: + influxdb_cloud_ref: + name: testing.assertEmpty + parent: Testing +weight: 301 +--- + +The `testing.assertEmpty()` function tests if an input stream is empty. +If not empty, the function returns an error. + +_**Function type:** Test_ + +```js +import "testing" + +testing.assertEmpty() +``` + +_The `testing.assertEmpty()` function can be used to perform in-line tests in a query._ + +## Examples + +#### Check if there is a difference between streams +This example uses the [`testing.diff()` function](/influxdb/cloud/reference/flux/stdlib/testing/diff) +which outputs the diff for the two streams. +The `.testing.assertEmpty()` function checks to see if the diff is empty. + +```js +import "testing" + +got = from(bucket: "example-bucket") + |> range(start: -15m) +want = from(bucket: "backup_example-bucket") + |> range(start: -15m) +got + |> testing.diff(want: want) + |> testing.assertEmpty() +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/testing/assertequals.md b/content/influxdb/cloud/reference/flux/stdlib/testing/assertequals.md new file mode 100644 index 000000000..0d69af7b3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/testing/assertequals.md @@ -0,0 +1,74 @@ +--- +title: testing.assertEquals() function +description: The testing.assertEquals() function tests whether two streams have identical data. +aliases: + - /influxdb/cloud/reference/flux/functions/tests/assertequals + - /influxdb/cloud/reference/flux/functions/testing/assertequals/ +menu: + influxdb_cloud_ref: + name: testing.assertEquals + parent: Testing +weight: 301 +--- + +The `testing.assertEquals()` function tests whether two streams have identical data. +If equal, the function outputs the tested data stream unchanged. +If unequal, the function returns an error. + +```js +import "testing" + +testing.assertEquals( + name: "streamEquality", + got: got, + want: want +) +``` + +_The `testing.assertEquals()` function can be used to perform in-line tests in a query._ + +## Parameters + +### name +Unique name given to the assertion. + +_**Data type:** String_ + +### got +The stream containing data to test. +Defaults to piped-forward data (`<-`). + +_**Data type:** Record_ + +### want +The stream that contains the expected data to test against. + +_**Data type:** Record_ + + +## Examples + +##### Assert of separate streams +```js +import "testing" + +want = from(bucket: "backup-example-bucket") + |> range(start: -5m) + +got = from(bucket: "example-bucket") + |> range(start: -5m) + +testing.assertEquals(got: got, want: want) +``` + +##### Inline assertion +```js +import "testing" + +want = from(bucket: "backup-example-bucket") + |> range(start: -5m) + +from(bucket: "example-bucket") + |> range(start: -5m) + |> testing.assertEquals(want: want) +``` diff --git a/content/influxdb/cloud/reference/flux/stdlib/testing/diff.md b/content/influxdb/cloud/reference/flux/stdlib/testing/diff.md new file mode 100644 index 000000000..a3c099bd4 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/testing/diff.md @@ -0,0 +1,78 @@ +--- +title: testing.diff() function +description: The testing.diff() function produces a diff between two streams. +aliases: + - /influxdb/cloud/reference/flux/functions/testing/diff/ +menu: + influxdb_cloud_ref: + name: testing.diff + parent: Testing +weight: 301 +--- + +The `testing.diff()` function produces a diff between two streams. + +_**Function type:** Test_ + +```js +import "testing" + +testing.diff( + got: stream2, + want: stream1, + epsilon: 0.000000001 +) +``` + +It matches tables from each stream with the same group keys. +For each matched table, it produces a diff. +Any added or removed rows are added to the table as a row. +An additional string column with the name `diff` is created and contains a `-` if the +row was present in the `got` table and not in the `want` table or `+` if the opposite is true. + +The diff function is guaranteed to emit at least one row if the tables are +different and no rows if the tables are the same. _The exact diff produced may change._ + +_The `testing.diff()` function can be used to perform in-line diffs in a query._ + +## Parameters + +### got +Stream containing data to test. +_Defaults to piped-forward data (`<-`)._ + +_**Data type:** Record_ + +### want +Stream that contains the expected data to test against. + +_**Data type:** Record_ + +### epsilon +Specifies how far apart two **float** values can be, but still considered equal. +Defaults to `0.000000001`. + +_**Data type:** Float_ + +## Examples + +##### Diff separate streams +```js +import "testing" + +want = from(bucket: "backup-example-bucket") + |> range(start: -5m) +got = from(bucket: "example-bucket") + |> range(start: -5m) +testing.diff(got: got, want: want) +``` + +##### Inline diff +```js +import "testing" + +want = from(bucket: "backup-example-bucket") |> range(start: -5m) +from(bucket: "example-bucket") + |> range(start: -5m) + |> testing.diff(want: want) +``` diff --git a/content/influxdb/cloud/reference/glossary.md b/content/influxdb/cloud/reference/glossary.md new file mode 100644 index 000000000..6fbc3619f --- /dev/null +++ b/content/influxdb/cloud/reference/glossary.md @@ -0,0 +1,12 @@ +--- +title: Glossary +description: > + Terms related to InfluxData products and platforms. +weight: 8 +menu: + influxdb_cloud_ref: + name: Glossary +influxdb/cloud/tags: [glossary] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/key-concepts/_index.md b/content/influxdb/cloud/reference/key-concepts/_index.md new file mode 100644 index 000000000..70ced71fe --- /dev/null +++ b/content/influxdb/cloud/reference/key-concepts/_index.md @@ -0,0 +1,14 @@ +--- +title: InfluxDB key concepts +description: > + Concepts related to InfluxDB. +weight: 2 +menu: + influxdb_cloud_ref: + name: Key concepts +influxdb/cloud/tags: [key concepts] +--- + +Before working with InfluxDB Cloud, it's helpful to learn a few key concepts. Browse the topics below to learn more. + +{{< children >}} diff --git a/content/influxdb/cloud/reference/key-concepts/data-elements.md b/content/influxdb/cloud/reference/key-concepts/data-elements.md new file mode 100644 index 000000000..7edbf9af8 --- /dev/null +++ b/content/influxdb/cloud/reference/key-concepts/data-elements.md @@ -0,0 +1,13 @@ +--- +title: InfluxDB data elements +description: > + InfluxDB structures data using elements such as timestamps, field keys, field values, tags, etc. +weight: 102 +menu: + influxdb_cloud_ref: + parent: Key concepts + name: Data elements +influxdb/cloud/tags: [key concepts, schema] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/key-concepts/data-schema.md b/content/influxdb/cloud/reference/key-concepts/data-schema.md new file mode 100644 index 000000000..9e19eef9d --- /dev/null +++ b/content/influxdb/cloud/reference/key-concepts/data-schema.md @@ -0,0 +1,15 @@ +--- +title: InfluxDB data schema +description: > + InfluxDB uses a tabular data schema for displaying raw data in Data Explorer and for returning query results in annotated CSV syntax. +aliases: + - /influxdb/cloud/reference/key-concepts/table-structure +weight: 103 +menu: + influxdb_cloud_ref: + parent: Key concepts + name: Data schema +influxdb/cloud/tags: [key concepts] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/key-concepts/design-principles.md b/content/influxdb/cloud/reference/key-concepts/design-principles.md new file mode 100644 index 000000000..f57a07ef4 --- /dev/null +++ b/content/influxdb/cloud/reference/key-concepts/design-principles.md @@ -0,0 +1,13 @@ +--- +title: InfluxDB design principles +description: > + Principles and tradeoffs related to InfluxDB design. +weight: 104 +menu: + influxdb_cloud_ref: + parent: Key concepts + name: Design principles +influxdb/cloud/tags: [key concepts, design principles] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/regions.md b/content/influxdb/cloud/reference/regions.md new file mode 100644 index 000000000..1178652ad --- /dev/null +++ b/content/influxdb/cloud/reference/regions.md @@ -0,0 +1,20 @@ +--- +title: InfluxDB Cloud regions +description: > + InfluxDB Cloud is available on multiple cloud provided and in multiple regions. + Each region has a unique InfluxDB Cloud URL and API endpoint. +aliases: + - /influxdb/cloud/reference/urls/ +weight: 6 +menu: + influxdb_cloud_ref: + name: InfluxDB Cloud regions +--- + +InfluxDB Cloud is available on multiple cloud provided and in multiple regions. +Each region has a unique InfluxDB Cloud URL and API endpoint. +Use the URLs below to interact with your InfluxDB Cloud instances with the +[InfluxDB API](/influxdb/cloud/reference/api/), [InfluxDB client libraries](/influxdb/cloud/tools/client-libraries/), +[`influx` CLI](/influxdb/cloud/reference/cli/influx/), or [Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/). + +{{< cloud_regions >}} diff --git a/content/influxdb/cloud/reference/release-notes/_index.md b/content/influxdb/cloud/reference/release-notes/_index.md new file mode 100644 index 000000000..6938f6443 --- /dev/null +++ b/content/influxdb/cloud/reference/release-notes/_index.md @@ -0,0 +1,12 @@ +--- +title: Release notes +description: Find important information about what's included in new versions of InfluxData products. +menu: + influxdb_cloud_ref: + name: Release notes +weight: 1 +--- + +Find important information about what's included in new versions of our products: + +{{< children >}} diff --git a/content/influxdb/v2.0/reference/release-notes/influxdb-cloud.md b/content/influxdb/cloud/reference/release-notes/cloud-updates.md similarity index 50% rename from content/influxdb/v2.0/reference/release-notes/influxdb-cloud.md rename to content/influxdb/cloud/reference/release-notes/cloud-updates.md index c498ef265..97fa4f2d4 100644 --- a/content/influxdb/v2.0/reference/release-notes/influxdb-cloud.md +++ b/content/influxdb/cloud/reference/release-notes/cloud-updates.md @@ -1,13 +1,14 @@ --- title: InfluxDB Cloud monthly updates -description: Important changes and what's new in each InfluxDB Cloud 2.0 update. +description: Important changes and what's new in each InfluxDB Cloud update. weight: 101 menu: - influxdb_2_0_ref: + influxdb_cloud_ref: parent: Release notes - name: InfluxDB Cloud + name: Monthly updates aliases: - /cloud/about/release-notes + - /influxdb/cloud/reference/release-notes/influxdb-cloud --- InfluxDB Cloud updates occur frequently. Find a compilation of monthly updates below. @@ -16,23 +17,23 @@ InfluxDB Cloud updates occur frequently. Find a compilation of monthly updates b ### Install and customize InfluxDB community templates in the Cloud UI -Install and customize any [InfluxDB community template](https://github.com/influxdata/community-templates#templates) directly in the Cloud user interface (UI). For more details, see how to [install and customize a template in the UI](/influxdb/v2.0/influxdb-templates/cloud/#install-and-customize-a-template-in-the-cloud-ui). +Install and customize any [InfluxDB community template](https://github.com/influxdata/community-templates#templates) directly in the Cloud user interface (UI). For more details, see how to [install and customize a template in the UI](/influxdb/cloud/influxdb-templates/cloud/). ## 2020-09-02 ### Pricing updates and Azure region -- Update [pricing vectors](/influxdb/v2.0/account-management/pricing-plans/#pricing-vect) to determine pricing by the total data out and query count. +- Update [pricing vectors](/influxdb/cloud/account-management/pricing-plans/#pricing-vectors) to determine pricing by the total data out and query count. -- Add [Microsoft Azure support](/influxdb/v2.0/reference/urls/#microsoft-azure) for the `eastus` and `westeurope` regions. Each region has a unique InfluxDB Cloud URL and API endpoint. +- Add [Microsoft Azure support](/influxdb/cloud/reference/regions/#microsoft-azure) for the `eastus` and `westeurope` regions. Each region has a unique InfluxDB Cloud URL and API endpoint. ### Flux updates - - Add time-weighted average [`timeWeightedAvg()` function](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/timeweightedavg/). - - Update [`integral()` function](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/integral/) with linear interpolation. - - Add [Flux query profiler](/influxdb/v2.0/reference/flux/stdlib/profiler/#use-the-query-profiler) to output query statistics that help you better understand query performance. - - Add [`tasks.lastSuccess()` function](/influxdb/v2.0/reference/flux/stdlib/influxdb-tasks/lastsuccess/) to retrieve the time of the last successful run of an InfluxDB task. - - Add the [`array.from` function](/influxdb/v2.0/reference/flux/stdlib/experimental/array/from/) to build ad hoc tables in a Flux script. + - Add time-weighted average [`timeWeightedAvg()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/timeweightedavg/). + - Update [`integral()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/integral/) with linear interpolation. + - Add [Flux query profiler](/influxdb/cloud/reference/flux/stdlib/profiler/#use-the-query-profiler) to output query statistics that help you better understand query performance. + - Add [`tasks.lastSuccess()` function](/influxdb/cloud/reference/flux/stdlib/influxdb-tasks/lastsuccess/) to retrieve the time of the last successful run of an InfluxDB task. + - Add the [`array.from` function](/influxdb/cloud/reference/flux/stdlib/experimental/array/from/) to build ad hoc tables in a Flux script. ### Bug fixes @@ -41,8 +42,8 @@ Install and customize any [InfluxDB community template](https://github.com/influ ## 2019-09-10 _Monitoring & Alerts_ ## Features -- **InfluxDB 2.0 alpha-17** – - _See the [alpha-17 release notes](/influxdb/v2.0/reference/release-notes/influxdb/#v2-0-0-alpha-17-2019-08-14) for details._ +- **InfluxDB OSS 2.0 alpha-17** – + _See the [alpha-17 release notes](/influxdb/v2%2E0/reference/release-notes/influxdb/#v200-alpha17-2019-08-14) for details._ - Alerts and Notifications to Slack (Free Plan), PagerDuty and HTTP (Usage-based Plan). - Rate limiting on cardinality for Free Plan. - Billing notifications. @@ -53,8 +54,8 @@ Install and customize any [InfluxDB community template](https://github.com/influ ### Features -- **InfluxDB 2.0 alpha-15** – - _See the [alpha-9 release notes](/influxdb/v2.0/reference/release-notes/influxdb/#v2-0-0-alpha-15-2019-07-11) for details._ +- **InfluxDB OSS 2.0 alpha-15** – + _See the [alpha-9 release notes](/influxdb/v2%2E0/reference/release-notes/influxdb/#v200-alpha15-2019-07-11) for details._ - Usage-based Plan. - Adjusted Free Plan rate limits. - Timezone selection in the user interface. @@ -70,7 +71,7 @@ Install and customize any [InfluxDB community template](https://github.com/influ ### Bug fixes -- Users cannot delete themselves from their Cloud 2.0 account. +- Users cannot delete themselves from their Cloud account. - The bucket retention period for Free Plan users is set to 72 hours. - Free Plan users cannot change a bucket's retention period. @@ -80,14 +81,14 @@ Install and customize any [InfluxDB community template](https://github.com/influ ### Features -- **InfluxDB 2.0 alpha-9** – - _See the [alpha-9 release notes](/influxdb/v2.0/reference/release-notes/influxdb/#v2-0-0-alpha-9-2019-05-01) for details._ +- **InfluxDB OSS 2.0 alpha-9** – + _See the [alpha-9 release notes](/influxdb/v2%2E0/reference/release-notes/influxdb/#v200-alpha9-2019-05-01) for details._ ### Bug fixes - Usage statistics on the Usage page show correct values. - Existing tasks with duration specified in nanoseconds no longer need to be resubmitted. -- Removed the additional user that showed up as an owner under the Cloud 2.0 organization. +- Removed the additional user that showed up as an owner under the Cloud organization. - Cloud users can use CLI tools to interact with their Cloud tenant. @@ -97,12 +98,12 @@ Install and customize any [InfluxDB community template](https://github.com/influ ### Features -- **InfluxDB 2.0 alpha-7** – - _See the [alpha-7 release notes](/influxdb/v2.0/reference/release-notes/influxdb/#v2-0-0-alpha-7-2019-03-28) for details._ +- **InfluxDB OSS 2.0 alpha-7** – + _See the [alpha-7 release notes](/influxdb/v2%2E0/reference/release-notes/influxdb/#v200-alpha7-2019-03-28) for details._ ### Bug fixes -- Logout works in InfluxDB Cloud 2.0 UI. +- Logout works in InfluxDB Cloud UI. - Single sign-on works between https://cloud2.influxdata.com and https://us-west-2-1.aws.cloud2.influxdata.com. - Able to copy error message from UI. - Able to change a task from every to cron. diff --git a/content/influxdb/cloud/reference/release-notes/flux.md b/content/influxdb/cloud/reference/release-notes/flux.md new file mode 100644 index 000000000..904c5eed5 --- /dev/null +++ b/content/influxdb/cloud/reference/release-notes/flux.md @@ -0,0 +1,11 @@ +--- +title: Flux release notes +description: Important changes and and what's new in each version of Flux. +weight: 102 +menu: + influxdb_cloud_ref: + parent: Release notes + name: Flux +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/sample-data.md b/content/influxdb/cloud/reference/sample-data.md new file mode 100644 index 000000000..65f4f2865 --- /dev/null +++ b/content/influxdb/cloud/reference/sample-data.md @@ -0,0 +1,54 @@ +--- +title: Sample data +description: > + Use sample data to familiarize yourself with time series data and InfluxDB. + InfluxData provides many sample time series datasets to use with InfluxDB + and InfluxDB Cloud. +aliases: + - /influxdb/cloud/write-data/sample-data/ +menu: influxdb_cloud_ref +weight: 7 +--- + +Use sample data to familiarize yourself with time series data and InfluxDB. +InfluxData provides many sample time series datasets to use with **InfluxDB Cloud**. + +## InfluxDB Cloud demo data +Use [InfluxDB Cloud demo data buckets](/influxdb/cloud/reference/sample-data/#influxdb-cloud-demo-data) for quick, +free access to different types of sample data. + +{{< youtube GSaByPC1Bdc >}} + +{{% note %}} +Demo data is not available for use with third-party integrations such as Grafana. +{{% /note %}} + +## Sample data sets +The following sample data sets are used as examples in [InfluxDB query guides](/influxdb/cloud/query-data/flux). + +- [Air sensor sample data](#air-sensor-sample-data) +- [Bird migration sample data](#bird-migration-sample-data) + +### Air sensor sample data +Air sensor sample data represents an "Internet of Things" (IoT) use case by simulating +temperature, humidity, and carbon monoxide levels for multiple rooms in a building. +The dataset also includes a relational SQL dataset with meta information about sensors in each room. + + + View air sensor sample data + + +_Used in [Query SQL data sources](/influxdb/cloud/query-data/flux/sql/)._ + +### Bird migration sample data +Bird migration data is adapted from the +[Movebank: Animal Tracking data set on Kaggle](https://www.kaggle.com/pulkit8595/movebank-animal-tracking) +and represents animal migratory movements throughout 2019. +Use the [Flux Geo package](/influxdb/cloud/reference/flux/stdlib/experimental/geo/#geo-schema-requirements) +to query and analyze the geo-temporal data in this sample data set. + + + View bird migration sample data + + +_Used in [Work with geo-temporal data](/influxdb/cloud/query-data/flux/geo/)._ diff --git a/content/influxdb/cloud/reference/syntax/_index.md b/content/influxdb/cloud/reference/syntax/_index.md new file mode 100644 index 000000000..cdc88f416 --- /dev/null +++ b/content/influxdb/cloud/reference/syntax/_index.md @@ -0,0 +1,13 @@ +--- +title: InfluxDB syntaxes +description: > + InfluxDB uses a handful of languages and syntaxes to perform tasks such as + writing, querying, processing, and deleting data. +weight: 5 +menu: + influxdb_cloud_ref: + name: Syntax +influxdb/cloud/tags: [syntax] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/syntax/annotated-csv/_index.md b/content/influxdb/cloud/reference/syntax/annotated-csv/_index.md new file mode 100644 index 000000000..9a318b997 --- /dev/null +++ b/content/influxdb/cloud/reference/syntax/annotated-csv/_index.md @@ -0,0 +1,17 @@ +--- +title: Annotated CSV +description: > + InfluxDB and Flux return query results in annotated CSV format. + You can also read annotated CSV directly from Flux with the `csv.from()` function + or write data to InfluxDB using annotated CSV and the `influx write` command. +weight: 103 +menu: + influxdb_cloud_ref: + parent: Syntax +influxdb/cloud/tags: [csv, syntax] +related: + - /influxdb/cloud/reference/flux/stdlib/csv/from/ + - /influxdb/cloud/reference/syntax/annotated-csv/extended/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/syntax/annotated-csv/extended.md b/content/influxdb/cloud/reference/syntax/annotated-csv/extended.md new file mode 100644 index 000000000..1d984bdbb --- /dev/null +++ b/content/influxdb/cloud/reference/syntax/annotated-csv/extended.md @@ -0,0 +1,20 @@ +--- +title: Extended annotated CSV +description: > + Extended annotated CSV provides additional annotations and options that specify + how CSV data should be converted to [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) + and written to InfluxDB. +menu: + influxdb_cloud_ref: + name: Extended annotated CSV + parent: Annotated CSV +weight: 201 +influxdb/cloud/tags: [csv, syntax, write] +related: + - /influxdb/cloud/write-data/csv/ + - /influxdb/cloud/reference/cli/influx/write/ + - /influxdb/cloud/reference/syntax/line-protocol/ + - /influxdb/cloud/reference/syntax/annotated-csv/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/syntax/delete-predicate.md b/content/influxdb/cloud/reference/syntax/delete-predicate.md new file mode 100644 index 000000000..93852b3ce --- /dev/null +++ b/content/influxdb/cloud/reference/syntax/delete-predicate.md @@ -0,0 +1,17 @@ +--- +title: Delete predicate syntax +list_title: Delete predicate +description: > + The InfluxDB `/delete` endpoint uses an InfluxQL-like predicate syntax to determine + what data points to delete. +menu: + influxdb_cloud_ref: + parent: Syntax + name: Delete predicate +weight: 104 +influxdb/cloud/tags: [syntax, delete] +related: + - /influxdb/cloud/reference/cli/influx/delete/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/syntax/flux.md b/content/influxdb/cloud/reference/syntax/flux.md new file mode 100644 index 000000000..ee9244db0 --- /dev/null +++ b/content/influxdb/cloud/reference/syntax/flux.md @@ -0,0 +1,15 @@ +--- +title: Flux syntax +list_title: Flux +description: > + Flux is a functional data scripting language designed for querying, analyzing, and acting on data. +menu: + influxdb_cloud_ref: + parent: Syntax + name: Flux + identifier: flux-syntax +weight: 101 +influxdb/cloud/tags: [syntax, flux] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/reference/syntax/line-protocol.md b/content/influxdb/cloud/reference/syntax/line-protocol.md new file mode 100644 index 000000000..90102bdfb --- /dev/null +++ b/content/influxdb/cloud/reference/syntax/line-protocol.md @@ -0,0 +1,15 @@ +--- +title: Line protocol +description: > + InfluxDB uses line protocol to write data points. + It is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point. +menu: + influxdb_cloud_ref: + parent: Syntax +weight: 102 +influxdb/cloud/tags: [write, line protocol, syntax] +related: + - /influxdb/cloud/write-data/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/security/_index.md b/content/influxdb/cloud/security/_index.md new file mode 100644 index 000000000..8d771d480 --- /dev/null +++ b/content/influxdb/cloud/security/_index.md @@ -0,0 +1,18 @@ +--- +title: Manage security and authorization +description: > + Security, access control, and sensitive secret handling are incredibly important + when handling any sort of sensitive data. + This section provides information about managing the security of your InfluxDB instance. +weight: 12 +menu: + influxdb_cloud: + name: Security & authorization +influxdb/cloud/tags: [security, authentication] +--- + +Security, access control, and sensitive secret handling are incredibly important +when handling any sort of sensitive data. +This section provides information about managing the security of your InfluxDB instance. + +{{< children >}} diff --git a/content/influxdb/cloud/security/secrets/_index.md b/content/influxdb/cloud/security/secrets/_index.md new file mode 100644 index 000000000..16957b08b --- /dev/null +++ b/content/influxdb/cloud/security/secrets/_index.md @@ -0,0 +1,41 @@ +--- +title: Store and use secrets +description: Use BoltDB or Vault to store secrets for InfluxDB. +influxdb/cloud/tags: [secrets, security] +menu: + influxdb_cloud: + parent: Security & authorization +weight: 102 +--- + +There are two options for storing secrets with InfluxDB: + +- By default, secrets are Base64-encoded and stored in the InfluxDB embedded key value store, [BoltDB](https://github.com/boltdb/bolt). +- You can also set up Vault to store secrets. For details, see [Store secrets in Vault](/influxdb/cloud/security/secrets/use-vault). + +{{% cloud %}} +By default, all secrets added to InfluxDB Cloud are stored in the InfluxDB Cloud Vault cluster. +{{% /cloud %}} + +## Use secrets in a query + +Import the `influxdata/influxd/secrets` package and use the `secrets.get()` function +to populate sensitive data in queries with secrets from your secret store. + +```js +import "influxdata/influxdb/secrets" +import "sql" + +username = secrets.get(key: "POSTGRES_USERNAME") +password = secrets.get(key: "POSTGRES_PASSWORD") + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost", + query:"SELECT * FROM example-table" +) +``` + +## Add, list, and delete secrets + +See [Manage secrets](/influxdb/cloud/security/secrets/manage-secrets). diff --git a/content/influxdb/cloud/security/secrets/manage-secrets/_index.md b/content/influxdb/cloud/security/secrets/manage-secrets/_index.md new file mode 100644 index 000000000..2f455415e --- /dev/null +++ b/content/influxdb/cloud/security/secrets/manage-secrets/_index.md @@ -0,0 +1,34 @@ +--- +title: Manage secrets +description: Manage secrets in InfluxDB with the InfluxDB API. +influxdb/cloud/tags: [secrets, security] +menu: + influxdb_cloud: + parent: Store and use secrets +weight: 201 +--- + +Manage secrets using the [`influx` command line interface (CLI)](/influxdb/cloud/reference/cli/influx/) or the InfluxDB API. +All secrets belong to an organization and are stored in your [secret-store](/influxdb/cloud/security/secrets/). + +{{< children >}} + +--- + +## Use secrets in a query +Import the `influxdata/influxd/secrets` package and use the `secrets.get()` function +to populate sensitive data in queries with secrets from your secret store. + +```js +import "influxdata/influxdb/secrets" +import "sql" + +username = secrets.get(key: "POSTGRES_USERNAME") +password = secrets.get(key: "POSTGRES_PASSWORD") + +sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost", + query:"SELECT * FROM example-table" +) +``` diff --git a/content/influxdb/cloud/security/secrets/manage-secrets/add.md b/content/influxdb/cloud/security/secrets/manage-secrets/add.md new file mode 100644 index 000000000..852ba1184 --- /dev/null +++ b/content/influxdb/cloud/security/secrets/manage-secrets/add.md @@ -0,0 +1,52 @@ +--- +title: Add secrets +description: Add secrets using the `influx` CLI or the InfluxDB API. +influxdb/cloud/tags: [secrets, security] +menu: + influxdb_cloud: + parent: Manage secrets +weight: 301 +--- + +Add secrets using the `influx` command line interface (CLI) or the InfluxDB API. + +## Add a secret using the influx CLI +Use the [`influx secret update` command](/influxdb/cloud/reference/cli/influx/secret/update/) +to add a new secret to your organization. +Provide the secret key with the `-k` or `--key` flag. +You may also provide the secret value with the `-v` or `--value` flag. +If you do not provide the secret value with the `-v` or `--value` flag, +enter the value when prompted. + +{{% warn %}} +Providing a secret value with the `-v` or `--value` flag may expose the secret +in your command history. +{{% /warn %}} + +```sh +# Syntax +influx secret update -k + +# Example +influx secret update -k foo +``` + +## Add a secret using the InfluxDB API +Use the `PATCH` request method and the `/orgs/{orgID}/secrets` API endpoint to +add a new secret to your organization. + +**Include the following:** + +- Your [organization ID](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id) in the request URL +- Your [authentication token](/influxdb/cloud/security/tokens/view-tokens/) in the `Authorization` header +- The secret key-value pair in the request body + + +```sh +curl -XPATCH https://cloud2.influxdata.com/api/v2/orgs//secrets \ + -H 'Authorization: Token YOURAUTHTOKEN' \ + -H 'Content-type: application/json' \ + --data '{ + "": "" +}' +``` diff --git a/content/influxdb/cloud/security/secrets/manage-secrets/delete.md b/content/influxdb/cloud/security/secrets/manage-secrets/delete.md new file mode 100644 index 000000000..b935deeb1 --- /dev/null +++ b/content/influxdb/cloud/security/secrets/manage-secrets/delete.md @@ -0,0 +1,45 @@ +--- +title: Delete secrets +description: Delete secrets using the `influx` CLI or the InfluxDB API. +influxdb/cloud/tags: [secrets, security] +menu: + influxdb_cloud: + parent: Manage secrets +weight: 304 +--- + +Delete secrets using the `influx` command line interface (CLI) or the InfluxDB API. + +## Delete a secret using the influx CLI +Use the [`influx secret delete` command](/influxdb/cloud/reference/cli/influx/secret/delete/) +to delete a secret key-value pair from your organization. +Provide the secret key to delete with the `-k` or `--key` flag. + +```sh +# Syntax +influx secret delete -k + +# Example +influx secret delete -k foo +``` + +## Delete secrets using the InfluxDB API +Use the `POST` request method and the `orgs/{orgID}/secrets/delete` API endpoint +to delete one or more secrets. + +**Include the following:** + +- Your [organization ID](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id) in the request URL +- Your [authentication token](/influxdb/cloud/security/tokens/view-tokens/) in the `Authorization` header +- An array of secret keys to delete in the request body + + +```bash +curl -XGET https://cloud2.influxdata.com/api/v2/orgs//secrets/delete \ + --H 'Authorization: Token YOURAUTHTOKEN' + --data '{ + "secrets": [ + "" + ] +}' +``` diff --git a/content/influxdb/cloud/security/secrets/manage-secrets/update.md b/content/influxdb/cloud/security/secrets/manage-secrets/update.md new file mode 100644 index 000000000..2ab620678 --- /dev/null +++ b/content/influxdb/cloud/security/secrets/manage-secrets/update.md @@ -0,0 +1,52 @@ +--- +title: Update secrets +description: Update secrets using the `influx` CLI or the InfluxDB API. +influxdb/cloud/tags: [secrets, security] +menu: + influxdb_cloud: + parent: Manage secrets +weight: 303 +--- + +Update secrets using the `influx` command line interface (CLI) or the InfluxDB API. + +## Update a secret using the influx CLI +Use the [`influx secret update` command](/influxdb/cloud/reference/cli/influx/secret/update/) +to update a secret in your organization. +Provide the secret key to update with the `-k` or `--key` flag. +You may also provide the secret value with the `-v` or `--value` flag. +If you do not provide the secret value with the `-v` or `--value` flag, +enter the value when prompted. + +{{% warn %}} +Providing a secret value with the `-v` or `--value` flag may expose the secret +in your command history. +{{% /warn %}} + +```sh +# Syntax +influx secret update -k + +# Example +influx secret update -k foo +``` + +## Update a secret using the InfluxDB API +Use the `PATCH` request method and the InfluxDB `/orgs/{orgID}/secrets` API endpoint +to update a secret in your organization. + +**Include the following:** + +- Your [organization ID](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id) in the request URL +- Your [authentication token](/influxdb/cloud/security/tokens/view-tokens/) in the `Authorization` header +- The updated secret key-value pair in the request body + + +```sh +curl -XPATCH https://cloud2.influxdata.com/api/v2/orgs//secrets \ + -H 'Authorization: Token YOURAUTHTOKEN' \ + -H 'Content-type: application/json' \ + --data '{ + "": "" +}' +``` diff --git a/content/influxdb/cloud/security/secrets/manage-secrets/view.md b/content/influxdb/cloud/security/secrets/manage-secrets/view.md new file mode 100644 index 000000000..5b7d7b2d6 --- /dev/null +++ b/content/influxdb/cloud/security/secrets/manage-secrets/view.md @@ -0,0 +1,34 @@ +--- +title: View secret keys +description: View secret keys using the `influx` CLI or the InfluxDB API. +influxdb/cloud/tags: [secrets, security] +menu: + influxdb_cloud: + parent: Manage secrets +weight: 302 +--- + +View secret keys using the `influx` command line interface (CLI) or the InfluxDB API. + +## View secret keys using the influx CLI +Use the [`influx secret list` command](/influxdb/cloud/reference/cli/influx/secret/list/) +to list your organization's secret keys. + +```sh +influx secret list +``` + +## View secret keys using the InfluxDB API +Use the `GET` request method and the InfluxDB `/orgs/{orgID}/secrets` API endpoint +to view your organization's secrets keys. + +**Include the following:** + +- Your [organization ID](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id) in the request URL +- Your [authentication token](/influxdb/cloud/security/tokens/view-tokens/) in the `Authorization` header + + +```sh +curl -XGET https://cloud2.influxdata.com/api/v2/orgs//secrets \ + -H 'Authorization: Token YOURAUTHTOKEN' +``` diff --git a/content/influxdb/cloud/security/secrets/use-vault.md b/content/influxdb/cloud/security/secrets/use-vault.md new file mode 100644 index 000000000..37a70d69d --- /dev/null +++ b/content/influxdb/cloud/security/secrets/use-vault.md @@ -0,0 +1,16 @@ +--- +title: Store secrets in Vault +description: Use Vault as an InfluxDB secret store and manage secrets through the in InfluxDB API. +influxdb/cloud/tags: [secrets, security] +menu: + influxdb_cloud: + parent: Store and use secrets +weight: 201 +--- + +[Vault](https://www.vaultproject.io/) secures, stores, and controls access +to tokens, passwords, certificates, and other sensitive secrets. +By default, all secrets added to **InfluxDB Cloud** are stored in the +**InfluxDB Cloud Vault cluster**. + +For more information about secrets, see [Manage secrets](/influxdb/cloud/security/secrets/manage-secrets/). diff --git a/content/influxdb/cloud/security/tokens/_index.md b/content/influxdb/cloud/security/tokens/_index.md new file mode 100644 index 000000000..53e3e4f93 --- /dev/null +++ b/content/influxdb/cloud/security/tokens/_index.md @@ -0,0 +1,20 @@ +--- +title: Manage authentication tokens +seotitle: Manage authentication tokens in InfluxDB +description: Manage authentication tokens in InfluxDB using the InfluxDB UI or the influx CLI. +aliases: + - /influxdb/cloud/users/tokens +influxdb/cloud/tags: [tokens, authentication, security] +menu: + influxdb_cloud: + name: Manage tokens + parent: Security & authorization +weight: 103 +--- + +InfluxDB ensures secure interaction between users and data through the use of **authentication tokens**. +A token belongs to an organization and identifies InfluxDB permissions within the organization. + +Learn how to create, view, update, or delete an authentication token. + +{{< children >}} diff --git a/content/influxdb/cloud/security/tokens/create-token.md b/content/influxdb/cloud/security/tokens/create-token.md new file mode 100644 index 000000000..de15f9497 --- /dev/null +++ b/content/influxdb/cloud/security/tokens/create-token.md @@ -0,0 +1,54 @@ +--- +title: Create a token +seotitle: Create an authentication token in InfluxDB +description: Create an authentication token in InfluxDB using the InfluxDB UI or the `influx` CLI. +aliases: + - /influxdb/cloud/users/tokens/create-token/ +menu: + influxdb_cloud: + name: Create a token + parent: Manage tokens +weight: 201 +--- + +Create authentication tokens using the InfluxDB user interface (UI) or the `influx` +command line interface (CLI). + +Tokens are visible only to the user who created them and stop working when the user is deactivated. We recommend creating a generic IT user to create and manage tokens for writing data. + +## Create a token in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Click **{{< icon "plus" >}} Generate** and select a token type + (**Read/Write Token** or **All Access Token**). +3. In the window that appears, enter a description for your token in the **Description** field. +4. If generating a **read/write token**: + - Search for and select buckets to read from in the **Read** pane. + - Search for and select buckets to write to in the **Write** pane. +5. Click **Save**. + +## Create a token using the influx CLI + +Use the [`influx auth create` command](/influxdb/cloud/reference/cli/influx/auth/create) to create a token. +Include flags with the command to grant specific permissions to the token. +See the [available flags](/influxdb/cloud/reference/cli/influx/auth/create#flags). + +```sh +# Syntax +influx auth create -o [permission-flags] + +# Example +influx auth create -o my-org \ + --read-buckets 03a2bbf46309a000 03ace3a87c269000 \ + --read-dashboards \ + --read-tasks \ + --read-telegrafs \ + --read-user +``` + +Filtering options such as filtering by authorization ID, username, or user ID are available. +See the [`influx auth list` documentation](/influxdb/cloud/reference/cli/influx/auth/list) +for information about other available flags. diff --git a/content/influxdb/cloud/security/tokens/delete-token.md b/content/influxdb/cloud/security/tokens/delete-token.md new file mode 100644 index 000000000..6e76cfadf --- /dev/null +++ b/content/influxdb/cloud/security/tokens/delete-token.md @@ -0,0 +1,39 @@ +--- +title: Delete a token +seotitle: Delete an authentication token from InfluxDB +description: Delete an authentication token from InfluxDB using the InfluxDB UI or the `influx` CLI. +aliases: + - /influxdb/cloud/users/tokens/delete-token +menu: + influxdb_cloud: + name: Delete a token + parent: Manage tokens +weight: 204 +--- + +Delete authentication tokens from the InfluxDB user interface (UI) or the `influx` command line interface (CLI). +Once deleted, all users and external integrations using the token will no longer +have access to your InfluxDB instance. + +## Delete tokens in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Hover over the token you want to delete and click **Delete** and **Confirm**. + +## Delete tokens using the influx CLI + +Use the [`influx auth delete` command](/influxdb/cloud/reference/cli/influx/auth/delete) +to delete a token. + +_This command requires an auth ID, which is available in the output of `influx auth find`._ + +```sh +# Syntax +influx auth delete -i + +# Example +influx auth delete -i 03a2bee5a9c9a000 +``` diff --git a/content/influxdb/cloud/security/tokens/update-tokens.md b/content/influxdb/cloud/security/tokens/update-tokens.md new file mode 100644 index 000000000..cd6189ad1 --- /dev/null +++ b/content/influxdb/cloud/security/tokens/update-tokens.md @@ -0,0 +1,31 @@ +--- +title: Update a token +seotitle: Update authentication tokens in InfluxDB +description: Update authentication tokens' descriptions in InfluxDB using the InfluxDB UI. +aliases: + - /influxdb/cloud/users/tokens/update-tokens +menu: + influxdb_cloud: + name: Update a token + parent: Manage tokens +weight: 203 +--- + +Update an authentication token's description using the InfluxDB user interface (UI). + +## Update a token in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Click the pencil icon {{< icon "pencil" >}} next to the token's name in the **Description** column. +3. Update the token description, then click anywhere else to save. + +## Enable or disable a token + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Click the **{{< icon "toggle-green" >}} Status** toggle. diff --git a/content/influxdb/cloud/security/tokens/view-tokens.md b/content/influxdb/cloud/security/tokens/view-tokens.md new file mode 100644 index 000000000..92f073f84 --- /dev/null +++ b/content/influxdb/cloud/security/tokens/view-tokens.md @@ -0,0 +1,40 @@ +--- +title: View tokens +seotitle: View authentication tokens in InfluxDB +description: View authentication tokens in InfluxDB using the InfluxDB UI or the `influx` CLI. +aliases: + - /influxdb/cloud/users/tokens/view-tokens +menu: + influxdb_cloud: + name: View tokens + parent: Manage tokens +weight: 202 +--- + +View authentication tokens using the InfluxDB user interface (UI) or the `influx` +command line interface (CLI). + +{{% note %}} +Tokens are visible only to the user who created them and stop working when the user is deactivated. We recommend creating a generic IT user to create and manage tokens for writing data. +{{% /note %}} + +## View tokens in the InfluxDB UI + +1. In the navigation menu on the left, select **Data (Load Data)** > **Tokens**. + + {{< nav-icon "disks" >}} + +2. Click a token name from the list to view the token and a summary of access permissions. + +## View tokens using the influx CLI + +Use the [`influx auth list` command](/influxdb/cloud/reference/cli/influx/auth/list) +to view tokens. + +```sh +influx auth list +``` + +Filtering options such as filtering by authorization ID, username, or user ID are available. +See the [`influx auth list` documentation](/influxdb/cloud/reference/cli/influx/auth/list) +for information about other available flags. diff --git a/content/influxdb/cloud/tags/_index.md b/content/influxdb/cloud/tags/_index.md new file mode 100644 index 000000000..3a3d5c828 --- /dev/null +++ b/content/influxdb/cloud/tags/_index.md @@ -0,0 +1,4 @@ +--- +title: Tags and related content +layout: tags-landing +--- diff --git a/content/influxdb/cloud/telegraf-configs/_index.md b/content/influxdb/cloud/telegraf-configs/_index.md new file mode 100644 index 000000000..0aa2ae0d6 --- /dev/null +++ b/content/influxdb/cloud/telegraf-configs/_index.md @@ -0,0 +1,13 @@ +--- +title: Telegraf configurations +description: > + placeholder +weight: 12 +menu: influxdb_cloud +influxdb/cloud/tags: [telegraf] +related: + - /influxdb/cloud/write-data/no-code/use-telegraf/manual-config/ + - /influxdb/cloud/write-data/no-code/use-telegraf/auto-config/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/telegraf-configs/create.md b/content/influxdb/cloud/telegraf-configs/create.md new file mode 100644 index 000000000..fc376becf --- /dev/null +++ b/content/influxdb/cloud/telegraf-configs/create.md @@ -0,0 +1,17 @@ +--- +title: Create a Telegraf configuration +description: > + Use the InfluxDB UI or the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) + to create an Telegraf configuration. +weight: 101 +menu: + influxdb_cloud: + name: Create a config + parent: Telegraf configurations +related: + - /influxdb/cloud/write-data/no-code/use-telegraf/manual-config/ + - /influxdb/cloud/write-data/no-code/use-telegraf/auto-config/ + - /influxdb/cloud/telegraf-configs/update/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/telegraf-configs/remove.md b/content/influxdb/cloud/telegraf-configs/remove.md new file mode 100644 index 000000000..b3c46fb71 --- /dev/null +++ b/content/influxdb/cloud/telegraf-configs/remove.md @@ -0,0 +1,16 @@ +--- +title: Remove a Telegraf configuration +description: > + Use the InfluxDB UI or the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) + to remove Telegraf configurations from InfluxDB. +weight: 104 +menu: + influxdb_cloud: + name: Remove a config + parent: Telegraf configurations +aliases: + - /influxdb/cloud/write-data/no-code/use-telegraf/auto-config/delete-telegraf-config/ + - /influxdb/cloud/collect-data/use-telegraf/auto-config/delete-telegraf-config +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/telegraf-configs/update.md b/content/influxdb/cloud/telegraf-configs/update.md new file mode 100644 index 000000000..4c39e5c0e --- /dev/null +++ b/content/influxdb/cloud/telegraf-configs/update.md @@ -0,0 +1,13 @@ +--- +title: Update a Telegraf configuration +description: > + Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) + to update InfluxDB Telegraf configurations. +weight: 103 +menu: + influxdb_cloud: + name: Update a config + parent: Telegraf configurations +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/telegraf-configs/view.md b/content/influxdb/cloud/telegraf-configs/view.md new file mode 100644 index 000000000..209e44c77 --- /dev/null +++ b/content/influxdb/cloud/telegraf-configs/view.md @@ -0,0 +1,13 @@ +--- +title: View Telegraf configurations +description: > + Use the InfluxDB user interface (UI) or the [`influx` CLI](/influxdb/cloud/reference/cli/influx/) + to view and download InfluxDB Telegraf configurations. +weight: 102 +menu: + influxdb_cloud: + name: View configs + parent: Telegraf configurations +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/tools/_index.md b/content/influxdb/cloud/tools/_index.md new file mode 100644 index 000000000..ee4fee42f --- /dev/null +++ b/content/influxdb/cloud/tools/_index.md @@ -0,0 +1,11 @@ +--- +title: InfluxDB tools and integrations +description: > + Use InfluxDB tools and other third-party integrations to interact with, manage, and visualize data in InfluxDB. +weight: 13 +menu: + influxdb_cloud: + name: Tools & integrations +--- + +{{< children >}} diff --git a/content/influxdb/cloud/tools/client-libraries/_index.md b/content/influxdb/cloud/tools/client-libraries/_index.md new file mode 100644 index 000000000..7e471d12b --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/_index.md @@ -0,0 +1,25 @@ +--- +title: Use InfluxDB client libraries +description: > + InfluxDB client libraries are language-specific tools that integrate with the InfluxDB v2 API. + View the list of available client libraries. +weight: 101 +aliases: + - /influxdb/cloud/reference/client-libraries/ + - /influxdb/cloud/reference/api/client-libraries/ +menu: + influxdb_cloud: + name: Use client libraries + parent: Tools & integrations +influxdb/cloud/tags: [client libraries] +--- + +InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. +The following **InfluxDB v2** client libraries are available: + +{{% note %}} +These client libraries are in active development and may not be feature-complete. +This list will continue to grow as more client libraries are released. +{{% /note %}} + +{{< children type="list" >}} diff --git a/content/influxdb/cloud/tools/client-libraries/arduino.md b/content/influxdb/cloud/tools/client-libraries/arduino.md new file mode 100644 index 000000000..cff58349d --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/arduino.md @@ -0,0 +1,13 @@ +--- +title: InfluxDB Arduino client library +list_title: Arduino +description: Use the Arduino client library to interact with InfluxDB. +external_url: https://github.com/tobiasschuerg/InfluxDB-Client-for-Arduino +list_note: _– contributed by [tobiasschuerg](https://github.com/tobiasschuerg)_ +menu: + influxdb_cloud: + name: Arduino + parent: Use client libraries + url: https://github.com/tobiasschuerg/InfluxDB-Client-for-Arduino +weight: 201 +--- diff --git a/content/influxdb/cloud/tools/client-libraries/csharp.md b/content/influxdb/cloud/tools/client-libraries/csharp.md new file mode 100644 index 000000000..315118ec8 --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/csharp.md @@ -0,0 +1,12 @@ +--- +title: InfluxDB C# client library +list_title: C# +description: Use the C# client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-csharp +menu: + influxdb_cloud: + name: C# + parent: Use client libraries + url: https://github.com/influxdata/influxdb-client-csharp +weight: 201 +--- diff --git a/content/influxdb/cloud/tools/client-libraries/go.md b/content/influxdb/cloud/tools/client-libraries/go.md new file mode 100644 index 000000000..a3bee512c --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/go.md @@ -0,0 +1,206 @@ +--- +title: Go client library +seotitle: InfluxDB Go client library +list_title: Go +description: > + Use the Go client library to interact with InfluxDB. +menu: + influxdb_cloud: + name: Go + parent: Use client libraries +influxdb/cloud/tags: [client libraries, Go] +weight: 201 +aliases: + - /influxdb/cloud/reference/api/client-libraries/go/ +--- + +Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to integrate InfluxDB into Go scripts and applications. + +This guide presumes some familiarity with Go and InfluxDB. +If just getting started, see [Get started with InfluxDB](/influxdb/cloud/get-started/). + +## Before you begin + +1. [Install Go 1.3 or later](https://golang.org/doc/install). +2. Download the client package in your $GOPATH and build the package. + + ```sh + # Download the InfluxDB Go client package + go get github.com/influxdata/influxdb-client-go + + # Build the package + go build + ``` +3. Ensure that InfluxDB is running and you can connect to it. + For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/cloud/reference/urls/). + +## Boilerplate for the InfluxDB Go Client Library + +Use the Go library to write and query data from InfluxDB. + +1. In your Go program, import the necessary packages and specify the entry point of your executable program. + + ```go + package main + + import ( + "context" + "fmt" + "time" + + influxdb2 "github.com/influxdata/influxdb-client-go" + ) + ``` + +2. Define variables for your InfluxDB [bucket](/influxdb/cloud/organizations/buckets/), [organization](/influxdb/cloud/organizations/), and [token](/influxdb/cloud/security/tokens/). + + ```go + bucket := "example-bucket" + org := "example-org" + token := "example-token" + // Store the URL of your InfluxDB instance + url := "https://cloud2.influxdata.com" + ``` + +3. Create the the InfluxDB Go client and pass in the `url` and `token` parameters. + + ```go + client := influxdb2.NewClient(url, token) + ``` + +4. Create a **write client** with the `WriteApiBlocking` method and pass in the `org` and `bucket` parameters. + + ```go + writeApi := client.WriteApiBlocking(org, bucket) + ``` + +5. To query data, create an InfluxDB **query client** and pass in your InfluxDB `org`. + + ```go + queryApi := client.QueryApi(org) + ``` + +## Write data to InfluxDB with Go + +Use the Go library to write data to InfluxDB. + +1. Create a [point](/influxdb/cloud/reference/glossary/#point) and write it to InfluxDB using the `WritePoint` method of the API writer struct. + +2. Close the client to flush all pending writes and finish. + + ```go + p := influxdb2.NewPoint("stat", + map[string]string{"unit": "temperature"}, + map[string]interface{}{"avg": 24.5, "max": 45}, + time.Now()) + writeApi.WritePoint(context.Background(), p) + client.Close() + ``` + +### Complete example write script + +```go + func main() { + bucket := "example-bucket" + org := "example-org" + token := "example-token" + // Store the URL of your InfluxDB instance + url := "https://cloud2.influxdata.com" + // Create new client with default option for server url authenticate by token + client := influxdb2.NewClient(url, token) + // User blocking write client for writes to desired bucket + writeApi := client.WriteApiBlocking(org, bucket) + // Create point using full params constructor + p := influxdb2.NewPoint("stat", + map[string]string{"unit": "temperature"}, + map[string]interface{}{"avg": 24.5, "max": 45}, + time.Now()) + // Write point immediately + writeApi.WritePoint(context.Background(), p) + // Ensures background processes finishes + client.Close() +} +``` +## Query data from InfluxDB with Go +Use the Go library to query data to InfluxDB. + +1. Create a Flux query and supply your `bucket` parameter. + + ```js + from(bucket:"") + |> range(start: -1h) + |> filter(fn: (r) => r._measurement == "stat") + ``` + + The query client sends the Flux query to InfluxDB and returns the results as a FluxRecord object with a table structure. + +**The query client includes the following methods:** + +- `Query`: Sends the Flux query to InfluxDB. +- `Next`: Iterates over the query response. +- `TableChanged`: Identifies when the group key changes. +- `Record`: Returns the last parsed FluxRecord and gives access to value and row properties. +- `Value`: Returns the actual field value. + +```go + result, err := queryApi.Query(context.Background(), `from(bucket:"")|> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`) + if err == nil { + for result.Next() { + if result.TableChanged() { + fmt.Printf("table: %s\n", result.TableMetadata().String()) + } + fmt.Printf("value: %v\n", result.Record().Value()) + } + if result.Err() != nil { + fmt.Printf("query parsing error: %s\n", result.Err().Error()) + } + } else { + panic(err) + } +``` + +**The FluxRecord object includes the following methods for accessing your data:** + +- `Table()`: Returns the index of the table the record belongs to. +- `Start()`: Returns the inclusive lower time bound of all records in the current table. +- `Stop()`: Returns the exclusive upper time bound of all records in the current table. +- `Time()`: Returns the time of the record. +- `Value() `: Returns the actual field value. +- `Field()`: Returns the field name. +- `Measurement()`: Returns the measurement name of the record. +- `Values()`: Returns a map of column values. +- `ValueByKey()`: Returns a value from the record for given column key. + +### Complete example query script + +```go + func main() { + // Create client + client := influxdb2.NewClient(url, token) + // Get query client + queryApi := client.QueryApi(org) + // Get QueryTableResult + result, err := queryApi.Query(context.Background(), `from(bucket:"my-bucket")|> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`) + if err == nil { + // Iterate over query response + for result.Next() { + // Notice when group key has changed + if result.TableChanged() { + fmt.Printf("table: %s\n", result.TableMetadata().String()) + } + // Access data + fmt.Printf("value: %v\n", result.Record().Value()) + } + // Check for an error + if result.Err() != nil { + fmt.Printf("query parsing error: %s\n", result.Err().Error()) + } + } else { + panic(err) + } + // Ensures background processes finishes + client.Close() +} +``` + +For more information, see the [Go client README on GitHub](https://github.com/influxdata/influxdb-client-go). diff --git a/content/influxdb/cloud/tools/client-libraries/java.md b/content/influxdb/cloud/tools/client-libraries/java.md new file mode 100644 index 000000000..327fb1756 --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/java.md @@ -0,0 +1,12 @@ +--- +title: InfluxDB Java client library +list_title: Java +description: Use the Java client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-java +menu: + influxdb_cloud: + name: Java + parent: Use client libraries + url: https://github.com/influxdata/influxdb-client-java +weight: 201 +--- diff --git a/content/influxdb/cloud/tools/client-libraries/js.md b/content/influxdb/cloud/tools/client-libraries/js.md new file mode 100644 index 000000000..3fc18e643 --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/js.md @@ -0,0 +1,172 @@ +--- +title: JavaScript client library +seotitle: InfluxDB JavaScript client library +list_title: JavaScript +description: > + Use the JavaScript client library to interact with InfluxDB. +menu: + influxdb_cloud: + name: JavaScript + parent: Use client libraries +influxdb/cloud/tags: [client libraries, JavaScript] +weight: 201 +aliases: + - /influxdb/cloud/reference/api/client-libraries/js/ +--- + +Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into JavaScript scripts and applications. This client supports both client-side (browser) and server-side (NodeJS) environments. + +This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB. +If just getting started, see [Get started with InfluxDB](/influxdb/cloud/get-started/). + +## Before you begin + +1. Install [NodeJS](https://nodejs.org/en/download/package-manager/). + +2. Ensure that InfluxDB is running and you can connect to it. + For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/cloud/reference/urls/). + +## Easiest way to get started +1. Clone the [examples directory](https://github.com/influxdata/influxdb-client-js/tree/master/examples) in the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repo. +2. Navigate to the `examples` directory: + + ```js + cd examples + ``` +3. Install `yarn` or `npm` dependencies as needed: + +```js + yarn install + npm install +``` + +3. Update your `./env` and `index.html` with the name of your InfluxDB [bucket](/influxdb/cloud/organizations/buckets/), [organization](/influxdb/cloud/organizations/), [token](/influxdb/cloud/security/tokens/), and `proxy` which relies upon proxy to forward requests to the target InfluxDB. +4. Run the following command to run the application at [http://localhost:3001/examples/index.html]() + + ```sh + npm run browser + ``` + +## Boilerplate for the InfluxDB Javascript client library +Use the Javascript library to write data to and query data from InfluxDB. + +1. To write a data point to InfluxDB using the JavaScript library, import the latest InfluxDB Javascript library in your script. + + ```js + import {InfluxDB, Point} from 'https://unpkg.com/@influxdata/influxdb-client/dist/index.browser.mjs' + ``` + +2. Define constants for your InfluxDB [bucket](/influxdb/cloud/organizations/buckets/), [organization](/influxdb/cloud/organizations/), [token](/influxdb/cloud/security/tokens/), and `proxy` which relies on a proxy to forward requests to the target InfluxDB instance. + + ```js + const proxy = '/influx' + const token = 'example-token' + const org = 'example-org' + const bucket = 'example-bucket' + ``` + +3. Instantiate the InfluxDB JavaScript client and pass in the `proxy` and `token` parameters. + + ```js + const InfluxDB = new InfluxDB({proxy, token}) + ``` + +## Write data to InfluxDB with JavaScript +Use the Javascript library to write data to InfluxDB. + +1. Use the `getWriteApi` method of the InfluxDB client to create a **write client**. Provide your InfluxDB `org` and `bucket`. + + ```js + const writeApi = InfluxDB.getWriteApi(org, bucket) + ``` + + The `useDefaultTags` method instructs the write api to use default tags when writing points. Create a [point](/influxdb/cloud/reference/glossary/#point) and write it to InfluxDB using the `writePoint` method. The `tag` and `floatField` methods add key value pairs for the tags and fields, respectively. Close the client to flush all pending writes and finish. + + ```js + writeApi.useDefaultTags({location: 'browser'}) + const point1 = new Point('temperature') + .tag('example', 'index.html') + .floatField('value', 24) + writeApi.writePoint(point1) + console.log(`${point1}`) + writeApi.close() + ``` + +### Complete example write script + +```js +const writeApi = new InfluxDB({proxy, token}) +const writeApi = influxDB.getWriteApi(org, bucket) +// setup default tags for all writes through this API +writeApi.useDefaultTags({location: 'browser'}) +const point1 = new Point('temperature') + .tag('example', 'index.html') + .floatField('value', 24) +writeApi.writePoint(point1) +console.log(` ${point1}`) +// flush pending writes and close writeApi +writeApi + .close() + .then(() => { + console.log('WRITE FINISHED') + }) +``` + +## Query data from InfluxDB with JavaScript +Use the Javascript library to query data from InfluxDB. + +1. Use the `getQueryApi` method of the `InfluxDB` client to create a new **query client**. Provide your InfluxDB `org`. + + ```js + const queryApi = influxDB.getQueryApi(org) + ``` + +2. Create a Flux query (including your `bucket` parameter). + + ```js + const fluxQuery = + 'from(bucket:"") + |> range(start: 0) + |> filter(fn: (r) => r._measurement == "temperature")' + ``` + + The **query client** sends the Flux query to InfluxDB and returns line table metadata and rows. + +3. Use the `next` method to iterate over the rows. + + ```js + queryApi.queryRows(fluxQuery, { + next(row: string[], tableMeta: FluxTableMetaData) { + const o = tableMeta.toObject(row) + // console.log(JSON.stringify(o, null, 2)) + console.log( + `${o._time} ${o._measurement} in '${o.location}' (${o.example}): ${o._field}=${o._value}` + ) + } + } + ``` + +### Complete example query script + +```js +// performs query and receive line table metadata and rows +// https://v2.docs.influxdata.com/v2.0/reference/syntax/annotated-csv/ +queryApi.queryRows(fluxQuery, { + next(row: string[], tableMeta: FluxTableMetaData) { + const o = tableMeta.toObject(row) + // console.log(JSON.stringify(o, null, 2)) + console.log( + '${o._time} ${o._measurement} in '${o.location}' (${o.example}): ${o._field}=${o._value}` + ) + }, + error(error: Error) { + console.error(error) + console.log('\nFinished ERROR') + }, + complete() { + console.log('\nFinished SUCCESS') + }, +}) +``` + +For more information, see the [JavaScript client README on GitHub](https://github.com/influxdata/influxdb-client-js). diff --git a/content/influxdb/cloud/tools/client-libraries/kotlin.md b/content/influxdb/cloud/tools/client-libraries/kotlin.md new file mode 100644 index 000000000..9e5149add --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/kotlin.md @@ -0,0 +1,12 @@ +--- +title: InfluxDB Kotlin client library +list_title: Kotlin +description: Use the Kotlin client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-java/tree/master/client-kotlin +menu: + influxdb_cloud: + name: Kotlin + parent: Use client libraries + url: https://github.com/influxdata/influxdb-client-java/tree/master/client-kotlin +weight: 201 +--- diff --git a/content/influxdb/cloud/tools/client-libraries/php.md b/content/influxdb/cloud/tools/client-libraries/php.md new file mode 100644 index 000000000..68ce52639 --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/php.md @@ -0,0 +1,12 @@ +--- +title: InfluxDB PHP client library +list_title: PHP +description: Use the PHP client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-php +menu: + influxdb_cloud: + name: PHP + parent: Use client libraries + url: https://github.com/influxdata/influxdb-client-php +weight: 201 +--- diff --git a/content/influxdb/cloud/tools/client-libraries/python.md b/content/influxdb/cloud/tools/client-libraries/python.md new file mode 100644 index 000000000..cb9bde2a8 --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/python.md @@ -0,0 +1,171 @@ +--- +title: Python client library +list_title: Python +description: > + Use the Python client library to interact with InfluxDB. +menu: + influxdb_cloud: + name: Python + parent: Use client libraries +influxdb/cloud/tags: [client libraries, python] +aliases: + - /influxdb/cloud/reference/api/client-libraries/python/ + - /influxdb/cloud/reference/api/client-libraries/python-cl-guide/ +weight: 201 +--- + +Use the [InfluxDB Python client library](https://github.com/influxdata/influxdb-client-python) to integrate InfluxDB into Python scripts and applications. + +This guide presumes some familiarity with Python and InfluxDB. +If just getting started, see [Get started with InfluxDB](/influxdb/cloud/get-started/). + +## Before you begin + +1. Install the InfluxDB Python library: + + ```sh + pip install influxdb-client + ``` + +2. Visit the URL of your InfluxDB Cloud UI. + +## Write data to InfluxDB with Python + +We are going to write some data in [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) using the Python library. + +1. In your Python program, import the InfluxDB client library and use it to write data to InfluxDB. + + ```python + import influxdb_client + from influxdb_client.client.write_api import SYNCHRONOUS + ``` + +2. Define a few variables with the name of your [bucket](/influxdb/cloud/organizations/buckets/), [organization](/influxdb/cloud/organizations/), and [token](/influxdb/cloud/security/tokens/). + + ```python + bucket = "" + org = "" + token = "" + # Store the URL of your InfluxDB instance + url="https://cloud2.influxdata.com" + ``` + +3. Instantiate the client. The `InfluxDBClient` object takes three named parameters: `url`, `org`, and `token`. Pass in the named parameters. + + ```python + client = InfluxDBClient( + url=url, + token=token, + org=org + ) + ``` + The `InfluxDBClient` object has a `write_api` method used for configuration. + +4. Instantiate a **write client** using the `client` object and the `write_api` method. Use the `write_api` method to configure the writer object. + + ```python + write_api = client.write_api(write_options=SYNCHRONOUS) + ``` + +5. Create a [point](/influxdb/cloud/reference/glossary/#point) object and write it to InfluxDB using the `write` method of the API writer object. The write method requires three parameters: `bucket`, `org`, and `record`. + + ```python + p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3) + write_api.write(bucket=bucket, org=org, record=p) + ``` + +### Complete example write script + +```python +import influxdb_client +from influxdb_client.client.write_api import SYNCHRONOUS + +bucket = "" +org = "" +token = "" +# Store the URL of your InfluxDB instance +url="https://cloud2.influxdata.com" + +client = influxdb_client.InfluxDBClient( + url=url, + token=token, + org=org +) + +write_api = client.write_api(write_options=SYNCHRONOUS) + +p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3) +write_api.write(bucket=bucket, org=org, record=p) +``` +## Query data from InfluxDB with Python + +1. Instantiate the **query client**. + + ```python + query_api = client.query_api() + ``` + +2. Create a Flux query. + + ```python + query = ‘ from(bucket:"my-bucket")\ + |> range(start: -10m)\ + |> filter(fn:(r) => r._measurement == "my_measurement")\ + |> filter(fn: (r) => r.location == "Prague")\ + |> filter(fn:(r) => r._field == "temperature" )‘ + ``` + + The query client sends the Flux query to InfluxDB and returns a Flux object with a table structure. + +3. Pass the `query()` method two named parameters:`org` and `query`. + + ```python + result = client.query_api().query(org=org, query=query) + ``` + +4. Iterate through the tables and records in the Flux object. + - Use the `get_value()` method to return values. + - Use the `get_field()` method to return fields. + + ```python + results = [] + for table in result: + for record in table.records: + results.append((record.get_field(), record.get_value())) + + print(results) + [(temperature, 25.3)] + ``` + +**The Flux object provides the following methods for accessing your data:** + +- `get_measurement()`: Returns the measurement name of the record. +- `get_field()`: Returns the field name. +- `get_values()`: Returns the actual field value. +- `values()`: Returns a map of column values. +- `values.get("")`: Returns a value from the record for given column. +- `get_time()`: Returns the time of the record. +- `get_start()`: Returns the inclusive lower time bound of all records in the current table. +- `get_stop()`: Returns the exclusive upper time bound of all records in the current table. + + +### Complete example query script + +```python +query_api = client.query_api() +query = ‘ from(bucket:"my-bucket")\ +|> range(start: -10m)\ +|> filter(fn:(r) => r._measurement == "my_measurement")\ +|> filter(fn: (r) => r.location == "Prague")\ +|> filter(fn:(r) => r._field == "temperature" )‘ +result = client.query_api().query(org=org, query=query) +results = [] +for table in result: + for record in table.records: + results.append((record.get_field(), record.get_value())) + +print(results) +[(temperature, 25.3)] +``` + +For more information, see the [Python client README on GitHub](https://github.com/influxdata/influxdb-client-python). diff --git a/content/influxdb/cloud/tools/client-libraries/ruby.md b/content/influxdb/cloud/tools/client-libraries/ruby.md new file mode 100644 index 000000000..454cc9aac --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/ruby.md @@ -0,0 +1,12 @@ +--- +title: InfluxDB Ruby client library +list_title: Ruby +description: Use the Ruby client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-ruby +menu: + influxdb_cloud: + name: Ruby + parent: Use client libraries + url: https://github.com/influxdata/influxdb-client-ruby +weight: 201 +--- diff --git a/content/influxdb/cloud/tools/client-libraries/scala.md b/content/influxdb/cloud/tools/client-libraries/scala.md new file mode 100644 index 000000000..89872b574 --- /dev/null +++ b/content/influxdb/cloud/tools/client-libraries/scala.md @@ -0,0 +1,12 @@ +--- +title: InfluxDB Scala client library +list_title: Scala +description: Use the Scala client library to interact with InfluxDB. +external_url: https://github.com/influxdata/influxdb-client-java/tree/master/client-scala +menu: + influxdb_cloud: + name: Scala + parent: Use client libraries + url: https://github.com/influxdata/influxdb-client-java/tree/master/client-scala +weight: 201 +--- diff --git a/content/influxdb/cloud/tools/clis.md b/content/influxdb/cloud/tools/clis.md new file mode 100644 index 000000000..dd2921060 --- /dev/null +++ b/content/influxdb/cloud/tools/clis.md @@ -0,0 +1,16 @@ +--- +title: Use InfluxDB CLI +description: + Use the `influx` command line interfaces to interact with and manage InfluxDB. +menu: + influxdb_cloud: + parent: Tools & integrations +weight: 102 +influxdb/cloud/tags: [cli] +--- + +Use the `influx` CLI to interact with and manage data in your **InfluxDB** instance. +Write and query data, generate InfluxDB templates, export data, manage organizations +and users, and more. + +_For more information, see the [`influx` reference documentation](/influxdb/cloud/reference/cli/influx/)._ diff --git a/content/influxdb/cloud/tools/google-data-studio.md b/content/influxdb/cloud/tools/google-data-studio.md new file mode 100644 index 000000000..63bbc51ac --- /dev/null +++ b/content/influxdb/cloud/tools/google-data-studio.md @@ -0,0 +1,14 @@ +--- +title: Use the Google Data Studio connector +description: > + The [InfluxDB Google Data Studio connector](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs) + lets you create reports and dashboards in Google Data Studio with data from + InfluxDB Cloud or InfluxDB OSS 2.0. +menu: + influxdb_cloud: + parent: Tools & integrations +weight: 102 +influxdb/cloud/tags: [google] +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/tools/grafana.md b/content/influxdb/cloud/tools/grafana.md new file mode 100644 index 000000000..3c64e1f42 --- /dev/null +++ b/content/influxdb/cloud/tools/grafana.md @@ -0,0 +1,113 @@ +--- +title: Use Grafana with InfluxDB Cloud +description: > + Use [Grafana](https://grafana.com/) to visualize data from your **InfluxDB Cloud** instance. +menu: + influxdb_cloud: + name: Use Grafana + parent: Tools & integrations +weight: 104 +influxdb/cloud/tags: [grafana] +related: + - https://grafana.com/docs/, Grafana documentation + - /influxdb/cloud/query-data/get-started/ + - /influxdb/cloud/query-data/influxql/ +--- + +Use [Grafana](https://grafana.com/) or [Grafana Cloud](https://grafana.com/products/cloud/) +to visualize data from InfluxDB Cloud. + +{{% note %}} +The instructions in this guide require **Grafana Cloud** or **Grafana v7.1+**. +{{% /note %}} + +1. [Sign up for {{< cloud-name >}}](/influxdb/cloud/get-started/). +2. [Sign up for Grafana Cloud](https://grafana.com/products/cloud/) or + [download and install Grafana](https://grafana.com/grafana/download). +3. Visit your **Grafana Cloud user interface** (UI) or, if running Grafana locally, + [start Grafana](https://grafana.com/docs/grafana/latest/installation/) and visit + `http://localhost:3000` in your browser. +4. In the left navigation of the Grafana UI, hover over the gear + icon to expand the **Configuration** section. Click **Data Sources**. +5. Click **Add data source**. +6. Select **InfluxDB** from the list of available data sources. +7. On the **Data Source configuration page**, enter a **name** for your InfluxDB data source. +8. Under **Query Language**, select one of the following: + +{{< tabs-wrapper >}} +{{% tabs %}} +[Flux](#) +[InfluxQL](#) +{{% /tabs %}} + +{{% tab-content %}} + +## Configure Grafana to use Flux + +With **Flux** selected as the query language in your InfluxDB data source, +configure your InfluxDB connection: + +1. Under **Connection**, enter the following: + + - **URL**: Your [InfluxDB URL](/influxdb/cloud/reference/urls/). + + ```sh + https://cloud2.influxdata.com/ + ``` + + - **Organization**: Your InfluxDB [organization name **or** ID](/influxdb/cloud/organizations/view-orgs/). + - **Token**: Your InfluxDB [authentication token](/influxdb/cloud/security/tokens/). + - **Default Bucket**: The default [bucket](/influxdb/cloud/organizations/buckets/) to use in Flux queries. + - **Min time interval**: The [Grafana minimum time interval](https://grafana.com/docs/grafana/latest/features/datasources/influxdb/#min-time-interval). + + {{< img-hd src="/img/influxdb/2-0-visualize-grafana.png" />}} + +2. Click **Save & Test**. Grafana attempts to connect to the InfluxDB datasource + and returns the results of the test. +{{% /tab-content %}} + + +{{% tab-content %}} + +## Configure Grafana to use InfluxQL + +With **InfluxQL** selected as the query language in your InfluxDB data source, +configure your InfluxDB connection: + +1. Under **HTTP**, enter the following: + + - **URL**: Your [InfluxDB URL](/influxdb/cloud/reference/urls/). + + ```sh + https://cloud2.influxdata.com + ``` + - **Access**: Server (default) + +2. Under **Auth**, enable **Basic Auth**. +3. Under **Basic Auth Details**, provide your InfluxDB authentication credentials: + + - **username**: InfluxDB username + - **password**: InfluxDB [authentication token](/influxdb/cloud/security/tokens/) + +4. Under **InfluxDB details**, set the following: + + - **Database**: The database to use when querying InfluxDB. + _See [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/)._ + - **HTTP Method**: Select **GET**. + - **Min time interval**: The [Grafana minimum time interval](https://grafana.com/docs/grafana/latest/features/datasources/influxdb/#min-time-interval). + + {{< img-hd src="/img/influxdb/2-0-visualize-grafana-influxql.png" />}} + +5. Click **Save & Test**. Grafana attempts to connect to the InfluxDB datasource + and returns the results of the test. +{{% /tab-content %}} + +{{< /tabs-wrapper >}} + +## Query and visualize data + +With your InfluxDB connection configured, use Grafana and Flux to query and +visualize time series data stored in **{{< cloud-name >}}**. + +For more information about using Grafana, see the [Grafana documentation](https://grafana.com/docs/). +If you're just learning Flux, see [Get started with Flux](/influxdb/cloud/query-data/get-started/). diff --git a/content/influxdb/cloud/tools/postman.md b/content/influxdb/cloud/tools/postman.md new file mode 100644 index 000000000..79d7ef53a --- /dev/null +++ b/content/influxdb/cloud/tools/postman.md @@ -0,0 +1,49 @@ +--- +title: Use Postman with the InfluxDB API +description: > + Use [Postman](https://www.postman.com/), a popular tool for exploring APIs, + to interact with the [InfluxDB API](/influxdb/cloud/reference/api). +menu: + influxdb_cloud: + parent: Tools & integrations + name: Use Postman +weight: 105 +influxdb/cloud/tags: [api, authentication] +aliases: + - /influxdb/cloud/reference/api/postman/ +--- + +Use [Postman](https://www.postman.com/), a popular tool for exploring APIs, +to interact with the [InfluxDB API](/influxdb/cloud/reference/api). + +## Install Postman + +Download Postman from the [official downloads page](https://www.postman.com/downloads/). + +Or to install with Homebrew on macOS, run the following command: + +```sh +brew cask install postman +``` + +## Send authenticated API requests with Postman + +All requests to the InfluxDB API must be authenticated. +Postman lets you configure the headers and body of HTTP requests. + +Use the **Authorization** tab in Postman to include the credentials required when interacting with the InfluxDB API. + +1. If you have not already, [create a token](/influxdb/cloud/security/tokens/create-token/). +2. In the **Authorization** tab, select **API Key** in the **Type** dropdown. +3. For **Key**, enter `Authorization`. +4. For **Value**, enter `Token `, replacing `` with the token generated in step 1. +5. Ensure that the **Add to** option is set to **Header**. + +#### Test authentication credentials +To test the authentication, enter the `/health` endpoint of an InfluxDB OSS or +InfluxDB Cloud instance into the address bar and click **Send**. + +###### InfluxDB API health endpoint +```sh +https://cloud2.influxdata.com/api/v2/health +``` diff --git a/content/influxdb/cloud/tools/repl.md b/content/influxdb/cloud/tools/repl.md new file mode 100644 index 000000000..bc30c2af0 --- /dev/null +++ b/content/influxdb/cloud/tools/repl.md @@ -0,0 +1,55 @@ +--- +title: Use the Interactive Flux REPL +description: > + Use the Flux REPL (Read–Eval–Print Loop) to execute Flux scripts and interact + with InfluxDB and other data sources. +influxdb/cloud/tags: [flux] +menu: + influxdb_cloud: + name: Use the Flux REPL + parent: Tools & integrations +weight: 103 +--- + +Use the Flux REPL (Read–Eval–Print Loop) to execute Flux scripts and interact with InfluxDB and other data sources. +[Build the REPL](#build-the-repl) from the Flux source code. + +## Build the REPL + +To use the Flux REPL, build it from source using the [Flux repository](https://github.com/influxdata/flux/). +For instructions, see the [Flux repository README](https://github.com/influxdata/flux/#requirements). + +## Use the REPL + +- [Open a REPL session](#open-a-repl-session) +- [Query data from InfluxDB](#query-data-from-influxdb) +- [Multi-line entries](#multi-line-entries) +- [Exit the REPL](#exit-the-repl) + +### Open a REPL session +To open a new REPL session, run: + +```sh +./flux repl +``` + +### Query data from InfluxDB +To query data from InfluxDB (local or remote), provide the host, organization, and token parameters +to the [`from()` function](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from/). + +```js +from( + bucket: "example-bucket", + host: "https://cloud2.influxdata.com", + org: "example-org", + token: "My5uP3rS3cRetT0k3n" +) +``` + +### Multi-line entries +Multi-line scripts like the example above work when pasted into the REPL. +Pasting newlines from the clipboard is allowed. +However, you cannot enter newline characters directly from the keyboard. + +### Exit the REPL +Exit the REPL by pressing **Control + D**. diff --git a/content/influxdb/cloud/visualize-data/_index.md b/content/influxdb/cloud/visualize-data/_index.md new file mode 100644 index 000000000..ac4dd24df --- /dev/null +++ b/content/influxdb/cloud/visualize-data/_index.md @@ -0,0 +1,16 @@ +--- +title: Visualize data with the InfluxDB UI +description: > + InfluxDB offers a complete dashboard solution for visualizing your time series data. + Create custom dashboards with flexible queries and visualization types. +influxdb/cloud/tags: [visualize] +menu: + influxdb_cloud: + name: Visualize data +weight: 5 +--- + +The InfluxDB user interface (UI) provides tools for building custom dashboards to visualize your data. +The following articles outline ways to customize and manage dashboards. + +{{< children >}} diff --git a/content/influxdb/cloud/visualize-data/dashboards/_index.md b/content/influxdb/cloud/visualize-data/dashboards/_index.md new file mode 100644 index 000000000..aae075528 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/dashboards/_index.md @@ -0,0 +1,37 @@ +--- +title: Manage InfluxDB dashboards +description: Create, edit, and manage custom dashboards in the InfluxDB user interface (UI). +influxdb/cloud/tags: [dashboards] +menu: + influxdb_cloud: + name: Manage dashboards + parent: Visualize data +weight: 102 +--- + +Create, edit, and manage dashboards from the **Dashboards** tab in the left navigation. + +{{< children >}} + + +## View your dashboard ID + +Use the InfluxDB UI or `influx` CLI to view your dashboard ID. + +### Dashboard ID in the UI + +When viewing a dashboard in the InfluxDB UI, your dashboard ID appears in the URL. + +
+https://cloud2.influxdata.com/orgs/03a2bbf46249a000/dashboards/04b6b15034cc000/...
+
+ +### Dashboard ID in the CLI +Use [`influx dashboards`](/influxdb/cloud/reference/cli/influx/dashboards/) to view a list of dashboards and IDs. + +```sh +> influx dashboards +ID Name +03a2bbf46249a000 dashboard-1 +03ace3a859669000 dashboard-2 +``` diff --git a/content/influxdb/cloud/visualize-data/dashboards/control-dashboard.md b/content/influxdb/cloud/visualize-data/dashboards/control-dashboard.md new file mode 100644 index 000000000..1a2e7bc01 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/dashboards/control-dashboard.md @@ -0,0 +1,68 @@ +--- +title: Control a dashboard +seotitle: Control an InfluxDB dashboard +description: Control an InfluxDB dashboard in the InfluxDB user interface (UI). +influxdb/cloud/tags: [dashboards] +menu: + influxdb_cloud: + name: Control a dashboard + parent: Manage dashboards +weight: 203 +--- + +## Control at the dashboard level + +Use dashboard controls in the upper left to update your dashboard. + +### Add a cell + +Click **{{< icon "add-cell" >}} Add Cell** to open the Data Explorer and configure a new cell for your dashboard. + +For details on using the Data Explorer, see [Explore metrics](/influxdb/cloud/visualize-data/explore-metrics/). + +### Add a note + +1. Click **{{< icon "note" >}} Add Note** to add a note cell to your dashboard. +2. Enter your note in Markdown in the left pane. A preview appears in the right pane. +3. Enable the **Show note when query returns no data** option to show the note only when the query displays no data. +4. Click **Save**. + +### Select timezone + +Click the timezone dropdown to select a timezone to use for the dashboard. Select either the local time (default) or UTC. + +{{< img-hd src="/img/influxdb/2-0-controls-timezone.png" alt="Select timezone" />}} + +### Select auto-refresh interval + +Select how frequently to refresh the dashboard's data. By default, refreshing is paused. + +{{< img-hd src="/img/influxdb/2-0-controls-refresh-interval.png" alt="Select refresh interval" />}} + +### Manually refresh dashboard + +Click the refresh button (**{{< icon "refresh" >}}**) to manually refresh the dashboard's data. + +### Select time range + +1. Select from the time range options in the dropdown menu. + + {{< img-hd src="/img/influxdb/2-0-controls-time-range.png" alt="Select time range" />}} + +2. Select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. +The default time range is 5 minutes. + + > The custom time range uses the selected timezone (local time or UTC). + +### Add variables + +Click **Variables** to display variables available for your dashboard. For details, see [Use and manage variables](/influxdb/cloud/visualize-data/variables/) + +### Presentation mode + +Click the fullscreen icon (**{{< icon "fullscreen" >}}**) to enter presentation mode. Presentation mode allows you to view [a dashboard] in full screen, hiding the left and top navigation menus so only the cells appear. This mode might be helpful, for example, for stationary screens dedicated to monitoring visualizations. + +### Toggle dark mode and light mode +Click the moon or sun icons to toggle your dashboard between **dark mode** and **light mode.** + +{{< img-hd src="/img/influxdb/2-0-controls-dark-light-mode.png" alt="Dark & light mode"/>}} diff --git a/content/influxdb/cloud/visualize-data/dashboards/create-dashboard.md b/content/influxdb/cloud/visualize-data/dashboards/create-dashboard.md new file mode 100644 index 000000000..b3ddb0500 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/dashboards/create-dashboard.md @@ -0,0 +1,85 @@ +--- +title: Create a dashboard +seotitle: Create an InfluxDB dashboard +description: > + Create a new dashboard or import an existing dashboard in the + InfluxDB user interface (UI). +influxdb/cloud/tags: [dashboards] +menu: + influxdb_cloud: + name: Create a dashboard + parent: Manage dashboards +weight: 201 +--- + +## Create a new dashboard + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Click the **{{< icon "plus" >}} Create Dashboard** menu in the upper right and select **New Dashboard**. +3. Enter a name for your dashboard in the **Name this dashboard** field in the upper left. + + +**To import an existing dashboard**: + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Click the **Create Dashboard** menu in the upper right and select **Import Dashboard**. +3. In the window that appears: + * Select **Upload File** to drag-and-drop or select a file. + * Select **Paste JSON** to paste in JSON. +4. Click **Import JSON as Dashboard**. + +## Create dashboards with templates + +**To create a dashboard from a template in the dashboards page**: + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Click the **+Create Dashboard** menu in the upper right and select **From a Template**. +3. In the window that appears, select a template and review the template's variables and cells. +4. Click **Create Dashboard**. + +**To create a dashboard from a template in the templates UI**: + +1. Click the **Settings** icon in the left navigation. + + {{< nav-icon "settings" >}} + +2. Select the **Templates** tab. + + - In the **Static Templates** tab, a list of pre-created templates appears. + - In the **User Templates** tab, a list of custom user-created templates appears. + +3. Hover over the name of the template you want to create a dashboard from, then click **Create**. + + +## Clone a dashboard + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Hover over the dashboard and click **{{< icon "copy" >}}**. +3. Click **Clone**. The cloned dashboard opens. + + +#### Add data to your dashboard + +1. From your dashboard, click **{{< icon "add-cell" >}} Add Cell**. +2. Create a query in the Data Explorer following the instructions in [Explore metrics](/influxdb/cloud/visualize-data/explore-metrics). +3. Enter a name for your cell in the upper left. +4. Click the checkmark icon (**{{< icon "checkmark" >}}**) to save the cell to your dashboard. +You can also send data to your dashboard directly from the Data Explorer. For details, [Explore metrics](/influxdb/cloud/visualize-data/explore-metrics). + +#### Add a note to your dashboard +1. From your dashboard, click **{{< icon "note" >}} Add Note** in the upper left. +2. Enter your note in the window that appears. You can use Markdown syntax to format your note. +3. To preview your Markdown formatting, click the **Preview** option. +4. Click **Save**. diff --git a/content/influxdb/cloud/visualize-data/dashboards/delete-dashboard.md b/content/influxdb/cloud/visualize-data/dashboards/delete-dashboard.md new file mode 100644 index 000000000..27a48f1d7 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/dashboards/delete-dashboard.md @@ -0,0 +1,23 @@ +--- +title: Delete a dashboard +seotitle: Delete an InfluxDB dashboard +description: Delete a dashboard from the InfluxDB user interface (UI). +influxdb/cloud/tags: [dashboards] +menu: + influxdb_cloud: + parent: Manage dashboards +weight: 204 +--- + +To delete a dashboard from the InfluxDB user interface (UI): + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Hover over the dashboard in the list of dashboards and click **{{< icon "trash" >}}**. +3. Click **Delete**. + +{{% warn %}} +Deleting a dashboard cannot be undone. +{{% /warn %}} diff --git a/content/influxdb/cloud/visualize-data/dashboards/export-dashboard.md b/content/influxdb/cloud/visualize-data/dashboards/export-dashboard.md new file mode 100644 index 000000000..5803fc5bf --- /dev/null +++ b/content/influxdb/cloud/visualize-data/dashboards/export-dashboard.md @@ -0,0 +1,26 @@ +--- +title: Export a dashboard +seotitle: Export an InfluxDB dashboard +description: > + Export a dashboard using the InfluxDB user interface (UI). +influxdb/cloud/tags: [dashboards] +menu: + influxdb_cloud: + name: Export a dashboard + parent: Manage dashboards +weight: 203 +--- + +InfluxDB lets you export dashboards from the InfluxDB user interface (UI). + +1. In the navigation menu on the left, select **Boards** (**Dashboards**). + + {{< nav-icon "dashboards" >}} + +2. Hover over a dashboard and click the gear icon (**{{< icon "gear" >}}**), + and then select **Export**. +3. Review the JSON in the window that appears. +4. Select one of the following options: + * **Download JSON**: Download the dashboard as a JSON file. + * **Save as template**: Save the JSON as a dashboard template. + * **Copy to Clipboard**: Copy the JSON to your clipboard. diff --git a/content/influxdb/v2.0/visualize-data/explore-metrics.md b/content/influxdb/cloud/visualize-data/explore-metrics.md similarity index 91% rename from content/influxdb/v2.0/visualize-data/explore-metrics.md rename to content/influxdb/cloud/visualize-data/explore-metrics.md index 0c384f8ad..cc792f19e 100644 --- a/content/influxdb/v2.0/visualize-data/explore-metrics.md +++ b/content/influxdb/cloud/visualize-data/explore-metrics.md @@ -5,7 +5,7 @@ description: > The InfluxDB user interface (UI) allows you to move seamlessly between using the Flux builder and manually editing the query. menu: - influxdb_2_0: + influxdb_cloud: name: Explore metrics parent: Visualize data weight: 101 @@ -14,7 +14,7 @@ weight: 101 Explore and visualize your data in the **Data Explorer**. The InfluxDB user interface (UI) allows you to move seamlessly between using the Flux builder or templates and manually editing the query. -Choose between [visualization types](/influxdb/v2.0/visualize-data/visualization-types/) for your query. +Choose between [visualization types](/influxdb/cloud/visualize-data/visualization-types/) for your query. To open the **Data Explorer**, click the **Explore** (**Data Explorer**) icon in the left navigation menu: @@ -24,7 +24,7 @@ To open the **Data Explorer**, click the **Explore** (**Data Explorer**) icon in Flux is InfluxData's functional data scripting language designed for querying, analyzing, and acting on time series data. -See [Get started with Flux](/influxdb/v2.0/query-data/get-started) to learn more about Flux. +See [Get started with Flux](/influxdb/cloud/query-data/get-started) to learn more about Flux. 1. In the navigation menu on the left, select **Explore** (**Data Explorer**). @@ -34,7 +34,7 @@ See [Get started with Flux](/influxdb/v2.0/query-data/get-started) to learn more - Select a bucket to define your data source or select `+ Create Bucket` to add a new bucket. - Edit your time range with the [time range option](#select-time-range) in the dropdown menu. - Add filters to narrow your data by selecting attributes or columns in the dropdown menu. - - Select **Group** from the **Filter** dropdown menu to group data into tables. For more about how grouping data in Flux works, see [Group data](/influxdb/v2.0/query-data/flux/group-data/). + - Select **Group** from the **Filter** dropdown menu to group data into tables. For more about how grouping data in Flux works, see [Group data](/influxdb/cloud/query-data/flux/group-data/). 3. Alternatively, click **Script Editor** to manually edit the query. To switch back to the query builder, click **Query Builder**. Note that your updates from the Script Editor will not be saved. 4. Use the **Functions** list to review the available Flux functions. @@ -47,7 +47,7 @@ See [Get started with Flux](/influxdb/v2.0/query-data/get-started) to learn more ## Visualize your query -- Select an available [visualization types](/influxdb/v2.0/visualize-data/visualization-types/) from the dropdown menu in the upper-left: +- Select an available [visualization types](/influxdb/cloud/visualize-data/visualization-types/) from the dropdown menu in the upper-left: {{< img-hd src="/img/influxdb/2-0-visualizations-dropdown.png" title="Visualization dropdown" />}} diff --git a/content/influxdb/cloud/visualize-data/labels.md b/content/influxdb/cloud/visualize-data/labels.md new file mode 100644 index 000000000..355023383 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/labels.md @@ -0,0 +1,44 @@ +--- +title: Manage labels in the InfluxDB UI +description: > + Labels are a way to add visual metadata to dashboards, tasks, and other items + in the InfluxDB UI. View and manage labels in the InfluxDB user interface. +influxdb/cloud/tags: [labels] +menu: + influxdb_cloud: + name: Manage labels + parent: Visualize data +weight: 104 +--- + +Labels are a way to add visual metadata to dashboards, tasks, and other items in the InfluxDB UI. +To manage labels: + +- In the navigation menu on the left, select **Settings** > **Labels**. + + {{< nav-icon "settings" >}} + + +#### Create a label +1. Click **{{< icon "plus" >}} Create Label**. +2. Enter a **Name** for the label. +3. Enter a description for the label _(Optional)_. +4. Select a **Color** for the label. +5. Click **Create Label**. + +#### Edit a label +1. In the label list view, click the name of the label you would like to edit. + The **Edit Label** overlay will appear. +2. Make the desired changes to the label. +3. Click **Save Changes**. + +#### Delete a label +1. In the label list view, hover over the label you would like to delete and click **{{< icon "trash" >}}**. +2. Click **Delete**. + +### Add labels to dashboard items +1. In the list view of dashboards, tasks, or other assets, hover over the item to which you would like to add a label. +2. Click the {{< icon "add-label" >}} icon that appears below the name. + The **Add Labels** overlay will appear. +3. Type the name of the label you would like to add to filter the list of available labels. + Click the label you would like to add. diff --git a/content/influxdb/cloud/visualize-data/variables/_index.md b/content/influxdb/cloud/visualize-data/variables/_index.md new file mode 100644 index 000000000..9185ffcd8 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/variables/_index.md @@ -0,0 +1,73 @@ +--- +title: Use and manage variables +seotitle: Use and manage dashboard variables +description: > + Dashboard variables allow you to alter specific components of cells' queries + without having to edit the queries, making it easy to interact with your dashboard cells and explore your data. +menu: + influxdb_cloud: + parent: Visualize data +weight: 103 +influxdb/cloud/tags: [variables] +--- + +Dashboard variables let you alter specific components of cells' queries without having to edit the queries, +making it easy to interact with your dashboard cells and explore your data. + +Variables are scoped by organization. + +## Use dashboard variables +Both [predefined dashboard variables](#predefined-dashboard-variables) and [custom dashboard variables](#custom-dashboard-variables) +are stored in a `v` record associated with each dashboard. +Reference each variable using dot-notation (e.g. `v.variableName`). + +```js +from(bucket: v.bucket) + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r._measurement == v.measurement and r._field == v.field) + |> aggregateWindow(every: v.windowPeriod, fn: mean) +``` + +When building Flux queries for dashboard cells, view available dashboard variables +in the **Variables** tab next to the Functions tab. + +{{< img-hd src="/img/influxdb/2-0-variables-data-explorer-view.png" />}} + +Click a variable name to add it to your query and select a value from the **Value** dropdown. + +## Link to dashboards with variables defined in the URL + +When you apply a variable to your dashboard, `&vars[variable_name]=value` is appended to the URL so you can share the link with the variables included. + +## Predefined dashboard variables +The InfluxDB user interface (UI) provides the following predefined dashboard variables: + +#### v.timeRangeStart +Specifies the beginning of the queried time range. +This variable is typically used to define the [`start` parameter](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range#start) +of the `range()` function. + +The **Time Range** selector defines the value of this variable. + +#### v.timeRangeStop +Specifies the end of the queried time range. +This variable is typically used to define the [`stop` parameter](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range#stop) +of the `range()` function. + +The **Time Range** selector defines the value of this variable. +It defaults to `now`. + +#### v.windowPeriod +Specifies the period of windowed data. +This variable is typically used to define the `every` or `period` parameters of the +[`window()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window) +in data aggregation operations. + +The value of this variable is calculated by analyzing the duration of the Flux +query it is used within. Queries that fetch data from a longer time range will +have a larger `v.windowPeriod` duration. + +## Custom dashboard variables +Create, manage, and use custom dashboard variables in the InfluxDB user interface (UI). + +{{< children >}} diff --git a/content/influxdb/cloud/visualize-data/variables/common-variables.md b/content/influxdb/cloud/visualize-data/variables/common-variables.md new file mode 100644 index 000000000..a068a44b3 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/variables/common-variables.md @@ -0,0 +1,106 @@ +--- +title: Common variable queries +description: Useful queries to use to populate values in common dashboard variable use cases. +menu: + influxdb_cloud: + parent: Use and manage variables + name: Common variable queries +weight: 208 +influxdb/cloud/tags: [variables] +--- + +## List buckets +List all buckets in the current organization. + +_**Flux functions:** +[buckets()](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/buckets/), +[rename()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/rename/), +[keep()](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/keep/)_ + +```js +buckets() + |> rename(columns: {"name": "_value"}) + |> keep(columns: ["_value"]) +``` + +## List measurements +List all measurements in a specified bucket. + +_**Flux package:** [InfluxDB v1](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/) +**Flux functions:** [v1.measurements()](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurements/)_ + +```js +import "influxdata/influxdb/v1" +v1.measurements(bucket: "bucket-name") +``` + +## List fields in a measurement +List all fields in a specified bucket and measurement. + +_**Flux package:** [InfluxDB v1](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/) +**Flux functions:** [v1.measurementTagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagvalues/)_ + +```js +import "influxdata/influxdb/v1" +v1.measurementTagValues( + bucket: "bucket-name", + measurement: "measurment-name", + tag: "_field" +) +``` + +## List unique tag values +List all unique tag values for a specific tag in a specified bucket. +The example below lists all unique values of the `host` tag. + +_**Flux package:** [InfluxDB v1](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/)_ +_**Flux functions:** [v1.tagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagvalues/)_ + +```js +import "influxdata/influxdb/v1" +v1.tagValues(bucket: "bucket-name", tag: "host") +``` + +## List Docker containers +List all Docker containers when using the Docker Telegraf plugin. + +_**Telegraf plugin:** [Docker](/{{< latest "telegraf" >}}/plugins/inputs/#docker)_ +_**Flux package:** [InfluxDB v1](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/)_ +_**Flux functions:** [v1.tagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/tagvalues/)_ + +```js +import "influxdata/influxdb/v1" +v1.tagValues(bucket: "bucket-name", tag: "container_name") +``` + +## List Kubernetes pods +List all Kubernetes pods when using the Kubernetes Telegraf plugin. + +_**Telegraf plugin:** [Kubernetes](/{{< latest "telegraf" >}}/plugins/inputs/#kubernetes)_ +_**Flux package:** [InfluxDB v1](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/)_ +_**Flux functions:** [v1.measurementTagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagvalues/)_ + +```js +import "influxdata/influxdb/v1" +v1.measurementTagValues( + bucket: "bucket-name", + measurement: "kubernetes_pod_container", + tag: "pod_name" +) +``` + +## List Kubernetes nodes +List all Kubernetes nodes when using the Kubernetes Telegraf plugin. + +_**Telegraf plugin:** [Kubernetes](/{{< latest "telegraf" >}}/plugins/inputs/#kubernetes)_ +_**Flux package:** [InfluxDB v1](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/)_ +_**Flux functions:** [v1.measurementTagValues()](/influxdb/cloud/reference/flux/stdlib/influxdb-v1/measurementtagvalues/)_ + +```js +import "influxdata/influxdb/v1" +v1.measurementTagValues( + bucket: "bucket-name", + measurement: "kubernetes_node", + tag: "node_name" +) +``` diff --git a/content/influxdb/cloud/visualize-data/variables/create-variable.md b/content/influxdb/cloud/visualize-data/variables/create-variable.md new file mode 100644 index 000000000..70b4aa844 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/variables/create-variable.md @@ -0,0 +1,73 @@ +--- +title: Create a variable +seotitle: Create a dashboard variable +description: Create dashboard variables in the Data Explorer, from the Organization page, or import a variable. +menu: + influxdb_cloud: + parent: Use and manage variables +weight: 201 +influxdb/cloud/tags: [variables] +--- + +Create dashboard variables in the Data Explorer, from the Settings section, or import a variable. +**Variable names must be unique.** + +There are multiple variable types that provide different means of populating your list of variable values. +_For information about variable types, see [Variable types](/influxdb/cloud/visualize-data/variables/variable-types/)._ + +{{% note %}} +##### Variable name restrictions +Variable names must begin with a letter or underscore (`_`). + +The following names cannot be used as dashboard variables because they are reserved keywords in Flux: +`and`, `import`, `not`, `return`, `option`, `test`, `empty`, `in`, `or`, `package`, and `builtin`. +{{% /note %}} + +## Create a variable in the Data Explorer + +{{% note %}} +InfluxData recommends using the Data Explorer to create +[Query dashboard variables](/influxdb/cloud/visualize-data/variables/variable-types/#query). +The [Table visualization type](/influxdb/cloud/visualize-data/visualization-types/table/) and +**View Raw Data** option to provide human-readable query results. +{{% /note %}} + +1. Click the **Data Explorer** icon in the sidebar. + + {{< nav-icon "data-explorer" >}} + +2. Use the **Query Builder** or **Script Editor** to build a query. +3. Use the [Table visualization type](/influxdb/cloud/visualize-data/visualization-types/table/) + or enable the **View Raw Data** option to view human-readable query results. +4. Click **Save As** in the upper right. +5. In the window that appears, select **Variable**. +6. Enter a name for your variable in the **Name** field. +7. Click **Create**. + +_For information about common Query variables, see [Common variable queries](/influxdb/cloud/visualize-data/variables/common-variables/)._ + +## Create a variable in the Settings section + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Enter a name for your variable. +4. Select your variable type. For details on each type, see [Variable types](/influxdb/cloud/visualize-data/variables/variable-types/). +5. Enter the appropriate variable information. +6. Click **Create**. + +## Import a variable +InfluxDB lets you import variables exported from InfluxDB in JSON format. + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Click the **{{< icon "plus" >}} Create Variable** drop-down menu and select **Import Variable**. +4. In the window that appears: + - Select **Upload File** to drag and drop or select a file. + - Select **Paste JSON** to paste in JSON. +6. Click **Import JSON as Variable**. diff --git a/content/influxdb/cloud/visualize-data/variables/delete-variable.md b/content/influxdb/cloud/visualize-data/variables/delete-variable.md new file mode 100644 index 000000000..e4f0f2850 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/variables/delete-variable.md @@ -0,0 +1,26 @@ +--- +title: Delete a variable +seotitle: Delete a dashboard variable +description: Delete a dashboard variable in the InfluxDB user interface. +menu: + influxdb_cloud: + parent: Use and manage variables +weight: 205 +influxdb/cloud/tags: [variables] +--- + +Delete an existing variable in the InfluxDB user interface (UI). + +### Delete a variable + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Hover over a variable, click the **{{< icon "trash" >}}** icon, and **Delete**. + +{{% warn %}} +Once deleted, any dashboards with queries that utilize the variable will no +longer function correctly. +{{% /warn %}} diff --git a/content/influxdb/cloud/visualize-data/variables/export-variable.md b/content/influxdb/cloud/visualize-data/variables/export-variable.md new file mode 100644 index 000000000..5bf478653 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/variables/export-variable.md @@ -0,0 +1,27 @@ +--- +title: Export a variable +seotitle: Export a dashboard variable +description: Export a dashboard variable in the InfluxDB user interface. +menu: + influxdb_cloud: + parent: Use and manage variables +weight: 204 +influxdb/cloud/tags: [variables] +--- +Export dashboard variables from the InfluxDB user interface (UI). +Variables are exported as downloadable JSON files. + +### Export a variable + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Hover over a variable in the list, then click the gear icon (**{{< icon "gear" >}}**) + and select **Export**. +4. Review the JSON in the window that appears. +5. Select one of the following options: + * **Download JSON**: Download the dashboard as a JSON file. + * **Save as template**: Save the JSON as a dashboard template. + * **Copy to Clipboard**: Copy the JSON to your clipboard. diff --git a/content/influxdb/cloud/visualize-data/variables/update-variable.md b/content/influxdb/cloud/visualize-data/variables/update-variable.md new file mode 100644 index 000000000..31603e9f7 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/variables/update-variable.md @@ -0,0 +1,23 @@ +--- +title: Update a variable +seotitle: Update a dashboard variable +description: Update a dashboard variable in the InfluxDB user interface. +menu: + influxdb_cloud: + parent: Use and manage variables +weight: 203 +influxdb/cloud/tags: [variables] +--- + +Update an existing dashboard variable's name or JSON content in the InfluxDB user interface (UI). + +### Update a variable + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +2. Select the **Variables** tab. +3. Click a variable's name from the list. +4. Update the variable's name, type, and associated information. +5. Click **Submit**. diff --git a/content/influxdb/cloud/visualize-data/variables/variable-types.md b/content/influxdb/cloud/visualize-data/variables/variable-types.md new file mode 100644 index 000000000..68b814b90 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/variables/variable-types.md @@ -0,0 +1,75 @@ +--- +title: Variable types +seotitle: Dashboard variable types +description: Overview of the types of dashboard variables available in InfluxDB +menu: + influxdb_cloud: + parent: Use and manage variables +weight: 207 +influxdb/cloud/tags: [variables] +--- + +Variable types determine how a variable's list of possible values is populated. +The following variable types are available: + +- [Map](#map) +- [Query](#query) +- [CSV](#csv) + +## Map +Map variables use a list of key value pairs in CSV format to map keys to specific values. +Keys populate the variable's value list in the InfluxDB user interface (UI), but +values are used when actually processing the query. + +The most common use case for map variables is aliasing simple, human-readable keys +to complex values. + +##### Map variable CSV example +```js +Juanito MacNeil,"5TKl6l8i4idg15Fxxe4P" +Astrophel Chaudhary,"bDhZbuVj5RV94NcFXZPm" +Ochieng Benes,"YIhg6SoMKRUH8FMlHs3V" +Mila Emile,"o61AhpOGr5aO3cYVArC0" +``` + +## Query +Query variable values are populated using the `_value` column of a Flux query. + +##### Query variable example +```js +// List all buckets +buckets() + |> rename(columns: {"name": "_value"}) + |> keep(columns: ["_value"]) +``` + +_For examples of dashboard variable queries, see [Common variable queries](/influxdb/cloud/visualize-data/variables/common-variables)._ + +{{% note %}} +#### Important things to note about variable queries +- The variable will only use values from the `_value` column. + If the data you’re looking for is in a column other than `_value`, use the + [`rename()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/rename/) or + [`map()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/map/) functions + to change the name of that column to `_value`. +- The variable will only use the first table in the output stream. + Use the [`group()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/group) + to group everything into a single table. +- Do not use any [predefined dashboard variables](/influxdb/cloud/visualize-data/variables/#predefined-dashboard-variables) in variable queries. +{{% /note %}} + +## CSV +CSV variables use a CSV-formatted list to populate variable values. +A common use case is when the list of potential values is static and cannot be +queried from InfluxDB. + +##### CSV variable examples +``` +value1, value2, value3, value4 +``` +``` +value1 +value2 +value3 +value4 +``` diff --git a/content/influxdb/cloud/visualize-data/variables/view-variables.md b/content/influxdb/cloud/visualize-data/variables/view-variables.md new file mode 100644 index 000000000..05a23a078 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/variables/view-variables.md @@ -0,0 +1,31 @@ +--- +title: View variables +seotitle: View dashboard variables +description: View dashboard variables in the InfluxDB user interface. +menu: + influxdb_cloud: + parent: Use and manage variables +weight: 203 +influxdb/cloud/tags: [variables] +--- + +View a list of dashboard variables in the InfluxDB user interface (UI) from an organization or from the Data Explorer. + +## View variables in the organization + +1. Click the **Settings** icon in the navigation bar. + + {{< nav-icon "settings" >}} + +3. Select the **Variables** tab. + +## View variables in the Data Explorer + +1. Click the **Data Explorer** icon in the navigation bar. + + {{< nav-icon "data-explorer" >}} + +2. Switch to **Script Editor**. +3. Click the **Variables** tab to the right of the script editor. + + {{< img-hd src="/img/influxdb/2-0-variables-data-explorer-view.png" />}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/_index.md b/content/influxdb/cloud/visualize-data/visualization-types/_index.md new file mode 100644 index 000000000..95291ab67 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/_index.md @@ -0,0 +1,17 @@ +--- +title: Visualization types +description: > + The InfluxDB UI provides multiple visualization types to visualize your data in + a format that makes to the most sense for your use case. Use to available customization + options to customize each visualization. +menu: + influxdb_cloud: + parent: Visualize data +weight: 105 +--- + +The InfluxDB UI provides multiple visualization types to visualize your data in +a format that makes to the most sense for your use case. Use to available customization +options to customize each visualization. + +{{< children >}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/band.md b/content/influxdb/cloud/visualize-data/visualization-types/band.md new file mode 100644 index 000000000..298d4fd3d --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/band.md @@ -0,0 +1,13 @@ +--- +title: Band Plot visualization +list_title: Band +list_image: /img/influxdb/2-0-visualizations-Band-example.png +description: +weight: 206 +menu: + influxdb_cloud: + name: Band + parent: Visualization types +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/gauge.md b/content/influxdb/cloud/visualize-data/visualization-types/gauge.md new file mode 100644 index 000000000..85b92615a --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/gauge.md @@ -0,0 +1,67 @@ +--- +title: Gauge visualization +list_title: Gauge +list_image: /img/influxdb/2-0-visualizations-gauge-example.png +description: > + The Gauge view displays the single value most recent value for a time series in a gauge view. +weight: 206 +menu: + influxdb_cloud: + name: Gauge + parent: Visualization types +--- + +The **Gauge** visualization displays the most recent value for a time series in a gauge. + +{{< img-hd src="/img/influxdb/2-0-visualizations-gauge-example-8.png" alt="Gauge example" />}} + +Select the **Gauge** option from the visualization dropdown in the upper right. + +## Gauge behavior +The gauge visualization displays a single numeric data point within a defined spectrum (_default is 0-100_). +It uses the latest point in the first table (or series) returned by the query. + +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Gauge displaying inconsistent data. +For consistent results, the Gauge query should return a single table. +{{% /note %}} + +## Gauge Controls +To view **Gauge** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +- **Prefix**: Prefix to add to the gauge. +- **Suffix**: Suffix to add to the gauge. +- **Decimal Places**: The number of decimal places to display for the gauge. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the gauge based on the current value. + - **Value is**: Enter the value at which the gauge should appear in the selected color. + Choose a color from the dropdown menu next to the value. + +## Gauge examples +Gauge visualizations are useful for showing the current value of a metric and displaying +where it falls within a spectrum. + +### Steam pressure gauge +The following example queries sensor data that tracks the pressure of steam pipes +in a facility and displays it as a gauge. + +###### Query pressure data from a specific sensor +```js +from(bucket: "example-bucket") + |> range(start: -1m) + |> filter(fn: (r) => + r._measurement == "steam-sensors" and + r._field == "psi" + r.sensorID == "a211i" + ) +``` + +###### Visualization options for pressure gauge +{{< img-hd src="/img/influxdb/2-0-visualizations-gauge-pressure-8.png" alt="Pressure guage example" />}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/graph-single-stat.md b/content/influxdb/cloud/visualize-data/visualization-types/graph-single-stat.md new file mode 100644 index 000000000..f3f80e707 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/graph-single-stat.md @@ -0,0 +1,96 @@ +--- +title: Graph + Single Stat visualization +list_title: Graph + Single Stat +list_image: /img/influxdb/2-0-visualizations-line-graph-single-stat-example.png +description: > + The Graph + Single Stat view displays the specified time series in a line graph + and overlays the single most recent value as a large numeric value. +weight: 202 +menu: + influxdb_cloud: + name: Graph + Single Stat + parent: Visualization types +related: + - /influxdb/cloud/visualize-data/visualization-types/graph + - /influxdb/cloud/visualize-data/visualization-types/single-stat +--- + +The **Graph + Single Stat** view displays the specified time series in a line graph +and overlays the single most recent value as a large numeric value. + +{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-single-stat-example-8.png" alt="Line Graph + Single Stat example" />}} + +Select the **Graph + Single Stat** option from the visualization dropdown in the upper right. + +## Graph + Single Stat behavior +The Graph visualization color codes each table (or series) in the queried data set. +When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). + +The Single Stat visualization displays a single numeric data point. +It uses the latest point in the first table (or series) returned by the query. + +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Single Stat visualization displaying inconsistent data. +For consistent Single Stat results, the query should return a single table. +{{% /note %}} + +## Graph + Single Stat Controls +To view **Graph + Single Stat** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. + +###### Options +- **Line Colors**: Select a color scheme to use for your graph. +- **Shade Area Below Lines**: Shade in the area below the graph lines. + +###### Y Axis +- **Y Axis Label**: Label for the y-axis. +- **Y Tick Prefix**: Prefix to be added to y-value. +- **Y Tick Suffix**: Suffix to be added to y-value. +- **Y Axis Domain**: The y-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum y-axis value. + - **Max**: Maximum y-axis value. +- **Positioning**: + - **Overlaid**: Display graph lines overlaid on each other. + - **Stacked**: Display graph lines stacked on top of each other. + +###### Customize Single-Stat +- **Prefix**: Prefix to be added to the single stat. +- **Suffix**: Suffix to be added to the single stat. +- **Decimal Places**: The number of decimal places to display for the single stat. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the single stat based on the current value. + - **Value is**: Enter the value at which the single stat should appear in the selected color. + Choose a color from the dropdown menu next to the value. +- **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. + Choose **Background** for the background of the graph to change color based on the configured thresholds. + +## Graph + Single Stat examples +The primary use case for the Graph + Single Stat visualization is to show the current or latest +value as well as historical values. + +### Show current value and historical values +The following example shows the current percentage of memory used as well as memory usage over time: + +###### Query memory usage percentage +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) +``` +###### Memory allocations visualization +{{< img-hd src="/img/influxdb/2-0-visualizations-graph-single-stat-mem-8.png" alt="Graph + Single Stat Memory Usage Example" />}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/graph.md b/content/influxdb/cloud/visualize-data/visualization-types/graph.md new file mode 100644 index 000000000..29d4bd17a --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/graph.md @@ -0,0 +1,74 @@ +--- +title: Graph visualization +list_title: Graph +list_image: /img/influxdb/2-0-visualizations-line-graph-example.png +description: > + The Graph view lets you select from multiple graph types such as line graphs and bar graphs *(Coming)*. +weight: 201 +menu: + influxdb_cloud: + name: Graph + parent: Visualization types +--- + +The Graph visualization provides several types of graphs, each configured through +the [Graph controls](#graph-controls). + +{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-example-8.png" alt="Line Graph example" />}} + +Select the **Graph** option from the visualization dropdown in the upper right. + +## Graph behavior +The Graph visualization color codes each table (or series) in the queried data set. +When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). + +When using a line graph, all points within a single table are connected. When multiple series are present, it automatically assigns colors based on the selected [Line Colors option](#options). + +## Graph controls +To view **Graph** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. + +###### Options +- **Interpolation**: Select from the following options: + - **Line**: Display a time series in a line graph + - **Smooth**: Display a time series in a line graph with smooth point interpolation. + - **Step**: Display a time series in a staircase graph. + + +- **Line Colors**: Select a color scheme to use for your graph. +- **Shade Area Below Lines**: Shade in the area below the graph lines. + +###### Y Axis +- **Y Axis Label**: Label for the y-axis. +- **Y Tick Prefix**: Prefix to be added to y-value. +- **Y Tick Suffix**: Suffix to be added to y-value. +- **Y Axis Domain**: The y-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum y-axis value. + - **Max**: Maximum y-axis value. +- **Positioning**: + - **Overlaid**: Display graph lines overlaid on each other. + - **Stacked**: Display graph lines stacked on top of each other. + + +## Graph Examples + +##### Graph with linear interpolation +{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-example-8.png" alt="Line Graph example" />}} + +##### Graph with smooth interpolation +{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-smooth-example-8.png" alt="Step-Plot Graph example" />}} + +##### Graph with step interpolation +{{< img-hd src="/img/influxdb/2-0-visualizations-line-graph-step-example-8.png" alt="Step-Plot Graph example" />}} + + + + diff --git a/content/influxdb/cloud/visualize-data/visualization-types/heatmap.md b/content/influxdb/cloud/visualize-data/visualization-types/heatmap.md new file mode 100644 index 000000000..f7c4fa451 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/heatmap.md @@ -0,0 +1,115 @@ +--- +title: Heatmap visualization +list_title: Heatmap +list_image: /img/influxdb/2-0-visualizations-heatmap-example.png +description: > + A Heatmap displays the distribution of data on an x and y axes where color + represents different concentrations of data points. +weight: 203 +menu: + influxdb_cloud: + name: Heatmap + parent: Visualization types +related: + - /influxdb/cloud/visualize-data/visualization-types/scatter +--- + +A **Heatmap** displays the distribution of data on an x and y axes where color +represents different concentrations of data points. + +{{< img-hd src="/img/influxdb/2-0-visualizations-heatmap-example.png" alt="Heatmap example" />}} + +Select the **Heatmap** option from the visualization dropdown in the upper right. + +## Heatmap behavior +Heatmaps divide data points into "bins" – segments of the visualization with upper +and lower bounds for both [X and Y axes](#data). +The [Bin Size option](#options) determines the bounds for each bin. +The total number of points that fall within a bin determine the its value and color. +Warmer or brighter colors represent higher bin values or density of points within the bin. + +## Heatmap Controls +To view **Heatmap** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. + +###### Options +- **Color Scheme**: Select a color scheme to use for your heatmap. +- **Bin Size**: Specify the size of each bin. Default is 10. + +###### X Axis +- **X Axis Label**: Label for the x-axis. +- **X Tick Prefix**: Prefix to be added to x-value. +- **X Tick Suffix**: Suffix to be added to x-value. +- **X Axis Domain**: The x-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum x-axis value. + - **Max**: Maximum x-axis value. + +###### Y Axis +- **Y Axis Label**: Label for the y-axis. +- **Y Tick Prefix**: Prefix to be added to y-value. +- **Y Tick Suffix**: Suffix to be added to y-value. +- **Y Axis Domain**: The y-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum y-axis value. + - **Max**: Maximum y-axis value. + +## Heatmap examples + +### Cross-measurement correlation +The following example explores possible correlation between CPU and Memory usage. +It uses data collected with the Telegraf [Mem](/{{< latest "telegraf" >}}/plugins//#mem) +and [CPU](/{{< latest "telegraf" >}}/plugins//#cpu) input plugins. + +###### Join CPU and memory usage +The following query joins CPU and memory usage on `_time`. +Each row in the output table contains `_value_cpu` and `_value_mem` columns. + +```js +cpu = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + +mem = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + +join(tables: {cpu: cpu, mem: mem}, on: ["_time"], method: "inner") +``` + +###### Use a heatmap to visualize correlation +In the Heatmap visualization controls, `_value_cpu` is selected as the [X Column](#data) +and `_value_mem` is selected as the [Y Column](#data). +The domain for each axis is also customized to account for the scale difference +between column values. + +{{< img-hd src="/img/influxdb/2-0-visualizations-heatmap-correlation.png" alt="Heatmap correlation example" />}} + + +## Important notes + +### Differences between a heatmap and a scatter plot +Heatmaps and [Scatter plots](/influxdb/cloud/visualize-data/visualization-types/scatter/) +both visualize the distribution of data points on X and Y axes. +However, in certain cases, heatmaps provide better visibility into point density. + +For example, the dashboard cells below visualize the same query results: + +{{< img-hd src="/img/influxdb/2-0-visualizations-heatmap-vs-scatter.png" alt="Heatmap vs Scatter plot" />}} + +The heatmap indicates isolated high point density, which isn't visible in the scatter plot. +In the scatter plot visualization, points that share the same X and Y coordinates +appear as a single point. diff --git a/content/influxdb/cloud/visualize-data/visualization-types/histogram.md b/content/influxdb/cloud/visualize-data/visualization-types/histogram.md new file mode 100644 index 000000000..7a87896c5 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/histogram.md @@ -0,0 +1,80 @@ +--- +title: Histogram visualization +list_title: Histogram +list_image: /img/influxdb/2-0-visualizations-histogram-example.png +description: > + A histogram is a way to view the distribution of data. + The y-axis is dedicated to count, and the x-axis is divided into bins. +weight: 204 +menu: + influxdb_cloud: + name: Histogram + parent: Visualization types +--- + +A histogram is a way to view the distribution of data. +The y-axis is dedicated to count, and the X-axis is divided into bins. + +{{< img-hd src="/img/influxdb/2-0-visualizations-histogram-example.png" alt="Histogram example" />}} + +Select the **Histogram** option from the visualization dropdown in the upper right. + +## Histogram behavior +The Histogram visualization is a bar graph that displays the number of data points +that fall within "bins" – segments of the X axis with upper and lower bounds. +Bin thresholds are determined by dividing the width of the X axis by the number +of bins set using the [Bins option](#options). +Data within bins can be further grouped or segmented by selecting columns in the +[Group By option](#options). + +{{% note %}} +The Histogram visualization automatically bins, segments, and counts data. +To work properly, query results **should not** be structured as histogram data. +{{% /note %}} + +## Histogram Controls +To view **Histogram** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **X Column**: The column to select data from. +- **Group By**: The column to group by. + +###### Options +- **Color Scheme**: Select a color scheme to use for your graph. +- **Positioning**: Select **Stacked** to stack groups in a bin on top of each other. + Select **Overlaid** to overlay groups in each bin. +- **Bins**: Enter a number of bins to divide data into or select Auto to automatically + calculate the number of bins. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### X Axis +- **X Axis Label**: Label for the x-axis. +- **X Axis Domain**: The x-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the value range of the x-axis. + - **Min**: Minimum x-axis value. + - **Max**: Maximum x-axis value. + +## Histogram examples + +### View error counts by severity over time +The following example uses the Histogram visualization to show the number of errors +"binned" by time and segmented by severity. +_It utilizes data from the [Telegraf Syslog plugin](/{{< latest "telegraf" >}}/plugins//#syslog)._ + +##### Query for errors by severity code +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "syslog" and + r._field == "severity_code" + ) +``` + +##### Histogram settings +In the Histogram visualization options, select `_time` as the [X Column](#data) +and `severity` as the [Group By](#data) option: + +{{< img-hd src="/img/influxdb/2-0-visualizations-histogram-errors.png" alt="Errors histogram" />}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/scatter.md b/content/influxdb/cloud/visualize-data/visualization-types/scatter.md new file mode 100644 index 000000000..d7b5e626b --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/scatter.md @@ -0,0 +1,109 @@ +--- +title: Scatter visualization +list_title: Scatter +list_image: /img/influxdb/2-0-visualizations-scatter-example.png +description: > + The Scatter view uses a scatter plot to display time series data. +weight: 208 +menu: + influxdb_cloud: + name: Scatter + parent: Visualization types +related: + - /influxdb/cloud/visualize-data/visualization-types/heatmap +--- + +The **Scatter** view uses a scatter plot to display time series data. + +{{< img-hd src="/img/influxdb/2-0-visualizations-scatter-example.png" alt="Scatter plot example" />}} + +Select the **Scatter** option from the visualization dropdown in the upper right. + +## Scatter behavior +The scatter visualization maps each data point to X and Y coordinates. +X and Y axes are specified with the [X Column](#data) and [Y Column](#data) visualization options. +Each unique series is differentiated using fill colors and symbols. +Use the [Symbol Column](#data) and [Fill Column](#data) options to select columns +used to differentiate points in the visualization. + +## Scatter controls +To view **Scatter** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +###### Data +- **Symbol Column**: Define a column containing values that should be differentiated with symbols. +- **Fill Column**: Define a column containing values that should be differentiated with fill color. +- **X Column**: Select a column to display on the x-axis. +- **Y Column**: Select a column to display on the y-axis. + +###### Options +- **Color Scheme**: Select a color scheme to use for your scatter plot. + +###### X Axis +- **X Axis Label**: Label for the x-axis. + +###### Y Axis +- **Y Axis Label**: Label for the y-axis. +- **Y Tick Prefix**: Prefix to be added to y-value. +- **Y Tick Suffix**: Suffix to be added to y-value. +- **Y Axis Domain**: The y-axis value range. + - **Auto**: Automatically determine the value range based on values in the data set. + - **Custom**: Manually specify the minimum y-axis value, maximum y-axis value, or range by including both. + - **Min**: Minimum y-axis value. + - **Max**: Maximum y-axis value. + +## Scatter examples + +### Cross-measurement correlation +The following example explores possible correlation between CPU and Memory usage. +It uses data collected with the Telegraf [Mem](/{{< latest "telegraf" >}}/plugins//#mem) +and [CPU](/{{< latest "telegraf" >}}/plugins//#cpu) input plugins. + +###### Query CPU and memory usage +The following query creates a union of CPU and memory usage. +It scales the CPU usage metric to better align with baseline memory usage. + +```js +cpu = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "cpu" and + r._field == "usage_system" and + r.cpu == "cpu-total" + ) + // Scale CPU usage + |> map(fn: (r) => ({ + _value: r._value + 60.0, + _time: r._time + }) + ) + +mem = from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + +union(tables: [cpu, mem]) +``` + +###### Use a scatter plot to visualize correlation +In the Scatter visualization controls, points are differentiated based on their group keys. + +{{< img-hd src="/img/influxdb/2-0-visualizations-scatter-correlation.png" alt="Heatmap correlation example" />}} + +## Important notes + +### Differences between a scatter plot and a heatmap +Scatter plots and [Heatmaps](/influxdb/cloud/visualize-data/visualization-types/heatmap/) +both visualize the distribution of data points on X and Y axes. +However, in certain cases, scatterplots can "hide" points if they share the same X and Y coordinates. + +For example, the dashboard cells below visualize the same query results: + +{{< img-hd src="/img/influxdb/2-0-visualizations-heatmap-vs-scatter.png" alt="Heatmap vs Scatter plot" />}} + +The heatmap indicates isolated high point density, which isn't visible in the scatter plot. +In the scatter plot visualization, points that share the same X and Y coordinates +appear as a single point. diff --git a/content/influxdb/cloud/visualize-data/visualization-types/single-stat.md b/content/influxdb/cloud/visualize-data/visualization-types/single-stat.md new file mode 100644 index 000000000..2da5ff22a --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/single-stat.md @@ -0,0 +1,65 @@ +--- +title: Single Stat visualization +list_title: Single stat +list_image: /img/influxdb/2-0-visualizations-single-stat-example.png +description: > + The Single Stat view displays the most recent value of the specified time series as a numerical value. +weight: 205 +menu: + influxdb_cloud: + name: Single Stat + parent: Visualization types +--- + +The **Single Stat** view displays the most recent value of the specified time series as a numerical value. + +{{< img-hd src="/img/influxdb/2-0-visualizations-single-stat-example-8.png" alt="Single stat example" />}} + +Select the **Single Stat** option from the visualization dropdown in the upper right. + +## Single Stat behavior +The Single Stat visualization displays a single numeric data point. +It uses the latest point in the first table (or series) returned by the query. + +{{% note %}} +#### Queries should return one table +Flux does not guarantee the order in which tables are returned. +If a query returns multiple tables (or series), the table order can change between query executions +and result in the Single Stat visualization displaying inconsistent data. +For consistent results, the Single Stat query should return a single table. +{{% /note %}} + +## Single Stat Controls +To view **Single Stat** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +- **Prefix**: Prefix to be added to the single stat. +- **Suffix**: Suffix to be added to the single stat. +- **Decimal Places**: The number of decimal places to display for the single stat. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the single stat based on the current value. + - **Value is**: Enter the value at which the single stat should appear in the selected color. + Choose a color from the dropdown menu next to the value. +- **Colorization**: Choose **Text** for the single stat to change color based on the configured thresholds. + Choose **Background** for the background of the graph to change color based on the configured thresholds. + +## Single Stat examples + +### Show human-readable current value +The following example shows the current memory usage displayed has a human-readable percentage: + +###### Query memory usage percentage +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) +``` + +###### Memory usage as a single stat +{{< img-hd src="/img/influxdb/2-0-visualizations-single-stat-example-8.png" alt="Graph + Single Stat Memory Usage Example" />}} diff --git a/content/influxdb/cloud/visualize-data/visualization-types/table.md b/content/influxdb/cloud/visualize-data/visualization-types/table.md new file mode 100644 index 000000000..a6e306208 --- /dev/null +++ b/content/influxdb/cloud/visualize-data/visualization-types/table.md @@ -0,0 +1,83 @@ +--- +title: Table visualization +list_title: Table +list_image: /img/influxdb/2-0-visualizations-table-example.png +description: > + The Table option displays the results of queries in a tabular view, which is + sometimes easier to analyze than graph views of data. +weight: 207 +menu: + influxdb_cloud: + name: Table + parent: Visualization types +--- + +The **Table** option displays the results of queries in a tabular view, which is +sometimes easier to analyze than graph views of data. + +{{< img-hd src="/img/influxdb/2-0-visualizations-table-example.png" alt="Table example" />}} + +Select the **Table** option from the visualization dropdown in the upper right. + +## Table behavior +The table visualization renders queried data in structured, easy-to-read tables. +Columns and rows match those in the query output. +If query results contain multiple tables, only one table is shown at a time. +Select other output tables in the far left column of the table visualization. +Tables are identified by their [group key](/influxdb/cloud/query-data/get-started/#group-keys). + +## Table Controls +To view **Table** controls, click **{{< icon "gear" >}} Customize** next to +the visualization dropdown. + +- **Default Sort Field**: Select the default sort field. Default is **time**. +- **Time Format**: Select the time format. Options include: + - `MM/DD/YYYY HH:mm:ss` (default) + - `MM/DD/YYYY HH:mm:ss.SSS` + - `YYYY-MM-DD HH:mm:ss` + - `HH:mm:ss` + - `HH:mm:ss.SSS` + - `MMMM D, YYYY HH:mm:ss` + - `dddd, MMMM D, YYYY HH:mm:ss` + - `Custom` +- **Decimal Places**: Enter the number of decimal places. Default (empty field) is **unlimited**. + - **Auto** or **Custom**: Enable or disable auto-setting. + +###### Column Settings +- **First Column**: Toggle to **Fixed** to lock the first column so that the listings are always visible. + Threshold settings do not apply in the first column when locked. +- **Table Columns**: + - Enter a new name to rename any of the columns. + - Click the eye icon next to a column to hide it. + - [additional]: Enter name for each additional column. + - Change the order of the columns by dragging to the desired position. + +###### Colorized Thresholds +- **Base Color**: Select a base or background color from the selection list. +- **Add a Threshold**: Change the color of the table based on the current value. + - **Value is**: Enter the value at which the table should appear in the selected color. + Choose a color from the dropdown menu next to the value. + +## Table examples +Tables are helpful when displaying many human-readable metrics in a dashboard +such as cluster statistics or log messages. + +### Human-readable cluster metrics +The following example queries the latest reported memory usage from a cluster of servers. + +###### Query the latest memory usage from each host +```js +from(bucket: "example-bucket") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => + r._measurement == "mem" and + r._field == "used_percent" + ) + |> group(columns: ["host"]) + |> last() + |> group() + |> keep(columns: ["_value", "host"]) +``` + +###### Cluster metrics in a table +{{< img-hd src="/img/influxdb/2-0-visualizations-table-human-readable.png" alt="Human readable metrics in a table" />}} diff --git a/content/influxdb/cloud/write-data/_index.md b/content/influxdb/cloud/write-data/_index.md new file mode 100644 index 000000000..9b61a5118 --- /dev/null +++ b/content/influxdb/cloud/write-data/_index.md @@ -0,0 +1,169 @@ +--- +title: Write data to InfluxDB +list_title: Write data +description: > + Collect and write time series data to InfluxDB Cloud and InfluxDB OSS. +weight: 2 +aliases: + - /influxdb/cloud/write-data/quick-start/ + - /influxdb/cloud/write-data/sample-data/demo-data/ +menu: + influxdb_cloud: + name: Write data +influxdb/cloud/tags: [write, line protocol] +related: + - /influxdb/cloud/write-data/no-code/use-telegraf/ + - /influxdb/cloud/api/#tag/Write, InfluxDB API /write endpoint + - /influxdb/cloud/reference/syntax/line-protocol + - /influxdb/cloud/reference/syntax/annotated-csv + - /influxdb/cloud/reference/cli/influx/write +--- + +Collect and write time series data to InfluxDB Cloud and InfluxDB OSS. Discover how to quickly start collecting data, and then explore other ways to write data using no-code solutions or developer tools. + + +- [What you'll need](#what-youll-need) +- [Quickly start collecting data](#quickly-start-collecting-data) + - [Demo data for InfluxDB Cloud](#demo-data-for-influxdb-cloud) + - [Sample data](#sample-data) +- [Other ways to write data](#other-ways-to-write-data) +- [Next steps](#next-steps) + +### What you'll need + +To write data into InfluxDB, you need the following: + +- **organization** – _See [View organizations](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id) + for instructions on viewing your organization ID._ +- **bucket** – _See [View buckets](/influxdb/cloud/organizations/buckets/view-buckets/) for + instructions on viewing your bucket ID._ +- **authentication token** – _See [View tokens](/influxdb/cloud/security/tokens/view-tokens/) + for instructions on viewing your authentication token._ +- **InfluxDB Cloud region URL** – _See [InfluxDB Cloud regions](/influxdb/cloud/reference/regions/)_. + +Use _line protocol_ format to write data into InfluxDB. +Each line represents a data point. +Each point requires a [*measurement*](/influxdb/cloud/reference/syntax/line-protocol/#measurement) +and [*field set*](/influxdb/cloud/reference/syntax/line-protocol/#field-set) and may also include +a [*tag set*](/influxdb/cloud/reference/syntax/line-protocol/#tag-set) and a [*timestamp*](/influxdb/cloud/reference/syntax/line-protocol/#timestamp). + +Line protocol data looks like this: + +```sh +mem,host=host1 used_percent=23.43234543 1556892576842902000 +cpu,host=host1 usage_user=3.8234,usage_system=4.23874 1556892726597397000 +mem,host=host1 used_percent=21.83599203 1556892777007291000 +``` + +#### Timestamp precision + +When writing data to InfluxDB, we [recommend including a timestamp](/influxdb/cloud/reference/syntax/line-protocol/#timestamp) with each point. +If a data point does not include a timestamp when it is received by the database, +InfluxDB uses the current system time (UTC) of its host machine. + +The default precision for timestamps is in nanoseconds. +If the precision of the timestamps is anything other than nanoseconds (`ns`), +you must **specify the precision in your write request**. +InfluxDB accepts the following precisions: + +- `ns` - Nanoseconds +- `us` - Microseconds +- `ms` - Milliseconds +- `s` - Seconds + +_For more details about line protocol, see the [Line protocol reference](/influxdb/cloud/reference/syntax/line-protocol) +and [Best practices for writing data](/influxdb/cloud/write-data/best-practices/)._ + +## Quickly start collecting data + +Familiarize yourself with querying, visualizing, and processing data in InfluxDB Cloud by collecting data right away. The following options are available: + +- [Demo data for InfluxDB Cloud](#demo-data-for-influxdb-cloud) +- [Sample data](#sample-data) + +## Demo data for InfluxDB Cloud +Use **InfluxDB Cloud** demo data buckets for quick and easy access to different +types of demo data that let you explore and familiarize yourself with InfluxDB Cloud. + +{{< youtube GSaByPC1Bdc >}} + +- [Add a demo data bucket](#add-a-demo-data-bucket) +- [Explore demo data](#explore-demo-data) +- [View demo data dashboards](#view-demo-data-dashboards) + +{{% note %}} +#### Free to use and read-only +- InfluxDB Cloud demo data buckets are **free to use** and are **_not_ subject to + [Free Plan](/influxdb/cloud/account-management/pricing-plans/#free-plan) rate limits**. +- Demo data buckets are **read-only**. You cannot write data into demo data buckets. +{{% /note %}} + +## Demo data sets +Choose from the following demo data sets: + +- **Website Monitoring** + Explore, visualize, and monitor HTTP response metrics from InfluxData websites. + + +## Add a demo data bucket +1. In the navigation menu on the left, click **Data (Load Data)** > **Buckets**. + + {{< nav-icon "data" >}} + +2. Click **{{< icon "plus" >}} Add Demo Data**, and then select the demo data bucket to add. +3. The Demo Data bucket appears in your list of buckets. + +## Explore demo data +Use the [Data Explorer](/influxdb/cloud/visualize-data/explore-metrics/) +to query and visualize data in demo data buckets. + +In the navigation menu on the left, click **Explore (Data Explorer)**. + +{{< nav-icon "explore" >}} + +## View demo data dashboards +After adding a demo data bucket, view the pre-built dashboard specific to the demo data set: + +1. In the navigation menu on the left, click **Boards (Dashboards)**. + + {{< nav-icon "dashboards" >}} + +2. Click the name of the dashboard that corresponds to your demo data bucket. + +{{% note %}} +#### Other sample data sets +See [Sample data](/influxdb/cloud/reference/sample-data) for more sample InfluxDB data sets. +{{% /note %}} + +## Sample data +Use [sample data sets](/influxdb/cloud/reference/sample-data/#sample-data-sets) +to quickly populate InfluxDB with sample time series data. + +--- + +## Other ways to write data + +There are multiple options for writing data into InfluxDB, including both no-code and developer solutions. + + - [No-code solutions](/influxdb/cloud/write-data/no-code) + - [Developer tools](/influxdb/cloud/write-data/developer-tools) + +--- + +## Next steps +With your data in InfluxDB, you're ready to do one or more of the following: + +### Query and explore your data +Query data using Flux, the UI, and the `influx` command line interface. +See [Query data](/influxdb/cloud/query-data/). + +### Process your data +Use InfluxDB tasks to process and downsample data. See [Process data](/influxdb/cloud/process-data/). + +### Visualize your data +Build custom dashboards to visualize your data. +See [Visualize data](/influxdb/cloud/visualize-data/). + +### Monitor your data and send alerts +Monitor your data and sends alerts based on specified logic. +See [Monitor and alert](/influxdb/cloud/monitor-alert/). diff --git a/content/influxdb/cloud/write-data/best-practices/_index.md b/content/influxdb/cloud/write-data/best-practices/_index.md new file mode 100644 index 000000000..edbb1ee98 --- /dev/null +++ b/content/influxdb/cloud/write-data/best-practices/_index.md @@ -0,0 +1,17 @@ +--- +title: Best practices for writing data +seotitle: Best practices for writing data to InfluxDB +description: > + Learn about the recommendations and best practices for writing data to InfluxDB. +weight: 105 +menu: + influxdb_cloud: + name: Best practices + identifier: write-best-practices + parent: Write data +--- + +The following articles walk through recommendations and best practices for writing +data to InfluxDB. + +{{< children >}} diff --git a/content/influxdb/cloud/write-data/best-practices/duplicate-points.md b/content/influxdb/cloud/write-data/best-practices/duplicate-points.md new file mode 100644 index 000000000..211439b2c --- /dev/null +++ b/content/influxdb/cloud/write-data/best-practices/duplicate-points.md @@ -0,0 +1,131 @@ +--- +title: Handle duplicate data points +seotitle: Handle duplicate data points when writing to InfluxDB +description: > + InfluxDB identifies unique data points by their measurement, tag set, and timestamp. + This article discusses methods for preserving data from two points with a common + measurement, tag set, and timestamp but a different field set. +weight: 202 +menu: + influxdb_cloud: + name: Handle duplicate points + parent: write-best-practices +influxdb/cloud/tags: [best practices, write] +--- + +InfluxDB identifies unique data points by their measurement, tag set, and timestamp +(each a part of [Line protocol](/influxdb/cloud/reference/syntax/line-protocol) used to write data to InfluxDB). + +```txt +web,host=host2,region=us_west firstByte=15.0 1559260800000000000 +--- ------------------------- ------------------- + | | | +Measurement Tag set Timestamp +``` + +## Duplicate data points +For points that have the same measurement name, tag set, and timestamp, +InfluxDB creates a union of the old and new field sets. +For any matching field keys, InfluxDB uses the field value of the new point. +For example: + +```sh +# Existing data point +web,host=host2,region=us_west firstByte=24.0,dnsLookup=7.0 1559260800000000000 + +# New data point +web,host=host2,region=us_west firstByte=15.0 1559260800000000000 +``` + +After you submit the new data point, InfluxDB overwrites `firstByte` with the new +field value and leaves the field `dnsLookup` alone: + +```sh +# Resulting data point +web,host=host2,region=us_west firstByte=15.0,dnsLookup=7.0 1559260800000000000 +``` + +```sh +from(bucket: "example-bucket") + |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) + |> filter(fn: (r) => r._measurement == "web") + +Table: keys: [_measurement, host, region] + _time _measurement host region dnsLookup firstByte +-------------------- ------------ ----- ------- --------- --------- +2019-05-31T00:00:00Z web host2 us_west 7 15 +``` + +## Preserve duplicate points +To preserve both old and new field values in duplicate points, use one of the following strategies: + +- [Add an arbitrary tag](#add-an-arbitrary-tag) +- [Increment the timestamp](#increment-the-timestamp) + +### Add an arbitrary tag +Add an arbitrary tag with unique values so InfluxDB reads the duplicate points as unique. + +For example, add a `uniq` tag to each data point: + +```sh +# Existing point +web,host=host2,region=us_west,uniq=1 firstByte=24.0,dnsLookup=7.0 1559260800000000000 + +# New point +web,host=host2,region=us_west,uniq=2 firstByte=15.0 1559260800000000000 +``` + +{{% note %}} +It is not necessary to retroactively add the unique tag to the existing data point. +Tag sets are evaluated as a whole. +The arbitrary `uniq` tag on the new point allows InfluxDB to recognize it as a unique point. +However, this causes the schema of the two points to differ and may lead to challenges when querying the data. +{{% /note %}} + +After writing the new point to InfluxDB: + +```sh +from(bucket: "example-bucket") + |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) + |> filter(fn: (r) => r._measurement == "web") + +Table: keys: [_measurement, host, region, uniq] + _time _measurement host region uniq firstByte dnsLookup +-------------------- ------------ ----- ------- ---- --------- --------- +2019-05-31T00:00:00Z web host2 us_west 1 24 7 + +Table: keys: [_measurement, host, region, uniq] + _time _measurement host region uniq firstByte +-------------------- ------------ ----- ------- ---- --------- +2019-05-31T00:00:00Z web host2 us_west 2 15 +``` + +### Increment the timestamp +Increment the timestamp by a nanosecond to enforce the uniqueness of each point. + +```sh +# Old data point +web,host=host2,region=us_west firstByte=24.0,dnsLookup=7.0 1559260800000000000 + +# New data point +web,host=host2,region=us_west firstByte=15.0 1559260800000000001 +``` + +After writing the new point to InfluxDB: + +```sh +from(bucket: "example-bucket") + |> range(start: 2019-05-31T00:00:00Z, stop: 2019-05-31T12:00:00Z) + |> filter(fn: (r) => r._measurement == "web") + +Table: keys: [_measurement, host, region] + _time _measurement host region firstByte dnsLookup +------------------------------ ------------ ----- ------- --------- --------- +2019-05-31T00:00:00.000000000Z web host2 us_west 24 7 +2019-05-31T00:00:00.000000001Z web host2 us_west 15 +``` + +{{% note %}} +The output of examples queries in this article has been modified to clearly show +the different approaches and results for handling duplicate data. +{{% /note %}} diff --git a/content/influxdb/cloud/write-data/best-practices/optimize-writes.md b/content/influxdb/cloud/write-data/best-practices/optimize-writes.md new file mode 100644 index 000000000..053f06dcd --- /dev/null +++ b/content/influxdb/cloud/write-data/best-practices/optimize-writes.md @@ -0,0 +1,113 @@ +--- +title: Optimize writes to InfluxDB +description: > + Simple tips to optimize performance and system overhead when writing data to InfluxDB. +weight: 202 +menu: + influxdb_cloud: + parent: write-best-practices +influxdb/cloud/tags: [best practices, write] +--- + +Use these tips to optimize performance and system overhead when writing data to InfluxDB. + +- [Batch writes](#batch-writes) +- [Sort tags by key](#sort-tags-by-key) +- [Use the coarsest time precision possible](#use-the-coarsest-time-precision-possible) +- [Use gzip compression](#use-gzip-compression) +- [Synchronize hosts with NTP](#synchronize-hosts-with-ntp) +- [Write multiple data points in one request](#write-multiple-data-points-in-one-request) + +{{% note %}} +The following tools write to InfluxDB and employ _most_ write optimizations by default: + +- [Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/) +- [InfluxDB client libraries](/influxdb/cloud/tools/client-libraries/) +{{% /note %}} + +## Batch writes + +Write data in batches to minimize network overhead when writing data to InfluxDB. + +{{% note %}} +The optimal batch size is 5000 lines of line protocol. +{{% /note %}} + +## Sort tags by key + +Before writing data points to InfluxDB, sort tags by key in lexicographic order. +_Verify sort results match results from the [Go `bytes.Compare` function](http://golang.org/pkg/bytes/#Compare)._ + +```sh +# Line protocol example with unsorted tags +measurement,tagC=therefore,tagE=am,tagA=i,tagD=i,tagB=think fieldKey=fieldValue 1562020262 + +# Optimized line protocol example with tags sorted by key +measurement,tagA=i,tagB=think,tagC=therefore,tagD=i,tagE=am fieldKey=fieldValue 1562020262 +``` + +## Use the coarsest time precision possible + +By default, InfluxDB writes data in nanosecond precision. +However if your data isn't collected in nanoseconds, there is no need to write at that precision. +For better performance, use the coarsest precision possible for timestamps. + +_Specify timestamp precision when [writing to InfluxDB](/influxdb/cloud/write-data/#timestamp-precision)._ + +## Use gzip compression + +Use gzip compression to speed up writes to InfluxDB. +Benchmarks have shown up to a 5x speed improvement when data is compressed. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Telegraf](#) +[Client libraries](#) +[InfluxDB API](#) +{{% /tabs %}} +{{% tab-content %}} +### Enable gzip compression in Telegraf + +In the `influxdb_v2` output plugin configuration in your `telegraf.conf`, set the +`content_encoding` option to `gzip`: + +```toml +[[outputs.influxdb_v2]] + urls = ["https://cloud2.influxdata.com"] + # ... + content_encoding = "gzip" +``` +{{% /tab-content %}} +{{% tab-content %}} +### Enable gzip compression in InfluxDB client libraries + +Each [InfluxDB client library](/influxdb/cloud/tools/client-libraries/) provides +options for compressing write requests or enforces compression by default. +The method for enabling compression is different for each library. +For specific instructions, see the [InfluxDB client libraries documentation](/influxdb/cloud/tools/client-libraries/). +{{% /tab-content %}} +{{% tab-content %}} +### Use gzip compression with the InfluxDB API + +When using the InfluxDB API `/write` endpoint to write data, set the `Content-Encoding` +header to `gzip` to compress the request data. + +```sh +curl -XPOST "https://cloud2.influxdata.com/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=s" \ + --header "Authorization: Token YOURAUTHTOKEN" \ + --header "Content-Encoding: gzip" \ + --data-raw "mem,host=host1 used_percent=23.43234543 1556896326" +``` +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +## Synchronize hosts with NTP + +Use the Network Time Protocol (NTP) to synchronize time between hosts. +If a timestamp isn't included in line protocol, InfluxDB uses its host's local +time (in UTC) to assign timestamps to each point. +If a host's clocks isn't synchronized with NTP, timestamps may be inaccurate. + +## Write multiple data points in one request + +To write multiple lines in one request, each line of line protocol must be delimited by a new line (`\n`). diff --git a/content/influxdb/v2.0/write-data/bulk-ingest-cloud.md b/content/influxdb/cloud/write-data/bulk-ingest-cloud.md similarity index 76% rename from content/influxdb/v2.0/write-data/bulk-ingest-cloud.md rename to content/influxdb/cloud/write-data/bulk-ingest-cloud.md index c1409223c..2c0ff5785 100644 --- a/content/influxdb/v2.0/write-data/bulk-ingest-cloud.md +++ b/content/influxdb/cloud/write-data/bulk-ingest-cloud.md @@ -6,13 +6,15 @@ weight: 105 description: > Write existing data to InfluxDB Cloud in bulk. menu: - influxdb_2_0: + influxdb_cloud: name: Bulk ingest parent: Write data products: [cloud] +alias: + - /influxdb/v2.0/write-data/bulk-ingest-cloud --- To upload a large amount of previously existing *historical* data into InfluxDB Cloud, contact Support for assistance. -We’ll review your ingest rate limits, volume, and existing [data schema](/influxdb/v2.0/reference/key-concepts/data-schema) to ensure the most efficient migration. +We’ll review your ingest rate limits, volume, and existing [data schema](/influxdb/cloud/reference/key-concepts/data-schema) to ensure the most efficient migration. Given our usage-based pricing and because the API is optimized for batched writing, we do not recommend using the API to ingest bulk data. diff --git a/content/influxdb/cloud/write-data/developer-tools/_index.md b/content/influxdb/cloud/write-data/developer-tools/_index.md new file mode 100644 index 000000000..402c9655b --- /dev/null +++ b/content/influxdb/cloud/write-data/developer-tools/_index.md @@ -0,0 +1,16 @@ +--- +title: Developer tools +seotitle: Write data to InfluxDB with developer tools +list_title: Use developer tools +weight: 102 +description: > + Write data to InfluxDB with developer tools. +menu: + influxdb_cloud: + name: Developer tools + parent: Write data +--- + +Write data to InfluxDB with developer tools. + +{{< children >}} diff --git a/content/influxdb/cloud/write-data/developer-tools/api.md b/content/influxdb/cloud/write-data/developer-tools/api.md new file mode 100644 index 000000000..6b7d854ee --- /dev/null +++ b/content/influxdb/cloud/write-data/developer-tools/api.md @@ -0,0 +1,65 @@ +--- +title: InfluxDB API +seotitle: Write data with the InfluxDB API +list_title: Write data with the InfluxDB API +weight: 206 +description: > + Write data to InfluxDB using the InfluxDB API. +menu: + influxdb_cloud: + name: InfluxDB API + parent: Developer tools +--- +Write data to InfluxDB using an HTTP request to the InfluxDB API `/write` endpoint. +Use the `POST` request method and include the following in your request: + +| Requirement | Include by | +|:----------- |:---------- | +| Organization | Use the `org` query parameter in your request URL. | +| Bucket | Use the `bucket` query parameter in your request URL. | +| Precision | Use the `precision` query parameter in your request URL. | +| Authentication token | Use the `Authorization: Token` header. | +| Line protocol | Pass as plain text in your request body. | + +#### Example API write request + +Below is an example API write request using `curl`. +The URL depends on on your [InfluxDB Cloud region](/influxdb/cloud/reference/regions/). + +To compress data when writing to InfluxDB, set the `Content-Encoding` header to `gzip`. +Compressing write requests reduces network bandwidth, but increases server-side load. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Uncompressed](#) +[Compressed](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +curl -XPOST "https://cloud2.influxdata.com/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=s" \ + --header "Authorization: Token YOURAUTHTOKEN" \ + --data-raw " +mem,host=host1 used_percent=23.43234543 1556896326 +mem,host=host2 used_percent=26.81522361 1556896326 +mem,host=host1 used_percent=22.52984738 1556896336 +mem,host=host2 used_percent=27.18294630 1556896336 +" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```bash +curl -XPOST "https://cloud2.influxdata.com/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=s" \ + --header "Authorization: Token YOURAUTHTOKEN" \ + --header "Content-Encoding: gzip" \ + --data-raw " +mem,host=host1 used_percent=23.43234543 1556896326 +mem,host=host2 used_percent=26.81522361 1556896326 +mem,host=host1 used_percent=22.52984738 1556896336 +mem,host=host2 used_percent=27.18294630 1556896336 +" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +_For information about **InfluxDB API response codes**, see +[InfluxDB API Write documentation](/influxdb/cloud/api/#operation/PostWrite)._ diff --git a/content/influxdb/cloud/write-data/developer-tools/client-libraries.md b/content/influxdb/cloud/write-data/developer-tools/client-libraries.md new file mode 100644 index 000000000..668595f22 --- /dev/null +++ b/content/influxdb/cloud/write-data/developer-tools/client-libraries.md @@ -0,0 +1,17 @@ +--- +title: Client libraries +seotitle: Write data with client libraries +list_title: Write data with client libraries +weight: 204 +description: > + Write data to InfluxDB using client libraries. +menu: + influxdb_cloud: + name: Client libraries + identifier: write-client-libraries + parent: Developer tools +--- + +Use language-specific client libraries to integrate with the InfluxDB v2 API. + +See [Client libraries reference](/influxdb/cloud/tools/client-libraries/) for more information. diff --git a/content/influxdb/cloud/write-data/developer-tools/csv.md b/content/influxdb/cloud/write-data/developer-tools/csv.md new file mode 100644 index 000000000..1f93116ca --- /dev/null +++ b/content/influxdb/cloud/write-data/developer-tools/csv.md @@ -0,0 +1,525 @@ +--- +title: Write CSV data to InfluxDB +description: > + Use the [`influx write` command](/influxdb/cloud/reference/cli/influx/write/) to write CSV data + to InfluxDB. Include annotations with the CSV data to determine how the data translates + into [line protocol](/influxdb/cloud/reference/syntax/line-protocol/). +menu: + influxdb_cloud: + name: Write CSV data + parent: Developer tools +aliases: + - /influxdb/cloud/write-data/csv/ +weight: 204 +related: + - /influxdb/cloud/reference/syntax/line-protocol/ + - /influxdb/cloud/reference/syntax/annotated-csv/ + - /influxdb/cloud/reference/cli/influx/write/ +--- + +Use the [`influx write` command](/influxdb/cloud/reference/cli/influx/write/) to write CSV data +to InfluxDB. Include [Extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended/) +annotations to specify how the data translates into [line protocol](/influxdb/cloud/reference/syntax/line-protocol/). +Include annotations in the CSV file or inject them using the `--header` flag of +the `influx write` command. + +##### On this page +- [CSV Annotations](#csv-annotations) +- [Inject annotation headers](#inject-annotation-headers) +- [Skip annotation headers](#skip-annotation-headers) +- [Process input as CSV](#process-input-as-csv) +- [Specify CSV character encoding](#specify-csv-character-encoding) +- [Skip rows with errors](#skip-rows-with-errors) +- [Advanced examples](#advanced-examples) + +##### Example write command +```sh +influx write -b example-bucket -f path/to/example.csv +``` + +##### example.csv +``` +#datatype measurement,tag,double,dateTime:RFC3339 +m,host,used_percent,time +mem,host1,64.23,2020-01-01T00:00:00Z +mem,host2,72.01,2020-01-01T00:00:00Z +mem,host1,62.61,2020-01-01T00:00:10Z +mem,host2,72.98,2020-01-01T00:00:10Z +mem,host1,63.40,2020-01-01T00:00:20Z +mem,host2,73.77,2020-01-01T00:00:20Z +``` + +##### Resulting line protocol +``` +mem,host=host1 used_percent=64.23 1577836800000000000 +mem,host=host2 used_percent=72.01 1577836800000000000 +mem,host=host1 used_percent=62.61 1577836810000000000 +mem,host=host2 used_percent=72.98 1577836810000000000 +mem,host=host1 used_percent=63.40 1577836820000000000 +mem,host=host2 used_percent=73.77 1577836820000000000 +``` + +{{% note %}} +To test the CSV to line protocol conversion process, use the `influx write dryrun` +command to print the resulting line protocol to stdout rather than write to InfluxDB. +{{% /note %}} + +## CSV Annotations +Use **CSV annotations** to specify which element of line protocol each CSV column +represents and how to format the data. CSV annotations are rows at the beginning +of a CSV file that describe column properties. + +The `influx write` command supports [Extended annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/extended) +which provides options for specifying how CSV data should be converted into line +protocol and how data is formatted. + +To write data to InfluxDB, data must include the following: + +- [measurement](/influxdb/cloud/reference/syntax/line-protocol/#measurement) +- [field set](/influxdb/cloud/reference/syntax/line-protocol/#field-set) +- [timestamp](/influxdb/cloud/reference/syntax/line-protocol/#timestamp) _(Optional but recommended)_ +- [tag set](/influxdb/cloud/reference/syntax/line-protocol/#tag-set) _(Optional)_ + +Use CSV annotations to specify which of these elements each column represents. + +## Write raw query results back to InfluxDB +Flux returns query results in [Annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/). +These results include all annotations necessary to write the data back to InfluxDB. + +## Inject annotation headers +If the CSV data you want to write to InfluxDB does not contain the annotations +required to properly convert the data to line protocol, use the `--header` flag +to inject annotation rows into the CSV data. + +```sh +influx write -b example-bucket \ + -f path/to/example.csv \ + --header "#constant measurement,birds" \ + --header "#datatype dataTime:2006-01-02,long,tag" +``` + +{{< flex >}} +{{% flex-content %}} +##### example.csv +``` +date,sighted,loc +2020-01-01,12,Boise +2020-06-01,78,Boise +2020-01-01,54,Seattle +2020-06-01,112,Seattle +2020-01-01,9,Detroit +2020-06-01,135,Detroit +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +birds,loc=Boise sighted=12i 1577836800000000000 +birds,loc=Boise sighted=78i 1590969600000000000 +birds,loc=Seattle sighted=54i 1577836800000000000 +birds,loc=Seattle sighted=112i 1590969600000000000 +birds,loc=Detroit sighted=9i 1577836800000000000 +birds,loc=Detroit sighted=135i 1590969600000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +#### Use files to inject headers +The `influx write` command supports importing multiple files in a single command. +Include annotations and header rows in their own file and import them with the write command. +Files are read in the order in which they're provided. + +```sh +influx write -b example-bucket \ + -f path/to/headers.csv \ + -f path/to/example.csv +``` + +{{< flex >}} +{{% flex-content %}} +##### headers.csv +``` +#constant measurement,birds +#datatype dataTime:2006-01-02,long,tag +``` +{{% /flex-content %}} +{{% flex-content %}} +##### example.csv +``` +date,sighted,loc +2020-01-01,12,Boise +2020-06-01,78,Boise +2020-01-01,54,Seattle +2020-06-01,112,Seattle +2020-01-01,9,Detroit +2020-06-01,135,Detroit +``` +{{% /flex-content %}} +{{< /flex >}} + +##### Resulting line protocol +``` +birds,loc=Boise sighted=12i 1577836800000000000 +birds,loc=Boise sighted=78i 1590969600000000000 +birds,loc=Seattle sighted=54i 1577836800000000000 +birds,loc=Seattle sighted=112i 1590969600000000000 +birds,loc=Detroit sighted=9i 1577836800000000000 +birds,loc=Detroit sighted=135i 1590969600000000000 +``` + +## Skip annotation headers +Some CSV data may include header rows that conflict with or lack the annotations +necessary to write CSV data to InfluxDB. +Use the `--skipHeader` flag to specify the **number of rows to skip** at the +beginning of the CSV data. + +```sh +influx write -b example-bucket \ + -f path/to/example.csv \ + --skipHeader=2 +``` + +You can then [inject new header rows](#inject-annotation-headers) to rename columns +and provide the necessary annotations. + +## Process input as CSV +The `influx write` command automatically processes files with the `.csv` extension as CSV files. +If your CSV file uses a different extension, use the `--format` flat to explicitly +declare the format of the input file. + +```sh +influx write -b example-bucket \ + -f path/to/example.txt \ + --format csv +``` + +{{% note %}} +The `influx write` command assumes all input files are line protocol unless they +include the `.csv` extension or you declare the `csv`. +{{% /note %}} + +## Specify CSV character encoding +The `influx write` command assumes CSV files contain UTF-8 encoded characters. +If your CSV data uses different character encoding, specify the encoding +with the `--encoding`. + +```sh +influx write -b example-bucket \ + -f path/to/example.csv \ + --encoding "UTF-16" +``` + +## Skip rows with errors +If a row in your CSV data is missing an +[element required to write to InfluxDB](/influxdb/cloud/reference/syntax/line-protocol/#elements-of-line-protocol) +or data is incorrectly formatted, when processing the row, the `influx write` command +returns an error and cancels the write request. +To skip rows with errors, use the `--skipRowOnError` flag. + +```sh +influx write -b example-bucket \ + -f path/to/example.csv \ + --skipRowOnError +``` + +{{% warn %}} +Skipped rows are ignored and are not written to InfluxDB. +{{% /warn %}} + +## Advanced examples + +- [Define constants](#define-constants) +- [Annotation shorthand](#annotation-shorthand) +- [Ignore columns](#ignore-columns) +- [Use alternate numeric formats](#use-alternate-numeric-formats) +- [Use alternate boolean format](#use-alternate-boolean-format) +- [Use different timestamp formats](#use-different-timestamp-formats) + +--- + +### Define constants +Use the Extended annotated CSV [`#constant` annotation](/influxdb/cloud/reference/syntax/annotated-csv/extended/#constant) +to add a column and value to each row in the CSV data. + +{{< flex >}} +{{% flex-content %}} +##### CSV with constants +``` +#constant measurement,example +#constant tag,source,csv +#datatype long,dateTime:RFC3339 +count,time +1,2020-01-01T00:00:00Z +4,2020-01-02T00:00:00Z +9,2020-01-03T00:00:00Z +18,2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example,source=csv count=1 1577836800000000000 +example,source=csv count=4 1577923200000000000 +example,source=csv count=9 1578009600000000000 +example,source=csv count=18 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Annotation shorthand +Extended annotated CSV supports [annotation shorthand](/influxdb/cloud/reference/syntax/annotated-csv/extended/#annotation-shorthand), +which lets you define the **column label**, **datatype**, and **default value** in the column header. + +{{< flex >}} +{{% flex-content %}} +##### CSV with annotation shorthand +``` +m|measurement,count|long|0,time|dateTime:RFC3339 +example,1,2020-01-01T00:00:00Z +example,4,2020-01-02T00:00:00Z +example,,2020-01-03T00:00:00Z +example,18,2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example count=1 1577836800000000000 +example count=4 1577923200000000000 +example count=0 1578009600000000000 +example count=18 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +#### Replace column header with annotation shorthand +It's possible to replace the column header row in a CSV file with annotation +shorthand without modifying the CSV file. +This lets you define column data types and default values while writing to InfluxDB. + +To replace an existing column header row with annotation shorthand: + +1. Use the `--skipHeader` flag to ignore the existing column header row. +2. Use the `--header` flag to inject a new column header row that uses annotation shorthand. + +{{% note %}} +`--skipHeader` is the same as `--skipHeader=1`. +{{% /note %}} + +```sh +influx write -b example-bucket \ + -f example.csv \ + --skipHeader + --header="m|measurement,count|long|0,time|dateTime:RFC3339" +``` + +{{< flex >}} +{{% flex-content %}} +##### Unmodified example.csv +``` +m,count,time +example,1,2020-01-01T00:00:00Z +example,4,2020-01-02T00:00:00Z +example,,2020-01-03T00:00:00Z +example,18,2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example count=1i 1577836800000000000 +example count=4i 1577923200000000000 +example count=0i 1578009600000000000 +example count=18i 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Ignore columns +Use the Extended annotated CSV [`#datatype ignored` annotation](/influxdb/cloud/reference/syntax/annotated-csv/extended/#ignored) +to ignore columns when writing CSV data to InfluxDB. + +{{< flex >}} +{{% flex-content %}} +##### CSV data with ignored column +``` +#datatype measurement,long,time,ignored +m,count,time,foo +example,1,2020-01-01T00:00:00Z,bar +example,4,2020-01-02T00:00:00Z,bar +example,9,2020-01-03T00:00:00Z,baz +example,18,2020-01-04T00:00:00Z,baz +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +m count=1i 1577836800000000000 +m count=4i 1577923200000000000 +m count=9i 1578009600000000000 +m count=18i 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Use alternate numeric formats +If your CSV data contains numeric values that use a non-default fraction separator (`.`) +or contain group separators, [define your numeric format](/influxdb/cloud/reference/syntax/annotated-csv/extended/#double) +in the `double`, `long`, and `unsignedLong` datatype annotations. + +{{% note %}} +If your **numeric format separators** include a comma (`,`), wrap the column annotation in double +quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter. +You can also [define a custom column separator](##################). +{{% /note %}} + +{{< tabs-wrapper >}} +{{% tabs %}} +[Floats](#) +[Integers](#) +[Uintegers](#) +{{% /tabs %}} +{{% tab-content %}} +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default float values +``` +#datatype measurement,"double:.,",dateTime:RFC3339 +m,lbs,time +example,"1,280.7",2020-01-01T00:00:00Z +example,"1,352.5",2020-01-02T00:00:00Z +example,"1,862.8",2020-01-03T00:00:00Z +example,"2,014.9",2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example lbs=1280.7 1577836800000000000 +example lbs=1352.5 1577923200000000000 +example lbs=1862.8 1578009600000000000 +example lbs=2014.9 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} +{{% /tab-content %}} + +{{% tab-content %}} +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default integer values +``` +#datatype measurement,"long:.,",dateTime:RFC3339 +m,lbs,time +example,"1,280.0",2020-01-01T00:00:00Z +example,"1,352.0",2020-01-02T00:00:00Z +example,"1,862.0",2020-01-03T00:00:00Z +example,"2,014.9",2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example lbs=1280i 1577836800000000000 +example lbs=1352i 1577923200000000000 +example lbs=1862i 1578009600000000000 +example lbs=2014i 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} +{{% /tab-content %}} + +{{% tab-content %}} +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default uinteger values +``` +#datatype measurement,"unsignedLong:.,",dateTime:RFC3339 +m,lbs,time +example,"1,280.0",2020-01-01T00:00:00Z +example,"1,352.0",2020-01-02T00:00:00Z +example,"1,862.0",2020-01-03T00:00:00Z +example,"2,014.9",2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example lbs=1280u 1577836800000000000 +example lbs=1352u 1577923200000000000 +example lbs=1862u 1578009600000000000 +example lbs=2014u 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +--- + +### Use alternate boolean format +Line protocol supports only [specific boolean values](/influxdb/cloud/reference/syntax/line-protocol/#boolean). +If your CSV data contains boolean values that line protocol does not support, +[define your boolean format](/influxdb/cloud/reference/syntax/annotated-csv/extended/#boolean) +in the `boolean` datatype annotation. + +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default boolean values +``` +sep=; +#datatype measurement,"boolean:y,Y,1:n,N,0",dateTime:RFC3339 +m,verified,time +example,y,2020-01-01T00:00:00Z +example,n,2020-01-02T00:00:00Z +example,1,2020-01-03T00:00:00Z +example,N,2020-01-04T00:00:00Z +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example verified=true 1577836800000000000 +example verified=false 1577923200000000000 +example verified=true 1578009600000000000 +example verified=false 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} + +--- + +### Use different timestamp formats +The `influx write` command automatically detects **RFC3339** and **number** formatted +timestamps when converting CSV to line protocol. +If using a different timestamp format, [define your timestamp format](/influxdb/cloud/reference/syntax/annotated-csv/extended/#datetime) +in the `dateTime` datatype annotation. + +{{< flex >}} +{{% flex-content %}} +##### CSV with non-default timestamps +``` +#datatype measurement,dateTime:2006-01-02,field +m,time,lbs +example,2020-01-01,1280.7 +example,2020-01-02,1352.5 +example,2020-01-03,1862.8 +example,2020-01-04,2014.9 +``` +{{% /flex-content %}} +{{% flex-content %}} +##### Resulting line protocol +``` +example lbs=1280.7 1577836800000000000 +example lbs=1352.5 1577923200000000000 +example lbs=1862.8 1578009600000000000 +example lbs=2014.9 1578096000000000000 +``` +{{% /flex-content %}} +{{< /flex >}} diff --git a/content/influxdb/cloud/write-data/developer-tools/influx-cli.md b/content/influxdb/cloud/write-data/developer-tools/influx-cli.md new file mode 100644 index 000000000..5910d28c9 --- /dev/null +++ b/content/influxdb/cloud/write-data/developer-tools/influx-cli.md @@ -0,0 +1,58 @@ +--- +title: Influx CLI +seotitle: Write data with the influx CLI +list_title: Write data with the influx CLI +weight: 205 +description: > + Write data to InfluxDB using the `influx` CLI. +menu: + influxdb_cloud: + name: Influx CLI + parent: Developer tools +related: + - /influxdb/cloud/write-data/developer-tools/csv/ +--- + +To write data from the command line, use the [`influx write` command](/influxdb/cloud/reference/cli/influx/write/). +Include the following in your command: + +| Requirement | Include by | +|:----------- |:---------- | +| Organization | Use the `-o`,`--org`, or `--org-id` flags. | +| Bucket | Use the `-b`, `--bucket`, or `--bucket-id` flags. | +| Precision | Use the `-p`, `--precision` flag. | +| Authentication token | Set the `INFLUX_TOKEN` environment variable or use the `t`, `--token` flag. | +| Data | Write data using **line protocol** or **annotated CSV**. Pass a file with the `-f`, `--file` flag. | + +_See [Line protocol](/influxdb/cloud/reference/syntax/line-protocol/) and [Annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv)_ + +#### Example influx write commands + +##### Write a single line of line protocol +```sh +influx write \ + -b bucketName \ + -o orgName \ + -p s \ + 'myMeasurement,host=myHost testField="testData" 1556896326' +``` + +##### Write line protocol from a file +```sh +influx write \ + -b bucketName \ + -o orgName \ + -p s \ + --format=lp + -f /path/to/line-protocol.txt +``` + +##### Write annotated CSV from a file +```sh +influx write \ + -b bucketName \ + -o orgName \ + -p s \ + --format=csv + -f /path/to/data.csv +``` diff --git a/content/influxdb/cloud/write-data/developer-tools/third-party-solutions.md b/content/influxdb/cloud/write-data/developer-tools/third-party-solutions.md new file mode 100644 index 000000000..1c6d53bdd --- /dev/null +++ b/content/influxdb/cloud/write-data/developer-tools/third-party-solutions.md @@ -0,0 +1,63 @@ +--- +title: Third-party technologies +seotitle: Write data with third-party technologies +list_title: Write data with third-party technologies +weight: 103 +description: > + Write data to InfluxDB using third-party developer tools. +aliases: +menu: + influxdb_cloud: + name: Third-party developer tools + parent: Developer tools +--- + +Configure third-party technologies to send line protocol directly to InfluxDB. + +## AWS Lambda via CloudFormation template + +Write to InfluxDB with AWS Lambda, Amazon Web Services' serverless offering. This example provides a CloudFormation template that collects earthquake from the [United States Geological Survey (USGS)](https://www.usgs.gov/) every hour and outputs it as line protocol into an InfluxDB bucket. + +The [template](https://influxdata-lambda.s3.amazonaws.com/GeoLambda.yml) contains the following sections: + +- Lines 1-20: Define variables that the template asks for when it's installed. +- Lines 21-120: Handle a quirk of Lambda deployments that requires the Lambda assets to be in your region before deployment. As there is no elegant workaround, these 100 lines create an S3 bucket in your account in the region you're creating the stack and copies in these resources. +- Lines 121-132: Define a role with basic permission to run the Lambda. +- Lines 133-144: Define a Python library layer. This layer packages the Python HTTP library, a Python S2 Geometry library, and the InfluxDB Python client library. +- Lines 145-165: Define the Lambda function, a short Python script zipped up in a file called `geo_lambda.zip`. +- Lines 166-188: Define an event rule with permission to run the Lambda every hour. + +### Deploy the template + +1. Log into your free AWS account and search for the CloudFormation service. Make sure you’re in the AWS region you want to deploy the Lambda to⁠. +2. Click **Create Stack**. +3. In the **Prerequisite - Prepare Template** section, select **Template is ready**. +4. In the **Specify template** section: + - Under **Template source**, select **Amazon S3 URL**. + - In the **Amazon S3 URL** field, enter the CloudFormation template URL: `https://influxdata-lambda.s3.amazonaws.com/GeoLambda.yml` +5. Click **Next**. +6. Enter a name in the **Stack name** field. +7. Enter the following InfluxDB details: + - Organization ID + - Bucket ID of the bucket the Lambda writes to + - Token with permission to write to the bucket + - InfluxDB URL +8. Do not alter or add to any other fields. Click **Next**. +9. Select the **I acknowledge that AWS CloudFormation might create IAM resources** check box. +10. Click **Create Stack**. + +After a few minutes, the stack deploys to your region. To view the new Lambda, select **Services > AWS Lambda**. On the Lambda functions page, you should see your new Lambda. The `CopyZipsFunction` is the helper copy function, and the `GeoPythonLambda` does the data collection and writing work: + +{{< img-hd src="/img/cloudformation1.png" alt="GeoPythonLambda data in InfluxDB" />}} + +### Verify your setup + +`GeoPythonLambda` should run every hour based on the AWS Rule we set up, but you should test and confirm it works. + +1. Click `GeoPythonLambda`, and then click **Test**. +2. The test requires an input definition, but this Lambda has no input requirements, so click through and save the default dataset. +3. If the test is successful, a green **Execution result: succeeded** message appears. + +With the data points written, when you log into your InfluxDB UI, you’ll be able to explore the geolocation earthquake data: + +{{< img-hd src="/img/cloudformation2.png" alt="GeoPythonLambda data in InfluxDB" />}} diff --git a/content/influxdb/cloud/write-data/no-code/_index.md b/content/influxdb/cloud/write-data/no-code/_index.md new file mode 100644 index 000000000..8f5f3ebba --- /dev/null +++ b/content/influxdb/cloud/write-data/no-code/_index.md @@ -0,0 +1,19 @@ +--- +title: No-code solutions +seotitle: Write data to InfluxDB without coding +list_title: Write data to InfluxDB without coding +weight: 101 +description: > + Write data to InfluxDB without writing code. +aliases: + - /influxdb/cloud/collect-data/advanced-telegraf + - /influxdb/cloud/collect-data/use-telegraf +menu: + influxdb_cloud: + name: No-code solutions + parent: Write data +--- + +The following options let you write data to InfluxDB without writing any code. Some options require a minimal amount of configuration. + +{{< children >}} diff --git a/content/influxdb/cloud/write-data/no-code/third-party.md b/content/influxdb/cloud/write-data/no-code/third-party.md new file mode 100644 index 000000000..0602698cf --- /dev/null +++ b/content/influxdb/cloud/write-data/no-code/third-party.md @@ -0,0 +1,82 @@ +--- +title: Third-party technologies +seotitle: Write data with third-party technologies +list_title: Write data with third-party technologies +weight: 103 +description: > + Write data to InfluxDB using third-party technologies. +menu: + influxdb_cloud: + name: Third-party technologies + parent: No-code solutions +--- + + +A number of third-party technologies can be configured to send line protocol directly to InfluxDB. + +If you're using any of the following technologies, check out the handy links below to configure these technologies to write data to InfluxDB (**no additional software to download or install**): + +- (Write metrics and log events only) [Vector 0.9 or later](#configure-vector) + +- [Apache NiFi 1.8 or later](#configure-apache-nifi) + +- [OpenHAB 3.0 or later](#configure-openhab) + +- [Apache JMeter 5.2 or later](#configure-apache-jmeter) + +- [FluentD 1.x or later](#configure-fluentd) + +#### Configure Vector + +1. View the **Vector documentation**: + - For write metrics, [InfluxDB Metrics Sink](https://vector.dev/docs/reference/sinks/influxdb_metrics/) + - For log events, [InfluxDB Logs Sink](https://vector.dev/docs/reference/sinks/influxdb_logs/) +2. Under **Configuration**, click **v2** to view configuration settings. +3. Scroll down to **How It Works** for more detail: + - [InfluxDB Metrics Sink – How It Works ](https://vector.dev/docs/reference/sinks/influxdb_metrics/#how-it-works) + - [InfluxDB Logs Sink – How It Works](https://vector.dev/docs/reference/sinks/influxdb_logs/#how-it-works) + +#### Configure Apache NiFi + +See the _[InfluxDB Processors for Apache NiFi Readme](https://github.com/influxdata/nifi-influxdb-bundle#influxdb-processors-for-apache-nifi)_ for details. + +#### Configure OpenHAB + +See the _[InfluxDB Persistence Readme](https://github.com/openhab/openhab-addons/tree/master/bundles/org.openhab.persistence.influxdb)_ for details. + +#### Configure Apache JMeter + + + +To configure Apache JMeter, complete the following steps in InfluxDB and JMeter. + +##### In InfluxDB + +1. [Find the name of your organization](/influxdb/cloud/organizations/view-orgs/) (needed to create a bucket and token). +2. [Create a bucket using the influx CLI](/influxdb/cloud/organizations/buckets/create-bucket/#create-a-bucket-using-the-influx-cli) and name it `jmeter`. +3. [Create a token](/influxdb/cloud/security/tokens/create-token/). + +##### In JMeter + +1. Create a [Backend Listener](https://jmeter.apache.org/usermanual/component_reference.html#Backend_Listener) using the _**InfluxDBBackendListenerClient**_ implementation. +2. In the **Backend Listener implementation** field, enter: + ``` + org.apache.jmeter.visualizers.backend.influxdb.influxdbBackendListenerClient + ``` +3. Under **Parameters**, specify the following: + - **influxdbMetricsSender**: + ``` + org.apache.jmeter.visualizers.backend.influxdb.HttpMetricsSender + ``` + - **influxdbUrl**: _(include the bucket and org you created in InfluxDB)_ + ``` + https://cloud2.influxdata.com/api/v2/write?org=my-org&bucket=jmeter + ``` + - **application**: `InfluxDB2` + - **influxdbToken**: _your InfluxDB authentication token_ + - Include additional parameters as needed. +4. Click **Add** to add the _**InfluxDBBackendListenerClient**_ implementation. + +#### Configure FluentD + +See the _[influxdb-plugin-fluent Readme](https://github.com/influxdata/influxdb-plugin-fluent)_ for details. diff --git a/content/influxdb/cloud/write-data/no-code/use-telegraf/_index.md b/content/influxdb/cloud/write-data/no-code/use-telegraf/_index.md new file mode 100644 index 000000000..447634c97 --- /dev/null +++ b/content/influxdb/cloud/write-data/no-code/use-telegraf/_index.md @@ -0,0 +1,38 @@ +--- +title: Telegraf (agent) +seotitle: Use the Telegraf agent to collect and write data +list_title: Use the Telegraf agent +weight: 101 +description: > + Use Telegraf to collect and write data to InfluxDB v2.0. + Create Telegraf configurations in the InfluxDB UI or manually configure Telegraf. +aliases: + - /influxdb/cloud/collect-data/advanced-telegraf + - /influxdb/cloud/collect-data/use-telegraf + - /influxdb/cloud/write-data/use-telegraf/ +menu: + influxdb_cloud: + name: Telegraf (agent) + parent: No-code solutions +--- + +[Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) is InfluxData's +data collection agent for collecting and reporting metrics. +Its vast library of input plugins and "plug-and-play" architecture lets you quickly +and easily collect metrics from many different sources. +This article describes how to use Telegraf to collect and store data in InfluxDB v2.0. + +For a list of available plugins, see [Telegraf plugins](/{{< latest "telegraf" >}}/plugins//). + +#### Requirements +- **Telegraf 1.9.2 or greater**. + _For information about installing Telegraf, see the + [Telegraf Installation instructions](/{{< latest "telegraf" >}}/introduction/installation/)._ + +{{< youtube qFS2zANwIrc >}} + +## Configure Telegraf +Telegraf input and output plugins are enabled and configured in Telegraf's configuration file (`telegraf.conf`). +You have the following options for configuring Telegraf: + +{{< children >}} diff --git a/content/influxdb/cloud/write-data/no-code/use-telegraf/auto-config.md b/content/influxdb/cloud/write-data/no-code/use-telegraf/auto-config.md new file mode 100644 index 000000000..a986181de --- /dev/null +++ b/content/influxdb/cloud/write-data/no-code/use-telegraf/auto-config.md @@ -0,0 +1,146 @@ +--- +title: Automatically configure Telegraf +seotitle: Automatically configure Telegraf for InfluxDB v2.0 +description: > + Use the InfluxDB UI to automatically generate a Telegraf configuration, + then start Telegraf using the generated configuration file. +menu: + influxdb_cloud: + parent: Telegraf (agent) +weight: 201 +related: + - /influxdb/cloud/telegraf-configs/create/ +--- + +The InfluxDB user interface (UI) can automatically create +Telegraf configuration files based on user-selected Telegraf plugins. +This article describes how to create a Telegraf configuration in the InfluxDB UI and +start Telegraf using the generated configuration file. + +{{% note %}} +Only a subset of plugins are configurable using the InfluxDB UI. +To use plugins other than those listed, you must [manually configure Telegraf](/influxdb/cloud/write-data/no-code/use-telegraf/manual-config). +{{% /note %}} + +{{% note %}} +_View the [requirements](/influxdb/cloud/write-data/no-code/use-telegraf#requirements) +for using Telegraf with InfluxDB v2.0._ +{{% /note %}} + +## Create a Telegraf configuration + +1. Open the InfluxDB Clou UI. +2. In the navigation menu on the left, select **Data** (**Load Data**) > **Telegraf**. + + {{< nav-icon "load data" >}} + +4. Click **{{< icon "plus" >}} Create Configuration**. +5. In the **Bucket** dropdown, select the bucket where Telegraf will store collected data. +6. Select one or more of the available plugin groups and click **Continue**. +7. Review the list of **Plugins to Configure** for configuration requirements. + Plugins listed with a {{< icon "check" >}} + require no additional configuration. + To configure a plugin or access plugin documentation, click the plugin name. + + {{% note %}} + Not all available plugins are listed on this screen. For more information on manually configuring additional plugins, see [Manually add Telegraf plugins](/influxdb/cloud/write-data/no-code/use-telegraf/manual-config/). + {{% /note %}} + +8. Provide a **Telegraf Configuration Name** and an optional **Telegraf Configuration Description**. +9. Click **Create and Verify**. +10. The **Test Your Configuration** page provides instructions for how to start + Telegraf using the generated configuration. + _See [Start Telegraf](#start-telegraf) below for detailed information about what each step does._ +11. Once Telegraf is running, click **Listen for Data** to confirm Telegraf is successfully + sending data to InfluxDB. + Once confirmed, a **Connection Found!** message appears. +12. Click **Finish**. Your Telegraf configuration name and the associated bucket name appears + in the list of Telegraf configurations. + + {{% note %}} + +### Windows + +If you plan to monitor a Windows host using the System plugin, you must complete the following steps. + +1. In the list of Telegraf configurations, double-click your + Telegraf configuration, and then click **Download Config**. +2. Open the downloaded Telegraf configuration file and replace the `[[inputs.processes]]` plugin with one of the following Windows plugins, depending on your Windows configuration: + + - [`[[inputs.win_perf_counters]]`](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/win_perf_counters) + - [`[[inputs.win_services]]`](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/win_services) + +3. Save the file and place it in a directory that **telegraf.exe** can access. + + {{% /note %}} + +## Start Telegraf + +Requests to the [InfluxDB v2 API](/influxdb/cloud/reference/api/) must include an authentication token. +A token identifies specific permissions to the InfluxDB instance. + +### Configure your token as an environment variable + +1. Find your authentication token. _For information about viewing tokens, see [View tokens](/influxdb/cloud/security/tokens/view-tokens/)._ + +2. To configure your token as the `INFLUX_TOKEN` environment variable, run the command appropriate for your operating system and command-line tool: + +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS or Linux](#) +[Windows](#) +{{% /tabs %}} + +{{% tab-content %}} +```sh +export INFLUX_TOKEN=YourAuthenticationToken +``` +{{% /tab-content %}} + +{{% tab-content %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[PowerShell](#) +[CMD](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```sh +$env:INFLUX_TOKEN = "YourAuthenticationToken" +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```sh +set INFLUX_TOKEN=YourAuthenticationToken +# Make sure to include a space character at the end of this command. +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +### Start the Telegraf service + +Start the Telegraf service using the `-config` flag to specify the location of the generated Telegraf configuration file. + +- For Windows, the location is always a local file path. +- For Linux and macOS, the location can be a local file path or URL. + +Telegraf starts using the Telegraf configuration pulled from InfluxDB API. + +{{% note %}} +InfluxDB host URLs and ports differ between InfluxDB OSS and InfluxDB Cloud. +For the exact command, see the Telegraf configuration **Setup Instructions** in the InfluxDB UI. +{{% /note %}} + +```sh +telegraf -config https://cloud2.influxdata.com/api/v2/telegrafs/0xoX00oOx0xoX00o +``` + +## Manage Telegraf configurations + +For more information about managing Telegraf configurations in InfluxDB, see +[Telegraf configurations](/influxdb/cloud/telegraf-configs/). diff --git a/content/influxdb/cloud/write-data/no-code/use-telegraf/manual-config.md b/content/influxdb/cloud/write-data/no-code/use-telegraf/manual-config.md new file mode 100644 index 000000000..29dc579d7 --- /dev/null +++ b/content/influxdb/cloud/write-data/no-code/use-telegraf/manual-config.md @@ -0,0 +1,161 @@ +--- +title: Manually configure Telegraf +seotitle: Manually configure Telegraf for InfluxDB v2.0 +description: > + Update existing or create new Telegraf configurations to use the `influxdb_v2` + output plugin to write to InfluxDB v2.0. + Start Telegraf using the custom configuration. +aliases: + - /influxdb/cloud/collect-data/use-telegraf/manual-config + - /influxdb/cloud/write-data/use-telegraf/manual-config +menu: + influxdb_cloud: + parent: Telegraf (agent) +weight: 202 +influxdb/cloud/tags: [manually, plugin, mqtt] +related: + - /{{< latest "telegraf" >}}/plugins// + - /influxdb/cloud/telegraf-configs/create/ + - /influxdb/cloud/telegraf-configs/update/ +--- + +Use the Telegraf `influxdb_v2` output plugin to collect and write metrics into an InfluxDB v2.0 bucket. +This article describes how to enable the `influxdb_v2` output plugin in new and existing Telegraf configurations, +then start Telegraf using the custom configuration file. + +{{< youtube qFS2zANwIrc >}} + +{{% note %}} +_View the [requirements](/influxdb/cloud/write-data/no-code/use-telegraf#requirements) +for using Telegraf with InfluxDB v2.0._ +{{% /note %}} + +## Configure Telegraf input and output plugins +Configure Telegraf input and output plugins in the Telegraf configuration file (typically named `telegraf.conf`). +Input plugins collect metrics. +Output plugins define destinations where metrics are sent. + +_See [Telegraf plugins](/{{< latest "telegraf" >}}/plugins//) for a complete list of available plugins._ + +### Manually add Telegraf plugins + +To manually add any of the available [Telegraf plugins](/{{< latest "telegraf" >}}/plugins//), follow the steps below. + +1. Find the plugin you want to enable from the complete list of available [Telegraf plugins](/{{< latest "telegraf" >}}/plugins//). +2. Click **View** to the right of the plugin name to open the plugin page on GitHub. For example, view the MQTT plugin GitHub page [here](https://github.com/influxdata/telegraf/blob/release-1.14/plugins/inputs/mqtt_consumer/README.md). +3. Copy and paste the example configuration into your Telegraf configuration file (typically named `telegraf.conf`). + +### Enable and configure the InfluxDB v2 output plugin + +To send data to an InfluxDB v2.0 instance, enable in the +[`influxdb_v2` output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb_v2/README.md) +in the `telegraf.conf`. + +To find an example InfluxDB v2 output plugin configuration in the UI: + +1. In the navigation menu on the left, select **Data (Load Data)** > **Telegraf**. + + {{< nav-icon "load data" >}} + +2. Click **InfluxDB Output Plugin**. +3. Click **Copy to Clipboard** to copy the example configuration or **Download Config** to save a copy. +4. Paste the example configuration into your `telegraf.conf` and specify the options below. + +The InfluxDB output plugin configuration contains the following options: + +##### urls +An array of URLs for your InfluxDB v2.0 instances. +See [InfluxDB URLs](/influxdb/cloud/reference/urls/) for information about which URLs to use. +**{{< cloud-name "short">}} requires HTTPS**. + +##### token +Your InfluxDB v2.0 authorization token. +For information about viewing tokens, see [View tokens](/influxdb/cloud/security/tokens/view-tokens/). + +{{% note %}} +###### Avoid storing tokens in `telegraf.conf` +We recommend storing your tokens by setting the `INFLUX_TOKEN` environment variable and including the environment variable in your configuration file. + +{{< tabs-wrapper >}} +{{% tabs %}} +[macOS or Linux](#) +[Windows](#) +{{% /tabs %}} + +{{% tab-content %}} +```sh +export INFLUX_TOKEN=YourAuthenticationToken +``` +{{% /tab-content %}} + +{{% tab-content %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[PowerShell](#) +[CMD](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} +```sh +$env:INFLUX_TOKEN = "YourAuthenticationToken" +``` +{{% /code-tab-content %}} + +{{% code-tab-content %}} +```sh +set INFLUX_TOKEN=YourAuthenticationToken +# Make sure to include a space character at the end of this command. +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +_See the [example `telegraf.conf` below](#example-influxdb_v2-configuration)._ +{{% /note %}} + +##### organization +The name of the organization that owns the target bucket. + +##### bucket +The name of the bucket to write data to. + +#### Example influxdb_v2 configuration +The example below illustrates an `influxdb_v2` configuration. + +```toml +# ... + +[[outputs.influxdb_v2]] + urls = ["https://cloud2.influxdata.com"] + token = "$INFLUX_TOKEN" + organization = "example-org" + bucket = "example-bucket" + +# ... +``` + +{{% note %}} +##### Write to InfluxDB v1.x and InfluxDB Cloud +If a Telegraf agent is already writing to an InfluxDB v1.x database, +enabling the InfluxDB v2 output plugin will write data to both v1.x and v2.0 instances. +{{% /note %}} + +## Add a custom Telegraf configuration to InfluxDB +To add a custom or manually configured Telegraf configuration to your collection +of Telegraf configurations in InfluxDB, use the [`influx telegrafs create`](/influxdb/cloud/reference/cli/influx/telegrafs/create/) +or [`influx telegrafs update`](/influxdb/cloud/reference/cli/influx/telegrafs/update/) commands. +For more information, see: + +- [Create a Telegraf configuration](/influxdb/cloud/telegraf-configs/create/#use-the-influx-cli) +- [Update a Telegraf configuration](/influxdb/cloud/telegraf-configs/update/#use-the-influx-cli) + +## Start Telegraf + +Start the Telegraf service using the `--config` flag to specify the location of your `telegraf.conf`. + +```sh +telegraf --config /path/to/custom/telegraf.conf +``` diff --git a/content/influxdb/cloud/write-data/no-code/use-telegraf/use-telegraf-plugins/_index.md b/content/influxdb/cloud/write-data/no-code/use-telegraf/use-telegraf-plugins/_index.md new file mode 100644 index 000000000..a38ee41cd --- /dev/null +++ b/content/influxdb/cloud/write-data/no-code/use-telegraf/use-telegraf-plugins/_index.md @@ -0,0 +1,16 @@ +--- +title: Use Telegraf plugins +description: > + Use Telegraf plugins to capture and write metrics to InfluxDB. +aliases: + - /influxdb/cloud/write-data/use-telegraf/use-telegraf-plugins/ +menu: + influxdb_cloud: + name: Use Telegraf plugins + parent: Telegraf (agent) +weight: 202 +--- + +The following articles guide you through step-by-step Telegraf configuration examples: + +{{< children >}} diff --git a/content/influxdb/cloud/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin.md b/content/influxdb/cloud/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin.md new file mode 100644 index 000000000..81e189300 --- /dev/null +++ b/content/influxdb/cloud/write-data/no-code/use-telegraf/use-telegraf-plugins/use-http-plugin.md @@ -0,0 +1,119 @@ +--- +title: Use the HTTP input plugin +seotitle: Use the Telegraf HTTP input plugin to write data to InfluxDB +list_title: HTTP input plugin +description: > + Write Citi Bike data to your InfluxDB instance with the HTTP plugin. +aliases: + - /influxdb/cloud/write-data/use-telegraf/use-telegraf-plugins/use-http-plugin/ +menu: + influxdb_cloud: + name: HTTP input plugin + parent: Use Telegraf plugins +weight: 202 +--- + +This example walks through using the Telegraf HTTP input plugin to collect live metrics on Citi Bike stations in New York City. Live station data is available in JSON format from [NYC OpenData](https://data.cityofnewyork.us/NYC-BigApps/Citi-Bike-Live-Station-Feed-JSON-/p94q-8hxh). + +Configure [`influxdb` output plugin](/{{< latest "telegraf" >}}/plugins//#influxdb) to write metrics to your InfluxDB instance. + +## Configure the HTTP Input plugin in your Telegraf configuration file + +To retrieve data from the Citi Bike URL endpoint, enable the `inputs.http` input plugin in your Telegraf configuration file. + +Specify the following options: + +### `urls` +One or more URLs to read metrics from. For this example, use `https://gbfs.citibikenyc.com/gbfs/en/station_status.json`. + +### `data_format` +The format of the data in the HTTP endpoints that Telegraf will ingest. For this example, use JSON. + + +## Add parser information to your Telegraf configuration + +Specify the following JSON-specific options. + +### JSON + +#### `json_query` +To parse only the relevant portion of JSON data, set the `json_query` option with a [GJSON](https://github.com/tidwall/gjson) path. The result of the query should contain a JSON object or an array of objects. +In this case, we don't want to parse the JSON query's `executionTime` at the beginning of the data, so we'll limit this to include only the data in the `stationBeanList` array. + +#### `tag_keys` +List of one or more JSON keys that should be added as tags. For this example, we'll use the tag keys `id`, `stationName`, `city`, and `postalCode`. + +#### `json_string_fields` +List the keys of fields that are in string format so that they can be parsed as strings. Here, the string fields are `statusValue`, `stAddress1`, `stAddress2`, `location`, and `landMark`. + +#### `json_time_key` +Key from the JSON file that creates the timestamp metric. In this case, we want to use the time that station data was last reported, or the `lastCommunicationTime`. If you don't specify a key, the time that Telegraf reads the data becomes the timestamp. + +#### `json_time_format` +The format used to interpret the designated `json_time_key`. This example uses [Go reference time format](https://golang.org/pkg/time/#Time.Format). For example, `Mon Jan 2 15:04:05 MST 2006`. + +#### `json_timezone` +The timezone We'll set this to the Unix TZ value where our bike data takes place, `America/New_York`. + + +#### Example configuration + + ```toml + [[inputs.http]] + #URL for NYC's Citi Bike station data in JSON format + urls = ["https://feeds.citibikenyc.com/stations/stations.json"] + + #Overwrite measurement name from default `http` to `citibikenyc` + name_override = "citibikenyc" + + #Exclude url and host items from tags + tagexclude = ["url", "host"] + + #Data from HTTP in JSON format + data_format = "json" + + #Parse `stationBeanList` array only + json_query = "stationBeanList" + + #Set station metadata as tags + tag_keys = ["id", "stationName", "city", "postalCode"] + + #Do not include station landmark data as fields + fielddrop = ["landMark"] + + #JSON values to set as string fields + json_string_fields = ["statusValue", "stAddress1", "stAddress2", "location", "landMark"] + + #Latest station information reported at `lastCommunicationTime` + json_time_key = "lastCommunicationTime" + + #Time is reported in Golang "reference time" format + json_time_format = "2006-01-02 03:04:05 PM" + + #Time is reported in Eastern Standard Time (EST) + json_timezone = "America/New_York" + ``` + + + +## Start Telegraf and verify data appears + +[Start the Telegraf service](/telegraf/v1.14/introduction/getting-started/). + +To test that the data is being sent to InfluxDB, run the following (replacing `telegraf.conf` with the path to your configuration file): + +``` +telegraf -config ~/telegraf.conf -test +``` + +This command should return line protocol that looks similar to the following: + + +``` +citibikenyc,id=3443,stationName=W\ 52\ St\ &\ 6\ Ave statusKey=1,location="",totalDocks=41,availableDocks=32,latitude=40.76132983124814,longitude=-73.97982001304626,availableBikes=8,stAddress2="",stAddress1="W 52 St & 6 Ave",statusValue="In Service" 1581533519000000000 +citibikenyc,id=367,stationName=E\ 53\ St\ &\ Lexington\ Ave availableBikes=8,stAddress1="E 53 St & Lexington Ave",longitude=-73.97069431,latitude=40.75828065,stAddress2="",statusKey=1,location="",statusValue="In Service",totalDocks=34,availableDocks=24 1581533492000000000 +citibikenyc,id=359,stationName=E\ 47\ St\ &\ Park\ Ave totalDocks=64,availableBikes=15,statusValue="In Service",location="",latitude=40.75510267,availableDocks=49,stAddress1="E 47 St & Park Ave",longitude=-73.97498696,statusKey=1,stAddress2="" 1581533535000000000 +citibikenyc,id=304,stationName=Broadway\ &\ Battery\ Pl statusValue="In Service",availableDocks=11,stAddress1="Broadway & Battery Pl",statusKey=1,stAddress2="",location="",totalDocks=33,latitude=40.70463334,longitude=-74.01361706,availableBikes=22 1581533499000000000 +``` + +Now, you can explore and query the Citi Bike data in InfluxDB. diff --git a/content/influxdb/v1.8/concepts/crosswalk.md b/content/influxdb/v1.8/concepts/crosswalk.md index 3214dcfec..b2603ccaf 100644 --- a/content/influxdb/v1.8/concepts/crosswalk.md +++ b/content/influxdb/v1.8/concepts/crosswalk.md @@ -127,8 +127,8 @@ For those familiar with [InfluxQL](#influxql), Flux is intended to address many of the outstanding feature requests that we've received since introducing InfluxDB 1.0. For a comparison between Flux and InfluxQL, see [Flux vs InfluxQL](/influxdb/v1.8/flux/flux-vs-influxql/). -Flux is the primary language for working with data in [InfluxDB 2.0 OSS](/influxdb/v2.0/get-started) -and [InfluxDB Cloud 2.0](/influxdb/v2.0/cloud/get-started/), +Flux is the primary language for working with data in [InfluxDB OSS 2.0](/influxdb/v2.0/get-started) +and [InfluxDB Cloud](/influxdb/cloud/get-started/), a generally available Platform as a Service (PaaS) available across multiple Cloud Service Providers. Using Flux with InfluxDB 1.8+ lets you get familiar with Flux concepts and syntax and ease the transition to InfluxDB 2.0. diff --git a/content/influxdb/v1.8/tools/api.md b/content/influxdb/v1.8/tools/api.md index 17b59c4a1..d6025eb7e 100644 --- a/content/influxdb/v1.8/tools/api.md +++ b/content/influxdb/v1.8/tools/api.md @@ -29,7 +29,7 @@ There are multiple reasons for introducing these: - The latest [InfluxDB client libraries](/influxdb/v1.8/tools/api_client_libraries/) are built for the InfluxDB 2.0 API, but now also work with **InfluxDB 1.8.0+**. -- InfluxDB Cloud 2.0 is a generally available service across multiple cloud service providers and regions +- InfluxDB Cloud is a generally available service across multiple cloud service providers and regions that is fully compatible with the **latest** client libraries. If you are just getting started with InfluxDB 1.x today, we recommend adopting diff --git a/content/influxdb/v1.8/tools/api_client_libraries.md b/content/influxdb/v1.8/tools/api_client_libraries.md index 0435e17c8..632816c12 100644 --- a/content/influxdb/v1.8/tools/api_client_libraries.md +++ b/content/influxdb/v1.8/tools/api_client_libraries.md @@ -15,7 +15,7 @@ v2: /influxdb/v2.0/tools/client-libraries/ InfluxDB client libraries are language-specific packages that integrate with the InfluxDB 2.0 API and support both **InfluxDB 1.8+** and **InfluxDB 2.0**. ->**Note:** We recommend using the new client libraries on this page to leverage the new read (via Flux) and write APIs and prepare for conversion to InfluxDB 2.0 and InfluxDB Cloud 2.0. For more information, see [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1.8/tools/api/#influxdb-2-0-api-compatibility-endpoints). Client libraries for [InfluxDB 1.7 and earlier](/influxdb/v1.7/tools/api_client_libraries/) may continue to work, but are not maintained by InfluxData. +>**Note:** We recommend using the new client libraries on this page to leverage the new read (via Flux) and write APIs and prepare for conversion to InfluxDB 2.0 and InfluxDB Cloud. For more information, see [InfluxDB 2.0 API compatibility endpoints](/influxdb/v1.8/tools/api/#influxdb-2-0-api-compatibility-endpoints). Client libraries for [InfluxDB 1.7 and earlier](/influxdb/v1.7/tools/api_client_libraries/) may continue to work, but are not maintained by InfluxData. ## Client libraries diff --git a/content/influxdb/v2.0/_index.md b/content/influxdb/v2.0/_index.md index daba3efdf..a13c49197 100644 --- a/content/influxdb/v2.0/_index.md +++ b/content/influxdb/v2.0/_index.md @@ -1,12 +1,12 @@ --- -title: InfluxDB v2.0 documentation +title: InfluxDB OSS 2.0 documentation description: > - InfluxDB is an open source time series database designed to handle high write and query loads. + InfluxDB OSS is an open source time series database designed to handle high write and query loads. Learn how to use and leverage InfluxDB in use cases such as monitoring metrics, IoT data, and events. layout: landing-influxdb menu: influxdb_2_0: - name: InfluxDB v2.0 + name: InfluxDB OSS 2.0 weight: 1 --- diff --git a/content/influxdb/v2.0/backup-restore/backup.md b/content/influxdb/v2.0/backup-restore/backup.md index 11ead8c66..bb0b9e40b 100644 --- a/content/influxdb/v2.0/backup-restore/backup.md +++ b/content/influxdb/v2.0/backup-restore/backup.md @@ -19,9 +19,9 @@ InfluxDB copies all data and metadata to a set of files stored in a specified di on your local filesystem. {{% warn %}} -#### InfluxDB 2.0rc (release candidate) +#### InfluxDB 2.0 (release candidate) -The `influx backup` command is not compatible with InfluxDB 2.0rc (release candidate). +The `influx backup` command is not compatible with InfluxDB 2.0 (release candidate). To back up data, 1. Stop `influxd`. @@ -31,7 +31,7 @@ To back up data, cp -r ~/.influxdbv2 ~/.influxdbv2_bak ``` -For more information, see [Upgrade to InfluxDB OSS 2.0rc](/influxdb/v2.0/reference/upgrading/rc-upgrade-guide/). +For more information, see [Upgrade to InfluxDB OSS 2.0](/influxdb/v2.0/upgrade/). {{% /warn %}} {{% cloud %}} @@ -47,10 +47,10 @@ The `influx backup` command requires: ##### Back up data with the influx CLI ```sh # Syntax -influx backup -p -t +influx backup -t # Example influx backup \ - -p path/to/backup_$(date '+%Y-%m-%d_%H-%M') \ + path/to/backup_$(date '+%Y-%m-%d_%H-%M') \ -t xXXXX0xXX0xxX0xx_x0XxXxXXXxxXX0XXX0XXxXxX0XxxxXX0Xx0xx== ``` diff --git a/content/influxdb/v2.0/backup-restore/restore.md b/content/influxdb/v2.0/backup-restore/restore.md index 6bd52cde3..a7b9640b7 100644 --- a/content/influxdb/v2.0/backup-restore/restore.md +++ b/content/influxdb/v2.0/backup-restore/restore.md @@ -14,11 +14,11 @@ related: products: [oss] --- -Use the `influxd restore` command to restore backup data and metadata from InfluxDB. +Use the `influx restore` command to restore backup data and metadata from InfluxDB. You must stop InfluxDB before restoring data. {{% cloud %}} -The `influxd restore` command only restores data to InfluxDB OSS, **not {{< cloud-name "short" >}}**. +The `influx restore` command only restores data to InfluxDB OSS, **not {{< cloud-name "short" >}}**. {{% /cloud %}} When restoring data from a backup file set, InfluxDB temporarily moves existing @@ -27,51 +27,25 @@ Once the process completes, the temporary data is deleted. If the restore process fails, InfluxDB preserves the data in the temporary location. _See [Recover from a failed restore](#recover-from-a-failed-restore)._ -## Restore data with the influxd CLI +## Restore data with the influx CLI 1. **Stop the `influxd` server.** -2. Use the `influxd restore` command and specify the path to the backup directory - using the `--backup-path` flag. +2. Use the `influx restore` command and specify the path to the backup directory in the first argument. ```sh # Syntax - influxd restore --backup-path + influxd restore # Example - influxd restore --backup-path ~/backups/2020-01-20_12-00/ + influxd restore ~/backups/2020-01-20_12-00/ ``` _For more information about restore options and flags, see the - [`influxd restore` documentation](/influxdb/v2.0/reference/cli/influxd/restore/)._ + [`influx restore` documentation](/influxdb/v2.0/reference/cli/influx/restore/)._ -## Customize the TSI rebuild process -By default, InfluxDB rebuilds the index and [series file](/influxdb/v2.0/reference/glossary/#series-file) when restoring data. -When rebuilding the Time Series Index (TSI), it uses the -[default `build-tsi` options](/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi/). -To customize the Time Series Index (TSI) rebuild process: - -1. Disable rebuilding the index and series files when restoring data: - - ```sh - influxd restore --rebuild-index false - ``` - -2. Manually run `influxd inspect build-tsi` with any - [custom options](/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi/#flags). - - ```sh - influxd inspect build-tsi \ - --max-log-file-size=1048576 \ - --max-cache-size=1073741824 - ``` - - {{% note %}} -Manually rebuild the TSI index to [adjust the performance](/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi/#adjust-performance) -of the TSI rebuild process. - {{% /note %}} ## Recover from a failed restore If the restoration process fails, InfluxDB preserves existing data in a `tmp` -directory in the [target engine path](/influxdb/v2.0/reference/cli/influxd/restore/#flags) +directory in the [target engine path](/influxdb/v2.0/reference/cli/influx/restore/#flags) (default is `~/.influxdbv2/engine`). To recover from a failed restore: diff --git a/content/influxdb/v2.0/get-started.md b/content/influxdb/v2.0/get-started.md index d1c0b543c..3a40db932 100644 --- a/content/influxdb/v2.0/get-started.md +++ b/content/influxdb/v2.0/get-started.md @@ -6,248 +6,14 @@ menu: name: Get started weight: 2 influxdb/v2.0/tags: [get-started, install] -aliases: - - /influxdb/v2.0/cloud/get-started --- The InfluxDB 2.0 time series platform is purpose-built to collect, store, process and visualize metrics and events. -Start with **InfluxDB Cloud 2.0**, a fully managed and hosted version of InfluxDB 2.0, -or **InfluxDB OSS 2.0**, the open source version of InfluxDB 2.0. - -
- Start with InfluxDB Cloud - Start with InfluxDB OSS -
- -_See [Differences between InfluxDB Cloud and InfluxDB OSS](#differences-between-influxdb-cloud-and-influxdb-oss)._ - ---- - -## Start with InfluxDB Cloud 2.0 - -### Start for free - -Start using {{< cloud-name >}} at no cost with the [Free Plan](/influxdb/v2.0/account-management/pricing-plans/#free-plan). -Use it as much and as long as you like within the plan's rate-limits. -Limits are designed to let you monitor 5-10 sensors, stacks or servers comfortably. - -### Sign up - -1. Choose one of the following: - - **Subscribe through InfluxData** - To subscribe to an InfluxDB Cloud 2.0 **Free Plan** through InfluxData, - go to [InfluxDB Cloud 2.0]({{< cloud-link >}}). - - - To use social sign-on, click **Continue with Google**. Note that Google social sign-on does not support email aliases. - - - Sign up with email by entering your name, email address, and password, then click **Create Account**. - - If you originally signed up with email but want to enable social sign-on, you can do so by logging in through Google as long as you use the same email address. - - - **Subscribe through a cloud provider** - To subscribe to an InfluxDB Cloud **Usage-Based** plan and pay through your - **Amazon Web Services (AWS)** or **Google Cloud Platform (GCP)** account: - - - **AWS** - Sign in to AWS, navigate to the [InfluxDB Cloud product on AWS Marketplace](https://aws.amazon.com/marketplace/pp/B08234JZPS), - and follow the prompts to subscribe. After you click **Set Up Your Account**, - enter your credentials, and then click **Start Now**. - All usage charges will be paid through the subscribed AWS account. - - - **GCP** - Sign in to GCP, navigate to the [InfluxDB Cloud product on GCP Marketplace](https://console.cloud.google.com/marketplace/details/influxdata-public/cloud2-gcp-marketplace-prod), - and follow the prompts to subscribe. After you click **Set Up Your Account**, - enter your credentials, and then click **Start Now**. - All usage charges will be paid through the subscribed GCP account. - - {{%note%}} -Currently, we do **not support** using an existing InfluxDB Cloud 2.0 account to sign up for an InfluxDB Cloud 2.0 plan through AWS or GCP Marketplaces. - {{%/note%}} - -2. If you signed up with your email address, InfluxDB Cloud requires email verification to complete the sign up process. - Verify your email address by opening the email sent to the address you provided and clicking **Verify Your Email**. -3. (If you subscribed through InfluxData) Choose your cloud provider. -4. Select a provider and region for your {{< cloud-name >}} instance. The following are available: - - {{< cloud_regions type="list" >}} - - _To suggest regions to add, click **Let us know** under Regions._ -5. (If you subscribed through InfluxData) Review the terms of the agreement, and then select **I have viewed and agree to InfluxDB Cloud 2.0 Services Subscription Agreement and InfluxData Global Data Processing Agreement**. - For details on the agreements, see the [InfluxDB Cloud 2.0: Services Subscription Agreement](https://www.influxdata.com/legal/terms-of-use/) and the [InfluxData Global Data Processing Agreement](https://www.influxdata.com/legal/influxdata-global-data-processing-agreement/). - -6. Click **Finish**. {{< cloud-name >}} opens with a default organization and bucket (both created from your email address). - - _To update organization and bucket names, see [Update an organization](/influxdb/v2.0/organizations/update-org/) - and [Update a bucket](/influxdb/v2.0/organizations/buckets/update-bucket/#update-a-bucket-s-name-in-the-influxdb-ui)._ - -{{% cloud %}} -All InfluxDB 2.0 documentation applies to {{< cloud-name "short" >}} unless otherwise specified. -References to the InfluxDB user interface (UI) or localhost:8086 refer to your -{{< cloud-name >}} UI. -{{% /cloud %}} - -### (Optional) Download, install, and use the influx CLI - -To use the `influx` CLI to manage and interact with your InfluxDB Cloud instance, complete the following steps: - -{{< tabs-wrapper >}} -{{% tabs %}} -[macOS](#) -[Linux](#) -{{% /tabs %}} - - -{{% tab-content %}} - -#### Step 1: Download influx CLI for macOS - -Click the following button to download and install `influx` CLI for macOS. - -influx CLI (macOS) - -#### Step 2: Unpackage the influx binary - -**Note:** The commands below are examples. Adjust the file names, paths, and utilities to your own needs. - -To unpackage the downloaded archive, **double click the archive file in Finder** -or run the following command in a macOS command prompt application such -**Terminal** or **[iTerm2](https://www.iterm2.com/)**: - -```sh -# Unpackage contents to the current working directory -tar zxvf ~/Downloads/influxdb-2.0.0-rc.3_darwin_amd64.tar.gz -``` - -#### Step 3: (Optional) Place the binary in your $PATH - -If you choose, you can place `influx` in your `$PATH` or you can -prefix the executable with `./` to run in place. If the binary is on your $PATH, you can run `influx` from any directory. Otherwise, you must specify the location of the CLI (for example, `./influx`or `path/to/influx`). - -**Note:** If you have the 1.x binary on your $PATH, moving the 2.0 binary to your $PATH will overwrite the 1.x binary because they have the same name. - -```sh -# Copy the influx binary to your $PATH -sudo cp influxdb-2.0.0-rc.3_darwin_amd64/influx /usr/local/bin/ -``` - -{{% note %}} -If you rename the binary, all references to `influx` in this documentation refer to the renamed binary. -{{% /note %}} - -#### Step 4: (macOS Catalina only) Authorize InfluxDB binaries - -If you're running `influx` on macOS Catalina, you must [manually authorize the InfluxDB binaries](/influxdb/v2.0/get-started/#run-influxdb-on-macos-catalina). - -#### Step 5: Set up a configuration profile - -To avoid having to pass your InfluxDB [authentication token](/influxdb/v2.0/security/tokens/) with each `influx` command, set up a configuration profile that stores your credentials. - -In a terminal, run the following command: - -```sh - # Set up a configuration profile - influx config create -n default \ - -u http://localhost:8086 \ - -o example-org \ - -t mySuP3rS3cr3tT0keN \ - -a - ``` - -This configures a new profile named `default` and makes the profile active so your `influx` CLI commands run against this instance. -For more detail, see [influx config](/influxdb/v2.0/reference/cli/influx/config/). - -#### Step 6: Learn `influx` CLI commands - -To see all available `influx` commands, type `influx -h` or check out [influx - InfluxDB command line interface](/influxdb/v2.0/reference/cli/influx/). - -{{% /tab-content %}} - - - -{{% tab-content %}} - -#### Step 1: Download influx CLI for Linux - -Download and install the `influx` CLI for Linux. - -influx CLI (amd64) - -#### Step 2: Unpackage the influx binary - -**Note:** The commands below are examples. Adjust the file names, paths, and utilities to your own needs. - -```sh -# Unpackage contents to the current working directory -tar xvfz influxdb_client_2.0.0-rc.3_linux_amd64.tar.gz -``` - -#### Step 3: (Optional) Place the binary in your $PATH - -If you choose, you can place `influx` in your `$PATH` or you can -prefix the executable with `./` to run in place. If the binary is on your $PATH, you can run `influx` from any directory. Otherwise, you must specify the location of the CLI (for example, `./influx`or `path/to/influx`). - -**Note:** If you have the 1.x binary on your $PATH, moving the 2.0 binary to your $PATH will overwrite the 1.x binary because they have the same name. - -```sh -# Copy the influx and influxd binary to your $PATH -sudo cp influxdb_client_2.0.0-rc.3_linux_amd64/influx /usr/local/bin/ -``` - -{{% note %}} -If you rename the binary, all references to `influx` in this documentation refer to the renamed binary. -{{% /note %}} - -#### Step 4: Set up a configuration profile - -To avoid having to pass your InfluxDB [authentication token](/influxdb/v2.0/security/tokens/) with each `influx` command, set up a configuration profile that stores your credentials. - -In a terminal, run the following command: - -```sh - # Set up a configuration profile - influx config create -n default \ - -u http://localhost:8086 \ - -o example-org \ - -t mySuP3rS3cr3tT0keN \ - -a - ``` - -This configures a new profile named `default` and makes the profile active so your `influx` CLI commands run against this instance. -For more detail, see [influx config](/influxdb/v2.0/reference/cli/influx/config/). - -#### Step 5: Learn `influx` CLI commands - -To see all available `influx` commands, type `influx -h` or check out [influx - InfluxDB command line interface](/influxdb/v2.0/reference/cli/influx/). - - -{{% /tab-content %}} - - -{{< /tabs-wrapper >}} - -### Sign in - -Sign in to [InfluxDB Cloud 2.0](https://cloud2.influxdata.com) using your email address and password. - -Sign in to InfluxDB Cloud 2.0 now - -### Start working with your time series data - -With {{< cloud-name "short" >}} setup, see [Next steps](#next-steps) for what to do next. - ---- - -## Start with InfluxDB OSS - Get started with InfluxDB OSS v2.0 by downloading InfluxDB, installing the necessary executables, and running the initial setup process. -{{% note %}} -To upgrade from InfluxDB 2.0 beta 16 or earlier to the latest version, see [Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0rc](/influxdb/v2.0/reference/upgrading/rc-upgrade-guide/). - -To upgrade to InfluxDB 2.0rc0 or later from InfluxDB 1.x, see [Upgrade from InfluxDB 1.x to InfluxDB 2.0](/influxdb/v2.0/reference/upgrading/influxd-upgrade-guide/). -{{% /note %}} +_See [Differences between InfluxDB Cloud and InfluxDB OSS](#differences-between-influxdb-cloud-and-influxdb-oss)._ {{< tabs-wrapper >}} {{% tabs %}} @@ -263,7 +29,38 @@ To upgrade to InfluxDB 2.0rc0 or later from InfluxDB 1.x, see [Upgrade from Infl Download InfluxDB v2.0 for macOS. -InfluxDB v2.0 (macOS) +InfluxDB v2.0 (macOS) + +### (Optional) Verify the authenticity of downloaded binary + +For added security, use `gpg` to verify the signature of your download. +(Most operating systems include the `gpg` command by default. +If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/) for installation instructions.) + +1. Download and import InfluxData's public key: + + ``` + curl -s https://repos.influxdata.com/influxdb2.key | gpg --import - + ``` + +2. Download the signature file for the release by adding `.asc` to the download URL. + For example: + + ``` + wget https://dl.influxdata.com/influxdb/releases/influxdb-2.0.1-darwin_amd64.tar.gz.asc + ``` + +3. Verify the signature with `gpg --verify`: + + ``` + gpg --verify influxdb-2.0.1-darwin_amd64.tar.gz.asc influxdb-2.0.1-darwin_amd64.tar.gz + ``` + + The output from this command should include the following: + + ``` + gpg: Good signature from "InfluxData " [unknown] + ``` ### Unpackage the InfluxDB binaries @@ -273,7 +70,7 @@ or run the following command in a macOS command prompt application such ```sh # Unpackage contents to the current working directory -tar zxvf ~/Downloads/influxdb-2.0.0-rc.3_darwin_amd64.tar.gz +tar zxvf ~/Downloads/influxdb-2.0.1_darwin_amd64.tar.gz ``` #### (Optional) Place the binaries in your $PATH @@ -283,7 +80,7 @@ prefix the executables with `./` to run then in place. ```sh # (Optional) Copy the influx and influxd binary to your $PATH -sudo cp influxdb-2.0.0-rc.3_darwin_amd64/{influx,influxd} /usr/local/bin/ +sudo cp influxdb-2.0.1_darwin_amd64/{influx,influxd} /usr/local/bin/ ``` {{% note %}} @@ -352,7 +149,38 @@ influxd --reporting-disabled Download InfluxDB v2.0 for Linux. -InfluxDB v2.0 (amd64) +InfluxDB v2.0 (amd64) + +### (Optional) Verify the authenticity of downloaded binary + +For added security, use `gpg` to verify the signature of your download. +(Most operating systems include the `gpg` command by default. +If `gpg` is not available, see the [GnuPG homepage](https://gnupg.org/download/) for installation instructions.) + +1. Download and import InfluxData's public key: + + ``` + curl -s https://repos.influxdata.com/influxdb2.key | gpg --import - + ``` + +2. Download the signature file for the release by adding `.asc` to the download URL. + For example: + + ``` + wget https://dl.influxdata.com/influxdb/releases/influxdb-2.0.1-linux_amd64.tar.gz.asc + ``` + +3. Verify the signature with `gpg --verify`: + + ``` + gpg --verify influxdb-2.0.1-linux_amd64.tar.gz.asc influxdb-2.0.1-linux_amd64.tar.gz + ``` + + The output from this command should include the following: + + ``` + gpg: Good signature from "InfluxData " [unknown] + ``` ### Place the executables in your $PATH @@ -362,10 +190,10 @@ _**Note:** The following commands are examples. Adjust the file names, paths, an ```sh # Unpackage contents to the current working directory -tar xvzf path/to/influxdb-2.0.0-rc.3_linux_amd64.tar.gz +tar xvzf path/to/influxdb-2.0.1_linux_amd64.tar.gz # Copy the influx and influxd binary to your $PATH -sudo cp influxdb-2.0.0-rc.3_linux_amd64/{influx,influxd} /usr/local/bin/ +sudo cp influxdb-2.0.1_linux_amd64/{influx,influxd} /usr/local/bin/ ``` {{% note %}} @@ -437,7 +265,7 @@ To opt-out of sending telemetry data back to InfluxData, include the `--reporting-disabled` flag when starting the InfluxDB container. ```bash -docker run -p 8086:8086 quay.io/influxdb/influxdb:2.0.0-rc --reporting-disabled +docker run -p 8086:8086 quay.io/influxdb/influxdb:2.0.1-rc --reporting-disabled ``` {{% /note %}} @@ -593,8 +421,6 @@ to provide the required information. {{< /tabs-wrapper >}} ---- - ## Next Steps ### Collect and write data @@ -621,10 +447,6 @@ For details, see [Scrape data](/influxdb/v2.0/write-data/no-code/scrape-data/). For information about using the InfluxDB v2 API, `influx` CLI, and client libraries to write data, see [Write data to InfluxDB](/influxdb/v2.0/write-data/). -#### Demo data -If using **{{< cloud-name "short" >}}**, [add a demo data bucket](/influxdb/v2.0/reference/sample-data/#influxdb-cloud-demo-data) -for quick, **free** access to time series data. - ### Query data Query data using Flux, the UI, and the `influx` command line interface. @@ -647,13 +469,13 @@ See [Monitor and alert](/influxdb/v2.0/monitor-alert/). ## Differences between InfluxDB Cloud and InfluxDB OSS {{< cloud-name >}} is API-compatible and functionally compatible with InfluxDB OSS 2.0. -The primary differences between InfluxDB OSS 2.0 and InfluxDB Cloud 2.0 are: +The primary differences between InfluxDB OSS 2.0 and InfluxDB Cloud are: - [InfluxDB scrapers](/influxdb/v2.0/write-data/no-code/scrape-data/) that collect data from specified targets are not available in {{< cloud-name "short" >}}. - {{< cloud-name "short" >}} instances are currently limited to a single organization. -#### New features in InfluxDB Cloud 2.0 +#### New features in InfluxDB Cloud - **Free Plan (rate-limited)**: Skip downloading and installing InfluxDB 2.0 and jump into exploring InfluxDB 2.0 technology. @@ -668,5 +490,5 @@ The primary differences between InfluxDB OSS 2.0 and InfluxDB Cloud 2.0 are: - **Integrated visualization and dashboards**: Based on the pioneering Chronograf project, the new user interface (InfluxDB UI) offers quick and effortless onboarding, richer user experiences, and significantly quicker results. -- **Usage-based pricing**: The [Usage-based Plan](/influxdb/v2.0/account-management/pricing-plans/#usage-based-plan) +- **Usage-based pricing**: The [Usage-based Plan](/influxdb/cloud/account-management/pricing-plans/#usage-based-plan) offers more flexibility and ensures that you only pay for what you use. diff --git a/content/influxdb/v2.0/influxdb-templates/create.md b/content/influxdb/v2.0/influxdb-templates/create.md index 236c8487c..a0f70bb2d 100644 --- a/content/influxdb/v2.0/influxdb-templates/create.md +++ b/content/influxdb/v2.0/influxdb-templates/create.md @@ -25,11 +25,6 @@ UI and export the resources as a template. Templatable resources are scoped to a single organization, so the simplest way to create a template is to create a new organization, build the template within the organization, and then [export all resources](#export-all-resources) as a template. - -**InfluxDB OSS** supports multiple organizations so you can create new organizations -for the sole purpose of building and maintaining a template. -In **InfluxDB Cloud**, your user account is an organization. -**We recommend using InfluxDB OSS to create InfluxDB templates.** {{% /note %}} **To create a template:** diff --git a/content/influxdb/v2.0/monitor-alert/notification-endpoints/_index.md b/content/influxdb/v2.0/monitor-alert/notification-endpoints/_index.md index ad9e870b7..863dd1fbe 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-endpoints/_index.md +++ b/content/influxdb/v2.0/monitor-alert/notification-endpoints/_index.md @@ -14,7 +14,6 @@ related: --- Notification endpoints store information to connect to a third party service. -If you're using the Free Plan, create a Slack endpoint. -If you're using the Usage-based Plan, create a connection to a HTTP, Slack, or PagerDuty endpoint. +Create a connection to a HTTP, Slack, or PagerDuty endpoint. {{< children >}} diff --git a/content/influxdb/v2.0/monitor-alert/notification-endpoints/create.md b/content/influxdb/v2.0/monitor-alert/notification-endpoints/create.md index ad4fa83f7..5cc14c495 100644 --- a/content/influxdb/v2.0/monitor-alert/notification-endpoints/create.md +++ b/content/influxdb/v2.0/monitor-alert/notification-endpoints/create.md @@ -22,16 +22,7 @@ To send notifications about changes in your data, start by creating a notificati 2. Select **Notification Endpoints** near to top of the page. 3. Click **{{< icon "plus" >}} Create**. -4. From the **Destination** drop-down list, select a destination endpoint to send notifications. - The following endpoints are available for InfluxDB 2.0 OSS, the InfluxDB Cloud 2.0 Free Plan, - and the InfluxDB Cloud 2.0 Usage-based Plan: - - | Endpoint | OSS | Free Plan _(Cloud)_ | Usage-based Plan _(Cloud)_ | - |:-------- |:--------: |:-------------------: |:----------------------------:| - | **Slack** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | - | **PagerDuty** | **{{< icon "check" >}}** | | **{{< icon "check" >}}** | - | **HTTP** | **{{< icon "check" >}}** | | **{{< icon "check" >}}** | - +4. From the **Destination** drop-down list, select a destination endpoint to send notifications 5. In the **Name** and **Description** fields, enter a name and description for the endpoint. 6. Enter enter information to connect to the endpoint: diff --git a/content/influxdb/v2.0/organizations/buckets/view-buckets.md b/content/influxdb/v2.0/organizations/buckets/view-buckets.md index 4f1fa9b1a..0737decb8 100644 --- a/content/influxdb/v2.0/organizations/buckets/view-buckets.md +++ b/content/influxdb/v2.0/organizations/buckets/view-buckets.md @@ -9,9 +9,7 @@ menu: weight: 202 --- -## View a list of buckets - -### View buckets in the InfluxDB UI +## View buckets in the InfluxDB UI 1. In the navigation menu on the left, select **Data (Load Data)** > **Buckets**. @@ -22,7 +20,7 @@ weight: 202 2. Click a bucket to open it in the **Data Explorer**. 3. Click the bucket ID to copy it to the clipboard. -### View buckets using the influx CLI +## View buckets using the influx CLI Use the [`influx bucket list` command](/influxdb/v2.0/reference/cli/influx/bucket/list) to view a buckets in an organization. diff --git a/content/influxdb/v2.0/organizations/create-org.md b/content/influxdb/v2.0/organizations/create-org.md index fcad542da..bc3055929 100644 --- a/content/influxdb/v2.0/organizations/create-org.md +++ b/content/influxdb/v2.0/organizations/create-org.md @@ -13,11 +13,6 @@ products: [oss] Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) to create an organization. -{{% cloud %}} -You cannot currently create additional organizations in {{< cloud-name >}}. -Only the default organization is available. -{{% /cloud %}} - ## Create an organization in the InfluxDB UI 1. In the navigation menu on the left, click the **Account dropdown**. diff --git a/content/influxdb/v2.0/organizations/members/add-member.md b/content/influxdb/v2.0/organizations/members/add-member.md index ce25c9192..f3b0b1669 100644 --- a/content/influxdb/v2.0/organizations/members/add-member.md +++ b/content/influxdb/v2.0/organizations/members/add-member.md @@ -11,10 +11,6 @@ weight: 201 Use the `influx` command line interface (CLI) to add a member to an organization. -{{% cloud %}} -To manage members of an organization in {{< cloud-name >}}, see [Manage multiple users](/influxdb/v2.0/account-management/multi-user/). -{{% /cloud %}} - +##### View all DBRP mappings ```sh -curl --request GET https://cloud2.influxdata.com/api/v2/dbrps \ +curl --request GET \ + http://localhost:8086/api/v2/dbrps \ --header "Authorization: Token YourAuthToken" \ - --header 'Content-type: application/json' \ - --data '{ - "bucket_id": "12ab34cd56ef", - "database": "example-db", - "id": "example-mapping-id" - "default": true - "organization_id": "example-org", - }' + --header "Content-type: application/json" \ + --data-urlencode "orgID=example-org" +``` + +##### Filter DBRP mappings by database +```sh +curl --request GET \ + http://localhost:8086/api/v2/dbrps \ + --header "Authorization: Token YourAuthToken" \ + --header "Content-type: application/json" \ + --data-urlencode "orgID=example-org" \ + --data-urlencode "db=example-db" ``` If you **do not find a mapping ID (`id`) for a bucket**, complete the next procedure to map the unmapped bucket. @@ -62,15 +69,15 @@ To map an unmapped bucket to a database and retention policy, use the [`POST /db - database and retention policy to map to bucket (`database` and `retention_policy`) ```sh -curl --request POST https://cloud2.influxdata.com/api/v2/dbrps \ +curl --request POST http://localhost:8086/api/v2/dbrps \ --header "Authorization: Token YourAuthToken" \ --header 'Content-type: application/json' \ --data '{ - "bucket_id": "12ab34cd56ef", + "bucketID": "12ab34cd56ef", "database": "example-db", - "default": true + "default": true, "organization": "example-org", - "organization_id": "example-org", + "organizationID": "example-org-id", "retention_policy": "example-rp", }' ``` @@ -80,7 +87,7 @@ After you've verified the bucket is mapped, query the bucket using the `query` 1 ## Query a mapped bucket with InfluxQL The [InfluxDB 1.x compatibility API](/influxdb/v2.0/reference/api/influxdb-1x/) supports -all InfluxDB 1.x client libraries and integrations in InfluxDB 2.0. +all InfluxDB 1.x client libraries and integrations in InfluxDB Cloud and InfluxDB OSS 2.0. To query a mapped bucket with InfluxQL, use the `/query` 1.x compatibility endpoint (see CURL example below), and include the following in your request: @@ -95,8 +102,9 @@ To query a mapped bucket with InfluxQL, use the `/query` 1.x compatibility endpo {{% /note %}} ```sh -curl --request GET https://cloud2.influxdata.com/query?database=MyDB&retention_policy=MyRP \ +curl --request GET http://localhost:8086/query \ --header "Authorization: Token YourAuthToken" \ + --data-urlencode "db=example-db" \ --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1" ``` @@ -105,13 +113,12 @@ To return results as **CSV**, include the `Accept: application/csv` header. ## InfluxQL support -InfluxDB 2.0 supports InfluxQL **read-only** queries. See supported and unsupported queries below. +InfluxDB Cloud and InfluxDB OSS 2.0 support InfluxQL **read-only** queries. See supported and unsupported queries below. To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/influxdb/v1.8/query_language/). {{< flex >}} {{< flex-content >}} {{% note %}} - ##### Supported InfluxQL queries - `DELETE`* @@ -134,7 +141,6 @@ To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/influxdb/v - `SELECT INTO` - `ALTER` - `CREATE` - - `DROP` (see above) - `GRANT` - `KILL` diff --git a/content/influxdb/v2.0/query-data/optimize-queries.md b/content/influxdb/v2.0/query-data/optimize-queries.md index 3a06d0ad2..d5ab5ab6e 100644 --- a/content/influxdb/v2.0/query-data/optimize-queries.md +++ b/content/influxdb/v2.0/query-data/optimize-queries.md @@ -26,11 +26,11 @@ reduce the amount of memory necessary to run a query. #### Pushdown functions - [range()](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/range/) - [filter()](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/filter/) -- [group()](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/group/) + Use pushdown functions at the beginning of your query. Once a non-pushdown function runs, Flux pulls data into memory and runs all @@ -41,10 +41,10 @@ subsequent operations there. from(bucket: "example-bucket") |> range(start: -1h) // |> filter(fn: (r) => r.sensor == "abc123") // Pushed to the data source - |> group(columns: ["_field", "host"]) // - |> aggregateWindow(every: 5m, fn: max) // - |> filter(fn: (r) => r._value >= 90.0) // Run in memory + |> group(columns: ["_field", "host"]) // + |> aggregateWindow(every: 5m, fn: max) // Run in memory + |> filter(fn: (r) => r._value >= 90.0) // |> top(n: 10) // ``` diff --git a/content/influxdb/v2.0/reference/api/_index.md b/content/influxdb/v2.0/reference/api/_index.md index 415bbf16f..ecb2dbc25 100644 --- a/content/influxdb/v2.0/reference/api/_index.md +++ b/content/influxdb/v2.0/reference/api/_index.md @@ -16,20 +16,28 @@ InfluxDB uses [authentication tokens](/influxdb/v2.0/security/tokens/) to author Include your authentication token as an `Authorization` header in each request. ```sh -curl --request POST \ - http://localhost:8086/api/v2/write?org=my-org&bucket=example-bucket \ - --header "Authorization: Token YOURAUTHTOKEN" +curl --request POST http://localhost:8086/api/v2/write \ + --header "Authorization: Token YOURAUTHTOKEN" \ + --data-urlencode "org=myorg" \ + --data-urlencode "bucket=example-bucket" ``` -## View InfluxDB v2 API Documentation -InfluxDB v2.0 API documentation +## InfluxDB v2 API Documentation +InfluxDB OSS 2.0 API documentation -### View InfluxDB API documentation locally +#### View InfluxDB API documentation locally InfluxDB API documentation is built into the `influxd` service and represents the API specific to the current version of InfluxDB. To view the API documentation locally, [start InfluxDB](/influxdb/v2.0/get-started/#start-influxdb) and visit the `/docs` endpoint in a browser ([localhost:8086/docs](http://localhost:8086/docs)). +## InfluxDB v1 compatibility API documentation +The InfluxDB v2 API includes [InfluxDB 1.x compatibility endpoints](/influxdb/v2.0/reference/api/influxdb-1x/) +that work with InfluxDB 1.x client libraries and third-party integrations like +[Grafana](https://grafana.com) and others. + +View full v1 compatibility API documentation + ## InfluxDB client libraries InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. For information about supported client libraries, see [InfluxDB client libraries](/influxdb/v2.0/tools/client-libraries/). diff --git a/content/influxdb/v2.0/reference/api/influxdb-1x/_index.md b/content/influxdb/v2.0/reference/api/influxdb-1x/_index.md index add65ca8a..0cc46e392 100644 --- a/content/influxdb/v2.0/reference/api/influxdb-1x/_index.md +++ b/content/influxdb/v2.0/reference/api/influxdb-1x/_index.md @@ -1,7 +1,8 @@ --- title: InfluxDB 1.x compatibility API description: > - placeholder + The InfluxDB v2 API includes InfluxDB 1.x compatibility endpoints that work with + InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. menu: influxdb_2_0_ref: name: 1.x compatibility @@ -15,6 +16,8 @@ related: The InfluxDB v2 API includes InfluxDB 1.x compatibility endpoints that work with InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. +View full v1 compatibility API documentation + ## Authentication InfluxDB 2.0 requires all query and write requests to be authenticated. Use **basic authentication** or **token authentication** to authenticate requests to @@ -61,7 +64,7 @@ Authorization: Token mYSuP3rs3cREtT0k3N The compatibility API supports InfluxQL, with the following caveats: - The `INTO` clause (e.g. `SELECT ... INTO ...`) is not supported. -- With the exception of [`DELETE`](/influxdb/v1.8/query_language/manage-database/#delete-series-with-delete) and +- With the exception of [`DELETE`](/influxdb/v1.8/query_language/manage-database/#delete-series-with-delete) and [`DROP MEASUREMENT`](/influxdb/v1.8/query_language/manage-database/#delete-measurements-with-drop-measurement) queries, which are still allowed, InfluxQL database management commands are not supported. diff --git a/content/influxdb/v2.0/reference/api/influxdb-1x/dbrp.md b/content/influxdb/v2.0/reference/api/influxdb-1x/dbrp.md index cc099059b..e330cb686 100644 --- a/content/influxdb/v2.0/reference/api/influxdb-1x/dbrp.md +++ b/content/influxdb/v2.0/reference/api/influxdb-1x/dbrp.md @@ -2,7 +2,7 @@ title: Database and retention policy mapping description: > The database and retention policy (DBRP) mapping service maps InfluxDB 1.x - database and retention policy combinations to InfluxDB 2.0 buckets. + database and retention policy combinations to InfluxDB Cloud and InfluxDB OSS 2.0 buckets. menu: influxdb_2_0_ref: name: DBRP mapping @@ -11,13 +11,13 @@ weight: 302 related: - /influxdb/v2.0/reference/api/influxdb-1x/query - /influxdb/v2.0/reference/api/influxdb-1x/write - - /influxdb/v2.0/api/#tag/DBRPs, InfluxDB 2.0 API /dbrps endpoint + - /influxdb/v2.0/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint --- The InfluxDB 1.x data model includes [databases](/influxdb/v1.8/concepts/glossary/#database) and [retention policies](/influxdb/v1.8/concepts/glossary/#retention-policy-rp). -InfluxDB 2.0 replaces both with [buckets](/influxdb/v2.0/reference/glossary/#bucket). -To support InfluxDB 1.x query and write patterns in InfluxDB 2.0, databases and retention +InfluxDB Cloud and InfluxDB OSS 2.0 replace both with [buckets](/influxdb/v2.0/reference/glossary/#bucket). +To support InfluxDB 1.x query and write patterns in InfluxDB Cloud and InfluxDB OSS 2.0, databases and retention policies are mapped to buckets using the **database and retention policy (DBRP) mapping service**. The DBRP mapping service uses the **database** and **retention policy** specified in @@ -25,7 +25,7 @@ The DBRP mapping service uses the **database** and **retention policy** specifie {{% note %}} To query data in InfluxQL that was written using the 2.x `/write` API, you must manually create a DBRP mapping to map a bucket to a database and retention policy. -For more information, see [Map unmapped buckets](/influxdb/v2.0/query-data/influxql/#manually-create-and-manage-dbrp-mappings). +For more information, see [Map unmapped buckets](/influxdb/v2.0/query-data/influxql/#map-unmapped-buckets). {{% /note %}} ### Default retention policies @@ -36,7 +36,8 @@ the default retention policy for the specified database. ### When writing data -When writing data to InfluxDB 2.0 using the [`/write` compatibility endpoint](/influxdb/v2.0/reference/api/influxdb-1x/write/), +When writing data to InfluxDB Cloud and InfluxDB OSS 2.0 using the +[`/write` compatibility endpoint](/influxdb/v2.0/reference/api/influxdb-1x/write/), the DBRP mapping service checks for a bucket mapped to the database and retention policy: - If a mapped bucket is found, data is written to the bucket. @@ -57,11 +58,12 @@ write request must be an **All Access token**. ### When querying data -When querying data from InfluxDB 2.0 using the [`/query` compatibility endpoint](/influxdb/v2.0/reference/api/influxdb-1x/query/), +When querying data from InfluxDB Cloud and InfluxDB OSS 2.0 using the +[`/query` compatibility endpoint](/influxdb/v2.0/reference/api/influxdb-1x/query/), the DBRP mapping service checks for the specified database and retention policy (if no retention policy is specified, the database's default retention policy is used): - If a mapped bucket exists, data is queried from the mapped bucket. -- If no mapped bucket exists, InfluxDB returns an error. See how to [Map unmapped buckets](/influxdb/v2.0/query-data/influxql/#manually-create-and-manage-dbrp-mappings). +- If no mapped bucket exists, InfluxDB returns an error. See how to [Map unmapped buckets](/influxdb/v2.0/query-data/influxql/#map-unmapped-buckets). _For more information on the DBRP mapping API, see the [`/api/v2/dbrps` endpoint documentation](/influxdb/v2.0/api/#tag/DBRPs)._ diff --git a/content/influxdb/v2.0/reference/api/influxdb-1x/query.md b/content/influxdb/v2.0/reference/api/influxdb-1x/query.md index 0bcbafb1a..de5066ab0 100644 --- a/content/influxdb/v2.0/reference/api/influxdb-1x/query.md +++ b/content/influxdb/v2.0/reference/api/influxdb-1x/query.md @@ -2,7 +2,7 @@ title: /query 1.x compatibility API list_title: /query description: > - The `/query` 1.x compatibility endpoint queries InfluxDB 2.0 using **InfluxQL**. + The `/query` 1.x compatibility endpoint queries InfluxDB Cloud and InfluxDB OSS 2.0 using **InfluxQL**. menu: influxdb_2_0_ref: name: /query @@ -17,7 +17,7 @@ related: - /influxdb/v2.0/query-data/influxql --- -The `/query` 1.x compatibility endpoint queries InfluxDB 2.0 using **InfluxQL**. +The `/query` 1.x compatibility endpoint queries InfluxDB Cloud and InfluxDB OSS 2.0 using **InfluxQL**. Use the `GET` request method to query data from the `/query` endpoint. 
@@ -25,12 +25,12 @@ Use the `GET` request method to query data from the `/query` endpoint.
The `/query` compatibility endpoint use the **database** and **retention policy** -specified in the query request to map the request to an InfluxDB 2.0 bucket. +specified in the query request to map the request to an InfluxDB bucket. For more information, see [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp). {{% note %}} If you have an existing bucket that does't follow the **database/retention-policy** naming convention, -you **must** [manually create a database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/#manually-create-and-manage-dbrp-mappings) +you **must** [manually create a database and retention policy mapping](/influxdb/v2.0/query-data/influxql/#map-unmapped-buckets) to query that bucket with the `/query` compatibility API. {{% /note %}} @@ -46,12 +46,12 @@ _For more information, see [Authentication](/influxdb/v2.0/reference/api/influxd ### db Required – The **database** to query data from. -This is mapped to an InfluxDB 2.0 [bucket](/influxdb/v2.0/reference/glossary/#bucket). +This is mapped to an InfluxDB [bucket](/influxdb/v2.0/reference/glossary/#bucket). _See [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/)._ ### rp The **retention policy** to query data from. -This is mapped to an InfluxDB 2.0 [bucket](/influxdb/v2.0/reference/glossary/#bucket). +This is mapped to an InfluxDB [bucket](/influxdb/v2.0/reference/glossary/#bucket). _See [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/)._ ### q diff --git a/content/influxdb/v2.0/reference/api/influxdb-1x/write.md b/content/influxdb/v2.0/reference/api/influxdb-1x/write.md index 130f47da0..1bdf4feeb 100644 --- a/content/influxdb/v2.0/reference/api/influxdb-1x/write.md +++ b/content/influxdb/v2.0/reference/api/influxdb-1x/write.md @@ -2,8 +2,8 @@ title: /write 1.x compatibility API list_title: /write description: > - The `/write` 1.x compatibility endpoint writes data to InfluxDB 2.0 using patterns from the - InfluxDB 1.x `/write` API endpoint. + The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud and + InfluxDB OSS 2.0 using patterns from the InfluxDB 1.x `/write` API endpoint. menu: influxdb_2_0_ref: name: /write @@ -18,8 +18,8 @@ related: - /influxdb/v2.0/reference/syntax/line-protocol --- -The `/write` 1.x compatibility endpoint writes data to InfluxDB 2.0 using patterns from the -InfluxDB 1.x `/write` API endpoint. +The `/write` 1.x compatibility endpoint writes data to InfluxDB Cloud and InfluxDB OSS 2.0 +using patterns from the InfluxDB 1.x `/write` API endpoint. Use the `POST` request method to write [line protocol](/influxdb/v2.0/reference/syntax/line-protocol/) to the `/write` endpoint. @@ -41,12 +41,12 @@ encode the line protocol. ### db Required – The **database** to write data to. -This is mapped to an InfluxDB 2.0 [bucket](/influxdb/v2.0/reference/glossary/#bucket). +This is mapped to an InfluxDB [bucket](/influxdb/v2.0/reference/glossary/#bucket). _See [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/)._ ### rp The **retention policy** to write data to. -This is mapped to an InfluxDB 2.0 [bucket](/influxdb/v2.0/reference/glossary/#bucket). +This is mapped to an InfluxDB [bucket](/influxdb/v2.0/reference/glossary/#bucket). _See [Database and retention policy mapping](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/)._ ### precision diff --git a/content/influxdb/v2.0/reference/cli/influx/backup/_index.md b/content/influxdb/v2.0/reference/cli/influx/backup/_index.md index f03daec5f..2859f305f 100644 --- a/content/influxdb/v2.0/reference/cli/influx/backup/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/backup/_index.md @@ -19,12 +19,12 @@ influx backup [flags] ``` ## Flags -| Flag | | Description | Input type | {{< cli/mapped >}} | -|:---- |:--- |:----------- |:----------:|:------------------ | -| `-c` | `--active-config` | CLI configuration to use for command | string | | -| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string |`INFLUX_CONFIGS_PATH` | -| `-h` | `--help` | Help for the `backup` command | | | -| | `--host` | HTTP address of InfluxDB (default `http://localhost:8086`) | string | `INFLUX_HOST` | -| `-p` | `--path` | Directory path to write backup files to | string | `INFLUX_PATH` | -| | `--skip-verify` | Skip TLS certificate verification | | | -| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` | +| Flag | | Description | Input type | {{< cli/mapped >}} | +|------|-------------------|-------------------------------------------------------------|------------|--------------------| +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--bucket-id` | ID of the bucket to back up from | string | | +| `-b` | `--bucket` | Name of the bucket to back up from | string | | +| `-h` | `--help` | Help for the `backup` command | | | +| | `--host` | HTTP address of InfluxDB (default: `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--skip-verify` | Skip TLS certificate verification | string | | +| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` | diff --git a/content/influxdb/v2.0/reference/cli/influx/restore/index.md b/content/influxdb/v2.0/reference/cli/influx/restore/index.md new file mode 100644 index 000000000..26623c27e --- /dev/null +++ b/content/influxdb/v2.0/reference/cli/influx/restore/index.md @@ -0,0 +1,47 @@ +--- +title: influx restore +description: The `influx restore` command restores backup data and metadata from an InfluxDB backup directory. +influxdb/v2.0/tags: [restore] +menu: + influxdb_2_0_ref: + parent: influx +weight: 201 +alias: + - /influxdb/v2.0/reference/cli/influxd/restore/ +related: + - /influxdb/v2.0/backup-restore/restore/ +--- + +The `influx restore` command restores backup data and metadata from an InfluxDB backup directory. + +{{% warn %}} +Shut down the `influxd` server before restoring data. +{{% /warn %}} + +### The restore process +When restoring data from a backup file set, InfluxDB temporarily moves existing +data and metadata while `restore` runs. +After `restore` completes, the temporary data is deleted. +If the restore process fails, InfluxDB preserves the data in the temporary location. + +_For information about recovering from a failed restore process, see +[Restore data](/influxdb/v2.0/backup-restore/restore/#recover-from-a-failed-restore)._ + + +## Usage + +``` +influxd restore [flags] +``` + +## Flags + +| Flag | | Description | Input type | +|------|----------------|----------------------------------------------|------------| +| | `--bucket-id` | ID of the bucket to restore from | string | +| `-b` | `--bucket` | Name of the bucket to restore from | string | +| | `--full` | Fully restore and replace all data on server | | +| | `--new-bucket` | Name of the bucket to restore to | string | +| | `--new-org` | Name of the organization to restore to | string | +| | `--org-id` | ID of the org to restore from | string | +| `-o` | `--org` | Name of the org to restore from | string | diff --git a/content/influxdb/v2.0/reference/cli/influxd/_index.md b/content/influxdb/v2.0/reference/cli/influxd/_index.md index b8394a0f1..49e590c7b 100644 --- a/content/influxdb/v2.0/reference/cli/influxd/_index.md +++ b/content/influxdb/v2.0/reference/cli/influxd/_index.md @@ -32,7 +32,6 @@ For information about other available InfluxDB configuration methods, see |:----------------------------------------------------------|:-------------------------------------------------| | [generate](/influxdb/v2.0/reference/cli/influxd/generate) | Generate time series data sets using TOML schema | | [inspect](/influxdb/v2.0/reference/cli/influxd/inspect) | Inspect on-disk database data | -| [restore](/influxdb/v2.0/reference/cli/influxd/restore) | Restore data and metadata from a backup file set | | [run](/influxdb/v2.0/reference/cli/influxd/run) | Start the influxd server _**(default)**_ | | [upgrade](/influxdb/v2.0/reference/cli/influxd/upgrade) | Upgrade a 1.x version of InfluxDB to 2.0 | | [version](/influxdb/v2.0/reference/cli/influxd/version) | Output the current version of InfluxDB | diff --git a/content/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi.md b/content/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi.md index b23e93b0f..cdd6cfae4 100644 --- a/content/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi.md +++ b/content/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi.md @@ -47,11 +47,11 @@ higher memory usage. ## Flags | Flag | | Description | Input Type | |:---- |:--- |:----------- |:----------:| -| | `--batch-size` | The size of the batches to write to the index. Defaults to `10000`. [See above](#batch-size). | integer | +| | `--batch-size` | The size of the batches to write to the index. Defaults to `10000`. [See above](#--batch-size). | integer | | | `--concurrency` | Number of workers to dedicate to shard index building. Defaults to `GOMAXPROCS` (8 by default). | integer | | `-h` | `--help` | Help for the `build-tsi` command. | | -| | `--max-cache-size` | Maximum cache size. Defaults to `1073741824`. [See above](#max-cache-size). | uinteger | -| | `--max-log-file-size` | Maximum log file size. Defaults to `1048576`. [See above](#max-log-file-size) . | integer | +| | `--max-cache-size` | Maximum cache size. Defaults to `1073741824`. [See above](#--max-cache-size). | uinteger | +| | `--max-log-file-size` | Maximum log file size. Defaults to `1048576`. [See above](#--max-log-file-size) . | integer | | | `--sfile-path` | Path to the series file directory. Defaults to `~/.influxdbv2/engine/_series`. | string | | | `--tsi-path` | Path to the TSI index directory. Defaults to `~/.influxdbv2/engine/index`. | string | | | `--tsm-path` | Path to the TSM data directory. Defaults to `~/.influxdbv2/engine/data`. | string | diff --git a/content/influxdb/v2.0/reference/cli/influxd/restore.md b/content/influxdb/v2.0/reference/cli/influxd/restore.md deleted file mode 100644 index 49777f966..000000000 --- a/content/influxdb/v2.0/reference/cli/influxd/restore.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: influxd restore -description: The `influxd restore` command restores backup data and metadata from an InfluxDB backup directory. -influxdb/v2.0/tags: [restore] -menu: - influxdb_2_0_ref: - parent: influxd -weight: 201 -related: - - /influxdb/v2.0/backup-restore/restore/ -products: [oss] ---- - -The `influxd restore` command restores backup data and metadata from an InfluxDB backup directory. - -{{% warn %}} -Shut down the `influxd` server before restoring data. -{{% /warn %}} - -### The restore process -When restoring data from a backup file set, InfluxDB temporarily moves existing -data and metadata while `restore` runs. -After `restore` completes, the temporary data is deleted. -If the restore process fails, InfluxDB preserves the data in the temporary location. - -_For information about recovering from a failed restore process, see -[Restore data](/influxdb/v2.0/backup-restore/restore/#recover-from-a-failed-restore)._ - -By default, `restore` rebuilds the index and series file using the default options -for [`influxd inspect build-tsi`](/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi/). -To customize the [`build-tsi` performance options](/influxdb/v2.0/reference/cli/influxd/inspect/build-tsi/#adjust-performance), -include `--rebuild-index false` with `influxd restore`, then manually run `influxd inspect build-tsi`. - -## Usage - -``` -influxd restore [flags] -``` - -## Flags - -| Flag | | Description | Input type | -|:---- |:--- |:----------- |:----------:| -| | `--bolt-path` | Path to target boltdb database (default is `~/.influxdbv2/influxd.bolt`) | string | -| | `--engine-path` | Path to target persistent engine files (default is `~/.influxdbv2/engine`) | string | -| | `--credentials-path` | Path to target persistent credentials files (default is `~/.influxdbv2/credentials`) | string | -| | `--backup-path` | Path to backup files | string | -| | `--rebuild-index` | Rebuild the TSI index and series file based on the `--engine-path` (default is `true`) | | -| `-h` | `--help` | Help for the `restore` command | | diff --git a/content/influxdb/v2.0/reference/cli/influxd/upgrade.md b/content/influxdb/v2.0/reference/cli/influxd/upgrade.md index 67284ce6e..5bce5d015 100644 --- a/content/influxdb/v2.0/reference/cli/influxd/upgrade.md +++ b/content/influxdb/v2.0/reference/cli/influxd/upgrade.md @@ -23,8 +23,6 @@ This command performs the following actions: Unsupported 1.x options are reported to standard output. If the configuration file is not available, the 1.x database folder can be passed via th `--v1-dir` flag. 2. Copies and upgrades 1.x database files. -3. Creates a script that creates tokens for 1.x users. - This script needs to be revised and run manually after starting 2.x. The target 2.x database directory is specified by the `--engine-path` option. If changed, the bolt path can be specified by the `--bolt-path` option. @@ -47,11 +45,11 @@ influxd upgrade [command] | `-f` | `--force` | Skip the confirmation prompt | | | `-h` | `--help` | Help for `influxd upgrade` | | | | `--influx-command-path` | Path to influx command (default `~/go/bin/influx`) | string | +| | `--log-level` | Supported log levels are `debug`, `info`, `warn`, and `error` (default `info`) | string | | | `--log-path` | (Optional) Custom log file path (default `~/upgrade.log`) | string | | `-o` | `--org` | Primary organization name | string | | `-p` | `--password` | Password for username | string | | `-r` | `--retention` | (Optional) Duration bucket will retain data (default `0`; retains data infinitely) | string | -| | `--security-script` | (Optional) Generated security upgrade script path (default `~/influxd-upgrade-security.sh`) | string | | `-t` | `--token` | (Optional) Token for username. If not specified, a token is auto-generated. | string | | `-u` | `--username` | Primary username | string | | | `--v1-dir` | Path to source 1.x `db` directory containing `meta`, `data`, and `wal` sub-folders (default `~/.influxdb`) | string | diff --git a/content/influxdb/v2.0/reference/flux/stdlib/experimental/to.md b/content/influxdb/v2.0/reference/flux/stdlib/experimental/to.md index 26eb76dce..877c3e4bc 100644 --- a/content/influxdb/v2.0/reference/flux/stdlib/experimental/to.md +++ b/content/influxdb/v2.0/reference/flux/stdlib/experimental/to.md @@ -55,7 +55,7 @@ the **field value** as the **column value**. If using the built-in `from()` function, use [`pivot()`](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/pivot/) to transform data into the structure `experimetnal.to()` expects. -_[See the example below](#use-pivot-to-shape-data-for-experimental-to)._ +_[See the example below](#use-pivot-to-shape-data-for-experimentalto)._ ## Parameters diff --git a/content/influxdb/v2.0/reference/flux/stdlib/slack/message.md b/content/influxdb/v2.0/reference/flux/stdlib/slack/message.md index ce3c3f636..d7307ff74 100644 --- a/content/influxdb/v2.0/reference/flux/stdlib/slack/message.md +++ b/content/influxdb/v2.0/reference/flux/stdlib/slack/message.md @@ -96,5 +96,6 @@ slack.message( token: "mySuPerSecRetTokEn", channel: "#system-status", text: "The last reported status was \"${lastReported.status}\"." + color: "warning" ) ``` diff --git a/content/influxdb/v2.0/reference/glossary.md b/content/influxdb/v2.0/reference/glossary.md index d4095ef07..3fe1d5787 100644 --- a/content/influxdb/v2.0/reference/glossary.md +++ b/content/influxdb/v2.0/reference/glossary.md @@ -866,7 +866,7 @@ Related entries: [field key](#field-key),[measurement](#measurement), [tag key]( ### series file -A file created and used by the [InfluxDB storage engine](/influxdb/v2.0/reference/internals/storage-engine/) +A file created and used by the **InfluxDB OSS storage engine** that contains a set of all series keys across the entire database. ### series key @@ -1051,8 +1051,9 @@ Related entries: [Create a token](/influxdb/v2.0/security/tokens/create-token/). ### tracing -By default, tracing is disabled in InfluxDB. -To enable tracing or set other InfluxDB configuration options, see [InfluxDB configuration options](/influxdb/v2.0/reference/config-options/). +By default, tracing is disabled in InfluxDB OSS. +To enable tracing or set other InfluxDB OSS configuration options, +see [InfluxDB OSS configuration options](/influxdb/v2%2E0/reference/config-options/). ### transformation diff --git a/content/influxdb/v2.0/reference/key-concepts/data-schema.md b/content/influxdb/v2.0/reference/key-concepts/data-schema.md index ecc2af516..917c8f3cc 100644 --- a/content/influxdb/v2.0/reference/key-concepts/data-schema.md +++ b/content/influxdb/v2.0/reference/key-concepts/data-schema.md @@ -12,7 +12,7 @@ menu: influxdb/v2.0/tags: [key concepts] --- -InfluxDB [data elements](/influxdb/v2.0/reference/key-concepts/data-elements/) are stored in [time-structured merge tree (TSM)](/influxdb/v2.0/reference/internals/storage-engine/#time-structured-merge-tree-tsm) and [time series index (TSI)](/influxdb/v2.0/reference/internals/storage-engine/#time-series-index-tsi) files to efficiently compact stored data. +InfluxDB [data elements](/influxdb/v2.0/reference/key-concepts/data-elements/) are stored in **time-structured merge tree (TSM)** and **time series index (TSI)** files to efficiently compact stored data. InfluxDB also provides a **tabular data schema** that includes the following: @@ -24,7 +24,7 @@ InfluxDB also provides a **tabular data schema** that includes the following: The **tabular data schema is used for the following**: -- To [view raw data](/influxdb/v2.0/visualize-data/explore-metrics/#view-raw-data) when [exploring metrics with InfluxDB](/influxdb/v2.0/visualize-data/explore-metrics) +- To [view raw data](/influxdb/v2.0/query-data/execute-queries/data-explorer/#view-raw-data) when [exploring metrics with InfluxDB](/influxdb/v2.0/visualize-data/explore-metrics) - To return query results in [annotated CSV syntax](/influxdb/v2.0/reference/syntax/annotated-csv/) ## Annotation rows diff --git a/content/influxdb/v2.0/reference/release-notes/flux.md b/content/influxdb/v2.0/reference/release-notes/flux.md index 4990774b6..6ab1338bf 100644 --- a/content/influxdb/v2.0/reference/release-notes/flux.md +++ b/content/influxdb/v2.0/reference/release-notes/flux.md @@ -8,6 +8,17 @@ menu: name: Flux --- +## v0.94.0 [2020-11-09] + +### Features +- Add "everything" Rust benchmark. + +### Bug fixes +- Add multiline support to the Flux formatter. +- Format types using letters instead of numbers. + +--- + ## v0.93.0 [2020-11-02] ### Features diff --git a/content/influxdb/v2.0/reference/release-notes/influxdb.md b/content/influxdb/v2.0/reference/release-notes/influxdb.md index fa795fc0f..b9ecc1e02 100644 --- a/content/influxdb/v2.0/reference/release-notes/influxdb.md +++ b/content/influxdb/v2.0/reference/release-notes/influxdb.md @@ -8,11 +8,83 @@ menu: weight: 101 --- +## v2.0.1 General Availability [2020-11-10] + +InfluxDB 2.0 general availability (GA) introduces the first **production-ready** open source version of InfluxDB 2.0. This release comprises all features and bug fixes included in prior alpha, beta, and release candidate versions. + +{{% note %}} +#### Known issues + +##### Delete with predicate API not implemented + +The delete with predicate API (`/api/v2/delete`) has not been implemented and currently returns a `501 Not implemented` message. This API will be implemented post GA. + +##### Duplicate DBRP mappings per database + +When there are multiple [DBRP mappings](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/) with the same database name in InfluxDB 1.x, SHOW DATABASES incorrectly returns duplicates. +{{% /note %}} + +Highlights include: + +- Support for **upgrading to InfluxDB 2.0**: + - To upgrade **from InfluxDB 1.x**, see [Upgrade from InfluxDB 1.x to InfluxDB 2.0](/influxdb/v2.0/upgrade/v1-to-v2). + - To upgrade **from InfluxDB 2.0 beta 16 or earlier**, see [Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0](/influxdb/v2.0/upgrade/v2-beta-to-v2). +- **Flux**, our powerful new functional data scripting language designed for querying, analyzing, and acting on data. This release includes [Flux v0.94.0](/influxdb/v2.0/reference/release-notes/flux/#v0-94-0-2020-11-09). If you're new to Flux, [check out how to get started with Flux](/influxdb/v2.0/query-data/get-started/). Next, delve deeper into the [Flux standard library](/influxdb/v2.0/reference/flux/stdlib/) reference docs and see how to [query with Flux](/influxdb/v2.0/query-data/flux/). +- Support for [InfluxDB 1.x API compatibility](/influxdb/v2.0/reference/api/influxdb-1x/). +- **Templates** and **stacks**. Discover how to [use community templates](/influxdb/v2.0/influxdb-templates/use/) and how to [manage templates with stacks](/influxdb/v2.0/influxdb-templates/stacks/). + +If you're new to InfluxDB 2.0, we recommend checking out [how to get started](/influxdb/v2.0/get-started/) and [InfluxDB key concepts](/influxdb/v2.0/reference/key-concepts/). + +## v2.0.0 [2020-11-09] + +### Features +- Improve UI for v1 `influx auth` commands. +- Upgrade to [Flux v0.94.0](/influxdb/v2.0/reference/release-notes/flux/#v0-94-0-2020-11-10) +- Upgrade `flux-lsp-browser` to v0.5.22. +- Add [RAS Telegraf input plugin](/telegraf/v1.16/plugins//#ras). + +### Bug Fixes + +- Remove unused `security-script` option from `influx upgrade` command. +- Fix parsing of retention policy CLI arguments in `influx setup` and `influxd upgrade`. +- Create CLI configs during upgrade to v2. +- Allow write-only v1 tokens to find database retention policies (DBRPs). +- Update `v1 auth` description. +- Use `db`/`rp` naming convention when migrating databases to buckets. +- Improve help text for `influxd` and `--no-password` switch. +- Use `10` instead of `MaxInt` when rewriting query-concurrency. +- Remove bucket and mapping auto-creation from `/write` 1.x compatibility API. +- Fix misuse of `reflect.SliceHeader`. + +## v2.0.0-rc.4 [2020-11-05] + +### Features + +- Upgrade to [Flux v0.93.0](/influxdb/v2.0/reference/release-notes/flux/#v0-93-0-2020-11-02). +- Add `influx backup` and `influx restore` CLI commands to support backing up and restoring data in InfluxDB 2.0. +- Add the `v1/authorization` package to support authorizing requests to the InfluxDB 1.x API. + +### Bug Fixes + +- Add a new `CreateUniquePhysicalNode` method, which reads and applies the plan node ID in context. Each physical node has a unique ID to support planner rules applied more than once in a query. Previously, the same node ID (hence the same dataset ID) caused the execution engine to generate undefined results. +- A cloned task is now only activated when you select **Active**. Previously, a cloned task was activated if the original task was activated. +- Reduce the `influx` binary file size. +- Isolate the `TelegrafConfigService` and remove URM interactions. +- Use the updated HTTP client for the authorization service. +- Make `tagKeys` and `tagValues` work for edge cases involving fields. +- Correctly parse float as 64-bits. +- Add simple metrics related to installed templates. +- Remove extra multiplication of retention policies in onboarding. +- Use the `fluxinit` package to initialize the Flux library instead of builtin. +- Add Logger to the constructor function to ensure the log field is initialized. +- Return an empty iterator instead of null in `tagValues`. +- Fix the `/ready` response content type to return `application/json`. + ## v2.0.0-rc.3 [2020-10-29] ### Features -- Upgrade to [Flux v0.91.0](/influxdb/v2.0/reference/release-notes/flux/#v0-91-0-2020-10-26). +- Upgrade to [Flux v0.91.0](/influxdb/v2.0/reference/release-notes/flux/#v0910-2020-10-26). - Enable window aggregate mean pushdown. - Add `newMultiShardArrayCursors` to aggregate array cursors. - UI updates: @@ -34,7 +106,7 @@ weight: 101 ### Features -- Upgrade to [Flux v0.90.0](/influxdb/v2.0/reference/release-notes/flux/#v0-90-0-2020-10-19). +- Upgrade to [Flux v0.90.0](/influxdb/v2.0/reference/release-notes/flux/#v0900-2020-10-19). - Add `--force` option to the `influx stacks rm` command, which lets you remove a stack without the confirmation prompt. - Add `aggregate_resultset` for mean aggregate pushdown to optimize windowed results. - Return an error if adding a resource to a stack (`influx stacks update --addResource`) fails due to an invalid resource type or resource ID. @@ -122,7 +194,7 @@ To simplify the migration for existing users of InfluxDB 1.x, this release inclu ### Bug Fixes -- Add description to [`influx auth`](influxdb/v2.0/reference/cli/influx/auth/) command outputs. +- Add description to [`influx auth`](/influxdb/v2.0/reference/cli/influx/auth/) command outputs. - Resolve issues with check triggers in notification tasks by including the edge of the observed boundary. - Detect and provide warning about duplicate tag names when writing CSV data using `influx write`. - Ensure the group annotation does not override the existing line part (measurement, field, tag, time) in a CSV group annotation. @@ -222,7 +294,7 @@ This release includes breaking changes: ### Features -- Add option for Cloud users to use the `influx` CLI to interact with a Cloud instance. For more information, see how to [download and install the influx CLI](/influxdb/v2.0/get-started/#optional-download-install-and-use-the-influx-cli) and then learn more about how the [influx - InfluxDB command line interface](/influxdb/v2.0/reference/cli/influx/) works. +- Add option for Cloud users to use the `influx` CLI to interact with a Cloud instance. For more information, see how to [download and install the influx CLI](/influxdb/v2.0/get-started/) and then learn more about how the [influx - InfluxDB command line interface](/influxdb/v2.0/reference/cli/influx/) works. - Consolidate `influx apply` commands under templates. Remove some nesting of the `influx` CLI commands. - Make all `influx apply` applications stateful through stacks. - Add ability to export a stack's existing resource state using `influx export`. @@ -686,7 +758,7 @@ The `map()` function panics if the first record processed has a `null` value. ### Features - Add `influxd inspect verify-wal` tool. -- Move to [Flux 0.34.2](/influxdb/v2.0/reference/release-notes/flux/#v0-34-2-2019-06-27) - +- Move to [Flux 0.34.2](/influxdb/v2.0/reference/release-notes/flux/#v0342-2019-06-27) - includes new string functions and initial multi-datasource support with `sql.from()`. - Only click save once to save cell. - Enable selecting more columns for line visualizations. diff --git a/content/influxdb/v2.0/reference/sample-data.md b/content/influxdb/v2.0/reference/sample-data.md index 82e9a2bbb..25182fdd8 100644 --- a/content/influxdb/v2.0/reference/sample-data.md +++ b/content/influxdb/v2.0/reference/sample-data.md @@ -11,17 +11,7 @@ weight: 7 --- Use sample data to familiarize yourself with time series data and InfluxDB. -InfluxData provides many sample time series datasets to use with **InfluxDB Cloud** and **InfluxDB**. - -## InfluxDB Cloud demo data -Use [InfluxDB Cloud demo data buckets](/influxdb/v2.0/reference/sample-data/#influxdb-cloud-demo-data) for quick, -free access to different types of sample data. - -{{< youtube GSaByPC1Bdc >}} - -{{% note %}} -Demo data is not available for use with third-party integrations such as Grafana. -{{% /note %}} +InfluxData provides many sample time series datasets to use with InfluxDB. ## Sample data sets The following sample data sets are used as examples in [InfluxDB query guides](/influxdb/v2.0/query-data/flux) diff --git a/content/influxdb/v2.0/reference/upgrading/_index.md b/content/influxdb/v2.0/reference/upgrading/_index.md deleted file mode 100644 index 755911d7b..000000000 --- a/content/influxdb/v2.0/reference/upgrading/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Upgrade InfluxDB -description: > - Upgrade your version of InfluxDB -menu: influxdb_2_0_ref -weight: 20 -influxdb/v2.0/tags: [] ---- - -{{< children >}} diff --git a/content/influxdb/v2.0/reference/upgrading/influxd-upgrade-guide.md b/content/influxdb/v2.0/reference/upgrading/influxd-upgrade-guide.md deleted file mode 100644 index d500ce425..000000000 --- a/content/influxdb/v2.0/reference/upgrading/influxd-upgrade-guide.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Upgrade from InfluxDB 1.x to InfluxDB 2.0 -description: > - Upgrade from InfluxDB 1.x to InfluxDB 2.0. -menu: - influxdb_2_0_ref: - parent: Upgrade InfluxDB - name: Upgrade from InfluxDB 1.x to InfluxDB 2.0 -weight: 9 ---- - -Use the `influxd upgrade` command to upgrade InfluxDB 1.x to InfluxDB 2.0. -This command copies all data stored in 1.x [databases](/influxdb/v1.8/concepts/glossary/#database) and -[retention policies](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) -to 2.0 [buckets](/influxdb/v2.0/reference/glossary/#bucket). - -{{% warn %}} -Back up all data before upgrading with `influx upgrade`. -{{% /warn %}} - -1. [Download the InfluxDB OSS 2.0rc](https://portal.influxdata.com/downloads/), - unpackage the InfluxDB binaries, and then place them in your `$PATH`. -2. Stop your running InfluxDB 1.x instance. -3. If your configuration file is at the default location (`~/.influxdbv2/configs`), run: - - ```sh - influxd upgrade - ``` - Otherwise, run: - ```sh - influxd upgrade --config - ``` - -4. Follow the prompts to set up a new InfluxDB 2.0 instance. - -For more information on upgrading, including how to handle non-standard installations, see [`influxd upgrade`](/influxdb/v2.0/reference/cli/influxd/upgrade/). diff --git a/content/influxdb/v2.0/reference/urls.md b/content/influxdb/v2.0/reference/urls.md index 23615d2ef..08d9c7e40 100644 --- a/content/influxdb/v2.0/reference/urls.md +++ b/content/influxdb/v2.0/reference/urls.md @@ -1,40 +1,31 @@ --- -title: InfluxDB 2.0 URLs +title: InfluxDB OSS URLs description: > - InfluxDB 2.0 is available both locally (OSS) or on multiple cloud providers in multiple regions (Cloud). -aliases: - - /influxdb/v2.0/cloud/urls/ + InfluxDB OSS is accessed at `localhost:8086` by default, but you can also + customize your InfluxDB host and port. weight: 6 menu: influxdb_2_0_ref: name: InfluxDB URLs --- -InfluxDB 2.0 is available both locally (OSS) or on multiple cloud providers in multiple regions (Cloud). +InfluxDB OSS is accessed at `localhost:8086` by default, but you can also +customize your InfluxDB host and port. -## InfluxDB Cloud URLs - -Each region has a unique InfluxDB Cloud URL and API endpoint. -Use the URLs below to interact with your InfluxDB Cloud instances with the -[InfluxDB API](/influxdb/v2.0/reference/api/), [InfluxDB client libraries](/influxdb/v2.0/tools/client-libraries/), -[`influx` CLI](/influxdb/v2.0/reference/cli/influx/), or [Telegraf](/influxdb/v2.0/write-data/no-code/use-telegraf/). - -{{< cloud_regions >}} - -## InfluxDB OSS URLs - -For InfluxDB OSS, the default URL is the following: +**Default host:** `localhost` +**Default port:** `8086` {{< keep-url >}} ``` http://localhost:8086/ ``` -### Customize your InfluxDB OSS URL +## Customize your InfluxDB OSS URL To customize your InfluxDB host and port, use the [`http-bind-address` configuration option](/influxdb/v2.0/reference/config-options/#http-bind-address) when starting `influxd`. +{{< keep-url >}} ```sh # Syntax influxd --http-bind-address : diff --git a/content/influxdb/v2.0/security/enable-tls.md b/content/influxdb/v2.0/security/enable-tls.md index 4f7d0c942..c533814e4 100644 --- a/content/influxdb/v2.0/security/enable-tls.md +++ b/content/influxdb/v2.0/security/enable-tls.md @@ -16,14 +16,14 @@ When configured with a signed certificate, TLS also allows clients to verify the To set up TLS over HTTPS, do the following: -- [Obtain requirements](#requirements) +- [Obtain requirements](#obtain-requirements) - [Configure InfluxDB to use TLS](#configure-influxdb-to-use-tls) {{% warn %}} InfluxData **strongly recommends** enabling HTTPS, especially if you plan on sending requests to InfluxDB over a network. {{% /warn %}} -## Requirements +## Obtain requirements To enable HTTPS with InfluxDB, you need a Transport Layer Security (TLS) certificate, also known as a Secured Sockets Layer (SSL) certificate. InfluxDB supports three types of TLS certificates: diff --git a/content/influxdb/v2.0/security/secrets/use-vault.md b/content/influxdb/v2.0/security/secrets/use-vault.md index 068400818..cba192b16 100644 --- a/content/influxdb/v2.0/security/secrets/use-vault.md +++ b/content/influxdb/v2.0/security/secrets/use-vault.md @@ -12,17 +12,14 @@ weight: 201 to tokens, passwords, certificates, and other sensitive secrets. Store sensitive secrets in Vault using InfluxDB's built-in Vault integration. -## Use Vault with {{< cloud-name >}} +To store secrets in Vault, complete the following steps: + +1. [Start a Vault server](#start-a-vault-server). +2. [Provide Vault server address and token](#provide-vault-server-address-and-token). +3. [Start InfluxDB](#start-influxdb). +4. [Manage secrets through the InfluxDB API](#manage-secrets-through-the-influxdb-api). -By default, all secrets added to **InfluxDB Cloud** are stored in the -**InfluxDB Cloud Vault cluster**. - -For more on adding and using secrets, see [Manage secrets](/influxdb/v2.0/security/secrets/manage-secrets/). -Once added, use the [`secrets.get()`](/influxdb/v2.0/reference/flux/stdlib/secrets/get/) function to retrieve secrets for use in Flux scripts. - -## Use Vault with InfluxDB OSS - -### Start a Vault server +## Start a Vault server Start a Vault server and ensure InfluxDB has network access to the server. @@ -47,26 +44,28 @@ For this example, install Vault on your local machine and start a Vault dev serv vault server -dev ``` -### Provide Vault server address and token +## Provide Vault server address and token Use `influxd` Vault-related tags or [Vault environment variables](https://www.vaultproject.io/docs/commands/index.html#environment-variables) to provide connection credentials and other important Vault-related information to InfluxDB. -#### Required credentials +### Required credentials + +#### Vault address -##### Vault address Provide the API address of your Vault server _(available in the Vault server output)_ using the [`--vault-addr` flag](/influxdb/v2.0/reference/config-options/#vault-addr) when starting `influxd` or with the `VAULT_ADDR` environment variable. -##### Vault token +#### Vault token + Provide your [Vault token](https://learn.hashicorp.com/vault/getting-started/authentication) (required to access your Vault server) using the [`--vault-token` flag](/influxdb/v2.0/reference/config-options/#vault-token) when starting `influxd` or with the `VAULT_TOKEN` environment variable. _Your Vault server configuration may require other Vault settings._ -### Start InfluxDB +## Start InfluxDB Start the [`influxd` service](/influxdb/v2.0/reference/cli/influxd/) with the `--secret-store` option set to `vault` any other necessary flags. @@ -93,6 +92,7 @@ If set, these flags override any [Vault environment variables](https://www.vault For more information, see [InfluxDB configuration options](/influxdb/v2.0/reference/config-options/). -### Manage secrets through the InfluxDB API +## Manage secrets through the InfluxDB API + Use the InfluxDB `/org/{orgID}/secrets` API endpoint to add tokens to Vault. For details, see [Manage secrets](/influxdb/v2.0/security/secrets/manage-secrets/). diff --git a/content/influxdb/v2.0/telegraf-configs/_index.md b/content/influxdb/v2.0/telegraf-configs/_index.md index 21e4af28a..df85860f9 100644 --- a/content/influxdb/v2.0/telegraf-configs/_index.md +++ b/content/influxdb/v2.0/telegraf-configs/_index.md @@ -1,7 +1,8 @@ --- title: Telegraf configurations description: > - placeholder + InfluxDB lets you automatically generate Telegraf configurations or upload customized + Telegraf configurations that collect metrics and write them to InfluxDB. weight: 12 menu: influxdb_2_0 influxdb/v2.0/tags: [telegraf] diff --git a/content/influxdb/v2.0/telegraf-configs/create.md b/content/influxdb/v2.0/telegraf-configs/create.md index b6fee33e4..c1bddba5a 100644 --- a/content/influxdb/v2.0/telegraf-configs/create.md +++ b/content/influxdb/v2.0/telegraf-configs/create.md @@ -32,7 +32,7 @@ For more information, see [Automatically configure Telegraf](/influxdb/v2.0/writ Telegraf has an extensive list of plugins for many different technologies and use cases. Not all plugins are available through the InfluxDB UI, but you can [create and upload custom Telegraf configurations](#create-a-custom-telegraf-configuration) -that include any of the available [Telegraf plugins](/influxdb/v2.0/reference/telegraf-plugins). +that include any of the available [Telegraf plugins](/{{< latest "telegraf" >}}/plugins/). ## Use the influx CLI Use the [`influx telegrafs create` command](/influxdb/v2.0/reference/cli/influx/telegrafs/create/) @@ -69,6 +69,6 @@ influx telegrafs create \ 1. Create a custom Telegraf configuration file that includes the `outputs.influxdb_v2` output plugin. _See [Manually configure Telegraf](/influxdb/v2.0/write-data/no-code/use-telegraf/manual-config/)_ for more information. -2. Add and customize [Telegraf plugins](/influxdb/v2.0/reference/telegraf-plugins) and save your changes. +2. Add and customize [Telegraf plugins](/{{< latest "telegraf" >}}/plugins/) and save your changes. 3. [Use the `influx telegrafs create` command](#use-the-influx-cli) to upload your custom Telegraf configuration to InfluxDB. diff --git a/content/influxdb/v2.0/telegraf-configs/update.md b/content/influxdb/v2.0/telegraf-configs/update.md index 1c0452e6b..7a93824e8 100644 --- a/content/influxdb/v2.0/telegraf-configs/update.md +++ b/content/influxdb/v2.0/telegraf-configs/update.md @@ -81,7 +81,7 @@ influx telegrafs update \ 2. Click the **name** of the Telegraf configuration to customize. 3. Click **Download Config** to download the Telegraf configuration file to your local machine. -4. Add or update [Telegraf plugin](/influxdb/v2.0/reference/telegraf-plugins) settings and +4. Add or update [Telegraf plugin](/{{< latest "telegraf" >}}/plugins/) settings and save your changes. 5. [Use the `influx telegrafs update` command](#use-the-influx-cli) to upload your modified Telegraf configuration to InfluxDB and replace the existing configuration. diff --git a/content/influxdb/v2.0/tools/clis.md b/content/influxdb/v2.0/tools/clis.md index 584d228d7..64c404c67 100644 --- a/content/influxdb/v2.0/tools/clis.md +++ b/content/influxdb/v2.0/tools/clis.md @@ -14,13 +14,15 @@ Use the `influx` and `influxd` command line interfaces (CLIs) to interact with a manage InfluxDB. ## influx CLI -Use the `influx` CLI to interact with and manage both **InfluxDB Cloud** and **InfluxDB OSS**. + +Use the `influx` CLI to interact with and manage your **InfluxDB** instance. Write and query data, generate InfluxDB templates, export data, manage organizations and users, and more. _For more information, see the [`influx` reference documentation](/influxdb/v2.0/reference/cli/influx/)._ ## influxd CLI + Use the `influxd` CLI to start the **InfluxDB OSS** server and manage the InfluxDB storage engine. Restore data, rebuild the time series index (TSI), assess the health of the underlying storage engine, and more. diff --git a/content/influxdb/v2.0/tools/google-data-studio.md b/content/influxdb/v2.0/tools/google-data-studio.md index 35f55908b..99c39c234 100644 --- a/content/influxdb/v2.0/tools/google-data-studio.md +++ b/content/influxdb/v2.0/tools/google-data-studio.md @@ -1,6 +1,9 @@ --- title: Use the Google Data Studio connector -description: The [InfluxDB Google Data Studio connector](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs) lets you create reports and dashboards in Google Data Studio with data from InfluxDB 2.0. +description: > + The [InfluxDB Google Data Studio connector](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs) + lets you create reports and dashboards in Google Data Studio with data from + InfluxDB Cloud or InfluxDB OSS 2.0. menu: influxdb_2_0: parent: Tools & integrations @@ -8,16 +11,16 @@ weight: 102 influxdb/v2.0/tags: [google] --- -The [InfluxDB Google Data Studio connector](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs) lets you create reports and dashboards in Google Data Studio with data from InfluxDB 2.0. The connector supports one measurement per organization. +The [InfluxDB Google Data Studio connector](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs) lets you create reports and dashboards in Google Data Studio with data from **InfluxDB Cloud** or **InfluxDB OSS 2.0**. The connector supports one measurement per organization. ### Add the InfluxDB Connector to Data Studio 1. Add the [InfluxDB Connector data source](https://datastudio.google.com/u/0/datasources/create?connectorId=AKfycbwhJChhmMypQvNlihgRJMAhCb8gaM3ii9oUNWlW_Cp2PbJSfqeHfPyjNVp15iy9ltCs). 2. Enter the following connection details: - - `InfluxDB URL`: Your [InfluxDB 2.0 URL](/influxdb/v2.0/reference/urls/). + - `InfluxDB URL`: Your [InfluxDB URL](/influxdb/v2.0/reference/urls/). - `Token`: Your [authentication token](/influxdb/v2.0/security/tokens/create-token/) with permission to read from the bucket you're using. - `Organization`: Your [organization name](/influxdb/v2.0/organizations/view-orgs). - - `Bucket`: Your [bucket name](/influxdb/v2.0/organizations/buckets/view-buckets/#view-a-list-of-buckets). This is auto-populated when you enter the fields above. + - `Bucket`: Your [bucket name](/influxdb/v2.0/organizations/buckets/view-buckets/). This is auto-populated when you enter the fields above. - `Measurement`: The [measurement](/influxdb/v2.0/reference/glossary/#measurement) to connect to. 3. Click **Connect**. diff --git a/content/influxdb/v2.0/tools/grafana.md b/content/influxdb/v2.0/tools/grafana.md index fa86212ea..4cf2b282d 100644 --- a/content/influxdb/v2.0/tools/grafana.md +++ b/content/influxdb/v2.0/tools/grafana.md @@ -1,7 +1,7 @@ --- -title: Use Grafana with InfluxDB +title: Use Grafana with InfluxDB OSS description: > - Use [Grafana](https://grafana.com/) to visualize data from **InfluxDB 2.0** and **InfluxDB Cloud**. + Use [Grafana](https://grafana.com/) to visualize data from your **InfluxDB** instance. menu: influxdb_2_0: name: Use Grafana @@ -13,18 +13,16 @@ aliases: related: - https://grafana.com/docs/, Grafana documentation - /influxdb/v2.0/query-data/get-started/ - - /influxdb/v2.0/query-data/influxql/ --- Use [Grafana](https://grafana.com/) or [Grafana Cloud](https://grafana.com/products/cloud/) -to visualize data from **InfluxDB 2.0** and **{{< cloud-name "short" >}}**. +to visualize data from your **InfluxDB** instance. {{% note %}} The instructions in this guide require **Grafana Cloud** or **Grafana v7.1+**. {{% /note %}} -1. [Sign up for {{< cloud-name >}}](/influxdb/v2.0/get-started/) or - [start InfluxDB 2.0 OSS](/influxdb/v2.0/get-started/#start-with-influxdb-oss). +1. [Start InfluxDB OSS 2.0](/influxdb/v2.0/get-started/). 2. [Sign up for Grafana Cloud](https://grafana.com/products/cloud/) or [download and install Grafana](https://grafana.com/grafana/download). 3. Visit your **Grafana Cloud user interface** (UI) or, if running Grafana locally, @@ -39,12 +37,12 @@ The instructions in this guide require **Grafana Cloud** or **Grafana v7.1+**. {{< tabs-wrapper >}} {{% tabs %}} -[Flux](#) +[Flux](#) [InfluxQL](#) {{% /tabs %}} - {{% tab-content %}} ## Configure Grafana to use Flux + With **Flux** selected as the query language in your InfluxDB data source, configure your InfluxDB connection: @@ -105,8 +103,9 @@ configure your InfluxDB connection: {{< /tabs-wrapper >}} ## Query and visualize data + With your InfluxDB connection configured, use Grafana and Flux to query and -visualize time series data stored in **InfluxDB 2.0** or **{{< cloud-name >}}**. +visualize time series data stored in your **InfluxDB** instance. For more information about using Grafana, see the [Grafana documentation](https://grafana.com/docs/). If you're just learning Flux, see [Get started with Flux](/influxdb/v2.0/query-data/get-started/). diff --git a/content/influxdb/v2.0/upgrade/_index.md b/content/influxdb/v2.0/upgrade/_index.md new file mode 100644 index 000000000..86e0a2ba4 --- /dev/null +++ b/content/influxdb/v2.0/upgrade/_index.md @@ -0,0 +1,12 @@ +--- +title: Upgrade InfluxDB +description: > + Upgrade your version of InfluxDB +menu: influxdb_2_0 +weight: 2 +aliases: + - /influxdb/v2.0/reference/upgrading/ +influxdb/v2.0/tags: [upgrade] +--- + +{{< children >}} diff --git a/content/influxdb/v2.0/upgrade/v1-to-v2.md b/content/influxdb/v2.0/upgrade/v1-to-v2.md new file mode 100644 index 000000000..02c48a4f2 --- /dev/null +++ b/content/influxdb/v2.0/upgrade/v1-to-v2.md @@ -0,0 +1,212 @@ +--- +title: Upgrade from InfluxDB 1.x to InfluxDB 2.0 +description: > + Upgrade from InfluxDB 1.x to InfluxDB 2.0. +menu: + influxdb_2_0: + parent: Upgrade InfluxDB + name: InfluxDB 1.x to 2.0 +weight: 10 +aliases: + - /influxdb/v2.0/reference/upgrading/influxd-upgrade-guide/ +--- + +Use the `influxd upgrade` command to upgrade InfluxDB 1.x to InfluxDB 2.0. +The `upgrade` command provides an in-place upgrade from InfluxDB 1.x to InfluxDB 2.0. + +Specifically, the upgrade process does the following: + +1. Reads the existing InfluxDB 1.x configuration file and generates an equivalent InfluxDB 2.0 configuration file at `~/.influxdbv2/config.toml`. +2. Upgrades metadata and storage engine paths to `~/.influxdbv2/meta` and `~/.influxdbv2/engine`, respectively (unless otherwise specified). +3. Writes existing data and write ahead log (WAL) files into InfluxDB 2.0 [buckets](/influxdb/v2.0/reference/glossary/#bucket). +4. Creates [database and retention policy (DBRP) mappings](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/) required to query data with InfluxQL. +5. Reads existing metadata and migrates non-admin users, passwords, and permissions into a 1.x authorization–compatible store within `~/influxdbv2/influxdb.bolt`. + +When starting InfluxDB 2.0 after running `influxdb upgrade`, InfluxDB must build a new time series index (TSI). +Depending on the volume of data present, this may take some time. + +## Before you begin: important considerations + +Before upgrading to InfluxDB 2.0, consider the following guidelines. +Some or all might apply to your specific installation and use case. +The sections below contain our recommendations for addressing possible gaps in the upgrade process. +Consider whether you need to address any of the following before upgrading. + +- [Available operating system, container, and platform support](#available-operating-system-container-and-platform-support) +- [Continuous queries](#continuous-queries) +- [Supported protocols](#supported-protocols) +- [Kapacitor](#kapacitor) +- [User migration](#user-migration) +- [Dashboards](#dashboards) +- [Other data](#other-data) +- [Secure by default](#secure-by-default) + +### Available operating system, container, and platform support + +{{% warn %}} +InfluxDB 2.0 requires 64-bit operating systems. +{{% /warn %}} + +InfluxDB 2.0 is currently available for macOS and Linux. +Docker images, ARM builds, and Windows builds are not currently available, +but are planned for subsequent releases. + +{{% note %}} +#### Hold off if using Docker +If you're running InfluxDB 1.8 in Docker, don't upgrade to InfluxDB 2.0 yet. +We are working on the upgrade process for InfluxDB Docker containers. +{{% /note %}} + +### Continuous queries +Continuous queries are replaced by **tasks** in InfluxDB 2.0. +To convert continuous queries to InfluxDB tasks: + +1. Use the InfluxDB 1.x `influx` interactive shell and run `show continuous queries`: + + ```sh + $ influx + Connected to http://localhost:8086 version 1.8.3 + InfluxDB shell version: 1.8.3 + > show continuous queries + ``` + +2. Save the continuous queries and convert them to Flux. For help converting InfluxQL to Flux, use the following resources: + + - [Get started with InfluxDB tasks](/influxdb/v2.0/process-data/get-started/) + - [Get started with Flux](/influxdb/v2.0/query-data/get-started/) + - [Common tasks](/v2.0/process-data/common-tasks/#downsample-data-with-influxdb) + - [`influx transpile`](https://docs.influxdata.com/influxdb/v2.0/reference/cli/influx/transpile/) (transpiles InfluxQL into Flux) + - Post in the [InfluxData Community](https://community.influxdata.com/) + - Ask in the [InfluxDB Community Slack](https://influxdata.com/slack) + +### Supported protocols + +InfluxDB 2.0 doesn't directly support the alternate write protocols +[supported in InfluxDB 1.x](/influxdb/v1.8/supported_protocols/) +(CollectD, Graphite, OpenTSDB, Prometheus, UDP). +Use [Telegraf](/{{< latest "telegraf" >}}/) to translate these protocols to line protocol. + +### Kapacitor + +You can continue to use Kapacitor with InfluxDB OSS 2.0 under the following scenarios: + +- Kapacitor Batch-style TICKscripts work with the 1.x read compatible API. + Existing Kapacitor user credentials should continue to work using the [1.x compatibility API](/influxdb/v2.0/reference/api/influxdb-1x/). +- InfluxDB 2.0 has no subsriptions API and does not support Kapacitor stream tasks. + To continue using stream tasks, write data directly to both InfluxDB and Kapacitor. + Use **Telegraf** and its [InfluxDB output plugin](/{{< latest "telegraf" >}}/plugins/#influxdb) + to write to Kapacitor and the [InfluxDB v2 output plugin](/{{< latest "telegraf" >}}/plugins/#influxdb_v2) to write to InfluxDB v2. + +##### Example Telegraf configuration +```toml +# Write to Kapacitor +[[outputs.influxdb]] + urls = ["http://localhost:9092"] + database = "example-db" + retention_policy = "example-rp" + +# Write to InfluxDB 2.0 +[[outputs.influxdb]] + urls = ["http://localhost:8086"] + database = "example-db" + retention_policy = "example-rp" + username = "v1-auth-username" + password = "v1-auth-password" +``` + +### User migration + +`influxd upgrade` migrates existing 1.x users and their permissions. +However, it *does not migrate administrative users*. + +To review users with admin permissions, in the InfluxDB 1.x CLI, run `show users`. +Any users labeled "admin" *will not* be migrated. + +If using an admin user for visualization or Chronograf's administrative functions, create a new read-only user before upgrading. +Admin rights are granted to the primary user created in the InfluxDB 2.0 setup process which runs at the end of the upgrade process. +This provides you with the opportunity to re-assess who should be granted admin-level access in your InfluxDB 2.0 setup. + +### Dashboards + +You can continue to use your existing dashboards and visualization tools with InfluxDB 2.0 via the [1.x read compatibility API](/influxdb/v2.0/reference/api/influxdb-1x/). +The upgrade process creates [DBRP mappings](/influxdb/v2.0/reference/api/influxdb-1x/dbrp/) to ensure existing users can execute InfluxQL queries with the appropriate permissions. + +However, if your dashboard tool is configured using a user with admin permissions, +you will need to create a new read-only user with the appropriate database permissions *before* upgrading. +This new username and password combination should be used within the data source configurations to continue to provide read-only access to the underlying data. + +Ensure your dashboards are all functioning before upgrading. + +### Other data + +The 1.x `_internal` database is not migrated with the `influxd upgrade` command. +To collect, store, and monitor similar internal InfluxDB metrics, +[create an InfluxDB 2.0 scraper](/influxdb/v2.0/write-data/no-code/scrape-data/manage-scrapers/create-a-scraper/) +to scrape data from the `/metrics` endpoint and store them in a bucket. + +### Secure by default + +InfluxDB 2.0 requires authentication and does not support the InfluxDB 1.x +`auth-enabled = false` configuration option. +Consider [enabling authentication in your InfluxDB 1.x instance](/influxdb/v1.8/administration/authentication_and_authorization/#set-up-authentication) +**before** upgrading to InfluxDB 2.0 to ensure the appropriate credentials are in place and +that the various applications, agents, and visualization tools are able to connect. + +## Perform the upgrade + +If you've considered the [guidance above](#before-you-begin-important-considerations) +and are ready to proceed, follow these steps to upgrade your InfluxDB 1.x to InfluxDB 2.0. + +1. [Download InfluxDB OSS 2.0](https://portal.influxdata.com/downloads/). + Unpackage the InfluxDB binaries and place them in your `$PATH`. +2. Stop your running InfluxDB 1.x instance. + Make a backup copy of all 1.x data before upgrading: + + ```sh + cp -R .influxdb/ .influxdb_bak/ + ``` +3. Use `influxd version` to ensure you are running InfluxDB 2.0 from the command line. + The `influxd upgrade` command is only available in InfluxDB 2.0. +4. If your 1.x configuration file is at the [default location](/influxdb/v1.8/administration/config/#using-the-configuration-file), run: + + ```sh + influxd upgrade + ``` + + If your 1.x configuration file is not at the default location, run: + + ```sh + influxd upgrade --config-file + ``` + +5. Follow the prompts to set up a new InfluxDB 2.0 instance. + + ``` + Welcome to InfluxDB 2.0 upgrade! + Please type your primary username: + + Please type your password: + + Please type your password again: + + Please type your primary organization name: + + Please type your primary bucket name: + + Please type your retention period in hours. + Or press ENTER for infinite: + + You have entered: + Username: + Organization: + Bucket: + Retention Period: infinite + Confirm? (y/n): y + ``` + +The output of the upgrade prints to standard output. +It is also saved (for troubleshooting and debugging) in the current directory to a file called `upgrade.log` located in the home directory of the user running `influxdb upgrade`. + +## Further reading + +For more information on upgrading, see the [`influxd upgrade` reference documentation](/influxdb/v2.0/reference/cli/influxd/upgrade/). diff --git a/content/influxdb/v2.0/reference/upgrading/rc-upgrade-guide.md b/content/influxdb/v2.0/upgrade/v2-beta-to-v2.md similarity index 96% rename from content/influxdb/v2.0/reference/upgrading/rc-upgrade-guide.md rename to content/influxdb/v2.0/upgrade/v2-beta-to-v2.md index fecc2ea2f..24e7ed75c 100644 --- a/content/influxdb/v2.0/reference/upgrading/rc-upgrade-guide.md +++ b/content/influxdb/v2.0/upgrade/v2-beta-to-v2.md @@ -1,18 +1,21 @@ --- -title: Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0rc +title: Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0 (stable) description: > - Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0rc. + To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.0 (stable), + manually upgrade all resources and data to the latest version by completing these steps. menu: - influxdb_2_0_ref: + influxdb_2_0: parent: Upgrade InfluxDB - name: Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0rc + name: InfluxDB 2.0 beta to 2.0 aliases: - /influxdb/v2.0/reference/rc0-upgrade-guide/ - /influxdb/v2.0/reference/rc1-upgrade-guide/ -weight: 7 + - /influxdb/v2.0/reference/upgrading/rc-upgrade-guide/ +weight: 11 --- -To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.0rc0 or later, you must manually upgrade all resources and data to the latest version by completing the following steps: +To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.0rc0 or later, +manually upgrade all resources and data to the latest version by completing the following steps: 1. [Disable existing integrations](#1-disable-existing-integrations) 2. [Stop existing InfluxDB beta instance](#2-stop-existing-influxdb-beta-instance) diff --git a/content/influxdb/v2.0/visualize-data/templates/_index.md b/content/influxdb/v2.0/visualize-data/templates/_index.md deleted file mode 100644 index 4c76ee95b..000000000 --- a/content/influxdb/v2.0/visualize-data/templates/_index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Manage InfluxDB dashboard templates -description: Create, edit, and manage dashboard templates in the InfluxDB user interface (UI). -influxdb/v2.0/tags: [templates] -menu: - influxdb_2_0: - name: Manage dashboard templates - parent: Visualize data -weight: 104 ---- - -Dashboard templates are a way to create and share dashboards across organizations -without starting from scratch. - -### Dashboard template types -The following types of templates are available: - -- **Static templates:** templates included with the InfluxDB user interface (UI). -- **User templates:** custom-built templates saved in the UI. - -{{< children >}} diff --git a/content/influxdb/v2.0/visualize-data/templates/create-template.md b/content/influxdb/v2.0/visualize-data/templates/create-template.md deleted file mode 100644 index 792f9aee7..000000000 --- a/content/influxdb/v2.0/visualize-data/templates/create-template.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Create a template -seotitle: Create an InfluxDB dashboard template -description: Create an InfluxDB dashboard template in the InfluxDB user interface (UI). -influxdb/v2.0/tags: [templates] -menu: - influxdb_2_0: - name: Create a template - parent: Manage dashboard templates -weight: 201 ---- - -## Create a template from an existing dashboard - -1. In the navigation menu on the left, select **Boards** (**Dashboards**). - - {{< nav-icon "dashboards" >}} - -2. Hover over the dashboard you want to use to create the template and click **{{< icon "gear" >}}**. -3. Click **Export**. The dashboard JSON appears in a new window. -4. Click **Save as template**. - - -## Clone a dashboard template - -{{% note %}} -Only [user templates](/influxdb/v2.0/visualize-data/templates/#dashboard-template-types) can be cloned. -{{% /note %}} - -1. In the navigation menu on the left, select **Settings** > **Templates**. - - {{< nav-icon "settings" >}} - -3. Select **User Templates**. - - {{< img-hd src="/img/influxdb/2-0-templates-type-select.png" alt="Select User Templates" />}} - -4. Hover over the template you want to clone and click **{{< icon "clone" >}}**. -5. Click **Clone** to confirm. The cloned template appears in your list. - -## Import an existing dashboard template - -1. In the navigation menu on the left, select **Settings** > **Templates**. - - {{< nav-icon "settings" >}} - -3. Click **Import Template** in the upper right. -4. In the window that appears: - * Select **Upload File** to drag-and-drop or select a file. - * Select **Paste JSON** to paste in JSON. -5. Click **Import JSON as Template**. diff --git a/content/influxdb/v2.0/visualize-data/templates/delete-template.md b/content/influxdb/v2.0/visualize-data/templates/delete-template.md deleted file mode 100644 index 5e1aa6ffb..000000000 --- a/content/influxdb/v2.0/visualize-data/templates/delete-template.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Delete a dashboard template -seotitle: Delete InfluxDB templates -description: Delete templates in the InfluxDB user interface (UI). -influxdb/v2.0/tags: [templates] -menu: - influxdb_2_0: - name: Delete a template - parent: Manage dashboard templates -weight: 203 ---- - -To delete a template in the InfluxDB UI: - -1. In the navigation menu on the left, select **Settings** > **Templates**. - - {{< nav-icon "settings" >}} - -3. Hover over the name of the template you want to delete, then click **{{< icon "trash" >}}**. -3. Click **Delete** to delete your dashboard. diff --git a/content/influxdb/v2.0/visualize-data/templates/use-template.md b/content/influxdb/v2.0/visualize-data/templates/use-template.md deleted file mode 100644 index ccea07508..000000000 --- a/content/influxdb/v2.0/visualize-data/templates/use-template.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Use a template -seotitle: Use an InfluxDB dashboard template -description: > - Use an InfluxDB dashboard template to create a new InfluxDB dashboard. -influxdb/v2.0/tags: [templates] -menu: - influxdb_2_0: - parent: Manage dashboard templates -weight: 202 ---- - -To create a new dashboard from an InfluxDB dashboard template: - -1. In the navigation menu on the left, select **Settings** > **Templates**. - - {{< nav-icon "settings" >}} - -3. Select the [template type](/influxdb/v2.0/visualize-data/templates/#dashboard-template-types). - - {{< img-hd src="/img/influxdb/2-0-templates-type-select.png" alt="Select User Templates" />}} - -4. Hover over the template you want to use and click **Create**. - A notification appears confirming the dashboard was created. -5. Visit the **Dashboards** page to view the newly created dashboard. diff --git a/content/influxdb/v2.0/visualize-data/templates/view-template.md b/content/influxdb/v2.0/visualize-data/templates/view-template.md deleted file mode 100644 index 6c5c9e160..000000000 --- a/content/influxdb/v2.0/visualize-data/templates/view-template.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: View templates -seotitle: View InfluxDB templates -description: View templates in the InfluxDB user interface (UI). -influxdb/v2.0/tags: [templates] -menu: - influxdb_2_0: - name: View templates - parent: Manage dashboard templates -weight: 202 ---- - -To view templates in the InfluxDB userface (UI): - -1. In the navigation menu on the left, select **Settings** > **Templates**. - - {{< nav-icon "settings" >}} - -3. Select templates to view: - - {{< img-hd src="/img/influxdb/2-0-templates-type-select.png" alt="Select User Templates" />}} - - - **Static Templates:** templates included with InfluxDB. - For more information, see [Static templates](#static-templates) below. - - **User Templates** custom-built templates saved in the UI. - -4. Click the name of a template to view its JSON. - -## Static templates -The following Telegraf-related dashboard templates are available: - -- [Apache Data](#apache-data) -- [Docker](#docker) -- [Getting Started with Flux](#getting-started-with-flux) -- [GitHub Data](#github-data) -- [InfluxDB 2.0 OSS Metrics](#influxdb-2-0-oss-metrics) -- [JMeter](#jmeter) -- [Kubernetes](#kubernetes) -- [Nginx](#nginx) -- [Redis](#redis) -- [System](#system) - -### Apache data -The Apache data dashboard template contains an overview of Apache HTTP server metrics. -It displays the following information: - -- Apache Uptime -- CPUs -- Memory -- Memory Used -- Bytes per Second -- Requests per Second -- CPU Load (System, User) -- Load -- Workers -- Disk IO -- Network -- Scoreboard - -#### Plugins -- [`apache` plugin](/{{< latest "telegraf" >}}/plugins//#apache) -- [`cpu` plugin](/{{< latest "telegraf" >}}/plugins//#cpu) -- [`disk` plugin](/{{< latest "telegraf" >}}/plugins//#disk) -- [`diskio` plugin](/{{< latest "telegraf" >}}/plugins//#diskio) -- [`mem` plugin](/{{< latest "telegraf" >}}/plugins//#mem) -- [`net` plugin](/{{< latest "telegraf" >}}/plugins//#net) -- [`netstat` plugin](/{{< latest "telegraf" >}}/plugins//#netstat) -- [`system` plugin](/{{< latest "telegraf" >}}/plugins//#system) - -### Docker -The Docker dashboard template contains an overview of Docker metrics. -It displays the following information: - -- System Uptime -- nCPUs -- System Load -- Total Memory -- Memory Usage -- Disk Usage -- CPU Usage -- System Load -- Swap -- Number of Docker containers -- CPU usage per container -- Memory usage % per container -- Memory usage per container -- Network TX traffic per container/sec -- Network RX traffic per container/sec -- Disk I/O read per container/sec -- Disk I/O write per container/sec - - -#### Plugins - -- [`cpu` plugin](/{{< latest "telegraf" >}}/plugins//#cpu) -- [`disk` plugin](/{{< latest "telegraf" >}}/plugins//#disk) -- [`diskio` plugin](/{{< latest "telegraf" >}}/plugins//#diskio) -- [`docker` plugin](//v2.0/reference/telegraf-plugins/#docker) -- [`mem` plugin](/{{< latest "telegraf" >}}/plugins//#mem) -- [`swap` plugin](/{{< latest "telegraf" >}}/plugins//#swap) -- [`system` plugin](/{{< latest "telegraf" >}}/plugins//#system) - -### Getting Started with Flux -This dashboard is designed to get you started with the Flux language. -It contains explanations and visualizations for a series of increasingly complex example Flux queries. - -- Creating your first basic Flux query -- Filtering data using the `filter` function -- Windowing data with the `window` function -- Aggregating data with the `aggregateWindow` function -- Multiple aggregates using Flux variables and the `yield` function -- Joins and maps with the `join`, `map`, `group`, and `drop` functions - -#### Plugins - -- [`cpu` plugin](/{{< latest "telegraf" >}}/plugins//#cpu) -- [`disk` plugin](/{{< latest "telegraf" >}}/plugins//#disk) - -### GitHub Data -The GitHub Data dashboard template displays data related to GitHub repositories: - -- Total Forks -- Total Size (bytes) -- Total Stars -- Total Open Issues -- Forks -- Size (bytes) -- Stars -- Issues -- Summary - -#### Plugins -- [`github` plugin](/{{< latest "telegraf" >}}/plugins//#github) - - -### InfluxDB 2.0 OSS Metrics -The InfluxDB 2.0 OSS Metrics dashboard shows a visual overview of some of the metrics -available from the local InfluxDB metrics endpoint located at `/metrics`. -It displays the following information: - -- Uptime -- Instance Info -- # of Orgs -- # of Users -- # of Buckets -- # of Tokens -- # of Telegraf configurations -- # of Dashboards -- # of Scrapers -- # of Tasks -- Local Object Store IO -- Memory Allocations (Bytes) -- Memory Usage (%) -- Memory Allocs & Frees (Bytes) - -### JMeter -The JMeter dashboard template provides an overview of JMeter metrics. -It displays the following information: - -- OK requests count -- Avg response time -- Max response time -- Min response time -- 99 and 95 percentile for successful requests -- KO requests count -- Thread/Virtual user count -- Number of hits -- Sent bytes -- Received bytes - -### Kubernetes - -The Kubernetes dashboard gives a visual overview of Kubernetes metrics. -It displays the following information: - -- Allocatable Memory -- Running Pods -- Running Containers -- K8s Node Capacity CPUs -- K8s Node Allocatable CPUs -- DaemonSet -- Capacity Pods -- Allocatable Pods -- Resource Requests CPU -- Resource Limit milliscpu -- Resource Memory -- Node Memory -- Replicas Available -- Persistent Volumes Status -- Running Containers - -#### Plugins -- [`kubernetes` plugin](/{{< latest "telegraf" >}}/plugins//) - -### Nginx -The Nginx dashboard gives a visual overview of Nginx metrics. -It displays the following information: - -- System Uptime -- nCPUs -- System Load -- Total Memory -- Memory Usage -- Disk Usage -- CPU Usage -- System Load -- Swap -- Nginx active connections -- Nginx reading: writing/waiting -- Nginx requests & connections/min -- Network - - -#### Plugins -- [`cpu` plugin](/{{< latest "telegraf" >}}/plugins//#cpu) -- [`disk` plugin](/{{< latest "telegraf" >}}/plugins//#disk) -- [`diskio` plugin](/{{< latest "telegraf" >}}/plugins//#diskio) -- [`mem` plugin](/{{< latest "telegraf" >}}/plugins//#mem) -- [`nginx` plugin](/{{< latest "telegraf" >}}/plugins//#nginx) -- [`swap` plugin](/{{< latest "telegraf" >}}/plugins//#swap) -- [`system` plugin](/{{< latest "telegraf" >}}/plugins//#system) - -### Redis -The Redis dashboard gives a visual overview of Nginx metrics. -It displays the following information: - -- System Uptime -- nCPUs -- System Load -- Total Memory -- Memory Usage -- Disk Usage -- CPU Usage -- System Load -- Swap -- Redis used memory -- Redis CPU -- Redis # commands processed per sec -- Redis eviced/expired keys -- Redis connected slaves -- Keyspace hitrate -- Redis - Network Input/Output -- Redis connections -- Redis uptime - -#### Plugins -- [`cpu` plugin](/{{< latest "telegraf" >}}/plugins//#cpu) -- [`disk` plugin](/{{< latest "telegraf" >}}/plugins//#disk) -- [`mem` plugin](/{{< latest "telegraf" >}}/plugins//#mem) -- [`redis` plugin](/{{< latest "telegraf" >}}/plugins//#redis) -- [`swap` plugin](/{{< latest "telegraf" >}}/plugins//#swap) -- [`system` plugin](/{{< latest "telegraf" >}}/plugins//#system) - - -### System -The System dashboard gives a visual overview of system metrics. -It displays the following information: - -- System Uptime -- nCPUs -- System Load -- Total Memory -- Memory Usage -- Disk Usage -- CPU Usage -- System Load -- Disk IO -- Network -- Processes -- Swap - -#### Plugins -- [`disk` plugin](/{{< latest "telegraf" >}}/plugins//#disk) -- [`diskio` plugin](/{{< latest "telegraf" >}}/plugins//#diskio) -- [`mem` plugin](/{{< latest "telegraf" >}}/plugins//#mem) -- [`net` plugin](/{{< latest "telegraf" >}}/plugins//#net) -- [`swap` plugin](/{{< latest "telegraf" >}}/plugins//#swap) -- [`system` plugin](/{{< latest "telegraf" >}}/plugins//#system) diff --git a/content/influxdb/v2.0/visualize-data/visualization-types/band.md b/content/influxdb/v2.0/visualize-data/visualization-types/band.md index 19b006897..bf5ed5f81 100644 --- a/content/influxdb/v2.0/visualize-data/visualization-types/band.md +++ b/content/influxdb/v2.0/visualize-data/visualization-types/band.md @@ -1,20 +1,91 @@ --- -title: Band visualization +title: Band Plot visualization list_title: Band list_image: /img/influxdb/2-0-visualizations-Band-example.png description: weight: 206 menu: influxdb_2_0: - name: Band + name: Band Plot parent: Visualization types --- -The **Band** visualization displays the upper and lower boundaries for groups of data over time. +The **Band Plot** visualization displays the upper and lower boundaries for groups of data over time. Boundaries are determined by applying aggregate functions to your data for a specified window period, and then setting the aggregate functions for a specified upper, main, or lower boundary. + +## Set up the Band Plot visualization + +To see bands (boundaries) in the **Band Plot** visualization, you must set up two or three boundaries for comparison. + +### Set up the band plot visualization in the Data Explorer + +1. Click the **Data Explorer** icon in the navigation bar. + + {{< nav-icon "data-explorer" >}} + +2. Enter your query (see [Explore data with Flux and the Data Explorer](/influxdb/v2.0/visualize-data/explore-metrics/#explore-data-with-flux-and-the-data-explorer)). You must include the aggregate functions used to determine the Band Plot visualization boundaries in your query. +3. Select the **Band Plot** option from the visualization dropdown in the upper left, and then click **Customize**. +4. Under **Data**, select the following: + - For **X Column** and **Y Column**, select the columns to display for the x- and y- axes. + - For **Time Format**, select the timestamp format to display in the visualization. +5. Under **Aggregate Functions**, select a function to determine each boundary (column) for comparison (select two or three): + - In the **Upper Column Name** field, select a function for the upper boundary. + - In the **Main Column Name** field, select a function for the main boundary. + - In the **Lower Column Name** field, select a function for the lower boundary. +6. (Optional) Continue to customize your visualization, including options such as interpolation, color, hover dimension, and y-axis settings. For more information, see [Options](options) and [Y Axis](y-axis) below. + + **Tip:** If you do not see shaded boundaries in the **Band Plot** visualization, verify the query window period includes a sufficient number of data points for the selected aggregate function. By default, the window period is automatically set to ten seconds (`10s`). To adjust your window period, select **Custom**, and then enter a supported time unit (for example nanoseconds (`ns`), microseconds (`us`), milliseconds (`ms`), seconds (`s`), or hours (`h`). {{< img-hd src="/img/influxdb/2-0-visualizations-Band-example.png" alt="Band example" />}} -To view a band chart, select the **Band** option from the visualization dropdown in the upper left. +### Set up the band plot visualization in the Script Editor + +1. Click the **Data Explorer** icon in the navigation bar. + + {{< nav-icon "data-explorer" >}} + +2. Click **Script Editor**. +3. Select the **Band Plot** option from the visualization dropdown in the upper left. +4. Create three aggregate functions: one for the main boundary, one for the upper boundary, and one for the lower boundary. The following example uses the [`mean()`](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/mean/), [`max()`](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/selectors/max/), and [`min()`](/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/selectors/min) functions: + +```js +from(bucket: "bucket_1") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r["_measurement"] == "cpu") + |> filter(fn: (r) => r["_field"] == "usage_system") + |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") + |> aggregateWindow(every: 15s, fn: mean, createEmpty: false) + |> yield(name: "mean") + +from(bucket: "bucket_1") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r["_measurement"] == "cpu") + |> filter(fn: (r) => r["_field"] == "usage_system") + |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") + |> aggregateWindow(every: 15s, fn: max, createEmpty: false) + |> yield(name: "max") + +from(bucket: "bucket_1") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r["_measurement"] == "cpu") + |> filter(fn: (r) => r["_field"] == "usage_system") + |> filter(fn: (r) => r["cpu"] == "cpu0" or r["cpu"] == "cpu1") + |> aggregateWindow(every: 15s, fn: min, createEmpty: false) + |> yield(name: "min") +``` + +5. (Optional) Customize the name of the yielded results for each function by editing the `name` parameter in the [`yield()`](/v2.0/reference/flux/stdlib/built-in/outputs/yield/) function. +For example, to change the name of the first function from `mean` to `Average`, modify the last line to the following: + ```js + |> yield(name: "Average") + ``` +6. Click **Customize** in the upper left. +7. Under **Aggregate Functions**, enter the functions you created to determine each boundary (column) for comparison. If you changed the `yield` name for any of the functions above, enter the modified name here instead of the function name: + - In the **Upper Column Name** field, enter the result set to use for the upper boundary. + - In the **Main Column Name** field, enter the result set to use for the main boundary. + - In the **Lower Column Name** field, enter the function for the lower boundary. +7. (Optional) Continue to customize your visualization, including options such as interpolation, color, hover dimension, and y-axis settings. For more information, see [Options](options) and [Y Axis](y-axis) below. + +### Customize column names ## Band behavior diff --git a/content/influxdb/v2.0/write-data/_index.md b/content/influxdb/v2.0/write-data/_index.md index 9c17efc9c..f93b8fc3f 100644 --- a/content/influxdb/v2.0/write-data/_index.md +++ b/content/influxdb/v2.0/write-data/_index.md @@ -19,17 +19,16 @@ related: - /influxdb/v2.0/reference/cli/influx/write --- -Discover what you'll need to write data into InfluxDB Cloud or OSS (open source). Learn how to quickly start collecting data, and then explore ways to write data, best practices, and what we recommend if you're migrating a large amount of historical data. +Discover what you'll need to write data into InfluxDB OSS (open source). Learn how to quickly start collecting data, and then explore ways to write data, best practices, and what we recommend if you're migrating a large amount of historical data. -- [What you'll need](#what-you-ll-need) +- [What you'll need](#what-youll-need) - [Quickly start collecting data](#quickly-start-collecting-data) - - [Demo data for InfluxDB Cloud](#demo-data-for-influxdb-cloud) - [Quick Start for InfluxDB OSS](#quick-start-for-influxdb-oss) + - [Sample data](#sample-data) - [Load data from sources in the InfluxDB UI](/influxdb/v2.0/write-data/load-data/) - [Use no-code solutions](/influxdb/v2.0/write-data/no-code) - [Use developer tools](/influxdb/v2.0/write-data/developer-tools) - [Best practices for writing data](/influxdb/v2.0/write-data/best-practices/) -- [Migrate historical data](/influxdb/v2.0/write-data/bulk-ingest-cloud/) - [Next steps](#next-steps) ### What you'll need @@ -83,63 +82,8 @@ and [Best practices for writing data](/influxdb/v2.0/write-data/best-practices/) Familiarize yourself with querying, visualizing, and processing data in InfluxDB Cloud and InfluxDB OSS by collecting data right away. The following options are available: -- [Demo data for InfluxDB Cloud](#demo-data-for-influxdb-cloud) - [Quick Start for InfluxDB OSS](#quick-start-for-influxdb-oss) - - -## Demo data for InfluxDB Cloud -Use **InfluxDB Cloud** demo data buckets for quick and easy access to different -types of demo data that let you explore and familiarize yourself with InfluxDB Cloud. - -{{< youtube GSaByPC1Bdc >}} - -- [Add a demo data bucket](#add-a-demo-data-bucket) -- [Explore demo data](#explore-demo-data) -- [View demo data dashboards](#view-demo-data-dashboards) - -{{% note %}} -#### Free to use and read-only -- InfluxDB Cloud demo data buckets are **free to use** and are **_not_ subject to - [Free Plan](/influxdb/v2.0/account-management/pricing-plans/#free-plan) rate limits**. -- Demo data buckets are **read-only**. You cannot write data into demo data buckets. -{{% /note %}} - -## Demo data sets -Choose from the following demo data sets: - -- **Website Monitoring** - Explore, visualize, and monitor HTTP response metrics from InfluxData websites. - - -## Add a demo data bucket -1. In the navigation menu on the left, click **Data (Load Data)** > **Buckets**. - - {{< nav-icon "data" >}} - -2. Click **{{< icon "plus" >}} Add Demo Data**, and then select the demo data bucket to add. -3. The Demo Data bucket appears in your list of buckets. - -## Explore demo data -Use the [Data Explorer](/influxdb/v2.0/visualize-data/explore-metrics/) -to query and visualize data in demo data buckets. - -In the navigation menu on the left, click **Explore (Data Explorer)**. - -{{< nav-icon "explore" >}} - -## View demo data dashboards -After adding a demo data bucket, view the pre-built dashboard specific to the demo data set: - -1. In the navigation menu on the left, click **Boards (Dashboards)**. - - {{< nav-icon "dashboards" >}} - -2. Click the name of the dashboard that corresponds to your demo data bucket. - -{{% note %}} -#### Other sample data sets -See [Sample data](/influxdb/v2.0/reference/sample-data) for more sample InfluxDB data sets. -{{% /note %}} +- [Sample data](#sample-data) ## Quick Start for InfluxDB OSS @@ -166,6 +110,10 @@ If you missed the Quick Start option, you can [manually create a scraper](/influ that scrapes data from the `/metrics` endpoint. {{% /note %}} +## Sample data +Use [sample data sets](/influxdb/v2.0/reference/sample-data/) to quickly populate +InfluxDB with sample time series data. + --- ## Next steps diff --git a/content/influxdb/v2.0/write-data/delete-data.md b/content/influxdb/v2.0/write-data/delete-data.md index 4217c56d2..0e3164563 100644 --- a/content/influxdb/v2.0/write-data/delete-data.md +++ b/content/influxdb/v2.0/write-data/delete-data.md @@ -48,12 +48,12 @@ Delete data from buckets you've created. You cannot delete data from system buck 4. Click **Confirm Delete** to delete the selected data. !--> -Use the `influx` CLI or the InfluxDB API `/delete` endpoint to delete data. +Use the `influx` CLI or the InfluxDB API [`/delete`](/influxdb/v2.0/api/#/paths/~1delete/post) endpoint to delete data. {{% note %}} -The `-p, --predicate` flag is supported in **InfluxDB Cloud** and **InfluxDB OSS 2.0 beta 16 or earlier**. +In **InfluxDB OSS 2.0**, the `influx delete --predicate` flag has been disabled. -In **InfluxDB OSS 2.0rc**, the `influx delete --predicate` flag has been disabled. +The `-p, --predicate` flag is supported in **InfluxDB Cloud** and **InfluxDB OSS 2.0 beta 16 or earlier**. {{% /note %}} ## Delete data using the influx CLI @@ -85,14 +85,14 @@ influx delete -o my-org -b my-bucket -t $INFLUX_TOKEN \ ``` {{% warn %}} -Running `influx delete` without the `-p` or `--predicate` flag deletes all data with +Deleting data in OSS (because the `-p` or `--predicate` flag is not implemented) deletes all data with timestamps between the specified `--start` and `--stop` times in the specified bucket. {{% /warn %}} ## Delete data using the API {{% note %}} -The `influx` CLI is installed with **InfluxDB OSS**. If you're using **InfluxDB Cloud** and haven't already, download the [`influx` CLI](/influxdb/v2.0/get-started/#optional-download-install-and-use-the-influx-cli). +The `influx` CLI is installed with **InfluxDB OSS**. If you're using **InfluxDB Cloud** and haven't already, download the [`influx` CLI](/influxdb/v2.0/get-started/). {{% /note %}} 1. Use the InfluxDB API `/delete` endpoint to delete points from InfluxDB. diff --git a/content/influxdb/v2.0/write-data/no-code/use-telegraf/manual-config.md b/content/influxdb/v2.0/write-data/no-code/use-telegraf/manual-config.md index 5fb2a0bc1..7d68e523b 100644 --- a/content/influxdb/v2.0/write-data/no-code/use-telegraf/manual-config.md +++ b/content/influxdb/v2.0/write-data/no-code/use-telegraf/manual-config.md @@ -113,7 +113,7 @@ set INFLUX_TOKEN=YourAuthenticationToken {{% /tab-content %}} {{< /tabs-wrapper >}} -_See the [example `telegraf.conf` below](#example-influxdb-v2-configuration)._ +_See the [example `telegraf.conf` below](#example-influxdb_v2-configuration)._ {{% /note %}} ##### organization diff --git a/content/platform/_index.md b/content/platform/_index.md index eaaaada27..fa6890521 100644 --- a/content/platform/_index.md +++ b/content/platform/_index.md @@ -30,8 +30,8 @@ The **InfluxData 1.x platform** includes the following open source components ([ The **InfluxDB 2.0 platform** consolidates components from the **InfluxData 1.x platform** into a single packaged solution, with added features and flexibility: - - [InfluxDB 2.0 OSS](/influxdb/v2.0/get-started/): open source platform solution in a single binary - - [InfluxDB Cloud 2.0](/influxdb/v2.0/get-started/) (**commercial offering**): hosted cloud solution + - [InfluxDB OSS 2.0](/influxdb/v2.0/get-started/): open source platform solution in a single binary + - [InfluxDB Cloud](/influxdb/cloud/get-started/) (**commercial offering**): hosted cloud solution InfluxDB Enterprise 2.0 is in development. @@ -145,4 +145,4 @@ To get started with the **InfluxData 1.x** platform, see [Installation and Configuration](/platform/install-and-deploy/) [Getting Started](/platform/introduction/getting-started) -To get started with the **InfluxDB 2.0** platform, see [**InfluxDB Cloud 2.0**](/influxdb/v2.0/get-started/) or [**InfluxDB 2.0 OSS**](/influxdb/v2.0/get-started/). +To get started with the **InfluxDB 2.0** platform, see [**InfluxDB Cloud**](/influxdb/cloud/get-started/) or [**InfluxDB OSS 2.0**](/influxdb/v2.0/get-started/). diff --git a/content/platform/_index.md~master b/content/platform/_index.md~master deleted file mode 100644 index ca1755bae..000000000 --- a/content/platform/_index.md~master +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Introduction to the InfluxData platform -description: The InfluxData platform is the leading modern time-series platform built for metrics and events. -aliases: - - /platform/introduction -menu: - platform: - name: Introduction -weight: 1 ---- - -**InfluxData platform** is the leading modern [time series](/platform/faq/#what-is-time-series-data) platform, built for metrics and events. Explore both versions of our platform below--[**InfluxData 1.x**](#influxdata-1-x) and [**InfluxDB 2.0**](#influxdb-2-0). - -## InfluxData 1.x - -The **InfluxData 1.x platform** includes the following open source components ([TICK stack](#tick-stack-components)): - - - [Telegraf](#telegraf): collect data - - [InfluxDB](#influxdb): store data - - [Chronograf](#chronograf): visualize data - - [Kapacitor](#kapacitor): process data and alerts - -**InfluxData 1.x** also includes the following **commercial offerings**: - - - [InfluxDB Enterprise](#influxdb-enterprise) - - [Kapacitor Enterprise](#kapacitor-enterprise) - - [InfluxCloud 1.x](https://help.influxcloud.net) (hosted cloud solution) - -## InfluxDB 2.0 - -The **InfluxDB 2.0 platform** consolidates components from the **InfluxData 1.x platform** into a single packaged solution, with added features and flexibility: - - - [InfluxDB 2.0 OSS](/influxdb/v2.0/get-started/): open source platform solution in a single binary - - [InfluxDB Cloud 2.0](/influxdb/v2.0/get-started/) (**commercial offering**): hosted cloud solution - -InfluxDB Enterprise 2.0 is in development. - -## InfluxData 1.x TICK stack - -### Telegraf - -Telegraf is a data collection agent that captures data from a growing list of sources -and translates it into [InfluxDB line protocol format](/{{< latest "influxdb" "v1" >}}/write_protocols/line_protocol_reference/) -for storage in InfluxDB. Telegraf's extensible architecture makes it easy to -create [plugins](/{{< latest "telegraf" >}}/plugins/) that both pull data (input plugins) and push data (output plugins) -to and from different sources and endpoints. - -### InfluxDB - -InfluxDB stores data for any use case involving large amounts of timestamped data, including -DevOps monitoring, log data, application metrics, IoT sensor data, and real-time analytics. -It provides functionality that allows you to conserve space on your machine by keeping -data for a defined length of time, then automatically downsampling or expiring and deleting -unneeded data from the system. - -### Chronograf - -Chronograf is the user interface for the TICK stack that provides customizable dashboards, -data visualizations, and data exploration. It also allows you to view and manage -[Kapacitor](#kapacitor) tasks. - -### Kapacitor - -Kapacitor is a data processing framework that enables you to process and act on data -as it is written to InfluxDB. This includes detecting anomalies, creating alerts -based on user-defined logic, and running ETL jobs. - -## InfluxData 1.x Enterprise versions - -InfluxDB Enterprise and Kapacitor Enterprise provide clustering, access control, and incremental backup functionality for production infrastructures at scale. You'll also receive direct support from the InfluxData support team. - -{{% note %}} -InfluxDB Enterprise and Kapacitor Enterprise are compatible with open source versions of Telegraf and Chronograf. -{{% /note %}} - -### InfluxDB Enterprise - -InfluxDB Enterprise provides functionality necessary to run a high-availability (HA) InfluxDB cluster, providing clustering, horizontal scale out, and advanced access controls, including: - -- Hinted handoff -- Anti-entropy -- Fine-grained authorization -- Cluster profiling -- Incremental backups - -#### Hinted handoff - -Data is written across nodes using an eventually consistent write model. -All writes are added to the [Hinted Handoff Queue (HHQ)](/{{< latest "enterprise_influxdb" >}}/concepts/clustering/#hinted-handoff), -then written to other nodes in the cluster. - -#### Anti-Entropy - -InfluxDB Enterprise's -[Anti-Entropy (AE)](/{{< latest "enterprise_influxdb" >}}/administration/anti-entropy/) -process ensures data shards in the cluster are in sync. When "entropy" (out-of-sync -data) is detected, AE will repair the affected shards, syncing the missing data. - -#### Fine-grained authorization - -In InfluxDB Enterprise, fine-grained authorization can be used to control access -at the measurement or series levels rather than just the database level. - -#### Cluster profiling - -Enterprise meta nodes expose the `/debug/pprof` API endpoint that allows you to -profile and potentially diagnose performance bottlenecks in your cluster. - -#### Incremental backups - -InfluxDB Enterprise allows for incremental backups that write only newly added -data to existing backup files rather than backing up all data in a new backup. - -### Kapacitor Enterprise - -Kapacitor Enterprise provides functionality necessary to run a high-availability -Kapacitor cluster, including: - -- Kapacitor cluster management -- Alert deduplication -- Secure communication - -#### Kapacitor cluster management - -Kapacitor Enterprise is packaged with `kapactorctl`, a command line client for creating -and managing Kapacitor clusters. - -#### Alert deduplication - -As alerts are triggered in a multi-node Kapacitor cluster, Kapacitor Enterprise -deduplicates alert data to prevent duplicate alert notifications from being sent. - -#### Secure communication - -Data is passed between InfluxDB and Kapacitor via subscriptions. -Kapacitor Enterprise includes configuration options that let you encrypt -communication between your Kapacitor Enterprise and InfluxDB Enterprise clusters. - -Try InfluxData Platform Enterprise - -## Get started - -To get started with the **InfluxData 1.x** platform, see - -[Installation and Configuration](/platform/installation) -[Getting Started](/platform/introduction/getting-started) - -To get started with the **InfluxDB 2.0** platform, see [**InfluxDB Cloud 2.0**](/influxdb/v2.0/get-started/) or [**InfluxDB 2.0 OSS**](/influxdb/v2.0/get-started/). diff --git a/content/platform/getting-started.md~master b/content/platform/getting-started.md~master deleted file mode 100644 index c02bf34b3..000000000 --- a/content/platform/getting-started.md~master +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Get started with the InfluxData Platform -description: placeholder -aliases: - - /platform/introduction/getting-started -menu: - platform: - name: Get started -weight: 2 ---- -## Overview - -![Getting started setup](/img/chronograf/1-6-intro-gs-diagram.png) - -Before following the steps below, [download and install](/platform/install-and-deploy/install/) each component of the TICK stack, or [Install the InfluxData Sandbox](/platform/install-and-deploy/deploying/sandbox-install/). - -## Understand how Telegraf writes data to InfluxDB - -Once Telegraf is installed and started, it will send system metrics to InfluxDB by default, which automatically creates a ‘telegraf’ database. - -The configuration file for Telegraf specifies where metrics come from and where they go (inputs and outputs). In this example, we'll focus on CPU data, which is one of the default system metrics generated by Telegraf. For this example, it is worth noting some relevant values: - -* `[agent].interval` - declares the frequency at which system metrics will be sent to InfluxDB. -* `[[outputs.influxdb]]` - declares how to connect to InfluxDB and the destination database, which is the default ‘telegraf’ database. -* `[[inputs.cpu]]` - declares how to collect the system cpu metrics to be sent to InfluxDB. Enabled by default. - -For details about the configuration file, see [Get started with Telegraf](/{{< latest "telegraf" >}}/introduction/getting-started/). - -## Query data in InfluxDB - -As reviewed above, Telegraf is sending system data, including CPU usage, to InfluxDB. There are two ways you can query your InfluxDB data: - -* [In Chronograf with the Data Explorer.](/{{< latest "chronograf" >}}/guides/create-a-dashboard/#step-3-create-your-query) Use the builder to select from your existing data and allow Chronograf to format the query for you. Alternatively, manually enter and edit a query. You can move between using the builder and manually editing the query. -* [Using the command line interface.](/{{< latest "influxdb" "v1" >}}/query_language/data_exploration/) - - -**Query example:** -```sql -SELECT "usage_system", - "usage_user" -FROM "telegraf"."autogen"."cpu" -WHERE time > now() - 30m -``` - -## Visualize that data in a Chronograf dashboard - -Now that you've explored your data with queries, you can build a dashboard in Chronograf to visualize the data. For details, see [Create a dashboard](/{{< latest "chronograf" >}}/guides/create-a-dashboard) and [Using pre-created dashboards](/{{< latest "chronograf" >}}/guides/using-precreated-dashboards/). - -## Create an alert in Kapacitor based on that data - -Since InfluxDB is running on `localhost:8086`, Kapacitor finds it during start up and creates several subscriptions on InfluxDB. These subscriptions tell InfluxDB to send all the data it receives from Telegraf to Kapacitor. - -For step-by-step instructions on how to set up an alert in Kapacitor based on your data, see [Creating Chronograf alert rules](/{{< latest "chronograf" >}}/guides/create-alert-rules/). diff --git a/data/influxdb_urls.yml b/data/influxdb_urls.yml index c11331a1c..f1d21f519 100644 --- a/data/influxdb_urls.yml +++ b/data/influxdb_urls.yml @@ -17,6 +17,9 @@ cloud: - name: US West (Oregon) location: Oregon, USA url: https://us-west-2-1.aws.cloud2.influxdata.com + - name: US East (Virginia) + location: Virginia, USA + url: https://us-east-1-1.aws.cloud2.influxdata.com - name: EU Frankfurt location: Frankfurt, Germany url: https://eu-central-1-1.aws.cloud2.influxdata.com diff --git a/data/products.yml b/data/products.yml index 05aad536a..c6ead28d3 100644 --- a/data/products.yml +++ b/data/products.yml @@ -1,42 +1,45 @@ influxdb: name: InfluxDB - altname: InfluxDB Cloud & OSS + altname: InfluxDB OSS namespace: influxdb - list_order: 1 + list_order: 2 versions: [v1.3, v1.4, v1.5, v1.6, v1.7, v1.8, v2.0] - latest: v1.8 + latest: v2.0 latest_override: v2.0 - # Used in cloud-name and cloud-link shortcodes - cloud: - name: "InfluxDB Cloud 2.0" - shortname: "InfluxDB Cloud" - link: "https://cloud2.influxdata.com/signup" +influxdb_cloud: + name: InfluxDB Cloud + altname: InfluxDB Cloud + namespace: influxdb + versions: [cloud] + list_order: 1 + latest: cloud + link: "https://cloud2.influxdata.com/signup" telegraf: name: Telegraf namespace: telegraf - list_order: 2 + list_order: 4 versions: [v1.9, v1.10, v1.11, v1.12, v1.13, v1.14, v1.15, v1.16] latest: v1.16 chronograf: name: Chronograf namespace: chronograf - list_order: 3 + list_order: 5 versions: [v1.6, v1.7, v1.8] latest: v1.8 kapacitor: name: Kapacitor namespace: kapacitor - list_order: 4 + list_order: 6 versions: [v1.4, v1.5] latest: v1.5 enterprise_influxdb: name: "InfluxDB Enterprise" namespace: enterprise_influxdb - list_order: 5 + list_order: 3 versions: [v1.5, v1.6, v1.7, v1.8] latest: v1.8 diff --git a/deploy/edge.js b/deploy/edge.js index 11c0b28c7..d7a1b79f3 100644 --- a/deploy/edge.js +++ b/deploy/edge.js @@ -3,7 +3,7 @@ const path = require('path'); const latestVersions = { - 'influxdb': 'v1.8', + 'influxdb': 'v2.0', 'influxdbv2': 'v2.0', 'telegraf': 'v1.16', 'chronograf': 'v1.8', diff --git a/layouts/_default/landing-influxdb.html b/layouts/_default/landing-influxdb.html index 5b632b656..01f2a95aa 100644 --- a/layouts/_default/landing-influxdb.html +++ b/layouts/_default/landing-influxdb.html @@ -4,6 +4,7 @@ {{ $productPathData := findRE "[^/]+.*?" .RelPermalink }} {{ $product := index $productPathData 0 }} {{ $currentVersion := index $productPathData 1 }} +{{ $isCloud := eq $currentVersion "cloud" }}
{{ partial "sidebar.html" . }} @@ -12,9 +13,13 @@
-

Get started with InfluxDB {{ replaceRE "v" "" $currentVersion }}

- Start with InfluxDB Cloud - Start with InfluxDB OSS + {{ if $isCloud }} +

Get started with InfluxDB Cloud

+ Get started + {{ else }} +

Get started with InfluxDB OSS {{ replaceRE "v" "" $currentVersion }}

+ Get started + {{ end }}
{{ partial "svgs/hive.svg" }}
diff --git a/layouts/index.html b/layouts/index.html index 2e05da91d..a728b2bbe 100644 --- a/layouts/index.html +++ b/layouts/index.html @@ -13,13 +13,16 @@
{{ partial "svgs/homepage-hero.svg" }}
-

InfluxDB Cloud &
InfluxDB {{ $influxdbVersionV2 }} OSS

+

InfluxDB Cloud &
InfluxDB OSS {{ replaceRE "v" "" $influxdbVersionV2 }}

The most powerful time series database. Designed to handle high write and query loads. - Run in the cloud with InfluxDB Cloud or on your own hardware with InfluxDB {{ $influxdbVersionV2 }} OSS. + Run in the cloud with InfluxDB Cloud or on your own hardware with InfluxDB OSS {{ replaceRE "v" "" $influxdbVersionV2 }}.

- View InfluxDB {{ $influxdbVersionV2 }} Documentation +
+ InfluxDB Cloud Docs + InfluxDB OSS {{ replaceRE "v" "" $influxdbVersionV2 }} Docs +
diff --git a/layouts/partials/article.html b/layouts/partials/article.html index 9249b3e7e..9614c45a1 100644 --- a/layouts/partials/article.html +++ b/layouts/partials/article.html @@ -1,7 +1,6 @@

{{ .Title }}

- {{ partial "article/product-tags.html" . }} {{ partial "article/stable-version.html" . }} {{ partial "article/flux-experimental.html" . }} {{ partial "article/flux-contrib.html" . }} diff --git a/layouts/partials/article/feedback.html b/layouts/partials/article/feedback.html index 6935d5461..8fd4f16b2 100644 --- a/layouts/partials/article/feedback.html +++ b/layouts/partials/article/feedback.html @@ -1,4 +1,5 @@ {{ $productPathData := findRE "[^/]+.*?" .RelPermalink }} +{{ $latestV2 := cond (isset .Site.Data.products.influxdb "latest_override") .Site.Data.products.influxdb.latest_override .Site.Data.products.influxdb.latest }} {{ .Scratch.Set "product" (index $productPathData 0) }} {{ if in (.Scratch.Get "product") "influxdb" }} {{ .Scratch.Set "product" "influxdb" }} @@ -10,6 +11,9 @@ {{ if .File }} {{ .Scratch.Set "pageGithubLink" (print "https://github.com/influxdata/docs-v2/edit/master/content/" .File.Path) }} + {{ if .Page.HasShortcode "duplicate-oss" }} + {{ .Scratch.Set "pageGithubLink" (replaceRE "/cloud/" (print "/" $latestV2 "/") (.Scratch.Get "pageGithubLink")) }} + {{ end }} {{ else }} {{ .Scratch.Set "pageGithubLink" (print "https://github.com/influxdata/docs-v2/edit/master/content/") }} {{ end }} diff --git a/layouts/partials/article/product-tags.html b/layouts/partials/article/product-tags.html deleted file mode 100644 index f52efc1a4..000000000 --- a/layouts/partials/article/product-tags.html +++ /dev/null @@ -1,12 +0,0 @@ -{{ if .Params.products }} -

- {{ range .Params.products }} - {{ $product := . }} - {{ $scratch := newScratch }} - {{ if eq $product "oss"}}{{ $scratch.Set "product-tag" "OSS" }}{{ end }} - {{ if eq $product "cloud"}}{{ $scratch.Set "product-tag" "Cloud" }}{{ end }} - {{ if eq $product "enterprise"}}{{ $scratch.Set "product-tag" "Enterprise" }}{{ end }} - InfluxDB {{ $scratch.Get "product-tag"}} only - {{ end }} -

-{{ end }} diff --git a/layouts/partials/article/stable-version.html b/layouts/partials/article/stable-version.html index c30b4281b..d8dfa5e11 100644 --- a/layouts/partials/article/stable-version.html +++ b/layouts/partials/article/stable-version.html @@ -9,8 +9,9 @@ {{ $v2EquivalentURL := replaceRE `v[1-2]\.[0-9]{1,2}` $latestV2 .Page.Params.v2 }} {{ $v2EquivalentPage := .GetPage (replaceRE `\/$` "" $v2EquivalentURL) }} {{ $v2PageExists := gt (len $v2EquivalentPage.Title) 0 }} +{{ $isCloud := in .Page.RelPermalink "/influxdb/cloud/"}} -{{ if lt $currentVersion $stableVersion }} +{{ if and (lt $currentVersion $stableVersion) (not $isCloud) }}

This page documents an earlier version of {{ $productName }}. diff --git a/layouts/partials/footer/influxdb-url-modal.html b/layouts/partials/footer/influxdb-url-modal.html index 17446e0d9..1cf1af7f3 100644 --- a/layouts/partials/footer/influxdb-url-modal.html +++ b/layouts/partials/footer/influxdb-url-modal.html @@ -1,53 +1,99 @@ -{{ $currentVersion := index (findRE "[^/]+.*?" .RelPermalink) 0 | default "v2.0" }} +{{ $latestInfluxDBVersion := cond (isset .Site.Data.products.influxdb "latest_override" ) .Site.Data.products.influxdb.latest_override .Site.Data.products.influxdb.latest }} +{{ $OSSLink := print "/influxdb/" $latestInfluxDBVersion "/reference/urls/ "}} +{{ $CloudLink := "/influxdb/cloud/reference/regions/" }} +{{ $isInfluxDB := cond (in .RelPermalink "/influxdb/") true false }} +{{ $isOSS := cond (in .RelPermalink "/influxdb/v") true false }} +{{ $isCloud := cond (in .RelPermalink "/influxdb/cloud/") true false }} + +{{ .Scratch.Set "modalTitle" "Where are you running InfluxDB?" }} +{{ if $isOSS }} + {{ .Scratch.Set "modalTitle" "What is your InfluxDB OSS URL?"}} +{{ else if $isCloud }} + {{ .Scratch.Set "modalTitle" "Select your InfluxDB Cloud region" }} +{{ end }} + +{{ .Scratch.Set "modalMessage" "Select your **InfluxDB Cloud region** or your **InfluxDB OSS URL** and we'll customize code examples for you." }} +{{ if $isOSS }} + {{ .Scratch.Set "modalMessage" "Customize your **InfluxDB OSS URL** and we'll update code examples for you." }} +{{ else if $isCloud }} + {{ .Scratch.Set "modalMessage" "Select your **InfluxDB Cloud region** and we'll customize code examples for you." }} +{{ end }} + +{{ .Scratch.Set "modalRefLinks" (print "[InfluxDB Cloud regions](" $CloudLink ") or [InfluxDB OSS URLs](" $OSSLink ")") }} +{{ if $isOSS }} + {{ .Scratch.Set "modalRefLinks" (print "[InfluxDB OSS URLs](" $OSSLink ")") }} +{{ else if $isCloud }} + {{ .Scratch.Set "modalRefLinks" (print "[InfluxDB Cloud regions](" $CloudLink ")") }} +{{ end }} + +{{ $modalTitle := .Scratch.Get "modalTitle" }} +{{ $modalMessage := .Scratch.Get "modalMessage" }} +{{ $modalRefLinks := .Scratch.Get "modalRefLinks" }} + +{{ define "productSection" }} + {{ $p := .product }} + {{ $formID := .formID }} + {{ $initialState := .initialState | default "" }} +

+
+ {{ range $p.providers }} +
+ {{ if eq .name "Custom" }} +
Custom
+
    +
  • + +
    + + +
    • +
+ {{ else }} +
{{ if .short_name}}{{ .short_name }}{{ else }}{{ .name }}{{ end }}
+
    + {{ range .regions }} +
  • + +
    • + {{ end }} + {{ end }} +
+
+ {{ end }} +
+
+{{ end }} +
-

Where are you running InfluxDB?

-

Select where you're using InfluxDB Cloud or InfluxDB OSS and we'll customize code examples with your InfluxDB URL.

+

{{ $modalTitle }}

+

{{ $modalMessage | markdownify }}

- {{ range sort .Site.Data.influxdb_urls "product" "desc" }} -
-

{{ .product }}

-
- {{ range .providers }} -
- {{ if eq .name "Custom" }} -
Custom
-
    -
  • - -
    - - -
    • -
- {{ else }} -
{{ if .short_name}}{{ .short_name }}{{ else }}{{ .name }}{{ end }}
-
    - {{ range .regions }} -
  • - -
    • - {{ end }} - {{ end }} -
-
- {{ end }} -
-
+ {{ if not $isInfluxDB }} +
    +
  • InfluxDB Cloud
    • +
  • InfluxDB OSS or Enterprise
    • +
+ {{ template "productSection" dict "product" .Site.Data.influxdb_urls.cloud "formID" "cloud" "initialState" "active"}} + {{ template "productSection" dict "product" .Site.Data.influxdb_urls.oss "formID" "oss" "initialState" "inactive"}} + {{ else if $isCloud }} + {{ template "productSection" dict "product" .Site.Data.influxdb_urls.cloud "formID" "cloud" }} + {{ else if $isOSS }} + {{ template "productSection" dict "product" .Site.Data.influxdb_urls.oss "formID" "oss" }} {{ end }}
-

For more information, see InfluxDB URLs.

+

For more information, see {{ $modalRefLinks | markdownify }}.

diff --git a/layouts/partials/footer/javascript.html b/layouts/partials/footer/javascript.html index 97df84c1d..c237b1da4 100644 --- a/layouts/partials/footer/javascript.html +++ b/layouts/partials/footer/javascript.html @@ -3,8 +3,9 @@ {{ $searchInteractions := resources.Get "js/search-interactions.js" }} {{ $telegrafFilters := resources.Get "js/telegraf-filters.js" }} {{ $influxdbURLs := resources.Get "js/influxdb-url.js" }} +{{ $featureCallouts := resources.Get "js/feature-callouts.js" }} {{ $notifications := resources.Get "js/notifications.js" }} -{{ $footerjs := slice $versionSelector $contentInteractions $searchInteractions $telegrafFilters $influxdbURLs $notifications | resources.Concat "js/footer.bundle.js" | resources.Fingerprint }} +{{ $footerjs := slice $versionSelector $contentInteractions $searchInteractions $telegrafFilters $influxdbURLs $featureCallouts $notifications | resources.Concat "js/footer.bundle.js" | resources.Fingerprint }}