Guía completa ATQL — Athento Query Language

ATQL — Athento Query Language

ATQL (Athento Query Language) es un lenguaje similar a SQL para consultar documentos en Athento. Permite definir qué campos devolver, qué formularios consultar y qué condiciones aplicar para filtrar resultados, tanto por campos del documento como por campos propios del formulario.

Sintaxis general

SELECT (*|<fields>) FROM <forms> [WHERE <conditions>] [ORDER BY <fields>] [GROUP BY <fields>]

Las cláusulas SELECT y FROM son obligatorias. El resto son opcionales.

Cláusula SELECT

Indica los campos (separados por comas) que se devolverán en el resultado, o * para devolver el documento completo.

SELECT * FROM Document
SELECT uuid, filename, author FROM my_form
SELECT uuid, metadata.invoice_number FROM my_form

Cláusula FROM

Especifica la lista de formularios sobre los que se ejecutará la consulta. Usa Document para consultar todos los formularios disponibles.

SELECT * FROM Document
SELECT * FROM my_form
SELECT * FROM form_a, form_b

Campos fijos del documento

Estos campos están disponibles siempre, independientemente del formulario. También se admiten nombres con estilo CMIS (por ejemplo, ecm:uuid, dc:title, dc:created).

Campo	Aliases	Descripción
uuid	—	Identificador del documento
filename	title	Título del documento
author	—	Usuario creador del documento
creation_date	created	Fecha de creación
modified_date	modified, modification_date	Fecha de la última modificación
validation_date	validated	Fecha de validación
validator	validated_by	Usuario que validó el documento
space	serie	Espacio donde se encuentra el documento
form	doctype	Nombre del formulario del documento
life_cycle_state	—	Estado del ciclo de vida
state	—	Estado del documento
size	—	Tamaño del archivo
hash	—	Hash del documento

Campos del formulario

Para filtrar o seleccionar campos del formulario, usa el prefijo metadata.:

SELECT metadata.invoice_number FROM my_form WHERE metadata.invoice_number = '1234'
SELECT uuid, metadata.field_a, metadata.field_b FROM my_form WHERE metadata.field_a = '10'

Cláusula WHERE

Permite filtrar los resultados mediante condiciones sobre campos del documento y campos del formulario. Puedes anidar condiciones con paréntesis.

Operadores de comparación

Operador	Descripción
=	Igual
!=	Distinto
<	Menor que
<=	Menor o igual que
>	Mayor que
>=	Mayor o igual que

Operadores de patrón

Operador	Descripción
LIKE	Coincidencia parcial sensible a mayúsculas
ILIKE	Coincidencia parcial insensible a mayúsculas
~	Coincidencia mediante expresión regular

Operadores de rango y conjunto

Operador	Descripción
IN	Coincide con cualquiera de los valores de una lista
BETWEEN	Coincide con valores dentro de un rango (incluyente)
IS	Similar a =, pero también permite comparar con valores null

Operadores lógicos

Operador	Descripción
AND	Ambas condiciones deben ser verdaderas
OR	Al menos una condición debe ser verdadera
NOT	Niega la condición siguiente

Ejemplo con condiciones anidadas:

SELECT * FROM my_form
WHERE (filename = 'a.pdf' OR filename = 'b.pdf')
  AND NOT metadata.status = 'archived'

Cláusula ORDER BY

Ordena los resultados por uno o varios campos. La dirección predeterminada es ascendente (ASC).

-- Ascendente (por defecto)
SELECT uuid FROM Document ORDER BY creation_date

-- Descendente
SELECT * FROM Document ORDER BY uuid DESC

-- Múltiples campos
SELECT filename FROM my_form ORDER BY filename, uuid DESC

Funciones

ATQL incluye funciones integradas para trabajar con fechas dinámicas y con el usuario autenticado.

Funciones de fecha

Función	Parámetros	Retorna	Formato
NOW(offset)	Offset opcional	Fecha y hora actual ± offset	yyyy-MM-dd hh:mm:ss
TODAY	—	Fecha actual	yyyy-MM-dd
YESTERDAY	—	Día anterior	yyyy-MM-dd
TOMORROW	—	Día siguiente	yyyy-MM-dd

