Referência da linguagem de consulta (versão 0.7)

A linguagem de consulta da API Google preview permite realizar várias manipulações de dados com a consulta para a fonte de dados.

Sumário

Introdução

Normalmente, as visualizações esperam dados de alguma forma específica. Por exemplo, um gráfico de pizza pode esperar dados como duas colunas: um rótulo de texto e um valor numérico. Os dados na fonte podem não corresponder exatamente a essa estrutura. Por exemplo, a fonte de dados pode ter mais de duas colunas ou a ordem das colunas pode não corresponder à ordem esperada pelo gráfico de pizza.

A linguagem de consulta permite enviar solicitações de manipulação e formatação de fontes à fonte de dados e garantir que a estrutura de dados e o conteúdo retornados correspondam à estrutura esperada.

A sintaxe da linguagem de consulta é semelhante à do SQL. Os desenvolvedores familiarizados com SQL precisam aprender e usar rapidamente essa linguagem de consulta. Há muitos tutoriais de SQL disponíveis na Web. Há algumas diferenças entre essa linguagem de consulta e o SQL, descritas na seção Sintaxe.

Observe que as fontes de dados não precisam implementar a linguagem de consulta ou, caso precisem, implementar todos os recursos da linguagem. A menos que você tenha motivos para acreditar, não dependa de uma fonte de dados para implementar todos os recursos dessa linguagem.

Como usar a linguagem de consulta

É possível anexar uma string de consulta a uma solicitação de fonte de dados de duas maneiras: definindo a string de consulta de dentro do código JavaScript ou definindo a string de consulta como um parâmetro no URL da fonte de dados. Se a solicitação não incluir uma string de consulta, o comportamento padrão de uma fonte de dados será retornar todas as linhas e colunas usando a ordem e a formatação padrão de linha/coluna. Para alterar isso, inclua uma string de consulta na sua solicitação para uma fonte de dados.

Como definir a consulta do JavaScript

Para definir a string de consulta no código JavaScript, chame o método setQuery da classe google.visualization.Query.

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

Como configurar a consulta no URL da fonte de dados

A string de consulta pode ser adicionada ao URL da fonte de dados usando o parâmetro tq. Ao definir a consulta no parâmetro de URL em vez de no JavaScript, você pode usar facilmente as visualizações escritas por outros desenvolvedores e ainda poder personalizar a consulta.

A string de consulta precisa ser devidamente codificada como um parâmetro de URL. Você pode codificar um URL usando a função encodeURIComponent de JavaScript ou manualmente usando a ferramenta de codificação no final desta seção.

Exemplo:

Considere a seguinte string de consulta para uma planilha do Google. Os IDs das colunas nas planilhas são sempre letras. O texto do título da coluna exibido na planilha publicada são rótulos, não IDs. Use o ID, não o rótulo, na string de consulta.

select A, sum(B) group by A

Quando codificada, esta consulta se torna:

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

Suponha que este seja o URL da sua planilha:

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

Adicione /gviz/tq?tq=YOUR_QUERY_STRING ao URL da planilha para receber a string de consulta final:

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

Use a ferramenta abaixo para codificar ou decodificar uma string de consulta:

Observação: o acesso aos dados de uma planilha particular requer a transmissão de credenciais de autorização explícitas usando o OAuth. Consulte a seção Planilhas Google: autorização para ver mais detalhes.

Sintaxe de idiomas

Visão geral

A sintaxe da linguagem de consulta da API Google Overview foi projetada para ser semelhante à sintaxe SQL. No entanto, ele é um subconjunto do SQL e tem alguns recursos que você precisará conhecer. Talvez você não tenha muita dificuldade para aprender sobre o SQL.

Tabelas de dados

