---
title: "Declare a metadata column"
method: POST
path: "/metadata_columns"
tags: ["metadata-columns"]
---

# Declare a metadata column

`POST /metadata_columns`

(reserved for future use) Declares a metadata column to be materialized as a typed LanceDB column with a scalar index at the next ingestion. The key must be a column-safe identifier and the type must be "string" or "integer".

Required roles: All

## Request body

- CreateMetadataColumnRequest
  - `key` string, required
  - `type` 'string' | 'integer', required
  - `filter_only` boolean
  - `index_type` 'btree' | 'bitmap' — Scalar index type. Omit to use the type default (integer -> btree, string -> bitmap).

## Response `201`

Column declared

- MetadataColumn — A declared metadata column materialized as a typed LanceDB column.
  - `key` string, required — Metadata key name (also the LanceDB column source name).
  - `type` 'string' | 'integer', required — Column type. Only string / integer (scalar-indexable) are allowed.
  - `filter_only` boolean — When true, the value is kept only as a LanceDB column for filtering and is not included in chunk bodies or API responses.
  - `index_type` 'btree' | 'bitmap' — Scalar index type actually applied to the column. Defaults to BTREE for integer and BITMAP for string when not specified at creation; override for cardinality (e.g. high-cardinality string -> btree).
  - `created_at` string, nullable

## Other responses

- `400` — Bad Request - the policy failed validation
- `401` — Unauthorized - Authentication failed
- `403` — Forbidden - requires an API key with All permission
- `409` — A column with the same key already exists

---

[API](https://skmtc.net/qlonolink/apis/qaip-apis.md) · [All operations](https://skmtc.net/qlonolink/apis/qaip-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/qlonolink/qaip-apis/revisions/f5f5994dfe05/schema)