Get metadata fields

List the file metadata fields that filters can read, with their type and state.

GET/namespaces/{namespace}/collections/{collection}/metadata-fields

PermissionCluster key, or a scoped key with read (write includes read). Key scopes and actions.

A metadata key that is not listed is stored and returned with the file, but no filter can read it.
status is indexing while the index is rebuilt for a change of that field. Filters read the old index until then.
invalid_values is at least the number of stored values that do not fit the field type, read from a sample of the files already indexed. No filter matches those values.

Request

https://engine.example.com/namespaces/acme/collections/incident-logs/metadata-fields

GET /namespaces/acme/collections/incident-logs/metadata-fields HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

200

The requested resource or result.

{
  "fields": {
    "environment": {
      "type": "text",
      "status": "ready",
      "invalid_values": 0
    },
    "severity": {
      "type": "number",
      "status": "indexing",
      "invalid_values": 0
    }
  }
}

Path parameters

namespacestringrequired

Namespace name or ns_ ID. It must be visible to this key.

collectionstringrequired

Collection name or col_ ID within the namespace. It must be visible to this key.

Responses

200Success

The requested resource or result.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

fieldsmap<string, object>required

Map of metadata key to the field. Only these keys can be used in a filter.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?

View as Markdown