Sintaxis SQL admitida

SELECT

La declaración SELECT se utiliza para consultar la base de datos. El resultado de una declaración SELECT es cero o más filas de datos, donde cada fila tiene un número fijo de columnas. El número de columnas del resultado se especifica mediante el nombre de la columna result o la lista de expresiones entre las palabras clave SELECT y FROM (opcional).

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

Cualquier expresión arbitraria se puede utilizar como resultado. Si una expresión del resultado es *, todas las columnas de todas las tablas se reemplazan por dicha expresión. Si la expresión es el nombre de una tabla seguido de .*,el resultado es todas las columnas de dicha tabla.

La palabra clave DISTINCT provoca la devolución de un subconjunto de filas de resultados (donde cada fila es distinta). Se asume que todos los valores de NULL son iguales. El comportamiento predeterminado es la devolución de todas las filas de resultados, que se pueden explicitar con la palabra clave ALL.

La consulta se ejecuta en una o varias tablas especificadas con la palabra clave FROM. Si los distintos nombres de las tablas están separados por comas, la consulta utiliza la unión cruzada de las distintas tablas. La sintaxis JOIN también se puede utilizar para especificar el modo de unión de las tablas. El único tipo de unión externa admitida es LEFT OUTER JOIN. Las expresiones de la cláusula ON deben producir como resultado un valor booleano. Se puede utilizar una subconsulta entre paréntesis como una tabla de la cláusula FROM. Se puede omitir toda la cláusula FROM, en cuyo caso, el resultado será una única fila con los valores de la lista de expresiones del resultado.

La cláusula WHERE se utiliza para limitar el número de filas recuperadas por la consulta. Las expresiones de la cláusula WHERE deben producir como resultado un valor booleano. El filtrado de la cláusula WHERE se lleva a cabo antes de cualquier agrupación, por lo que las expresiones de la cláusula WHERE no pueden incluir funciones de agregación.

La cláusula GROUP BY combina una o varias filas del resultado en una sola fila de resultados. La cláusula GROUP BY es especialmente útil cuando el resultado contiene funciones de agregación. Las expresiones de la cláusula GROUP BY no tienen por qué ser expresiones que aparezcan en la lista de expresiones SELECT.

La cláusula HAVING se parece a WHERE, en el sentido que limita las filas devueltas por la declaración. Sin embargo, la cláusula HAVING se aplica tras producirse cualquier agrupación especificada por una cláusula GROUP BY. En consecuencia, la expresión HAVING puede hacer referencia a valores que incluyan funciones de agregación. No es necesario que aparezca ninguna expresión de la cláusula HAVING en la lista SELECT. Al igual que ocurre con la expresión WHERE, la expresión HAVING debe producir como resultado un valor booleano.

La cláusula ORDER BY provoca la ordenación de las filas de resultados. El argumento sort-expr-list de la cláusula ORDER BY es una lista de expresiones utilizadas como clave para la ordenación. Las expresiones no tienen por qué formar parte del resultado de una declaración SELECT, pero en una declaración SELECT compuesta (una declaración SELECT que utilice uno de los operadores compound-op), cada expresión de ordenación debe coincidir exactamente con una de las columnas de resultados. Cada expresión de ordenación puede ir acompañada, de forma opcional, de una cláusula sort-order formada por la palabra clave COLLATE y el nombre de la función de intercalación utilizada para ordenar el texto, o bien la palabra clave ASC o DESC para especificar el tipo de ordenación (ascendente o descendente). sort-order se puede omitir y utilizar el valor predeterminado (orden ascendente). Para obtener una definición de la cláusula COLLATE y de las funciones de intercalación, consulte COLLATE.

La cláusula LIMIT pone un límite superior al número de filas devueltas en el resultado. Un valor negativo de LIMIT indica la ausencia de límite superior. El OFFSET opcional que sigue a LIMIT especifica el número de filas que se deben saltar al principio del conjunto de resultados. En una consulta SELECT compuesta, la cláusula LIMIT tal vez aparezca solo tras la declaración SELECT final. El límite se aplica a toda la consulta. Tenga en cuenta que si utiliza la palabra clave OFFSET en la cláusula LIMIT, el límite es el primer entero y el desfase es el segundo entero. Si se utiliza una coma en vez de la palabra clave OFFSET, el desfase es primer número y el límite es el segundo. Esta aparente contradicción es intencionada: maximiza la compatibilidad con sistemas de bases de datos SQL heredados.

Un SELECT compuesto está formado por do o más declaraciones SELECT simples conectadas por uno de los operadores UNION, UNION ALL, INTERSECT o EXCEPT. En un SELECT, compuesto, todas las declaraciones SELECT que lo forman deben especificar el mismo número de columnas de resultados. Solo puede haber una cláusula ORDER BY única tras la declaración SELECT final (y antes de la cláusula LIMIT única, si se ha especificado). Los operadores UNION y UNION ALL combinan los resultados de las declaraciones SELECT siguiente y anterior en una sola tabla. La diferencia reside en que en UNION, todas las filas de resultados son distintas, mientras que en UNION ALL puede haber duplicados. El operador INTERSECT toma la intersección de los resultados de las declaraciones SELECT anterior y siguiente. EXCEPT toma el resultado del SELECT anterior tras eliminar los resultados del SELECT siguiente. Si se conectan tres o más declaraciones SELECT en una compuesta, se agrupan de la primera a la última.

