schema查询语法

InfluxQL是一种类似SQL的查询语言，用于与InfluxDB中的数据进行交互。下面我们要介绍一些有用的查询schema的语法：

  • SHOW DATABASES
  • SHOW RETENTION POLICIES
  • SHOW SERIES
  • SHOW MEASUREMENTS
  • SHOW TAG KEYS
  • SHOW TAG VALUES
  • SHOW FIELD KEYS

在开始之前，默认已经登入了CLI：

  1. $ influx -precision rfc3339 
  2. Connected to http://localhost:8086 version 1.3.x
  3. InfluxDB shell 1.3.x
  4. >

SHOW DATABASES

返回当前实例上的所有的数据库。

语法

  1. SHOW DATABASES

例子

例一：运行SHOW DATABASES查询

  1. > SHOW DATABASES
  3. name: databases
  4. name
  5. ----
  6. NOAA_water_database
  7. _internal

SHOW RETENTION POLICIES

返回指定数据库的保留策略的列表。

语法

  1. SHOW RETENTION POLICIES [ON <database_name>]

语法描述

ON <database_name>是可选的。如果查询不包括ON <database_name>，则必须在CLI中使用USE <database_name>指定数据库，或者在HTTP API请求中指定db查询字符串参数。

例子

例一：运行带有ON子句的SHOW RETENTION POLICIES

  1. > SHOW RETENTION POLICIES ON NOAA_water_database
  3. name      duration   shardGroupDuration   replicaN   default
  4. ----      --------   ------------------   --------   -------
  5. autogen   0s         168h0m0s             1          true

该查询以表格格式返回数据库NOAA_water_database中的保留策略列表。 该数据库有一个名为autogen的保留策略。该保留策略具有无限持续时间，持续时间七天的shard group，副本数为1，并且是数据库的DEFAULT保留策略。

例二：运行不带ON子句的SHOW RETENTION POLICIES

CLI

使用USE <database_name>指定数据库：

  1. > USE NOAA_water_database
  2. Using database NOAA_water_database
  4. > SHOW RETENTION POLICIES
  6. name      duration   shardGroupDuration   replicaN   default
  7. ----      --------   ------------------   --------   -------
  8. autogen   0s         168h0m0s             1          true
HTTP API

用db参数指定数据库：

  1. ~# curl -G "http://localhost:8086/query?db=NOAA_water_database&pretty=true" --data-urlencode "q=SHOW RETENTION POLICIES"
  3. {
  4.     "results": [
  5.         {
  6.             "statement_id": 0,
  7.             "series": [
  8.                 {
  9.                     "columns": [
  10.                         "name",
  11.                         "duration",
  12.                         "shardGroupDuration",
  13.                         "replicaN",
  14.                         "default"
  15.                     ],
  16.                     "values": [
  17.                         [
  18.                             "autogen",
  19.                             "0s",
  20.                             "168h0m0s",
  21.                             1,
  22.                             true
  23.                         ]
  24.                     ]
  25.                 }
  26.             ]
  27.         }
  28.     ]
  29. }

SHOW SERIES

返回指定数据库的series列表。

语法

  1. SHOW SERIES [ON <database_name>] [FROM_clause] [WHERE <tag_key> <operator> [ '<tag_value>' | <regular_expression>]] [LIMIT_clause] [OFFSET_clause]

语法描述

ON <database_name>是可选的。如果查询不包括ON <database_name>，则必须在CLI中使用USE <database_name>指定数据库，或者在HTTP API请求中指定db查询字符串参数。

FROM，WHERE，LIMIT和OFFSET子句是可选的。 WHERE子句支持tag比较; field比较对SHOW SERIES查询无效。

WHERE子句中支持的运算符：

= 等于<> 不等于!= 不等于=~ 匹配!~ 不匹配

例子

例一：运行带ON子句的SHOW SERIES

  1. > SHOW SERIES ON NOAA_water_database
  3. key
  4. ---
  5. average_temperature,location=coyote_creek
  6. average_temperature,location=santa_monica
  7. h2o_feet,location=coyote_creek
  8. h2o_feet,location=santa_monica
  9. h2o_pH,location=coyote_creek
  10. h2o_pH,location=santa_monica
  11. h2o_quality,location=coyote_creek,randtag=1
  12. h2o_quality,location=coyote_creek,randtag=2
  13. h2o_quality,location=coyote_creek,randtag=3
  14. h2o_quality,location=santa_monica,randtag=1
  15. h2o_quality,location=santa_monica,randtag=2
  16. h2o_quality,location=santa_monica,randtag=3
  17. h2o_temperature,location=coyote_creek
  18. h2o_temperature,location=santa_monica

查询的输出类似于行协议格式。第一个逗号之前的所有内容都是measurement名称。第一个逗号后的所有内容都是tag key或tag value。 NOAA_water_database有五个不同的measurement和14个不同的series。

例二：运行不带ON子句的SHOW SERIES

CLI

用USE <database_name>指定数据库：

  1. > USE NOAA_water_database
  2. Using database NOAA_water_database
  4. > SHOW SERIES
  6. key
  7. ---
  8. average_temperature,location=coyote_creek
  9. average_temperature,location=santa_monica
  10. h2o_feet,location=coyote_creek
  11. h2o_feet,location=santa_monica
  12. h2o_pH,location=coyote_creek
  13. h2o_pH,location=santa_monica
  14. h2o_quality,location=coyote_creek,randtag=1
  15. h2o_quality,location=coyote_creek,randtag=2
  16. h2o_quality,location=coyote_creek,randtag=3
  17. h2o_quality,location=santa_monica,randtag=1
  18. h2o_quality,location=santa_monica,randtag=2
  19. h2o_quality,location=santa_monica,randtag=3
  20. h2o_temperature,location=coyote_creek
  21. h2o_temperature,location=santa_monica
HTTP API

用db参数指定数据库：

  1. ~# curl -G "http://localhost:8086/query?db=NOAA_water_database&pretty=true" --data-urlencode "q=SHOW SERIES"
  3. {
  4.     "results": [
  5.         {
  6.             "statement_id": 0,
  7.             "series": [
  8.                 {
  9.                     "columns": [
  10.                         "key"
  11.                     ],
  12.                     "values": [
  13.                         [
  14.                             "average_temperature,location=coyote_creek"
  15.                         ],
  16.                         [
  17.                             "average_temperature,location=santa_monica"
  18.                         ],
  19.                         [
  20.                             "h2o_feet,location=coyote_creek"
  21.                         ],
  22.                         [
  23.                             "h2o_feet,location=santa_monica"
  24.                         ],
  25.                         [
  26.                             "h2o_pH,location=coyote_creek"
  27.                         ],
  28.                         [
  29.                             "h2o_pH,location=santa_monica"
  30.                         ],
  31.                         [
  32.                             "h2o_quality,location=coyote_creek,randtag=1"
  33.                         ],
  34.                         [
  35.                             "h2o_quality,location=coyote_creek,randtag=2"
  36.                         ],
  37.                         [
  38.                             "h2o_quality,location=coyote_creek,randtag=3"
  39.                         ],
  40.                         [
  41.                             "h2o_quality,location=santa_monica,randtag=1"
  42.                         ],
  43.                         [
  44.                             "h2o_quality,location=santa_monica,randtag=2"
  45.                         ],
  46.                         [
  47.                             "h2o_quality,location=santa_monica,randtag=3"
  48.                         ],
  49.                         [
  50.                             "h2o_temperature,location=coyote_creek"
  51.                         ],
  52.                         [
  53.                             "h2o_temperature,location=santa_monica"
  54.                         ]
  55.                     ]
  56.                 }
  57.             ]
  58.         }
  59.     ]
  60. }

例三：运行带有多个子句的SHOW SERIES

  1. > SHOW SERIES ON NOAA_water_database FROM "h2o_quality" WHERE "location" = 'coyote_creek' LIMIT 2
  3. key
  4. ---
  5. h2o_quality,location=coyote_creek,randtag=1
  6. h2o_quality,location=coyote_creek,randtag=2

查询返回数据库NOAA_water_database中与measurement h2o_quality相关联的并且tag为location = coyote_creek的两个series。

