Guides
GuidesLog In
Guides

Utilizando DQL y DataNinja API

Cómo usar DQL y la API para extraer grandes cantidades de datos

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 recomendados

Estas 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.

HerramientaPropósitoUso común
DataNinja Query Language (DQL)Permite a los usuarios consultar datos de DataNinja con una sintaxis similar a SQLRevisar registros, probar filtros, crear informes, confirmar valores de campos
Pestaña ExplorerPermite a los usuarios revisar los objetos, campos y relaciones disponibles en DataNinjaIdentificar nombres de campos para DQL, Grid Configurations, informes o integraciones
API de DataNinjaPermite a los usuarios técnicos interactuar con los datos de DataNinja mediante endpoints de APICrear, actualizar, obtener o integrar registros con sistemas externos
Token de APIPermite que una integración o herramienta se conecte a DataNinja como ustedConectar Power BI, Excel, Google Sheets, scripts u otras integraciones
Documentación de la API en PostmanOfrece documentación y ejemplos de los endpoints de la APIRevisar 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".

Página API en la pestaña DQL con la sintaxis de DQL y ejemplos

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.

Pestaña Explorer con la lista de objetos y las insignias CF

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.

Objeto Address en la pestaña Explorer con su pestaña Custom Fields abierta

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.

Campos seleccionados y botón Copy en el objeto Batch de la pestaña Explorer

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.

Enlace Foreign Key en un campo de tabla del API Explorer

La pestaña "Explorer" puede ayudarle a entender:

Qué revisarPor qué es importante
ObjetosAyuda a identificar el tipo de registro de DataNinja que se consulta
CamposConfirma los nombres exactos de los campos disponibles para filtrar o para informes
Objetos relacionadosAyuda a identificar campos que pueden estar disponibles mediante la notación de puntos
Estructura de datosAyuda a los usuarios a entender cómo se conectan los registros
Valores de camposAyuda 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.

ObjetivoEjemplo de DQL
Devolver registros válidosSELECT [fields] FROM part WHERE isvalid=true
Devolver registros con un estado específicoSELECT [fields] FROM manufacturedbatch WHERE lifecycleid=2
Devolver un número limitado de registrosSELECT [fields] FROM part LIMIT 100
Ordenar registros por nombreSELECT [fields] FROM part WHERE isvalid=true ORDER BY name
❗️

Volumen de resultados

Si 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 100

En 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 SalesOrder

Cada 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 LIMIT de 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, LIMIT y OFFSET de 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.

  1. Haga clic en el icono de engranaje en la esquina superior derecha y luego en "User Profile".
  2. 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".
  3. 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.
  4. Copie el token de inmediato. Solo se muestra al crearlo, así que guárdelo en un lugar seguro, como un administrador de contraseñas.
Pestaña API tokens del perfil de usuario con el botón Create token

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ña

Las 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ñas

Cualquier 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

NecesidadHerramienta recomendada
Revisar o consultar registros de DataNinjaDQL
Probar la lógica de un filtroDQL
Identificar los objetos y campos disponiblesPestaña "Explorer"
Crear o dar soporte a Grid ConfigurationsPestaña "Explorer" y DQL
Crear, actualizar u obtener registros mediante una integraciónAPI, con un token de API
Revisar la documentación de los endpoints de la APIDocumentación de la API en Postman

Solución de problemas

ProblemaCausa posibleAcción sugerida
La consulta no devuelve los resultados esperadosEl nombre del campo o del objeto puede ser incorrectoConfirme el nombre del campo o del objeto en la pestaña "Explorer"
La consulta devuelve demasiados registrosEl filtro puede ser demasiado amplioAgregue más condiciones o use LIMIT
La consulta no devuelve registrosEl filtro puede ser demasiado restrictivo o el valor puede no coincidir exactamenteQuite una condición a la vez y vuelva a probar
Un campo relacionado no funcionaLa notación de puntos puede no coincidir con una relación disponible, o la ruta tiene más de 3 relaciones de profundidadRevise los objetos relacionados en la pestaña "Explorer" y acorte la ruta
Una subconsulta devuelve un errorEl LIMIT de la subconsulta es mayor que 250, o la consulta tiene más de 5 subconsultasReduzca el LIMIT o divida la consulta
El usuario no puede acceder a los datos esperadosEl acceso del rol o de los permisos puede estar limitadoRevise los permisos del usuario en DataNinja
"Create token" no está disponible, o falta la pestaña "API tokens"El usuario tiene el rol ContractorPregunte a su administrador si otro rol es más adecuado
"You already have the maximum of 10 active API tokens."Tiene 10 tokens activosRevoque 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