> ## Documentation Index > Fetch the complete documentation index at: https://withcoral.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search with Coral > Find the right SQL surface from catalog metadata or values Coral observed during earlier queries. `coral search` helps you find where to query before you write SQL. Describe a table, table function, column, filter, or value in natural language, and Coral ranks matching locations in your current workspace. Catalog search prepares the current workspace query runtime and catalog, then searches a local index. Runtime preparation can read stored credentials, initialize source providers, and inspect file metadata in local or object storage, but it does not execute your data query or return source rows. Optional observed-value search can also match samples collected while executing earlier queries; it only reads Coral's local search state. ## Search the catalog Use natural language to describe the data you need: ```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}} coral search github issues urgent ``` Among the ranked results, you might see: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Results 1. [table] github.issues Issues opened against a repository 2. [function] github.search_issues Full-text search across issues required: q returns: number, title, state ``` Every result is something you can query. Matching columns, arguments, and values are not separate results — they appear under the table or function that owns them, so one entry tells you what to select, what you must constrain, and which literal values to filter by. `required` lists what you must supply before the entry will return rows: filters for a table, arguments for a function. `matched` lines give you values Coral has previously observed on that field, ready to use in a `WHERE` clause or as an argument. Use a table reference in a `FROM` clause. Call a function with its required named arguments, such as `FROM github.search_issues(q => '')`. Run the query with `coral sql`. See [Query your data](/docs/getting-started/quickstart#3-query-your-data) for a complete example. Here, `github` is the query-visible SQL schema. JSON and MCP results include it in `sql_reference`. A catalog-backed table uses a three-part `catalog.schema.table` reference. The schema is also the installed source name: one source publishes one SQL namespace. When more fields matched than were shown, the result reports how many were left out so you can widen the query rather than assume the column does not exist. By default, Coral returns up to 10 results. Use `--limit` to request between 1 and 50. See the complete [`coral search` reference](/docs/reference/cli-reference#coral-search). ## Find values Coral has seen Sometimes you remember a project name, issue ID, deployment status, or another value, but not where it lives. Observed-value search can match that value against data Coral observed in the past and surface the table or table function where it appeared, with the value attached to the column that holds it. A value only counts as a match when your query names it outright. That keeps a common value like `open` from pulling in every entry that happens to have a status column. Coral builds this memory from values produced by HTTP- and MCP-backed sources while executing SQL queries. It does not crawl your sources in the background or query them when you search. The observed-values index and its stored values stay in the workspace's local search database. Coral does not upload them to a remote search service. Search matches are still returned to the CLI or MCP client that requested them. Observed values are a sample of what Coral has encountered, not a complete index of a connected source. A missing result means Coral found no match in its local observations—not that the value is absent from the source. ### Enable observed-value search Observed-value collection, search, and maintenance are experimental and disabled by default. Enable the `observed_values_search` [runtime feature](/docs/reference/configuration#runtime-features). ## Use search over MCP Coral exposes the same search through its read-only `search` MCP tool. Catalog results are always available. When observed-value search is enabled for the MCP server process, the agent also receives typed observed-value matches and can use the matching table and column to write SQL. Ask for the result you want; you do not need to name the `search` tool: > "Use Coral to show the open GitHub issues assigned to me." > "Use Coral to find where `urgent` appeared, then query the matching data." [Set up Coral over MCP](/docs/guides/use-coral-over-mcp). ## Manage observed-value storage Observed values stay in the workspace's local search database. Coral skips columns with common credential-like names and values that match common secret formats. Source authors can also set `do_not_index: true` on a column to exclude that field before Coral inspects or persists its values. This suppression is best effort, so treat the search database like other local query data. Collection is automatic when the feature is enabled and a supported source scan runs. Disabling `observed_values_search` stops collection, retrieval, and maintenance, but does not delete observations already stored locally. `do_not_index` remains the field-level source policy for excluding particular columns. Coral excludes values last seen more than 365 days ago. It applies a 256 MiB workspace search-storage ceiling, including 32 MiB reserved for write-ahead log growth, and may evict older observations sooner or stop accepting new observations under storage pressure. To remove observed values for a workspace: ```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}} coral search-index clear --scope observed-values --workspace default --yes ``` To remove them for one installed source, pass its name: ```shellscript theme={"theme":{"light":"github-light","dark":"github-dark"}} coral search-index clear --scope observed-values --source github --workspace default --yes ``` Rebuilding or draining the observed-values index only updates Coral's local search state; neither operation fetches new source values. See [`coral search-index`](/docs/reference/cli-reference#coral-search-index) for drain, rebuild, source-scoped clear, and workspace-scoped clear commands.