SHOW MEASUREMENTS

返回指定数据库的measurement列表。

语法

  1. SHOW MEASUREMENTS [ON <database_name>] [WITH MEASUREMENT <regular_expression>] [WHERE <tag_key> <operator> ['<tag_value>' | <regular_expression>]] [LIMIT_clause] [OFFSET_clause]

语法描述

ON <database_name>是可选的。如果查询不包括ON <database_name>，则必须在CLI中使用USE <database_name>指定数据库，或者在HTTP API请求中指定db查询字符串参数。

WITH，WHERE，LIMIT和OFFSET子句是可选的。 WHERE子句支持tag比较; field比较对SHOW MEASUREMENTS查询无效。

WHERE子句中支持的运算符：

= 等于<> 不等于!= 不等于=~ 匹配!~ 不匹配

例子

例一：运行带ON子句的SHOW MEASUREMENTS

  1. > SHOW MEASUREMENTS ON NOAA_water_database
  3. name: measurements
  4. name
  5. ----
  6. average_temperature
  7. h2o_feet
  8. h2o_pH
  9. h2o_quality
  10. h2o_temperature

查询返回数据库NOAA_water_database中的measurement列表。数据库有五个measurement：average_temperature，h2o_feet，h2o_pH，h2o_quality和h2o_temperature。

例二：运行不带ON子句的SHOW MEASUREMENTS

CLI

用USE <database_name>指定数据库。

  1. > USE NOAA_water_database
  2. Using database NOAA_water_database
  4. > SHOW MEASUREMENTS
  5. name: measurements
  6. name
  7. ----
  8. average_temperature
  9. h2o_feet
  10. h2o_pH
  11. h2o_quality
  12. h2o_temperature

HTTP API