Para obtener una definición de las expresiones permitidas, consulte Expresiones.

Desde AIR 2.5, el operador CAST de SQL es compatible al leer para convertir los datos BLOB a objetos ByteArray de ActionScript. Por ejemplo, el siguiente código lee los datos sin procesar que no se almacenen en formato AMF y los almacena en un 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

La primera expresión (con la palabra clave VALUES) crea una única nueva fila en una tabla existente. Si no se especifica un column-list, el número de valores debe coincidir con el número de columnas de la tabla. Si se especifica un column-list, el número de valores debe coincidir con el número de columnas especificadas. Las columnas de la tabla que no aparecen en la lista de columnas se llenan con valores predeterminados en el momento de creación de la tabla, o con NULL si no hay ningún valore predeterminado definido.

La segunda expresión de la declaración INSERT toma los datos de una declaración SELECT. El número de columnas del resultado de SELECT debe coincidir exactamente con el número de columnas de la tabla si no se especifica column-list, o debe coincidir con el número de columnas especificadas en el column-list. Se realiza una nueva entrada en la tabla por cada fila del resultado de SELECT. El SELECT puede ser simple o compuesto. Para obtener una definición de las declaraciones SELECT admitidas, consulte SELECT.

El conflict-algorithm opcional permite especificar un algoritmo de resolución de conflictos de restricciones alternativo y utilizarlo durante este comando. Para ver una explicación y definición de algoritmos de conflicto, consulte Declaraciones y cláusulas especiales .

Las dos formas de REPLACE INTO de la declaración equivalen a utilizar la expresión INSERT [OR conflict-algorithm] estándar con el algoritmo de conflictos REPLACE (p.ej. la forma INSERT OR REPLACE...).

Las dos formas de REPLACE INTO de la declaración equivalen a utilizar la expresión INSERT [OR conflict-algorithm] estándar con el algoritmo de conflictos REPLACE (p.ej. la forma INSERT OR REPLACE...).

UPDATE

El comando de actualización cambia los registros existentes en una tabla.

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

El comando consta de una palabra clave UPDATE seguida del nombre de la tabla en la que se desean actualizar los registros. Tras la palabra clave SET, indique el nombre de la columna y el valor con el que la columna cambiará como lista separada por comas. La expresión de la cláusula WHERE proporciona la fila o filas en las que se actualizan los registros.

DELETE

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

El comando está formado por las palabras clave DELETE FROM seguidas del nombre de la tabla de la que se eliminarán los registros.

Sin una cláusula WHERE, se eliminan todas las filas de la tabla. Si se facilita una cláusula WHERE, solo se eliminan las filas que coincidan con la expresión. La expresión de la cláusula WHERE debe producir como resultado un valor booleano. Para obtener una definición de las expresiones permitidas, consulte Expresiones.

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 definición de columna es el nombre de la columna seguido de su tipo de datos correspondiente y, por último, una o varias restricciones de columna opcionales. El tipo de datos de la columna limita los datos que pueden guardarse en dicha columna. Si se intenta guardar un valor en una columna con tipos de datos distintos, el motor de ejecución convertirá el valor en el tipo adecuado si es posible, o lanzará un error. Consulte la sección Compatibilidad de tipos de datos para obtener más información.

La restricción de la columna NOT NULL indica que la columna no puede contener valores NULL.

Una restricción UNIQUE provoca la creación de un índice en la columna o columnas especificadas. Este índice puede contener claves únicas: dos filas no pueden contener valores duplicados o combinaciones de valores para la columna o columnas especificadas. Una declaración CREATE TABLE puede tener varias restricciones UNIQUE, incluidas varias columnas con una restricción UNIQUE en la definición de la columna o múltiples restricciones UNIQUE en el nivel de las tablas.

Una restricción CHECK define una expresión que se calcula y debe ser true para poder insertar o actualizar los datos de una fila. La expresión CHECK debe producir como resultado un valor booleano.

Una cláusula COLLATE en una definición de columna especifica qué función de intercalación de texto debe usarse al comparar entradas de texto en la columna. La función de intercalación BINARY se utiliza de forma predeterminada. Para obtener más información sobre la cláusula COLLATE y sus funciones de intercalación, consulte COLLATE.

La restricción DEFAULT especifica un valor predeterminado para utilizarlo con un INSERT. El valor puede ser NULL, una constante de cadena o un número. El valor predeterminado también puede ser una de las palabras clave especiales (no distinguen entre mayúsculas y minúsculas) CURRENT_TIME, CURRENT_DATE o CURRENT_TIMESTAMP. Si el valor es NULL, se inserta (literalmente) una constante de cadena o un número en la columna cada vez que una declaración INSERT no especifique un valor para la columna. Si el valor es CURRENT_TIME, CURRENT_DATE o CURRENT_TIMESTAMP, se inserta en la columna la fecha/hora UTC actual. Para CURRENT_TIME, el formato es HH:MM:SS. Para CURRENT_DATE, el formato es YYYY-MM-DD. El formato para CURRENT_TIMESTAMP es YYYY-MM-DD HH:MM:SS.

