> ## Documentation Index > Fetch the complete documentation index at: https://infino-29-bot-sync-openapi-spec.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Describe or change a table's schema > With `table_name` alone, return the table's columns. With `patch`, change the schema — adding, retyping, renaming, indexing or retiring a column, or creating the table when there is none — and return the schema document that results. A patch needs the `manage` capability. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/schema/{database} openapi: 3.1.0 info: title: Infino API description: >- The Infino hosted data-plane API: per-database table operations — create, ingest, search, and SQL. version: 0.1.0 servers: - url: https://api.platform.infino.ws description: Infino Cloud security: - api_key: [] tags: - name: Databases description: Create, list, and delete the databases in your account. - name: Tables description: Create, drop, and list tables, and describe a table's schema. - name: Rows description: Append, update, and delete rows. - name: Search description: BM25, vector, and hybrid search, token and exact match, count, and SQL. paths: /v1/schema/{database}: post: tags: - Tables summary: Describe or change a table's schema description: >- With `table_name` alone, return the table's columns. With `patch`, change the schema — adding, retyping, renaming, indexing or retiring a column, or creating the table when there is none — and return the schema document that results. A patch needs the `manage` capability. operationId: schema parameters: - name: database in: path description: Target database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SchemaRequest' required: true responses: '200': description: >- A describe answers the table's columns as the `[{name, type, nullable, …}]` descriptor array by default, the schema document under `encoding: "document"`, and an Arrow IPC schema message under `encoding: "ipc"`. A write answers the schema document that resulted — the patch applied, or the table created from it. content: application/json: schema: $ref: '#/components/schemas/SchemaResponse' '400': description: >- Invalid request body, an unknown `encoding`, an `encoding` sent together with `patch` (a write always answers the document), or a patch the schema refuses: a type the frozen column disagrees with, a name a live column holds, an id no live column has, a change that needs an empty table, an index the column cannot carry. The message names the remedy. '401': description: Missing or invalid API key. '403': description: >- Either the body carries `patch` and the key lacks the `manage` capability, or the account is at a storage limit: a patch creates the table when there is none, so it meets the same quota wall a row-adding write does, with the same body naming the limit. A describe is a read and is never refused for either reason. '409': description: >- `expected_schema_id` no longer matches: the schema moved. Describe again and resubmit. '503': description: >- The database's workers are still activating, or no capacity is free to place them. Transient — retry after the `Retry-After` interval. security: - api_key: [] components: schemas: SchemaRequest: type: object description: >- `POST /v1/schema/{database}`: one op, two shapes. With `table_name` alone it describes the table; with `patch` it changes the schema — or creates the table when there is none — and describes the result. The two shapes answer differently. A describe answers the `[{name, type, nullable, …}]` column-descriptor array, which is what it has always answered; `encoding` asks for the other forms. A write answers the schema document ([`SchemaDocument`]), which is what carries the `schema_id` the next compare-and-set needs. required: - table_name properties: encoding: type: - string - 'null' description: >- Response encoding of a describe. Omitted (the default) returns the `[{name, type, nullable, …}]` column-descriptor array; `"document"` returns the schema document ([`SchemaDocument`]), which adds each column's stable `id`, its index and its metadata; `"ipc"` returns an Arrow IPC schema message carrying the Arrow shape of the columns. Any other value is a 400. Only a describe takes it: sending it together with `patch` is a 400, because a write always answers the document. expected_schema_id: type: - integer - 'null' format: int32 description: |- Compare-and-set against the document's `schema_id`: the write is refused with 409 when the schema has moved. minimum: 0 patch: type: - object - 'null' description: >- The schema write, in the document's own shape: `fields` to add or change (matched by `id` when given, else by `name`; `dropped: true` retires one), `max_fields`, `max_depth`. Nothing is dropped by omission, and applying what a describe returned changes nothing. Requires the `manage` capability; a `patch` that is present and not null counts as a write, whether the body is sent as an object or as an array, which serde fills by position. table_name: type: string additionalProperties: false SchemaResponse: oneOf: - type: array items: $ref: '#/components/schemas/DescribedColumn' description: >- The default answer to a describe: the table's columns in the shape `create_table` declares them, widened to the types it cannot declare. - $ref: '#/components/schemas/SchemaDocument' description: The answer to a schema write, and to a describe that asked for it. description: >- What `POST /v1/schema/{database}` answers with, as JSON: the column descriptors by default, the [`SchemaDocument`] when a write ran or `encoding: "document"` asked for it. (`encoding: "ipc"` answers an Arrow IPC schema message, which is not JSON and is not in this union.) Untagged: the two are told apart by their JSON shape — the descriptors are an array, the document an object. DescribedColumn: type: object description: >- One column as `POST /v1/schema/{database}` describes it by default. `name`, `type` and `nullable` describe a column and a struct's own fields; a map's `key`/`value`, and a list's `item` when the element is itself nested, are types rather than fields and carry `type` and its keys alone. This is the `create_table` descriptor vocabulary widened to every type a table can hold — see `SchemaField` for which of them `create_table` accepts back. A column's stable `id`, its index and its metadata are not in this shape; ask for `encoding: "document"` to get those. required: - type properties: dim: type: - integer - 'null' format: int32 description: Element count of a `vector` or `fixed_size_list`. minimum: 0 fields: type: - array - 'null' items: $ref: '#/components/schemas/DescribedColumn' description: A struct's own fields. item: oneOf: - type: string - type: object description: The element's bare scalar spelling, or its own type keys. key: oneOf: - type: 'null' - $ref: '#/components/schemas/DescribedColumn' description: A map's key type. name: type: - string - 'null' description: |- Absent when this describes a type rather than a field — a map's `key`/`value`, or a nested list `item`. nullable: type: - boolean - 'null' description: Absent alongside `name`, for the same reason. precision: type: - integer - 'null' format: int32 description: Total digits of a decimal. minimum: 0 scale: type: - integer - 'null' format: int32 description: Digits after the point of a decimal; may be negative. type: type: string description: >- The type tag: a scalar spelling (`"i64"`, `"large_utf8"`, `"timestamp_ms"`, …), or `"vector"`, `"list"`, `"large_list"`, `"fixed_size_list"`, `"struct"`, `"map"`, `"decimal"`, `"decimal256"`. A type with no spelling at all falls back to Arrow's own display name. tz: type: - string - 'null' description: IANA time zone of a zoned timestamp. value: oneOf: - type: 'null' - $ref: '#/components/schemas/DescribedColumn' description: A map's value type. additionalProperties: false SchemaDocument: type: object description: >- The schema document: the table's definition as the engine holds it. Returned by every schema write, and by a describe that asks for `encoding: "document"`. Its `schema_id` is what the next write passes as `expected_schema_id` to make itself a compare-and-set. required: - schema_id - last_field_id - max_fields - max_depth - fields - tombstoned properties: fields: type: array items: $ref: '#/components/schemas/SchemaDocumentField' description: The live columns, in schema order. last_field_id: type: integer format: int32 description: >- The highest field id ever minted for this table, live or dropped. Ids are never reused, so this only grows. minimum: 0 max_depth: type: integer format: int32 description: How deep a document may nest before the row mapper refuses it. minimum: 0 max_fields: type: integer format: int32 description: The most live fields the table may hold. minimum: 0 schema_id: type: integer format: int32 description: |- Bumps on every committed schema change. Pass it back as `expected_schema_id` to make the next write a compare-and-set. minimum: 0 tombstoned: type: array items: type: integer format: int32 minimum: 0 description: >- Ids of columns that were dropped. Their names are free for reuse by a new column, which gets a new id. additionalProperties: false SchemaDocumentField: type: object description: >- One column of a schema document, and the nested fields inside it. The document spells types differently from the descriptor array a describe answers by default: a list's `item` is always a field object rather than a bare name, and a map carries Arrow's `entries` struct plus `keys_sorted` rather than a flattened `key`/`value` pair — so a client reading both encodings needs a parser for each. `id`, `index`, `converting_from` and `metadata` belong to a top-level column; a nested field carries `name`, `nullable` and its type keys alone. required: - name - type - nullable properties: converting_from: type: - object - 'null' description: |- The type the column is being converted *from*, as type keys. Present only while a committed type change is still being applied to the table's existing files; absent once every file carries the new type. dim: type: - integer - 'null' format: int32 description: Element count of a `vector` or `fixed_size_list`. minimum: 0 entries: oneOf: - type: 'null' - $ref: '#/components/schemas/SchemaDocumentField' description: >- A map's entry field: Arrow's two-field `{key, value}` struct, as Arrow stores it. fields: type: - array - 'null' items: $ref: '#/components/schemas/SchemaDocumentField' description: A struct's own fields. id: type: - integer - 'null' format: int32 description: >- Stable for the column's whole life, across renames — what a `patch` matches on when it changes an existing column. Every top-level column carries one; a nested field does not. minimum: 0 index: oneOf: - type: 'null' - $ref: '#/components/schemas/SchemaColumnIndex' description: The column's search index, absent when it carries none. ipc: type: - string - 'null' description: |- A base64 Arrow IPC schema message carrying the one type that has no spelling. Present only when `type` is `"arrow"`. item: oneOf: - type: 'null' - $ref: '#/components/schemas/SchemaDocumentField' description: Element field of a `list`, `large_list` or `fixed_size_list`. item_nullable: type: - boolean - 'null' description: >- Present, and `false`, only when a `vector`'s element is non-nullable — the compact spelling's elements are nullable by default. keys_sorted: type: - boolean - 'null' description: Whether a map's keys are stored sorted. metadata: type: - object - 'null' description: >- Free-form column metadata, carried through unchanged. Absent when the column has none. additionalProperties: type: string propertyNames: type: string name: type: string nullable: type: boolean precision: type: - integer - 'null' format: int32 description: Total digits of a decimal. minimum: 0 scale: type: - integer - 'null' format: int32 description: Digits after the point of a decimal; may be negative. type: type: string description: >- The type tag: a scalar spelling, `"vector"`, `"list"`, `"large_list"`, `"fixed_size_list"`, `"struct"`, `"map"`, `"decimal"`, `"decimal256"`, `"fixed_size_binary"`, or `"arrow"` for a type with no spelling, whose Arrow form rides in `ipc`. tz: type: - string - 'null' description: IANA time zone of a zoned timestamp. width: type: - integer - 'null' format: int32 description: Byte width of a `fixed_size_binary`. minimum: 0 additionalProperties: false SchemaColumnIndex: oneOf: - type: object description: |- A full-text index: what the column was tokenized under, and the BM25 constants it is scored with. required: - analyzer - positions - stored - k1 - b - kind properties: analyzer: type: string b: type: number format: float description: BM25 length normalization. k1: type: number format: float description: BM25 term-frequency saturation. kind: type: string enum: - fts positions: type: boolean description: Whether term positions are stored (what a phrase query needs). stemmer: type: - string - 'null' description: Absent when the chain does not stem. stopwords: type: - string - 'null' description: Absent when the chain removes no stopwords. stored: type: boolean description: Whether the column's text is stored in the index. - type: object description: A vector index. required: - metric - rot_seed - rerank_codec - kind properties: kind: type: string enum: - vector metric: $ref: '#/components/schemas/Metric' rerank_codec: type: string description: |- The on-disk rerank byte layout. A free-form name, not a closed set: the engine adds codecs over time. rot_seed: type: string description: |- The rotation seed, as a decimal **string**: it is a `u64` whose default sits above the 2^53 a JSON number carries exactly, so a client that reads numbers as doubles would hand back a different seed than it was given. description: The search index on a [`SchemaDocumentField`], discriminated by `kind`. Metric: type: string description: |- Vector distance metric. Accepted case-insensitively, with the aliases `l2` → `l2sq` and `dot` → `negdot`; serialized canonically. enum: - cosine - l2sq - negdot securitySchemes: api_key: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.