查询语言参考(版本 0.7)

利用 Google Visualization API 查询语言,您可以对对数据源的查询执行各种数据操作。

目录

简介

通常,可视化图表需要某种特定形式的数据。例如,饼图可能需要两列数据:文本标签和数值。数据源中的数据未必与此结构完全一致。 例如,数据源可能有两列以上,或者列的顺序可能与饼图的预期顺序不匹配。

查询语言能够向数据源发送数据操作和格式设置请求,并确保返回的数据结构和内容与预期结构相匹配。

查询语言的语法与 SQL 类似。熟悉 SQL 的开发者应该能够快速学习和使用此查询语言。您可以在网上找到许多 SQL 教程。 此查询语言与 SQL 之间存在一些差异,详情请参阅syntax部分。

请注意,数据源无需实现查询语言,如果实现查询语言,也无需实现该语言的所有功能。除非您有理由相信,否则您不应依赖数据源来实现此语言的所有功能。

使用查询语言

您可以通过以下两种方式将查询字符串附加到数据源请求:在 JavaScript 代码中设置查询字符串,或在数据源网址中将查询字符串设置为参数。如果您的请求不包含查询字符串,则数据源的默认行为是使用默认行/列顺序和格式返回所有行和列。若要更改这种情况,您可以在向数据源发送的请求中添加查询字符串。

通过 JavaScript 设置查询

如需在 JavaScript 代码中设置查询字符串,请调用 google.visualization.Query 类的 setQuery 方法。

var query = new google.visualization.Query(DATA_SOURCE_URL);
query.setQuery('select dept, sum(salary) group by dept');
query.send(handleQueryResponse);

在数据源网址中设置查询

您可以使用 tq 参数将查询字符串添加到数据源网址中。在网址参数(而不是 JavaScript)中设置查询可让您轻松使用其他开发者编写的可视化图表,并且仍然可以自定义查询。

查询字符串必须正确编码为网址参数。您可以使用 JavaScript encodeURIComponent 函数对网址进行编码,也可以使用本部分末尾的编码工具手动对网址进行编码。

示例

考虑 Google 电子表格的以下查询字符串。(请注意,电子表格中的列 ID 始终是字母;已发布的电子表格中显示的列标题文字是标签,而不是 ID。您必须在查询字符串中使用 ID,而不是标签。)

select A, sum(B) group by A

编码后,此查询会变为:

select%20A%2C%20sum(B)%20group%20by%20A

假设您电子表格的网址如下:

https://docs.google.com/a/google.com/spreadsheets/d/1r8_mfnZAvTFmT02JHi1XgOwn_-sLCR9XgmR8wEQ4uW4

/gviz/tq?tq=YOUR_QUERY_STRING 添加到电子表格网址,以获取最终的查询字符串:

https://docs.google.com/a/google.com/spreadsheets/d/1r8_mfnZAvTFmT02JHi1XgOwn_-sLCR9XgmR8wEQ4uW4/gviz/tq?tq=select%A%2C%20sum(B)%20group%20by%20A

使用以下工具对查询字符串进行编码或解码:

注意:访问不公开的电子表格数据需要使用 OAuth 传递明确的授权凭据。如需了解详情,请参阅 Google 电子表格:授权部分。

语言语法

概览

Google Visualization API 查询语言语法的设计类似于 SQL 语法。不过,它是 SQL 的子集,具有一些自己的特性,需要您学习一下。如果您熟悉 SQL,学习起来应该不会太难。

数据表格

本文档使用“数据表”一词来指代查询结果集。数据表由行和列组成。 数据表中的每一列都具有以下属性:

  • 标识符(或列 ID)。用于引用查询中的列。请注意,切勿在查询中尝试按标签引用列,而应仅按标识符引用列。提示尽量不要使用任何包含空格的 ID;空格难以管理,并且可能会导致您在编码过程中出现小但很难发现的错误。此外,包含空格的 ID 必须用反引号括起来。
  • Label(标签)。通常向最终用户显示的 string。例如,在饼图中显示图例,或在表格中以列标题。
  • 数据类型。支持的数据类型包括 stringnumberbooleandatedatetimetimeofday。列的所有值都将具有与列类型匹配的数据类型或 null 值。这些类型与 JavaScript 类型(如本页文字部分所述)类似,却不完全相同。
  • 格式设置模式。数据源可以为其部分或全部列定义格式模式。您可以通过添加格式子句来替换此模式。