Al especificar un PRIMARY KEY, normalmente solo se crea un índice de UNIQUE en la columna o columnas correspondientes. Sin embargo, si la restricción PRIMARY KEY se encuentra en una sola columna con el tipo de datos INTEGER (o a uno de sus equivalentes como int), entonces la base de datos utiliza dicha columna como clave principal actual para la tabla. Esto significa que la columna solo puede contener valores enteros únicos. (Tenga en cuenta que en muchas implementaciones de SQLite solo el tipo de columna INTEGER hace que la columna sirva de clave principal interna, pero en Adobe AIR, los equivalentes de INTEGER como int también proporcionan este comportamiento.)

Si una tabla no contiene una columna INTEGER PRIMARY KEY, se generará automáticamente una clave de enteros al insertar una fila. Siempre se puede acceder a la clave principal de una fila mediante uno de los nombres especiales ROWID, OID o _ROWID_. Puede utilizar estos nombres tanto si son un INTEGER PRIMARY KEY declarado explícitamente o un valor interno generado. No obstante, si la tabla tiene un INTEGER PRIMARY KEY explícito, el nombre de la columna de los datos del resultado es el nombre real de la columna, no el nombre especial.

Una cINTEGER PRIMARY KEY también puede contener la palabra clave AUTOINCREMENT. Cuando se utiliza la palabra clave AUTOINCREMENT , la base de datos genera automáticamente una clave entera incrementada y la inserta en la columna INTEGER PRIMARY KEY cuando ejecuta una declaración INSERT que no especifica ningún valor explícito para la columna.

Solo puede haber una restricción PRIMARY KEY en una declaración CREATE TABLE. Puede ser parte de una definición de columna o tratarse de una restricción PRIMARY KEY única en el nivel de tablas. Una columna de clave principal es NOT NULL implícitamente.

La cláusula conflict-clause opcional con restricciones permite especificar un algoritmo de resolución de conflictos de restricciones alternativo predeterminado para dicha restricción. El valor predeterminado es ABORT. Las restricciones distintas de la misma tabla pueden tener distintos algoritmos de resolución de conflictos predeterminados. Si una declaración INSERT o UPDATE especifica un algoritmo de resolución de conflictos de restricciones distinto, dicho algoritmo se utilizará en vez del especificado en la declaración CREATE TABLE. Consulte la sección ON CONFLICT de Declaraciones y cláusulas especiales para obtener más información.

Las restricciones adicionales, como las FOREIGN KEY, no producen errores porque el motor de ejecución las omite.

Si las palabras clave TEMP o TEMPORARY se encuentran entre CREATE y TABLE, la tabla creada solo será visible dentro de la misma conexión de base de datos (instancia de SQLConnection). Se elimina automáticamente cuando se cierra la conexión de base de datos. Todos los índices creados en una tabla temporal también son temporales. Las tablas y los índices temporales se guardan en un archivo independiente distinto del archivo principal de la base de datos.

Si se especifica el prefijo opcional database-name, la tabla se crea en una base de datos especificada (base de datos conectada a la instancia de SQLConnection mediante la llamada al método attach() con el nombre de base de datos especificado). Es un error especificar un prefijo database-name y la palabra clave TEMP, a no ser que el prefijo database-name sea temp. Si no se especifica ningún nombre de base de datos y la palabra clave TEMP no está presente, la tabla se crea en la base de datos principal (la base de datos conectada a la instancia de SQLConnection mediante el método open() o openAsync()).

No hay límites arbitrarios en el número de columnas o en el número de restricciones de una tabla. Tampoco hay límites arbitrarios en la cantidad de datos de una fila.

La expresión CREATE TABLE AS define la tabla como el conjunto de resultados de una consulta. Los nombres de las columnas de la tabla son los nombres de las columnas del resultado.

Si la cláusula IF NOT EXISTS opcional está presente y ya existe otra tabla con el mismo nombre, la base de datos ignora el comando CREATE TABLE.

Se puede eliminar una tabla con la declaración DROP TABLE, y se pueden realizar cambios limitados con la declaración ALTER TABLE.

ALTER TABLE

El comando ALTER TABLE permite al usuario renombrar o agregar una nueva columna a una tabla existente. No es posible eliminar una columna de una tabla.

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

Se utiliza la sintaxis RENAME TO para renombrar la tabla identificada por [database-name.] como new-table-name. Este comando no se puede utilizar para mover una tabla entre bases de datos asociadas; solo sirve para renombrar una tabla dentro de la misma base de datos.

Si la tabla que se va a renombrar contiene activadores o índices, estos permanecen asociados a la tabla una vez renombrada. No obstante, si hay definiciones o declaraciones de vistas ejecutadas por activadores que hacen referencia a la tabla que se está renombrando, no se actualizan automáticamente con el nuevo nombre de la tabla. Si la tabla renombrada tiene vistas o activadores asociados, debe descartarlos manualmente y recrear las definiciones de los activadores o las vistas con el nuevo nombre de la tabla.

Se utiliza la sintaxis ADD [COLUMN] para agregar una nueva columna a una tabla existente. La nueva columna siempre se añade al final de la lista de las columnas existentes. La cláusula column-def puede expresarse de todas las formas permitidas en una declaración CREATE TABLE, aunque con las siguientes restricciones:

