Sintaxe SQL para a qual há suporte

SELECT

A instrução SELECT é usada para consultar o banco de dados. O resultado de uma instrução SELECT é zero ou mais linhas de dados em que cada uma tem um número de colunas fixo. O número de colunas no resultado é especificado pelo nome da coluna result ou pela lista de expressão entre as palavras-chave SELECT e as opcionais FROM.

sql-statement   ::=  SELECT [ALL | DISTINCT] result 
                     [FROM table-list] 
                     [WHERE expr] 
                     [GROUP BY expr-list] 
                     [HAVING expr] 
                     [compound-op select-statement]* 
                     [ORDER BY sort-expr-list] 
                     [LIMIT integer [( OFFSET | , ) integer]] 
result          ::=  result-column [, result-column]* 
result-column   ::=  * | table-name . * | expr [[AS] string] 
table-list      ::=  table [ join-op table join-args ]* 
table           ::=  table-name [AS alias] | 
                     ( select ) [AS alias] 
join-op         ::=  , | [NATURAL] [LEFT | RIGHT | FULL] [OUTER | INNER | CROSS] JOIN 
join-args       ::=  [ON expr] [USING ( id-list )] 
compound-op     ::=  UNION | UNION ALL | INTERSECT | EXCEPT 
sort-expr-list  ::=  expr [sort-order] [, expr [sort-order]]* 
sort-order      ::=  [COLLATE collation-name] [ASC | DESC] 
collation-name  ::=  BINARY | NOCASE

Qualquer expressão arbitrária pode ser usada como resultado. Caso uma expressão de resultado seja *, todas as colunas de todas as tabelas serão substituídas por essa expressão. Caso a expressão seja o nome de uma tabela seguido de .*, o resultado será igual a todas as colunas nessa única tabela.

A palavra-chave DISTINCT faz com que um subconjunto de linhas de resultado seja retornado, no qual cada linha de resultado é diferente. Valores NULL não são tratados como distintos entre si. O comportamento padrão é de que todas as linhas de resultado sejam retornadas, as quais podem ser explicitadas com a palavra-chave ALL.

A consulta é executada em uma ou mais tabelas especificadas após a palavra-chave FROM. Caso vários nomes de tabela estejam separados por vírgulas, a consulta usa a junção cruzada das várias tabelas. A sintaxe JOIN também pode ser usada para especificar como as tabelas são unidas. O único tipo de junção externa para o qual há suporte é LEFT OUTER JOIN. A expressão da cláusula ON em join-args deve ser resolvida como um valor booliano. Uma subconsulta entre parênteses pode ser usada como uma tabela na cláusula FROM. Toda a cláusula FROM pode ser omitida, no caso de o resultado ser uma única linha com os valores da lista de expressões result.

A cláusula WHERE é usada para limitar o número de linhas recuperadas pela consulta. As expressões de cláusula WHERE devem ser resolvidas como um valor booliano. Como a filtragem de cláusula WHERE é realizada antes de qualquer agrupamento, as expressões de cláusula WHERE talvez não incluam funções agregadas.

A cláusula GROUP BY faz com que uma ou mais linhas do resultado sejam combinadas com uma única linha de saída. Uma cláusula GROUP BY é especialmente útil quando o resultado contém funções agregadas. As expressões na cláusula GROUP BY não precisam ser expressões exibidas na lista de expressões SELECT.

A cláusula HAVING é semelhante a WHERE ao limitar as linhas retornadas pela instrução. No entanto, a cláusula HAVING se aplica após a ocorrência de qualquer agrupamento especificado por uma cláusula GROUP BY. Consequentemente, a expressão HAVING pode se referir a valores que incluem funções agregadas. Uma expressão de cláusula HAVING não precisa ser exibida na lista SELECT. Assim como uma expressão WHERE, uma expressão HAVING deve ser resolvida como um valor booliano.

A cláusula ORDER BY faz com que as linhas de saída sejam classificadas. O argumento sort-expr-list da cláusula ORDER BY é uma lista de expressões usadas como chave da classificação. As expressões não precisam fazer parte do resultado de uma simples SELECT, mas em uma SELECT composta (uma SELECT usando um dos operadores compound-op), cada expressão de classificação deve corresponder exatamente a uma das colunas de resultado. Cada expressão de classificação pode ser seguida de uma cláusula sort-order que consiste na palavra-chave COLLATE e no nome de uma função de intercalação usada para classificar o texto e/ou a palavra-chave ASC ou DESC para especificar a ordem de classificação (crescente ou decrescente). A sort-order pode ser omitida e o padrão (ordem crescente) é usado. Para obter uma definição da cláusula COLLATE e das funções de intercalação, consulte COLLATE. A sort-order pode ser omitida e o padrão (ordem crescente) é usado. Para obter uma definição da cláusula COLLATE e das funções de intercalação, consulte COLLATE.

A cláusula LIMIT coloca um limite superior sobre o número de linhas retornadas no resultado. Uma LIMIT negativa não indica nenhum limite superior. A OFFSET opcional que segue LIMIT especifica quantas linhas ignorar no início do conjunto de resultados. Em uma consulta SELECT composta, a cláusula LIMIT talvez só seja exibida após a instrução SELECT final, e o limite é aplicado a toda a consulta. Observe que, caso a palavra-chave OFFSET seja usada na cláusula LIMIT, o limite é o primeiro inteiro e a distância é o segundo inteiro. Caso seja usada uma vírgula no lugar da palavra-chave OFFSET, a distância é o primeiro número e o limite, o segundo. Essa contradição aparente é intencional — ela maximiza a compatibilidade com sistemas de banco de dados SQL herdados.

Uma SELECT composta é formada por duas ou mais instruções SELECT simples conectadas por um dos operadores UNION, UNION ALL, INTERSECT ou EXCEPT. Em uma SELECT composta, todas as instruções SELECT constituintes devem especificar o mesmo número de colunas de resultado. Só pode haver uma única cláusula ORDER BY após a instrução SELECT final (e antes da única cláusula LIMIT, caso haja uma especificada). Os operadores UNION e UNION ALL integram os resultados das instruções SELECT anterior e posterior em uma única tabela. A diferença é que na UNION, todas as linhas de resultado são distintas, mas em UNION ALL talvez haja cópias. O operador INTERSECT usa a intersecção dos resultados das instruções SELECT anterior e posterior. EXCEPT usa o resultado da SELECT anterior após a remoção dos resultados da SELECT seguinte. Quando três ou mais instruções SELECT estão conectadas a uma composta, elas são agrupadas da primeira à última.

