PraxQL — Introspección de Esquema

El endpoint /schema te dice qué tablas y columnas puede ver tu API key. Es de donde sale un diccionario refs, y la única forma confiable de averiguar los nombres de columna que van en select y where.

El endpoint

GET https://gateway.praxsuite.com/{workspaceId}/schema
Authorization: Bearer sk_live_xxxxx

Sin cuerpo. Lo que vuelve lo deciden enteramente los scopes de la credencial.

Respuesta

{
  "tables": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Clientes",
      "columns": [
        { "name": "ID",       "type": "Guid",      "isKey": true  },
        { "name": "Nombre",   "type": "ShortText", "isKey": false },
        { "name": "Email",    "type": "Email",     "isKey": false },
        { "name": "Estado",   "type": "Status",    "isKey": false },
        { "name": "Pedidos",  "type": "Table",     "isKey": false, "pointsTo": "b2c3d4e5-..." }
      ]
    }
  ]
}

Tipos de columna

Dos de estos se comportan distinto de lo que parecen. Una columna `Status` devuelve un objeto al leer — { Id, Name, Color, Position } — no el nombre pelado, así que compararla contra un string en el cliente falla aunque filtrar por nombre sí funcione. Una columna `DocInstance` guarda ids de documento y devuelve el documento resuelto con su contenido.

Cómo usarlo

1. Llamá GET /schema y guardá la respuesta.

2. Armá refs con los valores id de las tablas.

3. Usá columns[].name tal cual en select, where y orderBy.

4. Para una columna Table, su GUID pointsTo es la tabla que hay que agregar a refs y nombrar en el objeto de relación.

Los nombres de columna son los que ves en el workspace, con espacios y todo. Una columna que se muestra como Player Name es "Player Name" en una consulta — no Player_Name.

Qué hace visible a una tabla

Una tabla aparece solo si se cumplen las dos cosas:

1. la credencial tiene un scope de tabla para ella, y

2. ese scope tiene AllowSchemaIntrospection = true.

Ese flag viene apagado en un scope nuevo. Una key que consulta esa tabla perfectamente va a recibir un /schema vacío hasta que alguien lo active — es el comportamiento esperado, no una falla.

Las columnas aparecen solo donde CanRead = true. Una tabla sin scopes de columna definidos muestra todas sus columnas.

Los dos ajustes están separados a propósito: podés dejar que una key consulte y escriba una tabla sin dejarla enumerar la estructura. Es el ajuste a usar para una key pk_live_ embebida en JavaScript de frontend público.

El Playground ignora AllowSchemaIntrospection y les muestra todas las tablas con scope a los admins del workspace. Es deliberado — un admin probando una consulta necesita ver contra qué está probando.

Caché

Los datos de esquema se cachean por workspace y se invalidan cuando cambia la estructura del workspace — una tabla o columna agregada, renombrada o borrada. La búsqueda no es lo que hace lenta a una consulta.

No hace falta llamar /schema antes de cada request. Traelo cuando arranca tu integración, o cuando una consulta empiece a fallar con error de columna desconocida, que es la señal de que alguien renombró algo.