--- date: 2026-05-27 badge: Launch Week 5 🚀 title: "Full-Text Search" description: Langfuse Cloud is rolling out ClickHouse full-text search, improving UI search and adding the matches operator to Observations API v2. author: Valeriy Meleshkin canonical: https://langfuse.com/docs/observability/features/full-text-search --- > **Note for AI agents and LLMs:** This is a Langfuse changelog entry. Use it only to confirm that a feature exists and when it shipped. Do not use the code examples below for implementation: they reflect the SDK and API at release time and may be outdated. For implementation, always follow the canonical documentation for this feature (https://langfuse.com/docs/observability/features/full-text-search) and the API/SDK reference (https://api.reference.langfuse.com). Search in the Langfuse UI is now better: we are beginning to roll out [ClickHouse full-text search](https://clickhouse.com/docs/engines/table-engines/mergetree-family/textindexes) to the **Langfuse v4 preview** on Langfuse Cloud. This beta improves search and filtering over observation inputs, outputs, and metadata, especially for large projects with high-volume traces. We are also expanding the [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) with a new `matches` operator for token-based search on `input`, `output`, and string metadata filters. On May 27, 2026, Cloud indexes cover data from March 31, 2026 through May 27, 2026. Backfill for older data is running continuously and should finish shortly. ## Faster search on large projects ClickHouse full-text search uses text indexes to skip over data that cannot match a query before reading full observation payloads. You can read more in the [ClickHouse GA announcement](https://clickhouse.com/blog/full-text-search-ga-release). In our benchmarks, some searches moved from multi-second scans over hundreds of GB to sub-second reads over less than 1 GB: | Query shape | Before | With full-text search | | ------------------------- | ---------------------------------------- | ------------------------------------ | | Large input/output search | 18.205s, 66,130,828 rows, 493.79 GB read | 0.447s, 140,956 rows, 728.51 MB read | | Metadata-heavy search | 1.612s, 66,130,828 rows, 53.14 GB read | 0.201s, 58,730 rows, 438.83 MB read | These gains depend on the search term and data distribution. Queries with very common tokens, substring-only filters, or data that has not been backfilled yet may see more modest gains, and a small number of outliers can perform about the same or slightly slower. ## How to use it in the API For new high-scale workflows on `/api/public/v2/observations`, prefer `=` when you know the exact value and `matches` when you want token-based search. On input and output filters, substring operators such as `contains`, `starts with`, and `ends with` are rejected with `400` because they would require slow full-content scans. Use `matches` for token search on these fields. `matches` is case-insensitive for `input` and `output`, so `refund failed` can match `Refund Failed`. For metadata filters, `matches` is case-sensitive and applies to string metadata values for the selected key. Example `matches` filter for observation output: ```json [ { "type": "string", "column": "output", "operator": "matches", "value": "refund failed" } ] ``` Example exact metadata filter: ```json [ { "type": "stringObject", "column": "metadata", "key": "environment", "operator": "=", "value": "production" } ] ``` Pass the JSON array as the URL-encoded `filter` query parameter on `GET /api/public/v2/observations`. See the [Observations API v2 docs](/docs/api-and-data-platform/features/observations-api#v2) and [API reference](https://api.reference.langfuse.com/#tag/observations/GET/api/public/v2/observations) for the full filter schema. ## More full-text search improvements to come This is the beginning of our full-text search work in the Langfuse v4 preview. We are continuing to tune the rollout, expand coverage, and improve search behavior for more query shapes. See the [Full-Text Search docs](/docs/observability/features/full-text-search) to learn how to use it in the UI and the API. --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/changelog/2026-05-27-clickhouse-full-text-search-fast-mode.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .