Types and 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.

​Temporal types

​Semantic scalar metadata

​Table annotations

Temporal types

Semantic scalar metadata

Table annotations