Neste documento, usamos o termo tabela de dados para nos referir ao conjunto de resultados de uma consulta. Uma tabela de dados é composta por linhas e colunas. Cada coluna em uma tabela de dados tem as seguintes propriedades:

  • Identificador (ou ID da coluna). Usado para referenciar colunas na consulta. Nunca tente referenciar uma coluna por rótulo em uma consulta, apenas por identificador. Dica:não use IDs que incluam espaços. Eles são difíceis de gerenciar e podem causar erros pequenos, mas difíceis de encontrar, na programação. Além disso, um ID que inclua espaços precisa ser colocado entre aspas duplas.
  • Rótulo. Uma string que normalmente é exibida aos usuários finais. Por exemplo, como uma legenda em um gráfico de pizza ou um cabeçalho de coluna em uma tabela.
  • Tipo de dados. Os tipos de dados com suporte são string, number, boolean, date, datetime e timeofday. Todos os valores de uma coluna terão um tipo de dados que corresponde ao tipo de coluna ou um valor null. Esses tipos são semelhantes, mas não idênticos, aos tipos JavaScript. Eles estão descritos na seção Literais desta página.
  • Padrão de formatação. A fonte de dados pode definir padrões de formatação para algumas ou todas as colunas. É possível modificar esse padrão incluindo uma cláusula de formato.

Tabela usada em todos os exemplos:

Nesta seção, todos os exemplos de consultas se referem à tabela a seguir. Os cabeçalhos das colunas são os identificadores.

nome
string
decl.
string
Hora do almoço
timeofday
salário
number
Data de contratação
date
idade
number
isnior
boolean
horário de início sênior
datetime
JohnEng12:00:00
1000
2005-03-1935verdadeiro2007-12-02 15:56:00
DaveEng12:00:00
500
2006-04-1927falsenull
SandraEng13:00:00
600
2005-10-1030falsenull
BenVendas12:00:00
400
2002-10-1032verdadeiro2005-03-09 12:30:00
DanaVendas12:00:00
350
2004-09-0825falsenull
MichelMarketing13:00:00
800
2005-01-1024verdadeiro2007-12-30 14:40:00

Cláusulas linguísticas

A sintaxe da linguagem de consulta é composta das seguintes cláusulas. Cada cláusula começa com uma ou duas palavras-chave. Todas as cláusulas são opcionais. As cláusulas são separadas por espaços. A ordem das cláusulas precisa ser a seguinte:

Cláusula Uso
select Seleciona quais colunas serão retornadas e em que ordem. Se omitido, todas as colunas da tabela serão retornadas na ordem padrão.
where Retorna apenas as linhas que correspondem a uma condição. Se omitido, todas as linhas são retornadas.
group by Agrega valores em linhas.
pivot Transforma valores distintos em colunas em novas colunas.
order by Classifica linhas por valores em colunas.
limit Limita o número de linhas retornadas.
offset Ignora um determinado número de primeiras linhas.
label Define os rótulos das colunas.
format Formata os valores em determinadas colunas usando determinados padrões de formatação.
options Define opções adicionais.
from A cláusula from foi eliminada da linguagem.

 

Selecionar

A cláusula select é usada para especificar as colunas a serem retornadas e a ordem delas. Se essa cláusula não for especificada ou se select * for usado, todas as colunas da tabela de fonte de dados serão retornadas, na ordem original. As colunas são referenciadas pelos identificadores (não pelos rótulos). Por exemplo, em uma planilha do Google, os identificadores de coluna são a letra da coluna com um ou dois caracteres (A, B, C, ...).

Os itens em uma cláusula select podem ser identificadores de coluna ou a saída de funções de agregação, funções escalares ou operadores.

Exemplos:

select *
select dept, salary
select max(salary)

No exemplo a seguir, as aspas duplas são usadas para referenciar IDs que contêm espaços (endereço de e-mail) ou palavras reservadas (data):

select `email address`, name, `date`

Execute esta consulta na tabela de exemplo:

select lunchTime, name

Retorna a seguinte resposta:

Hora do almoço nome
12:00:00John
12:00:00Dave
13:00:00Sandra
12:00:00Ben
12:00:00Dana
13:00:00Michel

Onde

A cláusula where é usada para retornar apenas linhas que correspondam a uma condição especificada.

Os operadores de comparação simples são <=, <, >, >=, =, !=, <>. Os dois operadores de comparação != <> significam diferente. As strings são comparadas por valor lexicográfico. A igualdade é indicada por =, não ==, como na maioria dos idiomas computacionais. A comparação com null é feita usando is null ou is not null.