El offset de NOW combina códigos de unidad: w (semanas), d (días), h (horas), m (minutos) y s (segundos). Antepon - para restar.

Offset	Significado
1w	1 semana desde ahora
2d	2 días desde ahora
-3h	Hace 3 horas
1w2d	1 semana y 2 días desde ahora
-3h4m	Hace 3 horas y 4 minutos

Función de usuario

Función	Retorna
CURRENT_USER	Nombre del usuario autenticado actualmente

Ejemplos de uso

-- Documentos creados en la última semana
SELECT * FROM my_form WHERE creation_date > NOW(-1w)

-- Documentos creados hoy
SELECT * FROM my_form WHERE creation_date > TODAY

-- Documentos creados desde ayer
SELECT * FROM my_form WHERE creation_date > YESTERDAY

-- Documentos del usuario actual
SELECT * FROM my_form WHERE author = CURRENT_USER

-- Documentos con vencimiento entre hace 1 semana y mañana
SELECT * FROM my_form WHERE creation_date BETWEEN NOW(-1w) AND TOMORROW

-- Campos del formulario que vencen en la próxima semana
SELECT * FROM Document WHERE metadata.expiration_date BETWEEN TODAY AND NOW(1w)

GROUP BY y funciones de agregación

Usa GROUP BY para agrupar resultados e incluye una función de agregación en el SELECT.

Nota: en las consultas agrupadas, el número de resultados predeterminado es 20. Usa el parámetro page_size para obtener más.

Funciones de agregación

Función	Descripción
count(field)	Número de documentos por valor
sum(field)	Suma de los valores del campo
avg(field)	Promedio ponderado de los valores
min(field)	Valor mínimo del campo
max(field)	Valor máximo del campo
max_min(field)	Valores máximo y mínimo del campo

Ejemplos de agregación

-- Documentos por autor y espacio desde ayer
SELECT count(author), count(serie) FROM my_form
WHERE creation_date > YESTERDAY
GROUP BY author, serie

-- Valor máximo de un campo del formulario
SELECT max(metadata.total_invoice) FROM Document
GROUP BY metadata.total_invoice

-- Máximo y mínimo de un campo del formulario
SELECT max_min(metadata.total_invoice) FROM Document
GROUP BY metadata.total_invoice

JOIN y EXCLUDE JOIN

ATQL permite combinar documentos a partir de formularios relacionados.

-- Incluir documentos relacionados mediante join
SELECT * FROM form_a JOIN form_b ON ...

-- Excluir documentos que coinciden con la condición de join
SELECT * FROM form_a EXCLUDE JOIN form_b ON ...

Ejemplos completos

-- Todos los documentos de un formulario
SELECT * FROM Document

-- Filtro por filename con OR
SELECT uuid, filename FROM Document
WHERE filename = 'Athento1.pdf' OR filename = 'Athento2.pdf'

-- Booleano complejo con campos del formulario
SELECT uuid, filename FROM MyForm
WHERE (filename = 'Athento1.pdf' OR filename = 'Athento2.pdf')
  AND (metadata.contract_number = '123456'
       AND NOT metadata.city IN ('Málaga', 'Madrid'))
ORDER BY uuid DESC

-- Rango de fechas
SELECT uuid, creation_date FROM my_form
WHERE (creation_date BETWEEN '2022-01-01' AND '2022-12-31'
       OR modified_date > '2022-12-01')
  AND NOT state = 'pending'
ORDER BY creation_date

-- Comprobación de null en campos del formulario
SELECT uuid, filename FROM my_form
WHERE metadata.my_metadata IS NULL

-- Selección de campos del formulario con filtros múltiples
SELECT uuid, metadata.field_a, metadata.field_b FROM my_form
WHERE NOT metadata.field_a = '10'
  AND (metadata.field_b = '20' OR filename = 'PDF-Athento.pdf')

-- Filtro por estado del ciclo de vida
SELECT * FROM Document WHERE life_cycle_state = 'Iniciado' ORDER BY uuid DESC

Tipos de error

Error	Cuándo ocurre
ATQLSyntaxError	Cuando la consulta tiene una sintaxis no válida
ATQLException	Error general al procesar una consulta ATQL
UnsupportedATQLError	Cuando la consulta utiliza una funcionalidad que aún no está soportada