> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Types and Metadata

> Interpret Arrow field types, semantic scalar annotations, and Parable catalog metadata.

Flight SQL returns Arrow schemas and Arrow record batches. The physical Arrow
type tells a client how to decode a value; optional Parable metadata explains
its product meaning and query characteristics.

## Temporal types

Contract-derived temporal scalars use native Arrow types:

| Semantic scalar     | Arrow type                      |
| ------------------- | ------------------------------- |
| `Temporal.Date`     | `Date32`                        |
| `Temporal.Time`     | `Time64(Microsecond)`           |
| `Temporal.DateTime` | `Timestamp(Microsecond, "UTC")` |

String-like semantic scalars remain Arrow `Utf8` and carry optional field
metadata. Tables without a contract-derived override can use the Arrow schema
provided by their underlying table provider.

## Semantic scalar metadata

When a field has a known semantic scalar, its Arrow metadata can include:

| Metadata key                      | Meaning                                                                                                                                                                                                                      |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parable.scalar.canonical_name`   | Namespaced scalar such as `Contact.Email`.                                                                                                                                                                                   |
| `parable.scalar.flat_name`        | Flattened scalar identifier.                                                                                                                                                                                                 |
| `parable.scalar.primitive`        | Underlying scalar primitive.                                                                                                                                                                                                 |
| `parable.scalar.sql_type`         | Recommended SQL type.                                                                                                                                                                                                        |
| `parable.scalar.json_schema_type` | JSON Schema primitive when defined.                                                                                                                                                                                          |
| `parable.scalar.format`           | Semantic format when defined.                                                                                                                                                                                                |
| `parable.scalar.max_length`       | Maximum length when defined.                                                                                                                                                                                                 |
| `parable.scalar.min_length`       | Minimum length when defined.                                                                                                                                                                                                 |
| `parable.scalar.pattern`          | Validation pattern when defined.                                                                                                                                                                                             |
| `parable.temporal.format`         | Declared epoch unit (`unix`, `unix_millis`, `unix_micros`, or `unix_nanos`) for a `Temporal.DateTime` field whose source encodes the instant as an epoch number, such as Slack `ts`. Present on top-level and nested fields. |

For example, columns carrying `Contact.Email` can be joined across Providers
and to `workspace.users.email` when they represent the same person.

Treat these keys as optional. An omitted key means unknown or not computed; it
does not mean an empty value, `false`, or zero.

## Table annotations

Table schemas can also describe logical identity and current annotations:

| Metadata key                         | Meaning                                                             |
| ------------------------------------ | ------------------------------------------------------------------- |
| `parable.metadata.contract_version`  | Version of the catalog metadata contract.                           |
| `parable.annotation.table_kind`      | `main`, `quarantine`, `child`, or `child_quarantine`.               |
| `parable.annotation.tap_kind`        | Source kind such as `override`, `custom`, `artifact`, or `derived`. |
| `parable.annotation.materialized`    | Whether a writer has materialized the table.                        |
| `parable.annotation.watermark`       | Completeness watermark when known.                                  |
| `parable.annotation.watermark_stale` | Whether the watermark is stale when known.                          |
| `parable.annotation.stats.row_count` | Latest annotated row count when known.                              |
| `parable.annotation.health_state`    | Current catalog health state when known.                            |
| `parable.annotation.health_reason`   | Human-readable health reason when known.                            |

Field metadata can mark internal columns with `parable.annotation.hidden` or
warn that a representation limits data skipping with
`parable.annotation.poor_pruning`.

Generic clients can ignore Parable metadata and still decode the Arrow schema.
Applications that use it should read the contract version and tolerate
additive keys.