所有示例中使用的表

在本部分中,所有查询示例均引用下表。列标题是列标识符。

名称
string
部门
string
lunchTime
timeofday
薪资
number
hireDate
date
年龄
number
isSenior
boolean
seniorityStartTime
datetime
John拉丁文小写字母 eng12:00:00
1000
2005-03-1935true2007-12-02 15:56:00
Dave拉丁文小写字母 eng12:00:00
500
2006-04-1927falsenull
莎莉拉丁文小写字母 eng13:00:00
600
2005-10-1030falsenull
Ben销售12:00:00
400
2002-10-1032true2005-03-09 12:30:00
达纳销售12:00:00
350
2004-09-0825falsenull
Mike营销13:00:00
800
2005-01-1024true2007-12-30 14:40:00

语言子句

查询语言的语法由以下子句组成。每个子句都以一个或两个关键字开头。所有子句均为可选子句。子句之间用空格分隔。子句的顺序必须如下所示:

子句 用量
select 选择要返回的列以及返回顺序。如果省略,系统会按默认顺序返回表的所有列。
where 仅返回与条件匹配的行。如果省略,则返回所有行。
group by 对各行的值进行汇总。
pivot 将列中的不同值转换为新列。
order by 按列中的值对行进行排序。
limit 限制返回的行数。
offset 跳过一定数量的前几行。
label 设置列标签。
format 使用给定的格式模式对某些列中的值进行格式设置。
options 设置其他选项。
from 语言中删除了 from 子句。

 

选择

select 子句用于指定要返回的列及其顺序。 如果未指定此子句,或使用 select *,则系统将按原始顺序返回数据源表的所有列。列由标识符(而不是标签)引用。例如,在 Google 电子表格中,列标识符为一个或两个字符的列字母(A、B、C...)。

select 子句中的项可以是列标识符,也可以是聚合函数标量函数运算符的输出。

示例

select *
select dept, salary
select max(salary)

在以下示例中,反引号用于引用包含空格(电子邮件地址)或保留字(日期)的列 ID:

select `email address`, name, `date`

示例表运行以下查询:

select lunchTime, name

返回以下响应:

lunchTime name
12:00:00John
12:00:00Dave
13:00:00莎莉
12:00:00Ben
12:00:00达纳
13:00:00Mike

地点

where 子句用于仅返回与指定条件匹配的行。

简单的比较运算符为 <=, <, >, >=, =, !=, <>。两个比较运算符 != <> 表示不相等。字符串按字典值进行比较。请注意,等式由 = 表示,而不是在大多数计算机语言中用 == 表示。null 进行比较的操作是使用 is nullis not null 完成的。

您可以使用逻辑运算符 andornot 将多个条件组合起来。圆括号可用于定义明确的优先级。

where 子句还支持一些更复杂的字符串比较运算符。 这些运算符将两个字符串作为参数;任何非字符串参数(例如日期或数字)在比较之前都将转换为字符串。字符串匹配区分大小写(您可以使用 upper()lower() 标量函数来解决此问题)。

  • contains - 子字符串匹配。如果 part 位于 whole 中的任何位置,则 whole contains part 为 true。示例where name contains 'John' 与“John”“John Adams”“Long John Silver”匹配,但与“john adams”不匹配。
  • starts with - 前缀匹配。如果 prefix 位于 value 的开头,则 value starts with prefix 为 true。示例where dept starts with 'engineering' 与 'engineering' 和 'engineering manager' 匹配。 where dept starts with 'e' 与“engineering”“eng”和“e”匹配。
  • ends with - 后缀匹配。如果 value 位于 value 末尾,则 suffix 为 true。 ends with示例where role ends with 'y' 与“cowboy”“boy”和“y”匹配。
  • matches - (preg) 正则表达式匹配。haystack matches如果 needle 中的正则表达式与 haystack 匹配,则为 true。 示例where country matches '.*ia' 与印度和尼日利亚匹配,但与印第安纳州不匹配。请注意,这不是全球搜索,因此 where country matches 'an' 不会与“加拿大”匹配。
  • like - 支持两种通配符的文本搜索:%(匹配零个或多个任意种类的字符)和 _(下划线),其匹配任何一个字符。这与 SQL LIKE 运算符类似。 示例where name like fre% 与“fre”“fred”和“freddy”匹配。

