diff --git a/assets/styles/layouts/_inline-icons.scss b/assets/styles/layouts/_inline-icons.scss index a67acf95c..4d58b2568 100644 --- a/assets/styles/layouts/_inline-icons.scss +++ b/assets/styles/layouts/_inline-icons.scss @@ -4,6 +4,7 @@ margin: 0 .15rem; &.middle:before { vertical-align: middle; } &.top:before { vertical-align: text-top; } + &.bottom:before { vertical-align: bottom; } &.xsmall:before { font-size: .8rem; } &.small:before { font-size: .9rem; } &.large:before { font-size: 1.1rem; } @@ -66,6 +67,24 @@ } } } + + &.notebook-add-cell { + display: inline-block; + position: relative; + border-radius: 50%; + height: 1.3rem; + width: 1.3rem; + background: linear-gradient(45deg, #5c10a0 0%, #8e1fc3 100%); + vertical-align: text-bottom; + text-align: center; + color: #fff; + font-size: .8rem; + + & > span { + display: block; + margin: 0.3rem 0; + } + } } .nav-item { @@ -305,7 +324,7 @@ } -//////////////////////////////////////////////////////////////////////////////// +//////////////////////////////////////////////////////////////////////////////// ///////////////////////////////// MEDIA QUERIES //////////////////////////////// //////////////////////////////////////////////////////////////////////////////// diff --git a/content/influxdb/cloud/notebooks/clean-data.md b/content/influxdb/cloud/notebooks/clean-data.md index 0123bc74f..3d67288ee 100644 --- a/content/influxdb/cloud/notebooks/clean-data.md +++ b/content/influxdb/cloud/notebooks/clean-data.md @@ -1,12 +1,13 @@ --- title: Normalize data with notebooks -description: > - Clean, standardize, or normalize you data to make it easier to compare with other measurements. +description: > + Learn how to create a notebook that normalizes or cleans data to make it + easier to work with. weight: 105 -influxdb/cloud/tags: +influxdb/cloud/tags: [notebooks] menu: influxdb_cloud: - name: Normalize data with notebooks + name: Normalize data parent: Notebooks --- diff --git a/content/influxdb/cloud/notebooks/downsample.md b/content/influxdb/cloud/notebooks/downsample.md index 70cd68d60..8245bf2dc 100644 --- a/content/influxdb/cloud/notebooks/downsample.md +++ b/content/influxdb/cloud/notebooks/downsample.md @@ -1,42 +1,16 @@ --- title: Downsample data with notebooks description: > - Downsample data to reduce overall disk usage as data collects over time. + Downsample data to summarize data at specified time intervals and reduce the + overall disk usage as data collects over time. + Learn how to create a notebook that downsamples data. weight: 104 -influxdb/cloud/tags: +influxdb/cloud/tags: [notebooks] menu: influxdb_cloud: - name: Downsample data with notebooks + name: Downsample data + identifier: notebooks-downsample parent: Notebooks --- -Downsample data to reduce the overall disk usage as data collects over time. -Learn how to create a notebook that downsamples data—walk through the following example to create a notebook that does the following: - -- Inputs InfluxDB Cloud demo data from the Website Monitoring Bucket -- Downsamples data by aggregating data within windows of time with a Flux script -- Outputs downsampled data to a bucket - -{{< youtube 0lS7n47kZog >}} - -## Requirements - -- This example uses [InfluxDB Cloud demo data](/influxdb/cloud/reference/sample-data/#influxdb-cloud-demo-data). -- Create a destination bucket to write downsampled data to. For details, see [Create a bucket](/influxdb/cloud/organizations/buckets/create-bucket/). - -## Downsample data with a notebook - -1. Create a new notebook (see [Create a notebook](/influxdb/cloud/notebooks/create-notebook/)). -2. Add a **Metric Selector** cell to select a bucket to query data from: - - In the **Choose a bucket** dropdown list, select **Website Monitoring Bucket**. - - Select the **response_time** field. - - Select the **mean** function from the aggregate selector in the upper-right. -3. Add a **Downsample** cell to bring in data from the previous cell and downsample it. - - Select an aggregate function from the **Apply aggregate** dropdown menu. - - Enter a window period. -4. Add an **Output to Bucket** cell, and then select the destination bucket for your downsampled data. -5. Add a **Markdown** cell to add a note to your team about what this notebook does. For example, the cell might say, "Downsample to one value per hour so we can do week-over-week performance. Sending data to downsample bucket." -6. Click **Preview** in the upper left to verify that your notebook runs and preview the output. -7. Run your notebook: - - Click **Run** from the **Preview** dropdown list to run the notebook and write to the output bucket a single time. - - To write continuously, click **Export as Task** in the upper right corner of the **Output to Bucket** cell. For details about working with tasks, see [Manage tasks](/influxdb/cloud/process-data/manage-tasks/). +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/notebooks/manage-notebooks.md b/content/influxdb/cloud/notebooks/manage-notebooks.md index 305a3ded4..8278cad89 100644 --- a/content/influxdb/cloud/notebooks/manage-notebooks.md +++ b/content/influxdb/cloud/notebooks/manage-notebooks.md @@ -1,6 +1,6 @@ --- title: Manage notebooks -description: View, update, and delete notebooks. +description: View, update, share, and delete notebooks. weight: 103 influxdb/cloud/tags: menu: diff --git a/content/influxdb/cloud/notebooks/overview.md b/content/influxdb/cloud/notebooks/overview.md index 8905563d7..88bdc3df4 100644 --- a/content/influxdb/cloud/notebooks/overview.md +++ b/content/influxdb/cloud/notebooks/overview.md @@ -3,7 +3,7 @@ title: Overview of notebooks description: > Learn about the building blocks of a notebook. weight: 101 -influxdb/cloud/tags: +influxdb/cloud/tags: [notebooks] menu: influxdb_cloud: name: Overview of notebooks diff --git a/content/influxdb/v2.0/query-data/execute-queries/data-explorer.md b/content/influxdb/v2.0/query-data/execute-queries/data-explorer.md index effc3fd8b..0c8e571ec 100644 --- a/content/influxdb/v2.0/query-data/execute-queries/data-explorer.md +++ b/content/influxdb/v2.0/query-data/execute-queries/data-explorer.md @@ -30,10 +30,10 @@ See [Get started with Flux](/influxdb/v2.0/query-data/get-started) to learn more {{< nav-icon "data-explorer" "v2" >}} 2. Use the Flux builder in the bottom panel to create a Flux query: - - 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 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/). 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. @@ -41,8 +41,8 @@ See [Get started with Flux](/influxdb/v2.0/query-data/get-started) to learn more 5. Click **Submit** (or press `Control+Enter`) to run your query. You can then preview your graph in the above pane. To cancel your query while it's running, click **Cancel**. 6. To work on multiple queries at once, click the {{< icon "plus" "v2" >}} to add another tab. - * Click the eye icon on a tab to hide or show a query's visualization. - * Click the name of the query in the tab to rename it. + - Click the eye icon on a tab to hide or show a query's visualization. + - Click the name of the query in the tab to rename it. ## Visualize your query diff --git a/content/influxdb/v2.1/notebooks/clean-data.md b/content/influxdb/v2.1/notebooks/clean-data.md index 93ebd7e20..2baa69f85 100644 --- a/content/influxdb/v2.1/notebooks/clean-data.md +++ b/content/influxdb/v2.1/notebooks/clean-data.md @@ -1,40 +1,163 @@ --- title: Normalize data with notebooks description: > - Clean, standardize, or normalize you data to make it easier to compare with other measurements. + Learn how to create a notebook that normalizes or cleans data to make it + easier to work with. weight: 105 influxdb/v2.1/tags: [notebooks] menu: influxdb_2_1: - name: Normalize data with notebooks + name: Normalize data parent: Notebooks --- -Learn how to create a notebook that normalizes data. Walk through the following example to create a notebook that does the following: +Learn how to create a notebook that normalizes data. +Data normalization is the process of modifying or cleaning data to make it easier to +work with. Examples include adjusting numeric values to a uniform scale and modifying strings. -- Inputs sample data from NOAA -- Normalizes sample data with a Flux script -- Outputs normalized data to a bucket +Walk through the following example to create a notebook that queries +[NOAA NDBC sample data](/influxdb/v2.0/reference/sample-data/#noaa-ndbc-data), +normalizes degree-based wind directions to cardinal directions, and then writes +the normalized data to a bucket. -## Requirements -- This example uses [NOAA water database data](/influxdb/v2.0/reference/sample-data/#noaa-water-sample-data). Note that using this data counts towards your total usage. -- Create a destination bucket to write normalized data to. For details, see [Create a bucket](/influxdb/v2.1/organizations/buckets/create-bucket/). +{{< cloud-only >}} +{{% cloud %}} +**Note**: Using sample data counts towards your total InfluxDB Cloud usage. +{{% /cloud %}} +{{< /cloud-only >}} -## Normalize data with a notebook -1. Create a new notebook (see [Create a notebook](/influxdb/v2.1/notebooks/create-notebook/)). -2. Add a **Metric Selector** cell to select a bucket to query data from: - - In the **Choose a bucket** dropdown, select your NOAA bucket. - - Select the **h2o_temperature** field. - - Select the **mean** function from the aggregate selector in the upper-right. -3. Add a **Flux Transformation** cell with the following script to bring in data from the previous cell and normalize it: - ```sh - __PREVIOUS_RESULT__ - |> map(fn: (r) => ({ r with _value: float(v: r._value) / 10.0 })) - ``` -4. Add an **Output to Bucket** cell: - - Select the destination bucket for your normalized data. -5. Add a **Markdown** cell to add a note to your team about what this notebook does. For example, the cell might say, "This notebook makes `h20_temperature` easier to view alongside `water_level`." -5. Click **Preview** in the upper left to verify that your notebook runs and preview the output. -6. Run your notebook: - - Click **Run** to run the notebook and write to the output bucket a single time. - - To write continuously, click **Export as Task** in the upper right corner of the **Output to Bucket** cell. For details about working with tasks, see [Manage tasks](/influxdb/v2.1/process-data/manage-tasks/). +1. [Create a new notebook](/influxdb/v2.1/notebooks/create-notebook/). +2. In the **Build a Query** cell: + + 1. In the **FROM** column under **{{% caps %}}Sample{{% /caps %}}**, + select **NOAA National Buoy Data**. + 2. In the next **FILTER** column, select **_measurement** from the drop-down list + and select the **ndbc** measurement in the list of measurements. + 3. In the next **FILTER** column, select **_field** from the drop-down list, + and select the **wind\_dir\_degt** field from the list of fields. + +3. Click {{% icon "notebook-add-cell" %}} after your **Build a Query** cell to + add a new cell and select **{{% caps %}}Flux Script{{% /caps %}}**. + +4. In the Flux script cell: + + 1. Define a custom function (`cardinalDir()`) that converts a numeric degree + value to a cardinal direction (N, NNE, NE, etc.). + 2. Use `__PREVIOUS_RESULT__` to load the output of the previous notebook + cell into the Flux script. + 3. Use [`map()`](/{{< latest "flux" >}}/stdlib/universe/map/) to iterate + over each input row, update the field key to `wind_dir_cardinal`, and + normalize the `_value` column to a cardinal direction using the custom + `cardinalDir()` function. + 4. {{% cloud-only %}} + + Use [`to()`](/{{< latest "flux">}}/stdlib/influxdata/influxdb/to/) + to write the normalized data back to InfluxDB. + Specify an existing bucket to write to or + [create a new bucket](/influxdb/v2.1/organizations/buckets/create-bucket/). + + {{% /cloud-only %}} + + {{% oss-only %}} + + ```js + import "array" + + cardinalDir = (d) => { + _cardinal = if d >= 348.7 or d < 11.25 then "N" + else if d >= 11.25 and d < 33.75 then "NNE" + else if d >= 33.75 and d < 56.25 then "NE" + else if d >= 56.25 and d < 78.75 then "ENE" + else if d >= 78.75 and d < 101.25 then "E" + else if d >= 101.25 and d < 123.75 then "ESE" + else if d >= 123.75 and d < 146.25 then "SE" + else if d >= 146.25 and d < 168.75 then "SSE" + else if d >= 168.75 and d < 191.25 then "S" + else if d >= 191.25 and d < 213.75 then "SSW" + else if d >= 213.75 and d < 236.25 then "SW" + else if d >= 236.25 and d < 258.75 then "WSW" + else if d >= 258.75 and d < 281.25 then "W" + else if d >= 281.25 and d < 303.75 then "WNW" + else if d >= 303.75 and d < 326.25 then "NW" + else if d >= 326.25 and d < 348.75 then "NNW" + else "" + + return _cardinal + } + + __PREVIOUS_RESULT__ + |> map(fn: (r) => ({r with + _field: "wind_dir_cardinal", + _value: cardinalDir(d: r._value), + })) + ``` + {{% /oss-only %}} + + {{% cloud-only %}} + + ```js + import "array" + + cardinalDir = (d) => { + _cardinal = if d >= 348.7 or d < 11.25 then "N" + else if d >= 11.25 and d < 33.75 then "NNE" + else if d >= 33.75 and d < 56.25 then "NE" + else if d >= 56.25 and d < 78.75 then "ENE" + else if d >= 78.75 and d < 101.25 then "E" + else if d >= 101.25 and d < 123.75 then "ESE" + else if d >= 123.75 and d < 146.25 then "SE" + else if d >= 146.25 and d < 168.75 then "SSE" + else if d >= 168.75 and d < 191.25 then "S" + else if d >= 191.25 and d < 213.75 then "SSW" + else if d >= 213.75 and d < 236.25 then "SW" + else if d >= 236.25 and d < 258.75 then "WSW" + else if d >= 258.75 and d < 281.25 then "W" + else if d >= 281.25 and d < 303.75 then "WNW" + else if d >= 303.75 and d < 326.25 then "NW" + else if d >= 326.25 and d < 348.75 then "NNW" + else "" + + return _cardinal + } + + __PREVIOUS_RESULT__ + |> map(fn: (r) => ({r with + _field: "wind_dir_cardinal", + _value: cardinalDir(d: r._value), + })) + |> to(bucket: "example-bucket") + ``` + {{% /cloud-only %}} + +4. {{% oss-only %}} + + Click {{% icon "notebook-add-cell" %}} after your **Flux Script** cell to + add a new cell and select **{{% caps %}}Output to Bucket{{% /caps %}}**. + Select a bucket from the **{{% icon "bucket" %}} Choose a bucket** + drop-down list. + + {{% /oss-only %}} + +5. _(Optional)_ Click {{% icon "notebook-add-cell" %}} and select **Note** to + add a cell containing notes about what this notebook does. For example, the + cell might say, "This notebook converts decimal degree wind direction values + to cardinal directions." +6. {{% oss-only %}} + + Click **Preview** in the upper left to verify that your notebook runs and previews the output. + + {{% /oss-only %}} +6. Click **Run** to run the notebook and write the normalized data to your bucket. + +## Continuously run a notebook +To continuously run your notebook, export the notebook as a task: + +1. Click {{% icon "notebook-add-cell" %}} to add a new cell and then select + **{{% caps %}}Task{{% /caps %}}**. +2. Provide the following: + + - **Every**: Interval that the task should run at. + - **Offset**: _(Optional)_ Time to wait after the defined interval to execute the task. + This allows the task to capture late-arriving data. + +3. Click **{{% icon "export" %}} Export as Task**. diff --git a/content/influxdb/v2.1/notebooks/create-notebook.md b/content/influxdb/v2.1/notebooks/create-notebook.md index cc20514a7..d5de4c257 100644 --- a/content/influxdb/v2.1/notebooks/create-notebook.md +++ b/content/influxdb/v2.1/notebooks/create-notebook.md @@ -9,101 +9,171 @@ menu: name: Create a notebook parent: Notebooks --- -To learn how notebooks can be useful and to see an overview of different cell types available in notebooks, see [Overview of Notebooks](/influxdb/v2.1/notebooks/overview/). + +Create a notebook to explore, visualize, and process your data. +Learn how to add and configure cells to customize your notebook. +To learn the benefits and concepts of notebooks, see [Overview of Notebooks](/influxdb/v2.1/notebooks/overview/). + +- [Create a notebook from a preset](#create-a-notebook-from-a-preset) +- [Use data source cells](#use-data-source-cells) +- [Use visualization cells](#use-visualization-cells) +- [Add a data source cell](#add-a-data-source-cell) +- [Add a validation cell](#add-a-validation-cell) +- [Add a visualization cell](#add-a-visualization-cell) + +## Create a notebook from a preset + +To create a new notebook, do the following: 1. In the navigation menu on the left, click **Notebooks**. {{< nav-icon "notebooks" >}} -2. Click one of the following options under **Create a Notebook**: - - New Notebook - - Set an Alert - - Schedule a Task - - Write a Flux Script +2. In the **Notebooks** page, select one of the following options under **Create a Notebook**: + - **New Notebook**: includes a [query builder cell](#add-a-data-source-cell), a [validation cell](#add-a-validation-cell), and a [visualization cell](#add-a-visualization-cell). + - **Set an Alert**: includes a [query builder cell](#add-a-data-source-cell), a [validation cell](#add-a-validation-cell), a [visualization cell](#add-a-visualization-cell), and an [alert builder cell](#add-an-action-cell). + - **Schedule a Task**: includes a [Flux Script editor cell](#add-a-data-source-cell), a [validation cell](#add-a-validation-cell), and a [task schedule cell](#add-an-action-cell). + - **Write a Flux Script**: includes a [Flux script editor cell](#add-a-data-source-cell), and a [validation cell](#add-a-validation-cell). + 3. Enter a name for your notebook in the **Untitled Notebook** field. -3. Do the following at the top of the page: +4. Do the following at the top of the page: - Select your local time zone or UTC. - - Choose a time range for your data. -4. Consider which notebook cells to add to your notebook. You need to have one input cell for other cells to run properly. The default notebook cell types included in your notebook (**Data Source**, **Visualization**, and **Action**) vary depending on the type of notebook you selected in step 2. -5. Select your bucket in your query or Flux script, and then select the filters to narrow your data. -6. Do one of the following: - - To view results in your cells (for example, to view your **Visualization** or **Action**) *without writing data*, click **Preview** (or press **CTRL + Enter**). - - To view the results of each cell and write the results to the specified output bucket, click **Run**. -7. (Optional) Change your visualization settings with the dropdown menus and gear icon at the top of the **Visualization** cell. -8. (Optional) Click the **+** icon, and then add one or more of the following cell types to your notebook: + - Choose a time [range](/{{% latest "flux" %}}/stdlib/universe/range/) for your data. +5. Your notebook should have a **Data Source** cell as the first cell. **Data Source** cells provide data to subsequent cells. The presets (listed in step 2) include either a **Query Builder** or a **Flux Script** as the first cell. +6. To define your data source query, do one of the following: + - If your notebook uses a **Query Builder** cell, select your bucket and any additional filters for your query. + - If your notebook uses a **Flux Script** cell, enter or paste a [Flux script](/influxdb/v2.1/query-data/flux/). +7. {{< oss-only >}} - - [Data source](#add-a-data-source-cell): to pull information into your notebook - - [Visualization](#add-a-visualization-cell): to - - [Action](#add-an-action-cell): filter and apply changes to your data, for example, create an alert, process data with a task, or output data to a bucket -9. (Optional) [Convert a cell into raw Flux script](#view-and-edit-flux-script-in-a-cell) to view and edit the code. + Select and click **Preview** (or press **CTRL + Enter**) under the notebook title. + InfluxDB displays query results in **Validate the Data** and **Visualize the Result** *without writing data or + running actions*. -### Add a data source cell + {{< /oss-only >}} +8. (Optional) Change your visualization settings with the drop-down menu and the {{< icon "gear" >}} **Configure** button at the top of the **Visualize the Result** cell. +9. (Optional) Toggle the **Presentation** switch to display visualization cells and hide all other cells. +10. (Optional) Configure notebook actions {{< oss-only >}}(**Alert**, **Task**, or **Output to Bucket**){{< /oss-only >}}{{< cloud-only >}}(**Alert** or **Task**){{< /cloud-only >}}. +11. (Optional) To run your notebook actions, select and click **Run** under the notebook title. +12. (Optional) To add a new cell, follow the steps for one of the cell types: -1. Select **Flux Script** or **Query Builder** as your input, and then select or enter the bucket to pull data from. -2. Select filters to narrow your data. -3. Select **Preview** (**CTRL + Enter**) or **Run** in the upper left dropdown menu. + - [Add a data source cell](#add-a-data-source-cell) + - [Add a validation cell](#add-a-validation-cell) + - [Add a visualization cell](#add-a-visualization-cell) + - [Add an action cell](#add-an-action-cell) +13. (Optional) [Convert a query builder cell into raw Flux script](#convert-a-query-builder-to-flux) to view and edit the code. -### Add an action cell +## Use Data Source cells -1. Select one of the following action cell-types: - - **Alert** - - **Downsample**: Window data by time and apply an aggregate to each window to downsample data. For more information, see [Downsample data with notebooks](/influxdb/v2.1/notebooks/downsample/). -2. Select **Preview** (**CTRL + Enter**) or **Run** in the upper left dropdown menu. +### Convert a Query Builder to Flux +To edit the raw Flux script of a **Query Builder** cell, convert the cell to Flux. + +{{% warn %}} +You can't convert a **Flux Script** editor cell to a **Query Builder** cell. +Once you convert a **Query Builder** cell to a **Flux Script** editor cell, you can't convert it back. +{{% /warn %}} + +1. Click the {{% icon "more" %}} icon in the **Query Builder** cell you want to edit as Flux, and then select **Convert to |> Flux**. +You won't be able to undo this step. + + A **Flux Script** editor cell containing the raw Flux script replaces the **Query Builder** cell. + +2. View and edit the Flux script as needed. + +## Use visualization cells + +- To change your [visualization type](/influxdb/v2.1/visualize-data/visualization-types/), select a new type from the drop-down list at the top of the cell. +- (For histogram only) To specify values, click **Select**. +- To configure the visualization, click **Configure**. +- To download results as an annotated CSV file, click the **CSV** button. +- To export to the dashboard, click **Export to Dashboard**. + +## Add a data source cell + +Add a [data source cell](/influxdb/v2.1/notebooks/overview/#data-source) to pull information into your notebook. + +To add a data source cell, do the following: +1. Click {{< icon "notebook-add-cell" >}}. +2. Select **{{< caps >}}Flux Script{{< /caps >}}** or **{{< caps >}}Query Builder{{< /caps >}}** as your input, and then select or enter the bucket to pull data from. +3. Select filters to narrow your data. +4. Select {{< oss-only >}}**Preview** (**CTRL + Enter**) or {{< /oss-only >}}**Run** in the upper left drop-down list. + +## Add a validation cell + +A validation cell uses the **Table** [visualization type](/influxdb/v2.1/visualize-data/visualization-types/) to display query results from a data source cell. + +To add a **Table** visualization cell, do the following: + +1. Click {{< icon "notebook-add-cell" >}}. +2. Under **Visualization**, click **{{< caps >}}Table{{< /caps >}}**. + +## Add a visualization cell + +Add a visualization cell to render query results as a [Visualization type](/influxdb/v2.1/visualize-data/visualization-types/). + +To add a Table visualization cell, do the following: + +1. Click {{< icon "notebook-add-cell" >}}. +2. Under **Visualization**, select one of the following visualization cell-types: + + - **{{< caps >}}Table{{< /caps >}}**: Display data in tabular format. + - **{{< caps >}}Graph{{< /caps >}}**: Visualize data using InfluxDB visualizations. + - **{{< caps >}}Note{{< /caps >}}**: Use Markdown to add notes or other information to your notebook. + +To modify a visualization cell, see [use visualization cells](#use-visualization-cells). +For detail on available visualization types and how to use them, see [Visualization types](/influxdb/v2.1/visualize-data/visualization-types/). + +## Add an action cell + +Add an [action cell](/influxdb/v2.1/notebooks/overview/#action) to create an [alert](/influxdb/v2.1/monitor-alert/) +{{< cloud-only >}}or{{< /cloud-only >}}{{< oss-only >}},{{< /oss-only >}} process data with a [task](/influxdb/v2.1/process-data/manage-tasks/) +{{< oss-only >}}, or output data to a bucket{{< /oss-only >}}. + +{{< oss-only >}} {{% warn %}} If your cell contains a custom script that uses any output function to write data to InfluxDB (for example: the `to()` function) or sends data to a third-party service, clicking Preview will write data. {{% /warn %}} -### Add a visualization cell +{{< /oss-only >}} -Select one of the following visualization cell-types: +- [Add an Alert cell](#add-an-alert-cell) +- {{< oss-only >}}[Add an Output to Bucket cell](#add-an-output-to-bucket-cell){{< /oss-only >}} +- [Add a Task cell](#add-a-task-cell) -- Table -- Graph -- Note -For detail on available visualization types and how to use them, see [Visualization types](/influxdb/cloud/visualize-data/visualization-types/). +### Add an Alert cell -#### Visualization - -- To change your visualization type, select a new type from the dropdown menu at the top of the cell. -- (For histogram only) To specify values, click **Select**. -- To configure the visualization, click **Configure**. -- To download results as an annotated CSV file, click the **CSV** button. -- To export to the dashboard, click **Export to Dashboard**. - -### Add an action cell - -Select one of the following action cell-types: - -- To recieve a notification, select [Alert](#alert) and complete the steps below. -- To write output to a bucket, select [Output to Bucket](#output-to-bucket) and complete the steps below. -- To create a task, select [Task](#task) and complete the steps below. - -#### Alert +To add an [alert](/influxdb/v2.1/monitor-alert/) to your notebook, do the following: 1. Enter a time range to automatically check the data and enter your query offset. 2. Customize the conditions to send an alert. 3. Select an endpoint to receive an alert: - Slack and a Slack Channel - HTTP post - - Pager Duty -4. (Optional) Personalize your message. By default, the message is "${strings.title(v: r._type)} for ${r._source_measurement} triggered at ${time(v: r._source_timestamp)}!" -5. Click **Export as Task** to create your alert. + - PagerDuty +4. (Optional) Personalize your message. By default, the message is: + ``` + ${strings.title(v: r._type)} for ${r._source_measurement} triggered at ${time(v: r._source_timestamp)}! + ``` +5. Click **{{< caps >}}Test Alert{{< /caps >}}** to send a test message to your configured **Endpoint**. The test will not schedule the new alert. +6. Click **{{< icon "export" >}} {{< caps >}}Export Alert Task{{< /caps >}}** to create your alert. -#### Output to bucket +{{< oss-only >}} +### Add an Output to Bucket cell -1. Select a bucket. -2. Click **Preview** to see what would be written to the bucket without commiting, or click **Run** in the upper left to write, or select **Export as Task** to schedule your output as a task. +To write **Data Source** results to a bucket, do the following: -#### Task +1. Click {{% icon "notebook-add-cell" %}}. +2. Click **{{< caps >}}Output to Bucket{{< /caps >}}**. +3. In the **{{< icon "bucket" >}} Choose a bucket** drop-down list, select or create a bucket. +4. Click **Preview** to view the query result in validation cells. +5. Select and click **Run** in the upper left to write the query result to the bucket. -1. Enter a time and an offset to schedule the task. -2. Click **Export as Task** to save. +{{< /oss-only >}} -### View and edit Flux script in a cell -Convert your notebook cells into raw Flux script to view and edit the code. Conversion to Flux is available for the following cell types: - - **Inputs: Metric Selector** - - **Transform: Column Editor** and **Downsample** +### Add a Task cell -1. Click the overflow menu icon in the cell you want to view as Flux, and then select **Convert to |> Flux**. You won't be able to undo this step. - A Flux cell appears with underlying script for the selected cell. -3. View and edit the Flux script as needed. +To add a [task](/influxdb/v2.1/process-data/manage-tasks/) to your notebook, do the following: + +1. Click {{% icon "notebook-add-cell" %}}. +2. Click **{{< caps >}}Task{{< /caps >}}**. +3. Enter a time and an offset to schedule the task. +4. Click **{{< icon "task" >}} {{< caps >}}Export as Task{{< /caps >}}** to save. diff --git a/content/influxdb/v2.1/notebooks/downsample.md b/content/influxdb/v2.1/notebooks/downsample.md new file mode 100644 index 000000000..e3c426c80 --- /dev/null +++ b/content/influxdb/v2.1/notebooks/downsample.md @@ -0,0 +1,111 @@ +--- +title: Downsample data with notebooks +description: > + Create a notebook to downsample data. Downsampling aggregates or summarizes data + within specified time intervals, reducing the overall disk usage as data + collects over time. +weight: 104 +influxdb/v2.1/tags: [notebooks] +menu: + influxdb_2_1: + name: Downsample data + identifier: notebooks-downsample + parent: Notebooks +--- + +Create a notebook to downsample data. Downsampling aggregates or summarizes data +within specified time intervals, reducing the overall disk usage as data +collects over time. + +The following example creates a notebook that queries **Coinbase bitcoin price +sample data** from the last hour, downsamples the data into ten minute summaries, +and then writes the downsampled data to an InfluxDB bucket. + +1. If you do not have an existing bucket to write the downsampled data to, + [create a new bucket](/influxdb/v2.1/organizations/buckets/create-bucket/). +2. [Create a new notebook](/influxdb/v2.1/notebooks/create-notebook/). +3. Select **Past 1h** from the time range drop-down list at the top of your notebook. +4. In the **Build a Query** cell: + + 1. In the **FROM** column under **{{% caps %}}Sample{{% /caps %}}**, + select **Coinbase bitcoin price**. + 2. In the next **FILTER** column, select **_measurement** from the drop-down list + and select the **coindesk** measurement in the list of measurements. + 3. In the next **FILTER** column, select **_field** from the drop-down list, + and select the **price** field from the list of fields. + 4. In the next **FILTER** column, select **code** from the drop-down list, + and select a currency code. + +5. Click {{% icon "notebook-add-cell" %}} after your **Build a Query** cell to + add a new cell and select **{{% caps %}}Flux Script{{% /caps %}}**. + +6. In the Flux script cell: + + 1. Use `__PREVIOUS_RESULT__` to load the output of the previous notebook + cell into the Flux script. + 2. Use [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) + to window data into ten minute intervals and return the average of each interval. + Specify the following parameters: + + - **every**: Window interval _(should be less than or equal to the duration of the queried time range)_. + For this example, use `10m`. + - **fn**: [Aggregate](/{{< latest "flux" >}}/function-types/#aggregates) + or [selector](/{{< latest "flux" >}}/function-types/#selectors) function + to apply to each window. + For this example, use `mean`. + + 3. {{% cloud-only %}} + + Use [`to()`](/{{< latest "flux">}}/stdlib/influxdata/influxdb/to/) + to write the downsampled data back to an InfluxDB bucket. + + {{% /cloud-only %}} + + {{% oss-only %}} + + ```js + __PREVIOUS_RESULT__ + |> aggregateWindow(every: 10m, fn: mean) + ``` + {{% /oss-only %}} + + {{% cloud-only %}} + + ```js + __PREVIOUS_RESULT__ + |> aggregateWindow(every: 10m, fn: mean) + |> to(bucket: "example-bucket") + ``` + {{% /cloud-only %}} + +7. {{% oss-only %}} + + Click {{% icon "notebook-add-cell" %}} after your **Flux Script** cell to + add a new cell and select **{{% caps %}}Output to Bucket{{% /caps %}}**. + Select a bucket from the **{{% icon "bucket" %}} Choose a bucket** + drop-down list. + + {{% /oss-only %}} + +8. _(Optional)_ Click {{% icon "notebook-add-cell" %}} and select **Note** to + add a note to describe your notebook, for example, + "Downsample Coinbase bitcoin prices into hourly averages." +9. {{% oss-only %}} + + Click **Preview** in the upper left to verify that your notebook runs and displays the output. + + {{% /oss-only %}} +10. Click **Run** to run the notebook and write the downsampled data to your bucket. + +## Continuously run a notebook +To continuously run your notebook, export the notebook as a task: + +1. Click {{% icon "notebook-add-cell" %}} to add a new cell, and then select + **{{% caps %}}Task{{% /caps %}}**. +2. Provide the following: + + - **Every**: Interval that the task should run at. + - **Offset**: _(Optional)_ Time to wait after the defined interval to execute the task. + This allows the task to capture late-arriving data. + +3. Click **{{% icon "export" %}} Export as Task**. diff --git a/content/influxdb/v2.1/notebooks/manage-notebooks.md b/content/influxdb/v2.1/notebooks/manage-notebooks.md index 5b00569b2..b2cb6ec91 100644 --- a/content/influxdb/v2.1/notebooks/manage-notebooks.md +++ b/content/influxdb/v2.1/notebooks/manage-notebooks.md @@ -9,9 +9,15 @@ menu: parent: Notebooks --- -View, update, and delete notebooks in the UI. +Manage your notebooks in the UI: + +- [View or update a notebook](#view-or-update-notebooks) +- {{% cloud-only %}}[Share a notebook](#share-a-notebook){{% /cloud-only %}} +- {{% cloud-only %}}[Unshare a notebook](#unshare-a-notebook){{% /cloud-only %}} +- [Delete a notebook](#delete-a-notebook) ## View or update notebooks + 1. In the navigation menu on the left, click **Notebooks**. {{< nav-icon "notebooks" >}} @@ -20,10 +26,31 @@ View, update, and delete notebooks in the UI. 2. Click a notebook to open it. 3. To update, edit the notebook's cells and content. Changes are saved automatically. +{{% cloud-only %}} + +## Share a notebook + +1. In the navigation menu on the left, click **Notebooks**. + + {{< nav-icon "notebooks" >}} + +2. Click the notebook to open it, and then click the **{{< icon "share" >}}** icon. +3. Select an API token with read-access to all resources in the notebook, + and then click the **{{< icon "check" >}}** icon. +4. Share the generated notebook URL as needed. + +## Unshare a notebook + +To stop sharing a notebook, select **{{< icon "trash" >}}** next to the shared notebook URL. + +{{% /cloud-only %}} + ## Delete a notebook + 1. In the navigation menu on the left, click **Notebooks**. {{< nav-icon "notebooks" >}} + 2. Hover over a notebook in the list that appears. 3. Click **Delete Notebook**. 4. Click **Confirm**. diff --git a/content/influxdb/v2.1/notebooks/overview.md b/content/influxdb/v2.1/notebooks/overview.md index b7dd1d2f2..39e31a26a 100644 --- a/content/influxdb/v2.1/notebooks/overview.md +++ b/content/influxdb/v2.1/notebooks/overview.md @@ -10,72 +10,88 @@ menu: parent: Notebooks --- -Learn about the building blocks of a notebook, how notebooks can help show how data is processed, and discover some common use cases. +Learn how notebooks can help to streamline and simplify your day-to-day business processes. -To use different notebook cell types, controls, and uses to process data, see: -- [Notebook concepts](/influxdb/v2.1/notebooks/overview/#notebook-concepts) -- [Notebook controls](/influxdb/v2.1/notebooks/overview/#notebook-controls) -- [Notebook cell types](/influxdb/v2.1/notebooks/overview/#notebook-cell-types) +See an overview of [notebook concepts](/influxdb/v2.1/notebooks/overview/#notebook-concepts), [notebook controls](/influxdb/v2.1/notebooks/overview/#notebook-controls), and [notebook cell types](/influxdb/v2.1/notebooks/overview/#notebook-cell-types) also know as the basic building blocks of a notebook. ## Notebook concepts -Using notebooks, you can: +You can think of an InfluxDB notebook as a collection of sequential data processing steps. Each step is represented by a "cell" that performs an action such as querying, visualizing, processing, or writing data to your buckets. Notebooks help you do the following: -- Create documents with live code, equations, visualizations, and explanatory notes. -- Create dashboard cells or scheduled tasks. -- Clean and downsample data. -- Build runbooks. -- Document data processing steps. +- Create snippets of live code, equations, visualizations, and explanatory notes. +- Create alerts or scheduled tasks. +- Downsample and normalize data. +- Build runbooks to share with your teams. +- Output data to buckets. ## Notebook controls The following options appear at the top of each notebook. +{{% oss-only %}} + ### Preview/Run mode - Select **Preview** (or press **Control+Enter**) to display results of each cell without writing data. Helps to verify that cells return expected results before writing data. -- Select **Run** mode displays results of each cell and writes data to the selected bucket. -### Presentation mode +{{% /oss-only %}} -Display notebooks in full screen with Presentation mode, 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. +{{% cloud-only %}} + +### Run + +Select {{< caps >}}Run{{< /caps >}} (or press **Control+Enter**) to display results of each cell and write data to the selected bucket. + +{{% /cloud-only %}} + +### Save Notebook (appears before first save) + +Select {{< caps >}}Save Notebook{{< /caps >}} to save all notebook cells. Once you've saved the notebook, this button disappears and the notebook automatically saves as subsequent changes are made. + +{{% note %}} +Saving the notebook does not save cell results. When you open a saved notebook, click {{< caps >}}**Run**{{< /caps >}} to update cell results. +{{% /note %}} ### Local or UTC timezone -Click the timezone dropdown list to select a timezone to use for the dashboard. Select either the local time (default) or UTC. +Click the timezone drop-down list to select a timezone to use for the notebook. Select either the local time (default) or UTC. ### Time range -Select from the options in the dropdown list or select **Custom Time Range** to enter a custom time range with precision up to nanoseconds. +Select from the options in the dropdown list or select **Custom Time Range** to enter a custom time range with precision up to nanoseconds, and then click **{{< caps >}}Apply Time Range{{< /caps >}}**. + +{{% cloud-only %}} + +### Share notebook + +To generate a URL for the notebook, click the **{{< icon "share" >}}** icon. +For more detail, see how to [share a notebook](/influxdb/cloud/notebooks/manage-notebooks/#share-a-notebook). + +{{% /cloud-only %}} ## Notebook cell types The following cell types are available for your notebook: - [Data source](#data-source) - [Visualization](#visualization) -- [Actions](#actions) +- [Action](#action) ### Data source -At least one input cell is required in a notebook for other cells to run. +At least one data source (input) cell is required in a notebook for other cells to run. -- **Flux Script**: Input your data using a Flux script. -- **Query Builder**: Input your data using a query. +- **{{< caps >}}Query Builder{{< /caps >}}**: Build a query with the Flux query builder. +- **{{< caps >}}Flux Script{{< /caps >}}**: Enter a raw Flux script. + + Data source cells work like the **Query Builder** or **Script Editor** in Data Explorer. For more information, see how to [query data with Flux and the Data Explorer](/influxdb/v2.1/query-data/execute-queries/data-explorer/#query-data-with-flux-and-the-data-explorer). ### Visualization -- **Table**: View your data in a table. -- **Graph**: View your data in a graph. -- **Note**: Create explanatory notes or other information for yourself or one of your team members. +- **{{< caps >}}Table{{< /caps >}}**: View your data in a table. +- **{{< caps >}}Graph{{< /caps >}}**: View your data in a graph. +- **{{< caps >}}Note{{< /caps >}}**: Create explanatory notes or other information for yourself or your team members. ### Action -- **Column Editor**: Modify column visibility and naming. -- **Markdown**: Create explanatory notes or other information for yourself or one of your team members. -- **Visualization**: Represents your data in visual formats such as graphs or charts. - -### Output - -- **Alert**: Set up alerts. See how to [monitor data and send alerts](https://docs.influxdata.com/influxdb/v2.0/monitor-alert/). -- **Tasks**: Set up tasks. See how to [manage tasks in InfluxDB] (https://docs.influxdata.com/influxdb/v2.0/process-data/manage-tasks/). -- **Output to Bucket**: In **Preview** mode, this cell represents what would be written if the data was going to be committed to a bucket. In **Run** mode, this writes data to the specified bucket. +- **{{< caps >}}Alert{{< /caps >}}**: Set up alerts. See how to [monitor data and send alerts](/influxdb/v2.1/monitor-alert/). +- **{{< caps >}}Tasks{{< /caps >}}**: Use the notebook to set up and export a task. See how to [manage tasks in InfluxDB](/influxdb/v2.1/process-data/manage-tasks/). diff --git a/content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md b/content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md index ffb281ee0..1591a08db 100644 --- a/content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md +++ b/content/influxdb/v2.1/notebooks/troubleshoot-notebooks.md @@ -10,10 +10,5 @@ menu: --- ### No measurements appear in my bucket even though there's data in it. -Try changing the time range. You might have measurements prior to the time range you selected. For example, if the selected time range is `Past 1h` and the last write happened 16 hours ago, you'd need to change the time range to `Past 24h` (or more) to see your data. -### "No bucket exists" error message appears. -This error appears when the Buckets API endpoint returns a list of bucket and you don’t have access to that bucket. Verify that you have access permissions to the bucket that you're trying to query or write to. - -### Metric selector crashes. -This can occur with high-cardinality buckets when there's too much data for the browser. To decrease the amount of data in your bucket, see how to [resolve high series cardinality](/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality/). +Try changing the time range. You might have measurements prior to the time range you selected. For example, if the selected time range is `Past 1h` and the last write happened 16 hours ago, you'd need to change the time range to `Past 24h` (or more) to see your data. diff --git a/content/influxdb/v2.1/query-data/execute-queries/data-explorer.md b/content/influxdb/v2.1/query-data/execute-queries/data-explorer.md index 6bf7acb70..8fcc8b5c6 100644 --- a/content/influxdb/v2.1/query-data/execute-queries/data-explorer.md +++ b/content/influxdb/v2.1/query-data/execute-queries/data-explorer.md @@ -30,10 +30,10 @@ See [Get started with Flux](/influxdb/v2.1/query-data/get-started) to learn more {{< nav-icon "data-explorer" >}} 2. Use the Flux builder in the bottom panel to create a Flux query: - - 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.1/query-data/flux/group-data/). + - 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.1/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. @@ -41,8 +41,8 @@ See [Get started with Flux](/influxdb/v2.1/query-data/get-started) to learn more 5. Click **Submit** (or press `Control+Enter`) to run your query. You can then preview your graph in the above pane. To cancel your query while it's running, click **Cancel**. 6. To work on multiple queries at once, click the {{< icon "plus" >}} to add another tab. - * Click the eye icon on a tab to hide or show a query's visualization. - * Click the name of the query in the tab to rename it. + - Click the eye icon on a tab to hide or show a query's visualization. + - Click the name of the query in the tab to rename it. ## Visualize your query diff --git a/layouts/shortcodes/icon.html b/layouts/shortcodes/icon.html index 0f2a92a28..dec829df7 100644 --- a/layouts/shortcodes/icon.html +++ b/layouts/shortcodes/icon.html @@ -143,6 +143,8 @@ {{- else if or (eq $icon "toggle") (eq $icon "toggle-blue") -}} + {{- else if or (eq $icon "notebook-add") (eq $icon "notebook-add-cell") -}} + {{- else if eq $icon "toggle-green" -}} {{- else if or (eq $icon "annotate") (eq $icon "pin") -}} @@ -151,5 +153,11 @@ {{- else if or (eq $icon "handle") (eq $icon "move-cell") (eq $icon "move") -}} + {{- else if eq $icon "share" -}} + + {{- else if eq $icon "bucket" -}} + + {{- else if or (eq $icon "more") (eq $icon "...") (eq $icon "ellipses") -}} + {{- end -}} -{{- end -}} \ No newline at end of file +{{- end -}}