Utilizando DQL y DataNinja API
Cómo usar DQL y la API para extraer grandes cantidades de datos
English: Read this page in English.
Français : Consultez cette page en français.
Use DataNinja Query Language (DQL), la pestaña "Explorer" de la página API y la API de DataNinja para consultar registros, confirmar los campos disponibles, crear filtros de Grid Configuration y dar soporte a integraciones.
DQL le permite consultar la información almacenada en DataNinja. La API permite a los usuarios técnicos y a los desarrolladores de integraciones interactuar con los datos de DataNinja mediante endpoints de API.
Usos recomendadosEstas herramientas son útiles cuando necesita:
- Extraer grandes cantidades de datos de DataNinja
- Dar soporte a informes personalizados
- Revisar los campos disponibles de un objeto
- Probar filtros antes de usarlos en informes o Grid Configurations
- Dar soporte a integraciones con sistemas externos
- Entender mejor cómo están estructurados los objetos y campos de DataNinja
Descripción general de DQL y la API
DQL y la pestaña "Explorer" se encuentran en la página API de su sitio de DataNinja. La pestaña "Explorer" enumera los objetos de la base de datos de DataNinja y sus campos, y las consultas DQL usan esos objetos y campos para devolver datos de solo lectura. La API de DataNinja y Postman están fuera de su sitio de DataNinja, pero funcionan juntos para permitirle hacer cambios en datos en vivo o extraer datos de solo lectura.
| Herramienta | Propósito | Uso común |
|---|---|---|
| DataNinja Query Language (DQL) | Permite a los usuarios consultar datos de DataNinja con una sintaxis similar a SQL | Revisar registros, probar filtros, crear informes, confirmar valores de campos |
| Pestaña Explorer | Permite a los usuarios revisar los objetos, campos y relaciones disponibles en DataNinja | Identificar nombres de campos para DQL, Grid Configurations, informes o integraciones |
| API de DataNinja | Permite a los usuarios técnicos interactuar con los datos de DataNinja mediante endpoints de API | Crear, actualizar, obtener o integrar registros con sistemas externos |
| Token de API | Permite que una integración o herramienta se conecte a DataNinja como usted | Conectar Power BI, Excel, Google Sheets, scripts u otras integraciones |
| Documentación de la API en Postman | Ofrece documentación y ejemplos de los endpoints de la API | Revisar llamadas a la API, buscar partes, revisar niveles de inventario y dar soporte a integraciones |
DataNinja Query Language (DQL)
DataNinja Query Language (DQL) es un lenguaje de consulta similar a SQL para los datos de una aplicación de DataNinja. Use DQL para revisar registros, probar filtros, crear informes y confirmar valores de campos. Use la notación de puntos en las cláusulas SELECT y WHERE para navegar por las relaciones. DataNinja crea automáticamente las uniones (joins) necesarias de forma interna.
DQL admite:
- Where
- Group by
- Having
- Order by
- Limit
- Offset
Los nombres de objetos y campos no distinguen mayúsculas de minúsculas, así que part.partNumber y PART.PARTNUMBER devuelven el mismo campo.
DQL lo usan con frecuencia los equipos de implementación, los administradores, los equipos de soporte y los usuarios técnicos que necesitan consultar datos de DataNinja o confirmar cómo está estructurada la información en el sistema.
Acceder a la página API
Puede ejecutar DQL desde la página API de DataNinja. Haga clic en el icono de engranaje en la esquina superior derecha, vaya a "All Lists" y haga clic en "API". La página API tiene cinco pestañas: "DQL", "Explorer", "Examples", "Setup" y "Custom Fields". Escriba y ejecute las consultas en la "Query Window" de la pestaña "DQL".

Usar la pestaña Explorer
Para explorar los objetos que puede consultar con DQL, abra la pestaña "Explorer" en la parte superior de la página API.
La pestaña "Explorer" le permite revisar los objetos y campos disponibles en DataNinja. Úsela para confirmar el nombre correcto de un campo o para copiarlo directamente en una consulta.

Si un objeto muestra un círculo verde "CF", se pueden crear campos personalizados en él. Consulte Campos personalizados para obtener más información.

Las consultas se pueden generar automáticamente marcando la casilla junto a los campos que necesita de un objeto y haciendo clic en "Copy". Solo se puede copiar un objeto a la vez, y copiar desde un objeto nuevo sobrescribe la consulta anterior.

Si un campo de un objeto tiene "Foreign Key" al lado, ese campo se conecta con otro objeto. Haga clic en "Foreign Key" para ir al objeto conectado.

