PraxQL — El Playground

El Playground es una consola de consultas dentro del portal. Escribís un cuerpo PraxQL, apretás Ejecutar, y ves volver las filas — sin escribir una línea de código cliente, sin emitir una key y sin salir del navegador.

Es la forma más rápida de responder las tres preguntas con las que arranca toda integración: qué tablas ve esta key, mi consulta parsea, y devuelve lo que espero.

Lo encontrás en API Gateway → Playground.

Anatomía

Cinco regiones, de arriba abajo y de izquierda a derecha.

La barra del endpoint. La URL exacta a la que tu app va a hacer POST — https://gateway.praxsuite.com/{workspaceId}/query. No es decoración: es el mismo endpoint que usa el Playground, y el botón de copiar al lado es cómo pasás de experimentar a integrar. En un despliegue dedicado el host cambia, y por eso conviene copiarla de acá en vez de escribirla.

El selector de credencial. Todas las keys activas del workspace, con su nombre y su prefijo. Esta elección es el punto entero del Playground — ver la sección siguiente.

Plantillas y Reiniciar. Cinco puntos de partida armados con tu esquema real: Simple Select, With Filters, Nested Relations, Aggregation, Insert Row. Reiniciar devuelve el editor a un esqueleto vacío.

El panel de esquema. Todas las tablas que alcanza la credencial seleccionada, con su cantidad de columnas. Expandí una y aparecen las columnas con su tipo de dato y cuál es la clave.

El editor y los resultados. Entra JSON, salen filas. El editor valida mientras escribís — la franja de abajo dice Valid JSON o nombra el error de sintaxis. Ctrl + Enter ejecuta.

Cómo llega el Playground a tus tablas

Esta es la parte que conviene entender bien, porque explica a la vez qué demuestra el Playground y qué no.

El Playground no se autentica con una API key. Es una pantalla del portal, así que corre con tu propio login, y exige permiso de lectura sobre la funcionalidad API Gateway más permiso para leer credenciales. Alguien que no ve la sección API Gateway no puede abrirlo.

Ejecuta como la credencial que elegiste. Cuando apretás Ejecutar, el servidor carga los scopes de tabla de esa credencial y corre tu consulta por el mismo parser y el mismo ejecutor que una llamada real del gateway. Aplican todas las capas: scopes de tabla, permisos de columna, row filters, reglas de enmascarado, y los propios límites de filas y profundidad del scope.

Así que el Playground responde una pregunta concreta y útil: "¿qué obtendría esta key?" Cambiá el selector a otra key, corré la misma consulta, y la diferencia en los resultados es la diferencia entre sus permisos. Es la forma más barata que existe de verificar un scope antes de publicarlo.

   tu login del portal  ──▶  Playground  ──▶  corre como: la credencial elegida
                                                │
                                                │  mismos scopes, mismos filtros,
                                                │  mismo enmascarado, mismos límites
                                                ▼
                                          los datos de tu workspace

Las cuatro diferencias con una llamada real

Todas son deliberadas, y todas le pasaron factura a alguien.

1. El panel de esquema muestra más de lo que mostraría `/schema`. Para administradores del workspace el Playground ignora el flag AllowSchemaIntrospection y lista todas las tablas con scope, porque un admin probando una consulta necesita ver contra qué prueba. Tu app llamando GET /schema con la misma key puede recibir una lista vacía — ese flag viene apagado en un scope nuevo. Que una tabla se vea acá no prueba que tu integración pueda enumerarla.

2. Nada llega a la pestaña Logs. Las corridas del Playground no se escriben en el log de consultas y no cuentan contra tu cuota de API. Es cómodo, y también es la trampa: si estás depurando mirando Logs, una corrida del Playground nunca va a aparecer ahí. Para generar una entrada tenés que llamar al endpoint de verdad.

3. Las mutaciones son escrituras reales. No hay sandbox ni simulacro. Un insert inserta, un delete borra. La plantilla Insert Row existe para mostrar la forma, no para correrla contra una tabla que te importe.