• La columna no puede tener una restricción PRIMARY KEY o UNIQUE.

• La columna no puede tener un valor predeterminado CURRENT_TIME, CURRENT_DATE o CURRENT_TIMESTAMP.

• Si se especifica una restricción NOT NULL, la columna debe tener un valor predeterminado distinto de NULL.

El tiempo de ejecución de la declaración ALTER TABLE no se ve afectado por la cantidad de datos de la tabla.

DROP TABLE

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

De forma predeterminada, la declaración DROP TABLE no reduce el tamaño del archivo de base de datos. El espacio libre de la base de datos se conserva y se utiliza en operaciones INSERT posteriores. Para eliminar espacio libre de la base de datos, utilice el método SQLConnection.clean(). Si el parámetro autoClean se establece en true al crear la base de datos por primera vez, el espacio se libera automáticamente.

La cláusula IF EXISTS opcional desactiva el error que se produciría si la tabla no existiese.

CREATE INDEX

El comando CREATE INDEX está formado por las palabras clave CREATE INDEX seguidas del nombre del nuevo índice, la palabra clave ON, el nombre de una tabla creada previamente para indexar y una lista entre paréntesis de los nombres de las columnas cuyos valores se utilizan para la clave del í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 columna puede ir seguida de las palabras clave ASC o DESC para indicar la ordenación, pero la designación del orden se omite en tiempo de ejecución. La ordenación siempre se establece en orden ascendente.

La cláusula COLLATE que sigue a cada nombre de columna define una secuencia de intercalación utilizada para los valores de texto de dicha columna. La secuencia de intercalación predeterminada es la definida para dicha columna en la declaración CREATE TABLE. Si no se especifica ninguna secuencia de intercalación, se utiliza BINARY. Para obtener una definición de la cláusula COLLATE y de las funciones de intercalación, consulte COLLATE.

No hay límites arbitrarios en el número de índices que se pueden asociar a una sola tabla. Tampoco hay límites en el número de columnas de cada índice.

DROP INDEX

La declaración DROP INDEX elimina un índice agregado con la declaración CREATE INDEX. El índice especificado se elimina completamente del archivo de base de datos. La única forma de poder recuperar el índice es volver a escribir el comando CREATE INDEX correspondiente.

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

De forma predeterminada, la declaración DROP INDEX no reduce el tamaño del archivo de base de datos. El espacio libre de la base de datos se conserva y se utiliza en operaciones INSERT posteriores. Para eliminar espacio libre de la base de datos, utilice el método SQLConnection.clean(). Si el parámetro autoClean se establece en true al crear la base de datos por primera vez, el espacio se libera automáticamente.

CREATE VIEW

El comando CREATE VIEW asigna un nombre a una declaración SELECT predefinida. Este nuevo nombre se puede utilizar posteriormente en una cláusula FROM de otra declaración SELECT en vez de un nombre de tabla. Las vistas se suelen utilizar para simplificar las consultas combinando un complejo conjunto de datos (de uso frecuente) en una estructura que se puede utilizar en otras operaciones.

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

Si la palabra clave TEMP o TEMPORARY se encuentra entre CREATE y VIEW, la vista creada solo es visible para la instancia de SQLConnection que abrió la base de datos y se elimina automáticamente al cerrarla.