示例

where salary >= 600
where dept != 'Eng' and date '2005-01-21' < hireDate
where (dept<>'Eng' and isSenior=true) or (dept='Sales') or seniorityStartTime is null

示例表运行以下查询:

select name where salary > 700

返回以下响应:

name
John
Mike

分组依据

group by 子句用于跨行聚合值。 系统会为“group-by”子句中每个不同的值组合创建一行。除非 order by 子句另行指定,否则数据按分组列自动排序。

注意:如果使用 group by 子句,则 select 子句中列出的每一列必须列在 group by 子句中,或者由聚合函数封装。

示例

select dept, max(salary) group by dept

示例表运行以下查询:

select lunchTime, avg(salary), count(age) group by isSenior,lunchTime

返回以下响应:

lunchTime 平均工资 统计年龄
12:00:00 425 2
13:00:00 600 1
12:00:00 700 2
13:00:00 800 1

数据透视

pivot 子句用于将列中的不同值转换为新列。例如,按“year”列进行数据透视会生成一个表,其中一列对应于原始表中出现的每个不同年份。例如,如果折线图可视化图表将每一列都绘制为一条单独的线条,那么这会很有用。如果要为每一年单独绘制一条线,并且“year”是原始表的一列,则使用透视操作执行必要的数据转换是一种不错的选择。

注意:如果使用 pivot 子句,则 select 子句中列出的每一列必须列在 group by 子句中,或者由聚合函数封装

由于多行可能包含数据透视列的相同值,因此数据透视意味着汇总。请注意,在不使用 group by 的情况下使用 pivot 时,结果表将仅包含一行。例如,对示例表运行以下查询:

select sum(salary) pivot dept

返回以下响应:

工程总工资 营销总薪资 销售总薪资
2100 800 750

这是因为 2100 是工程部门的工资总和,而营销部门的工资总和是 800 等。

pivotgroup by 结合使用会更加实用,因为它会创建一个表,其中每个单元格都包含相关行和相关列的聚合结果。例如,对示例表运行以下查询:

select dept, sum(salary)
  group by dept
  pivot lunchTime

返回以下响应:

部门 12:00:00 总工资 13:00:00 总工资
拉丁文小写字母 eng 1500 600
营销 null 800
销售 750 null

您也可以在 pivot 列和 group by 列之间切换,以“反转”此表格,切换列和行。对示例表运行以下查询:

select lunchTime, sum(salary)
  group by lunchTime
  pivot dept

返回以下响应:

lunchTime 工程总工资 营销总薪资 销售总薪资
12:00:00 1500 null 750
13:00:00 600 800 null

您还可以在 pivot 子句中使用多个列。在这种情况下,响应表中的列由原始表中的值的所有唯一值组合组成。例如,对示例表运行以下查询:

select sum(salary)
  pivot dept, lunchTime

返回以下响应:

英语,12:00:00 总工资 工程,13:00:00 总工资 营销,13:00:00 总工资 销售,12:00:00 总工资
1500 600 800 750

请注意,只有原始表中显示的组合才会成为响应表中的列。这就是为什么没有“营销,12:00:00”或“销售”,13:00:00 列的原因。

您也可以使用多种聚合方式。例如,对示例表运行以下查询:

select sum(salary), max(lunchTime)
  pivot dept

返回以下响应:

工程总工资 营销总薪资 销售总薪资 英语 Max-lunchTime 营销最长午餐时间 销售最长午餐时间
2100 800 750 13:00:00 13:00:00 12:00:00

您可以合并 select 子句中的多个聚合、group by 子句中的多列以及 pivot 子句中的多列。在内部,聚合是通过将“Group by”和“pivot”子句中的列串联在一起来执行的。

