Concepts

Search

Kognita offers three search modes for every knowledge base. Choose the one that best fits your query pattern, or use hybrid as the safe default.

Mode	How it works	Best for
Full-text	PostgreSQL FTS: tokenizes the query and matches against inverted index.	Exact keyword lookups, product codes, IDs, structured text.
Semantic	Embeds the query and finds nearest neighbors by cosine similarity.	Natural language questions, paraphrases, intent matching.
Hybrid	Weighted combination of full-text and semantic scores.	Most use cases; balances recall and precision.

Full-text search

Uses PostgreSQL's built-in full-text search (tsvector / tsquery). Fast and effective when users type exact words or phrases that appear in the content. No embeddings are generated at query time, so latency is very low.

bash

curl -X POST https://api.kognita.ai/api/v1/knowledge-bases/{kbId}/search/full-text \
  -H "x-kognita-api-key: YOUR_API_KEY" \
  -H "x-kognita-organization-id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "knowledge base API", "limit": 10}'

Semantic search

Converts the query into a vector using the same embedding model configured on the knowledge base, then finds the most similar stored vectors. Understands synonyms and paraphrases, useful for natural language questions where the exact words may not appear in the stored text.

Latency note: Semantic search calls the embedding model for each query. This adds ~100–500 ms depending on the model and network.

bash

curl -X POST https://api.kognita.ai/api/v1/knowledge-bases/{kbId}/search/semantic \
  -H "x-kognita-api-key: YOUR_API_KEY" \
  -H "x-kognita-organization-id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do I store data for my AI?", "limit": 10}'

Hybrid search

Combines full-text and semantic scores with a configurable weight. The semanticWeight parameter (0–1) controls the blend:

semanticWeight: 1.0 (pure semantic)
semanticWeight: 0.0 (pure full-text)
semanticWeight: 0.5 (balanced, default)
semanticWeight: 0.7 (recommended for RAG)

bash

curl -X POST https://api.kognita.ai/api/v1/knowledge-bases/{kbId}/search/hybrid \
  -H "x-kognita-api-key: YOUR_API_KEY" \
  -H "x-kognita-organization-id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "knowledge base API for AI applications",
    "limit": 10,
    "semanticWeight": 0.7
  }'

Search results

All three modes return the same SearchResult shape:

`id`	`string`	The chunk ID that matched.
`contentChunk`	`string`	The text of the matching chunk.
`score`	`number`	Relevance score. Higher is more relevant. Range varies by mode.

→ API reference: Search → API reference: Knowledge bases