使用参数db指定数据库：

  1. ~# curl -G "http://localhost:8086/query?db=NOAA_water_database&pretty=true" --data-urlencode "q=SHOW MEASUREMENTS"
  3. {
  4.   {
  5.       "results": [
  6.           {
  7.               "statement_id": 0,
  8.               "series": [
  9.                   {
  10.                       "name": "measurements",
  11.                       "columns": [
  12.                           "name"
  13.                       ],
  14.                       "values": [
  15.                           [
  16.                               "average_temperature"
  17.                           ],
  18.                           [
  19.                               "h2o_feet"
  20.                           ],
  21.                           [
  22.                               "h2o_pH"
  23.                           ],
  24.                           [
  25.                               "h2o_quality"
  26.                           ],
  27.                           [
  28.                               "h2o_temperature"
  29.                           ]
  30.                       ]
  31.                   }
  32.               ]
  33.           }
  34.       ]
  35.   }

例三：运行有多个子句的SHOW MEASUREMENTS(1)

  1. > SHOW MEASUREMENTS ON NOAA_water_database WITH MEASUREMENT =~ /h2o.*/ LIMIT 2 OFFSET 1
  3. name: measurements
  4. name
  5. ----
  6. h2o_pH
  7. h2o_quality

该查询返回以以h2o开头的NOAA_water_database数据库中的measurement。 LIMIT和OFFSET子句将返回的measurement名称,并且数量限制为两个，再将结果偏移一个，所以跳过了measurementh2o_feet。

例四：运行有多个子句的SHOW MEASUREMENTS(2)

  1. > SHOW MEASUREMENTS ON NOAA_water_database WITH MEASUREMENT =~ /h2o.*/ WHERE "randtag"  =~ /\d/
  3. name: measurements
  4. name
  5. ----
  6. h2o_quality

该查询返回NOAA_water_database中以h2o开头，并且tagrandtag包含一个整数的所有measurement。

SHOW TAG KEYS

返回指定数据库的tag key列表。

语法

  1. SHOW TAG KEYS [ON <database_name>] [FROM_clause] [WHERE <tag_key> <operator> ['<tag_value>' | <regular_expression>]] [LIMIT_clause] [OFFSET_clause]

语法描述

ON <database_name>是可选的。如果查询不包括ON <database_name>，则必须在CLI中使用USE <database_name>指定数据库，或者在HTTP API请求中指定db查询字符串参数。

FROM和WHERE子句是可选的。 WHERE子句支持tag比较; field比较对SHOW TAG KEYS查询无效。

WHERE子句中支持的运算符：

= 等于<> 不等于!= 不等于=~ 匹配!~ 不匹配

例子

例一：运行带有ON子句的SHOW TAG KEYS

  1. > SHOW TAG KEYS ON "NOAA_water_database"
  3. name: average_temperature
  4. tagKey
  5. ------
  6. location
  8. name: h2o_feet
  9. tagKey
  10. ------
  11. location
  13. name: h2o_pH
  14. tagKey
  15. ------
  16. location
  18. name: h2o_quality
  19. tagKey
  20. ------
  21. location
  22. randtag
  24. name: h2o_temperature
  25. tagKey
  26. ------
  27. location

查询返回数据库NOAA_water_database中的tag key列表。输出按measurement名称给tag key分组; 它显示每个measurement都具有tag keylocation，并且measurementh2o_quality具有额外的tag key randtag。

例二：运行不带ON子句的SHOW TAG KEYS

CLI

用USE <database_name>指定数据库：

  1. > USE NOAA_water_database
  2. Using database NOAA_water_database
  4. > SHOW TAG KEYS
  6. name: average_temperature
  7. tagKey
  8. ------
  9. location
  11. name: h2o_feet
  12. tagKey
  13. ------
  14. location
  16. name: h2o_pH
  17. tagKey
  18. ------
  19. location
  21. name: h2o_quality
  22. tagKey
  23. ------
  24. location
  25. randtag
  27. name: h2o_temperature
  28. tagKey
  29. ------
  30. location
HTTP API

用参数db指定数据库：

  1. ~# curl -G "http://localhost:8086/query?db=NOAA_water_database&pretty=true" --data-urlencode "q=SHOW TAG KEYS"
  3. {
  4.     "results": [
  5.         {
  6.             "statement_id": 0,
  7.             "series": [
  8.                 {
  9.                     "name": "average_temperature",
  10.                     "columns": [
  11.                         "tagKey"
  12.                     ],
  13.                     "values": [
  14.                         [
  15.                             "location"
  16.                         ]
  17.                     ]
  18.                 },
  19.                 {
  20.                     "name": "h2o_feet",
  21.                     "columns": [
  22.                         "tagKey"
  23.                     ],
  24.                     "values": [
  25.                         [
  26.                             "location"
  27.                         ]
  28.                     ]
  29.                 },
  30.                 {
  31.                     "name": "h2o_pH",
  32.                     "columns": [
  33.                         "tagKey"
  34.                     ],
  35.                     "values": [
  36.                         [
  37.                             "location"
  38.                         ]
  39.                     ]
  40.                 },
  41.                 {
  42.                     "name": "h2o_quality",
  43.                     "columns": [
  44.                         "tagKey"
  45.                     ],
  46.                     "values": [
  47.                         [
  48.                             "location"
  49.                         ],
  50.                         [
  51.                             "randtag"
  52.                         ]
  53.                     ]
  54.                 },
  55.                 {
  56.                     "name": "h2o_temperature",
  57.                     "columns": [
  58.                         "tagKey"
  59.                     ],
  60.                     "values": [
  61.                         [
  62.                             "location"
  63.                         ]
  64.                     ]
  65.                 }
  66.             ]
  67.         }
  68.     ]
  69. }

例三：运行带有多个子句的SHOW TAG KEYS

  1. > SHOW TAG KEYS ON "NOAA_water_database" FROM "h2o_quality" LIMIT 1 OFFSET 1
  3. name: h2o_quality
  4. tagKey
  5. ------
  6. randtag

该查询从数据库NOAA_water_database的measurementh2o_quality中返回tag key。 LIMIT和OFFSET子句限制返回到一个tag key，再将结果偏移一个。

SHOW TAG VALUES

返回数据库中指定tag key的tag value列表。

语法

  1. SHOW TAG VALUES [ON <database_name>][FROM_clause] WITH KEY [ [<operator> "<tag_key>" | <regular_expression>] | [IN ("<tag_key1>","<tag_key2")]] [WHERE <tag_key> <operator> ['<tag_value>' | <regular_expression>]] [LIMIT_clause] [OFFSET_clause]

语法描述

ON <database_name>是可选的。如果查询不包括ON <database_name>，则必须在CLI中使用USE <database_name>指定数据库，或者在HTTP API请求中指定db查询字符串参数。

WITH子句是必须的，它支持指定一个单独的tag key、一个表达式或是多个tag key。

FROM、WHERE、LIMIT和OFFSET子句是可选的。 WHERE子句支持tag比较; field比较对SHOW TAG KEYS查询无效。

WHERE子句中支持的运算符：

= 等于<> 不等于!= 不等于=~ 匹配!~ 不匹配

例子

例一：运行带有ON子句的SHOW TAG VALUES

  1. > SHOW TAG VALUES ON "NOAA_water_database" WITH KEY = "randtag"
  3. name: h2o_quality
  4. key       value
  5. ---       -----
  6. randtag   1
  7. randtag   2
  8. randtag   3

该查询返回数据库NOAA_water_database，tag key为randtag的所有tag value。SHOW TAG VALUES将结果按measurement名字分组。

例二：运行不带ON子句的SHOW TAG VALUES

CLI

用USE <database_name>指定数据库：

  1. > USE NOAA_water_database
  2. Using database NOAA_water_database
  4. > SHOW TAG VALUES WITH KEY = "randtag"
  6. name: h2o_quality
  7. key       value
  8. ---       -----
  9. randtag   1
  10. randtag   2
  11. randtag   3
HTTP API

用参数db指定数据库：

  1. ~# curl -G "http://localhost:8086/query?db=NOAA_water_database&pretty=true" --data-urlencode 'q=SHOW TAG VALUES WITH KEY = "randtag"'
  3. {
  4.     "results": [
  5.         {
  6.             "statement_id": 0,
  7.             "series": [
  8.                 {
  9.                     "name": "h2o_quality",
  10.                     "columns": [
  11.                         "key",
  12.                         "value"
  13.                     ],
  14.                     "values": [
  15.                         [
  16.                             "randtag",
  17.                             "1"
  18.                         ],
  19.                         [
  20.                             "randtag",
  21.                             "2"
  22.                         ],
  23.                         [
  24.                             "randtag",
  25.                             "3"
  26.                         ]
  27.                     ]
  28.                 }
  29.             ]
  30.         }
  31.     ]
  32. }

例三：运行带有多个子句的SHOW TAG VALUES

  1. > SHOW TAG VALUES ON "NOAA_water_database" WITH KEY IN ("location","randtag") WHERE "randtag" =~ /./ LIMIT 3
  3. name: h2o_quality
  4. key        value
  5. ---        -----
  6. location   coyote_creek
  7. location   santa_monica
  8. randtag       1

该查询从数据库NOAA_water_database的所有measurement中返回tag key为location或者randtag，并且randtag的tag value不为空的tag value。 LIMIT子句限制返回三个tag value。

SHOW FIELD KEYS

返回field key以及其field value的数据类型。

语法

  1. SHOW FIELD KEYS [ON <database_name>] [FROM <measurement_name>]

语法描述

ON <database_name>是可选的。如果查询不包括ON <database_name>，则必须在CLI中使用USE <database_name>指定数据库，或者在HTTP API请求中指定db查询字符串参数。

FROM子句也是可选的。

例子

例一：运行一个带ON子句的SHOW FIELD KEYS

  1. > SHOW FIELD KEYS ON "NOAA_water_database"
  3. name: average_temperature
  4. fieldKey            fieldType
  5. --------            ---------
  6. degrees             float
  8. name: h2o_feet
  9. fieldKey            fieldType
  10. --------            ---------
  11. level description   string
  12. water_level         float
  14. name: h2o_pH
  15. fieldKey            fieldType
  16. --------            ---------
  17. pH                  float
  19. name: h2o_quality
  20. fieldKey            fieldType
  21. --------            ---------
  22. index               float
  24. name: h2o_temperature
  25. fieldKey            fieldType
  26. --------            ---------
  27. degrees             float

该查询返回数据库NOAA_water_database中的每个measurement对应的field key以及其数据类型。

例二：运行一个不带ON子句的SHOW FIELD KEYS

CLI

用USE <database_name>指定数据库：

  1. > USE NOAA_water_database
  2. Using database NOAA_water_database
  4. > SHOW FIELD KEYS
  6. name: average_temperature
  7. fieldKey            fieldType
  8. --------            ---------
  9. degrees             float
  11. name: h2o_feet
  12. fieldKey            fieldType
  13. --------            ---------
  14. level description   string
  15. water_level         float
  17. name: h2o_pH
  18. fieldKey            fieldType
  19. --------            ---------
  20. pH                  float
  22. name: h2o_quality
  23. fieldKey            fieldType
  24. --------            ---------
  25. index               float
  27. name: h2o_temperature
  28. fieldKey            fieldType
  29. --------            ---------
  30. degrees             float
HTTP API

用参数db指定数据库：

  1. ~# curl -G "http://localhost:8086/query?db=NOAA_water_database&pretty=true" --data-urlencode 'q=SHOW FIELD KEYS'
  3. {
  4.     "results": [
  5.         {
  6.             "statement_id": 0,
  7.             "series": [
  8.                 {
  9.                     "name": "average_temperature",
  10.                     "columns": [
  11.                         "fieldKey",
  12.                         "fieldType"
  13.                     ],
  14.                     "values": [
  15.                         [
  16.                             "degrees",
  17.                             "float"
  18.                         ]
  19.                     ]
  20.                 },
  21.                 {
  22.                     "name": "h2o_feet",
  23.                     "columns": [
  24.                         "fieldKey",
  25.                         "fieldType"
  26.                     ],
  27.                     "values": [
  28.                         [
  29.                             "level description",
  30.                             "string"
  31.                         ],
  32.                         [
  33.                             "water_level",
  34.                             "float"
  35.                         ]
  36.                     ]
  37.                 },
  38.                 {
  39.                     "name": "h2o_pH",
  40.                     "columns": [
  41.                         "fieldKey",
  42.                         "fieldType"
  43.                     ],
  44.                     "values": [
  45.                         [
  46.                             "pH",
  47.                             "float"
  48.                         ]
  49.                     ]
  50.                 },
  51.                 {
  52.                     "name": "h2o_quality",
  53.                     "columns": [
  54.                         "fieldKey",
  55.                         "fieldType"
  56.                     ],
  57.                     "values": [
  58.                         [
  59.                             "index",
  60.                             "float"
  61.                         ]
  62.                     ]
  63.                 },
  64.                 {
  65.                     "name": "h2o_temperature",
  66.                     "columns": [
  67.                         "fieldKey",
  68.                         "fieldType"
  69.                     ],
  70.                     "values": [
  71.                         [
  72.                             "degrees",
  73.                             "float"
  74.                         ]
  75.                     ]
  76.                 }
  77.             ]
  78.         }
  79.     ]
  80. }

例三：运行带有FROM子句的SHOW FIELD KEYS

  1. > SHOW FIELD KEYS ON "NOAA_water_database" FROM "h2o_feet"
  3. name: h2o_feet
  4. fieldKey            fieldType
  5. --------            ---------
  6. level description   string
  7. water_level         float

该查询返回数据库NOAA_water_database中measurement为h2o_feet的对应的field key以及其数据类型。

SHOW FIELD KEYS的常见问题

问题一：SHOW FIELD KEYS和field 类型的差异

field value的数据类型在同一个shard里面一样但是在多个shard里面可以不同，SHOW FIELD KEYS遍历每个shard返回与field key相关的每种数据类型。

例子

field all_the_types中存储了四个不同的数据类型

  1. > SHOW FIELD KEYS
  3. name: mymeas
  4. fieldKey        fieldType
  5. --------        ---------
  6. all_the_types   integer
  7. all_the_types   float
  8. all_the_types   string
  9. all_the_types   boolean

注意SHOW FIELD KEYS处理field的类型差异和SELECT语句不一样。