Para obter uma definição das expressões permitidas, consulte Expressões

A partir do AIR 2.5, o operador SQL CAST conta com suporte durante a leitura para converter dados BLOB em objetos ByteArray do ActionScript. Por exemplo, o código a seguir lê dados brutos que não estão armazenados no formato AMF e os armazena em um objeto ByteArray:

stmt.text = "SELECT CAST(data AS ByteArray) AS data FROM pictures;"; 
stmt.execute(); 
var result:SQLResult = stmt.getResult(); 
var bytes:ByteArray = result.data[0].data;

INSERT

sql-statement  ::=  INSERT [OR conflict-algorithm] INTO [database-name.] table-name [(column-list)] VALUES (value-list) | 
                    INSERT [OR conflict-algorithm] INTO [database-name.] table-name [(column-list)] select-statement 
                    REPLACE INTO [database-name.] table-name [(column-list)] VALUES (value-list) | 
                    REPLACE INTO [database-name.] table-name [(column-list)] select-statement

A primeira forma (com a palavra-chave VALUES) cria uma única linha nova em uma tabela existente. Caso nenhuma column-list seja especificada, o número de valores deve ser igual ao número de colunas na tabela. Caso uma column-list seja especificada, o número de valores deve corresponder ao número de colunas especificadas. As colunas da tabela que não são exibidas na lista são preenchidas com o valor definido padrão quando a tabela é criada, ou com NULL caso nenhum valor padrão seja definido.

A segunda forma da instrução INSERT usa os dados de uma instrução SELECT. O número de colunas no resultado da SELECT deve corresponder exatamente ao número de colunas na tabela caso column-list não esteja especificada, ou deve corresponder ao número de colunas nomeadas na column-list. É criada uma nova entrada na tabela para todas as linhas do resultado de SELECT. A SELECT pode ser simples ou composta. Para obter uma definição das instruções SELECT permitidas, consulte SELECT.

A conflict-algorithm opcional permite a especificação de um algoritmo para resolução de conflitos de restrição a ser usado durante esse comando único. Para obter uma explicação e definição do conflito de algoritmos, consulte Instruções especiais e cláusulas .

As duas formas REPLACE INTO da instrução são equivalentes ao uso da forma INSERT [OR conflict-algorithm] padrão com o algoritmo de conflito REPLACE (ou seja, a forma INSERT OR REPLACE...).

As duas formas REPLACE INTO da instrução são equivalentes ao uso da forma INSERT [OR conflict-algorithm] padrão com o algoritmo de conflito REPLACE (ou seja, a forma INSERT OR REPLACE...).

UPDATE

O comando update altera os registros existentes em uma tabela.

sql-statement  ::=  UPDATE [database-name.] table-name SET column1=value1, column2=value2,... [WHERE expr]

O comando consiste na palavra-chave UPDATE seguida do nome do tabela cujos registros você deseja atualizar. Depois da palavra-chave SET, forneça o nome da coluna e o valor para o qual a coluna deve ser alterada, como uma lista separada por vírgulas. A expressão da cláusula WHERE indica a linha ou linhas em que os registros são atualizados.

DELETE

sql-statement  ::=  DELETE FROM [database-name.] table-name [WHERE expr]

O comando consiste nas palavras-chave DELETE FROM seguidas do nome da tabela da qual os registros devem ser removidos.

Sem uma cláusula WHERE, todas as linhas da tabela são removidas. Caso uma cláusula WHERE seja fornecida, apenas essas linhas correspondentes à expressão são removidas. A expressão da cláusula WHERE deve ser resolvida como um valor booliano. Para obter uma definição das expressões permitidas, consulte Expressões

CREATE TABLE

sql-statement       ::=  CREATE [TEMP | TEMPORARY] TABLE [IF NOT EXISTS] [database-name.] table-name 
                         ( column-def [, column-def]* [, constraint]* ) 
sql-statement       ::=  CREATE [TEMP | TEMPORARY] TABLE [database-name.] table-name AS select-statement 
column-def          ::=  name [type] [[CONSTRAINT name] column-constraint]* 
type                ::=  typename | typename ( number ) | typename ( number , number ) 
column-constraint   ::=  NOT NULL [ conflict-clause ] | 
                         PRIMARY KEY [sort-order] [ conflict-clause ] [AUTOINCREMENT] | 
                         UNIQUE [conflict-clause] | 
                         CHECK ( expr ) | 
                         DEFAULT default-value | 
                         COLLATE collation-name 
constraint          ::=  PRIMARY KEY ( column-list ) [conflict-clause] | 
                         UNIQUE ( column-list ) [conflict-clause] | 
                         CHECK ( expr ) 
conflict-clause     ::=  ON CONFLICT conflict-algorithm 
conflict-algorithm  ::=  ROLLBACK | ABORT | FAIL | IGNORE | REPLACE 
default-value       ::=  NULL | string | number | CURRENT_TIME | CURRENT_DATE | CURRENT_TIMESTAMP 
sort-order          ::=  ASC | DESC 
collation-name      ::=  BINARY | NOCASE 
column-list         ::=  column-name [, column-name]*

Cada definição de coluna é o nome da coluna seguido do tipo de dados da coluna e, em seguida, de uma ou mais restrições de coluna opcionais. O tipo de dados da coluna restringe quais dados podem ser armazenados nessa coluna. Se for feita uma tentativa de armazenar um valor em uma coluna com um tipo de dados diferente, o tempo de execução converterá o valor no tipo apropriado, se possível, ou apresentará um erro. Consulte Suporte ao tipo de dados para obter detalhes.

A restrição de coluna NOT NULL indica que a coluna não pode conter valores NULL.

Uma restrição UNIQUE faz com que seja criado um índice na(s) coluna(s) especificada(s). Esse índice deve conter chaves exclusivas — duas linhas não podem conter valores duplicados ou combinações de valores para a(s) coluna(s) especificada(s). Uma instrução CREATE TABLE pode ter várias restrições UNIQUE, inclusive várias colunas com uma restrição UNIQUE na definição da coluna e/ou várias restrições UNIQUE no nível da tabela.

Uma restrição CHECK define uma expressão avaliada e que deve ser verdadeira para que os dados de uma linha sejam inseridos ou atualizados. A expressão CHECK deve ser resolvida como um valor booliano.

Uma cláusula COLLATE numa definição de coluna especifica qual função de colação de texto deverá ser usado ao comparar entradas de texto na coluna. Por padrão, a função de intercalação BINARY é usada. Para obter detalhes sobre a cláusula COLLATE e as funções de intercalação, consulte COLLATE.

A restrição DEFAULT especifica um valor padrão a ser usado com INSERT. O valor pode ser NULL, uma constante de string ou um número. O valor padrão também pode ser uma das palavras-chave especiais que não diferenciam maiúsculas de minúsculas CURRENT_TIME, CURRENT_DATE ou CURRENT_TIMESTAMP. Caso o valor seja NULL, uma constante de string, ou um número, ele é literalmente inserido na coluna sempre que uma instrução INSERT não especificar um valor da coluna. Caso o valor seja CURRENT_TIME, CURRENT_DATE ou CURRENT_TIMESTAMP, a data e/ou hora UTC atual é inserida na coluna. Em CURRENT_TIME, o formato é HH:MM:SS. Em CURRENT_DATE, o formato é YYYY-MM-DD. O formato de CURRENT_TIMESTAMP é YYYY-MM-DD HH:MM:SS.

Especificar uma PRIMARY KEY normalmente apenas cria um índice UNIQUE na(s) coluna(s) correspondente(s). No entanto, caso a restrição PRIMARY KEY esteja em uma única coluna cujo tipo de dados seja INTEGER (ou um de seus sinônimos, tais como int), essa coluna será usada pelo banco de dados como a chave primária real da tabela. Isso significa que a coluna só pode manter valores de inteiro exclusivos. (Observe que, em muitas implementações do SQLite, apenas o tipo de coluna INTEGER faz com que a coluna sirva como chave primária interna, mas, no Adobe AIR, os sinônimos de INTEGER, como int, também especificam esse comportamento).

Se uma tabela não tiver uma coluna INTEGER PRIMARY KEY, uma chave de inteiro será gerada automaticamente quando uma linha for inserida. A chave primária de uma linha pode ser sempre acessada usando um dos nomes especiais ROWID, OID ou _ROWID_. Esses nomes podem ser usados independentemente da declaração explícita de INTEGER PRIMARY KEY ou de um valor gerado internamente. Entretanto, caso a tabela tenha uma INTEGER PRIMARY KEY explícita, o nome da coluna nos dados de resultados é o nome real da coluna e não o nome especial.

Uma coluna INTEGER PRIMARY KEY também pode incluir a palavra-chave AUTOINCREMENT. Quando a palavra-chave AUTOINCREMENT for usada, o banco de dados gera automaticamente e insere uma chave inteira incrementada sequencialmente na coluna INTEGER PRIMARY KEY quando executa uma instrução INSERT que não especifica um valor explícito para a coluna.

Só pode haver uma restrição PRIMARY KEY em uma instrução CREATE TABLE. Ela pode fazer parte da definição de uma coluna ou de uma restrição PRIMARY KEY única no nível da tabela. Implicitamente, uma coluna de chave primária é NOT NULL.

A conflict-clause opcional que segue muitas restrições permite a especificação de um algoritmo para resolução de conflitos de restrição padrão alternativo para essa restrição. O padrão é ABORT. restrições diferentes dentro da mesma tabela podem ter algoritmos para resolução de conflitos padrão diferentes. Caso uma instrução INSERT ou UPDATE especifique um algoritmo para resolução de conflitos diferente, esse algoritmo é usado em lugar do especificado na instrução CREATE TABLE. Consulte a seção ON CONFLICT de Instruções especiais e cláusulas para obter informações adicionais.

restrições adicionais como, por exemplo, FOREIGN KEY não resultam em erro, mas o tempo de execução as ignora.

Caso ocorra palavra-chave TEMP ou TEMPORARY entre CREATE e TABLE, a tabela criada permanece visível apenas dentro da mesma conexão de banco de dados (ocorrência de SQLConnection). Ela é excluída automaticamente quando a conexão de banco de dados é fechada. Todos os índices criados em uma tabela temporária também são temporários. As tabelas e os índices temporários são armazenados em um arquivo separado distinto do arquivo de banco de dados principal.

Caso o prefixo opcional database-name seja especificado, a tabela é criada em um banco de dados nomeado (um banco de dados conectado à instância de SQLConnection pela chamada do método attach() com o nome do banco de dados especificado). É um erro especificar um prefixo database-name e a palavra-chave TEMP, a menos que o prefixo database-name seja temp. Caso nenhum nome de banco de dados seja especificado e a palavra-chave TEMP não esteja presente, a tabela é criada no banco de dados principal (o banco de dados conectado à instância de SQLConnection usando o método open() ou openAsync()).

não há nenhum limite arbitrário quanto ao número de colunas ou ao número de restrições em uma tabela. Também não existe nenhum limite arbitrário quanto à quantidade de dados em uma linha.

A forma CREATE TABLE AS define a tabela como o conjunto de resultados de uma consulta. Os nomes das colunas da tabela são os nomes das colunas no resultado.

Caso a cláusula opcional IF NOT EXISTS esteja presente e já haja outra tabela com o mesmo nome, o banco de dados ignora o comando CREATE TABLE.

Uma tabela pode ser removida usando a instrução DROP TABLE, e alterações limitadas podem ser feitas usando a instrução ALTER TABLE.

ALTER TABLE

O comando ALTER TABLE permite ao usuário renomear ou adicionar uma nova coluna a uma tabela existente. Não é possível remover uma coluna de uma tabela.

sql-statement ::= ALTER TABLE [database-name.] table-name alteration 
alteration    ::= RENAME TO new-table-name 
alteration    ::= ADD [COLUMN] column-def

A sintaxe RENAME TO é usada para renomear a tabela identificada por [database-name.] table-name para new-table-name. Esse comando não pode ser usado para mover uma tabela entre bancos de dados anexados, e sim apenas para renomear uma tabela dentro do mesmo banco de dados.

Caso a tabela que está sendo renomeada tenha disparadores ou índices, eles permanecem anexados à tabela depois que ela é renomeada. No entanto, caso haja alguma definição ou instrução de exibição executada por disparadores referente à tabela que está sendo renomeada, eles não serão modificados automaticamente para usar o novo nome da tabela. Caso uma tabela renomeada tenha exibições ou disparadores, você deve ignorar e recriar manualmente os disparadores ou as definições de exibição usando o novo nome da tabela.

A sintaxe ADD [COLUMN] é usada para adicionar uma nova coluna a uma tabela existente. A nova coluna sempre é acrescentada ao final da lista de colunas existentes. A cláusula column-def pode assumir qualquer uma das formas permitidas em uma instrução CREATE TABLE, com as seguintes restrições:

• A coluna talvez não tenha uma restrição PRIMARY KEY ou UNIQUE.

• A coluna talvez não tenha um valor padrão igual a CURRENT_TIME, CURRENT_DATE ou CURRENT_TIMESTAMP.

• Caso seja especificada uma restrição NOT NULL, a coluna deve ter um valor padrão diferente de NULL.

O momento da execução da instrução ALTER TABLE não afetado pela quantidade de dados na tabela.

DROP TABLE

sql-statement  ::=  DROP TABLE [IF EXISTS] [database-name.] table-name

Por padrão, a instrução DROP TABLE não reduz o tamanho do arquivo de banco de dados. O espaço livre no banco de dados é mantido e usado em operações INSERT subsequentes. Para remover o espaço livre no banco de dados, use o método SQLConnection.clean(). Caso o parâmetro autoClean esteja definido como true quando o banco de dados for criado inicialmente, o espaço é automaticamente liberado.

A cláusula IF EXISTS opcional suprime o erro que normalmente aconteceria se a tabela não existisse.

CREATE INDEX

O comando CREATE INDEX consiste nas palavras-chave CREATE INDEX seguidas do nome do novo índice, a palavra-chave ON, o nome de uma tabela criada anteriormente a ser indexada e uma lista entre parênteses dos nomes das colunas na tabela cujos valores são usados na chave de índice.

sql-statement  ::=  CREATE [UNIQUE] INDEX [IF NOT EXISTS] [database-name.] index-name 
                    ON table-name ( column-name [, column-name]* ) 
column-name    ::=  name [COLLATE collation-name] [ASC | DESC]

Cada nome de coluna pode ser seguido das palavras-chave ASC ou DESC para indicar a ordem de classificação, embora a designação da ordem de classificação seja ignorada pelo tempo de execução. A classificação é sempre feita na ordem crescente.

A cláusula COLLATE que segue cada nome de coluna define uma sequência de intercalação usada nos valores de texto da coluna. A sequência de intercalação padrão é a definida para a coluna na instrução CREATE TABLE. Caso nenhuma seja especificada, é usada a sequência de intercalação BINARY. Para obter uma definição da cláusula COLLATE e das funções de intercalação, consulte COLLATE.

Não há limites arbitrários quanto ao número de índices que podem ser anexados a uma única tabela. Também não existem limites para o número de colunas em um índice.

DROP INDEX

A instrução drop index remove um índice adicionado com a instrução CREATE INDEX. O índice especificado é removido completamente do arquivo de banco de dados. A única forma de recuperar o índice é digitar novamente o comando CREATE INDEX apropriado.

sql-statement ::= DROP INDEX [IF EXISTS] [database-name.] index-name

Por padrão, a instrução DROP INDEX não reduz o tamanho do arquivo de banco de dados. O espaço livre no banco de dados é mantido e usado em operações INSERT subsequentes. Para remover o espaço livre no banco de dados, use o método SQLConnection.clean(). Caso o parâmetro autoClean esteja definido como true quando o banco de dados for criado inicialmente, o espaço é automaticamente liberado.

CREATE VIEW

O comando CREATE VIEW atribui um nome a uma instrução SELECT predefinida. Esse novo nome pode ser usado em uma cláusula FROM de outra instrução SELECT em lugar do nome de uma tabela. As exibições costumam ser usadas para simplificar as consultas, integrando um conjunto complexo (e muito usado) de dados a uma estrutura que pode ser usada em outras operações.

sql-statement ::= CREATE [TEMP | TEMPORARY] VIEW [IF NOT EXISTS] [database-name.] view-name AS select-statement

Caso ocorra a palavra-chave TEMP ou TEMPORARY entre CREATE e VIEW, a exibição criada só permanece visível para a ocorrência de SQLConnection que abriu o banco de dados, sendo excluída automaticamente quando ele é fechado.

Caso seja especificada uma [database-name], a exibição é criada no banco de dados nomeado (um banco de dados conectado à instância de SQLConnection usando o método attach(), com o argumento name especificado). É um erro especificar uma [database-name] e a palavra-chave TEMP, a menos que [database-name] seja temp. Caso nenhum nome de banco de dados seja especificado e a palavra-chave TEMP não esteja presente, a exibição é criada no banco de dados principal (o banco de dados conectado à instância de SQLConnection usando o método open() ou openAsync()).

As exibições são somente leitura. Uma instrução DELETE, INSERT ou UPDATE não pode ser usada em uma exibição, a menos que haja pelo menos um disparador do tipo associado (INSTEAD OF DELETE, INSTEAD OF INSERT, INSTEAD OF UPDATE) definido. Para informações sobre a criação de um gatilho para uma visualização, consulte CRIAR GATILHO.

Uma exibição é removida de um banco de dados usando a instrução DROP VIEW.

DROP VIEW

A instrução DROP VIEW remove uma exibição criada por uma instrução CREATE VIEW.

sql-statement ::= DROP VIEW [IF EXISTS] view-name

A view-name especificada é o nome da exibição a ser ignorada. Ela é removida do banco de dados, mas nenhum dado nas tabelas subjacentes é modificado.

CREATE TRIGGER

A instrução create trigger é usada para adicionar disparadores ao esquema do banco de dados. Um disparador é uma operação do banco de dados (a trigger-action) que é realizada automaticamente quando ocorre um evento de banco de dados especificado (o database-event).