É possível mesclar várias condições usando os operadores lógicos and, or e not. Parênteses podem ser usados para definir uma precedência explícita.

A cláusula "where" também aceita alguns operadores de comparação de strings mais complexos. Esses operadores usam duas strings como argumentos. Qualquer argumento que não seja string (por exemplo, datas ou números) será convertido em strings antes da comparação. A correspondência de strings diferencia maiúsculas de minúsculas (é possível usar upper() ou lower() funções escalares para solucionar esse problema).

  • contains: uma correspondência de substring. parte contains parte é verdadeira se part estiver em qualquer lugar dentro de todo. Exemplo: where name contains 'John' corresponde a "John", "John Adams", "Long John Silver", mas não a "John adams".
  • starts with: uma correspondência de prefixo. value starts with prefix é verdadeiro se prefix estiver no início de value. Exemplos: where dept starts with 'engineering' corresponde a "engenharia" e "gerentes de engenharia". where dept starts with 'e' corresponde a "engenharia", "eng" e "e".
  • ends with: uma correspondência de sufixo. valor ends with sufixo é verdadeiro se sufixo estiver no final de valor. Exemplo: where role ends with 'y' corresponde a "cowboy", "boy" e "y".
  • matches: uma correspondência de expressão regular (preg, em inglês). haystack matches needle será verdadeiro se a expressão regular em needle corresponder a haystack. Exemplos: where country matches '.*ia' corresponde à Índia e à Nigéria, mas não a Indiana. Esta não é uma pesquisa global, portanto, where country matches 'an' não corresponderá a "Canadá".
  • like: uma pesquisa de texto compatível com dois caracteres curinga: %, que corresponde a zero ou mais caracteres de qualquer tipo, e _ (sublinhado), que corresponde a qualquer caractere. Isso é semelhante ao operador SQL Like. Exemplo: where name like fre% corresponde a "fre", "fred" e "freddy".

Exemplos:

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

Execute esta consulta na tabela de exemplo:

select name where salary > 700

Retorna a seguinte resposta:

nome
John
Michel

Agrupar por

A cláusula group by é usada para agregar valores em todas as linhas. Uma única linha é criada para cada combinação distinta de valores na cláusula group-by. Os dados são classificados automaticamente pelas colunas de agrupamento, a menos que especificado de outra forma por uma cláusula order by.

Observação: se você usar uma cláusula group by, cada coluna listada na cláusula select precisará estar listada na cláusula group by ou ser encapsulada por uma função de agregação.

Exemplos:

select dept, max(salary) group by dept

Execute esta consulta na tabela de exemplo:

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

Retorna a seguinte resposta:

Hora do almoço Salário médio contar idade
12:00:00 425 2
13:00:00 600 1
12:00:00 700 2
13:00:00 800 1

Dinâmica

A cláusula pivot é usada para transformar valores distintos em colunas em novas colunas. Por exemplo, uma tabela dinâmica por uma coluna "year" produziria uma tabela com uma coluna para cada ano distinto que aparece na tabela original. Isso pode ser útil se, por exemplo, uma visualização do gráfico de linhas desenhar cada coluna como uma linha separada. Se você quiser traçar uma linha separada para cada ano, e "ano" for uma das colunas da tabela original, uma boa opção seria usar uma operação dinâmica para fazer a transformação de dados necessária.

Observação: se você usar uma cláusula pivot, todas as colunas listadas na cláusula select precisarão ser listadas na cláusula group by ou ser incluídas por uma função de agregação

Como várias linhas podem conter os mesmos valores para as colunas dinâmicas, a tabela dinâmica agrega agregação. Observe que, ao usar pivot sem group by, a tabela de resultados conterá exatamente uma linha. Por exemplo, execute a seguinte consulta na tabela de exemplo:

select sum(salary) pivot dept

Retorna a seguinte resposta:

Salário do engenharia salário de marketing Soma das vendas
2.100 800 750

Isso acontece porque 2.100 é a soma dos salários do departamento de engenharia, 800 do departamento de marketing etc.

