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

Merge pull request #531 from influxdata/key-concepts 

Key concepts
pull/541/head
kelseiv 2019-10-21 13:53:08 -07:00 committed by GitHub
parent cd4da537a5 dc23046805
commit aa41473a83
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 400 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
assets/js/content-interactions.js
View File

@ -35,9 +35,9 @@ $('.article a[href^="#"]:not(' + elementWhiteList + ')').click(function (e) {
///////////////////////////// Left Nav Interactions /////////////////////////////
$(".children-toggle").click(function(e) {
e.preventDefault()
$(this).toggleClass('open');
$(this).siblings('.children').toggleClass('open');
e.preventDefault()
$(this).toggleClass('open');
$(this).siblings('.children').toggleClass('open');
})
//////////////////////////// Mobile Contents Toggle ////////////////////////////
@ -52,28 +52,28 @@ $('#contents-toggle-btn').click(function(e) {
function tabbedContent(container, tab, content) {
// Add the active class to the first tab in each tab group,
// in case it wasn't already set in the markup.
$(container).each(function () {
$(tab, this).removeClass('is-active');
$(tab + ':first', this).addClass('is-active');
});
// Add the active class to the first tab in each tab group,
// in case it wasn't already set in the markup.
$(container).each(function () {
$(tab, this).removeClass('is-active');
$(tab + ':first', this).addClass('is-active');
});
$(tab).on('click', function(e) {
e.preventDefault();
$(tab).on('click', function(e) {
e.preventDefault();
// Make sure the tab being clicked is marked as active, and make the rest inactive.
$(this).addClass('is-active').siblings().removeClass('is-active');
// Make sure the tab being clicked is marked as active, and make the rest inactive.
$(this).addClass('is-active').siblings().removeClass('is-active');
// Render the correct tab content based on the position of the tab being clicked.
const activeIndex = $(tab).index(this);
$(content).each(function(i) {
if (i === activeIndex) {
$(this).show();
$(this).siblings(content).hide();
}
});
});
// Render the correct tab content based on the position of the tab being clicked.
const activeIndex = $(tab).index(this);
$(content).each(function(i) {
if (i === activeIndex) {
$(this).show();
$(this).siblings(content).hide();
}
});
});
}
tabbedContent('.code-tabs-wrapper', '.code-tabs p a', '.code-tab-content');
@ -82,8 +82,8 @@ tabbedContent('.tabs-wrapper', '.tabs p a', '.tab-content');
/////////////////////////////// Truncate Content ///////////////////////////////
$(".truncate-toggle").click(function(e) {
e.preventDefault()
$(this).closest('.truncate').toggleClass('closed');
e.preventDefault()
$(this).closest('.truncate').toggleClass('closed');
})
//////////////////// Replace Missing Images with Placeholder ///////////////////
@ -92,3 +92,11 @@ $(".article--content img").on("error", function() {
$(this).attr("src", "/img/coming-soon.svg");
$(this).attr("style", "max-width:500px;");
});
////////////////////////// Inject tooltips on load //////////////////////////////
$('.tooltip').each( function(){
$toolTipText = $('<div/>').addClass('tooltip-text').text($(this).attr('data-tooltip-text'));
$toolTipElement = $('<div/>').addClass('tooltip-container').append($toolTipText);
$(this).prepend($toolTipElement);
});

7
assets/styles/styles-default.scss
View File

@ -1,9 +1,10 @@
// InfluxData Docs Default Theme (Light)
// Import Tools
@import "tools/icomoon";
@import "tools/media-queries.scss";
@import "tools/mixins.scss";
@import "tools/icomoon",
"tools/media-queries.scss",
"tools/mixins.scss",
"tools/tooltips";
// Import default light theme
@import "themes/theme-light.scss";

6
assets/styles/themes/_theme-dark.scss
View File

@ -176,3 +176,9 @@ $landing-btn-bg: $b-dodger;
$landing-btn-text-hover: $b-dodger;
$landing-btn-bg-hover: $g20-white;
$landing-artwork-color: $cp-minsk;
// Tooltip colors
$tooltip-color: $ch-chartreuse;
$tooltip-color-alt: $ch-canary;
$tooltip-bg: $g20-white;
$tooltip-text: $cp-minsk;

6
assets/styles/themes/_theme-light.scss
View File

@ -177,3 +177,9 @@ $landing-btn-bg: $b-dodger !default;
$landing-btn-text-hover: $b-dodger !default;
$landing-btn-bg-hover: $g20-white !default;
$landing-artwork-color: rgba($g20-white, .15) !default;
// Tooltip colors
$tooltip-color: $m-magenta !default;
$tooltip-color-alt: $wp-trance !default;
$tooltip-bg: $m-lavander !default;
$tooltip-text: $g20-white !default;

91
assets/styles/tools/_tooltips.scss Normal file
View File

@ -0,0 +1,91 @@
@import "themes/theme-light.scss";
// Font weights
$medium: 500;
$bold: 700;
// Border radius
$radius: 3px;
////////////////////////////////// Tool Tips //////////////////////////////////
.tooltip {
position: relative;
display: inline;
font-weight: $medium;
color: $tooltip-color;
&:hover {
.tooltip-container { visibility: visible; }
.tooltip-text {
opacity: 1;
transform: translate(-50%,-2.5rem);
}
}
.tooltip-container {
position: absolute;
top: 0;
left: 50%;
transform: translateX(-50%);
overflow: visible;
visibility: hidden;
}
.tooltip-text {
font-weight: $medium;
position: absolute;
border-radius: $radius;
padding: .15rem .75rem;
font-size: 0.9rem;
line-height: 1.75rem;
left: 50%;
transform: translate(-50%,-1.75rem);
transition: all 0.2s ease;
white-space: nowrap;
opacity: 0;
color: $tooltip-text;
background-color: $tooltip-bg;
&:after {
content: '';
position: absolute;
left: 50%;
bottom: -14px;
transform: translateX(-50%);
border-top: 8px solid $tooltip-bg;
border-right: 8px solid transparent;
border-bottom: 8px solid transparent;
border-left: 8px solid transparent;
}
}
}
th .tooltip {
color: $tooltip-color-alt;
&:hover {
.tooltip-container { visibility: visible; }
.tooltip-text {
opacity: 1;
transform: translate(-50%,1.75rem);
}
}
.tooltip-text {
transform: translate(-50%,1rem);
&:after {
content: '';
position: absolute;
height: 0;
left: 50%;
top: -14px;
transform: translateX(-50%);
border-top: 8px solid transparent;
border-right: 8px solid transparent;
border-bottom: 8px solid $tooltip-bg;
border-left: 8px solid transparent;
}
}
}

2
content/v2.0/reference/api.md
View File

@ -4,7 +4,7 @@ description: >
The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB.
Access the InfluxDB API using the `/api/v2/` endpoint.
menu: v2_0_ref
weight: 2
weight: 3
v2.0/tags: [api]
---

2
content/v2.0/reference/cli/_index.md
View File

@ -8,7 +8,7 @@ v2.0/tags: [cli]
menu:
v2_0_ref:
name: Command line tools
weight: 3
weight: 4
---
InfluxDB provides command line tools designed to aid in managing and working

2
content/v2.0/reference/client-libraries.md
View File

@ -3,7 +3,7 @@ title: 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: 3
weight: 4
menu:
v2_0_ref:
name: Client libraries

2
content/v2.0/reference/config-options.md
View File

@ -6,7 +6,7 @@ description: >
menu:
v2_0_ref:
name: Configuration options
weight: 2
weight: 3
---
To configure InfluxDB, use the following configuration options when starting the

14
content/v2.0/reference/key-concepts/_index.md Normal file
View File

@ -0,0 +1,14 @@
---
title: InfluxDB key concepts
description: >
Concepts related to InfluxDB.
weight: 2
menu:
v2_0_ref:
name: Key concepts
v2.0/tags: [key concepts]
---
Before working with InfluxDB 2.0, it's helpful to learn a few key concepts. Browse the topics below to learn more.
{{< children >}}

175
content/v2.0/reference/key-concepts/data-elements.md Normal file
View File

@ -0,0 +1,175 @@
---
title: InfluxDB data elements
description: >
InfluxDB structures data using elements such as timestamps, field keys, field values, tags, etc.
weight: 102
menu:
v2_0_ref:
parent: Key concepts
name: Data elements
v2.0/tags: [key concepts, schema]
---
InfluxDB 2.0 includes the following data elements:
- [timestamp](#timestamp)
- [field key](#field-key)
- [field value](#field-value)
- [field set](#field-set)
- [tag key](#tag-key)
- [tag value](#tag-value)
- [tag set](#tag-set)
- [measurement](#measurement)
- [series](#series)
- [point](#point)
- [bucket](#bucket)
- [organization](#organization)
The sample data below is used to illustrate data elements concepts.
_Hover over highlighted terms to get acquainted with InfluxDB terminology and layout._
**bucket:** `my_bucket`
| _time | _measurement | <span class ="tooltip" data-tooltip-text ="Tag key">location</span> | <span class ="tooltip" data-tooltip-text ="Tag key">scientist</span> | _field | _value |
|:------------------- |:------------ |:------- |:------ |:-- |:------ |
| 2019-08-18T00:00:00Z | census | klamath | anderson | bees | 23 |
| 2019-08-18T00:00:00Z | census | portland | mullen | ants | 30 |
| 2019-08-18T00:06:00Z | census | klamath | anderson | bees | 28 |
| <span class="tooltip" data-tooltip-text="Timestamp">2019-08-18T00:06:00Z</span> | <span class="tooltip" data-tooltip-text="measurement"> census</span> | <span class ="tooltip" data-tooltip-text ="Tag value">portland</span> | <span class ="tooltip" data-tooltip-text ="Tag value">mullen</span> | <span class ="tooltip" data-tooltip-text ="Field key">ants</span> | <span class ="tooltip" data-tooltip-text ="Field value">32</span> |
## Timestamp
All data stored in InfluxDB has a `_time` column that stores timestamps. On disk, timestamps are stored in epoch nanosecond format. InfluxDB formats timestamps show the date and time in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) UTC associated with data. Timestamp precision is important when you write data.
## Measurement
The `_measurement` column shows the name of the measurement `census`. Measurement names are strings. A measurement acts as a container for tags, fields, and timestamps. Use a measurement name that describes your data. The name `census` tells us that the field values record the number of `bees` and `ants`.
## Fields
A field includes a field key stored in the `_field` column and a field value stored in the `_value` column.
### Field key
A field key is a string that represents the name of the field. In the sample data above, `bees` and `ants` are field keys.
### Field values
A field value represents the value of an associated field. Field values can be strings, floats, integers, or booleans. The field values in the sample data show the number of `bees` at specified times: `23`, and `28` and the number of `ants` at a specified time: `30` and `32`.
### Field sets
A field set is a collection of field key-value pairs associated with a timestamp. The sample data includes the following field sets:
```bash
census bees=23i,ants=30i 1566086400000000000
census bees=28i,ants=32i 1566086760000000000
-----------------
Field set
```
{{% note %}}
**Fields aren't indexed:** Fields are required in InfluxDB data and are not indexed. Queries that filter field values must scan all field values to match query conditions. As a result, queries on tags > are more performant than queries on fields. **Store commonly queried metadata in tags.**
{{% /note %}}
## Tags
The columns in the sample data, `location` and `scientist`, are tags.
Tags include tag keys and tag values that are stored as strings and metadata.
### Tag keys
The tag keys in the sample data are `location` and `scientist`.
### Tag values
The tag key `location` has two tag values: `klamath` and `portland`.
The tag key `scientist` also has two tag values: `anderson` and `mullen`.
### Tag sets
The collection of tag key-value pairs make up a tag set. The sample data includes the following four tag sets:
```bash
location = klamath, scientist = anderson
location = portland, scientist = anderson
location = klamath, scientist = mullen
location = portland, scientist = mullen
```
{{% note %}}
**Tags are indexed:** Tags are optional. You don't need tags in your data structure, but it's typically a good idea to include tags.
Because tags are indexed, queries on tags are faster than queries on fields. This makes tags ideal for storing commonly-queried metadata.
{{% /note %}}
#### Why your schema matters
If most of your queries focus on values in the fields, for example, a query to find when 23 bees were counted:
```js
from(bucket: "bucket-name")
|> range(start: 2019-08-17T00:00:00Z, stop: 2019-08-19T00:00:00Z)
|> filter(fn: (r) => r._field == "bees" and r._value == 23)
```
InfluxDB scans every field value in the dataset for `bees` before the query returns a response. If our sample `census` data grew to millions of rows, to optimize your query, you could rearrange your [schema](/v2.0/reference/glossary/#schema) so the fields (`bees` and `ants`) becomes tags and the tags (`location` and `scientist`) become fields:
| _time | _measurement | <span class ="tooltip" data-tooltip-text ="Tag key">bees</span> | _field | _value |
|:------------------- |:------------ |:------- |:-- |:------ |
| 2019-08-18T00:00:00Z | census | 23 | location | klamath |
| 2019-08-18T00:00:00Z | census | 23 | scientist | anderson |
| 2019-08-18T00:06:00Z | census | <span class ="tooltip" data-tooltip-text ="Tag value">28</span> | <span class ="tooltip" data-tooltip-text ="Field key">location</span> | <span class ="tooltip" data-tooltip-text ="Field value">klamath</span> |
| 2019-08-18T00:06:00Z | census | 28 | scientist | anderson |
| _time | _measurement | <span class ="tooltip" data-tooltip-text ="Tag key">ants</span> | _field | _value |
|:------------------- |:------------ |:------- |:-- |:------ |
| 2019-08-18T00:00:00Z | census | 30 | location | portland |
| 2019-08-18T00:00:00Z | census | 30 | scientist | mullen |
| 2019-08-18T00:06:00Z | census | <span class ="tooltip" data-tooltip-text ="Tag value">32</span> | <span class ="tooltip" data-tooltip-text ="Field key">location</span> | <span class ="tooltip" data-tooltip-text ="Field value">portland</span>|
| 2019-08-18T00:06:00Z | census | 32 | scientist | mullen |
Now that `bees` and `ants` are tags, InfluxDB doesn't have to scan all `_field` and `_value` columns. This makes your queries faster.
## Series
Now that you're familiar with measurements, field sets, and tag sets, it's time to discuss series keys and series. A **series key** is a collection of points that share a measurement, tag set, and field key. For example, the [sample data](#sample-data) includes two unique series keys:
| _measurement | tag set | _field |
|:------------- |:------------------------------- |:------ |
| census | <span class="tooltip" data-tooltip-text="Tag set">location=klamath,scientist=anderson</span> |<span class="tooltip" data-tooltip-text="Field key">bees</span>|
| census | location=portland,scientist=mullen | ants |
A **series** includes timestamps and field values for a given series key. From the sample data, here's a **series key** and the corresponding **series**:
```bash
# series key
census,location=klamath,scientist=anderson bees
# series
2019-08-18T00:00:00Z 23
2019-08-18T00:06:00Z 28
```
Understanding the concept of a series is essential when designing your [schema](v2.0/reference/glossary/#schema) and working with your data in InfluxDB.
## Point
A **point** includes the series key, a field value, and a timestamp. For example, a single point from the [sample data](#sample-data) looks like this:
`2019-08-18T00:00:00Z census ants 30 portland mullen`
## Bucket
All InfluxDB data is stored in a bucket. A **bucket** combines the concept of a database and a retention period (the duration of time that each data point persists). A bucket belongs to an organization. For more information about buckets, see [Manage buckets](https://v2.docs.influxdata.com/v2.0/organizations/buckets/).
## Organization
An InfluxDB **organization** is a workspace for a group of [users](/v2.0/users/). All [dashboards](/v2.0/visualize-data/dashboards/), [tasks](/v2.0/process-data/), buckets, and users belong to an organization. For more information about organizations, see [Manage organizations](https://v2.docs.influxdata.com/v2.0/organizations/).
If you're just starting out, we recommend taking a look at the following guides:
- [Getting Started](/influxdb/v0.10/introduction/getting_started/)
- [Writing Data](/influxdb/v0.10/guides/writing_data/)
- [Querying Data](/influxdb/v0.10/guides/querying_data/)

44
content/v2.0/reference/key-concepts/design-principles.md Normal file
View File

@ -0,0 +1,44 @@
---
title: InfluxDB design principles
description: >
Principles and tradeoffs related to InfluxDB design.
weight: 104
menu:
v2_0_ref:
parent: Key concepts
name: Design principles
v2.0/tags: [key concepts, design principles]
---
InfluxDB implements optimal design principles for time series data. Some of these design principles may have associated tradeoffs in performance.
- [Time-ordered data](#time-ordered-data)
- [Strict update and delete permissions](#strict-update-and-delete-permissions)
- [Handle read and write queries first](#handle-read-and-write-queries-first)
- [Schemaless design](#schemaless-design)
- [Datasets over individual points](#datasets-over-individual-points)
- [Duplicate data](#duplicate-data)
## Time-ordered data
To improve performance, data is written in time-ascending order.
## Strict update and delete permissions
To increase query and write performance, InfluxDB tightly restricts **update** and **delete** permissions. Time series data is predominantly new data that is never updated. Deletes generally only affect data that isn't being written to, and contentious updates never occur.
## Handle read and write queries first
InfluxDB prioritizes read and write requests over strong consistency. InfluxDB returns results when a query is executed. Any transactions that affect the queried data are processed subsequently to ensure that data is eventually consistency. Therefore, if the ingest rate is high (multiple writes per ms), query results may not include the most recent data.
## Schemaless design
InfluxDB uses a schemaless design to better manage discontinuous data. Time series data are often ephemeral, meaning the data appears for a few hours and then go away. For example, a new host that gets started and reports for a while and then gets shut down.
## Datasets over individual points
Because the data set is more important than an individual point, InfluxDB implements powerful tools to aggregate data and handle large data sets. Points are differentiated by timestamp and series, so don’t have IDs in the traditional sense.
## Duplicate data
To simplify conflict resolution and increase write performance, InfluxDB assumes data sent multiple times is duplicate data. Identical points aren't stored twice. If a new field value is submitted for a point, InfluxDB updates the point with the most recent field value. In rare circumstances, data may be overwritten. Learn more about [duplicate points](/v2.0/write-data/best-practices/duplicate-points/).

24
content/v2.0/reference/key-concepts/table-structure.md Normal file
View File

@ -0,0 +1,24 @@
---
draft: true
title: InfluxDB table structure
description: >
InfluxDB uses a columnar system to structure tables.
weight: 103
menu:
v2_0_ref:
parent: Key concepts
name: Table structure
v2.0/tags: [key concepts]
---
InfluxDB 2.0 uses the following columnar table structure to store data:
- **Annotation rows:** include the following rows: #group, #datatype, and #default.
- **Header row:** describes the data labels for each column in a row.
- **Data columns:** include the following columns: annotation, result, and table.
- **Data rows:** all rows that contain time series data. For details about the type of data stored in InfluxDB, see [InfluxDB data elements](/v2.0/reference/key-concepts/data-elements/).
For specifications on the InfluxDB 2.0 table structure, see [Tables](/v2.0/reference/annotated-csv/#tables).
**_Tip:_** To visualize your table structure in the InfluxDB user interface, click the **Data Explorer** icon
in the sidebar, create a query, click **Submit**, and then select **View Raw Data**.