利用 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
。例如,在饼图中显示图例,或在表格中以列标题。 - 数据类型。支持的数据类型包括
string
、number
、boolean
、date
、datetime
和timeofday
。列的所有值都将具有与列类型匹配的数据类型或null
值。这些类型与 JavaScript 类型(如本页文字部分所述)类似,却不完全相同。 - 格式设置模式。数据源可以为其部分或全部列定义格式模式。您可以通过添加格式子句来替换此模式。
在本部分中,所有查询示例均引用下表。列标题是列标识符。
名称string |
部门string |
lunchTimetimeofday |
薪资 number |
hireDatedate |
年龄number |
isSeniorboolean |
seniorityStartTimedatetime |
---|---|---|---|---|---|---|---|
John | 拉丁文小写字母 eng | 12:00:00 | 1000 | 2005-03-19 | 35 | true | 2007-12-02 15:56:00 |
Dave | 拉丁文小写字母 eng | 12:00:00 | 500 | 2006-04-19 | 27 | false | null |
莎莉 | 拉丁文小写字母 eng | 13:00:00 | 600 | 2005-10-10 | 30 | false | null |
Ben | 销售 | 12:00:00 | 400 | 2002-10-10 | 32 | true | 2005-03-09 12:30:00 |
达纳 | 销售 | 12:00:00 | 350 | 2004-09-08 | 25 | false | null |
Mike | 营销 | 13:00:00 | 800 | 2005-01-10 | 24 | true | 2007-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:00 | John |
12:00:00 | Dave |
13:00:00 | 莎莉 |
12:00:00 | Ben |
12:00:00 | 达纳 |
13:00:00 | Mike |
地点
where
子句用于仅返回与指定条件匹配的行。
简单的比较运算符为 <=, <, >, >=, =,
!=, <>
。两个比较运算符 != <>
表示不相等。字符串按字典值进行比较。请注意,等式由 =
表示,而不是在大多数计算机语言中用 ==
表示。
与 null
进行比较的操作是使用 is null
或 is not null
完成的。
您可以使用逻辑运算符 and
、or
和 not
将多个条件组合起来。圆括号可用于定义明确的优先级。
where 子句还支持一些更复杂的字符串比较运算符。
这些运算符将两个字符串作为参数;任何非字符串参数(例如日期或数字)在比较之前都将转换为字符串。字符串匹配区分大小写(您可以使用 upper()
或 lower()
标量函数来解决此问题)。
contains
- 子字符串匹配。如果 part 位于 whole 中的任何位置,则 wholecontains
part 为 true。示例:where name contains 'John'
与“John”“John Adams”“Long John Silver”匹配,但与“john adams”不匹配。starts with
- 前缀匹配。如果 prefix 位于 value 的开头,则 valuestarts 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) 正则表达式匹配。haystackmatches
如果 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 等。
将 pivot
与 group 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
子句中指定的列不能出现在 select
、group by
或 order 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 属性中返回。
模式语法:
number
、date
、timeofday
、datetime
- 由 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(用于找出某一列中的最大值)和 +(将两列的值相加到同一行中)。
有些函数可以出现在任何子句中;有些函数可以出现在子句的子集中。记录如下。
示例:
根据此表... | 如果我们应用此查询... | 我们得到了这个结果 | ||||||||||||||||||||||||
|
select upper(name), year(startDate) |
|
以下数据操作函数由 Google Visualization API 查询语言定义:
聚合函数
系统会向聚合函数传递单个列标识符,并对每个组中的所有值执行操作(组由 group by
或 pivot
子句指定,如果未使用这些子句,则所有行指定)。
示例:
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.
聚合函数可用在 select
、order by
、label
和 format
子句中。它们不能 出现在 where
、group by
、pivot
、limit
、offset
或 options
子句中。
以下是支持的聚合函数:
名称 | 说明 | 支持的列类型 | 返回值类型 |
---|---|---|---|
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))
标量函数可用于以下任何子句:select
、where
、group by
、pivot
、order by
、label,
和
format
。
名称 | |
---|---|
year() |
根据日期或日期时间值返回年份值。例如: 参数:一个类型为
date 或 datetime 的参数返回值类型:
number |
month() |
从日期或日期时间值返回从零开始的月份值。例如: 参数:一个类型为
date 或 datetime 的参数返回值类型:
number |
day() |
根据 参数:一个类型为
date 或 datetime 的参数返回值类型:
number |
hour() |
从日期时间或 参数:一个类型为
datetime 或 timeofday 的参数返回值类型:
number |
minute() |
从 参数:一个类型为
datetime 或 timeofday 的参数返回值类型:
number |
second() |
返回 参数:一个类型为
datetime 或 timeofday 的参数返回值类型:
number |
millisecond() |
返回 参数:一个类型为
datetime 或 timeofday 的参数返回值类型:
number |
quarter() |
返回 参数:一个类型为
date 或 datetime 的参数返回值类型:
number |
dayOfWeek() |
从 参数:一个类型为
date 或 datetime 的参数返回值类型:
number |
now() |
返回表示当前 参数:无
返回值类型:
datetime |
dateDiff() |
返回两个 参数:
date 或 datetime 类型的两个参数(可以分别是其中一个)返回值类型:
number |
toDate() |
将指定值转换为
参数:一个类型为
date 、datetime 或 number 的参数返回值类型:
date |
upper() |
返回指定的 参数:一个类型为
string 的参数返回值类型:
string |
lower() |
返回指定的 参数:一个类型为
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
- 布尔值字面量为
true
或false
。 -
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