pivot 子句中指定的列不能出现在 selectgroup byorder by 子句中。使用 pivot 时,order by 子句不能包含任何聚合列。其原因在于,对于 select 子句中指定的每项聚合,结果表中都会生成许多列。不过,您可以使用 pivot 设置汇总列的格式。这种格式的结果是,由数据透视操作生成与特定聚合相关的所有新列都采用指定模式的格式。在上面的示例中,添加 format sum(salary) "some_format_string" 将影响以下列:Egsum-salary、Marketingsum-salary 和 Salessum-salary。

您可以为汇总列添加标签。如果 label 子句中未指定标签,则透视所生成的列的标签由数据透视列中的值列表、聚合类型(最小值、最大值、总和...)和聚合列的标签组成。例如“Eng,12:00:00sum Salary”。如果 select 子句中仅指定了一种聚合,则系统会从标签中移除聚合部分,并且仅保留数据透视列中的值列表。例如“Eng,12:00:00”。当 label 子句为汇总列指定标签时,当 select 子句中只有一个汇总且有多个汇总时,请求的标签会附加到值列表中。例如,label sum(salary) "sumsal" 会生成列标签“Eng,12:00:00sumsal”“Eng,13:00:00sumsal”等。

排序依据

order by 子句用于按指定列中的值对行进行排序。

order by 子句中的项可以是列标识符,也可以是聚合函数标量函数运算符的输出。

示例

order by dept, salary desc
select dept, max(salary) group by dept order by max(salary)

限制

limit 子句用于限制返回的行数。

示例

limit 100

偏移

offset 子句用于跳过给定数量的前几行。如果使用 limit 子句,则首先应用 offset:例如,limit 15 offset 30 返回第 31 行到第 45 行。

示例

offset 10
limit 30 offset 210

标签

label 子句用于为一列或多列设置标签。请注意,在查询中,不能使用标签值代替 ID。

label 子句中的项可以是列标识符,也可以是聚合函数标量函数运算符的输出。

语法

label column_id label_string [,column_id label_string]
column_id
:要向其分配标签的列的标识符
label_string
要分配给该列的标签。许多可视化图表会使用列标签作为文本来向最终用户显示,例如饼图中的图例标签。标签是字符串字面量,并遵循这些语法规则。

示例

以下示例将 dept 列的标签设置为“Department”,将名称列的标签设置为“Employee Name”,将位置列的标签设置为“Employee Location”:

label dept 'Department', name "Employee Name", location 'Employee Location'

格式

format 子句用于为一列或多列中的单元格指定设置了格式的值。返回的数据应同时包含设置了格式的列中每个单元格的实际值和格式化值。许多可视化图表使用未设置格式的值进行计算,但使用格式化值进行显示。您在此子句中指定的模式通常在相应列的 pattern 属性中返回。

模式语法

numberdatetimeofdaydatetime
ICU 定义的日期数字模式。
boolean
模式是格式为“value-if-true:value-if-false”的 string

示例

format salary '#,##0.00', hireDate 'dd-MMM-yyyy', isSenior 'Yes!:Not yet'

 

选项

options 子句用于控制用于执行查询的其他选项。可能跟随 options 子句的关键字有:

  • no_format 从结果中移除设置了格式的值,仅保留基础值。 当特定可视化图表不使用带格式的值来缩减响应大小时,可以使用此属性。
  • no_values 从结果中移除基础值,只保留已设置格式的值。可在特定可视化图表仅使用格式化值以减小响应大小时使用。

数据操纵函数

利用多种运算符和函数,您可以在单个列中处理或聚合数据,或者跨列比较或合并数据。示例包括 sum()(将某列中的所有值相加)、max(用于找出某一列中的最大值)和 +(将两列的值相加到同一行中)。

有些函数可以出现在任何子句中;有些函数可以出现在子句的子集中。记录如下。

示例

根据此表... 如果我们应用此查询... 我们得到了这个结果
名称 薪资 税费 StartDate
Sharon 1000 100 2009-1-1
英伟达 2000 200 2008-1-21
Moran 3000 300 2008-2-12
select upper(name), year(startDate)
名称 年(开始日期)
视听 2008
莫兰 2008
SHARON 2009

 

