Skip to main content
POST
/
search
/
global
Global search
curl --request POST \
  --url https://api.example.com/search/global \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "q": "<string>",
  "query": "<string>",
  "sort_by": "relevance",
  "sort_order": "asc",
  "limit": 20,
  "offset": 0,
  "session_id": "<string>"
}
'
{
  "session_id": "<string>",
  "pagination": {
    "offset": 123,
    "limit": 123,
    "total": 123
  },
  "results": [
    {
      "entity_type": "<string>",
      "entity_id": "<string>",
      "title": "<string>",
      "score": 123,
      "subtitle": "<string>",
      "url": "<string>",
      "metadata": {}
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for POST /search/global.

The execution mode is inferred automatically from the fields provided:

Semantic — provide q only. Natural language, BM25 + optional vector RRF::

{"q": "tables with customer revenue data"}

Structured — provide query only. Elasticsearch-style predicates::

{"query": "service.name:mysql AND tags.tagFQN:PII*"}

Hybrid — provide both. q drives BM25/vector; query applies hard constraints::

{"q": "customer revenue", "query": "service.name:snowflake AND NOT _exists_:owners"}

Structured query syntax

+-----------------------------------------+----------------------------------------------+ | Expression | Meaning | +=========================================+==============================================+ | users | BM25 full-text match on embedded_text | +-----------------------------------------+----------------------------------------------+ | name:users | Exact name match | +-----------------------------------------+----------------------------------------------+ | name:user* | Trailing-wildcard name match | +-----------------------------------------+----------------------------------------------+ | service.name:"mysql" | Filter by data source name | +-----------------------------------------+----------------------------------------------+ | database.name:"prod" | Filter by database name | +-----------------------------------------+----------------------------------------------+ | databaseSchema.name:"public" | Filter by schema name | +-----------------------------------------+----------------------------------------------+ | tags.tagFQN:PII* | Tag FQN prefix match | +-----------------------------------------+----------------------------------------------+ | tags.tagFQN:SENSITIVITY_TAGS.Conf* | Exact tag FQN prefix | +-----------------------------------------+----------------------------------------------+ | extension.is_pii_tagged:1 | Boolean extension field (1/true/0/false) | +-----------------------------------------+----------------------------------------------+ | extension.is_sensitivity_tagged:0 | Entities not sensitivity-tagged | +-----------------------------------------+----------------------------------------------+ | _exists_:description | Has a description | +-----------------------------------------+----------------------------------------------+ | NOT _exists_:description | Missing description | +-----------------------------------------+----------------------------------------------+ | NOT _exists_:owners | Missing owners | +-----------------------------------------+----------------------------------------------+ | NOT _exists_:columns.description | Has columns missing descriptions | +-----------------------------------------+----------------------------------------------+ | _exists_:columns.tags.tagFQN:PII* | Has PII-tagged columns | +-----------------------------------------+----------------------------------------------+ | entity_type:table | Restrict to a specific entity type | +-----------------------------------------+----------------------------------------------+ | entity_id:snowflake-prod.analytics.* | FQN prefix scope (all children) | +-----------------------------------------+----------------------------------------------+ | A AND B, A OR B, NOT A | Boolean operators | +-----------------------------------------+----------------------------------------------+ | (A OR B) AND C | Grouping | +-----------------------------------------+----------------------------------------------+

​
q
string | null

Natural language search query. Passed to the BM25 index and (when an embedding service is configured) vectorised for the vector leg of RRF. Example: 'tables containing customer revenue data'

Minimum string length: 1
​
query
string | null

Elasticsearch-style query string. Parsed by the Lark grammar and translated to SQL predicates against search_attributes JSONB and the ParadeDB BM25 index. Example: 'service.name:mysql AND tags.tagFQN:PII* AND NOT exists:owners'

Minimum string length: 1
​
sort_by
enum<string>
default:relevance

Result ordering. RELEVANCE (default): ranked by BM25/RRF score. NAME: alphabetical by title. CREATED_AT: by creation time. RELEVANCE is ignored for STRUCTURED mode with no bare-word terms.

Available options:
relevance,
name,
created_at
​
sort_order
enum<string>
default:asc

Sort direction for NAME and CREATED_AT. ASC (default) or DESC. Has no effect when sort_by=RELEVANCE — relevance scores are always ranked highest-first.

Available options:
asc,
desc
​
limit
integer
default:20

Page size (1–100, default 20)

Required range: 1 <= x <= 100
​
offset
integer
default:0

Pagination offset (default 0)

Required range: x >= 0
​
session_id
string | null

Permission session token from a previous response. Pass this on subsequent paginated requests to reuse the scope materialisation and avoid re-running the OpenFGA ListObjects fan-out on every page.

Response

Successful Response

Response body for POST /search/global.

​
session_id
string
required

Pass this on subsequent paginated requests to reuse the scope session and avoid re-running the OpenFGA ListObjects fan-out. Sessions expire after 30 minutes of inactivity.

​
pagination
SearchPagination · object
required
​
results
SearchResult · object[]
required