Usar pivot com group by pode ser ainda mais útil, porque cria uma tabela em que cada célula contém o resultado da agregação da linha e da coluna em questão. Por exemplo, execute a consulta a seguir na tabela de exemplo:

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

Retorna a seguinte resposta:

dept 12:00:00 soma-salário 13:00:00 soma-salário
Eng 1.500 600
Marketing null 800
Vendas 750 null

Também é possível "inverter" essa tabela, alternando entre colunas e linhas, alternando entre as colunas pivot e group by. Execute esta consulta na tabela de exemplo:

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

Retorna a seguinte resposta:

Hora do almoço Salário do engenharia salário de marketing Soma das vendas
12:00:00 1.500 null 750
13:00:00 600 800 null

Também é possível usar mais de uma coluna na cláusula pivot. Nesse caso, as colunas da tabela de resposta são compostas por todas as combinações únicas de valores nas colunas da tabela original. Por exemplo, execute a seguinte consulta na tabela de exemplo:

select sum(salary)
  pivot dept, lunchTime

Retorna a seguinte resposta:

Engenharia,12:00:00 soma-salário Eng,13:00:00 soma-salário Marketing,13:00:00 soma-salário Vendas,12:00:00 soma-salário
1.500 600 800 750

Somente as combinações que aparecem na tabela original recebem colunas na tabela de resposta. Por isso, não há uma coluna para "Marketing", 12:00:00 ou para "Vendas", 13:00:00.

Também é possível usar mais de uma agregação. Por exemplo, execute a seguinte consulta na tabela de exemplo:

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

Retorna a seguinte resposta:

Salário do engenharia salário de marketing Soma das vendas Máximo de tempo de engenharia Tempo máximo de marketing Tempo máximo de vendas
2.100 800 750 13:00:00 13:00:00 12:00:00

É possível combinar várias agregações na cláusula select, várias colunas na cláusula group by e várias colunas na pivot. Internamente, a agregação é realizada pela concatenação das colunas no grupo por e por cláusulas dinâmicas.

As colunas especificadas na cláusula pivot podem não aparecer nas cláusulas select, group by ou order by. Quando pivot é usado, a cláusula order by não pode conter nenhuma coluna de agregação. Isso acontece porque muitas colunas são geradas na tabela de resultados para cada agregação especificada na cláusula select. No entanto, é possível formatar colunas de agregação quando pivot for usado. O resultado desse formato é que todas as colunas novas relevantes para a agregação específica, que são geradas pela operação dinâmica, são formatadas pelo padrão especificado. No exemplo acima, adicionar format sum(salary) "some_format_string" afetará as seguintes colunas: "Som-salary", "Sum sum" e "sal de vendas".

É possível rotular colunas de agregação. Se nenhum rótulo for especificado na cláusula label, o rótulo de uma coluna produzida como resultado da rotação será composto pela lista de valores nas colunas dinâmicas, pelo tipo de agregação (mín., máx., soma...) e pelo rótulo da coluna agregada. Por exemplo, "Eng,12:00:00 sum". Se apenas uma agregação for especificada na cláusula select, a parte de agregação será removida do rótulo e somente a lista de valores nas colunas dinâmicas será mantida. Por exemplo, "Eng, 12:00:00". Quando uma cláusula label especifica um rótulo para uma coluna de agregação, o rótulo solicitado é anexado à lista de valores, tanto quando há apenas uma agregação na cláusula select quanto quando há mais de uma. Por exemplo, label sum(salary) "sumsal" resultará nos rótulos de colunas "Eng, 12:00:00 sumsal", "Eng,13:00:00 sumsal" etc.

Ordenar por

A cláusula order by é usada para classificar as linhas pelos valores em colunas especificadas.

Os itens em uma cláusula order by podem ser identificadores de coluna ou a saída de funções de agregação, funções escalares ou operadores.

Exemplos:

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

Limite

A cláusula limit é usada para limitar o número de linhas retornadas.

Exemplo:

limit 100

Deslocamento