sql-statement   ::=  CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] [database-name.] trigger-name 
                     [BEFORE | AFTER] database-event 
                     ON table-name 
                     trigger-action 
sql-statement   ::=  CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] [database-name.] trigger-name 
                     INSTEAD OF database-event 
                     ON view-name 
                     trigger-action 
database-event  ::=  DELETE | 
                     INSERT | 
                     UPDATE | 
                     UPDATE OF column-list 
trigger-action  ::=  [FOR EACH ROW] [WHEN expr] 
                     BEGIN 
                       trigger-step ; 
                       [ trigger-step ; ]* 
                     END 
trigger-step    ::=  update-statement | 
                     insert-statement | 
                     delete-statement | 
                     select-statement 
column-list     ::=  column-name [, column-name]*

O acionamento de um disparador é especificado sempre que ocorre uma DELETE, INSERT ou UPDATE em uma determinada tabela de banco de dados, ou sempre que uma UPDATE de uma ou mais colunas especificadas de uma tabela são atualizadas. Os disparadores são permanentes, a menos que a palavra-chave TEMP ou TEMPORARY seja usada. Nesse caso, o disparador é removido quando a conexão de banco de dados principal da instância de SQLConnection é fechada. Caso nenhum tempo seja especificado (BEFORE ou AFTER), o disparador assume o padrão BEFORE.

Como só há suporte para disparadores FOR EACH ROW, o texto FOR EACH ROW é opcional. Com um disparador FOR EACH ROW, as instruções trigger-step são executadas para todas as linhas do banco de dados inserido, atualizado ou excluído pela instrução que faz com que o disparador seja acionado, caso a expressão de cláusula WHEN seja avaliada como true.

Caso uma cláusula WHEN seja fornecida, as instruções SQL especificadas como etapas do disparador só são executadas em linhas para as quais a cláusula WHEN é verdadeira. Caso nenhuma cláusula WHEN seja fornecida, as instruções SQL são executadas em todas as linhas.

No corpo de um disparador, (a cláusula trigger-action) os valores anteriores e posteriores à alteração da tabela afetada estão disponíveis usando os nomes de tabela especiais OLD e NEW. A estrutura das tabelas OLD e NEW corresponde à estrutura da tabela na qual o disparador é criado. A tabela OLD contém todas as linhas modificadas ou excluídas pela instrução de acionamento, no estado anterior às operações da instrução de acionamento. A tabela NEW contém todas as linhas modificadas ou criadas pela instrução de acionamento, no estado posterior às operações da instrução de acionamento. A cláusula WHEN e as instruções trigger-step podem acessar valores na linha que está sendo inserida, excluída ou atualizada usando referências da forma NEW.column-name e OLD.column-name, em que column-name é o nome de uma coluna da tabela à qual o disparador está associado. A disponibilidade das referências de tabela OLD e NEW depende do tipo de database-event tratado pelo disparador:

• INSERT – Referências NEW são válidas

• UPDATE – Referências NEW e OLD são válidas

• DELETE – Referências OLD são válidas

O tempo especificado (BEFORE, AFTER ou INSTEAD OF) determina quando as instruções trigger-step são executadas em relação à inserção, modificação ou remoção da linha associada. Uma cláusula ON CONFLICT pode ser especificada como parte de uma instrução UPDATE ou INSERT em uma trigger-step. No entanto, caso uma cláusula ON CONFLICT seja especificada como parte da instrução, o que faz com que o disparador seja acionado, é usada essa política de tratamento de conflitos.

Além dos disparadores de tabela, um disparador INSTEAD OF pode ser criado em uma exibição. Caso um ou mais disparadores INSTEAD OF INSERT, INSTEAD OF DELETE ou INSTEAD OF UPDATE sejam definidos em uma exibição, isso não é considerado erro para executar o tipo associado de instrução (INSERT, DELETE ou UPDATE) na exibição. Nesse caso, executar uma INSERT, DELETE ou UPDATE na exibição faz com que os disparadores associados sejam acionados. Como o disparador é INSTEAD OF, as tabelas subjacentes à exibição não são modificadas pela instrução que faz com que o disparador seja acionado. No entanto, os disparadores podem ser usados para realizar operações de modificação nas tabelas subjacentes.

Há algo importante para se ter em mente durante a criação de um disparador em uma tabela com uma coluna INTEGER PRIMARY KEY. Caso um disparador BEFORE modifique a coluna INTEGER PRIMARY KEY de uma linha a ser atualizada pela instrução que faz com que o disparador seja acionado, a atualização não ocorre. Uma solução é criar a tabela com uma coluna PRIMARY KEY e não uma coluna INTEGER PRIMARY KEY.

Um disparador pode ser removido usando a instrução DROP TRIGGER. Quando uma tabela ou exibição é ignorada, todos os disparadores associados também são ignorados automaticamente.

Função RAISE()

Uma função SQL RAISE() especial pode ser usada em uma instrução trigger-step de um disparador. Essa função tem a seguinte sintaxe:

raise-function  ::=  RAISE ( ABORT, error-message ) | 
                     RAISE ( FAIL, error-message ) | 
                     RAISE ( ROLLBACK, error-message ) | 
                     RAISE ( IGNORE )

Quando uma das três primeiras formas é chamada durante a execução do disparador, a ação de processamento ON CONFLICT especificada (ABORT, FAIL ou ROLLBACK) é realizada, e a execução da instrução atual é concluída. Como ROLLBACK é considerada uma falha na execução da instrução, a instância de SQLStatement cujo método execute() estava sendo realizado despacha um evento error (SQLErrorEvent.ERROR). O objeto SQLError na propriedade error do objeto do evento despachado tem o conjunto de propriedades details definido como a error-message especificada na função RAISE().

Quando RAISE(IGNORE) é chamada, o restante do disparador atual, a instrução que fez com que o disparador fosse executado e todos os disparadores subsequentes que seriam executados são abandonados. Nenhuma alteração feita no banco de dados é revertida. Caso a instrução que fez com que o disparador fosse executado seja ela própria parte de um disparador, esse programa disparador reinicia a execução no início da próxima etapa. Para obter mais informações sobre os algoritmos para resolução de conflitos, consulte a seção ON CONFLICT (algoritmos em conflito).

