Code Search

Code Search retrieves CIEL concepts and external terminology codes. Use it when you know the wording but not the code, when a QA suggestion is missing, or when you need to compare candidates across sources.

Search modes

Mode	Best for	Main risk
Exact code	A known source/code pair	Selecting the wrong source or version
Textual	Known words, prefixes, and terminology labels	Missing a differently worded synonym
Semantic	Meaning-oriented discovery using embeddings	A plausible but clinically incorrect neighbor

CIEL searches can use the current HEAD mirror or a fixed version. External terminologies are indexed on demand and may need a background indexing job before semantic results are complete.

Text matching and result order

Textual search matches the beginning of words, including words later in a name; it is not arbitrary substring search. For example, diabe can find diabetes, but abetes does not find the middle of that word. Use a deliberate non-interactive contains filter only when the task genuinely requires matching inside a stored value.

For human-readable names, straight and typographic apostrophes are folded for matching. A search for either Crohn's or Crohns can therefore find the same name after the CIEL index has been rebuilt.

When no explicit column sort is selected, CIEL text results order the matched set by typed-term evidence. A preferred English name that begins with the query ranks ahead of a synonym-only or less contiguous match. This improves the first page without expanding the result set; semantic ranking remains a separate mode.

Review a result

1. Select the terminology and version.
2. Start with an exact-code or textual query when possible.
3. Use semantic mode to broaden discovery.
4. Inspect status, preferred label, synonyms, and available hierarchy context.
5. Open the code in the authoritative terminology when the change is material.
6. Copy the source, code, display, and intended map type into the review.

Do not ask an LLM to invent a replacement code. CIEL Lab's MCP search can retrieve indexed candidates, but the same verification rule applies.

Semantic ranking limitation

Embeddings compress meaning into a similarity vector. A broad phrase can score above a more specific post-coordinated expression. The behavior discussed in OpenConceptLab/ocl_issues#2389 is a useful example: specificity and laterality may not dominate the nearest neighbor score.

Use terminology filters, exact attributes, and human reranking when the distinction is clinically meaningful.

Comparison demonstration