A cláusula offset é usada para pular um determinado número de primeiras linhas. Se uma cláusula limit for usada, offset será aplicado primeiro. Por exemplo, limit 15 offset 30 retornará as linhas 31 a 45.

Exemplos:

offset 10
limit 30 offset 210

Rótulo

A cláusula label é usada para definir o rótulo de uma ou mais colunas. Não é possível usar um valor de rótulo no lugar de um ID em uma consulta.

Os itens em uma cláusula label podem ser identificadores de coluna ou a saída de funções de agregação, funções escalares ou operadores.

Sintaxe:

label column_id label_string [,column_id label_string]
column_id
O identificador da coluna que está recebendo o rótulo.
label_string
O rótulo a ser atribuído a essa coluna. Muitas visualizações usam o rótulo da coluna como texto a ser exibido para o usuário final, como um rótulo de legenda em um gráfico de pizza. Os rótulos são literais de string e seguem essas regras de sintaxe.

Exemplo:

O exemplo a seguir define o rótulo da coluna dept como "Departamento", o rótulo da coluna de nome como "Nome do funcionário" e o rótulo da coluna de local como "Local do funcionário".

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

Formato

A cláusula format é usada para especificar um valor formatado para células em uma ou mais colunas. Os dados retornados precisam incluir um valor real e um valor formatado para cada célula em uma coluna formatada. Muitas visualizações usam o valor não formatado para cálculos, mas o valor formatado para exibição. Os padrões especificados nesta cláusula geralmente são retornados na propriedade pattern das colunas correspondentes.

Sintaxe do padrão:

number, date, timeofday, datetime
Os padrões de data e número definidos pela ICU.
boolean
O padrão é um string no formato valor-se-verdadeiro:valor-se-falso.

Exemplo:

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

 

Opções

A cláusula options é usada para controlar outras opções para a execução da consulta. As possíveis palavras-chave que podem seguir a cláusula options são:

  • no_format Remove os valores formatados do resultado e deixa apenas os valores subjacentes. É possível usar quando a visualização específica não usa os valores formatados para reduzir o tamanho da resposta.
  • no_values Remove os valores subjacentes do resultado e deixa somente os valores formatados. Pode ser usado quando a visualização específica usa apenas os valores formatados para reduzir o tamanho da resposta.

Funções de manipulação de dados

Há vários tipos de operadores e funções que permitem manipular ou agregar dados em uma única coluna ou comparar ou combinar dados entre colunas. Exemplos incluem soma() (para adicionar todos os valores em uma coluna), max (para encontrar o maior valor em uma coluna) e + (para adicionar os valores de duas colunas na mesma linha).

Algumas funções podem aparecer em qualquer cláusula, enquanto outras podem aparecer em um subconjunto de cláusulas. Isso está documentado abaixo.

Exemplo:

Dada esta tabela... Se aplicarmos essa consulta... Recebemos esse resultado.
Nome Salário Tributo StartDate
Susana 1000 100 1/1/2009
Avital 2.000 200 21/01/2008
Moran 3.000 300 12/02/2008
select upper(name), year(startDate)
Nome ano(Data de início)
MÉDIO 2008
MORAN 2008
SHARON 2009

 

As funções de manipulação de dados a seguir são definidas pela linguagem de consulta da API Google preview:

 

Funções de agregação

As funções de agregação recebem um identificador de coluna única e realizam uma ação em todos os valores de cada grupo. Os grupos são especificados por cláusulas group by ou pivot ou em todas as linhas se essas cláusulas não forem usadas.

Exemplos:

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.

As funções de agregação podem ser usadas nas cláusulas select, order by, label e format. Elas não podem aparecer em cláusulas where, group by, pivot, limit, offset ou options.

Veja as funções de agregação compatíveis:

