Text Search¶

Text search is part of the query story in Centrali. Use it when users type natural text and expect relevant results instead of exact field matches.

For new work, keep search on the records query surface:

use search= on simple GET list routes
use a text clause in POST /records/query
use centrali.records.search() in the SDK

Choose the Right Tool¶

Need	Start Here	Why
Fast text lookup with a simple list route	`GET /records/slug/{recordSlug}?search=...`	Low-friction for browse pages
Text search plus filters, paging, sorting, or includes	`POST /records/query` with `text`	One canonical query body
SDK convenience for app code	`centrali.records.search()`	Sugar over the same canonical query model
Exact reporting filters	Query Records	Structured filters first, no relevance ranking assumptions

Search on the GET List Surface¶

Use search for simple text lookup:

curl "https://api.centrali.io/data/workspace/acme/api/v1/records/slug/products?search=laptop&searchFields=data.name,data.description&pageSize=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

This is the fastest path for simple browse and lookup pages.

Search in the Canonical Query Body¶

Use a text clause when search is part of a richer query:

curl -X POST "https://api.centrali.io/data/workspace/acme/api/v1/records/query" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "products",
    "text": {
      "query": "wireless headphones",
      "fields": ["data.name", "data.description"]
    },
    "where": {
      "data.inStock": { "eq": true }
    },
    "sort": [
      { "field": "createdAt", "direction": "desc" }
    ],
    "page": {
      "limit": 10
    }
  }'

That lets you combine:

relevance-oriented text search
business filters
projection
includes
a single consistent { data, meta } result shape

SDK Usage¶

const results = await centrali.records.search('products', 'wireless headphones', {
  where: {
    'data.inStock': { eq: true },
    'data.price': { lt: 300 }
  },
  page: { limit: 10 }
});

If you want full control over the query body, use centrali.records.query() directly:

const results = await centrali.records.query('products', {
  text: {
    query: 'wireless headphones',
    fields: ['data.name', 'data.description']
  },
  where: {
    'data.inStock': { eq: true }
  },
  page: { limit: 10 }
});

Compute Functions¶

async function run() {
  const results = await api.queryRecords('products', {
    text: {
      query: 'clearance'
    },
    where: {
      'data.inStock': { eq: true }
    },
    page: {
      limit: 25
    }
  });

  return {
    success: true,
    products: results.data
  };
}

Practical Guidance¶

Use text search for discovery, not exact reporting.
Combine text with where when relevance must still respect business rules.
Keep searchFields or text.fields focused on the fields users actually search.
If exact matching matters more than relevance, move back to structured filters.