以下数据操作函数由 Google Visualization API 查询语言定义:

 

聚合函数

系统会向聚合函数传递单个列标识符,并对每个组中的所有值执行操作(组由 group bypivot 子句指定,如果未使用这些子句,则所有行指定)。

示例

select max(salary)               // Returns a table with one column and one row.
select max(salary) group by dept // Returns a table with the max salary for each dept column value.
select max(salary) pivot dept    // Returns a one-row table with a column for each dept,
                                 //   and the max salary for that department.

聚合函数可用在 selectorder bylabelformat 子句中。它们不能 出现在 wheregroup bypivotlimitoffsetoptions 子句中。

以下是支持的聚合函数:

名称 说明 支持的列类型 返回值类型
avg() 返回组的相应列中所有值的平均值。 number number
count() 返回组的指定列中的元素数量。Null 单元格不计算在内。 任何类型 number
max() 返回组的列中的最大值。日期比较的是较早的日期,string 按字母顺序进行比较,区分大小写。 任何类型 类型与列相同
min() 返回组的列中的最小值。日期与早前较小的日期进行比较;string 按字母顺序进行比较,区分大小写 任何类型 类型与列相同
sum() 返回组的相应列中所有值的总和。 number number

注意:聚合函数只能将列标识符用作参数:

max(startDate)                      // OK
min(firstScore) + min(secondScore)  // OK
max(year(startDate))                // INVALID. max requires column ID
sum(salary + perks)                 // INVALID. sum requires column ID.

标量函数

标量函数对零个或多个参数执行操作以生成另一个值。您可向标量函数传递计算结果为相应类型参数的任何表达式。请注意,这些类型是本文档文字部分中定义的类型,可能与名称相似的 JavaScript 对象略有不同。

请注意,列名称将通过标量函数封装来更改。

标量函数可以将计算结果为单个值的任何内容作为参数:

year(max(startDate))
datediff(now(), todate(1234567890000))

标量函数可用于以下任何子句:selectwheregroup bypivotorder bylabel, format

名称
year()

根据日期或日期时间值返回年份值。例如: year(date "2009-02-05") 会返回 2009。

参数:一个类型为 datedatetime 的参数
返回值类型number
month()

从日期或日期时间值返回从零开始的月份值。例如:month(date "2009-02-05") 会返回 1。注意:月份从 0 开始,因此该函数针对 1 月返回 0,针对 2 月返回 1,依此类推。

参数:一个类型为 datedatetime 的参数
返回值类型number
day()

根据 date 或日期时间值返回一个月中的某一天。例如:day(date "2009-02-05") 会返回 5。

参数:一个类型为 datedatetime 的参数
返回值类型number
hour()

从日期时间或 timeofday 值返回小时值。例如:hour(timeofday "12:03:17") 会返回 12。

参数:一个类型为 datetimetimeofday 的参数
返回值类型number
minute()

datetimetimeofday 值返回分钟值。例如:minute(timeofday "12:03:17") 会返回 3。

参数:一个类型为 datetimetimeofday 的参数
返回值类型number
second()

返回 datetimetimeofday 值的第二个值。例如:second(timeofday "12:03:17") 会返回 17。

参数:一个类型为 datetimetimeofday 的参数
返回值类型number
millisecond()

返回 datetimetimeofday 值的毫秒部分。例如:millisecond(timeofday "12:03:17.123") 会返回 123。

参数:一个类型为 datetimetimeofday 的参数
返回值类型number
quarter()

返回 datedatetime 值的季度。例如:quarter(date "2009-02-05") 会返回 1。请注意,季度从 1 开始计算,因此该函数针对第一个季度返回 1,针对第二个季度返回 2,依此类推。

参数:一个类型为 datedatetime 的参数
返回值类型number
dayOfWeek()

datedatetime 值返回星期几。例如:dayOfWeek(date "2009-02-26") 会返回 5。请注意,日期从 1 开始,因此该函数会返回 1 表示周日,2 表示周一,依此类推。

参数:一个类型为 datedatetime 的参数
返回值类型number
now()

返回表示当前 datetime 的日期时间值(采用 GMT 时区)。