Nome Descrição Tipos de colunas compatíveis Tipo de retorno
avg() Retorna o valor médio de todos os valores na coluna para um grupo. number number
count() Retorna a contagem de elementos na coluna especificada para um grupo. As células nulas não são contadas. Qualquer tipo number
max() Retorna o valor máximo na coluna para um grupo. As datas são comparadas com versões anteriores, strings são comparadas em ordem alfabética, com diferenciação de maiúsculas e minúsculas. Qualquer tipo Mesmo tipo da coluna
min() Retorna o valor mínimo na coluna para um grupo. As datas são comparadas com números menores, os strings são comparados em ordem alfabética, com diferenciação de maiúsculas e minúsculas. Qualquer tipo Mesmo tipo da coluna
sum() Retorna a soma de todos os valores na coluna para um grupo. number number

Observação:as funções de agregação só podem usar um identificador de coluna como argumento:

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

Funções escalares

As funções escalares operam com zero ou mais parâmetros para produzir outro valor. As funções escalares podem ser passadas para qualquer expressão avaliada como o parâmetro do tipo apropriado. Observe que esses são os tipos definidos na seção Literais deste documento, que podem ser um pouco diferentes dos objetos JavaScript com nomes semelhantes.

Observe que o nome da coluna será alterado envolvendo-a com uma função escalar.

As funções escalares podem usar qualquer parâmetro que seja avaliado como um único valor:

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

As funções escalares podem ser usadas em qualquer uma das seguintes cláusulas: select, where, group by, pivot, order by, label, e format.

Nome
year()

Retorna o valor do ano de um valor de data ou data/hora. Por exemplo: year(date "2009-02-05") retorna 2009.

Parâmetros: um parâmetro do tipo date ou datetime
Tipo de retorno: number
month()

Retorna o valor do mês com base em zero de um valor de data ou data/hora. Por exemplo: month(date "2009-02-05") retorna 1. Observação: os meses são baseados em 0, portanto, a função retorna 0 para janeiro, 1 para fevereiro etc.

Parâmetros:um parâmetro do tipo date ou datetime
Tipo de retorno: number
day()

Retorna o dia do mês de um valor de date ou data e hora. Por exemplo: day(date "2009-02-05") retorna 5.

Parâmetros:um parâmetro do tipo date ou datetime
Tipo de retorno: number
hour()

Retorna o valor de hora de um valor de data/hora ou timeofday. Por exemplo: hour(timeofday "12:03:17") retorna 12.

Parâmetros:um parâmetro do tipo datetime ou timeofday
Tipo de retorno: number
minute()

Retorna o valor do minuto de um valor datetime ou timeofday. Por exemplo: minute(timeofday "12:03:17") retorna 3.

Parâmetros: um parâmetro do tipo datetime ou timeofday
Tipo de retorno: number
second()

Retorna o segundo valor de um valor datetime ou timeofday. Por exemplo: second(timeofday "12:03:17") retorna 17.

Parâmetros:um parâmetro do tipo datetime ou timeofday
Tipo de retorno: number
millisecond()

Retorna a parte de milissegundos de um valor datetime ou timeofday. Por exemplo: millisecond(timeofday "12:03:17.123") retorna 123.

Parâmetros:um parâmetro do tipo datetime ou timeofday
Tipo de retorno: number
quarter()

Retorna o trimestre de um valor de date ou datetime. Por exemplo: quarter(date "2009-02-05") retorna 1. Os trimestres são baseados em 1, portanto, a função retorna 1 para o primeiro trimestre, 2 para o segundo etc.

Parâmetros: um parâmetro do tipo date ou datetime
Tipo de retorno: number
dayOfWeek()

Retorna o dia da semana de um valor de date ou datetime. Por exemplo: dayOfWeek(date "2009-02-26") retorna 5. Os dias são baseados em 1, para que a função retorne 1 para domingo, 2 para segunda-feira etc.

Parâmetros:um parâmetro do tipo date ou datetime
Tipo de retorno: number
now()

Retorna um valor de data e hora que representa o datetime atual no fuso horário GMT.

Parâmetros: nenhum
Tipo de retorno: datetime
dateDiff()

Retorna a diferença em dias entre dois valores date ou datetime. Observação: somente as partes date dos valores são usadas no cálculo e, assim, a função sempre retorna um valor inteiro. Por exemplo: dateDiff(date "2008-03-13", date "2008-02-12") retorna 29, dateDiff(date "2009-02-13", date "2009-03-13") retorna -29. Os valores de tempo são truncados antes da comparação.

