Elegir columnas de partición

Las columnas de partición pueden hacer que las consultas selectivas sean mucho más rápidas al permitir que Telemetry omita partes que no pueden contener los valores solicitados. Son especialmente útiles para agentes y flujos de trabajo automatizados que investigan repetidamente un cliente, servicio, entorno, seguimiento o tipo de evento en una tabla grande.

No son lo mismo que SQL PARTITION BY y no cambian los resultados de la consulta. Telemetry aplica hash a los valores configurados cuando escribe datos y registra la información de esa partición con cada parte. En el momento de la consulta, un filtro compatible se procesa de la misma manera, por lo que las partes no relacionadas se pueden excluir antes de que se lean sus datos.

Cuando usarlos

Particione una tabla cuando todo esto sea cierto:

• la tabla tiene suficientes datos o partes que escanearla es un trabajo material
• consultas importantes se filtran repetidamente en el mismo campo
• esos filtros generalmente seleccionan una pequeña fracción de la tabla
• el campo es un escalar de cadena, booleano o numérico

Los buenos candidatos incluyen account_id, workspace_id, service, environment, event y campos anidados estables como request.region.

Para un agente que investiga incidentes cuenta por cuenta, account_id suele ser una primera columna sólida:

SELECT timestamp_utc, event, message
FROM app_events
WHERE account_id = 'acct_123'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC

El predicado de tiempo todavía reduce la ventana de tiempo; el predicado de cuenta también permite que Telemetry pode las partes particionadas dentro de esa ventana.

Coloque primero la columna más útil

El orden de las columnas define una jerarquía de prefijos iniciales. Dado:

{
  "partitionColumns": ["account_id", "event"]
}

Telemetry puede utilizar la poda de partición para consultas que filtran por:

• account_id
• account_id y event

No puede utilizar este diseño para una consulta que filtra solo por event porque falta la primera columna. Elija la primera columna para el conjunto más amplio de consultas importantes y luego agregue otra solo cuando las consultas se filtren comúnmente por ambas.

Comience con una columna. Agregue un segundo solo después de que pueda describir el patrón de consulta que mejora. Las listas de columnas largas crean grupos de escritura y compactación cada vez más estrechos, mientras que las columnas posteriores ayudan a menos consultas.

Filtros que permiten la poda

Actualmente, Telemetry deriva la poda de partición a partir de predicados de igualdad literal, IN positivo y IS NULL unidos con AND:

WHERE account_id = 'acct_123'

WHERE account_id IN ('acct_123', 'acct_456')

WHERE account_id = 'acct_123'
  AND event IN ('request_failed', 'request_retried')

WHERE account_id IS NULL

Los predicados de rango, la negación y las expresiones OR ambiguas no producen poda de partición. Por ejemplo, particionar en duration_ms no ayuda a duration_ms > 1000. Las consultas siguen siendo correctas; simplemente escanean sin esa optimización.

Las rutas escalares anidadas también funcionan:

{
  "partitionColumns": ["request.region"]
}

SELECT count(*)
FROM app_events
WHERE request.region = 'us-west-2'

Las listas, los objetos y las marcas de tiempo no se admiten como columnas de partición. El filtrado de marcas de tiempo ya tiene su propia ruta de poda y generalmente se expresa mejor como un rango de tiempo de consulta.

que evitar

Evite elegir un campo simplemente porque existe en cada evento. Una columna de partición útil refleja una consulta frecuente y selectiva.

Tenga cuidado con:

• campos que casi todas las consultas ignoran
• campos consultados principalmente con rangos, LIKE o negación
• Valores que cambian rápidamente o son ilimitados cuando las consultas rara vez los repiten.
• varias columnas cuyo prefijo inicial no coincide con patrones de consulta reales

Un campo de baja cardinalidad aún puede resultar útil cuando elimina una gran parte de la tabla (por ejemplo, environment = 'production'). Un identificador de alta cardinalidad puede ser excelente para investigaciones de puntos, pero puede fragmentar las escrituras y la compactación. Prefiera el campo que elimine la mayor cantidad de datos en las consultas que realmente le interesan, no simplemente el campo con los valores más distintos.

Flujo de trabajo de implementación

1. Inspeccione las consultas realizadas por personas, paneles, alertas y agentes. Identificar el filtro de igualdad que comparten las consultas selectivas más caras.
2. Confirme el campo y escriba GET /tables/<table>/schema.
3. Configure una columna de partición a través de la interfaz de usuario de configuración de la tabla o el Tablas API.
4. Mantener los filtros de tiempo de las consultas importantes; La poda de partición complementa la poda del tiempo en lugar de reemplazarla.
5. Vuelva a ejecutar las consultas de los representantes después de que los datos existentes hayan tenido tiempo de reescribirse. Compare el trabajo escaneado y la latencia, no solo una ejecución de caché en caliente.
6. Agregue una segunda columna solo si las consultas comunes se filtran en la primera y segunda columnas juntas.

Los datos nuevos utilizan inmediatamente una especificación de partición modificada. Las partes existentes se reescriben en segundo plano y las partes no reescritas siguen siendo consultables, por lo que los resultados permanecen completos durante la migración. El rendimiento mejora progresivamente a medida que una mayor parte de la tabla adopta el nuevo diseño.

Configurar a través del API

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

Para cambiar el pedido, envíe la lista completa de deseos. Para desactivar la partición, envíe null o una matriz vacía:

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

El API valida los campos con el esquema actual de la tabla. Consulte el Referencia de tablas API para conocer el contrato de solicitud y respuesta exacto.