La pestaña "Explorer" puede ayudarle a entender:
| Qué revisar | Por qué es importante |
|---|---|
| Objetos | Ayuda a identificar el tipo de registro de DataNinja que se consulta |
| Campos | Confirma los nombres exactos de los campos disponibles para filtrar o para informes |
| Objetos relacionados | Ayuda a identificar campos que pueden estar disponibles mediante la notación de puntos |
| Estructura de datos | Ayuda a los usuarios a entender cómo se conectan los registros |
| Valores de campos | Ayuda a los usuarios a confirmar valores que pueden usarse en filtros, como el estado, el tipo o la categoría |
Ejemplos básicos de DQL
Estos ejemplos son solo de referencia. Confirme los nombres correctos de objetos, campos y valores en su propio sitio de DataNinja con la pestaña "Explorer". En la tabla siguiente, reemplace [fields] por los campos (columnas) que quiere ver en los resultados.
| Objetivo | Ejemplo de DQL |
|---|---|
| Devolver registros válidos | SELECT [fields] FROM part WHERE isvalid=true |
| Devolver registros con un estado específico | SELECT [fields] FROM manufacturedbatch WHERE lifecycleid=2 |
| Devolver un número limitado de registros | SELECT [fields] FROM part LIMIT 100 |
| Ordenar registros por nombre | SELECT [fields] FROM part WHERE isvalid=true ORDER BY name |
Volumen de resultadosSi su consulta DQL genera un gran volumen de resultados, el rendimiento de su sitio de DataNinja puede disminuir; las páginas pueden cargar más lento o pueden aparecer mensajes de "Internal Server Error". Para evitarlo, filtre su búsqueda tanto como sea posible o use LIMIT para controlar el número de resultados que aparecen en la página.
Usar la notación de puntos para objetos relacionados
DQL admite la notación de puntos para hacer referencia a campos de objetos relacionados. Esto le permite filtrar o seleccionar información de registros relacionados sin crear uniones manualmente.
SELECT id, identifier, lifecycleId, partId, partNumber, part.defaultLocationId
FROM batch
LIMIT 100En este ejemplo, part.defaultLocationId hace referencia al campo defaultLocationId del objeto relacionado part.
Los objetos y campos relacionados disponibles dependen del objeto que se consulta. Use la pestaña "Explorer" para confirmar qué relaciones están disponibles.
Una ruta con puntos puede llegar hasta 3 relaciones de profundidad. Por ejemplo, part.partNumber en un lote tiene 1 relación de profundidad. Si una ruta va más allá, o uno de sus pasos no es una relación de ese objeto, la consulta se detiene con un error que indica la ruta, para que pueda acortarla o corregir el paso.
Devolver registros relacionados con subconsultas
Para devolver un registro junto con una lista de sus registros relacionados, como una orden de venta y sus líneas, coloque una subconsulta entre paréntesis dentro del SELECT. El FROM de la subconsulta es el nombre de una colección del objeto principal, y puede tener sus propios WHERE, ORDER BY y LIMIT.
SELECT Id,
(
SELECT Id, Quantity, Part.Name AS PartName
FROM Lines
WHERE IsDeleted = false
ORDER BY LineNumber DESC
LIMIT 100
) AS Lines
FROM SalesOrderCada orden de venta se devuelve una sola vez, con sus líneas en una lista que lleva el nombre del alias (Lines). Un registro sin filas relacionadas devuelve una lista vacía, y cada lista incluye el total de filas secundarias que coinciden, aunque el LIMIT acorte la lista.
- Una consulta puede tener hasta 5 subconsultas.
- El
LIMITde una subconsulta se aplica a cada registro principal. Es de 100 filas si lo omite, y puede ser como máximo 250. - Los
WHERE,ORDER BY,LIMITyOFFSETde la consulta principal se aplican solo a los registros principales.
Conectar una integración con un token de API
Las integraciones y herramientas como Power BI, Excel, Google Sheets o sus propios scripts usan un token de API para conectarse a DataNinja. Usted crea y administra sus propios tokens en su perfil de usuario.
- Haga clic en el icono de engranaje en la esquina superior derecha y luego en "User Profile".
- Abra la pestaña "API tokens". También puede llegar desde la pestaña "Setup" de la página API haciendo clic en "Go to API Tokens".
- Haga clic en "Create token" y asigne al token un nombre que coincida con la aplicación que conecta, como "Power BI sync", para encontrarlo fácilmente después.
- Copie el token de inmediato. Solo se muestra al crearlo, así que guárdelo en un lugar seguro, como un administrador de contraseñas.