Parâmetros: dois parâmetros de tipo date ou datetime (podem ser um de cada)
Tipo de retorno: number
toDate()

Transforma o valor informado em um valor date.

  • Dado um date, ele retorna o mesmo valor.
  • Dado um datetime, ele retorna a parte date. Por exemplo: toDate(dateTime "2009-01-01 12:00:00") retorna "2009-01-01".
  • Dado um number N, ele retorna um date N milissegundos após o período. A Época é definida como 1o de janeiro de 1970, 00:00:00 GMT. Por exemplo: toDate(1234567890000) retorna "2009-02-13".
Parâmetros: um parâmetro do tipo date, datetime ou number
Tipo de retorno: date
upper()

Retorna o string especificado em letras maiúsculas. Por exemplo: upper("foo") retorna "FOO".

Parâmetros: um parâmetro do tipo string
Tipo de retorno: string
lower()

Retorna o string especificado em letras minúsculas. Por exemplo: lower("Bar") retorna "bar".

Parâmetros: um parâmetro do tipo string
Tipo de retorno: string

Operadores aritméticos

É possível usar operadores aritméticos para realizar operações matemáticas em qualquer item que avalie um número único, ou seja, a saída de funções agregadas, operadores ou constantes apropriadas.

Exemplos:

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

Os seguintes operadores são definidos:

Nome Descrição Parâmetros Tipo de retorno
+ Retorna a soma de dois valores number. Dois numbers number
- Retorna a diferença entre dois valores number. Dois numbers number
* Retorna o produto de duas numbers. Dois numbers number
/ Retorna o quociente de dois numbers. Divisão por zero retorna nulo. Dois numbers number

Elementos de linguagem

Literais

Os literais são valores usados para comparações ou atribuições. Os literais podem ser strings, números, valores booleanos ou vários tipos de data/hora. Veja alguns exemplos de literais usados na sintaxe de consulta:

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

Veja os formatos para cada tipo de literal:

string
Um literal string precisa ser colocado entre aspas simples ou duplas. Exemplos:"fourteen" 'hello world' "It's raining".
number
Os literais numéricos são especificados em notação decimal. Exemplos: 3  3.0  3.14  -71  -7.2  .6
boolean
Os literais booleanos são true ou false.
date
Use a palavra-chave date seguida por um literal string no formato yyyy-MM-dd. Exemplo: date "2008-03-18".
timeofday
Use a palavra-chave timeofday seguida por um literal de string no formato HH:mm:ss[.SSS] Exemplo: timeofday "12:30:45".
datetime
Data e hora, usando a palavra-chave datetime ou timestamp seguida por um literal string no formato yyyy-MM-dd HH:mm:ss[.sss]. Exemplo: datetime '2008-03-18 12:30:34.123'

Identificadores

Identificadores (ou IDs) são strings de texto que identificam colunas.

Importante:se o identificador

  • Tem espaços,
  • é uma palavra reservada;
  • Contém qualquer coisa, exceto caracteres alfanuméricos ou sublinhados ([a-zA-Z0-9_]),
  • Começa com um dígito

ela precisa ser colocada entre aspas duplas (não entre aspas simples).

Caso contrário,o identificador não precisa estar entre aspas. Nem todas as palavras-chave definidas pela sintaxe são palavras reservadas. Por exemplo, você pode usar "max" como um identificador sem precisar colocar as aspas novamente.

Exemplos:col1   employee_table   `start date`   `7 days traffic`   `select`.

Recomendamos não escolher um identificador que exija aspas duplas, porque pode ser fácil esquecer de usar essas aspas ou acidentalmente usar "aspas simples" em vez de "acentos graves". Esses são erros comuns e geralmente são difíceis de depurar.

Diferenciação entre maiúsculas e minúsculas

Identificadores e literais de string diferenciam maiúsculas de minúsculas. Todos os outros elementos de linguagem não diferenciam maiúsculas de minúsculas.

Palavras reservadas

As seguintes palavras reservadas precisam estar entre aspas se usadas como identificadores:

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