Event Data Types and Nullability
Telemetry infers a table schema from structured events. Flexible ingestion removes an up-front migration step, but useful SQL still depends on stable field meanings and types.
Choose a durable type
Use strings for identifiers and controlled categories, numbers for values that will be calculated, booleans for true two-state facts, and timestamps for moments in time.
| Value | Recommended field |
|---|---|
| Duration | Numeric duration_ms |
| Money | Numeric normalized amount plus source currency |
| Identifier | String, even when it contains only digits |
| Outcome | Controlled string such as success, failed, or timeout |
| Feature flag | Boolean when there are exactly two meanings |
| Event time | Timezone-qualified input normalized to timestamp_utc |
Do not send "842" for a duration in one deployment and 842 in another. Do not reuse status for an HTTP code in one service and a workflow category in another.
Understand missing values
The Log API removes null values, empty objects, and empty arrays during normalization. A missing field therefore means no value was stored on that row; it does not mean zero, false, an empty string, or unknown.
Use IS NULL when absence is analytically meaningful. Use COALESCE only when the replacement has a defensible business meaning:
SELECT
event_name,
100.0 * SUM(CASE WHEN account_id IS NULL THEN 1 ELSE 0 END)
/ NULLIF(COUNT(*), 0) AS missing_account_rate_pct
FROM product_events
GROUP BY event_name;
The required-field null-rate recipe adds volume safeguards and producer-version context.
Evolve without changing meaning
Adding a nullable field is usually compatible. Changing a field type or redefining an existing category is not. When a meaning changes, introduce a new field or schema_version and migrate queries deliberately.
Nested objects become queryable dotted fields. Keep each nested path stable and avoid arrays whose element structure changes between events.
Review schema evolution, event schema design, and querying nested JSON before expanding a production contract.