DROP TRIGGER

A instrução DROP TRIGGER remove um disparador criado pela instrução CREATE TRIGGER.

sql-statement  ::=  DROP TRIGGER [IF EXISTS] [database-name.] trigger-name

O disparador é excluído do banco de dados. Observe que os disparadores são ignorados automaticamente quando a tabela associada é ignorada.

COLLATE

A cláusula COLLATE é usada em instruções SELECT, CREATE TABLE e CREATE INDEX para especificar o algoritmo de comparação usado durante a comparação ou a classificação dos valores.

sql-statement   ::=  COLLATE collation-name 
collation-name  ::=  BINARY | NOCASE

O tipo de intercalação padrão de colunas é BINARY. Quando a intercalação BINARY é usada com valores da classe de armazenamento TEXT, a intercalação binária é realizada comparando-se os bytes na memória que representam o valor, independentemente da codificação do texto.

A sequência de intercalação NOCASE só é aplicada a valores da classe de armazenamento TEXT. Quando usada, a intercalação NOCASE realiza uma comparação sem diferenciação entre maiúsculas e minúsculas.

Nenhuma sequência de intercalação é usada em classes de armazenamento do tipo NULL, BLOB, INTEGER ou REAL.

Para usar um tipo de intercalação que não seja BINARY com uma coluna, uma cláusula COLLATE deve ser especificada como parte da definição da coluna na instrução CREATE TABLE. Sempre que dois valores TEXT são comparados, uma sequência de intercalação é usada para determinar os resultados da comparação de acordo com as seguintes regras:

EXPLAIN

O modificador de comando EXPLAIN é uma extensão não padrão do SQL.

sql-statement  ::=  EXPLAIN sql-statement

Caso a palavra-chave EXPLAIN seja exibida antes de qualquer outra instrução SQL, em vez de efetivamente executar o comando, o resultado informa a sequência das instruções da máquina virtual que seriam usadas para executar o comando, se a palavra-chave EXPLAIN não estivesse presente. O recurso EXPLAIN é um recurso avançado e permite aos desenvolvedores alterar o texto da instrução SQL em uma tentativa de otimizar o desempenho ou depurar uma instrução que não parece estar funcionando corretamente.

ON CONFLICT (algoritmos em conflito)

A cláusula ON CONFLICT não é um comando SQL separado. Trata-se de uma cláusula não padrão que pode ser exibida em muitos outros comandos SQL.

conflict-clause     ::=  ON CONFLICT conflict-algorithm 
conflict-clause     ::=  OR conflict-algorithm 
conflict-algorithm  ::=  ROLLBACK | 
                         ABORT | 
                         FAIL | 
                         IGNORE | 
                         REPLACE

A primeira forma da cláusula ON CONFLICT, usando as palavras-chave ON CONFLICT, é usada em uma instrução CREATE TABLE. Em uma instrução INSERT ou UPDATE, é usada a segunda forma, com ON CONFLICT substituída por OR para fazer a sintaxe parecer mais natural. Por exemplo, em vez de INSERT ON CONFLICT IGNORE, a instrução se torna INSERT OR IGNORE. Embora as palavras-chave sejam diferentes, o significado da cláusula é o mesmo nas duas formas.

A cláusula ON CONFLICT especifica o algoritmo usado para resolver conflitos de restrição. Os cinco algoritmos são ROLLBACK, ABORT, FAIL, IGNORE e REPLACE. O algoritmo padrão é ABORT. A seguir, uma explicação dos cinco algoritmos de conflito:

ROLLBACK

Quando ocorre uma violação de restrição, ocorre uma ROLLBACK imediata, encerrando a transação atual. O comando é abortado e a ocorrência de SQLStatement despacha um erro error. Caso não haja nenhuma transação ativa (outra que não seja a implícita criada em todos os comandos), esse algoritmo funciona da mesma forma que ABORT.

ABORT

Quando ocorre uma violação de restrição, o comando restaura todas as alterações anteriores que possa ter feito e a ocorrência de SQLStatement gera um evento error. Como nenhuma ROLLBACK é executada, as alterações feitas em comandos anteriores em uma transação são preservadas. ABORT é o comportamento padrão.

FAIL

Quando ocorre uma violação de restrição, o comando é abortado e a SQLStatement gera um evento error. No entanto, todas as alterações feitas no banco de dados pela instrução antes de encontrar a violação de restrição são preservadas, e não restauradas. Por exemplo, caso uma instrução UPDATE encontre uma violação de restrição na 100ª linha que ela tenta atualizar, as alterações iniciais feitas nas 99 linhas são preservadas, mas as feitas nas linhas 100 e posteriores não ocorrem.

IGNORE

Quando ocorre uma violação de restrição, uma linha que contém a violação de restrição não é inserida ou alterada. Além de essa linha ser ignorada, o comando continua sendo executado normalmente. Outras linhas anteriores e posteriores à linha que apresentava a violação de restrição continuavam sendo inseridas ou atualizadas normalmente. Nenhum erro é retornado.

REPLACE

Quando ocorre uma violação de restrição UNIQUE, as linhas preexistentes que estão causando a violação de restrição são removidas antes de inserir ou atualizar a linha atual. Consequentemente, a inserção ou a atualização sempre ocorre e o comando continua sendo executado normalmente. Nenhum erro é retornado. Caso ocorra uma violação de restrição NOT NULL, o valor NULL é substituído pelo valor padrão da coluna. Caso a coluna não tenha nenhum valor padrão, é usado o algoritmo ABORT. Caso ocorra uma violação de restrição CHECK, é usado o algoritmo IGNORE. Quando essa estratégia de resolução de conflitos exclui linhas para atender a uma restrição, ela não invoca disparadores de exclusão nessas linhas.

O algoritmo especificado na cláusula OR de uma instrução INSERT ou UPDATE substitui todos os algoritmos especificados em uma instrução CREATE TABLE. Caso nenhum algoritmo seja especificado na instrução CREATE TABLE ou na instrução INSERT ou UPDATE em execução, é usado o algoritmo ABORT.

REINDEX

O comando REINDEX é usado para excluir e recriar um ou mais índices. Esse comando é útil quando a definição de uma sequência de intercalação é alterada.