Su integración envía el token en el encabezado ApiToken de cada solicitud a la API de DataNinja. Para leer datos con DQL, envíe una solicitud GET a la dirección /api/dql/query de su sitio de DataNinja con su consulta en el parámetro dql:
GET https://<your site>.dataninja.com/api/dql/query?dql=SELECT Id, Name FROM Part LIMIT 10
ApiToken: <your token>Lo que debe saber sobre los tokens:
- Un token actúa como usted, con sus roles y permisos, y todo lo que hace queda registrado a su nombre.
- Cada token caduca un año después de crearse. La pestaña "API tokens" muestra la fecha de caducidad de cada token.
- Puede tener hasta 10 tokens activos, y cada uno necesita un nombre único.
- Puede revocar un token en la pestaña "API tokens" en cualquier momento. Primero se le pide confirmar; luego deja de funcionar de inmediato, y sus demás tokens siguen funcionando.
- Los usuarios con el rol Contractor no pueden crear tokens. Desactivar o eliminar a un usuario, o cambiarlo al rol Contractor, revoca todos sus tokens.
Integraciones que iniciaban sesión con usuario y contraseñaLas integraciones anteriores obtenían su token enviando un nombre de usuario y una contraseña a DataNinja. Eso ya no devuelve un token. Si una integración deja de conectarse, cree un token en la pestaña "API tokens" y agréguelo a la integración.
Trate los tokens como contraseñasCualquier persona que tenga su token puede leer y cambiar sus datos de DataNinja con sus permisos. No lo comparta, y revóquelo en cuanto una integración ya no lo necesite.
Usar la API de DataNinja
DataNinja usa Postman para documentar la API e interactuar con ella. La documentación de la API de DataNinja incluye ejemplos e instrucciones para actividades relacionadas con la API, como:
- Revisar los endpoints disponibles
- Enviar datos a DataNinja
- Obtener datos de DataNinja
- Dar soporte a integraciones con sistemas externos
Consulte la documentación de la API de DataNinja.
Prácticas recomendadas
- Use la pestaña "Explorer" para confirmar los nombres de objetos y campos antes de escribir consultas
- Empiece con una consulta sencilla y agregue filtros poco a poco
- Use filtros y límites al consultar grandes conjuntos de datos
- Confirme los valores exactos de los campos antes de filtrar por estado, tipo, categoría o ubicación
- Seleccione campos específicos en lugar de
SELECT *cuando solo necesite cierta información - Pruebe los resultados de una consulta antes de usar la misma lógica en un informe, una integración o una Grid Configuration
- Evite las consultas demasiado amplias, sobre todo con grandes conjuntos de datos
DQL frente a API
| Necesidad | Herramienta recomendada |
|---|---|
| Revisar o consultar registros de DataNinja | DQL |
| Probar la lógica de un filtro | DQL |
| Identificar los objetos y campos disponibles | Pestaña "Explorer" |
| Crear o dar soporte a Grid Configurations | Pestaña "Explorer" y DQL |
| Crear, actualizar u obtener registros mediante una integración | API, con un token de API |
| Revisar la documentación de los endpoints de la API | Documentación de la API en Postman |
Solución de problemas
| Problema | Causa posible | Acción sugerida |
|---|---|---|
| La consulta no devuelve los resultados esperados | El nombre del campo o del objeto puede ser incorrecto | Confirme el nombre del campo o del objeto en la pestaña "Explorer" |
| La consulta devuelve demasiados registros | El filtro puede ser demasiado amplio | Agregue más condiciones o use LIMIT |
| La consulta no devuelve registros | El filtro puede ser demasiado restrictivo o el valor puede no coincidir exactamente | Quite una condición a la vez y vuelva a probar |
| Un campo relacionado no funciona | La notación de puntos puede no coincidir con una relación disponible, o la ruta tiene más de 3 relaciones de profundidad | Revise los objetos relacionados en la pestaña "Explorer" y acorte la ruta |
| Una subconsulta devuelve un error | El LIMIT de la subconsulta es mayor que 250, o la consulta tiene más de 5 subconsultas | Reduzca el LIMIT o divida la consulta |
| El usuario no puede acceder a los datos esperados | El acceso del rol o de los permisos puede estar limitado | Revise los permisos del usuario en DataNinja |
| "Create token" no está disponible, o falta la pestaña "API tokens" | El usuario tiene el rol Contractor | Pregunte a su administrador si otro rol es más adecuado |
| "You already have the maximum of 10 active API tokens." | Tiene 10 tokens activos | Revoque un token que ya no use en la pestaña "API tokens" |
| Una integración recibe "401 Unauthorized" | Falta el encabezado ApiToken, o el token se revocó o caducó | Cree un token nuevo y actualice la integración |
Updated 7 days ago