Si se especifica un [database-name], la vista se crea en la base de datos especificada (una base de datos conectada a la instancia de SQLConnection mediante el método attach(), con el argumento name especificado. Es un error especificar un [database-name] y la palabra clave TEMP a no ser que [database-name] sea temp. Si no se especifica ningún nombre de base de datos y la palabra clave TEMP no está presente, la vistase crea en la base de datos principal (la base de datos conectada a la instancia de SQLConnection mediante el método open() o openAsync()).

Las vistas son de solo lectura. Una declaración DELETE, INSERT o UPDATE no se puede utilizar en una vista, a no ser que se haya definido al menos un activador del tipo asociado (INSTEAD OF DELETE, INSTEAD OF INSERT, INSTEAD OF UPDATE). Para obtener más información sobre la creación de un activador para una vista, consulte CREATE TRIGGER.

La declaración DROP VIEW elimina una vista de la base de datos.

DROP VIEW

La declaración DROP VIEW elimina una vista creada con la declaración CREATE VIEW.

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

El view-name especificado es el nombre de la vista que se va a descartar. Se elimina de la base de datos, pero no se modifica ningún dato de las tablas subyacentes.

CREATE TRIGGER

La declaración CREATE TRIGGER se utiliza para agregar activadores al esquema de base de datos. Un activador es una operación de base de datos (trigger-action) que se lleva a cabo automáticamente cuando se produce un evento concreto de base de datos (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]*

Un activador se activa cada vez que se produce un DELETE, INSERT o UPDATE en una tabla de base de datos particular, o cuando se actualiza el UPDATE de una o varias columnas de una tabla. Los activadores son permanente, a no ser que se utilice la palabra clave TEMP o TEMPORARY. En ese caso, el activador se elimina cuando se cierra la conexión de base de datos principal de la instancia de SQLConnection. Si no se especifica ningún tiempo, (BEFORE o AFTER) el valor predeterminado del activador es BEFORE.

Solo se admiten activadores FOR EACH ROW, por lo que el texto FOR EACH ROW es opcional. Con un activador FOR EACH ROW, se ejecutan las declaraciones trigger-step en cada fila de la base de datos que se inserte, actualice o elimine. Para ello, la declaración activa el activador si la expresión de cláusula WHEN produce true como resultado.

Si se facilita una cláusula WHEN, las declaraciones SQL especificadas como pasos de activación solo se ejecutan en las filas en las que la cláusula WHEN es true. Si no se facilita ninguna cláusula WHEN, las declaraciones SQL se ejecutan en todas las filas.

Dentro del cuerpo de un activador (la cláusula trigger-action), los valores previos y siguientes de cambios de la tabla afectada están disponibles con los nombres especiales de tabla OLD y NEW. La estructura de las tablas OLD y NEW coincide con la estructura de la tabla en la que se crea el activador. La tabla OLD contiene todas las filas modificadas o eliminadas con la declaración del activador en el estado que tenían antes de iniciarse las operaciones de la declaración. La tabla NEW contiene todas las filas modificadas o creadas con la declaración del activador en el estado que tenían después de iniciarse las operaciones de la declaración. Tanto la cláusula WHEN como las declaraciones trigger-step pueden acceder a valores de la fila insertada, eliminada o actualizada mediante referencias expresadas como NEW.column-name y OLD.column-name, donde column-name es el nombre de la columna de la tabla con la que se asocia el activador. La disponibilidad de las referencias a la tabla OLD y NEW depende del tipo de database-event gestionado por el activador:

• INSERT – las referencias NEW son válidas

• UPDATE – las referencias NEW y OLD son válidas

• DELETE – las referencias OLD son válidas

El tiempo especificado (BEFORE, AFTER o INSTEAD OF) determina cuándo se ejecutan las declaraciones trigger-step en relación a la inserción, modificación o eliminación de la fila asociada. Una cláusula ON CONFLICT puede especificarse como parte de una declaración UPDATE o INSERT en un trigger-step. Sin embargo, si se especifica una cláusula ON CONFLICT como parte de la declaración que activa el activador, se utilizará la política de gestión de conflictos.

Además de activadores de tablas, se puede crear un activador INSTEAD OF en una vista. Si se definen uno o varios INSTEAD OF INSERT, INSTEAD OF DELETE o INSTEAD OF UPDATE en una vista, no se considerará un error ejecutar el tipo asociado de la instancia (INSERT, DELETE o UPDATE) en la vista. En ese caso, al ejecutar un INSERT, DELETE o UPDATE en la vista, activa los activadores asociados. Como el activador es un activador INSTEAD OF, las tablas subyacentes de la vista no se modifican con la declaración que activa el activador. Sin embargo, los activadores se pueden utilizar para realizar operaciones de modificación en las tablas subyacentes.

Debe tener algo importante en cuenta cuando cree un activador en una tabla con una columna INTEGER PRIMARY KEY. Si un activador BEFORE modifica la columna INTEGER PRIMARY KEY de una fila que se deba actualizar con la declaración que activa el activador, no se realiza ninguna actualización. Una alternativa es crear la tabla con una columna PRIMARY KEY en vez de con una columna INTEGER PRIMARY KEY.

Un activador se puede eliminar con la declaración DROP TRIGGER. Cuando se visualiza o se descarta una tabla, todos los activadores asociados a la tabla o a la vista también se descartan automáticamente.

Función RAISE ()

Se puede utilizar una función SQL RAISE() especial en la declaración trigger-step de un activador. Esta función tiene la sintaxis siguiente:

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

Cuando se llama a una de las primeras tres expresiones durante la ejecución del activador, la acción de procesamiento ON CONFLICT especificada (ABORT, FAIL o ROLLBACK) se lleva a cabo y finaliza la ejecución de la declaración actual. ROLLBACK se considera un error de ejecución de declaración y la instancia de SQLStatement cuyo método execute() se estaba ejecutando distribuye un evento (SQLErrorEvent.ERROR). El objeto SQLError de la propiedad error del objeto de evento distribuido tiene su propiedad details establecida como el error-message especificado en la función RAISE().

Cuando se llama a RAISE(IGNORE), se abandona el resto del activador actual, la declaración que provocó la ejecución del activador y los activadores posteriores que podrían ejecutarse. No se invierte ningún cambio en la base de datos. Si la declaración que provocó la ejecución del activador es en sí misma un activador, su programa reanuda la ejecución al principio del siguiente paso. Para obtener más información sobre los algoritmos de resolución de conflictos, consulte la sección ON CONFLICT (algoritmos de conflictos).

DROP TRIGGER

La declaración DROP TRIGGER elimina un activador creado por la declaración CREATE TRIGGER.

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

El activador se elimina de la base de datos. Tenga en cuenta que los activadores se descartan automáticamente cuando se descarta su tabla asociada.

COLLATE

La cláusula COLLATE se utiliza en las declaraciones SELECT, CREATE TABLE y CREATE INDEX para especificar el algoritmo de comparación empleado al comparar u ordenar valores.

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

El tipo de intercalación predeterminada de las columnas es BINARY. Cuando se utiliza la intercalación BINARY con valores de la clase de almacenamiento TEXT, se lleva a cabo una intercalación binaria comparando los bytes de la memoria que representan el valor, independientemente de la codificación del texto.

La secuencia de intercalación NOCASE solo se aplica a valores de la clase de almacenamiento TEXT. Cuando se utiliza, la intercalación NOCASE lleva a cabo una comparación sin distinguir entre mayúsculas y minúsculas.

No se utiliza ninguna secuencia de intercalación en las clases de almacenamiento de tipo NULL, BLOB, INTEGER o REAL.

Para utilizar un tipo de intercalación que no sea BINARY con una columna, debe especificar una cláusula COLLATE como parte de la definición de la columna en la declaración CREATE TABLE. Cada vez que se comparan dos valores TEXT, se utiliza una secuencia de intercalación para determinar los resultados de la comparación a partir de las siguientes reglas:

EXPLAIN

El modificador de comandos EXPLAIN es una ampliación no estándar de SQL.

sql-statement  ::=  EXPLAIN sql-statement

Si la palabra clave EXPLAIN aparece antes de cualquier otra declaración SQL, en vez de ejecutar el comando, en realidad el resultado informa sobre la secuencia de instrucciones de la máquina virtual que se habría utilizado para ejecutar el comando, de no haber estado presente la palabra clave EXPLAIN. La función EXPLAIN es una función avanzada y permite a los desarrolladores cambiar el texto de declaraciones SQL para intentar mejorar el rendimiento o depurar una declaración que parezca no funcionar correctamente.

ON CONFLICT (algoritmos de conflictos)

La cláusula ON CONFLICT no es un comando SQL independiente. Se trata de una cláusula no estándar que puede aparecer en muchos otros comandos SQL.

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

La primera expresión de la cláusula ON CONFLICT utiliza las palabras clave ON CONFLICT y se utiliza en una declaración CREATE TABLE. En el caso de una declaración INSERT o UPDATE, se utiliza la segunda expresión ON CONFLICT sustituida por OR para que la sintaxis sea más natural. Por ejemplo, en vez de INSERT ON CONFLICT IGNORE, la declaración se convierte en INSERT OR IGNORE. Aunque las palabras clave son distintas, el significado de la cláusula es el mismo en ambas expresiones.

La cláusula ON CONFLICT especifica el algoritmo empleado para resolver conflictos de restricciones. Los cinco algoritmos son ROLLBACK, ABORT, FAIL, IGNORE y REPLACE. El algoritmo predeterminado es ABORT. A continuación se explican los cinco algoritmos de conflictos:

ROLLBACK

Cuando se produce una violación de restricción, se activa un ROLLBACK inmediatamente y finaliza la transacción actual. El comando se cancela y la instancia de SQLStatement distribuye un evento error. Si no hay ninguna transacción activa (que no sea la transacción implícita creada en cada comando), este algoritmo funciona igual que ABORT.

ABORT

Cuando se produce una violación de restricción, el comando descarta todos los cambios anteriores realizados y la instancia de SQLStatement distribuye un evento error. No se ejecuta ROLLBACK, por lo que se conservan los comandos anteriores de una transacción. ABORT es el comportamiento predeterminado.

FAIL

Cuando se produce una violación de restricción, el comando se cancela y la instancia de SQLStatement distribuye un evento error. No obstante, todos los cambios realizados por la declaración en la base de datos antes de producirse la violación se conservan y no se descartan. Por ejemplo, si una declaración UPDATE encuentra una violación de restricción en la fila 100 que intenta actualizar, los cambios realizados en las 99 filas anteriores se conservan, pero no así los de la fila 100 y sucesivas.

IGNORE

Cuando se produce una violación de restricción, la fila que contiene la violación no se inserta ni se cambia. Salvo el caso omiso que se hace a esta fila, el comando continúa ejecutándose con normalidad. Las filas anteriores y posteriores a la que contiene la violación de restricción se insertan y se actualizan también con normalidad. No se devuelve ningún error.

REPLACE

Cuando se produce una violación de restricción UNIQUE, las filas previas existentes que generan la violación se eliminan antes de insertar o actualizar la fila actual. En consecuencia, siempre se produce la inserción y la actualización de filas y el comando sigue ejecutándose con normalidad. No se devuelve ningún error. Si se produce una violación de restricción NOT NULL, el valor NULL se reemplaza por el valor predeterminado de dicha columna. Si la columna no tiene ningún valor predeterminado, se utiliza el algoritmo ABORT. Si se produce una violación de restricción CHECK, se utiliza el algoritmo IGNORE. Cuando esta estrategia de resolución de conflictos elimina filas para poder satisfacer una restricción, no se invocan activadores de eliminación en otras filas.

El algoritmo especificado en la cláusula OR de una declaración INSERT o UPDATE anula cualquier algoritmo especificado en una declaración CREATE TABLE. Si no se especifica ningún algoritmo en la declaración CREATE TABLE o en la declaración INSERT o UPDATE en ejecución, se utiliza el algoritmo ABORT.

REINDEX

El comando REINDEX se utiliza para eliminar y recrear uno o varios índices. El comando resulta útil si ha cambiado la definición de una secuencia de intercalación.

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

En la primera expresión, se recrean todos los índices de las bases de datos asociadas que utilicen la secuencia de intercalación especificada. En la segunda expresión, cuando se especifica un table-name, se reconstruyen todos los índices asociados a la tabla. Si se especifica un index-name, solo se elimina y se recrea el índice especificado.

COMENTARIOS

Los comentarios no son comandos SQL, pero pueden estar presentes en las consultas SQL. El motor de ejecución los trata como espacios en blanco. Pueden empezar en cualquier ubicación de un espacio en blanco, incluidas expresiones al margen que abarquen varias líneas.

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

Un comentario de una sola línea se indica con dos guiones. Un comentario de una sola línea solo llega hasta el final de la línea actual.

Los comentarios en bloque pueden abarcar varias líneas o incorporarse en una sola línea. Si no hay ningún delimitador, un comentario en bloque llega hasta el final de la entrada. Esta situación no se trata como un error. Una nueva declaración SQL puede empezar en una nueva línea detrás del final del comentario en bloque. Los comentarios en bloque pueden incluirse en cualquier espacio en blanco, incluidas expresiones al margen, y en medio de otras declaraciones SQL. Los comentarios en bloque no se pueden anidar. Los comentarios de una sola línea dentro de un comentario en bloque no se tienen en cuenta.

EXPRESIONES

Las expresiones son subcomandos dentro de otros bloques SQL. A continuación se describe la sintaxis válida para una expresión dentro de una declaración 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

Una expresión es una combinación de valores y operadores que pueden producir como resultado un valor. Las expresiones se pueden dividir en dos tipos generales, en función de si producen un valor booleano (true o false) o un valor no booleano.

En múltiples situaciones habituales, incluidas las cláusulas WHERE y HAVING, la expresión ON en una cláusula JOIN, y una expresión CHECK, la expresión debe producir como resultado un valor booleano. Los siguientes tipos de expresiones cumplen esta condición:

• ISNULL

• NOTNULL

• IN ()

• EXISTS ()

• LIKE

• GLOB

• Ciertas funciones

• Ciertos operadores (concretamente, operadores de comparación)

Valores literales

Un valor numérico literal se escribe como un número entero o un número de coma flotante. Se admite notación científica. El carácter . (punto) siempre se utiliza como punto decimal.

Un literal de cadena se indica encerrando la cadena en comillas simples '. Para incluir una comilla dentro de una cadena, ponga dos comillas sencillas seguidas como en el siguiente ejemplo: ''.

Un literal booleano se indica con el valor true o false. Los valores de literal booleano se utilizan con el tipo de datos de columna Boolean.

Un literal BLOB es un literal de cadena que contiene datos hexadecimales y está precedido de un solo carácter x o X, como X'53514697465'.

Un valor de literal también puede ser el token NULL.

Nombre de columna

Un nombre de columna puede ser cualquiera de los nombres definidos en la declaración CREATE TABLE o uno de los siguientes identificadores especiales: ROWID, OID o _ROWID_. Todos estos identificadores especiales describen la única clave de enteros aleatorios (la "clave de fila") asociada a cada fila de la tabla. Los identificadores especiales solo hacen referencia a la clave de la fila si la declaración CREATE TABLE no define una columna real con el mismo nombre. Las claves de fila se comportan como columnas de solo lectura. Una clave de fila se puede utilizar en cualquier situación en que utilizaría una columna normal, salgo para cambiar el valor de una clave de fila en una declaración UPDATE o INSERT. La declaración SELECT * FROM no incluye la clave de fila en su conjunto de resultados.

Declaración SELECT

Una declaración SELECT puede aparecer en una expresión bien como el operando a la derecha del operador IN, como una cantidad escalar (un valor de resultado único) o como el operando de un operador EXISTS. Cuando se utiliza como una cantidad escalar o como el operando de un operador IN, el SELECT solo puede tener una columna en su resultado. Se permite una declaración SELECT compuesta (conectada con palabras clave como UNION o EXCEPT). Con el operador EXISTS, las columnas del conjunto de resultados de SELECT se ignoran y la expresión devuelve TRUE si existen una o varias filas y devuelve FALSE si el conjunto de resultados está vacío. Si ningún término de la expresión SELECT hace referencia al valor de la consulta que lo contiene, la expresión se calcula una vez antes de cualquier otro procesamiento y, si es necesario, se reutiliza el resultado. Si la expresión SELECT contiene variables de la consulta exterior (denominada subconsulta correlacionada), SELECT se vuelve a calcular cada vez que sea necesario.

Cuando SELECT es el operando a la derecha del operador IN, el operador IN devuielve TRUE si el resultado del operando a la izquierda es igual que cualquiera de los valores del conjunto de resultados de la declaración SELECT. El operador IN puede estar precedido de la palabra clave NOT para invertir el sentido de la prueba.

Cuando aparece un SELECT en una expresión, pero no es un operando a la derecha del operador IN, la primera fila del resultado de SELCT pasa a ser el valor utilizado en la expresión. Si SELECT arroja más de una fila de resultados, se ignoran todas las filas siguientes. Si SELECT no arroja ninguna fila, el valor de SELECT es NULL.

Expresión CAST

Una expresión CAST cambia el tipo de datos del valor especificado al proporcionado. El tipo especificado puede ser cualquier nombre de tipo no vacío válido para el tipo en una definición de columna de la declaración CREATE TABLE. Consulte la sección Compatibilidad de tipos de datos para obtener más información.

Elementos de expresiones adicionales

Los siguientes elementos SQL también se pueden utilizar en expresiones:

• Funciones incorporadas: Funciones de agregación, funciones escalares y funciones de formato de fecha y hora

• Operadores

• Parámetros

Funciones de agregación

Las funciones de agregación realizan operaciones en valores de varias filas. Estas funciones se utilizan fundamentalmente en declaraciones SELECT en combinación con la cláusula GROUP BY.

En cualquiera de las funciones de agregación anteriores que toman un solo argumento, dicho argumento puede ir precedido de la palabra clave DISTINCT. En este caso, los elementos duplicados se filtran antes de transferirse a la función de agregación. Por ejemplo, la llamada a la función COUNT(DISTINCT x) devuelve el número de valores distintos de la columna X y no el número total de valores no NULL de la columna x.

Funciones escalares

Las funciones escalares operan con valores, de fila en fila.

Funciones de formato de fecha y hora

Las funciones de formato de fecha y hora son un grupo de funciones escalares que se utilizan para crear datos de fecha y hora con formato. Tenga en cuenta que estas funciones operan con cadenas y valores numéricos y devuelven este tipo de valores. Estas funciones no están pensadas para utilizarse con el tipo de datos DATE. Si utiliza estas funciones en datos de una columna cuyo tipo de datos declarado sea DATE, no tendrán el comportamiento predeterminado.

Formatos de tiempo

El carácter T en estos formatos es un carácter literal "T" que separa la fecha y la hora. Los formatos que solo incluyen una hora asumen que la fecha es 2001-01-01.

Modificadores

Operadores habituales

Los siguientes operadores binarios se permiten en un bloque SQL y se muestran ordenados de mayor a menor precedencia:

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

Los operadores de prefijo unarios admitidos son:

 !    ~    NOT

El operador COLLATE se puede entender como un operador de postfijo unario. El operador COLLATE tiene la precedencia mayor. Siempre se vincula con mayor fuerza que cualquier operador de prefijo unario u operador binario.

Tenga en cuenta que existen dos variaciones de los operadores de igualdad y de desigualdad. El operador de igualdad puede ser = o ==. El operador de desigualdad puede ser != o <>.

El operador || es el operador de concatenación de cadenas: une las dos cadenas y sus operandos.

El operador % genera el resto de su módulo de entre el operando izquierdo y el derecho.

El resultado de cualquier operador binario es un valor numérico, excepto el operador de concatenación ||, que produce un resultado de cadena.

Operadores SQL

LIKE

El operador LIKE lleva a cabo una comparación de coincidencia de patrones.

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

El operando a la derecha del operador LIKE contiene el patrón y el operando de la izquierda contiene la cadena que debe comparar con el patrón. Un símbolo de porcentaje (%) en el patrón es un carácter comodín: busca cada secuencia de cero o más caracteres de la cadena y la compara. Un guion bajo (_) en el patrón busca coincidencias de cualquier carácter de la cadena. Cualquier otro carácter se compara consigo mismo o con su equivalente en minúsculas/mayúsculas, es decir, se comparan las búsquedas sin distinción entre mayúsculas y minúsculas. (Nota: el motor de base de datos solo puede leer caracteres en mayúscula/minúscula Latin de 7 bits. En consecuencia, el operador LIKE distingue entre mayúsculas y minúsculas en caracteres iso8859 de 8 bits o en caracteres UTF-8. Por ejemplo, la expresión 'a' LIKE 'A' es TRUE pero 'æ' LIKE 'Æ' es FALSE). La distinción entre mayúsculas y minúsculas en caracteres Latin se puede cambiar con la propiedad SQLConnection.caseSensitiveLike.

Si la cláusula ESCAPE opcional está presente, la expresión que sigue a la palabra clave ESCAPE debe producir como resultado una cadena con un solo carácter. Este carácter se puede utilizar en el patrón LIKE para coincidir con el porcentaje literal o con los caracteres de guion bajo. El carácter de escape seguido de un símbolo de porcentaje, un guion bajo o el mismo carácter coincide con un símbolo de porcentaje literal, con un guion bajo o con un carácter de escape de la cadena, respectivamente.

GLOB

El operador GLOB es parecido a LIKE pero utiliza la sintaxis de glob de archivos Unix para los comodines. Al contrario que LIKE, GLOB sí distingue entre mayúsculas y minúsculas.

IN

El operador IN calcula si su operando izquierdo es igual a los valores de su operando derecho (un conjunto de valores entre paréntesis).

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]*

El operando derecho puede ser un conjunto de valores literales separados por comas, o el resultado de una declaración SELECT. Consulte las declaraciones SELECT de las expresiones para ver una explicación y las limitaciones de una declaración SELECT como operando derecho del operador IN.

BETWEEN...AND

El operador BETWEEN...AND equivale a utilizar dos expresiones con los operadores >= y <=. Por ejemplo, la expresión x BETWEEN y AND z es equivalente a x >= y AND x <= z.

NOT

El operador NOT es un operador de negación. Los operadores GLOB, LIKEe IN pueden ir precedidos de la palabra clave NOT para invertir el sentido de la prueba (dicho de otro modo, para comprobar que un valor no coincide con el patrón indicado).