参数:无
返回值类型datetime
dateDiff()

返回两个 datedatetime 值之间的天数差值。 注意:计算中仅使用值的 date 部分,因此该函数始终返回整数值。例如:dateDiff(date "2008-03-13", date "2008-02-12") 返回 29;dateDiff(date "2009-02-13", date "2009-03-13") 返回 -29。 时间值在比较之前会被截断。

参数datedatetime 类型的两个参数(可以分别是其中一个)
返回值类型number
toDate()

将指定值转换为 date 值。

  • 对于给定的 date,它会返回相同的值。
  • 对于 datetime,它会返回 date 部分。例如:toDate(dateTime "2009-01-01 12:00:00") 会返回“2009-01-01”。
  • 对于给定的 number N,它会在 Epoch 后返回 date N 毫秒。“纪元”定义为 GMT 1970 年 1 月 1 日 00:00:00。例如:toDate(1234567890000) 会返回“2009-02-13”。
参数:一个类型为 datedatetimenumber 的参数
返回值类型date
upper()

返回指定的 string(以大写字母表示)。例如:upper("foo") 会返回“FOO”。

参数:一个类型为 string 的参数
返回值类型string
lower()

返回指定的 string(采用小写字母)。例如:lower("Bar") 会返回“bar”。

参数:一个类型为 string 的参数
返回值类型string

算术运算符

您可以使用算术运算符对计算结果为单个数字的任何内容(即相应聚合函数、运算符或常量的输出)执行数学运算。

示例

select empSalary - empTax
select 2 * (max(empSalary) / max(empTax))

定义了以下运算符:

名称 说明 参数 返回值类型
+ 返回两个 number 值的总和。 两个 number number
- 返回两个 number 值之间的差值。 两个 number number
* 返回两个 number 的乘积。 两个 number number
/ 返回两个 number 的商。除以 0 会返回 null。 两个 number number

语言元素

文字

字面量是用于比较或赋值的值。字面量可以是 string、数字、布尔值或各种日期/时间类型。以下是查询语法中使用的字面量的一些示例:

where startDate < date "2008-03-18"  // date "2008-03-18" is a date literal
limit 30                             // 30 is a numeric literal
format salary '#,##0.00', isSenior 'not yet:of course!'  // '#,##0.00' and 'not yet:of course!' are both string literals

以下是每类字面量的格式:

string
string 字面量应用单引号或双引号括起来。示例"fourteen" 'hello world' "It's raining"
number
数字字面量以十进制表示法指定。示例 3  3.0  3.14  -71  -7.2  .6
boolean
布尔值字面量为 truefalse
date
使用关键字 date,后跟 yyyy-MM-dd 格式的 string 字面量。示例date "2008-03-18"
timeofday
使用关键字 timeofday,后跟 string 字面量,格式为 HH:mm:ss[.SSS] 示例timeofday "12:30:45"
datetime
日期和时间,使用关键字 datetime 或关键字 timestamp,后跟 yyyy-MM-dd HH:mm:ss[.sss] 格式的 string 字面量。示例datetime '2008-03-18 12:30:34.123'

标识符

标识符(或 ID)是用于标识列的文本 string

重要提示:如果您的标识符

  • 包含空格
  • 是一个保留字词
  • 包含字母数字字符或下划线 ([a-zA-Z0-9_]) 以外的任何内容,或者
  • 以数字开头

必须用反引号(而不是单引号)括起来。

否则,无需加上引号您的标识符。(请注意,并非所有由语法定义的关键字均为保留字词;因此,例如,您可以将“max”用作标识符,而无需将其反引号引用。)

示例col1   employee_table   `start date`   `7 days traffic`   `select`

我们建议您不要选择需要反引号的标识符,因为很容易忘记使用反引号,或者不小心使用“单引号”而不是“反引号”。这些都是常见的错误,通常很难调试。

区分大小写

标识符和字符串字面量区分大小写。 其他所有语言元素均不区分大小写。

保留字词

如果将以下保留字用作标识符,则必须带反引号:

and
asc
by
date
datetime
desc
false
format
group
label
limit
not
offset
options
or
order
pivot
select
timeofday
timestamp
true
where