Tablas

Tables API le permite inspeccionar y administrar tablas mediante programación.

Operaciones soportadas:

• Tablas de lista. GET https://api.telemetry.sh/tables
• Obtener esquema. GET https://api.telemetry.sh/tables/<table>/schema
• Establecer retención. PATCH https://api.telemetry.sh/tables/<table>/retention
• Establecer columnas de partición. PATCH https://api.telemetry.sh/tables/<table>/partition-columns
• Eliminar tabla. DELETE https://api.telemetry.sh/tables/<table>

Encabezados

Reglas de alcance:

• GET /tables y GET /tables/<table>/schema requieren read, write o read-and-write.
• PATCH /tables/<table>/retention, PATCH /tables/<table>/partition-columns y DELETE /tables/<table> requieren write o read-and-write

Contrato de ruta de tabla

El segmento de ruta <table> es normalizado por API antes del reenvío:

• los espacios se convierten en guiones bajos
• las letras estan en minusculas
• Después de la normalización, solo se permiten letras ASCII minúsculas, números y _.

Ejemplos:

• Uber Rides se convierte en uber_rides
• graphjson_egress se queda graphjson_egress
• my-table se rechaza porque - no está permitido

Utilice nombres de tablas canónicas que contengan únicamente letras minúsculas, números y guiones bajos si desea un comportamiento predecible.

Listar tablas

OBTENER https://api.telemetry.sh/tables

Parámetros de consulta admitidos:

Las solicitudes exitosas devuelven 200 OK:

{
  "status": "success",
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 3,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "tables": [
    "heartbeat",
    "telemetry_user_events",
    "graphjson_egress"
  ]
}

Ejemplo

curl "https://api.telemetry.sh/tables?page=1&pageSize=25" \
  -H "Authorization: $API_KEY"

Obtener esquema de tabla

OBTENER https://api.telemetry.sh/tables/<table>/schema

Esto devuelve:

• el objeto de esquema analizado para la tabla
• la política de retención actual, si la hubiera
• metadatos de partición, si los hay

Las solicitudes exitosas devuelven 200 OK:

{
  "status": "success",
  "table": "graphjson_egress",
  "schema": {
    "fields": [
      {
        "name": "timestamp_utc",
        "data_type": {
          "Timestamp": ["Millisecond", "UTC"]
        },
        "nullable": true,
        "dict_id": 0,
        "dict_is_ordered": false,
        "metadata": {}
      }
    ],
    "metadata": {}
  },
  "retention_days": null,
  "partition_columns": null,
  "partition_spec_version": null
}

Ejemplo

curl https://api.telemetry.sh/tables/graphjson_egress/schema \
  -H "Authorization: $API_KEY"

Establecer retención de tabla

PARCHE https://api.telemetry.sh/tables/<table>/retention

Cuerpo

Notas:

• Se rechazan los valores inferiores a 1.
• Si envía {} o {"retentionDays": null}, se elimina la retención.

Las solicitudes exitosas devuelven 200 OK:

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": null,
  "partition_spec_version": null
}

Ejemplo

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": 30
  }'

Retención clara

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": null
  }'

Establecer columnas de partición

PARCHE https://api.telemetry.sh/tables/<table>/partition-columns

Las columnas de partición organizan las partes de una tabla para que los filtros de igualdad puedan omitir datos no relacionados antes de que una consulta los lea. El orden importa: coloque primero el campo utilizado por la mayoría de las consultas. Consulte Elegir columnas de partición para obtener consejos de selección y ejemplos de consultas.

La tabla ya debe tener un esquema. Puede utilizar campos escalares anidados o de nivel superior, como account_id o request.region. Se admiten campos de cadena, booleanos y numéricos.

Cuerpo

La solicitud se rechaza si un campo no existe en el esquema actual, tiene un tipo no admitido, está duplicado, está vacío o contiene un segmento de ruta anidada vacío.

Cambiar las columnas crea una nueva especificación de partición. Los nuevos datos ingeridos los utilizan inmediatamente, mientras que las partes existentes se reescriben en segundo plano. Las consultas permanecen completas durante esa transición, pero el beneficio total del rendimiento llega a medida que avanza la reescritura.

Las solicitudes exitosas devuelven 200 OK con la configuración efectiva:

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": ["account_id", "event"],
  "partition_spec_version": 2
}

Ejemplo

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": ["account_id", "event"]
  }'

Deshabilitar la partición

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": null
  }'

Eliminar tabla

BORRAR https://api.telemetry.sh/tables/<table>

Esto elimina permanentemente la tabla y todos sus datos.

Las solicitudes exitosas devuelven 200 OK:

{
  "status": "success",
  "deleted_table": {
    "name": "graphjson_egress"
  }
}

Ejemplo

curl -X DELETE https://api.telemetry.sh/tables/graphjson_egress \
  -H "Authorization: $API_KEY"

Punto final relacionado

Telemetry también sigue admitiendo el punto final heredado DELETE /delete para eliminar filas con una cláusula where. Utilice las tablas API cuando desee operaciones del ciclo de vida de toda la tabla.

Errores comunes

• 400 Bad Request si el nombre de la tabla contiene caracteres no válidos después de la normalización
• 400 Bad Request si retentionDays no es un entero positivo o null
• 400 Bad Request si una columna de partición no es válida o no es un campo admitido en el esquema actual
• 403 Forbidden si la clave API no tiene permiso para la operación solicitada
• 401 Unauthorized si la clave API falta o no es válida
• 404 Not Found si la tabla no existe