4. `{{claim:sub}}` se resuelve a *vos*. En una llamada real, los marcadores de claims y las plantillas de valor por defecto se resuelven desde el token del usuario final. En el Playground no hay usuario final, así que la plataforma sustituye tu propio id de usuario del portal — que es lo que mantiene honesto a CREATEDBY, pero significa que un row filter por usuario basado en sub no se va a comportar como en producción. Eso probalo contra una sesión real de usuario final.

Armar una consulta sin escribir GUIDs

El panel de esquema no es solo una referencia; escribe en el editor.

• Pasá el mouse sobre una tabla y aparece un rayito. Al hacerle clic, el GUID de la tabla se agrega a refs, y queda como from si from estaba vacío.

• Hacé clic en una columna y su nombre se agrega a select.

• El número de cada tabla es su cantidad de columnas; el ícono y la etiqueta a la derecha de cada columna son su tipo de dato.

Las dos acciones editan el JSON en el lugar, así que necesitan que el editor tenga JSON válido — arreglá el error de sintaxis primero o la inserción se rechaza con un aviso.

Un detalle que conviene saber. El botón del rayito usa el nombre de la tabla como alias, y un alias tiene que empezar con letra o guion bajo y contener solo letras, dígitos y guiones bajos. Para una tabla cuyo nombre tiene un espacio — CRM Products — la clave generada en refs se rechaza con 400 INVALID_REFS. Renombrá el alias a algo como Products (y actualizá from para que coincida) y corre. El GUID que insertó sigue siendo el correcto.

Una corrida, de punta a punta

{
  "refs": {
    "Clientes": "1f60b6bd-eb33-4c55-bc3a-d7fbc127e717"
  },
  "query": {
    "from": "Clientes",
    "select": ["Nombre", "Email", "Teléfono"],
    "orderBy": [{ "field": "Nombre", "dir": "asc" }],
    "limit": 25
  },
  "includeTotalCount": true
}

El encabezado sobre los resultados es el bloque meta, y conviene leerlo en vez de saltearlo:

La brecha entre esos dos últimos números es la útil: una consulta que ejecuta en 2 ms dentro de un viaje de 171 ms no es una consulta que necesites optimizar.

Si te vuelven menos filas de las que pediste, es el scope hablando. Un scope de tabla nuevo limita a 200 filas y las relaciones a profundidad 2, bastante por debajo de los topes de plataforma de 1.000 y 5. El límite efectivo siempre está en meta.limit.

Cambiá los resultados a JSON para ver exactamente el payload que va a parsear tu app — incluida la forma de las columnas Status, que vuelven como objeto y no como nombre pelado.

Del Playground a tu código

El cuerpo que acabás de correr es el cuerpo que mandás. No hay nada que traducir:

curl -X POST https://gateway.praxsuite.com/{workspaceId}/query \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"refs":{"Clientes":"..."},"query":{"from":"Clientes","limit":25}}'

Copiá la URL de la barra del endpoint, copiá la consulta con el botón sobre el editor, y usá una key con los mismos scopes que la credencial que elegiste. Si funcionó acá, funciona allá — teniendo en cuenta las cuatro diferencias de arriba.

Cuándo el Playground es la herramienta equivocada

• Pruebas de carga. Acá las corridas no se miden, así que nada de lo que midas refleja cuota ni rate limits.

• Cualquier cosa que dependa de la identidad de un usuario final. No hay usuario final logueado, así que los filtros con valueFromClaim y los valores {{claim:…}} no se resuelven como lo harán en producción.

• Verificar que una key no puede introspeccionar. El panel muestra de más a propósito. Revisá AllowSchemaIntrospection en el scope.

Para todo lo demás — probar un scope, darle forma a una consulta, ver qué devuelve realmente un filtro — es el primer lugar al que ir.

Siguiente

• Introducción a PraxQL — el formato de request que espera el editor.

• Modelo de Seguridad — las capas por las que el Playground está pasando tu consulta.