sql-statement  ::=  REINDEX collation-name 
sql-statement  ::=  REINDEX [database-name .] ( table-name | index-name )

Na primeira forma, todos os índices em todos os bancos de dados anexados que usam a sequência de intercalação nomeada são recriados. Na segunda forma, quando é especificada table-name, todos os índices associados à tabela são recriados. Caso uma index-name seja fornecida, apenas o índice especificado é excluído e recriado.

COMMENTS

Comentários não são comandos SQL, mas podem ocorrer em consultas SQL. Eles são tratados como espaço em brando pelo tempo de execução. Eles podem começar em qualquer lugar onde haja um espaço em branco, inclusive dentro de expressões que se estendam por várias linhas.

comment             ::=  single-line-comment | 
                         block-comment 
single-line-comment ::=  -- single-line 
block-comment       ::=  /* multiple-lines or block [*/]

Um comentário com uma única linha é indicado por dois traços. Ele só se estende até o final da linha atual.

Comentários em bloco podem se estender por um número variado de linhas ou ser incorporados a uma única linha. Caso não haja nenhum delimitador de encerramento, um comentário em bloco se estende até o final da entrada. Essa situação não é tratada como um erro. Uma nova instrução SQL pode começar em uma linha após o término do comentário em bloco. Os comentários em bloco podem ser incorporados em qualquer lugar onde haja um espaço em branco, inclusive expressões internas e no meio de outras instruções SQL. Os comentários em bloco não são aninhados. Comentários em linha única dentro de um comentário em bloco são ignorados.

EXPRESSIONS

As expressões são subcomandos dentro de outros blocos SQL. A seguir, a descrição da sintaxe válida de uma expressão dentro de uma instrução SQL:

expr            ::=  expr binary-op expr | 
                     expr [NOT] like-op expr [ESCAPE expr] | 
                     unary-op expr | 
                     ( expr ) | 
                     column-name | 
                     table-name.column-name | 
                     database-name.table-name.column-name | 
                     literal-value | 
                     parameter | 
                     function-name( expr-list | * ) | 
                     expr ISNULL | 
                     expr NOTNULL | 
                     expr [NOT] BETWEEN expr AND expr | 
                     expr [NOT] IN ( value-list ) | 
                     expr [NOT] IN ( select-statement ) | 
                     expr [NOT] IN [database-name.] table-name | 
                     [EXISTS] ( select-statement ) | 
                     CASE [expr] ( WHEN expr THEN expr )+ [ELSE expr] END | 
                     CAST ( expr AS type ) | 
                     expr COLLATE collation-name 
like-op         ::=  LIKE | GLOB 
binary-op       ::=  see Operators 
unary-op        ::=  see Operators 
parameter       ::=  :param-name | @param-name | ? 
value-list      ::=  literal-value [, literal-value]* 
literal-value   ::=  literal-string | literal-number | literal-boolean | literal-blob | literal-null 
literal-string  ::=  'string value' 
literal-number  ::=  integer | number 
literal-boolean  ::=  true | false 
literal-blob  ::=  X'string of hexadecimal data' 
literal-null  ::=  NULL

Uma expressão é uma combinação de valores e operadores que podem ser resolvidos como um valor único. As expressões podem ser divididas em dois tipos gerais, dependendo de sua resolução como um valor booliano (true ou false) ou como um valor não booliano.

Em várias situações comuns, inclusive em uma cláusula WHERE, HAVING, a expressão ON em uma cláusula JOIN e uma expressão CHECK, a expressão deve ser resolvida como um valor booliano. Os tipos de expressões a seguir atendem a essa condição:

• ISNULL

• NOTNULL

• IN ()

• EXISTS ()

• LIKE

• GLOB

• Determinadas funções

• Determinados operadores (mais especificamente operadores de comparação)

Valores literais

Um valor numérico literal é escrito como um número inteiro ou um número de ponto flutuante. A notação científica é suportada. O quantificador . (ponto final) é sempre usado como a casa decimal.

Uma string literal é indicada colocando a string entre aspas simples '. Para incluir uma aspa simples dentro de uma string, coloque duas aspas simples em sequência como este exemplo:

Um literal booliano é indicado pelo valor true ou false. Os valores boolianos literais são usados com o tipo de dados da coluna Booliana.

Um literal de BLOB é uma string literal contendo dados hexadecimais e após um único caractere x ou X como, por exemplo, X'53514697465'.

Um valor literal também pode ser o token NULL.

Nome da coluna

Um nome de coluna pode ser qualquer um dos nomes definidos na instrução CREATE TABLE ou em um dos seguintes identificadores especiais: Esses identificadores especiais descrevem a chave de inteiro aleatória exclusiva (a chave de linha) associada a todas as linhas de cada tabela. Os identificadores especiais só se referem à chave de linha caso a instrução CREATE TABLE não defina uma coluna real com o mesmo nome. As chaves de linha se comportam como colunas somente leitura. Uma chave de linha pode ser usada em qualquer lugar onde uma coluna normal possa ser usada, exceto pelo fato de não ser possível alterar o valor de uma chave de linha em uma instrução UPDATE ou INSERT. A instrução SELECT * FROM table não inclui a chave de linha no conjunto de resultados.

Instrução SELECT

Uma instrução SELECT pode ser exibida em uma expressão como o operando à direita do operador IN, como quantidade escalar (um único valor de resultado), ou como o operando de um operador EXISTS. Quando usada como quantidade escalar ou o operando de um operador IN, a SELECT só pode ter uma única coluna no resultado. Uma instrução SELECT composta (conectada com palavras-chave como UNION ou EXCEPT) é permitida. Com o operador EXISTS, as colunas do conjunto de resultados de SELECT são ignoradas e a expressão retorna TRUE caso haja uma ou mais linhas e FALSE caso o conjunto de resultados seja vazio. Caso nenhum termo da expressão SELECT se refira ao valor na consulta, a expressão é avaliada uma vez antes de qualquer outro processamento e o resultado é reutilizado conforme necessário. Caso a expressão SELECT não contenha variáveis da consulta externa, conhecida como subconsulta correlacionada, a SELECT é reavaliada sempre que necessário.

Quando uma SELECT for o operando à direita do operador IN, o operador IN retorna TRUE caso o resultado do operando à esquerda seja igual a qualquer um dos valores no conjunto de resultados da instrução SELECT. O operador IN pode ser precedido pela palavra-chave NOT para inverter o sentido do teste.

Quando uma SELECT é exibida dentro de uma expressão, mas não é operando à direita de um operador IN, a primeira linha do resultado da SELECT se torna o valor usado na expressão. Caso a SELECT produza mais de uma linha de resultado, todas as linhas depois dela são ignoradas. Caso a SELECT não produza nenhuma linha, o valor da SELECT é NULL.

expressão CAST

Uma expressão CAST altera o tipo de dados do valor especificado para o especificado. O tipo especificado pode ser um nome de tipo não vazio válido para o tipo em uma definição de coluna de uma instrução CREATE TABLE. Suporte ao tipo de dados

Elementos de expressão adicionais

Os elementos SQL a seguir também podem ser usados em expressões:

• Funções internas: funções agregadas, funções escalares e funções de formatação de data/hora

• Operadores

• Parâmetros

funções agregadas

As funções agregadas realizam operações em valores de várias linhas. Essas funções são especialmente usadas em instruções SELECT com a cláusula GROUP BY.

Em qualquer uma das funções agregadas anteriores que usam um único argumento, esse argumento pode ser precedido pela palavra-chave DISTINCT. Nesse caso, os elementos duplicados são filtrados antes de serem passados para a função agregada. Por exemplo, a chamada de função COUNT(DISTINCT x) retorna o número de valores distintos da coluna X e não o número total de valores que não sejam NULL na coluna x.

funções escalares

As funções escalares funcionam em valores uma linha por vez.

funções de formatação de data e hora

As funções de formatação de data e hora são um grupo de funções escalares usadas para criar dados de data e hora formatados. Observe que essas funções operam e retornam valores de string e número. Essas funções não devem ser usadas com o tipo de dados DATE. Caso você use essas funções nos dados de uma coluna cujo tipo de dados declarado é DATE, elas não se comportam como esperado.

Formatos de hora

O caractere V nesses formatos é um caractere literal "T" que separa a data e a hora. Os formatos que só incluem uma hora pressupõem a data 2001-01-01.

Modificadores

Operadores comuns

Os seguintes operadores binários são permitidos em um bloco SQL, estando listados da maior para a menor precedência:

*    /    % 
+    - 
<< >> &     | 
< >=   > >= 
=    ==   !=   <> IN 
AND 
OR

Os operadores de prefixo unários para os quais há suporte são:

 !    ~    NOT

O operador COLLATE pode ser considerado um operador de sufixo unário. O operador COLLATE apresenta a maior precedência. Ele sempre é mais vinculado do que qualquer operador unário de prefixo ou operador binário.

Observe que existem duas variações dos operadores de igualdade e de não-igualdade. A igualdade pode ser = ou ==. O operador de não igualdade pode ser != ou <>.= ou <>.

O operador || é o operador de concatenação da string—ele une as duas strings dos operandos.

O operador % fornece o restante do módulo do operando à esquerda no operando à direita.

O resultado de qualquer operador binário é um valor numérico, exceto pelo operador de concatenação || que fornece um resultado de string.

Operadores SQL

LIKE

O operador LIKE realiza uma comparação de padrões.

expr     ::=  (column-name | expr) LIKE pattern 
pattern  ::=  '[ string | % | _ ]'

O operando à direita do operador LIKE contém o padrão e o operando à esquerda contém a string de acordo com o padrão. Um símbolo de porcentagem (%) no padrão é um caractere curinga—ele corresponde a qualquer sequência de zero ou mais caracteres na string. Um sublinhado (_) no padrão corresponde a um único caractere da string. Qualquer outro caractere se compara ou o equivalente em maiúsculas/minúsculas, ou seja, são feitas as correspondências de maneira sem diferenciação de maiúsculas e minúsculas. o mecanismo de banco de dados só compreende maiúsculas/minúsculas em caracteres Latinos de 7 bits. Consequentemente, o operador LIKE diferencia maiúsculas e minúsculas para caracteres iso8859 de 8 bits ou caracteres UTF-8. Por exemplo, a expressão 'a' LIKE 'A' é TRUE, mas 'æ' LIKE 'Æ' é FALSE). A diferenciação entre maiúsculas e minúsculas para caracteres Latin pode ser alterada usando a propriedade SQLConnection.caseSensitiveLike.

Caso a cláusula opcional ESCAPE esteja presente, a expressão após a palavra-chave ESCAPE deve ser avaliada como uma string que consiste em um único caractere. Esse caractere pode ser usado no padrão LIKE para corresponder aos caracteres de porcentagem literal ou sublinhado. O caractere de escape seguido de um símbolo de porcentagem, sublinhado ou ele próprio compara um símbolo de porcentagem, sublinhado ou caractere de escapa na string, respectivamente.

GLOB

O operador GLOB é semelhante a LIKE, mas usa a sintaxe globbing do arquivo Unix nos curingas. Diferentemente de LIKE, GLOB diferencia maiúsculas de minúsculas.

IN

O operador IN calcula se o operando à esquerda é igual a um dos valores no operando à direita (um conjunto de valores entre parênteses).

in-expr         ::=  expr [NOT] IN ( value-list ) | 
                     expr [NOT] IN ( select-statement ) | 
                     expr [NOT] IN [database-name.] table-name 
value-list      ::=  literal-value [, literal-value]*

O operando à direita pode ser um conjunto de valores literais separados por vírgulas ou o resultado de uma instrução SELECT. Consulte as instruções SELECT em expressões para obter uma explicação e saber as limitações quanto ao uso de uma instrução SELECT como operando à direita do operador IN.

BETWEEN...AND

O operador BETWEEN...AND equivale ao uso de duas expressões com os operadores >= e <=. Por exemplo, a expressão x BETWEEN y AND z é equivalente a x >= y AND x <= z.

NOT

NOT é um operador de negação. Os operadores GLOB, LIKE, e IN podem ser precedidos pela palavra-chave NOT para inverter o sentido do teste (em outras palavras, para verificar se um valor não corresponde ao padrão indicado).